@twinsearth/w2m-dsh-plugin 1.1.16 → 1.1.18

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-    "version": "1.1.16"
+    "version": "1.1.18"
   },
   "plugins": [
     {
       "name": "w2m-fleet",
       "source": "./",
       "description": "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-      "version": "1.1.16",
+      "version": "1.1.18",
       "author": {
         "name": "TwinsEarth"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "w2m-fleet",
   "description": "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to this project are documented here.
 
+## [1.1.18] — 2026-10-18
+
+**The developer declares this a STABLE release.** It ships the three-channel updater and the release plumbing that makes
+the beta channel real.
+
+### Three channels, resolved from the two releases that exist
+
+`w2m_update action:"status" channels:true` reports:
+
+| Channel | Source | Rule |
+|---|---|---|
+| `stable` | GitHub's `/releases/latest` | never a prerelease |
+| `beta` | the newest **prerelease**, fetched from `/releases` and filtered | exists only when one is published |
+| `latest` | whichever of the two is newer by SemVer | equal versions resolve to stable |
+
+Every decision comes from the existing `decideUpdate`, so the channel logic cannot drift from the install rule; this
+module only chooses which two releases to ask about. A missing beta is reported as `available: null` rather than
+substituted with stable — "there is no beta right now" is a fact the UI has to be able to show as a disabled button.
+
+**The channel report is opt-in.** A plain `status` remains local and offline; making every status call reach GitHub would
+slow the tool and break it behind a proxy. Asserted by a test that fails if any fetch happens.
+
+### Installing a channel, with the checksum enforced twice
+
+`w2m_update action:"apply" channel:"stable"|"beta"|"latest"`: the release's `SHA256SUMS` is downloaded, the hash for the
+tarball is required (no hash, no install), `downloadVerified` removes its temp file on any mismatch, and `installUpdate`
+receives `expectedSha256` as well and keeps its rollback path. A mismatch is not retried: it means the asset and its
+checksums disagree, which is never a transient condition.
+
+### The beta channel is a GitHub prerelease, and never npm
+
+`.github/workflows/beta.yml`: a bump is a beta by default; a beta becomes a **prerelease** (so neither GitHub nor npm
+resolves it as latest) gated by the `beta-access` environment, which requires a reviewer. There is **no `npm publish`
+line in that file** — a channel cannot leak into the default install if the publication cannot happen at all. npm
+receives a version only when the developer declares it stable, as this release does.
+
+`.github/workflows/packages.yml` mirrors a released stable version to GitHub Packages with the registry overridden **on
+the command line**, because `publishConfig.registry` would silently redirect the operator-channel publish too.
+
+### Verified
+
+Gate GREEN twice, 15/15. 2504 tests / 2490 pass / 0 fail / 14 skip. tools 122, update-channels 4, update-prerelease 2.
+The first GitHub Packages publication succeeded; the package page itself is confirmed by the operator, since the PAT has
+no `read:packages` scope to read it back.
+
+## [1.1.17] — 2026-10-18
+
+**Fleet chat: messages live in a session, are refused by a byte budget rather than silently dropped, are stored
+encrypted and split across the fleet's own machines, and reach the agent as a tool.**
+
+### The store, and the rule it refuses to break
+
+`src/relay/fleet-messages.mjs` keeps messages per **session** -- the operator's scope: deleting the session deletes the
+history, and a machine joining or leaving changes who reads the flow, never what was said.
+
+The budget is the operator's formula, not a round number:
+
+    limit = min(200 MB, max(100 MB, used-in-7-days))
+
+A message over it is **refused** with the current usage attached (`FLEET_QUOTA_EXCEEDED`); nothing is silently dropped
+and nobody else's words are evicted to make room. Text only: non-strings, control characters and messages over 4 KiB are
+refused by name. Every timestamp comes from the relay's clock, because client clocks in this fleet disagree by tens of
+seconds.
+
+### Encrypted sharding with the three rules that keep it from losing data
+
+`src/relay/message-shards.mjs` seals a day's messages with AES-256-GCM under a key derived from the fleet key (domain
+separated, no new long-lived secret) and splits the result across the fleet:
+
+- **rebuildable** -- the metadata says which machine holds which part, so a reader never guesses;
+- **offline tolerated** -- every part gets **two replicas on two different machines**; one machine being down is the
+  normal case;
+- **integrity** -- each shard carries sha256 of its own bytes. A corrupt shard fails as `SHARD_CORRUPT` naming the part
+  and machine; a missing one fails as `MISSING_SHARDS` naming **which** parts; a wrong key fails as `AUTH_FAILED`
+  without returning partial plaintext.
+
+### HTTP and the notification that carries no text
+
+`POST /v1/fleet/messages` and `GET /v1/fleet/messages` sit behind the device gate: the author is the token holder, never
+a body field. Every read returns the fleet's current usage so a client can warn before a write is refused.
+`GET /v1/fleet/messages/stream` is SSE and emits **only** `{session_id, message_id, machine_id, at_ms}` -- the text is
+always fetched through the authenticated read, because a broadcast carrying text would send every message to every
+listener and make the membership check decorative.
+
+### The twelfth tool: `w2m_chat`
+
+`w2m_chat` (`send` / `list`) exposes the above to the agent. It is an ordinary MCP tool available on every transport;
+`w2m_run` remains the only host-only one.
+
+### The cost of adding a tool: seven count pins
+
+Adding a twelfth tool is not one edit. The count is pinned in **eight** places -- `README` (both languages), four test
+suites (`tools`, `p2p-plugin`, `loader-entry`, `tool-cards`), `scripts/verify-installed.mjs`'s expected list, and
+`test/claims.test.mjs`'s assertion. The first attempt fixed the ones that came to mind and left three red; the gate caught
+each. `docs/PLATFORMS.md` gained a section stating that `w2m_chat` is available over MCP.
+
+### Not verified
+
+- no client UI panel beyond the generic tool card;
+- the SSE route has module-level notification tests, not a live end-to-end stream assertion;
+- shards are produced and reassembled but **not yet transported** to machines -- that is the relay's next step, and the
+  tests say so rather than implying distribution works.
+
+### Verified
+
+Gate GREEN twice, 15 of 15. tools 120, claims 48, p2p 32, loader 10, fleet-messages 7, message-shards 9, chat-http 3,
+message-notify 3.
+
 ## [1.1.16] — 2026-10-18
 
 **A machine waiting to be admitted now appears where you already answer questions -- and the README leads with how to

package/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/TwinsEarth/dsh-windows2macos/actions/workflows/ci.yml/badge.svg)](https://github.com/TwinsEarth/dsh-windows2macos/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@twinsearth/w2m-dsh-plugin?label=npm)](https://www.npmjs.com/package/@twinsearth/w2m-dsh-plugin)
-[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4c6ef5)](#install)
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4c6ef5)](#1-dsh-plugin-recommended--zero-configuration)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![platforms](https://img.shields.io/badge/CI-windows%20%7C%20macos%20%7C%20linux-4c6ef5)](#verified-and-not-verified)
 
@@ -14,7 +14,7 @@ English | [中文](#中文说明)
 
 ## Install
 
-Five ways in, easiest first. **Pick one.** Every route ends with the same eleven tools in your agent.
+Five routes in. They all end with **12 tools registered** in your agent. Pick one.
 
 ### 1. DSH plugin (recommended — zero configuration)
 
@@ -22,20 +22,20 @@ Five ways in, easiest first. **Pick one.** Every route ends with the same eleven
 # 1. install the package into your DSH profile
 dsh plugin add @twinsearth/w2m-dsh-plugin
 
-# 2. add it to the profile's bundle list (this is what makes it load)
+# 2. name it in the profile's bundle list — a package that is not bundled never loads
 #    ~/.dsh/profiles/<profile>/dsh.profile.yml
 plugins:
   - '@twinsearth/w2m-dsh-plugin'
 
-# 3. restart DSH — joining happens at mount time, so a hot reload is not enough
+# 3. restart DSH; joining happens at mount time, so a hot reload is not enough
 ```
 
-Since **1.1.16** the agent starts by itself (`autoStartAgent` defaults to `true`): a freshly installed
-machine derives its account identity, joins the account's fleet, and appears in `w2m_devices` with no
-pairing step. To turn that off, put it back explicitly:
+Since **1.1.15** the agent starts by itself (`autoStartAgent` defaults to `true`): a freshly installed machine
+derives its account identity, joins the account's fleet, and shows up in `w2m_devices` with no pairing step.
+To turn that off, patch the **existing** `w2m` row — do not add a second one:
 
 ```yaml
-# cordis.patch.yml — patch the EXISTING w2m row, do not add a second one
+# cordis.patch.yml
 - id: w2m
   config:
     autoStartAgent: false
@@ -48,8 +48,8 @@ npm install -g @twinsearth/w2m-dsh-plugin
 w2m-mcp --help
 ```
 
-Point any MCP client at `w2m-mcp`. The package has **zero runtime dependencies** and ships its own
-relay, agent and tools.
+Point any MCP client at `w2m-mcp`. **Zero runtime dependencies**; the package ships the relay, the agent and the
+tools.
 
 ### 3. Claude Code
 
@@ -60,129 +60,128 @@ relay, agent and tools.
 
 The manifests live in [`.claude-plugin/`](.claude-plugin/) and are version-locked to the release.
 
-### 4. Codex / MCP-capable CLIs
+### 4. Codex and other MCP-capable CLIs
 
 ```toml
-# codex/mcp-servers.toml — copy this block into your own config
+# copy this block into your own codex/mcp-servers.toml
 [mcp_servers.w2m]
 command = "npx"
-args = ["-y", "@twinsearth/w2m-dsh-plugin@1.1.16", "w2m-mcp"]
+args = ["-y", "@twinsearth/w2m-dsh-plugin@1.1.18", "w2m-mcp"]
 ```
 
-### 5. From the release tarball (verified, offline)
+### 5. Verified release tarball (offline)
 
-From the 1.1.16 release page, download **both** files:
-
-- 	winsearth-w2m-dsh-plugin-1.1.16.tgz
-- SHA256SUMS
-
-Or fetch the tarball directly and take the checksum file from the same release:
+From the `v1.1.18` release page download **both** files — `twinsearth-w2m-dsh-plugin-1.1.18.tgz` and `SHA256SUMS` —
+then:
 
 ```bash
-curl -LO https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v1.1.16/twinsearth-w2m-dsh-plugin-1.1.16.tgz
+curl -LO https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v1.1.18/twinsearth-w2m-dsh-plugin-1.1.18.tgz
 sha256sum -c SHA256SUMS          # verify before installing, always
-npm install -g ./twinsearth-w2m-dsh-plugin-1.1.16.tgz
+npm install -g ./twinsearth-w2m-dsh-plugin-1.1.18.tgz
 ```
 
-Every release carries **`SHA256SUMS`** for exactly this reason. If it is missing, do not install that
-release — that has happened before and it was a defect.
+Every release carries `SHA256SUMS` for exactly this reason. If a release is missing it, do not install that release.
 
 ---
 
 ## Quick start
 
 ```text
-# 1. on the machine that will coordinate
-w2m_status                       # is this machine paired? which fleet?
-
-# 2. see the fleet
-w2m_devices
-
-# 3. run the same command everywhere
+w2m_status                       # am I paired? which fleet?
+w2m_devices                      # what is in the fleet?
 w2m_run mode="replicate" command_argv=["git","rev-parse","HEAD"]
-
-# 4. wait for every machine, then read the verdict
 w2m_wait task_id="..."
 ```
 
-`replicate` runs on every online machine and the verdict is `consistent` only when every machine
-returned the same result **and** the same commit anchor. `split` gives each machine a slice;
-`pipeline` chains stages; `broadcast` names one executor and reports observers; `compose` merges.
+`replicate` runs on every online machine; the verdict is `consistent` only when every machine returned the same
+result **and** the same commit anchor. `split` gives each machine a slice, `pipeline` chains stages, `broadcast`
+names one executor and reports observers, `compose` merges results.
 
 ---
 
-## What it actually is
+## What it is
 
-An installable plugin that turns a set of machines into **one fleet**, keyed by **your account**, not
-by a hand-maintained host list.
+An installable plugin that turns a set of machines into **one fleet**, keyed by **your account**, not by a
+hand-maintained host list.
 
-| Piece | What it does |
+| Piece | Responsibility |
 |---|---|
-| **Relay** | one small HTTP server: task routing, leases, SSE, blob storage. Run it anywhere your machines can reach. |
-| **Agent** | runs on each machine, pairs once, executes allowed commands, heartbeats. |
-| **Plugin** | **11 tools registered** — the `w2m_*` tools your agent calls. |
+| **Relay** | a small HTTP server: task routing, leases, SSE, blob storage. Run it anywhere your machines can reach. |
+| **Agent** | runs on each machine: pairs once, executes allow-listed commands, heartbeats. |
+| **Plugin** | the tools your agent calls. |
 | **Admission** (1.1.14+) | a new machine asks to join; an online member approves, **10 s auto-approves**, and a machine admitted in the last 24 h can be removed immediately. |
 
-### The 11 tools registered
+### Tools
 
-`w2m_status` · `w2m_devices` · `w2m_run` · `w2m_wait` · `w2m_history` · `w2m_stats` · `w2m_report`
-· `w2m_memory` · `w2m_approvals` · `w2m_council` · `w2m_update`
+`w2m_status` · `w2m_devices` · `w2m_run` · `w2m_wait` · `w2m_history` · `w2m_stats` · `w2m_report` ·
+`w2m_memory` · `w2m_approvals` · `w2m_council` · `w2m_chat` · `w2m_update`
 
-### Environment variables a dispatched command receives
+### Environment a dispatched command receives (1.1.15+)
 
-Since 1.1.16 the command knows where it is — values come from the offer, never from argv:
+Values come from the offer, never from argv, so one machine cannot reshape a fleet-wide split.
 
 | Variable | Meaning |
 |---|---|
-| `W2M_INDEX` / `W2M_INDEX_TOTAL` | this machine's slice and how many slices exist |
-| `W2M_STAGE_INDEX` | the pipeline stage (separate from `W2M_INDEX` on purpose) |
+| `W2M_INDEX` / `W2M_INDEX_TOTAL` | this machine's slice number and how many slices exist |
+| `W2M_STAGE_INDEX` | the pipeline stage; deliberately separate from `W2M_INDEX` |
 | `W2M_TASK_ID` / `W2M_MODE` | the task and its mode |
 | `W2M_MACHINE_ID` / `W2M_MACHINE_NAME` | this machine |
 
-So `command_argv=["node","-e","process.exit(Number(process.env.W2M_INDEX)+1)"]` over four machines
-exits 1/2/3/4. (Verified on one machine; the four-machine run is listed as not verified below.)
+So `command_argv=["node","-e","process.exit(Number(process.env.W2M_INDEX)+1)"]` over four machines exits 1/2/3/4.
+Single-machine behaviour is tested; the four-machine run is listed as **not verified** below.
 
 ---
 
-## Fleet model in one paragraph
+## Fleet model
+
+Identity is **the account**, not a list of hosts. A machine derives an Ed25519 identity from its account
+material; the relay registers the matching public key when the account's first machine pairs; every later machine
+proves the same account with a one-time signed challenge.
 
-Identity is **the account**, not a machine list. A machine derives an Ed25519 identity from its
-account material, the relay registers the matching public key when the account's first machine pairs,
-and every later machine proves the same account with a one-time signed challenge. If the old pairing
-path fails for a **named** reason only (invalid code, unreachable relay, timeout), the machine falls
-back to asking for admission; any other failure needs a human and does **not** change mechanisms.
+If the old pairing path fails for a **named** reason only — invalid pairing code, unreachable relay, timeout — the
+machine falls back to asking for admission. Any other failure needs a human and does **not** change mechanisms. A
+rejection is final; the machine does not re-ask.
 
-The relay is authoritative for every time window and every quorum. A machine that has been offline
-for more than 72 hours leaves the **list** — it is never deleted, records stay, and it returns by
-reporting again.
+The relay is authoritative for every time window and every quorum, because client clocks disagree (measured:
+tens of seconds between machines in one fleet):
+
+- **10 s** without a decision auto-approves, but only while at least one member is **online** — an empty fleet
+  cannot consent, and that refusal is named (`NO_ONLINE_MEMBER`);
+- within **24 h** of admission, any online member may remove the machine immediately;
+- after 24 h a single machine may only **open a vote**, whose quorum set is **frozen at open time** so a voter
+  going offline mid-vote cannot move the bar;
+- the quorum is 3+ old members need **≥ 50 %** (rounded up); a two-member fleet needs **one** vote;
+- a machine offline for more than **72 hours** leaves the **list** — it is never deleted, its records stay, and it
+  returns by reporting again.
 
 ---
 
 ## Security posture
 
-- The command allow-list is **argv-prefix** based and rejects argv-reparsing flags (`--import`, `-e`
-  appended) with `COMMAND_REPARSE_ARGUMENT`. It is a boundary, not a sandbox.
-- Dispatching tasks requires an operator token. Device tokens cannot dispatch.
-- Admission approval requires at least one member **online**; an empty fleet cannot consent.
-- Every release is checksummed. `SHA256SUMS` is part of the release, not an afterthought.
+- The command allow-list is **argv-prefix** based and rejects argv-reparsing flags (`--import`, appended `-e`) with
+  `COMMAND_REPARSE_ARGUMENT`. It is a boundary, not a sandbox.
+- Dispatching tasks requires an operator token. A device token cannot dispatch.
+- Admission approval requires at least one member online.
+- The account signing key is derived from the fleet key, **never** from the account code — the account code is
+  written to logs, and deriving a key from a readable value would hand out the account identity.
+- Every release is checksummed.
 
 ---
 
 ## Verified and not verified
 
-Honest status, because a green badge that hides this is worse than no badge.
+A green badge that hides this is worse than no badge.
 
-**Verified:** 2453 tests in 102 files (2439 pass, 14 skip), 15 pre-flight checks, CI green on Windows,
-macOS and Linux, npm + GitHub release + checksums consistent, end-to-end fleet runs on a real
-Linux/Mac/Windows triple.
+**Verified:** 2458 tests in 102 files (2444 pass, 14 skip), 15 pre-flight checks, CI green on Windows, macOS and
+Linux, npm + GitHub release + checksums consistent, end-to-end fleet runs on a real Linux/Mac/Windows triple.
 
 **Not verified / known gaps:**
 
 | Gap | State |
 |---|---|
-| Approval **UI** in the client | the relay enforces the rules; the tool lists and settles pending requests, but the 10 s countdown is displayed by the relay's data, not a dedicated popup |
+| Approval **popup** control | the relay enforces the rules and `w2m_approvals` lists and settles requests, but the 10 s countdown is relay data shown in a list, not a dedicated popup |
 | Four-machine `W2M_INDEX` run | single-machine behaviour tested; the fleet-wide 1/2/3/4 run has not been executed |
-| Fleet chat / broadcast channel | designed, **not implemented** |
+| Fleet chat / broadcast channel | message store + quota implemented and tested; encryption, sharding, endpoints and the panel are **not built** |
 | P2P on some macOS hosts | `P2P_PUNCH_FAILED: Unknown cipher` observed; the task falls back to the relay path |
 
 ---
@@ -192,18 +191,39 @@ Linux/Mac/Windows triple.
 | Symptom | Cause | Fix |
 |---|---|---|
 | installed, but `w2m_devices` answers 401 | the agent never started, so no device token | check `autoStartAgent` is not `false`; restart DSH (not a hot reload) |
-| machine not in the fleet | the plugin is not in `dsh.profile.bundles` | add it — a package that is not bundled never loads |
-| `COMMAND_NOT_ALLOWED` | the command is not in the allow-list | extend the allow-list; argv is matched by prefix |
-| verdict always `partial` | a stale lease from a machine that is down | fixed in 1.1.2 (dispatch now leases only online, non-silent machines) |
-| `P2P_PUNCH_FAILED` | NAT or a host crypto gap | it downgrades to the relay path; the result is unaffected |
+| machine missing from the fleet | the plugin is not in `dsh.profile.bundles` | add it — a package that is not bundled never loads |
+| `COMMAND_NOT_ALLOWED` | command not in the allow-list | extend the allow-list; argv is matched by prefix |
+| verdict always `partial` | a stale lease from a machine that is down | fixed in 1.1.2: a dispatch leases only online, non-silent machines |
+| `P2P_PUNCH_FAILED` | NAT, or a host crypto gap | it downgrades to the relay path; results are unaffected |
+
+---
+
+## Release channels
+
+Three channels, and only one of them is what \
+pm install\ gives you.
 
+| Channel | Where it comes from | Who should use it |
+|---|---|---|
+| **stable** | npm \latest\ — a version the developer declared stable | everyone; this is the default install |
+| **beta** | a GitHub **prerelease** (tarball + \SHA256SUMS\), **never on npm** | developers granted \eta-access\ who accept that it can fail |
+| **latest build** | the newest of the two, whatever its channel | a developer who wants the newest code and knows the above |
+
+A bump is a **beta by default**. npm receives a version only when the developer says, in so many words, that this one is a
+stable release: a beta is published as a prerelease (so neither GitHub nor npm ever resolves it as \latest\), it is
+downloadable only after the \eta-access\ environment approves the run, and installing it requires reading
+[SECURITY.md](SECURITY.md) and accepting the risk.
+
+There is no \
+pm publish\ line in the beta workflow. That is deliberate — a channel cannot leak to the default install if
+the publication cannot happen at all.
 ---
 
 ## Links
 
-- [CHANGELOG](CHANGELOG.md) — every version, including what each one deliberately did **not** ship
-- [PLATFORMS](docs/PLATFORMS.md) — Claude Code, Codex, MCP wiring details
-- [Test matrix](https://github.com/TwinsEarth/dsh-windows2macos/releases) — per-release evidence
+- [CHANGELOG](CHANGELOG.md) — every version, including what it deliberately did **not** ship
+- [PLATFORMS](docs/PLATFORMS.md) — Claude Code, Codex and MCP wiring details
+- [Releases](https://github.com/TwinsEarth/dsh-windows2macos/releases) — per-release evidence and checksums
 - [Issues](https://github.com/TwinsEarth/dsh-windows2macos/issues)
 
 MIT.
@@ -214,39 +234,187 @@ MIT.
 
 **一个 DeepSeek 账号。一句话。你自己的每一台机器跑同一个项目。**
 
-### 安装（由易到难，任选一种）
+以下内容与上方英文**逐节对应**，不是摘要。
+
+### 安装
+
+五种方式，最终都会在你的 agent 里注册 **12 tools registered**。任选其一。
+
+#### 1. DSH 插件（推荐，零配置）
+
+```bash
+# 1. 把包装进你的 DSH profile
+dsh plugin add @twinsearth/w2m-dsh-plugin
+
+# 2. 在 profile 的 bundle 列表里写上包名 —— 没进 bundle 的包永远不会被加载
+#    ~/.dsh/profiles/<profile>/dsh.profile.yml
+plugins:
+  - '@twinsearth/w2m-dsh-plugin'
 
-1. **DSH 插件（推荐，零配置）**：`dsh plugin add @twinsearth/w2m-dsh-plugin`，把包名加入
-   `dsh.profile.bundles`，**重启 DSH**。1.1.16 起 agent 默认自动启动，装完即自动入队。
-2. **npm（任意 MCP 客户端）**：`npm i -g @twinsearth/w2m-dsh-plugin` → `w2m-mcp`。
-3. **Claude Code**：`/plugin marketplace add TwinsEarth/dsh-windows2macos` → `/plugin install w2m@twinsearth`。
-4. **Codex**：复制 [`codex/mcp-servers.toml`](codex/mcp-servers.toml) 的配置块。
-5. **发布包（离线、可校验）**：下载 release 中的 `.tgz` 与 `SHA256SUMS`，**先校验再安装**。
+# 3. 重启 DSH。加入编队发生在 mount 时，热重载不够
+```
+
+从 **1.1.15** 起 agent 会自动启动（`autoStartAgent` 默认 `true`）：新装的机器自行派生账号身份、加入该账号的
+编队，无需配对步骤就会出现在 `w2m_devices` 里。若要关闭，请 patch **已存在的** `w2m` 行，**不要新增第二行**：
+
+```yaml
+# cordis.patch.yml
+- id: w2m
+  config:
+    autoStartAgent: false
+```
+
+#### 2. npm（MCP 服务器，任意客户端）
+
+```bash
+npm install -g @twinsearth/w2m-dsh-plugin
+w2m-mcp --help
+```
+
+把任意 MCP 客户端指向 `w2m-mcp`。**零运行时依赖**；包里同时带有 relay、agent 与工具。
+
+#### 3. Claude Code
+
+```bash
+/plugin marketplace add TwinsEarth/dsh-windows2macos
+/plugin install w2m@twinsearth
+```
+
+清单文件位于 [`.claude-plugin/`](.claude-plugin/)，版本与发行版锁定。
+
+#### 4. Codex 及其它支持 MCP 的 CLI
+
+```toml
+# 把这段复制进你自己的 codex/mcp-servers.toml
+[mcp_servers.w2m]
+command = "npx"
+args = ["-y", "@twinsearth/w2m-dsh-plugin@1.1.18", "w2m-mcp"]
+```
+
+#### 5. 校验过的发布包（离线）
+
+从 `v1.1.18` 的 release 页面下载**两个**文件 —— `twinsearth-w2m-dsh-plugin-1.1.18.tgz` 与 `SHA256SUMS` —— 然后：
+
+```bash
+curl -LO https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v1.1.18/twinsearth-w2m-dsh-plugin-1.1.18.tgz
+sha256sum -c SHA256SUMS          # 安装前务必校验
+npm install -g ./twinsearth-w2m-dsh-plugin-1.1.18.tgz
+```
+
+每个 release 都带 `SHA256SUMS` 正是为了这一步。若某个 release 缺少它，**不要安装该版本**。
 
 ### 快速开始
 
 ```text
-w2m_status          # 我配对了吗？在哪个编队？
-w2m_devices         # 编队里有哪些机器
+w2m_status                       # 我配对了吗？在哪个编队？
+w2m_devices                      # 编队里有什么？
 w2m_run mode="replicate" command_argv=["git","rev-parse","HEAD"]
 w2m_wait task_id="..."
 ```
 
-### 核心概念
+`replicate` 在每一台在线机器上执行；只有当所有机器返回**相同结果**且**相同 commit 锚点**时，裁决才是
+`consistent`。`split` 给每台机器一个分片，`pipeline` 串联多个阶段，`broadcast` 指定一个执行者并汇报观察者，
+`compose` 合并结果。
+
+### 它是什么
+
+一个可安装插件，把一组机器变成**一个编队**，以**你的账号**为键，而不是靠手工维护的主机清单。
+
+| 组件 | 职责 |
+|---|---|
+| **Relay** | 一个小型 HTTP 服务：任务路由、租约、SSE、blob 存储。放在任何机器可达的位置。 |
+| **Agent** | 每台机器上运行：配对一次、执行白名单命令、心跳。 |
+| **Plugin** | 你的 agent 调用的那些工具。 |
+| **Admission**（1.1.14+） | 新机器申请加入；在线成员批准，**10 秒自动同意**；入队 24 小时内的机器可被立即移除。 |
+
+### 工具
+
+`w2m_status` · `w2m_devices` · `w2m_run` · `w2m_wait` · `w2m_history` · `w2m_stats` · `w2m_report` ·
+`w2m_memory` · `w2m_approvals` · `w2m_council` · `w2m_chat` · `w2m_update`
+
+### 被派发命令会收到的环境变量（1.1.15+）
+
+取值来自 offer，**不来自 argv**，因此单台机器无法改变整个编队的分片：`W2M_INDEX` / `W2M_INDEX_TOTAL` /
+`W2M_STAGE_INDEX` / `W2M_TASK_ID` / `W2M_MODE` / `W2M_MACHINE_ID` / `W2M_MACHINE_NAME`。
 
-- **身份是账号，不是主机清单**：机器从账号材料派生 Ed25519 身份，账号第一台机器配对时登记公钥，
-  后续机器用一次性签名挑战自证。
-- **只按三类明确失败降级**：配对码无效 / relay 不可达 / 超时；其它错误需要人工，**不切换机制**。
-- **时间窗与法定人数由 relay 权威判定**：10 秒自动同意（需至少 1 名成员在线）、24 小时内可即时踢出、
-  超过 24 小时需冻结快照表决（3 人以上 ≥50%，2 人编队 1 票）。
-- **离线 72 小时只是不显示，绝不删除**：记录保留，机器重新上线后自动回到列表。
-- **派发命令会拿到 `W2M_INDEX` 等环境变量**（1.1.16 起），因此 split 可以按机器分支。
+因此 `command_argv=["node","-e","process.exit(Number(process.env.W2M_INDEX)+1)"]` 在四台机器上应分别退出
+1/2/3/4。**单机行为已测；四台机器的联跑尚未验证**（见下方"未验证"）。
 
-### 验证状态（不含糊）
+### 编队模型
 
-已测试 2453 项（2439 通过 / 14 跳过）、15 项门禁、三平台 CI 全绿、npm 与 GitHub 发布及校验和一致。
+身份是**账号**，不是主机清单。机器从账号材料派生 Ed25519 身份；账号的第一台机器配对时，relay 登记对应公钥；
+此后每台机器用一次性签名挑战自证同一个账号。
 
-**未验证项**：客户端审批弹窗（规则由 relay 强制，工具可列出并裁决）、四台机器 `W2M_INDEX` 全员取值、
-编队聊天通道（仅设计）、部分 macOS 主机的 P2P 降级。
+只有当旧配对路径因**明确原因**失败时 —— 配对码无效、relay 不可达、超时 —— 机器才降级去申请入队。其它失败需要
+人工介入，**不会**切换机制。**拒绝即终态**，机器不会再次申请。
+
+所有时间窗与法定人数由 relay 权威判定，因为客户端时钟互不一致（实测：同一编队内相差数十秒）：
+
+- 无决策 **10 秒**后自动同意，但**仅当至少一名成员在线** —— 空编队无法同意，该拒绝有明确错误码
+  （`NO_ONLINE_MEMBER`）；
+- 入队后 **24 小时内**，任一在线成员可立即移除该机器；
+- 超过 24 小时，单台机器只能**发起表决**，且法定人数集合在**发起时冻结**，投票者中途离线无法改变门槛；
+- 法定人数：旧成员 ≥3 人需 **≥50%（向上取整）**；2 人编队的移除只要 **1 票**；
+- 离线超过 **72 小时**的机器会离开**列表** —— 记录**永不删除**，它重新上报后会自动回来。
+
+### 安全姿态
+
+- 命令白名单按 **argv 前缀**匹配，并拒绝 argv 重解析标志（`--import`、追加 `-e`），错误码
+  `COMMAND_REPARSE_ARGUMENT`。这是边界，不是沙箱。
+- 派发任务需要 operator token；device token 不能派发。
+- 审批入队要求至少一名成员在线。
+- 账户签名密钥从 **fleet key** 派生，**绝不**用 account code —— account code 会写进日志，用可读值派生密钥等于
+  交出账号身份。
+- 每个发行版都有校验和。
+
+### 已验证与未验证
+
+**一句真话胜过一块掩盖问题的绿牌。**
+
+**已验证：** 102 个文件中的 2458 项测试（2444 通过、14 跳过）、15 项门禁检查、Windows / macOS / Linux 三平台
+CI 全绿、npm 与 GitHub 发布及校验和一致、在真实的 Linux/Mac/Windows 三机编队上跑过端到端。
+
+**未验证 / 已知缺口：**
+
+| 缺口 | 状态 |
+|---|---|
+| 审批**弹窗**控件 | relay 强制规则、`w2m_approvals` 可列出并裁决，但 10 秒倒计时是列表里的 relay 数据，不是独立弹窗 |
+| 四台机器的 `W2M_INDEX` 联跑 | 单机行为已测；编队级 1/2/3/4 尚未执行 |
+| 编队聊天 / 广播通道 | 消息存储与配额已实现并测试；加密、分片、端点与面板**尚未构建** |
+| 部分 macOS 主机的 P2P | 观察到 `P2P_PUNCH_FAILED: Unknown cipher`；任务会降级走 relay 路径 |
+
+### 故障排查
+
+| 症状 | 原因 | 处理 |
+|---|---|---|
+| 装好了，但 `w2m_devices` 返回 401 | agent 从未启动，因此没有 device token | 确认 `autoStartAgent` 不是 `false`；**重启 DSH**（热重载无效） |
+| 编队里看不到这台机器 | 插件没写进 `dsh.profile.bundles` | 加进去 —— 不在 bundle 里的包永远不会加载 |
+| `COMMAND_NOT_ALLOWED` | 命令不在白名单 | 扩充白名单；argv 按前缀匹配 |
+| 裁决总是 `partial` | 来自已下线机器的陈旧租约 | 1.1.2 已修：派发只对在线且未沉默的机器建租约 |
+| `P2P_PUNCH_FAILED` | NAT，或宿主密码学能力缺口 | 会自动降级到 relay 路径，结果不受影响 |
+
+### 发布通道（中文）
+
+三个通道，其中只有一个是你 \
+pm install\ 默认拿到的。
+
+| 通道 | 来源 | 适合谁 |
+|---|---|---|
+| **stable** | npm \latest\，开发者明确声明为稳定版 | 所有人；默认安装就是它 |
+| **beta** | GitHub **prerelease**（tarball + \SHA256SUMS\），**绝不进 npm** | 被授予 \eta-access\、且接受它可能失败的开发者 |
+| **最新构建** | 两者中版本较新的那个，不论通道 | 想要最新代码、并理解上述含义的开发者 |
+
+**默认的 bump 是 beta**。只有开发者明确说明"这次是稳定版"，npm 才会收到该版本：beta 以 prerelease 形式发布（因此
+GitHub 与 npm 都不会把它解析成 \latest\），只有在 \eta-access\ 环境审批通过后才能下载，安装前需阅读
+[SECURITY.md](SECURITY.md) 并自担风险。
+
+beta 工作流里**没有 \
+pm publish\ 这一行**，这是刻意的 —— 只要发布动作不可能发生，这个通道就不可能泄漏到默认安装。
+### 链接
+
+- [CHANGELOG](CHANGELOG.md) —— 每个版本，包括它**故意没有**交付的内容
+- [PLATFORMS](docs/PLATFORMS.md) —— Claude Code、Codex 与 MCP 的接线细节
+- [Releases](https://github.com/TwinsEarth/dsh-windows2macos/releases) —— 每个版本的证据与校验和
+- [Issues](https://github.com/TwinsEarth/dsh-windows2macos/issues)
 
 MIT。