dsh-notch 0.3.1 → 0.3.4

package/README.en.md

@@ -8,70 +8,57 @@ Installation has two parts: a **Host plugin inside DSH** that supplies session s
 
 ## Installation
 
-### Requirements
+**DSH Notch 0.3.4 supports official DeepSeek Harness `0.2.0-rc.2`.** Install `dsh-notch@0.3.4` and `dsh-notch-focus@0.1.2` from npm. The native macOS helper remains version 0.3.3 and is included in the release below. This release changes npm packaging and installation instructions; its runtime code matches 0.3.3.
 
-- macOS 14 or later.
-- DeepSeek Harness `0.1.7-rc.1`. This package peers `@deepseek-ai/dsh` and the `@deepseek-ai/dsh-*` packages it imports at `>=0.1.7-rc.1 <0.1.8`.
-- A working local DSH Web Host, with `dsh`, `pnpm`, and `git` available in your terminal.
-- Swift 6 or later through Command Line Tools. Check with `swift --version`; use `xcode-select --install` if the developer tools are missing.
+### 1. Download the release
 
-These instructions use the default `web` profile and `~/.dsh`. For a custom `DSH_HOME`, run plugin installation with that same environment and edit that Home's profile in step 2.
+Download from [v0.3.4](https://github.com/aa2246740/dsh-notch/releases/tag/v0.3.4):
 
-### 1. Download and install the Host plugin
+| File | Purpose |
+| --- | --- |
+| `dsh-notch-0.3.4.tgz` | Host plugin for status, questions, and native connectivity |
+| `dsh-notch-focus-0.1.2.tgz` | Client companion for navigation and reading acknowledgements |
+| `dsh-notch-0.3.3-macos-arm64.tar.gz` | Native executable and robot resources; macOS 14+, Apple Silicon |
+| `SHA256SUMS` | Place beside the downloads and run `shasum -a 256 -c SHA256SUMS` |
 
-```sh
-git clone https://github.com/aa2246740/dsh-notch.git
-cd dsh-notch
-dsh plugin --profile web add "$PWD"
-```
+Prebuilt packages do not require Swift or DSHX. Other architectures require a source build and are not covered by this binary release.
 
-This links the local package into DSH's Web profile. Keep the checkout: it is also where you build the native application.
+### 2. Install both plugin packages
 
-The warning `declares no dsh.bundle — installed as a plain dependency` is expected for this package. **Continue with step 2 to activate it.** The current package has no automatic bundle registration, so `plugin add` alone does not start Notch.
+**Official Desktop:** enter `dsh-notch@0.3.4` and `dsh-notch-focus@0.1.2` through the app's Plugins page, enable them, follow the app's loading instructions, then reopen the page. The app owns the Desktop profile.
 
-If you run DSH from source without a global `dsh` command, run this from the Harness checkout, then return to the Notch checkout:
+**Web:** use the same `DSH_HOME` as the running Host, then run from your download directory:
 
 ```sh
-pnpm dsh plugin --profile web add /absolute/path/to/dsh-notch
+dsh plugin --profile web add dsh-notch@0.3.4
+dsh plugin --profile web add dsh-notch-focus@0.1.2
 ```
 
-### 2. Activate the plugin in DSH
-
-Append this item to the YAML list in `~/.dsh/profiles/web/cordis.patch.yml`. Create the file if absent. **Keep existing configuration, and add this ID only once.**
-
-```yaml
-- insert:
-    - id: dsh-notch
-      name: dsh-notch
-```
+Both packages declare official `dsh.bundle.patch` entries. Follow the plugin manager's loading guidance and reopen the page. Do not add a second manual insert. Update existing entries when migrating older installations so a Bundle and an old manual patch do not mount the same plugin twice.
 
-`name: dsh-notch` resolves the profile dependency from step 1. Do not copy the repository's `cordis.yml` directly into this location; its relative paths serve a different purpose.
+A loaded Host writes `$DSH_HOME/dsh-notch/runtime.json`. This is a private connection file managed by the plugin; do not fill it in or share it. Check Host loading errors if it is absent.
 
-The standard Web profile watches this file and loads the plugin after saving. If DSH is not running yet, start it using your usual launcher. Successful loading emits `[my-plugins/dsh-notch] loaded` in the Host log and creates `~/.dsh/dsh-notch/runtime.json`.
-
-The plugin manages this private connection file automatically. Do not fill it in manually or paste its contents into a chat. If it is absent, resolve YAML, module-resolution, or missing-service errors in the Host before continuing.
-
-### 3. Build and start the real Notch
-
-From the Notch checkout:
+### 3. Extract and start the native helper
 
 ```sh
-swift build --package-path macos -c release
-macos/.build/release/dsh-notch --verify-idle-resources
-macos/.build/release/dsh-notch
+tar -xzf dsh-notch-0.3.3-macos-arm64.tar.gz
+cd dsh-notch-0.3.3-macos-arm64
+./dsh-notch --verify-idle-resources
+./dsh-notch
 ```
 
-The resource check should print `IDLE_RESOURCES=10/10`. The last command starts the application connected to real DSH sessions. Keep this terminal open during the first run.
+The resource check should print `IDLE_RESOURCES=10/10`. Keep the terminal open for the first run. If a desktop launcher already manages a Notch helper, update that executable instead. Always keep `dsh-notch` and `DshNotch_DshNotch.bundle` together when moving them. A custom `DSH_HOME` must match the Host's Home.
 
-If your DSH.app already manages a Notch helper, update that copy instead of starting a duplicate. When moving the executable or integrating it into a desktop shell, keep `dsh-notch` and `DshNotch_DshNotch.bundle` from the same build together in the destination directory, then relaunch the helper. Installing the Host plugin does not configure login startup or replace a desktop shell's existing executable.
+Optionally set the Host plugin's `helperPath` configuration to the absolute path of the extracted executable and follow the app's plugin loading guidance. The Host then supervises that helper; do not also start another copy manually.
 
-### 4. Confirm it works
+### 4. Confirm synchronization
 
-- With no active work or unread results, the robot appears at the screen edge.
-- Existing running sessions produce a blue count; questions and results produce their corresponding states.
-- Clicking a session opens it in DSH. When a question appears, answer it directly in Notch.
+- Running primary sessions show a blue count; completions, failures, and questions show their corresponding states.
+- Clicking a Notch session opens the matching conversation in DSH.
+- Opening a completed session in foreground DSH clears that result from Notch. Running tasks remain visible.
+- Reading all results returns Notch to the idle robot.
 
-Use existing sessions for these checks; a new model task is unnecessary. Seeing the robot alone does not prove Host connectivity: confirm that real session state updates too.
+The native helper exits with its Host. Temporary request failures do not close it. Closing only the window keeps it alive if the Host still runs. See [desktop helper ownership](desktop/README.md) for lifecycle integration.
 
 ## Usage
 
@@ -84,9 +71,17 @@ Use existing sessions for these checks; a new model task is unnecessary. Seeing
 | Click an option | Submit that choice; follow the panel for multiple questions or selections |
 | Click the question title | Open the full conversation in DSH |
 | Read all results | Return to the idle robot |
+| Drag and release Notch | Hide it elastically at the screen edge; drag it out again to restore |
+| New completion, failure, or decision while hidden | Bounce back to the normal compact view; repeated polls of the same event do not reveal it again |
+
+Ordinary running-state and size updates keep a hidden Notch tucked away. An attention event received during a drag waits until release. Screen work-area changes, including a right-side macOS Dock, do not move the hidden cap away from the physical display edge.
 
 The interface uses native AppKit, SwiftUI, and Canvas. Animation itself never calls a model. The panel grows with content, scrolls at the screen-height cap, and respects Reduced Motion.
 
+Counts represent user conversations. Workflow workers and nested subagents belong to their owning conversation; they do not add separate running, success, or failure indicators. A background worker keeps its owner running, while result indicators come from the owner's final outcome. Child questions appear on the owner's yellow indicator and answers return to the original requester, with multiple questions handled in order. User-created forks remain independent conversations.
+
+External Codex, Claude Code, ACP, and DSH SDK children registered as official background jobs also keep their owner active. Observation never consumes job completion notices. The [dsh-notch-focus companion](companions/dsh-notch-focus/README.md) handles browser navigation and cold-session mirroring; existing installations can keep their current directory. See the [source compatibility audit](docs/subagent-compatibility.md) for entry paths, cancellation, resumption, and verification limits.
+
 ## Troubleshooting
 
 | Symptom | Check |
@@ -98,16 +93,28 @@ The interface uses native AppKit, SwiftUI, and Canvas. Animation itself never ca
 | Two Notches | Check for both a manually started and a desktop-shell-managed copy. |
 | Old behavior after updating source | Rebuild and replace the executable actually running; `git pull` does not replace an existing native process. |
 
-The Host plugin requires `sessions`, `webServer`, `approval`, `userQuestions`, and `agents`. It targets a local DSH Web Host on the same Mac. Native foregrounding looks for a DSH.app with bundle ID `local.dsh.desktop`; other desktop shells need an adapter. Successful package installation alone does not certify multiple Homes, remote Hosts, or every DSH version.
+The Host plugin requires `sessions`, `webServer`, `approval`, `userQuestions`, and `agents`. It targets a local DSH Web Host on the same Mac. Native foregrounding prefers official `com.deepseek.dsh` and retains compatibility with `local.dsh.desktop`. Successful package installation alone does not certify multiple Homes, remote Hosts, or every DSH version.
 
 ## Updates and development
 
 After updating source, rebuild the native helper. Native-only changes require updating and relaunching Notch. Changes under `src/` also require the appropriate Host module activation.
 
-Maintainers using [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) can inspect `dshx activation-plan dsh-notch --change artifact` or `--change server`, according to the changed surface. Initial activation above uses a watched patch; restarting the whole Host does not replace a missing installation step.
+Maintainers using [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) can inspect `dshx activation-plan dsh-notch --change artifact` or `--change server`, according to the changed surface. Package synchronization and live activation are separate checks.
+
+Source builds require Node.js 24 and Swift 6 / Command Line Tools:
+
+```sh
+npm ci --ignore-scripts --legacy-peer-deps
+npm run build
+npm run build:macos
+```
+
+See the [companion README](companions/dsh-notch-focus/README.md) for its DSHX 0.9.2 build against a `dsh-v0.2.0-rc.2` checkout. Release consumers do not need DSHX.
+
+Development checks:
 
 ```sh
-npm ci
+npm ci --ignore-scripts --legacy-peer-deps
 npm test
 npm run test:outcome
 npm run test:motion
@@ -118,6 +125,8 @@ npm run test:idle
 npm run build:macos
 ```
 
+Try the elastic edge-hiding gesture in the [standalone native preview](tools/elastic-preview/README.md), built with `npm run build:elastic-preview`. It uses local fixtures, makes no model requests, and does not replace an installed Notch.
+
 ### Optional recording demo
 
 For animation review and video recording, separate from plugin installation:
@@ -129,8 +138,10 @@ open "dist/DSH Notch Demo.app"
 
 The demo contains 36 bilingual scenes driven by local fixtures. It does not connect to DSH. See the [demo controls](tools/recording/README.md).
 
-More: [motion contracts](macos/STATUS-MOTION.md), [design notes](DESIGN.md), [0.3.0 changes](docs/releases/v0.3.0.md), and [optional desktop-shell diagnostics](tools/desktop-shell/README.md).
+More: [motion contracts](macos/STATUS-MOTION.md), [design notes](DESIGN.md), [0.3.3 changes](docs/releases/v0.3.3.md), [0.3.2 changes](docs/releases/v0.3.2.md), [0.3.0 changes](docs/releases/v0.3.0.md), and [optional desktop-shell diagnostics](tools/desktop-shell/README.md).
 
 ## License
 
 [MIT](LICENSE). Robot resources derive from [OpenBotMotion](https://github.com/aa2246740/open-bot-motion); its original [MIT notice](tools/idle/LICENSE.open-bot-motion) is retained. This is a community-maintained DSH plugin.
+
+See the [Desktop 0.1.7-rc.2 verification record](docs/desktop-017rc2.md). `DSH_NOTCH_RUNTIME_FILE` selects the connection only. Use explicit `--demo` or `--elastic-preview` modes for offline presentation.

package/README.md

@@ -8,77 +8,57 @@
 
 ## 安装
 
-### 准备条件
+**DSH Notch 0.3.4 支持官方 DeepSeek Harness `0.2.0-rc.2`。** 从 npm 安装 `dsh-notch@0.3.4` 和 `dsh-notch-focus@0.1.2`。原生 macOS 程序继续使用 0.3.3，包含在下面的发布页中。本次只调整 npm 打包和安装说明，运行代码与 0.3.3 相同。
 
-- macOS 14 或更新版本。
-- DeepSeek Harness `0.1.7-rc.1`。本包对 `@deepseek-ai/dsh` 与所用 `@deepseek-ai/dsh-*` 的 peer 是 `>=0.1.7-rc.1 <0.1.8`。
-- 本机已有正常运行的 DSH Web Host；终端能使用 `dsh`、`pnpm` 和 `git`。
-- Swift 6 或更新版本的 Command Line Tools。用 `swift --version` 检查；没有开发工具时先运行 `xcode-select --install`。
+### 1. 下载发布包
 
-以下以默认的 `web` profile、`~/.dsh` 为例。若你的 DSH 使用自定义 `DSH_HOME`，插件安装命令必须使用同一环境，第二步也要编辑该 Home 下的 profile 文件。
+从 [v0.3.4 Release](https://github.com/aa2246740/dsh-notch/releases/tag/v0.3.4) 下载：
 
-### 1. 下载并安装 Host 插件
-
-```sh
-git clone https://github.com/aa2246740/dsh-notch.git
-cd dsh-notch
-dsh plugin --profile web add "$PWD"
-```
+| 文件 | 用途 |
+| --- | --- |
+| `dsh-notch-0.3.4.tgz` | Host 插件，提供状态、问题和原生程序连接 |
+| `dsh-notch-focus-0.1.2.tgz` | 客户端同步助手，负责双向会话跳转与已读同步 |
+| `dsh-notch-0.3.3-macos-arm64.tar.gz` | macOS 14+、Apple Silicon 原生程序及机器人资源 |
+| `SHA256SUMS` | 下载校验；与上述文件放在同一目录后执行 `shasum -a 256 -c SHA256SUMS` |
 
-这条命令把本地插件目录链接到 DSH 的 Web profile。请保留这个目录，后面还要在这里构建 Notch。
+预编译包无需 Swift 或 DSHX。其他架构需从源码构建，尚未提供验收过的预编译包。
 
-如果看到 `declares no dsh.bundle — installed as a plain dependency`，这是当前包的预期提示：**包已经装入，继续第二步把插件加入运行配置。** 当前版本没有声明自动挂载的 bundle，单独执行 `plugin add` 还不会显示 Notch。
+### 2. 在 DSH 安装两个插件包
 
-<details>
-<summary>从 Harness 源码运行，没有全局 dsh 命令？</summary>
+**官方 Desktop：** 在应用内插件管理页分别输入 `dsh-notch@0.3.4` 和 `dsh-notch-focus@0.1.2`，确认都已启用，按应用提示完成加载，再重新打开页面。Desktop profile 由应用管理。
 
-在 Harness checkout 里运行它自己的 CLI，使用刚下载插件的绝对路径：
+**Web：** 对运行中的 Host 使用相同的 `DSH_HOME`，在下载目录执行：
 
 ```sh
-pnpm dsh plugin --profile web add /absolute/path/to/dsh-notch
-```
-
-然后回到 `dsh-notch` 目录继续下面的步骤。
-
-</details>
-
-### 2. 在 DSH 中激活插件
-
-打开 `~/.dsh/profiles/web/cordis.patch.yml`，在现有 YAML 列表中追加下面这一项。文件不存在时可新建；**保留已有配置，同一个 `id` 只添加一次**。
-
-```yaml
-- insert:
-    - id: dsh-notch
-      name: dsh-notch
+dsh plugin --profile web add dsh-notch@0.3.4
+dsh plugin --profile web add dsh-notch-focus@0.1.2
 ```
 
-这里的 `name: dsh-notch` 从第一步安装的 profile 依赖中解析。不要直接复制仓库内的 `cordis.yml`：里面的相对路径用途不同。
-
-标准 Web profile 会监听这份配置并热加载插件。若 DSH 正在运行，保存后等它加载即可；尚未启动 DSH 时，用你原来的启动入口启动它。成功后，Host 日志会出现 `[my-plugins/dsh-notch] loaded`，并生成 `~/.dsh/dsh-notch/runtime.json`。
-
-该文件包含 Notch 的本机连接信息，由插件自动管理，不需要手动填写或把内容发给 Agent。如果没有生成，先检查 Host 是否报 YAML、模块解析或缺少服务的错误，再继续第三步。
+两个包都声明了官方 `dsh.bundle.patch`。按插件管理器的提示加载，并重新打开页面；不要再手工追加同名 `insert`。已有安装应更新原条目，避免 Bundle 与旧手动配置重复挂载。
 
-### 3. 构建并启动正式 Notch
+Host 加载后生成 `$DSH_HOME/dsh-notch/runtime.json`。这是插件管理的私有连接文件，不需要填写或分享。找不到它时，先检查 Host 插件的加载错误。
 
-在刚下载的 `dsh-notch` 目录执行：
+### 3. 解压并启动原生程序
 
 ```sh
-swift build --package-path macos -c release
-macos/.build/release/dsh-notch --verify-idle-resources
-macos/.build/release/dsh-notch
+tar -xzf dsh-notch-0.3.3-macos-arm64.tar.gz
+cd dsh-notch-0.3.3-macos-arm64
+./dsh-notch --verify-idle-resources
+./dsh-notch
 ```
 
-资源检查应输出 `IDLE_RESOURCES=10/10`。最后一条命令启动连接真实 DSH 会话的 Notch；首次启动时保持这个终端窗口打开。
+资源检查应输出 `IDLE_RESOURCES=10/10`。首次运行请保持终端打开；如果已有桌面启动器管理 Notch，更新它使用的那份程序即可。移动时始终把 `dsh-notch` 和 `DshNotch_DshNotch.bundle` 放在一起。使用自定义 `DSH_HOME` 时，原生程序和 Host 必须指向同一 Home。
 
-如果你使用的 DSH.app 已经在管理一份 Notch，只更新那份程序，避免同时启动两个。移动程序或接入 App 壳时，要把 `dsh-notch` 和同一构建目录的 `DshNotch_DshNotch.bundle` 一起放到目标目录，再重新启动 Notch 程序。单独安装 Host 插件不会自动配置登录启动，也不会替换某个 App 壳里的旧程序。
+可在 Host 插件配置中把 `helperPath` 设为已解压的 `dsh-notch` 的绝对路径，让插件随 Host 管理辅助进程；配置后按应用的插件加载提示生效。请勿同时手工启动另一份。
 
-### 4. 确认安装成功
+### 4. 确认同步正常
 
-- 没有活跃任务和未读结果时，屏幕边缘出现机器人。
-- 已有会话运行时出现蓝色计数；完成、失败或等待决定时显示对应状态。
-- 点击会话能回到 DSH；出现问题时可以直接在 Notch 里选择回答。
+- 正在运行的主会话显示蓝色计数；完成、失败或等待回答显示对应状态。
+- 点击 Notch 的会话，DSH 打开对应对话。
+- 在 DSH 前台打开已完成的会话，Notch 清除该条未读状态；仍在运行的任务继续保留。
+- 全部结果读完后，Notch 回到机器人待机。
 
-可以用已有会话检查，不必为了测试新开一个模型任务。仅出现机器人还不能证明已经连接 Host；还要确认真实会话状态能同步。
+Notch 跟随连接文件中的 Host 进程退出。临时请求失败不会让它退出；只关闭窗口而 Host 仍在后台运行时，它会继续显示任务。[桌面托管说明](desktop/README.md)介绍了辅助程序的退出与快速重启联动。
 
 ## 使用
 
@@ -91,9 +71,17 @@ macos/.build/release/dsh-notch
 | 点击问题选项 | 直接提交该选项；多选或多题按面板提示完成 |
 | 点击问题标题 | 回到 DSH 查看完整上下文 |
 | 全部结果读完 | 回到机器人待机 |
+| 拖动 Notch 后松手 | 弹性收纳到屏幕边缘；再拖出即可恢复 |
+| 隐藏时出现新完成、错误或待审批问题 | 自动弹回正常紧凑状态；同一提醒不会因轮询反复弹出 |
+
+隐藏状态下，普通运行和尺寸更新不打扰你。鼠标正在拖动时收到新提醒，会先保持跟手，等松手再恢复。右侧系统 Dock 或显示工作区变化不会改变 Notch 对物理屏幕边缘的定位。
 
 Notch 使用原生 AppKit / SwiftUI / Canvas 渲染。动画本身不调用模型。窗口随内容展开，达到屏幕高度上限后滚动；系统开启“减少动态效果”时呈现静态状态。
 
+计数以用户的主对话为单位：workflow 和普通子代理（包括嵌套子代理）归到所属主对话，不会各自增加蓝色数字或生成完成、失败灯。后台子代理仍在工作时，主任务继续显示运行中；结果灯以主对话的最终结果为准。子代理需要你回答的问题会显示在主任务的黄色状态下，回答送回原请求，多个问题依次处理。用户手动 fork 出来的对话仍独立计数。
+
+外部 Codex、Claude Code、ACP、DSH SDK 子代理转入官方后台任务后，也会归到所属主对话。Notch 只读取状态，不消费后台任务的完成通知。浏览器跳转和未加载会话的同步由 [dsh-notch-focus 助手](companions/dsh-notch-focus/README.md)提供；已有安装保留原目录更新即可。入口、取消与恢复路径的检查范围见[源码兼容性审计](docs/subagent-compatibility.md)。
+
 ## 常见安装问题
 
 | 现象 | 检查位置 |
@@ -105,28 +93,43 @@ Notch 使用原生 AppKit / SwiftUI / Canvas 渲染。动画本身不调用模
 | 屏幕上出现两个 Notch | 检查是否同时启动了手动版本和 App 壳管理的版本，只保留预期的那一份。 |
 | 更新源码后仍是旧效果 | 重新构建，并更新实际运行的可执行文件；只 `git pull` 不会替换已启动的原生进程。 |
 
-当前 Host 插件依赖 `sessions`、`webServer`、`approval`、`userQuestions`、`agents` 服务，面向同一台 Mac 上的 DSH Web Host。原生界面的会话跳转会唤起 bundle ID 为 `local.dsh.desktop` 的 DSH.app；其他 App 壳的前台唤起需要适配。多 Home、远程 Host 和各版本 DSH 的兼容性不能只凭安装成功判断。
+若状态灯叠影、点击后才恢复，可按发生时间查看 `~/.dsh/dsh-notch/presentation.jsonl`。日志只记录计数、动画阶段、布局和进程编号，不记录对话正文、标题或认证信息；达到 256 KiB 后轮换，只保留当前和上一份。刷新时会检查过期的转场并补做收尾，菜单交互期间也继续推进状态与布局计时器。
+
+当前 Host 插件依赖 `sessions`、`webServer`、`approval`、`userQuestions`、`agents` 服务，面向同一台 Mac 上的 DSH Web Host。原生界面的会话跳转优先唤起官方 `com.deepseek.dsh` 桌面版，并保留旧 `local.dsh.desktop` 壳的兼容。多 Home、远程 Host 和各版本 DSH 的兼容性不能只凭安装成功判断。
 
 ## 更新与开发
 
-更新已安装的源码后，重新构建原生程序。只改原生界面时，更新并重新启动 Notch 即可；若改了 `src/` 下的 Host 插件代码，还需要对应的服务端热加载。
+更新已安装的源码后，重新构建原生程序。只改原生界面时，更新并重新启动 Notch 即可；若改了 `src/` 下的 Host 插件代码，先 `npm run build` 更新 `lib/index.mjs`，再做对应的服务端热加载。
+
+使用 [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) 的维护者可先执行 `dshx activation-plan dsh-notch --change artifact` 或 `--change server`，按实际修改范围更新。激活要匹配实际 Host 和挂载方式，不能把复制原生二进制当作 Host 模块热更新。
+
+从源码构建 Host 和原生程序需要 Node.js 24、Swift 6 / Command Line Tools：
 
-使用 [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) 的维护者可先执行 `dshx activation-plan dsh-notch --change artifact` 或 `--change server`，按实际修改范围更新。安装文档中的首次配置属于 watched patch，不能用重启整个 Host 代替缺失的安装步骤。
+```sh
+npm ci --ignore-scripts --legacy-peer-deps
+npm run build
+npm run build:macos
+```
+
+同步助手的源码构建需要 DSHX 0.9.2 和已备好依赖的 `dsh-v0.2.0-rc.2` Harness checkout；步骤见[助手说明](companions/dsh-notch-focus/README.md)。预编译发布包不需要这些开发工具。
 
 开发检查：
 
 ```sh
-npm ci
+npm ci --ignore-scripts --legacy-peer-deps
 npm test
 npm run test:outcome
 npm run test:motion
 npm run test:geometry
 npm run test:scrollbar
 npm run test:expanded-height
+npm run test:host-lifetime
 npm run test:idle
 npm run build:macos
 ```
 
+弹性收纳交互可在 [独立原生预览](tools/elastic-preview/README.md) 中试用；运行 `npm run build:elastic-preview` 构建，不连接 DSH、不调用模型，也不替换当前安装。
+
 ### 录屏 Demo（可选）
 
 用于开发、检查动画或录制演示视频，**不属于插件安装步骤**：
@@ -138,8 +141,10 @@ open "dist/DSH Notch Demo.app"
 
 Demo 提供 36 个中英双语场景，使用本地假任务，不连接 DSH。录屏控制与快捷键见 [Demo 文档](tools/recording/README.md)。
 
-更多：[动效说明](macos/STATUS-MOTION.md) · [设计说明](DESIGN.md) · [0.3.0 更新记录](docs/releases/v0.3.0.md) · [可选 App 壳诊断](tools/desktop-shell/README.md)。
+更多：[动效说明](macos/STATUS-MOTION.md) · [设计说明](DESIGN.md) · [0.3.3 更新记录](docs/releases/v0.3.3.md) · [0.3.2 更新记录](docs/releases/v0.3.2.md) · [0.3.0 更新记录](docs/releases/v0.3.0.md) · [可选 App 壳诊断](tools/desktop-shell/README.md)。
 
 ## 许可
 
 [MIT](LICENSE)。机器人资源基于 [OpenBotMotion](https://github.com/aa2246740/open-bot-motion)，保留了原始 [MIT 许可声明](tools/idle/LICENSE.open-bot-motion)。这是社区维护的 DSH 插件。
+
+官方桌面版的原生启动适配与验证见 [0.1.7-rc.2 验证记录](docs/desktop-017rc2.md)。`DSH_NOTCH_RUNTIME_FILE` 只指定连接文件，绝不触发演示偏移；演示使用显式的 `--demo` 或 `--elastic-preview` 入口。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-notch
+      name: dsh-notch

package/desktop/README.md

@@ -0,0 +1,29 @@
+# Desktop helper ownership
+
+`notch-lifecycle.mjs` is a small Node/Electron integration for desktop shells that launch the native helper. It owns both a helper it spawns and an existing helper adopted from a PID file. It verifies the executable and process start time, retries if the adopted helper exits during startup, and closes the owned helper on application quit.
+
+```js
+import { superviseNotch } from './notch-lifecycle.mjs'
+
+let notch
+app.on('before-quit', () => notch?.stop())
+// After the authenticated Host has finished starting:
+notch = superviseNotch({ bin: absoluteHelperPath, pidPath: helperPIDPath, log })
+```
+
+Register quit cleanup before awaiting Host startup. If the app quits while startup is pending, cancel/terminate its own starting Host and do not start Notch afterwards. Do not terminate an unrelated Host to manage Notch.
+
+An external native updater should create `${pidPath}.updating` before stopping the old helper, replace the binary/resources, start and verify the new helper, publish its PID, then remove the marker in a `finally` block. The marker expires after 60 seconds if an updater crashes. This prevents the shell's recovery from racing the updater.
+
+The native helper also watches its Host independently. Actual process exit closes it without a deliberate grace delay; HTTP timeouts do not. A process that has already committed to exiting is replaced by the desktop supervisor rather than treated as a usable helper forever.
+
+Validation:
+
+```sh
+npm test
+swift build --package-path macos -c release
+python3 macos/Tests/helper-lifetime.py
+node desktop/restart-probe.mjs
+```
+
+The native probes use disposable local owner processes and isolated runtime files. They never start DSH or invoke a model.

package/desktop/notch-lifecycle.mjs

@@ -0,0 +1,120 @@
+import { spawn, execFileSync } from 'node:child_process'
+import { readFileSync, mkdirSync, writeFileSync, renameSync, unlinkSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+/** PID alone is not ownership: require both executable and process start time. */
+export function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return { state: 'dead' }
+  try {
+    const text = execFileSync('/bin/ps', ['-p', String(pid), '-o', 'lstart=', '-o', 'comm='],
+      { encoding: 'utf8', env: { ...process.env, LC_ALL: 'C' }, timeout: 1000 }).trim()
+    const match = /^(.{24})\s+(.+)$/.exec(text)
+    if (match) return { state: 'alive', stamp: match[1], command: match[2] }
+  } catch {}
+  try { process.kill(pid, 0) } catch (error) {
+    if (error.code === 'ESRCH') return { state: 'dead' }
+  }
+  return { state: 'unknown' }
+}
+
+export function processLiveness(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return 'dead'
+  try { process.kill(pid, 0); return 'alive' } catch (error) {
+    return error.code === 'ESRCH' ? 'dead' : 'unknown'
+  }
+}
+
+/** The desktop owns an adopted helper too. If it exits during adoption, retry. */
+export function superviseNotch({ bin, pidPath, log, interval = 250, env = process.env,
+  probe = processIdentity, alive = processLiveness, launch = spawn, signal = process.kill.bind(process) }) {
+  let current, pending, timer, stopped = false
+  const starts = []
+  const note = text => log.write(`[notch] ${text}\n`)
+  const storedPID = () => {
+    try { return Number(readFileSync(pidPath, 'utf8').trim()) } catch { return 0 }
+  }
+  const owned = pid => {
+    const identity = probe(pid)
+    return identity.state === 'alive' && resolve(identity.command) === resolve(bin)
+      ? { pid, ...identity, checkedAt: Date.now() } : undefined
+  }
+  const schedule = () => {
+    clearTimeout(timer)
+    if (!stopped) { timer = setTimeout(reconcile, interval); timer.unref?.() }
+  }
+  function reconcile() {
+    if (stopped) return
+    if (pending) { schedule(); return }
+    // External installers hold this short lease while replacing executable + PID.
+    // A crashed installer cannot disable recovery indefinitely.
+    try {
+      if (Date.now() - statSync(`${pidPath}.updating`).mtimeMs < 60000) { schedule(); return }
+    } catch {}
+    if (current) {
+      const state = alive(current.pid)
+      if (state === 'unknown' || (state === 'alive' && Date.now() - current.checkedAt < 5000)) {
+        schedule(); return
+      }
+      const live = probe(current.pid)
+      if (live.state === 'unknown' || (live.state === 'alive' && live.stamp === current.stamp && live.command === current.command)) {
+        current.checkedAt = Date.now()
+        schedule(); return
+      }
+      current = undefined
+    }
+    const pid = storedPID()
+    const identity = probe(pid)
+    if (identity.state === 'unknown') { schedule(); return }
+    current = owned(pid)
+    if (current) { note(`adopt ${current.pid}`); schedule(); return }
+    while (starts.length && Date.now() - starts[0] > 10000) starts.shift()
+    if (starts.length >= 3) { note('helper repeatedly exited; retry paused'); stopped = true; return }
+    starts.push(Date.now())
+    const child = launch(bin, [], { stdio: ['ignore', 'pipe', 'pipe'], detached: false, env })
+    pending = child
+    child.stdout?.pipe(log, { end: false })
+    child.stderr?.pipe(log, { end: false })
+    child.once('spawn', () => {
+      if (pending !== child) return
+      pending = undefined
+      if (stopped) { child.kill('SIGTERM'); return }
+      current = owned(child.pid)
+      // A successful spawn still must be attributable before touching its PID file.
+      if (!current) { child.kill('SIGTERM'); schedule(); return }
+      mkdirSync(dirname(pidPath), { recursive: true })
+      const stage = `${pidPath}.${process.pid}.tmp`
+      writeFileSync(stage, `${child.pid}\n`)
+      renameSync(stage, pidPath)
+      note(`spawn ${child.pid}`)
+      schedule()
+    })
+    child.once('error', error => { if (pending === child) pending = undefined; note(`spawn error: ${error.message}`); schedule() })
+    child.once('exit', () => {
+      if (pending === child) pending = undefined
+      if (current?.pid === child.pid) current = undefined
+      schedule()
+    })
+    schedule()
+  }
+  const stop = () => {
+    stopped = true
+    clearTimeout(timer)
+    pending?.kill('SIGTERM')
+    // A native hot replacement may have updated the file since the last check.
+    const candidates = [current, owned(storedPID())].filter(Boolean)
+    const seen = new Set()
+    for (const item of candidates) {
+      if (seen.has(item.pid)) continue
+      seen.add(item.pid)
+      const live = owned(item.pid)
+      if (!live || live.stamp !== item.stamp) continue
+      try { signal(item.pid, 'SIGTERM'); note(`stop ${item.pid}`) } catch (error) {
+        if (error.code !== 'ESRCH') note(`stop failed: ${error.message}`)
+      }
+      if (storedPID() === item.pid) { try { unlinkSync(pidPath) } catch {} }
+    }
+    current = undefined
+  }
+  reconcile()
+  return { get pid() { return current?.pid ?? pending?.pid }, stop, kill: stop }
+}

package/desktop/restart-probe.mjs

@@ -0,0 +1,61 @@
+// Real native helper + disposable sleep processes; never starts DSH or calls a model.
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import { mkdtempSync, writeFileSync, rmSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Writable } from 'node:stream'
+import { superviseNotch, processIdentity } from './notch-lifecycle.mjs'
+
+const bin = fileURLToPath(new URL('../macos/.build/release/dsh-notch', import.meta.url))
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms))
+const logs = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+const running = child => child.exitCode === null && child.signalCode === null
+async function owner() {
+  const child = spawn('/bin/sleep', ['60']); await once(child, 'spawn'); return child
+}
+async function stop(child) {
+  if (!child || !running(child)) return
+  const exited = once(child, 'exit'); child.kill('SIGTERM'); await exited
+}
+
+for (const gap of [0, 50, 1200]) {
+  const root = mkdtempSync(join(tmpdir(), 'notch-restart-'))
+  const runtime = join(root, 'runtime.json'), pidPath = join(root, 'helper.pid')
+  const children = []
+  let first, second, manager
+  const writeOwner = child => writeFileSync(runtime, JSON.stringify({ pid: child.pid,
+    writtenAt: Date.now(), origin: 'http://127.0.0.1:9', token: 'offline-test' }))
+  const launch = (file, args, options) => {
+    const child = spawn(file, args, { ...options, env: { ...process.env, DSH_NOTCH_RUNTIME_FILE: runtime } })
+    children.push(child); return child
+  }
+  try {
+    first = await owner(); writeOwner(first)
+    const old = launch(bin, [], { stdio: 'ignore', detached: true }); await once(old, 'spawn')
+    writeFileSync(pidPath, String(old.pid))
+    await delay(800)
+    assert.equal(processIdentity(old.pid).command, bin)
+    await stop(first)
+    await delay(gap)
+    second = await owner(); writeOwner(second)
+    manager = superviseNotch({ bin, pidPath, launch, log: logs, interval: 25 })
+    await delay(900)
+    const live = children.filter(running)
+    assert.equal(live.length, 1, `gap ${gap}: exactly one helper expected`)
+    assert.equal(manager.pid, live[0].pid)
+    assert.equal(Number(readFileSync(pidPath, 'utf8')), live[0].pid)
+    const start = performance.now()
+    manager.stop()
+    while (children.some(running) && performance.now() - start < 1000) await delay(10)
+    assert.equal(children.filter(running).length, 0, 'quit must also close an adopted helper')
+    console.log(`PASS restart gap=${gap}ms: one live helper; quit ${(performance.now() - start).toFixed(0)}ms`)
+  } finally {
+    manager?.stop()
+    await Promise.all(children.map(stop))
+    await stop(first); await stop(second)
+    rmSync(root, { recursive: true, force: true })
+  }
+}

package/docs/desktop-017rc2.md

@@ -0,0 +1,23 @@
+# 官方桌面版 0.1.7-rc.2 适配
+
+本分支保留 `ff78f13` 的完整弹性拖拽、左端变细、隐藏贴边和关注事件弹回，合入 `e79bbf1` 的 RC2 兼容分支，并保存当前本地桌面部署已经采用的 Home 路径、原生辅助程序托管、后台子任务及桌面唤起适配。
+
+## 本次故障
+
+正式 Host 给辅助程序传入 `DSH_NOTCH_RUNTIME_FILE`，用于指定连接文件。旧原生入口却用同一个变量判断“演示”，把窗口向内移动 360 pt，并让决策面板忽略自动折叠。现在连接选择与显示行为完全分开：正式入口始终以物理屏幕右边缘为锚点，离线演示只走已有显式入口。
+
+## 验证
+
+- `npm run test:desktop-launch` 使用真正的 `AppDelegate` 和离线连接文件，检查原生窗口边界：旧入口测得 360 pt 间隙，修复后为 0 pt。测试不连接真实 Host，不调用模型。
+- `npm run test:edge-dock` 通过，覆盖二维拖动、连续形变、原形裁切、回弹打断、重要事件恢复和减少动态效果。
+- `npm test`：61/61 通过，包含 RC2 的 `jobs.list(agent.id)`、`job.owner` 和主任务归属。每个测试进程使用临时 `DSH_HOME`，防止继承真实 Home 写入已读状态。
+- Release 原生构建与 Host 预编译构建通过；`dshx check` 检查源入口通过，热替换文件集合同时声明实际加载的 `lib/index.mjs` 与源码及辅助模块。
+- 原生预览实操完成斜向拖动收纳、运行更新保持隐藏、完成后完整弹回。
+
+## 部署边界
+
+本次运行中需要改变的只有用户目录里的原生辅助程序。当前 Host 已经加载 RC2 适配的 Host 插件，服务器部分不需要再激活。更新采用辅助程序自己的短更新租约、哈希与进程身份检查、备份和原子替换；由现有托管器拉起唯一新辅助进程。官方应用包、Host 进程、profile 配置及真实任务均不修改。
+
+当前 DSHX 外部 CLI 的 desktop `activation-plan` 能分类为 artifact，但离线 profile 合成需要 Creator+ 发出的短时能力，返回 `DESKTOP_PROFILE_BRIDGE_REQUIRED`。本次不绕过此限制、不伪造票据、不执行 Host 插件激活；原生辅助程序的独立更新与运行验证单独记录。以后若改 Host 模块，仍需满足对应激活流程。
+
+正式验收区分源代码、构建、安装哈希、唯一进程、Host 快照和 GUI 操作。独立预览不等于向正式会话注入事件，算法测试不等于实屏帧率保证。