@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.7

package/README.md

@@ -1,3 +1,666 @@
-# Temporary Holding Version
+# DSH: Windows2MacOS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One DeepSeek account. One instruction. Every machine you own runs the same project.**
+
+English | [中文](#中文说明)
+
+[![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)
+[![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](#design-notes)
+[![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)
+
+---
+
+## The problem
+
+You have a Windows desktop and a Mac laptop. You are working on one project. You
+want to say *"run the test suite"* once, and have **both** machines run it — then
+see whether they agree.
+
+DeepSeek Harness cannot do this today, and not by accident:
+
+- one `dsh` process serves **one machine** — a profile is a local pnpm workspace;
+- its transport is **loopback only** (the web server accepts `127.0.0.1`/`0.0.0.0`
+  and the CLI refuses `--host 0.0.0.0`, because it ships no TLS or origin policy);
+- the official agent-team feature is explicit that it does **not** support
+  teammates with separate working directories or **several processes
+  coordinating over one team**.
+
+So the cross-machine capability has to be built. This is that build.
+
+## What you get
+
+```
+        you, on any machine, talking to DSH
+                       │
+                       ▼
+   ┌──────────────────────────────────┐        ┌──────────────────────────┐
+   │  Windows · DSH session           │        │  macOS · DSH session     │
+   │   w2m plugin (8 tools)           │        │   w2m plugin (8 tools)   │
+   │        │                         │        │        │                 │
+   │   Localside agent                │        │   Localside agent        │
+   │    · three anchors               │        │    · three anchors       │
+   │    · local spool                 │        │    · local spool         │
+   │    · executes argv               │        │    · executes argv       │
+   └──────────┬───────────────────────┘        └──────────┬───────────────┘
+              │  outbound POST + SSE                      │
+              ▼                                           ▼
+        ┌──────────────────────────────────────────────────────────┐
+        │  Rabbit relay: rendezvous, ledger, STUN responder        │
+        └──────────────────────────────────────────────────────────┘
+```
+
+Every machine only ever makes **outbound** connections. No public IP, no port
+forwarding, no SSH server on Windows (which, measured, is not installed by
+default — `ssh.exe` exists, `sshd` does not). The relay is the rendezvous and the
+ledger; the payload path is a UDP hole punch between the machines themselves — on
+by default in v0.4.0 — and it falls back to the relay loudly, naming the reason,
+when the network will not allow it.
+
+### The direct path (v0.4.0, default)
+
+Both machines announce the address a STUN server sees them as, the dispatching
+machine punches to the other's candidate, and the task offer travels over the
+punched channel instead of the relay. The relay holds its own copy of that offer
+back for about a second while the punch is attempted, and offers it anyway if the
+punch does not land — so a failed punch costs latency, not the task.
+
+The result *notice* returns the same way, with one stated limit: the frame carries
+the task and machine identity, not the result payload. `result_path` is one of the
+envelope's own fields and the envelope's hash covers it, so the acknowledgement has
+to be known before the envelope is built. The direct path therefore saves the
+dispatcher the wait for the relay's copy, not the bytes — the payload still reaches
+everyone through the ledger, which is the only writer allowed to hold it.
+
+```yaml
+- id: w2m
+  config:
+    p2pMode: auto          # auto (default) | direct | relay
+    # stunServers: ['202.182.123.154:3478']   # default: the shared server, then three public ones
+```
+
+`auto` tries the direct path and falls back with the reason attached; `direct`
+refuses the relay copy rather than falling back, so a punch failure becomes a
+visible failure; `relay` is byte-for-byte v0.3.9 — no UDP socket is bound at all.
+Every result carries `transport` plus a `p2p` object saying which path the offer
+took and which path the result took, and `w2m_wait` shows it per machine.
+
+**Why `auto` and not `direct`.** Punching cannot succeed behind a symmetric NAT,
+and that is measured rather than assumed. On the reference Windows client network
+(China Mobile), three STUN servers reported three different mapped ports for one
+socket — `endpoint-dependent`, punchable: false. A default that hard-required the
+direct path would break every deployment on such a network the moment it
+upgraded. See [PROTOCOL-v0.4.0.md](PROTOCOL-v0.4.0.md) §1.
+
+### Two coordination modes
+
+| Mode | What it does | When to use |
+|---|---|---|
+| `replicate` | every machine runs the **same** command; results compared side by side | "does this change pass on both platforms?" |
+| `split` | work divided by `index` (`explicit` or `modulo` sharding) | one large test suite, several machines |
+
+### Six aggregation states
+
+Not four — because "the environments differ" and "the results differ" are
+different findings, and collapsing them turns noise into bug reports.
+
+| State | Meaning |
+|---|---|
+| `consistent` | every machine agreed on every comparable field |
+| `divergent` | machines disagreed — the report names the field and each machine's value |
+| `divergent-platform` | only toolchain/platform differ, and the difference is confined to stdout text — expected |
+| `failed` | every machine failed |
+| `partial` | some succeeded, some failed |
+| `unverifiable` | an **anchor** did not match, so comparison is refused |
+
+## Install
+
+> **This package can run three ways, and all three start the same binaries.**
+>
+> ```bash
+> node bin/w2m-rabbit.mjs ...        # from a clone (what the examples below use)
+> npx @twinsearth/w2m-dsh-plugin ... # if it is on a registry
+> w2m-rabbit ...                     # once installed, via its bin entry
+> ```
+>
+> The examples use the clone form because that is what is verified in this
+> repository. Nothing needs to be installed to use the relay or the agent: they
+> are plain Node scripts with **no runtime dependencies**.
+
+### 1. The relay + STUN (once, on any always-on machine)
+
+> **v0.4.0 defaults to a shared server, so this step is optional.** With no
+> `rabbitUrl` configured, the plugin uses `http://202.182.123.154:8787` — a
+> rendezvous, ledger and STUN responder that is already running. Point it at your
+> own host when you want your own; nothing else changes.
+
+```bash
+node bin/w2m-rabbit.mjs --host 0.0.0.0 --port 8787 --state ~/.dsh/xclient/rabbit
+node bin/w2m-stun.mjs   --host 0.0.0.0 --port 3478        # the punch needs this
+```
+
+`w2m-rabbit` prints a **pairing code**. Pair the first machine, and the relay
+immediately prints a **new** code — so you can pair the second machine without
+restarting anything. (For scripted onboarding, start it with
+`pairingCodeReusable: true` and one code stays valid for its whole TTL.)
+
+`w2m-stun` answers "what address does the world see me as", which is the address a
+peer has to aim at. Machines fall back to three public STUN servers if it is not
+there, so leaving it out degrades the punch rather than breaking it.
+
+Deploying both on a fresh host, with the proxy and firewall rules, is one command:
+`deploy/shared-server/install.sh` — see
+[deploy/shared-server/README.md](deploy/shared-server/README.md), including the
+part about TLS that this shape does not have by default.
+
+### 2. Localside (on every machine that should run the project)
+
+```bash
+node bin/w2m-localside.mjs \
+  --rabbit http://<relay-host>:8787 \
+  --pair PAIR-XXXXXXXX \
+  --project /path/to/your/project \
+  --name win-desktop \
+  --state ~/.dsh/xclient/localside-win \
+  --p2p-mode auto
+  # --p2p-port 41234    # v0.4.1: pin the punch socket, so an inbound firewall
+  #                     # rule names one port and survives a restart
+```
+
+`--allowed-commands` is a **default-deny whitelist** as a JSON array. Nothing
+runs unless it matches a prefix:
+
+```bash
+  --allowed-commands '["node --test","git status --porcelain"]'
+```
+
+> The allow-list matches the whole `argv`, token by token, and a string entry is
+> split on whitespace — so `node -e console.log` does **not** allow
+> `node -e console.log(1)`, and a path containing a space has to be written as an
+> array entry. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) §10.
+
+> ⚠️ **v0.0.1 note:** Localside is verified as a standalone process. Running it
+> *in-process* from the plugin (`autoStartAgent: true`) is implemented but has
+> not been exercised end-to-end in this release — start it as its own process.
+
+### 3. The DSH plugin
+
+**From npm** — the shortest form, and the one the marketplaces install:
+
+```bash
+dsh plugin --profile <profile-name> add @twinsearth/w2m-dsh-plugin
+```
+
+**From the release tarball** — the same bytes, and it needs no registry at all:
+
+```bash
+dsh plugin --profile <profile-name> add \
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.4.6/twinsearth-w2m-dsh-plugin-0.4.6.tgz
+```
+
+**From the repository** — the form a marketplace's one-click installer uses (it clones
+the repo, builds nothing, and registers `cordis.patch.yml`):
+
+```bash
+dsh plugin --profile <profile-name> install TwinsEarth/dsh-windows2macos
+```
+
+All three end up with the same package: `release.yml` packs the tarball with
+`scripts/pack.mjs`, the release publishes it with `SHA256SUMS`, and the npm publish uses
+that exact file rather than repacking — so "which artifact did you install?" has one
+answer, not three.
+
+> Whichever form you use, the installer must end up with the plugin in the profile's
+> `node_modules` **and** a row in the profile's `cordis.patch.yml`. A bundle that is
+> listed in `package.json` but never composed is the failure this project hit once
+> already — see `cordis.patch.yml`'s header for what that looked like.
+
+Then give it the relay URL in that profile's `cordis.patch.yml` — or leave
+`rabbitUrl` empty to use the shared server:
+
+```yaml
+- id: w2m
+  config:
+    rabbitUrl: ''            # empty => the shared server's default
+    operatorToken: ''        # required to dispatch; the relay prints it once
+    stateDir: /absolute/path/to/$DSH_HOME/xclient   # `!!js process.env.DSH_HOME` can evaluate to undefined
+    machineName: win-desktop
+    p2pMode: auto
+```
+
+Restart DSH. You should see eight tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
+`w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`.
+
+> `dsh` may not be on your `PATH`. On a packaged install it lives under
+> `resources/runtime/cli/bin/`. If `dsh` is not found, call it by path.
+
+### What this plugin touches, before you install it
+
+Stated here and machine-readably in `package.json`'s `disclosure`, because installing a
+plugin runs its code with your permissions:
+
+| | |
+|---|---|
+| **Cloud** | yes — a relay is required. The default is the shared server (`202.182.123.154:8787`, STUN on `:3478`); point `rabbitUrl` at your own host, or run the relay yourself with `deploy/shared-server/install.sh` |
+| **Offline** | no. The relay is the ledger; peer-to-peer only moves the task offer, and the result still reaches the ledger |
+| **Credentials** | the operator token (profile config or `W2M_OPERATOR_TOKEN`) authorises *dispatched work*; the device token lives in `$DSH_HOME/xclient/device.json` (mode 0600 where the platform honours it) and authorises *taking* work |
+| **Filesystem** | reads and writes inside your project directory (anchors, fingerprints), plus its own spool and state under `--state` |
+| **Network** | the configured relay, the STUN servers, and UDP to the peer machines. Peers can reach this machine's punch port, which is ephemeral unless you pin it with `--p2p-port` |
+| **Jurisdiction** | data crosses between wherever your machines are and wherever the relay is; the reference deployment is CN ↔ JP |
+
+## Use
+
+Then just talk to DSH:
+
+> List my machines, then run `node --test` on all of them at the same commit and
+> tell me whether the output matches.
+
+The model calls `w2m_devices` → `w2m_run` → `w2m_wait` → `w2m_report` and hands
+you the comparison.
+
+## Why you can trust the comparison
+
+A commit SHA alone is not enough. Measured: on a **dirty** working tree,
+`git checkout --detach <sha>` **exits 0 and keeps the local changes** — HEAD
+matches the base while the working tree does not. Compare on SHA alone and you
+will report a logic difference that is really a "these are not the same files"
+difference.
+
+So every result carries **three anchors**:
+
+| Anchor | What it proves |
+|---|---|
+| `base_commit` | both machines started from the same commit |
+| `pre_tree_fingerprint` | both had the **same working-tree bytes**, including untracked files |
+| `command_hash` | both ran the same argv, in the same shell mode, in the same relative cwd |
+
+The fingerprint algorithm is `git-temp-index-tree/v1`: a throwaway index file
+(`git read-tree` → `git add -A` → `git write-tree`) that never touches your
+working tree. Each call gets its **own** temporary index — sharing one
+`GIT_INDEX_FILE` across processes makes them fail with `idx.lock: File exists`.
+
+`git stash create` is *not* used: measured, it drops untracked files and returns
+an empty string in both the "clean" and "only untracked files" cases, so the two
+are indistinguishable.
+
+**Prerequisite:** put this in your project root, or the two machines will never
+fingerprint alike:
+
+```gitattributes
+* text=auto eol=lf
+```
+
+Measured: with that line, a `core.autocrlf=true` checkout and a
+`core.autocrlf=false` checkout produce byte-identical working trees. Without it,
+one is CRLF and the other LF.
+
+## Across networks and regions
+
+> **New in 0.1.2.** Before this version the relay only worked at the root of a
+> host: endpoints were built with `new URL('/v1/stream', rabbitUrl)`, which
+> discards a path prefix, so anything mounted under `/w2m` answered 404 to
+> everything. Sub-path deployment now works, and sending work requires its own
+> credential. See [CHANGELOG](CHANGELOG.md#012--2026-10-07).
+
+Machines only ever make **outbound** connections, so the relay can be anywhere
+both sides can reach. Four shapes are supported and documented end to end in
+[docs/DEPLOY.md](docs/DEPLOY.md):
+
+| Shape | TLS terminated by | `rabbitUrl` looks like |
+|---|---|---|
+| **The shared server** (v0.4.0 default) | nothing — plain `http://` on a public IP | `http://202.182.123.154:8787` |
+| **Your own VPS** | the relay (`--tls-cert`/`--tls-key`) or a proxy | `https://w2m.example.com` |
+| **Tailscale / WireGuard** | the network — WireGuard encrypts | `http://100.x.y.z:8787` |
+| **Tunnel** (Cloudflare Tunnel, ngrok) | the tunnel service | `https://<sub>.example.com` or with a sub-path |
+
+> **The shared server has no TLS, and that is stated rather than implied.** There is
+> no hostname to issue a certificate for. Pairing codes, tokens and results cross
+> the wire in clear text; the direct path keeps the payload off the relay, and the
+> machine-side allow-list is the load-bearing control. With a domain, add TLS and
+> put `https://` in `rabbitUrl` — nothing else changes:
+> [deploy/shared-server/README.md](deploy/shared-server/README.md).
+
+> **Plain `http://` over a Tailscale address is not a mistake.** WireGuard already
+> provides end-to-end encryption and authenticates both peers; adding TLS on top
+> would add certificate plumbing without adding a property you do not already
+> have.
+
+If your proxy or tunnel mounts the relay under a prefix — `https://host/w2m/` —
+then start it with `--base-path /w2m` and put the same prefix in `rabbitUrl`.
+Sub-path deployment works because URLs are joined by concatenation; see
+[CHANGELOG](CHANGELOG.md#012--2026-10-07) for the bug that made this impossible
+before 0.1.2.
+
+### Two credentials, on purpose
+
+| Credential | Held by | Authorises |
+|---|---|---|
+| `device_token` | each machine | taking work, reporting results |
+| `operator_token` | **only you** | **sending work** (`POST /v1/task`) |
+
+A machine that can be told what to do should not automatically be able to tell the
+others. The relay writes the operator token to `<state>/operator-token.txt` on
+first start and prints it once; the plugin takes it as `operatorToken`. Starting
+the relay with `--operator-token ''` removes the requirement — it warns loudly,
+and that is only appropriate for a trusted LAN.
+
+### Surviving a restart
+
+`devices.json` plus `ledger.jsonl` mean a restarted relay keeps its paired
+machines and its task history, which matters once the relay lives on a VPS you
+will eventually reboot. A corrupt ledger line is skipped and reported; a corrupt
+device file starts empty **and says so** rather than silently forgetting every
+machine. `--no-persist` restores in-memory behaviour.
+
+## Staying up to date
+
+> **New in 0.2.3.** A machine running this plugin checks its own GitHub releases
+> at **00:00, 03:00 and 05:00 Beijing time** and installs a newer version if there
+> is one. This is **off by default** — an updater that replaces the installed
+> plugin is opt-in.
+
+Turn it on in the profile patch:
+
+```yaml
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- insert:
+    - id: w2m-tools
+      name: '@twinsearth/w2m-dsh-plugin/tools'
+      config:
+        rabbitUrl: 'http://100.x.y.z:8787'
+        autoUpdate: true          # default false
+        # autoUpdateTimes: ['00:00:00', '03:00:00', '05:00:00']   # Beijing wall clock
+        # autoUpdateTimeZone: Asia/Shanghai                       # default
+        # autoUpdateDryRun: true                                  # verify, install nothing
+        # updateRepo: TwinsEarth/dsh-windows2macos                # default
+```
+
+Ask it what it is doing from any session with `w2m_update` (`action: "status"` to
+inspect, `action: "check"` to run one cycle now).
+
+**What it does and does not do:**
+
+- Compares the newest GitHub release against the version it was built as. It
+  installs **only a strictly newer, non-prerelease** version — a downgrade is
+  worse than a missed update, and a release candidate outranks the release it
+  precedes by SemVer, so the gate is explicit.
+- Downloads the tarball and **verifies the SHA-256 published in that release's
+  `SHA256SUMS`** before anything is written. A mismatch installs nothing.
+- Backs up the profile's `package.json` and `pnpm-lock.yaml`, then installs
+  through `dsh plugin --profile <p> add <tarball>` (falling back to the runtime's
+  own pnpm). If the install fails, the manifest is restored byte-for-byte.
+- **It does not restart DSH.** The new version loads on the next start; the
+  running process keeps the code it loaded. `w2m_status` reports
+  `restart_required` once an install has happened, and the installed tarball
+  lives in `<profile>/.w2m-update/` so the dependency does not dangle.
+- **It does not hot-swap the running plugin.** Nothing may rewrite the module a
+  live Cordis container already loaded, so claiming otherwise would be a lie in
+  the status output.
+
+**Honest limits.**
+
+- A missed slot runs once on the next start if it was missed by less than 90
+  minutes (a machine asleep across one slot). Wider than that and the check waits
+  for the next slot rather than firing at an arbitrary hour.
+- If pnpm fails *after* it has already changed `node_modules`, restoring the
+  manifest is not enough to guarantee DSH still starts. The result then carries
+  `rollbackComplete: false` and a `reconciliation` command; `w2m_status` surfaces
+  it as `reconciliation_needed`. This is the one state that needs a human.
+- A negative result is never reported as success: a GitHub lookup that fails is
+  recorded as an **error**, not as "already up to date", because those two look
+  identical in a log and only one of them is a problem.
+
+## Security
+
+Read this before exposing the relay to anything.
+
+- **Admission** is a single-use, rotating pairing code, then a per-device bearer
+  token stored in `device.json` (mode `0600`). Pairing attempts are rate limited
+  (5 per IP per minute by default, successes included).
+- **Sending work needs the operator token**, not a device token.
+- **`--trust-proxy` is off by default and should stay off** unless the relay
+  really is behind a proxy you control: it makes the relay believe
+  `X-Forwarded-For`, and believing that header without a proxy in front lets any
+  client forge its address and walk past the rate limit.
+- **The relay holds no model credentials and no working copy.** It can forge
+  tasks, which is exactly why the machine-side whitelist is the load-bearing
+  control.
+- **Commands are never shell strings.** argv arrays are passed to
+  `spawn(cmd, args, { shell: false })`, so nothing a caller types can be
+  reinterpreted as shell syntax.
+- **Default-deny whitelist.** A machine runs nothing that does not match
+  `--allowed-commands`.
+- **Read-only by default.** `replicate` tasks run with `write: false`; there is
+  no code path that writes to your project in that mode.
+- **TLS is your choice, but a deliberate one.** Shape A gets it from WireGuard;
+  shapes B and C get it from the relay's `--tls-cert`/`--tls-key` or from the
+  proxy. Running shape B or C over plain `http://` would put the operator token
+  and every result on the wire in clear text — do not.
+- The plugin **does not read** `.credentials.yaml`.
+
+## Verified, and not verified
+
+This project's rule is that claims carry their evidence.
+
+### v0.4.0 — the direct path is the default, and here is what that is worth
+
+v0.3.9 shipped the P2P transport and admitted in its own §8 that nothing read
+`p2p.mode`, the announcer did not exist and the task path still went through the
+relay. v0.4.0 is that admission paid off:
+
+* **the announcer exists** — a machine binds one UDP socket, asks the STUN servers
+  what the world sees, announces its candidates and refreshes them;
+* **the offer can arrive over the punched path**, and the result can return over it;
+* **exactly-once survives both copies arriving** — the relay's offer is still
+  emitted, and a second copy of the same `task_id`+`attempt` is never executed;
+* **every result says which path it took** (`transport`, `p2p.offer_path`,
+  `p2p.result_path`, and a `路径` column in the report);
+* **the relay is still the ledger** — the direct copy is additional, never a
+  replacement, so the comparison cannot become less trustworthy because a network
+  was faster.
+
+Three things are worth knowing before relying on it:
+
+* **Punching cannot succeed against a symmetric NAT**, and this is measured twice
+  on two real networks: an iPhone hotspot (v0.3.9) and the reference Windows
+  client network, China Mobile (v0.4.0 — three servers, three mapped ports: 36028,
+  5855, 26713). Nothing can dial *into* such a network, which is why the default is
+  `auto` with a *reported* fallback rather than `direct`.
+* **A punch from a symmetric NAT to a public peer still lands** — measured:
+  `HELLO` → `HELLO_ACK` in **331.61 ms** from that same Chinese network to the
+  shared server in Tokyo, with the ledger recording `transport: p2p` for the
+  Japanese machine. A punch you initiate opens the mapping, and the peer's answer
+  to the datagram it just received comes back through it. That asymmetry is why the
+  dispatcher dials the executor.
+* **A machine that must accept a punch needs a reachable UDP port.** On a public
+  host that is a firewall rule for the agent's punch port (the shared server has
+  one); behind a NAT it is the hole the punch opens. **v0.4.1 pins it**: `--p2p-port <n>`
+  (or `W2M_P2P_PORT`) makes the rule name one port instead of a range, which v0.4.0 could not
+  do — the node always bound an ephemeral one, so the rule had to be re-pointed after every
+  restart.
+* **A two-NAT punch is still unverified.** Two sockets on one host share a path
+  with no translator between them, so the loopback tests prove the protocol and
+  nothing about NAT. What *has* now been measured is one real WAN hop: dispatcher
+  on a Chinese residential network, executor on the shared server in Tokyo. That is
+  one NAT, and it is labelled as one NAT.
+
+**The same suites run on three platforms in CI** — see the badge above, or
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml). The matrix is
+`windows-latest` × node 20/22, `macos-latest` × node 22, `ubuntu-latest` ×
+node 22. That matters here more than in most projects: a Windows-and-macOS
+coordination tool whose macOS half had never been executed would be a claim, not
+a product.
+
+| Suite | Tests | What it covers |
+|---|---|---|
+| relay | 91 | pairing, auth, SSE with `ready`-first and `seq` replay, leases with heartbeat renewal and expiry, dedupe, all six aggregation states, report generation, operation token, rate limiting, persistence and restart recovery, TLS, and the lost-offer recovery path |
+| agent | 105 | whitelist allow/deny, timeout, output truncation, exit codes, anchors on clean and dirty trees, four concurrent fingerprint computations, spool, a 40-case URL join matrix, cursor lifecycle across relay restarts |
+| plugin | 73 | eight tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints |
+| end to end + crossnetwork | 46 | two Localsides on two checkouts against one relay running real commands: consistent / divergent / failed / refused / unverifiable / deduped / long-lease / split, plus sub-path deployment, the two credential kinds, a SIGKILLed relay restarting with its ledger intact, pairing rate limiting, proxy-header trust boundaries, and the anti-buffering headers |
+| schedule | 39 | the daily slots as exact UTC instants, zones that shift by 30 minutes for DST, a full simulated year of consecutive arming, and catch-up collapsing several missed slots into one run |
+| auto-update | 34 | the install/skip decision, no downgrade, prerelease refused, an unverified tarball refused, a failed lookup recorded as an error rather than as "current", and no token ever persisted |
+| update-source | 50 | version ordering, streaming SHA-256 verification, timeouts that really abort, rate-limit reporting, and one real GitHub API call (opt-in — see below) |
+| update-install | 28 | zero writes on a hash mismatch, byte-for-byte restore, atomic staging, dry run, and two real-pnpm integration runs in throwaway profiles |
+| update-wiring | 15 | configuration validation that names the setting, and one `ctx.effect` owning the timer whose disposer stops it |
+
+435 unit tests total: 434 pass, 1 skip. Run them with `scripts/verify.ps1`
+(Windows) or `scripts/verify.sh` (macOS/Linux). The skip is one agent test that
+asserts POSIX mode bits, which NTFS does not carry.
+
+The one test that calls GitHub for real is **opt-in** (`W2M_NETWORK_TESTS=1`).
+GitHub allows 60 unauthenticated API requests per hour *per IP* and hosted CI
+runners share IPs, so it failed on `macos-latest` with HTTP 403 `RATE_LIMITED`
+while every other job passed — and a release gate that depends on someone else's
+rate-limit budget eventually blocks a release for a reason unrelated to the code.
+CI still runs it in a separate **non-blocking** job with the workflow token, and
+the same code paths are covered without a network in the blocking matrix.
+
+Two behaviours are checked but not covered by a test file, because both concern
+the real binaries rather than the modules:
+
+- **CLI smoke test** (`scripts/smoke-cli.ps1`): real `w2m-rabbit` plus two real
+  `w2m-localside` processes, ending in a `consistent` verdict and a rendered
+  markdown report.
+- **Release-artifact reproducibility**: CI packs the sources twice and fails if
+  the two tarballs differ, so a published hash is a statement about the sources
+  rather than about when the command ran.
+
+Two extra gates exist because "it installed" is not "it loads" — the first
+version of this package shipped a re-export naming a symbol that did not exist,
+and it passed `node --check` and every unit test, failing only when DSH mounted
+the plugin:
+
+```bash
+node scripts/check-entrypoints.mjs   # imports lib/tools.js, the exact specifier cordis.patch.yml mounts
+node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 5 tools
+```
+
+**Not verified:**
+
+- **A real Windows↔macOS pair.** The CI matrix proves each platform runs the
+  suites, but the two halves of a matrix job never talk to each other: CI does
+  not pair a Windows runner with a macOS runner over the network. The
+  machine-to-machine link has only been exercised between two processes on one
+  host. Burn-in on your own two machines is still the last step.
+- **A single account driving both machines' model sessions.** This release
+  executes commands deterministically; it does not inject prompts into a remote
+  DSH session. Whether one account can run two concurrent model sessions at once
+  depends on your account's limits and is untested here.
+- **`write: true`.** A write-enabled task is executed, but there is no branch
+  merge in 0.0.1.
+
+## Design notes
+
+- **Zero third-party runtime dependencies.** Only `node:` built-in modules. The
+  relay is `node:http`; the downlink is Server-Sent Events and the uplink is
+  ordinary POST, so there is no WebSocket handshake to get wrong.
+- **`@deepseek-ai/dsh-tools` is an optional peer dependency**, resolved at
+  runtime by DSH. It is deliberately *not* a hard dependency: declaring it would
+  pull roughly 287 `@deepseek-ai/*` packages into the install for one import.
+- **Long lease + progress heartbeat**, never a fixed timeout. Measured risk: a
+  machine running a 40-minute test would be declared dead and the task re-sent to
+  another machine — both machines then running it, both producing side effects.
+  Only a *failed renewal* marks a lease dead, and only the relay's clock decides.
+
+The full wire contract — every endpoint, field and state transition — is in
+[PROTOCOL.md](PROTOCOL.md). It is frozen: changing it is a breaking change.
+
+## Development
+
+```bash
+node --test test/                          # everything
+node --test test/relay.test.mjs
+node --test test/agent.test.mjs
+node --test test/tools.test.mjs
+node --test --test-force-exit test/e2e.test.mjs   # see note
+```
+
+> The end-to-end suite needs `--test-force-exit`: each simulated machine holds an
+> open SSE connection, and a long-lived stream keeps Node's event loop alive
+> after the assertions finish. The suite also needs a git binary on `PATH`.
+
+## Contributing
+
+Issues and pull requests are welcome. If you change observable behaviour, update
+`PROTOCOL.md` in the same commit — that file is the contract three components
+agree on.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## 中文说明
+
+**同一个 DeepSeek 账号，一条指令，让在线的 Windows 与 Mac 跑同一个项目。**
+
+### 为什么需要它
+
+DSH 目前**不能**跨机器协作，而且不是疏忽：
+
+- 一个 `dsh` 进程只服务**一台机器**（一个 profile 就是一个本地 pnpm workspace）；
+- 传输层是**仅回环**的（web 服务器只接受 `127.0.0.1`/`0.0.0.0`，CLI 明确拒绝 `--host 0.0.0.0`，因为它自身不带 TLS 与来源策略）；
+- 官方 agent-team 明确**不支持** teammates 各自独立的工作目录，也**不支持多个进程协作同一个 team**。
+
+所以跨机器能力必须自建。这就是那个实现。
+
+### 核心设计
+
+| 设计 | 理由 |
+|---|---|
+| **P2P 直连优先**（v0.4.0 默认） | 两端各报自己的反射地址，由派发方打洞并把任务直接送过去；打不通才回落到中继，并且**报告用了哪条路** |
+| **中继 = 会合点 + 账本 + 回落** | 中继仍然收下每一条结果：它是账本，账本不完整，比较就不可信 |
+| **默认只读**（`replicate` 且 `write: false`） | 一次性消除重复提交、覆盖写、推送竞争这三类最常见的事故 |
+| **三锚校验** | 实测：脏工作区上 `git checkout --detach <sha>` **退出码 0 却保留本地改动** —— 只看 commit SHA 会把"不是同一份代码"误判成"结果分歧" |
+| **六态聚合** | "环境不同"与"结果不同"是两件事，合并记账会把噪声当 bug |
+| **能力不匹配 → `refused`** | 拒绝执行，而不是静默降级 |
+| **长租约 + 进度心跳** | 固定超时会让跑 40 分钟的机器被判死并重投 → **两台同时跑、同时产生副作用** |
+| **零第三方运行时依赖** | 只用 `node:` 内置模块；下行 SSE + 上行 POST，不用 WebSocket |
+
+### 快速开始
+
+```bash
+# 1) 中继 + STUN（任一台常开的机器，一次）
+#    v0.4.0 已内置共享服务器作为默认值，这一步是可选的：
+#    http://202.182.123.154:8787 与 202.182.123.154:3478
+node bin/w2m-rabbit.mjs --host 0.0.0.0 --port 8787 --state ~/.dsh/xclient/rabbit
+node bin/w2m-stun.mjs   --host 0.0.0.0 --port 3478
+#    中继会打印一次性配对码 PAIR-XXXXXXXX
+
+# 2) 每台参与机器（在其项目目录所在机器上跑）
+node bin/w2m-localside.mjs --rabbit http://<中继地址>:8787 --pair PAIR-XXXXXXXX \
+  --project /path/to/your/project --name win-desktop --p2p-mode auto \
+  --allowed-commands '["node --test","git status --porcelain"]'
+
+# 3) 装 DSH 插件
+dsh plugin --profile <profile-name> add \
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.4.3/twinsearth-w2m-dsh-plugin-0.4.3.tgz
+```
+
+然后在 profile 的 `cordis.patch.yml` 里给插件 `rabbitUrl`（留空即用共享服务器）与 `operatorToken`，重启 DSH，即可直接用自然语言指挥：
+
+> 列出我的机器，然后在所有机器上跑 `node --test`，告诉我输出是否一致。
+
+### 项目前置条件
+
+项目根必须有 `.gitattributes` 写 `* text=auto eol=lf`，否则两台机器的指纹永远不一致（实测：加了之后 `autocrlf=true` 与 `=false` 两种配置的工作区字节完全相同）。
+
+### 已实测 / 未实测
+
+- ✅ **P2P 直连已接通（v0.4.0）**：宣告（announce）、打洞、任务通过直连通道送达、结果沿同一通道返回、两条路径同时到达时**只执行一次**、以及每条结果都带 `transport` / `p2p.offer_path` / `p2p.result_path`。回落到中继时带**具体原因**（`P2P_PUNCH_TIMEOUT` 等），不是一句"没走直连"。
+- ✅ **跨真网一跳已实测**：派发端在**中国移动的对称 NAT 之后**（三台 STUN 服务器给出三个不同的映射端口：36028 / 5855 / 26713，`endpoint-dependent`，punchable: false），执行端在东京的共享服务器上。**实测打洞成功：`HELLO` → `HELLO_ACK` 331.61 ms**，账本为那台日本机器记录 `transport: p2p`（`result_path: p2p`）。对称 NAT 挡住的是"被拨入"，挡不住"主动拨出" —— 这正是派发方负责打洞的原因。
+- ✅ **要接受打洞的机器必须有可达的 UDP 端口**：公网主机上就是一条防火墙规则（共享服务器已加）。**v0.4.1 起可以用 `--p2p-port <n>`（或 `W2M_P2P_PORT`）固定端口**，规则只需写一个端口，不必覆盖区间。
+- ✅ **共享服务器已上线**：中继（`:8787` 与经 nginx 的 `:80`）、STUN 响应器（`:3478/udp`）、systemd 单元、ufw 规则，一条命令可复现：`deploy/shared-server/install.sh`。
+- ✅ **三平台 CI**：同一套用例在 `windows-latest`（node 20/22）、`macos-latest`（node 22）、`ubuntu-latest`（node 22）上跑，见上方徽章与 `.github/workflows/ci.yml`。
+- ⚠️ **两个 NAT 之后的互通仍未实测**：本机环回上的打洞只证明协议正确，不证明能穿透 NAT；目前实测的是**一跳、一个 NAT**（见上）。
+- ⚠️ **真实的 Windows↔macOS 互联未实测**：CI 矩阵只证明**各平台都能跑**这套代码；矩阵里的两台机器**并不会互相通信**。
+- ⚠️ **UDP 直连通道本身不认证**（与 v0.3.9 §6 相同）：session id 是 32 位随机数，UDP 源地址可伪造 —— 直连不比中继更可信，威胁模型包含路上攻击者时请开启请求签名。
+- ⚠️ **单账号驱动两台机器的模型会话未实测**：本版本执行的是**确定性命令**，不向远端 DSH 会话注入 prompt。
+- ⚠️ **`write: true` 不合并**：写模式的任务会执行，但没有分支合并。
+
+### 许可
+
+[MIT](LICENSE)