@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.2

package/README.md

@@ -65,8 +65,13 @@ when the network will not allow it.
 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.
+back for **3000 ms** (`DEFAULT_P2P_OFFER_GRACE_MS`) 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 constant was 1200 ms first and that was **too tight**: measured on
+a 1-vCPU shared host, two agent tests saw the relay's copy overtake the direct one,
+which under `p2pMode: direct` means refusing an offer that was about to arrive.
+3000 ms covers a slow host with room to spare, and the cost is bounded — one delayed
+copy per task, once.
 
 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
@@ -95,27 +100,52 @@ socket — `endpoint-dependent`, punchable: false. A default that hard-required
 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
+### Four coordination modes
+
+Four — and the third and fourth are the ones people fail to find, which is why they are named here.
 
 | 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 |
+| `broadcast` | **exactly one** machine runs it, chosen with `executor_machine_id` (or the composer's selected target); every other machine holds an `observing` lease and is told the outcome | "run this migration on the database host, and tell everyone what happened" |
+| `pipeline` | **every** machine runs the whole `stages` chain, in order, stopping at the first stage that fails | "check out, build, then test — as one task with one verdict" |
+
+Two properties of the last two are worth stating because they are what stop them from being footguns:
 
-### Six aggregation states
+* **Observers are never counted as agreeing.** An `observing` lease is excluded from every aggregation
+  step, so a machine that did not run the command cannot be reported as having produced the same result.
+* **A pipeline has no cross-machine data flow.** It is `replicate` applied to a sequence: stage 2 on a
+  machine consumes that machine's stage 1, never a peer's. The alternative — fan stage 1 out, converge
+  the outputs into stage 2 — has no well-defined input on a fleet, and two machines finishing in a
+  different order would make one `task_id` describe two different executions. The reasoning is in
+  [docs/PIPELINE-DESIGN.md](docs/PIPELINE-DESIGN.md), which also records that the chain's `command_hash`
+  binds **every** stage, not just the first.
 
-Not four — because "the environments differ" and "the results differ" are
-different findings, and collapsing them turns noise into bug reports.
+### Nine aggregation states
+
+Nine, not four — because "the environments differ" and "the results differ" are different findings, and
+collapsing them turns noise into bug reports. Three more were added in v0.3.0, each replacing a case that
+used to be reported as something less true.
 
 | 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 |
+| `degraded` | every machine reported; some succeeded and some failed. Distinct from `partial`, which also means "still in flight" |
 | `failed` | every machine failed |
-| `partial` | some succeeded, some failed |
+| `partial` | some succeeded, some failed, and machines are still out |
+| `timeout` | the deadline passed and the machines that never answered are not coming back |
+| `cancelled` | the operator stopped it — not a defect, so it must not be reported as `failed` |
 | `unverifiable` | an **anchor** did not match, so comparison is refused |
 
+Two more values are **not verdicts**, because no terminal answer exists yet or none was ever possible:
+`pending` (before the first result lands) and `refused` (every machine was refused at the capability
+gate). `pending` is the only non-terminal one; `refused` reads like "still deciding" but every machine
+has already answered, so waiting cannot change it. All nine verdicts are declared in
+`src/relay/report.mjs`'s `AGGREGATE_STATUSES`.
+
 ## Install
 
 > **This package can run three ways, and all three start the same binaries.**
@@ -181,6 +211,28 @@ runs unless it matches a prefix:
 > 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.
+>
+> **What an entry actually grants — read this before trusting a list.** An entry
+> names a tool and the arguments up to a point; whatever follows is still that
+> tool's own behaviour, so `node --test` allows `node --test <any file>`, and the
+> test runner loads and runs whatever file it is handed. **A prefix entry is not a
+> sandbox**: it says which program may run, not what that program will do. Two
+> narrower rules sit on top of the prefix match:
+>
+> * **Code-loading trailing arguments are refused** (`COMMAND_REPARSING_ARGUMENT`):
+>   `--test-reporter`, `--import`, `--require`, `-r`, `--experimental-loader`,
+>   `-e`/`--eval`, `-p`/`--print`, `python -c`/`-m`, `bash -c`, `git -c`/`--exec-path`,
+>   `make -f`, `tar --to-command`, and their equivalents in the interpreters in
+>   common use. If a machine is meant to run one of them, name it **in the entry**
+>   (`["node --test --test-reporter=tap"]`) — the entry is the explicit grant, and
+>   the refusal says so.
+> * **The executable is compared by identity, not by spelling.** A bare name is
+>   resolved through PATH as before; an absolute path is admitted only when it
+>   resolves to the same file the entry's executable does (otherwise
+>   `COMMAND_EXECUTABLE_PATH_MISMATCH`), and a relative path is refused outright
+>   (`COMMAND_EXECUTABLE_RELATIVE_PATH`) because the working directory comes from
+>   the offer. A copy of some other program at `E:\Temp\evil\node.exe` is not
+>   `node`, however it is named.
 
 > ⚠️ **v0.0.1 note:** Localside is verified as a standalone process. Running it
 > *in-process* from the plugin (`autoStartAgent: true`) is implemented but has
@@ -198,7 +250,7 @@ dsh plugin --profile <profile-name> add @twinsearth/w2m-dsh-plugin
 
 ```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
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.9/twinsearth-w2m-dsh-plugin-0.5.9.tgz
 ```
 
 **From the repository** — the form a marketplace's one-click installer uses (it clones
@@ -231,6 +283,23 @@ Then give it the relay URL in that profile's `cordis.patch.yml` — or leave
     p2pMode: auto
 ```
 
+> **Do not add a `name:` line to that row.** In a patch, `name` is not a rename — it is an
+> *assertion* about the entry being patched, and the Loader skips the whole patch when it does not
+> match. The row is already inserted by the bundle with the package name, so an override that
+> asserts something else is discarded, and the plugin mounts with the bundle's **empty** defaults:
+>
+> ```
+> patch: name mismatch for "w2m" (expected "@twinsearth/w2m-dsh-plugin",
+>        got "@twinsearth/w2m-dsh-plugin/tools"), skipping
+> ```
+>
+> That is a silent failure by construction — the install looks right, eight tools appear, and
+> `w2m_status` reports `paired: false` and a null `rabbitUrl` because none of your values were ever
+> applied. It is not hypothetical: this row's expected name moved from the `/tools` subpath to the
+> package root in v0.5.4 (see `cordis.patch.yml`'s header for why), and every override that still
+> asserted the old subpath stopped being applied on upgrade. `id` already identifies the row, so the
+> safest `name:` is no `name:` at all.
+
 Restart DSH. You should see eight tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
 `w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`.
 
@@ -342,10 +411,14 @@ before 0.1.2.
 | `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.
+others. The relay writes the operator token to `<state>/operator-token.txt` (mode
+0600) on first start and prints it once — on that first start only, because a
+relay's stdout ends up in journald, a container log or a CI transcript and this
+token authorises dispatching to the whole fleet. Every later start names the file
+instead of the value; `--print-operator-token` (or `W2M_PRINT_OPERATOR_TOKEN=1`)
+prints it anyway for an operator who needs it there. 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
 
@@ -367,8 +440,8 @@ Turn it on in the profile patch:
 ```yaml
 # ~/.dsh/profiles/<profile>/cordis.patch.yml
 - insert:
-    - id: w2m-tools
-      name: '@twinsearth/w2m-dsh-plugin/tools'
+    - id: w2m
+      name: '@twinsearth/w2m-dsh-plugin'
       config:
         rabbitUrl: 'http://100.x.y.z:8787'
         autoUpdate: true          # default false
@@ -378,6 +451,16 @@ Turn it on in the profile patch:
         # updateRepo: TwinsEarth/dsh-windows2macos                # default
 ```
 
+> **The id is `w2m` and the name is the bare package — both matter, and neither is cosmetic.**
+> `w2m` is the id the packaged `cordis.patch.yml` inserts, so a second row under a different id
+> is a second plugin instance rather than a configuration of the first. `@twinsearth/w2m-dsh-plugin`
+> must be the **bare** package name: a subpath such as
+> `@twinsearth/w2m-dsh-plugin/tools` resolves to no `package.json`, so `dsh.client` is never read
+> and **the client half is silently disabled** — the composer control never registers, and nothing
+> on the host side reports a problem. `./tools` remains a supported mount point; it is simply not
+> the one this bundle uses, and using it costs you the browser half. See
+> [TROUBLESHOOTING.md](TROUBLESHOOTING.md) §2.
+
 Ask it what it is doing from any session with `w2m_update` (`action: "status"` to
 inspect, `action: "check"` to run one cycle now).
 
@@ -431,8 +514,11 @@ Read this before exposing the relay to anything.
 - **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`.
+- **Default-deny whitelist, with its limit stated.** A machine runs nothing that
+  does not match `--allowed-commands`, and the matching rules are in §2 above.
+  The list controls *which program* may run; a prefix entry grants what that
+  program can be told to do with the arguments it is given (`node --test` runs
+  the test files it is handed), so it is a control, not a sandbox.
 - **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;
@@ -496,19 +582,103 @@ 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 |
+| relay | 142 | pairing, auth, SSE with `ready`-first and `seq` replay, leases with heartbeat renewal and expiry, dedupe, all **nine** aggregation states plus `pending`/`refused`, report generation, operator token, rate limiting, persistence and restart recovery, TLS, and the lost-offer recovery path |
+| agent | 129 | allow-list 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, and the bundled-runtime resolver |
+| tools | 89 | eight tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints, and the credential canaries |
+| broadcast | 19 | exactly one executor, the rest `observing`; observers excluded from every aggregation step so a machine that did not run is never counted as agreeing |
+| claims | 19 | the document claims themselves: the version, the bundle patch, the tool list, every documented tarball URL, and the CHANGELOG's shape |
+| fleet-target | 37 | the composer's target selection, and the `executor_machine_id` narrowing that overrides it |
+| client-bundle | 25 | the browser half builds, exports, and resolves against `PLATFORM_MODULES` |
 | 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.
+| update-wiring | 34 | configuration validation that names the setting, and one `ctx.effect` owning the timer whose disposer stops it |
+| signing | 33 | request signing: mismatch, expiry, replay and required-signature refusals |
+| stress | 9 | sustained load on the relay's frame handling |
+| shared-config | 16 | the fleet-wide config file, including its refusal of secret-looking keys |
+| metrics / metrics-route | 16 + 5 | the Prometheus exposition and its route, with no credential ever rendered |
+| tool-cards | 8 | the tool descriptions the model actually reads |
+| p2p-stun | 18 | the STUN responder and reflexive-address discovery |
+| p2p-transport | 28 | the reliable ordered channel over UDP |
+| p2p-signaling | 17 | peer candidates: announce, fetch, expiry |
+| p2p-node | 38 | the node that binds the punch socket, announces, punches and dials |
+| p2p-transport-fields | 28 | `transport` / `p2p.offer_path` / `p2p.result_path` / `p2p.opened_by` on every result |
+| p2p-plugin | 32 | the plugin half of the direct path, including the pushes and their named failures |
+| p2p-crypto | 33 | stage 1 of the data-plane encryption: the handshake, the refusal codes, the replay window and the epoch ratchet |
+| stun-server | 27 | the standalone `w2m-stun` binary |
+| loader-entry | 10 | the entry DSH actually mounts, packed and installed — the gate v0.5.4 needed |
+| mdns-wire / mdns-discover | 38 + 45 | the DNS wire codec, and LAN discovery |
+| e2e + crossnetwork | 11 + 35 | 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 |
+| signing-e2e | 8 | a signed task end to end |
+| outbound-only | 7 | a running agent binds no TCP listener, and `relay` mode binds no UDP socket at all |
+| recovery | 4 | restart and lost-offer recovery |
+| pipeline-e2e | 2 | a real relay and a real agent running a chain: the stages append to a witness file, so the ordering evidence is written by the stages themselves; the second case proves the chain stops at the first failure |
+| p2p-agent | 21 | the agent half of the direct path, including the reverse dial for results |
+
+**The numbers above are from v0.5.9 on `win32 x64`, Node `v24.18.1`** — the floor this package
+declares is `>=20.19.0`, and Node 24 is what DSH ships on this host. **36 suites on disk, 1,139 tests:**
+1,131 pass, **2 fail**, 6 skip. The two failures are `test/pipeline-e2e.test.mjs`'s two cases on this
+Windows host; **everything else is green.** Three suites are environment-sensitive and their counts
+move with it: `claims` is 19 tests here and **22 when `dist/` holds a packed tarball**, which is when
+its two tarball-vs-`package.json` checks run instead of skipping — so a checkout with `dist/` measures
+**1,142 tests / 1,134 pass / 4 skip**, and that is the number to expect from a release tree.
+
+**Which script runs which suite matters, because they are not the same set:**
+
+| Command | Suites | Result on this host (v0.5.9) |
+|---|---|---|
+| `npm test` — the unit suite | 29 | 1,051 tests, **all pass**, 6 skip |
+| `npm run test:all` — units + end-to-end | 35 | 1,106 tests, 1,098 pass, **2 fail** (`pipeline-e2e`), 6 skip |
+| `pwsh scripts/verify.ps1` — the acceptance run | 29 | 1,050 tests, 1,048 pass, **2 fail** (`pipeline-e2e`), 6 skip |
+
+> **`test:all` and `verify.ps1` are not supersets of each other.** At v0.5.9 `test:all` was still
+> missing `test/p2p-crypto.test.mjs` — 33 tests covering the data-plane encryption, absent from the
+> suite a release runs, and `CHANGELOG.md`'s v0.5.9 entry says so instead of claiming otherwise.
+> **v0.6.0 applied the one-line fix that entry asked its owner for**, so the file is now in `npm test`
+> and in `test:all`; `verify.ps1`'s own suite list still does not name it.
+
+`%DSH_HOME%\dsh-runtimes\` is absent on this host, which is why `verify.ps1` falls back to the
+`node` on `PATH`; the resolver's own bundled-runtime case is exercised against a throwaway home in
+`test/agent.test.mjs`, and “Not verified” below says what that does and does not prove.
+
+> **`pipeline-e2e` fails 2/2 at the v0.5.9 tag on this host, and the cause is the test, not the
+> product.** Both cases die with `ENOENT … order.txt` / `stop.txt`: the witness files the stages are
+> supposed to append to were never created, because **no stage ever ran**. In that revision the suite
+> passes its agent `--allowed-commands` as the *string* entry `process.execPath`
+> (`pipeline-e2e.test.mjs`, `allowedCommands = [NODE]`). A string entry is split on whitespace **by
+> design**, and on a machine whose Node lives under `C:\Program Files\`, that entry becomes the two
+> tokens `C:\Program` and `Files\nodejs\node.exe`, which match nothing — so the agent refused the
+> chain with `COMMAND_NOT_ALLOWED` before its first stage. It is therefore **not a Node-24 artifact**:
+> it is a test defect that appears wherever the interpreter's path contains a space, and it is
+> consistent with this suite passing on CI runners, whose Node is unpacked to a space-free path.
+> **The working tree already repairs it** (array-form entry naming `-e`, plus a third case asserting
+> that a stage outside the allow-list refuses the whole chain and runs nothing), and measured on this
+> host that repair takes the suite to **3/3 pass**. The failure is recorded here because v0.5.9 is
+> what a reader installs, and the honest label for the tag is **failing on Windows under
+> `C:\Program Files`** rather than "passes".
+
+**Skips are per platform, not a single number, and the difference is one test.** On this Windows host
+(Node 24.18.1, `dist/` present, network tests not enabled) there are **4**:
+
+| Suite | Skipped case | Why |
+|---|---|---|
+| agent | `writes 0600 where the platform honours POSIX bits` | NTFS carries no POSIX mode bits. **Skips on Windows; runs on macOS/Linux.** |
+| agent | `starts a bundled-only tool from runArgv even when PATH cannot see it` | A POSIX shell script is not a Windows executable. **Skips on Windows; runs on macOS/Linux.** |
+| claims | `every documented tarball exists as a release asset` | network check off unless `W2M_NETWORK_TESTS=1` |
+| update-source | `fetches, parses and verifies the published release end to end` | same gate |
+
+Two further cases are environment-conditional rather than platform-conditional, and skip only when
+their input is missing: `claims`'s two tarball-vs-`package.json` checks run when `dist/` holds a
+packed tarball and skip when it does not, and `agent`'s `git anchors` suite skips when `git` is not on
+`PATH`. On this machine `git` is present, so that one does not fire.
+
+The consequence, stated rather than generalised: **macOS and Linux run the two agent cases Windows
+cannot, and skip `reports the windows filesystem honestly`, which is Windows-only**, so their skip
+count is set by the same network gate plus whichever platform case applies — **it is not this host's
+number, and calling it one is exactly the generalisation this section used to make.** No macOS or
+Linux run was performed for this table; only the CI matrix measures those, and by this project's own
+labelling rule the figure above is `[M]` for Windows and `[?]` for the other two.
 
 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
@@ -618,7 +788,7 @@ DSH 目前**不能**跨机器协作，而且不是疏忽：
 | **中继 = 会合点 + 账本 + 回落** | 中继仍然收下每一条结果：它是账本，账本不完整，比较就不可信 |
 | **默认只读**（`replicate` 且 `write: false`） | 一次性消除重复提交、覆盖写、推送竞争这三类最常见的事故 |
 | **三锚校验** | 实测：脏工作区上 `git checkout --detach <sha>` **退出码 0 却保留本地改动** —— 只看 commit SHA 会把"不是同一份代码"误判成"结果分歧" |
-| **六态聚合** | "环境不同"与"结果不同"是两件事，合并记账会把噪声当 bug |
+| **九态聚合** | "环境不同"与"结果不同"是两件事，合并记账会把噪声当 bug；另有 `pending` / `refused` 两个非判定值不计入结论 |
 | **能力不匹配 → `refused`** | 拒绝执行，而不是静默降级 |
 | **长租约 + 进度心跳** | 固定超时会让跑 40 分钟的机器被判死并重投 → **两台同时跑、同时产生副作用** |
 | **零第三方运行时依赖** | 只用 `node:` 内置模块；下行 SSE + 上行 POST，不用 WebSocket |
@@ -640,7 +810,7 @@ node bin/w2m-localside.mjs --rabbit http://<中继地址>:8787 --pair PAIR-XXXXX
 
 # 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
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.9/twinsearth-w2m-dsh-plugin-0.5.9.tgz
 ```
 
 然后在 profile 的 `cordis.patch.yml` 里给插件 `rabbitUrl`（留空即用共享服务器）与 `operatorToken`，重启 DSH，即可直接用自然语言指挥：

package/SECURITY.md

@@ -52,16 +52,23 @@ real service and other people's machines are paired to it.
 
 ## Supported versions
 
-**The supported line is v0.5.3 and everything before it.** A version is installable unless the table
-says otherwise. Security fixes land on the newest installable version; older installable versions are
-not back-patched unless a report makes that necessary, and if it does, this table will say so.
-
-| Version                | Installable        | Note                                                                                                                           |
-| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| **v0.5.6 and later**   | not yet released   | In progress as this document is written. Check `CHANGELOG.md` for the newest entry that is not marked withdrawn.               |
-| v0.5.5                 | **no — withdrawn** | Fails to activate during DSH's web boot, which makes the whole application refuse to start, and takes all eight tools with it. |
-| v0.5.4                 | **no — withdrawn** | Same loader failure. `CHANGELOG.md` marks it `DO NOT INSTALL`.                                                                 |
-| **v0.5.3 and earlier** | **yes**            | The supported line. The client half was added in v0.5.4; v0.5.3 is a host-only plugin that loads.                              |
+**The supported line is v0.5.9, the newest published version.** A version is installable unless the
+table says otherwise. Security fixes land on the newest installable version; older installable
+versions are not back-patched unless a report makes that necessary, and if it does, this table will
+say so.
+
+| Version            | Installable        | Note                                                                                                                           |
+| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| **v0.5.9**         | **yes**            | The supported line, and the current release. The client half is present and activates.                                         |
+| v0.5.6 – v0.5.8    | **yes**            | Installable, and each one works, but each is superseded by v0.5.9. Prefer the newest.                                          |
+| v0.5.5             | **no — withdrawn** | Fails to activate during DSH's web boot, which makes the whole application refuse to start, and takes all eight tools with it. |
+| v0.5.4             | **no — withdrawn** | Same loader failure. `CHANGELOG.md` marks it `DO NOT INSTALL`.                                                                 |
+| v0.5.3 and earlier | **yes — outdated** | Installable, and v0.5.3 is the last host-only release. Nothing before v0.5.4 has the client half, so no composer control.      |
+
+**v0.5.4 and v0.5.5 are withdrawn because they prevent the application from starting.** That is not a
+degraded plugin or a missing feature: the loader entry fails, so the whole host entry is skipped and
+DSH's web boot refuses, taking all eight tools with it. The failure and its cause are written up in
+§3 of `TROUBLESHOOTING.md`.
 
 The withdrawals are not a security judgement: those versions are not installable, so they are not
 supported. `CHANGELOG.md` is the authority — an entry marked `DO NOT INSTALL` is not supported
@@ -71,11 +78,11 @@ whatever this table says, and the reverse is also true.
 
 ```bash
 # The newest installable version from the registry
-dsh plugin --profile <profile> add @twinsearth/w2m-dsh-plugin@0.5.3
+dsh plugin --profile <profile> add @twinsearth/w2m-dsh-plugin@0.5.9
 
 # Or the same bytes from the release, verified against SHA256SUMS from the same release
 dsh plugin --profile <profile> add \
-  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.3/twinsearth-w2m-dsh-plugin-0.5.3.tgz
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.9/twinsearth-w2m-dsh-plugin-0.5.9.tgz
 ```
 
 A version published minutes ago may be invisible to pnpm's `minimumReleaseAge` gate. That is the
@@ -98,6 +105,14 @@ The split is the point: a machine that can receive work does not thereby gain th
 the others. If a machine's device token is stolen, the damage is confined to that machine's own
 execution surface; it cannot be used to drive the fleet.
 
+**It does, however, read the fleet's task metadata.** `GET /v1/tasks/{task_id}`, `POST /v1/heartbeat`
+and the result/notice routes accept a **device** token, and a task's aggregate is keyed by `task_id`,
+not by which machine is asking. So any paired machine's device token can read the aggregate of **any**
+task on **every** machine — statuses, per-machine outcomes, anchors, comparable fields, counts. What it
+cannot read that way is the captured output itself: the aggregate carries hashes and byte counts, not
+`stdout`/`stderr` text. Treat the device token as a **fleet-wide metadata read credential**, not as a
+credential scoped to its own machine.
+
 The relay writes the operator token once, on first start, and prints it once on stderr. It is
 deliberately absent from `--json` output — a token in a log is a leak. Treat it as a credential: it is
 never needed in a bug report.
@@ -106,8 +121,22 @@ never needed in a bug report.
 
 - **Run commands you allow, in the project directory it was pointed at.** The allow-list is
   **default-deny** and matches the whole `argv`, token by token: an entry `node --test` permits
-  `node --test x.test.mjs` and refuses `node --testify x`. An empty list is not "nothing runs" — it
-  means the plugin-side gate is not applied, so rely on the agent-side `--allowed-commands`.
+  `node --test x.test.mjs` and refuses `node --testify x`. That permission is **as wide as the tool**:
+  the test runner loads and runs the file it is handed, so `node --test` is a grant of code execution
+  from any file the machine can read — a prefix entry is not a sandbox. Two narrower rules apply on
+  top of the prefix match: trailing arguments that make the tool load code the entry never named
+  (`--test-reporter`, `--import`, `-e`, `python -c`, …) are refused with `COMMAND_REPARSING_ARGUMENT`,
+  and `argv[0]` is admitted as a path only when it is the file the entry's executable resolves to
+  (`COMMAND_EXECUTABLE_PATH_MISMATCH`; relative paths are refused outright with
+  `COMMAND_EXECUTABLE_RELATIVE_PATH`). Neither turns a prefix entry into a per-argument policy — if
+  you need that, name the arguments in the entry. **An empty allow-list means two opposite
+  things on the two sides, so set both.** The plugin's list (`allowedCommands`) is not a gate at all
+  when it is empty: with nothing configured the plugin declines to refuse, deliberately, and says so —
+  `checkAllowedCommand` returns "may proceed" rather than duplicating a policy it was not given. The
+  agent's list (`--allowed-commands`) is default-deny with nothing configured: an empty list refuses
+  **every** offer, and the refusal names the reason. So a fleet with no list on either side runs
+  nothing, and a fleet with the plugin's list empty but an agent list set runs exactly what the agent
+  allows — which is the only one of the two that is a control.
 - **Read the project** it was started with, and compute git anchors and fingerprints over it.
 - **Report results**, including command output, to the relay — where the operator who dispatched the
   work can read them.
@@ -116,12 +145,16 @@ never needed in a bug report.
 ### What a paired machine cannot do
 
 - **Run anything outside its allow-list.** A refused command is reported as `refused` with
-  `COMMAND_NOT_ALLOWED`, not executed.
+  `COMMAND_NOT_ALLOWED` — or, for the narrower rules above, `COMMAND_REPARSING_ARGUMENT`,
+  `COMMAND_EXECUTABLE_PATH_MISMATCH` or `COMMAND_EXECUTABLE_RELATIVE_PATH` — not executed.
 - **Command other machines.** That requires the operator token, which the agent is not given.
-- **Read another machine's results.** This is the claim people most reasonably doubt, and it is worth
-  being precise: the operator token authorises _dispatch_. A machine's results are visible to whoever
-  holds the operator token for that relay — the ledger is the relay's, not the agent's — so an agent
-  holding only its device token cannot enumerate or fetch another machine's output.
+- **Read another machine's captured output.** This is the claim people most reasonably doubt, so it is
+  worth being exact rather than broad — see the read-scope paragraph above, which is the other half of
+  it. The operator token authorises _dispatch_, and no step of a dispatch needs a machine's `stdout`.
+  The relay's stored envelope does carry `stdout_head`/`stdout_tail`, but the aggregate that
+  `GET /v1/tasks/{task_id}` and the report render expose only `stdout_sha256`, `stdout_bytes` and the
+  comparable fields, so a device token alone cannot fetch that text. **Fleet-wide metadata, no captured
+  output** — if you need stronger than that, it is not there today.
 - **Ask for your interactive confirmation per command.** There is no approval prompt in the loop. The
   allow-list is the gate, which is why it is default-deny and why you should make it as narrow as the
   work allows.
@@ -131,6 +164,23 @@ never needed in a bug report.
   and Windows has no `sshd` by default. If you find anything in this project writing to an
   `authorized_keys` file, that is a security report — please use the private channel above.
 
+### The guarantees nobody has tested yet
+
+The consent model above is the claim this project asks you to trust. Four of its statements are, as of
+v0.5.9, **not backed by any test** — and the difference between "enforced", "true by absence" and "true
+because we looked" matters, so each is labelled here the way an audit would label it rather than the way
+a policy document would.
+
+| Statement                                                          | Why it holds today                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | What it would take to be checkable                                                                                                                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **The relay holds no model credentials and no working copy.**      | **Enforced by the code's shape, not by a test or a guard.** The relay is a process whose entire filesystem access is its own state: `src/relay/persistence.mjs` reads and writes `devices.json`, `ledger.jsonl` and `operator-token.txt`, and `src/relay/server.mjs` reads the TLS cert and key. It never reads a project directory, so there is no code path a model credential could arrive through. It _does_ hold your task metadata, results and the operator token — that is the ledger's job, and it is stated above. | A test that the packed relay, started in a temp home with a project directory containing a `.credentials.yaml`, opens no file under that directory. `test/claims.test.mjs` is the natural home. |
+| **The plugin never reads `.credentials.yaml`.**                    | **True by absence.** There is **no code path that references it anywhere in this repository** — no `readFile`, no `join`, nothing but the one comment in `src/plugin/tools.mjs` that promises not to. That is the strongest evidence available and it is **weaker than a test**: it says nobody wrote it yet, not that nothing can.                                                                                                                                                                                          | A source-level assertion over the shipped files: no `src/**` or `bin/**` file mentions a credentials path. Cheap, and it would catch the day someone adds one.                                  |
+| **Nothing writes `authorized_keys`, and no SSH server is opened.** | **True by absence**, same as above, and the same caveat: no `authorized_keys`, `ssh-keygen` or equivalent string exists in any `.mjs` in this repository. The design reason is real (every machine makes only outbound connections, and Windows ships no `sshd`), but the design reason is not the check.                                                                                                                                                                                                                    | Same as above: a source-level scan asserted by a test, plus the existing `test/outbound-only.test.mjs`, which already shows the machine side opens no listening TCP port.                       |
+| **There is no approval prompt in the loop.**                       | **True by design, and nameable.** The plugin contains no permission-gating code at all — the word does not appear in it outside a comment listing what the tool dispatcher does _not_ implement — so a command that reaches the agent runs, and the allow-list is the only gate. Note that this is deliberately **not** the DSH permission prompt: if the dispatching session's own policy asks you to approve a call, that prompt is the harness's and is unaffected.                                                       | Hard to assert negatively; a claims check that the plugin registers no `approval`/`permission` request surface is the nearest honest form.                                                      |
+
+None of the four becomes a guarantee by being written down. If you need one of them to be load-bearing
+for a workload, treat it as **unverified** until a test in `test/claims.test.mjs` carries it.
+
 ### What it touches on your machine
 
 Declared here and machine-readably in `package.json`'s `disclosure`, because installing a plugin runs