dsh-deeppilot 0.9.4 → 0.9.5

package/COMPATIBILITY.md

@@ -1,24 +1,30 @@
 # Compatibility
 
-This branch targets the **DSH `0.2.x` line, from `0.2.0-rc.2` onward**. The DSH
-peer dependencies accept `>=0.2.0-rc.2 <0.3.0-0`: any later `0.2.x` host,
-including future release candidates and the eventual `0.2.0` GA, installs
-without a plugin update. The development packages this branch builds and
-typechecks against are pinned to the exact audited release, currently
-`0.2.0-rc.2`. Every `0.1.x` build and any `0.3.0` or later release are outside
-this branch's support scope; a `0.3.x` line requires its own audit and its own
-range before the plugin will install there.
+This branch targets exactly **two DSH releases**: `0.2.0-rc.2`, which the npm
+`latest`/`next` channels point at, and `0.2.1-alpha.3`, which the `alpha` channel
+points at. Both are named in `peerDependencies`; no other version is accepted.
+DSH evaluates that range before composing a profile — on every start, not only on
+install — so a newly published DSH release deactivates this plugin until the
+range is widened deliberately. That is the intended trade: a plugin that cannot
+run on an unaudited host fails visibly instead of misbehaving quietly. The
+decision and the reversal it represents are recorded in
+[`docs/决策记录.md`](./docs/决策记录.md) (章节一), with the supporting audit in
+[`docs/DSH_RELEASE_MEMORY.md`](./docs/DSH_RELEASE_MEMORY.md).
+
+The development packages this branch builds and typechecks against stay pinned
+to the exact release-candidate baseline, currently `0.2.0-rc.2`; the alpha host
+is covered by the isolated compose and live-runs recorded in the release memory.
 
 | Component | Current contract | Evidence |
 |---|---|---|
 | Node.js | 22 or newer | Package engine and CI |
-| DSH CLI and Host API | `>=0.2.0-rc.2 <0.3.0-0` (dev pins `0.2.0-rc.2`; source audits through `0.2.1-alpha.2`) | Peer metadata, source typecheck, unit tests, bundle build, and config schema projection against a real 0.2.0-rc.2 CLI, plus an isolated compose with the published 0.2.1-alpha.2 CLI |
+| DSH CLI and Host API | `0.2.0-rc.2 \|\| 0.2.1-alpha.3` (dev pins `0.2.0-rc.2`) | Peer metadata, source typecheck, unit tests, bundle build, and config schema projection against a real 0.2.0-rc.2 CLI, plus isolated composes and live phone-protocol runs with the published 0.2.1-alpha.2 and 0.2.1-alpha.3 CLIs |
 | iOS bridge | DeepPilot protocol v2 | Bridge protocol tests; device behavior must be checked with the running Host and app |
 | Remote access | Tailscale Funnel on ports 443, 8443, or 10000 | Helper and supervisor tests |
 
 ## DSH interfaces used here
 
-- The Host adapter uses Session and Workspace controllers, Gateway Remote Events, and `typertGateway.wireStream.open(endpoint, payload, uplink, peer, signal)`. Its in-process carrier passes `undefined` for `uplink` and `peer` and the cancellation signal in argument five.
+- The Host adapter uses Session and Workspace controllers, Gateway Remote Events, and `typertGateway.wireStream.open(endpoint, payload, uplink, peer, signal)`. Its in-process carrier passes `undefined` for `uplink`, a live owner/answer Peer for `peer`, and the cancellation signal in argument five. That Peer comes from `connection.createPeer({ principal: { kind: 'owner' }, interactions: 'answer' })` where the Host exposes it, and from the `connection.operator` instance otherwise. The same Peer is named on `fetchHandler.fetch(request, peer)` and the Connection install goes through `installConnection(ctx, { transport, interactions: 'answer' })` when the Client face offers it. alpha.3 requires all three; alpha.2 ignores the extra `fetch` argument, defaults an absent `open` peer to its operator, and ignores the participation.
 - The resident Client sends relative RPC paths such as `api/$events/result`. The in-process transport resolves those paths to a local URL before constructing a Node `Request`; the shared Fetch handler dispatches it without a network request. This is required for iOS approval and question answers to settle at the Gateway.
 - The client settings page binds `configForms.get('deeppilot')` when the service becomes available. The Host reads volatile config references from its profile entry and reconciles transports on `loader/volatile-update`.
 - Typert strict codecs publish `create()` factories. Session opening reads `session.projections` for a complete baseline; that controller requires a cancellation signal from `0.2.1-alpha.2` on, so the adapter always passes one.
@@ -64,6 +70,36 @@ carries the old top-level `debug: true` is accepted but that value is ignored:
 verbose logging must be turned on again from the settings page. No other config
 field changed shape, and the old key is not read anywhere in this version.
 
+## 0.2.1-alpha.3 audit outcome
+
+The source-level audit of `dsh-v0.2.1-alpha.3` against `dsh-v0.2.1-alpha.2`
+(852 commits, 3311 changed files) found the first release on this line that
+breaks the plugin at runtime. One root cause — alpha.3 makes every in-process
+carrier name a `PeerScope` with a `principal`, a `signal`, and an `interactions`
+participation — landed in four places: `wireStream.open`'s `peer` argument became
+required, the `$events` endpoint began requiring `interactions: 'answer'`,
+`ConnectionFetchHandler.fetch` gained a required Peer, and the `node` export
+condition started resolving the Client faces to bundles that export them as ESM
+instead of registering the browser module banner the resident Client's loader
+reads. The failure mode was silent: the resident interaction client did not
+start, so the phone lost approval and question delivery while every other
+capability kept working.
+
+All four are fixed in one call form both hosts accept (see "DSH interfaces used
+here"). The peer range was narrowed to name `0.2.0-rc.2` and `0.2.1-alpha.3`
+explicitly, and protocol v2, pairing state, and device records are untouched, so
+no paired phone needs to re-pair. The live runs behind this verdict are recorded
+in [`docs/DSH_RELEASE_MEMORY.md`](./docs/DSH_RELEASE_MEMORY.md): alpha.3 with the
+unfixed build logs `DSH Remote interaction client unavailable`, alpha.3 with this
+build does not, and alpha.2 still scores the checklist result it did before the
+change.
+
+Two host-side migrations in this release belong to the operator rather than to
+the plugin: a residual `models` key on an `llm-deepseek-account` entry now fails
+that plugin's load, **including an empty array**, and `--from-default-profile`
+now replaces an existing profile directory — its `node_modules` and the user's
+own `cordis.patch.yml` included — instead of leaving it in place.
+
 ## 0.2.1-alpha.2 audit outcome
 
 The source-level audit of `dsh-v0.2.1-alpha.2` against `dsh-v0.2.1-alpha.1`
@@ -106,6 +142,11 @@ install the plugin. A source diff is still expected for each new DSH release
 and recorded in `docs/DSH_RELEASE_MEMORY.md`, but a clean result now only
 needs a documentation update, not a peer-range widening.
 
+> **Superseded 2026-10-14.** That open-ended range was narrowed back to the two
+> versions actually audited, `0.2.0-rc.2` and `0.2.1-alpha.3`; see the
+> 0.2.1-alpha.3 outcome above and `docs/决策记录.md` (章节一). The paragraphs in
+> this historical entry describe the policy as it stood on 2026-09-29.
+
 ## 0.2.0-rc.1 audit outcome
 
 The source-level audit of `dsh-v0.2.0-rc.1` against the previous baseline
@@ -135,4 +176,4 @@ The complete audit evidence and re-audit procedure remain in [`docs/DSH_RELEASE_
 
 ## Evidence limits
 
-Unit tests and config schema projection do not prove every network, Mac, Linux, Windows, or iPhone combination. In particular, physical-device performance, signed helper distribution, and production APNs delivery need their own checks. Include the exact DSH version, plugin commit, Node version, OS, connection mode, and sanitized status output when reporting a compatibility issue; never include credentials or message content.
+Unit tests and config schema projection do not prove every network, macOS, Linux, Windows, or iPhone combination. In particular, physical-device performance, signed helper distribution, and production APNs delivery need their own checks. Include the exact DSH version, plugin commit, Node version, OS, connection mode, and sanitized status output when reporting a compatibility issue; never include credentials or message content.

package/PRIVACY.md

@@ -2,7 +2,7 @@
 
 DeepPilot connects directly to the DSH Host controlled by the user. The plugin does not upload complete conversations to a DeepPilot application server.
 
-## Data stored on the Mac
+## Data stored on your computer
 
 By default, runtime state is stored under `$DSH_HOME/deeppilot/`:
 
@@ -10,7 +10,7 @@ By default, runtime state is stored under `$DSH_HOME/deeppilot/`:
 - `devices-v2.json`: paired public keys, fingerprints, scopes, device metadata, revocation/last-seen timestamps, notification preferences, APNs alert registrations, WidgetKit push registrations (a separate token per device used only for content-free widget refresh invalidations), and at most one Live Activity registration per device (activity identifier, session identifier, APNs Live Activity update token, environment, and expiry);
 - `tailscale/`: local state for the optional embedded tsnet node.
 
-The directory is owner-only mode `0700`. The Mac never receives or stores iPhone private signing keys. Pairing codes exist only in plugin memory for up to five minutes and are not written to disk.
+The directory is owner-only mode `0700`. The computer never receives or stores iPhone private signing keys. Pairing codes exist only in plugin memory for up to five minutes and are not written to disk.
 
 The settings report exposes public-key fingerprints, scopes, revocation state, and masked notification diagnostics. It does not expose full APNs tokens, pairing codes, or message bodies.
 

package/README.md

@@ -32,15 +32,18 @@ Host on your own computer and does not replace or modify the DSH Web UI.
 
 ## Install from npm
 
-This source checkout targets Node.js 22+ and the **DSH `0.2.x` line, `0.2.0-rc.2`
-or later** (up to, but excluding, `0.3.0`), with a `web` profile. The package
-includes Funnel helpers for macOS, Linux, and Windows on amd64/arm64;
-trusted-LAN mode does not require the helper.
-
-The current working tree accepts any DSH release in `>=0.2.0-rc.2 <0.3.0-0`
-and is built/typechecked against `0.2.0-rc.2`. A previously published plugin
-package may still carry its own older, exact-pinned compatibility declaration
-until a release is made from this tree.
+This source checkout targets Node.js 22+ and the two DSH releases it has been
+audited against — `0.2.0-rc.2` (the `latest`/`next` channels) and `0.2.1-alpha.3`
+(the `alpha` channel) — with a `web` profile. DSH checks a plugin's declared peer
+range before composing a profile, on every start rather than only on install, so
+any other host version refuses to activate this plugin. The package includes
+Funnel helpers for macOS, Linux, and Windows on amd64/arm64; trusted-LAN mode
+does not require the helper.
+
+The current working tree names exactly those two versions in
+`peerDependencies` and is built/typechecked against `0.2.0-rc.2`. A previously
+published plugin package may still carry its own older compatibility
+declaration until a release is made from this tree.
 
 ```sh
 dsh plugin --profile web add dsh-deeppilot
@@ -83,30 +86,20 @@ DeepPilot state under `$DSH_HOME/deeppilot/`.
 
 ## Publishing (maintainers)
 
-Release from this branch only after validating against DSH `0.2.0-rc.2`:
-
-1. Bump `version` in `package.json` and in the root `""` entry of
-   `package-lock.json`, then run `npm test && npm run typecheck && npm run build`
-   and inspect `npm pack --dry-run --json`. The compatibility metadata test
-   enforces the audited DSH peer range and the exact development dependency
-   version.
-2. Commit the release and push it. `npm publish` runs `prepack` (build) and
-   `prepublishOnly` (test + typecheck) automatically.
-3. Publish pre-releases without touching `latest`:
-
-   ```sh
-   npm publish --tag alpha
-   ```
-
-   After a successful publish, verify the dist tag and install the package in
-   a DSH `0.2.0-rc.2` profile before pointing users at it.
-4. Tag the release commit `vX.Y.Z` and prepare a GitHub Release
-   (English + 简体中文 notes) that links this README section.
-5. Publish stable releases with `npm publish --tag latest`, which moves
-   `latest` to the new version. Stable releases must never be published
-   with `--tag alpha`.
-
-Never run `npm publish` from a copy that still has an older version.
+采用可信发布（Trusted Publishing）：GitHub Actions（GitHub 工作流）通过 OIDC
+身份认证发布，并生成来源证明（Provenance），无需长期 npm 发布令牌。
+
+1. 同步包版本与锁文件版本，按 `AGENTS.md` 完成发布验证；提交、推送并等待
+   持续集成（CI）通过。
+2. 从已合入 `main` 的发布提交创建附注标签 `v<版本>`，准备英文与简体中文的
+   GitHub Release（发布页）草稿。
+3. 经用户授权后，在该版本标签上手动运行 `publish.yml`。稳定版使用
+   `latest`（稳定分发标签），预发布版使用 `alpha`（预发布分发标签）。
+4. 核对 npm 版本、分发标签、包完整性与来源证明，并在全新 DSH 配置中安装验证，
+   然后公开 GitHub 发布草稿。
+
+工作流不会因推送标签自动发布。npm 网站绑定、手动命令及首次发布的验证边界见
+[npm 可信发布说明](./docs/NPM_PUBLISHING.md)。
 
 
 ## Connection and privacy

package/README.zh-CN.md

@@ -30,13 +30,15 @@
 
 ## 从 npm 安装
 
-当前源码面向 Node.js 22+ 与带 `web` profile 的 **DSH `0.2.x` 系列（`0.2.0-rc.2`
-及以上，低于 `0.3.0`）**。npm 包内置 macOS、Linux、Windows
+当前源码面向 Node.js 22+ 与带 `web` profile 的**两个已审计 DSH 版本**：
+`0.2.0-rc.2`（`latest`/`next` 通道）与 `0.2.1-alpha.3`（`alpha` 通道）。
+DSH 在组合 profile 前会校验插件声明的 peer 范围，且**每次启动都会校验**（不只是
+安装时），因此其他宿主版本会拒绝激活本插件。npm 包内置 macOS、Linux、Windows
 的 amd64/arm64 Funnel helper；可信局域网模式不依赖 helper。
 
-当前工作树接受 `>=0.2.0-rc.2 <0.3.0-0` 范围内的任意 DSH 版本，构建与类型检查针对
-`0.2.0-rc.2`。从此工作树发布新版本前，已发布的旧插件包仍可能带有各自旧的精确
-版本兼容声明。
+当前工作树的 `peerDependencies` 精确列出这两个版本，构建与类型检查针对
+`0.2.0-rc.2`。从此工作树发布新版本前，已发布的旧插件包仍可能带有各自旧的
+兼容声明。
 
 ```sh
 dsh plugin --profile web add dsh-deeppilot
@@ -71,27 +73,20 @@ dsh plugin --profile web remove dsh-deeppilot
 
 ## 发布说明（维护者）
 
-此分支仅在 DSH `0.2.0-rc.2` 下完成验证后发布：
+采用可信发布（Trusted Publishing）：GitHub Actions（GitHub 工作流）通过 OIDC
+身份认证发布，并生成来源证明（Provenance），无需长期 npm 发布令牌。
 
-1. 同步修改 `package.json` 与 `package-lock.json` 根 `""` 条目中的
-   `version`，然后运行 `npm test && npm run typecheck && npm run build`，
-   并检查 `npm pack --dry-run --json`。兼容性元数据测试会校验 peer 依赖是否为
-   审计过的版本范围、开发依赖是否固定为精确的审计基线版本。
-2. 提交发布并推送。`npm publish` 会自动执行 `prepack`（构建）与
-   `prepublishOnly`（测试 + 类型检查）。
-3. 发布预发布版本，不要动 `latest`：
+1. 同步包版本与锁文件版本，按 `AGENTS.md` 完成发布验证；提交、推送并等待
+   持续集成（CI）通过。
+2. 从已合入 `main` 的发布提交创建附注标签 `v<版本>`，准备英文与简体中文的
+   GitHub Release（发布页）草稿。
+3. 经用户授权后，在该版本标签上手动运行 `publish.yml`。稳定版使用
+   `latest`（稳定分发标签），预发布版使用 `alpha`（预发布分发标签）。
+4. 核对 npm 版本、分发标签、包完整性与来源证明，并在全新 DSH 配置中安装验证，
+   然后公开 GitHub 发布草稿。
 
-   ```sh
-   npm publish --tag alpha
-   ```
-
-   发布成功后检查 dist tag，并在 DSH `0.2.0-rc.2` profile 中安装验证发布的包。
-4. 为发布提交打 `vX.Y.Z` tag，并准备包含英文与简体中文说明的
-   GitHub Release，链接本 README 的发布说明。
-5. 稳定版用 `npm publish --tag latest` 发布，使 `latest` 切换到新版本。
-   稳定版绝不使用 `--tag alpha` 发布。
-
-绝不要从仍是旧版本的副本执行 `npm publish`。
+工作流不会因推送标签自动发布。npm 网站绑定、手动命令及首次发布的验证边界见
+[npm 可信发布说明](./docs/NPM_PUBLISHING.md)。
 
 
 ## 连接与隐私

package/SECURITY.md

@@ -12,11 +12,12 @@ Do not open a public issue containing pairing codes, APNs device tokens, provide
 
 - `/phone/pair` accepts only a short-lived, single-use pairing code and a P-256 public key. The code expires after five minutes and is invalidated after one successful registration.
 - `/phone` upgrades anonymously, then sends a fresh 30-second challenge bound to the stable Host audience. The client proves possession of its registered P-256 private key with ECDSA/SHA-256.
-- The iOS app uses a non-exportable Secure Enclave key on physical devices. The Mac stores only public keys and metadata.
+- The iOS app uses a non-exportable Secure Enclave key on physical devices. The computer stores only public keys and metadata.
 - `GET /phone/health` is intentionally unauthenticated and returns only minimal readiness/version facts.
 - Protocol v1, shared Bearer tokens, query credentials, and `c2s.hello.auth` are not accepted. There is no remote downgrade switch.
 - The server enforces explicit protocol scopes, while the normal settings UI grants the default scope set and exposes only the global connection switch plus per-device deletion. Deleting a device disconnects it immediately.
 - The canonical `$DSH_HOME/deeppilot` directory is repaired to mode `0700`. `host-id` and `devices-v2.json` are owner-only.
+- Losing `devices-v2.json`, `host-id` or `lan-tls/` makes every affected phone pair again; see [docs/DEVICE_REGISTRY_RECOVERY.md](./docs/DEVICE_REGISTRY_RECOVERY.md) for what to back up and how to recover.
 - The independent LAN listener (default port `3098`) is TLS-only: the plugin serves a self-signed EC P-256 certificate, and the app pins its SPKI fingerprint delivered inside the pairing QR. There is no trust-on-first-use; a regenerated key forces re-pairing. The private key lives owner-only under `$DSH_HOME/deeppilot/lan-tls/`. Never forward the LAN port to the public Internet; public access should use Funnel HTTPS/WSS.
 - The LAN listener and Funnel helper publish only `/phone`, `/phone/pair`, and `/phone/health`, never the complete DSH Web UI.
 - Logs must never include pairing codes, key material, APNs tokens, or message bodies.

package/cordis.patch.yml

@@ -1,5 +1,5 @@
 # dsh-deeppilot bundle layer.
-# Phone clients cannot interact with a native picker rendered on the Host Mac.
+# Phone clients cannot interact with a native picker rendered on the host computer.
 # Replace dsh-web-app's adaptive picker with the official browse pair while
 # this bundle is composed, so host.listDirectory is available remotely.
 # Removing this bundle restores the lower web-app auto row unchanged.

package/docs/DEVICE_REGISTRY_RECOVERY.md

@@ -0,0 +1,87 @@
+# Recovering from a lost device registry
+
+[简体中文](./DEVICE_REGISTRY_RECOVERY.zh-CN.md)
+
+The computer keeps the list of paired phones in
+`$DSH_HOME/deeppilot/devices-v2.json` (`~/.dsh/deeppilot/devices-v2.json` when
+`DSH_HOME` is unset). It holds each phone's **public** key, scopes, display
+name, notification preferences and push registrations. The matching private key
+never leaves the phone (Secure Enclave on a physical iPhone), so this file is the
+only thing that makes a paired phone recognisable. If it is gone, no phone can
+prove who it is, and the only way back is to pair again.
+
+## What you will see
+
+| Situation | Host | Phone |
+| --- | --- | --- |
+| File deleted, or the data directory is new | Starts with no devices and logs no error: a missing file is indistinguishable from a first run. The start-up line `device registry loaded from ...: 0 device(s), 0 push registration(s)` is the tell. | Every phone is refused with close code `4401` and shows "pairing is no longer valid". |
+| File unreadable (truncated, disk error) | Logs `[deeppilot] device registry unreadable, starting empty: ...` at start-up, then reports `0 device(s)` and behaves as above. | Same. |
+| A single device deleted in the settings page | That one device is refused; others are unaffected. | Same message on that phone only. |
+
+The phone cannot tell these cases apart: `4401` is also what a revoked device
+gets. If every phone fails at once, suspect the registry; if one fails, suspect
+revocation.
+
+## Before you touch anything
+
+1. **Stop DeepSeek Harness first.** The plugin reads the registry once at start-up
+   and rewrites it from memory afterwards, so an edit made while it runs is
+   overwritten.
+2. **Copy the damaged file aside** (`cp devices-v2.json devices-v2.json.bad`) if
+   it exists. The first successful pairing writes a fresh registry over it, and
+   a truncated file may still contain recoverable entries.
+3. **Never delete `host-id`.** It is the stable Host identity (`audience`) that
+   every phone has stored. A new `host-id` invalidates every pairing even if the
+   registry is restored. If `host-id` itself is malformed the plugin refuses to
+   start; restore it from a backup rather than deleting it.
+
+## Recovery
+
+### A. You have a backup of `devices-v2.json`
+
+The file is replaced atomically (written to a temporary file, then renamed), so
+a copy taken at any moment is a consistent snapshot.
+
+1. Stop DeepSeek Harness.
+2. Put the backup at `$DSH_HOME/deeppilot/devices-v2.json` with mode `0600`.
+3. Start DeepSeek Harness. The start-up log reports how many devices and push
+   registrations were loaded.
+4. Bring the app to the foreground on each phone (or use its retry action). A phone that was refused with `4401` stops retrying by itself, so it reconnects when you reopen the app, not the moment the Host comes back. No re-pairing is needed.
+
+Anything changed after the backup was taken (devices paired, renamed or deleted)
+is rolled back with it. A device you deleted after the backup works again, so
+delete it once more.
+
+### B. No usable backup
+
+Every phone has to pair again.
+
+1. Start DeepSeek Harness and open the DeepPilot plugin settings page.
+2. Show the pairing QR code (or the copyable pairing text). A code is valid for five minutes and works once.
+3. On each phone, open the host in the app's settings, choose edit, and scan the
+   new QR code (or paste the pairing text). If that does not take, remove the host
+   in the app and add it again.
+4. Remove stale entries from the settings page if the old registry was partly
+   recovered.
+
+What is reset: custom device names, per-device notification preferences and
+scopes (back to the defaults). Push registrations and Live Activity tokens come
+back by themselves, because the app registers them on every connection.
+
+Conversations, projects and models are untouched; they belong to DeepSeek
+Harness, not to this plugin.
+
+## Related files that also force re-pairing
+
+| File or directory | If lost |
+| --- | --- |
+| `host-id` | New audience: every phone must pair again. |
+| `lan-tls/` | New certificate key: phones paired over the LAN reject the host until re-paired (Funnel pairings are unaffected). |
+| `tailscale/` | Funnel's Tailscale node state. Expect a new node and a fresh Funnel authorisation; LAN pairings are unaffected. |
+
+## Keeping a backup
+
+Copy `devices-v2.json` and `host-id` together to somewhere outside `DSH_HOME`
+whenever you pair or delete a device. Treat the copy like any file that grants
+access to your sessions: it lists the keys allowed to connect, though it cannot
+be used to impersonate a phone.

package/docs/DEVICE_REGISTRY_RECOVERY.zh-CN.md

@@ -0,0 +1,73 @@
+# 设备注册表丢失后的恢复
+
+[English](./DEVICE_REGISTRY_RECOVERY.md)
+
+电脑上用 `$DSH_HOME/deeppilot/devices-v2.json`（未设置 `DSH_HOME` 时为
+`~/.dsh/deeppilot/devices-v2.json`）记录已配对的手机：每台手机的**公钥**、权限范围、
+显示名称、通知偏好和推送注册。私钥永远不离开手机（真机在 Secure Enclave 中），
+所以这个文件是电脑认出已配对手机的唯一依据。文件丢了，手机就无法证明自己的身份，
+唯一的出路是重新配对。
+
+## 你会看到什么
+
+| 情形 | 电脑端 | 手机端 |
+| --- | --- | --- |
+| 文件被删，或数据目录是新的 | 以空设备列表启动，不报错：缺文件与首次运行无法区分。启动日志里的 `device registry loaded from ...: 0 device(s), 0 push registration(s)` 就是线索 | 所有手机被关闭码 `4401` 拒绝，提示"配对已失效" |
+| 文件不可读（被截断、磁盘错误） | 启动时记一条 `[deeppilot] device registry unreadable, starting empty: ...`，随后报告 `0 device(s)`，之后同上 | 同上 |
+| 在设置页只删除了一台设备 | 仅该设备被拒绝，其余不受影响 | 仅该手机出现同样提示 |
+
+手机无法区分这几种情形：被吊销的设备拿到的同样是 `4401`。如果所有手机同时失败，先怀疑
+注册表；只有一台失败，先怀疑它被删除。
+
+## 动手之前
+
+1. **先停止 DeepSeek Harness。**插件只在启动时读一次注册表，之后按内存内容重写文件，
+   运行中手工修改会被覆盖。
+2. **把损坏的文件另存一份**（`cp devices-v2.json devices-v2.json.bad`）。第一次成功配对
+   会用新内容覆盖它，而被截断的文件里也许还有可挽回的条目。
+3. **不要删除 `host-id`。**它是所有手机都保存着的 Host 身份（`audience`）；换了新的
+   `host-id`，即便注册表恢复了，所有配对也都作废。如果 `host-id` 本身格式损坏，插件会
+   拒绝启动，请从备份恢复，而不是删除。
+
+## 恢复步骤
+
+### A. 有 `devices-v2.json` 的备份
+
+该文件是原子替换写入的（先写临时文件再改名），任何时刻拷贝出来的都是一致的快照。
+
+1. 停止 DeepSeek Harness。
+2. 把备份放回 `$DSH_HOME/deeppilot/devices-v2.json`，权限设为 `0600`。
+3. 启动 DeepSeek Harness。启动日志会报告载入了多少台设备和多少条推送注册。
+4. 在每台手机上把 App 切回前台（或使用重试操作）。被 `4401` 拒绝过的手机会停止自动重试，所以要等你重新打开 App 才会重连，而不是电脑恢复的那一刻。无需重新配对。
+
+备份之后的变更（新配对、改名、删除的设备）会一并回退。备份之后被你删除的设备会重新
+可用，请再删除一次。
+
+### B. 没有可用备份
+
+每台手机都需要重新配对。
+
+1. 启动 DeepSeek Harness，打开 DeepPilot 插件设置页。
+2. 显示配对二维码（或可复制的配对文本）。配对码 5 分钟有效，只能用一次。
+3. 在每台手机的 App 设置里编辑该主机，扫描新二维码（或粘贴配对文本）。如果不生效，
+   就在 App 里删除该主机后重新添加。
+4. 如果旧注册表恢复了一部分，在设置页清理多余的条目。
+
+会被重置的内容：自定义设备名称、每台设备的通知偏好和权限范围（回到默认值）。推送注册和
+实时活动令牌会自动恢复，因为 App 每次连接都会重新注册。
+
+会话、项目和模型不受影响，它们属于 DeepSeek Harness，不属于本插件。
+
+## 同样会迫使重新配对的相关文件
+
+| 文件或目录 | 丢失后果 |
+| --- | --- |
+| `host-id` | 新的 audience：所有手机都要重新配对 |
+| `lan-tls/` | 新的证书密钥：经局域网配对的手机在重新配对前会拒绝该主机（Funnel 配对不受影响） |
+| `tailscale/` | Funnel 的 Tailscale 节点状态。预期会出现新节点并需要重新授权 Funnel；局域网配对不受影响 |
+
+## 保留备份
+
+每次配对或删除设备后，把 `devices-v2.json` 和 `host-id` 一起拷贝到 `DSH_HOME` 之外。
+这份拷贝要像对待任何能访问你会话的文件一样保管：它列出了允许连接的公钥，但无法用来
+冒充手机。