@twinsearth/w2m-dsh-plugin 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.2] — 2026-10-13
+
+The release that stops a broken *relay* from being reported as an out-of-date *peer*, and stops a
+relay that has quietly stopped recording from looking healthy.
+
+The incident, measured on this fleet: every machine at v0.6.1 held a valid device key and announced
+it, `peers_known` stayed `0` on all of them, no handshake was ever armed, and every direct channel
+came back `P2P_CRYPTO_PLAINTEXT_PEER` — documented as *"the peer never learned a key (an older
+build)"*. Both ends were the same build, on the same host. The component that was actually behind was
+the relay: it started `2026-10-10T18:01:40Z`, and v0.6.0 and v0.6.1 shipped on `2026-10-11`. It had
+never heard of `static_key`, so it accepted every announcement, dropped the field, and served entries
+without it. The reason code blamed the one component that was up to date.
+
+### Added
+
+* **`encryption.relay_serves_keys`** — whether the relay keeps the key this machine announces. `null`
+  until an announcement proves it either way; `false` when the relay dropped what was sent; `null` for
+  a node with no key of its own, because such a node never asked and must not conclude "no". Detected
+  from this node's **own** announcement — it POSTs a key and the relay echoes the entry it stored — so
+  it needs no relay cooperation, no version negotiation and no capability call. That is what makes it
+  work against the relay that is actually deployed, which is the whole point.
+* **`P2P_CRYPTO_RELAY_NO_KEYS`** — a new reason, used when a peer announced, this machine holds a key
+  of its own, no key came back for that peer, and this node has already proved the relay drops keys.
+* **`/healthz` reports durability**: top-level `degraded` and `degraded_reason`, plus `degraded`,
+  `degraded_since`, `last_append_error` and `append_failures` inside `persistence`. `ok` deliberately
+  stays `true`: the relay still serves the fleet, and flipping it would turn a recording problem into
+  an outage. Persistence disabled is not degraded — there is nothing that can fail.
+
+### Fixed
+
+* **The reason a direct channel is plaintext now names the real cause.** `punch()` computed it as
+  `request === null ? PLAINTEXT_PEER : NO_KEY`, and `dial()` sends no crypto request in three
+  situations that are all *local* — this machine has no device key, it holds no key for that peer, or
+  it is dialling itself. Every one of them was reported as the peer being old. The code already
+  disagreed with itself about this: `dial()`'s own comment claims the reason "then says
+  `P2P_CRYPTO_NO_KEY`". The reason is now decided where it is known and travels with the call;
+  `PLAINTEXT_PEER` keeps its real meaning and keeps firing for the one case that is genuinely about
+  the peer — it publishes no key, so there is nothing to encrypt with.
+* **`dial()` learns the peer key it was throwing away.** The peer's `static_key` has ridden in the
+  relay's `/v1/peer/{id}` record since v0.6.0, and `dial()` was fetching that very record for the
+  candidate list and discarding the key. A dispatcher that reported `PLAINTEXT_PEER` against a
+  same-version peer could have encrypted; it had an empty store and never asked. Reporting alone would
+  have been a better-worded lie.
+* **`device.key` is loaded from beside `device.json`, not from `--state`.** The plugin followed the
+  documented rule; the agent did not, on the stated grounds that "`identity.mjs` puts `device.json`
+  when the agent is run with `--state`" — which is false. `device.json` is fixed at
+  `<DSH_HOME>/xclient/device.json` by the identity contract and `--state` does not move it. Measured
+  consequence on one machine running both halves: two different keypairs under one `machine_id`, both
+  announcing to the one `/v1/peer/{machine_id}` slot, the relay's record alternating between the two
+  nodes' ports every ~8s, each announcement overwriting the other. A dispatcher reading that record
+  learned one node's key or the other's, never reliably the key of the node it was about to dial. The
+  fix takes the path the caller actually resolved — `bin/w2m-localside.mjs` already had it in
+  `identityPath` and simply did not pass it down — and deliberately does **not** re-resolve `DSH_HOME`
+  inside the agent, which would make a test or an embedder read and *create* a key in the real user's
+  home.
+* **A key already generated in `--state` is adopted, not abandoned.** `DeviceKey.load` warns that
+  "silently generating a replacement key would make every peer that knows the old one refuse this
+  machine", so the canonical location may create and a legacy file may only be adopted. An adopted key
+  is logged, because the public key is what a peer authenticates this machine by.
+* **A relay that serves without recording now says so.** On a full disk the relay answered every
+  request normally and appended nothing; the only trace was one warning per failed append, and this
+  fleet's relay had reached **22 byte-identical `ENOSPC` entries**, so the signal was buried in its own
+  repetition. Identical warnings are now counted rather than repeated, and durability is a first-class
+  state: entered by the first failed append, cleared by the next success. `append_failures` is
+  cumulative and deliberately never reset — "how much was lost" is the first question after a disk
+  fills, and a counter that returns to zero cannot answer it.
+* **A patch override that asserts the wrong `name:` now has a documented failure mode.** In a patch,
+  `name` is an *assertion* about the entry being targeted, not a rename, and the Loader drops the whole
+  patch on mismatch — leaving the plugin mounted on the bundle's empty defaults: eight tools present,
+  `w2m_status` reading `paired: false` and a null `rabbitUrl`, with the profile's settings sitting in
+  the file the whole time, unread. README now carries the hazard where the config block is copied,
+  `TROUBLESHOOTING.md` §2 names it as the third mechanism for "the patch lost my configuration" (and
+  the only one where the file looks intact), and §17 documents the reason codes this release adds and
+  corrects.
+* **`test/agent.test.mjs`'s sub-path CLI test no longer depends on the host's `PATH`.** This is what
+  made v0.6.1's own pre-flight **RED** — "do not bump" — on a machine where node exists only as DSH's
+  bundled runtime. `runCli` points the child's `DSH_HOME` at a scratch directory, so
+  `bundledBinDirs()` correctly finds no bundled runtime there; the command under test is built from
+  `process.execPath` while the allow-list entry is the bare name `node -e`; and with no bundled runtime
+  and no `node` on `PATH`, that name does not resolve, so the absolute path is refused with
+  `COMMAND_EXECUTABLE_PATH_MISMATCH` — the allow-list behaving exactly as documented. CI runs
+  `actions/setup-node`, which is why it was green there. The child now gets the executing node's own
+  directory on its `PATH`, which restores the identity the check exists to confirm rather than
+  weakening it: a mismatched absolute path is still refused with the same code.
+
+### Changed
+
+* `scripts/preflight.mjs` reports **11 pass, 0 fail, 1 unverifiable — GREEN, cleared to bump** on a
+  clean macOS checkout. Before this release the same gate reported "10 pass, 1 fail — RED".
+* The local suite reads **557 tests, 555 pass, 0 fail**.
+
 ## [0.6.1] — 2026-10-11
 
 ### Fixed

package/README.md

@@ -283,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`.
 

package/TROUBLESHOOTING.md

@@ -104,6 +104,29 @@ YAML, and the loader fails on the file as a whole — one bad row takes the enti
 just this plugin. Both cases are why this file is treated as hand-edited state, not as a generated
 artifact.
 
+A third mechanism, and the only one where the file looks *perfect* and is still being ignored: **a
+`name:` line in your override is an assertion, not a rename.** The bundle inserts this row itself with
+the package name, so your row targets it by `id` and a `name:` only has to agree. When it does not, the
+Loader drops the whole patch:
+
+```
+patch: name mismatch for "w2m" (expected "@twinsearth/w2m-dsh-plugin",
+       got "@twinsearth/w2m-dsh-plugin/tools"), skipping
+```
+
+Every value in that block is then absent — not overridden with something else, simply never applied —
+and the plugin mounts on the bundle's empty defaults. This is the failure mode where `cat` shows your
+settings sitting right there and `w2m_status` reports `paired: false` anyway.
+
+It is also the one that arrives **on upgrade** rather than on a crash: the entry's expected name moved
+from the `/tools` subpath to the package root in v0.5.4 (`cordis.patch.yml`'s header records why), and
+every override still asserting the old subpath stopped being applied the moment the profile was
+upgraded — with no edit to the profile and no error. If you keep a `name:`, an upgrade can silently
+disconnect you from your own configuration.
+
+**The fix is to delete the line.** `id: w2m` already identifies the row; asserting the name buys
+nothing and turns any future rename by the bundle into a silent misconfiguration.
+
 **Decision procedure.**
 
 ```bash
@@ -113,6 +136,9 @@ cat "$DSH_HOME/profiles/<profile>/cordis.patch.yml"
 
 - First characters are `[]` → the placeholder case; see the safe-edit rule below.
 - The `w2m` row is absent → it was dropped; re-add it (§2 fix 3).
+- The row carries a `name:` line → **delete that line first**, then re-check the values. Everything
+  else in this section assumes the patch is being applied at all, and a mismatched `name:` means it
+  is not.
 - The row is present but values are empty → it was reset; re-apply them.
 
 ```bash
@@ -827,6 +853,9 @@ elsewhere. `<kind>` is the sub-directory a program is started with: `localside`
 | `LEASE_EXPIRED`                                                           | task status                                                                | §4/§5 — the executor stopped renewing its lease                                                                                                                                                                                                                  |
 | `P2P_UNAVAILABLE`                                                         | `refused` result in `p2pMode: direct`                                      | §6 — the punch did not land and direct-only refuses the fallback                                                                                                                                                                                                 |
 | `P2P_PUNCH_TIMEOUT`                                                       | reported transport reason                                                  | §6, §13                                                                                                                                                                                                                                                          |
+| `P2P_CRYPTO_RELAY_NO_KEYS`                                                | `p2p.encryption.reason` on a direct channel that came back plaintext       | **the relay, not the peer.** This machine holds a key and the peer announced one, yet the relay served no key for it — this node has proved, from its own announcement, that the relay drops the `static_key` field. Almost always a relay older than v0.6.0: upgrade and restart it. `w2m_status` shows the same fact as `encryption.relay_serves_keys: false`. Replaced a misleading `PLAINTEXT_PEER` in v0.6.2 |
+| `P2P_CRYPTO_PLAINTEXT_PEER`                                               | `p2p.encryption.reason`                                                    | the peer genuinely publishes no key, so there is nothing to encrypt with. Check the peer's version before assuming it is merely misconfigured — and note that this code used to be reported for local causes too, which is why `P2P_CRYPTO_NO_KEY` and `..._RELAY_NO_KEYS` now exist |
+| `P2P_CRYPTO_NO_KEY`                                                       | `p2p.encryption.reason`                                                    | **this** machine's gap, not the peer's: no device key of its own, no key for that peer, or a self-dial (a machine keeps no key for itself). `device.key` lives beside `device.json`, not in `--state` |
 | `RUNNER_THREW`                                                            | the **auto-updater**'s spawn result (`w2m_update`), not an envelope status | the updater's own runner threw before or instead of running: read the message beside it, and check the install path. An envelope never carries this — `src/agent/exec.mjs` defines only `ok`, `nonzero_exit`, `timeout`, `crashed`, `refused` and `unverifiable` |
 | `SIGNATURE_*` (`MISMATCH`, `EXPIRED`, `REPLAY`, `REQUIRED`, `INCOMPLETE`) | relay, when signing is configured                                          | the signing secret is rotated or the two sides disagree; `SIGNING_NOT_CONFIGURED` means signing is off                                                                                                                                                           |
 

package/bin/w2m-localside.mjs

@@ -230,6 +230,11 @@ async function main() {
       project,
       stateDir,
       identity,
+      // v0.6.2: the device key belongs beside the `device.json` this process actually loaded, and this
+      // is the only place that knows where that is. Without it the agent fell back to `--state`, a
+      // different directory — so on one machine the plugin and the agent each minted their own keypair
+      // and then overwrote each other's announcement under the one shared machine_id.
+      identityPath,
       caps,
       platform,
       allowedCommands,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/agent/agent.mjs

@@ -23,8 +23,8 @@
 
 import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
-import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -49,7 +49,7 @@ import {
 } from './git.mjs';
 import { createSpool } from './spool.mjs';
 import { matchAllowedCommand, parseAllowedCommands } from './allowed-commands.mjs';
-import { CRYPTO_REASON, DeviceKey, PeerKeyStore } from './crypto.mjs';
+import { CRYPTO_REASON, DEVICE_KEY_FILE, DeviceKey, PeerKeyStore } from './crypto.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
 import { punchSession, reverseDialSession } from './p2p.mjs';
 import { createSigner } from '../signing.mjs';
@@ -988,6 +988,7 @@ export function createAgent(options) {
     project,
     stateDir,
     identity,
+    identityPath = null,
     caps,
     platform,
     once = false,
@@ -1093,11 +1094,17 @@ export function createAgent(options) {
   // *dispatcher* publishes in an offer, and "which key will this machine present" must not depend on
   // whether a particular code path happened to have run yet. `loadOrCreate` is the documented rule
   // ("generated the first time a machine pairs"), and a failure is never fatal — see `deviceKeyError`.
-  const deviceKeyOutcome = loadDeviceKey(options.deviceKey ?? null, stateDir, identity.machine_id);
+  const deviceKeyOutcome = loadDeviceKey(options.deviceKey ?? null, stateDir, identity.machine_id, identityPath);
   /** @type {object|null} This machine's static keypair, or null when there is none. */
   const deviceKey = deviceKeyOutcome.key;
   /** @type {string|null} Why there is no key, when there is none. Reported, never thrown. */
   const deviceKeyError = deviceKeyOutcome.error;
+  /**
+   * A key adopted from the pre-v0.6.2 location (`--state/device.key`). Reported once at startup,
+   * because a machine whose key moved is a machine whose public key a peer may have learned under the
+   * old file — silence here would make "my peers stopped talking to me" have no visible cause.
+   */
+  const deviceKeyMigratedFrom = deviceKeyOutcome.migratedFrom ?? null;
   /**
    * Peer static keys, learned from offers.
    *
@@ -1359,6 +1366,15 @@ export function createAgent(options) {
       log(result.ok ? 'info' : 'warn', `p2p ${p2pMode}: ${result.ok ? 'node started' : 'node did not start'}`, {
         error: result.error ?? null,
       });
+      // v0.6.2: a key adopted from the pre-fix location. Said out loud because the public key is what
+      // a peer authenticates this machine by, and a silent move would look like a peer going deaf.
+      if (deviceKeyMigratedFrom !== null) {
+        log('warn', 'p2p: adopting a device key from the old --state location', {
+          from: deviceKeyMigratedFrom,
+          public_key: deviceKey === null ? null : deviceKey.publicKeyBase64,
+          note: 'v0.6.2 moved device.key beside device.json; delete the old file once every peer has seen the new announcement',
+        });
+      }
       refreshP2PStatus();
       return result;
     })();
@@ -4067,32 +4083,88 @@ export function createAgent(options) {
  * be read so an operator can fix it. Refusing to start an agent because a *security upgrade* could not
  * complete is exactly the fleet-losing failure `docs/P2P-CRYPTO.md` §4 forbids.
  *
- * The key lives beside the spool and `agent-state.json` (the `--state` directory), which is where
- * `identity.mjs` puts `device.json` when the agent is run with `--state`. A caller that injected a
- * `DeviceKey` gets that one, which is the test seam and the way a caller supplies a key from
- * somewhere else entirely.
+ * WHERE THE KEY LIVES, AND THE BUG THAT CAME FROM GETTING IT WRONG (v0.6.2)
+ *
+ * `DeviceKey.load` documents the rule as "`device.key` **beside `device.json`**", and this function
+ * used to break it: it loaded from the `--state` directory, justified by a comment claiming that
+ * `identity.mjs` puts `device.json` there "when the agent is run with `--state`". That claim is false.
+ * `device.json` is fixed at `<DSH_HOME>/xclient/device.json` by the identity contract and `--state`
+ * does not move it — which is why an agent run as `--state ~/.dsh/xclient/localside-mac` had its
+ * identity one directory *above* its key.
+ *
+ * The measured consequence, on one machine running both halves of W2M: the plugin (which loads the key
+ * correctly, from `dirname(device.json)`) and the agent each generated a *different* pair, and both
+ * announced to the one `/v1/peer/{machine_id}` slot — the relay's record alternated between the two
+ * nodes' ports every few seconds, and the `static_key` a dispatcher read was one node's or the other's.
+ * A dispatcher that learns the wrong key cannot arm a handshake, so every direct channel came back
+ * `P2P_CRYPTO_PLAINTEXT_PEER` — reported as "the peer is an older build" when both ends were the same
+ * build on the same host.
  *
- * @param {object|null} injected A `DeviceKey`, or null to load or generate one from the state dir.
- * @param {string} stateDir
+ * MIGRATION. `DeviceKey.load` warns that "silently generating a replacement key would make every peer
+ * that knows the old one refuse this machine". So a key already generated in the old location is
+ * adopted rather than abandoned: canonical first, then a copy forward from `--state`, then generate.
+ *
+ * @param {object|null} injected A `DeviceKey`, or null to load or generate one.
+ * @param {string} stateDir The `--state` directory; the key's home only when `deviceFile` is absent.
  * @param {string} machineId
- * @returns {{key: object|null, error: string|null}}
+ * @param {string|null} [deviceFile] Absolute path of the `device.json` this agent loaded. The key
+ *   belongs beside it; pass the path the caller resolved rather than re-resolving `DSH_HOME` here.
+ * @returns {{key: object|null, error: string|null, migratedFrom: string|null}}
  */
-function loadDeviceKey(injected, stateDir, machineId) {
+function loadDeviceKey(injected, stateDir, machineId, deviceFile = undefined) {
   if (injected !== null && injected !== undefined) {
     if (typeof injected.sharedSecret !== 'function' || typeof injected.publicKeyBase64 !== 'string') {
-      return { key: null, error: 'P2P_CRYPTO_NO_KEY: the injected deviceKey is not a DeviceKey' };
+      return { key: null, error: 'P2P_CRYPTO_NO_KEY: the injected deviceKey is not a DeviceKey', migratedFrom: null };
     }
-    return { key: injected, error: null };
+    return { key: injected, error: null, migratedFrom: null };
   }
-  try {
-    const loaded = DeviceKey.load({ dir: stateDir, machineId });
-    return { key: loaded.key, error: null };
-  } catch (error) {
+
+  // Beside `device.json` — the documented rule. `identityPath` is the path the caller actually
+  // loaded, never a fresh global resolution: resolving `DSH_HOME` here would make a test (or any
+  // caller with an injected identity) read and *create* a key in the real user's home.
+  let canonicalDir = null;
+  if (typeof deviceFile === 'string' && deviceFile !== '') canonicalDir = dirname(deviceFile);
+
+  const legacyPath = join(stateDir, DEVICE_KEY_FILE);
+
+  /**
+   * Candidates in order. `mayCreate` is the whole subtlety: only a location that is *the* documented
+   * home may mint a key. A legacy directory is consulted to adopt a key that is already there, never
+   * to create one — `DeviceKey.load` warns that generating a replacement "would make every peer that
+   * knows the old one refuse this machine", so an upgrade must not silently change this machine's
+   * public key.
+   *
+   * With no `identityPath` the caller injected its own identity and there is no canonical home, so
+   * `--state` keeps the pre-v0.6.2 behaviour of being able to create. That is what stops a test or an
+   * embedder from reading and writing the real user's `~/.dsh/xclient`.
+   */
+  const candidates =
+    canonicalDir === null
+      ? [{ dir: stateDir, mayCreate: true, from: null }]
+      : [
+        { dir: canonicalDir, mayCreate: true, from: null },
+        ...(existsSync(legacyPath) ? [{ dir: stateDir, mayCreate: false, from: legacyPath }] : []),
+      ];
+
+  let lastError = null;
+  for (const candidate of candidates) {
+    try {
+      const loaded = DeviceKey.load({ dir: candidate.dir, machineId });
+      if (candidate.mayCreate === false && loaded.created) continue;
+      return { key: loaded.key, error: null, migratedFrom: candidate.from };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  if (lastError !== null) {
     return {
       key: null,
-      error: `P2P_CRYPTO_KEY_UNREADABLE: ${error instanceof Error ? error.message : String(error)}`,
+      error: `P2P_CRYPTO_KEY_UNREADABLE: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+      migratedFrom: null,
     };
   }
+  return { key: null, error: null, migratedFrom: null };
 }
 
 /**

package/src/agent/crypto.mjs

@@ -209,6 +209,20 @@ export const CRYPTO_REASON = Object.freeze({
   MALFORMED: 'P2P_CRYPTO_MALFORMED',
   /** The peer never learned a key (an older build), so a direct channel with it is plaintext. */
   PLAINTEXT_PEER: 'P2P_CRYPTO_PLAINTEXT_PEER',
+  /**
+   * The relay is not serving peer keys, so no handshake can be armed by anyone (v0.6.2).
+   *
+   * Distinct from {@link PLAINTEXT_PEER} on purpose, and the distinction is the whole reason this code
+   * exists. A relay older than v0.6.0 has never heard of `static_key`: it accepts an announcement,
+   * silently drops the field, and serves an entry without it. Every peer then looks exactly like a
+   * machine that has no key — which is how a stale *relay* came to be reported for hours as "the peer
+   * is an older build", pointing the investigation at the one component that was up to date.
+   *
+   * Detected from this node's own announcement: we POST a key, so the entry the relay echoes back says
+   * whether it kept it. No relay cooperation and no version negotiation required, which is what makes
+   * it work against the relay that is actually deployed.
+   */
+  RELAY_NO_KEYS: 'P2P_CRYPTO_RELAY_NO_KEYS',
   /**
    * A `REFUSE` datagram was **dropped**, not honoured: it named a session this punch did not agree.
    *

package/src/agent/p2p-node.mjs

@@ -509,6 +509,14 @@ export class P2PNode extends EventEmitter {
     this.deviceKey = deviceKey ?? null;
     /** @type {PeerKeyStore} Peer static keys, learned from offers and from the relay. */
     this.peerKeys = peerKeys instanceof PeerKeyStore ? peerKeys : new PeerKeyStore();
+    /**
+     * Does the relay keep the static key this machine announces? `null` until an announcement proves
+     * it either way. See the note in `performAnnounce` — a relay older than v0.6.0 drops the field
+     * silently, and that is otherwise indistinguishable from every peer having no key.
+     *
+     * @type {boolean|null}
+     */
+    this.relayServesKeys = null;
     /** @type {object|null} `CryptoSession` overrides; null means the documented thresholds. */
     this.cryptoTuning = cryptoTuning ?? null;
     /** @type {NonceCache} Replay tracking for inbound handshakes. Outlives one `accept()`. */
@@ -654,6 +662,12 @@ export class P2PNode extends EventEmitter {
         enabled: this.deviceKey !== null,
         public_key: this.deviceKey === null ? null : (this.deviceKey.publicKeyBase64 ?? null),
         peers_known: this.peerKeys.size,
+        /**
+         * `null` until this node's own announcement proves it either way; `false` means the relay
+         * dropped the key we sent, which is the fact that explains an otherwise mysterious
+         * `peers_known: 0` on a fleet whose machines all hold keys (v0.6.2).
+         */
+        relay_serves_keys: this.relayServesKeys,
         handshakes: this.cryptoCounts.handshakes,
         encrypted_channels: this.cryptoCounts.encrypted_channels,
         plaintext_channels: this.cryptoCounts.plaintext_channels,
@@ -951,6 +965,28 @@ export class P2PNode extends EventEmitter {
     const posted = response?.ok === true;
     if (!posted && postError === null) postError = describeAnnounceFailure(response);
 
+    /**
+     * Does the relay keep the static key we send it? (v0.6.2)
+     *
+     * This is knowable from our own announcement, and only from our own announcement: we POST
+     * `static_key`, and the relay echoes the entry it stored. A relay that predates v0.6.0 has never
+     * heard of the field, drops it silently, and echoes an entry without it — indistinguishable, from
+     * any peer's point of view, from a machine that has no key at all.
+     *
+     * That ambiguity is what turned a stale relay into hours of "the peer is an older build". The
+     * deployed relay in this fleet started 2026-10-10T18:01:40Z; v0.6.0 and v0.6.1 shipped on
+     * 2026-10-11. Every announcement carried a valid key, every stored entry lost it, no dispatcher
+     * could ever arm a handshake, and `PLAINTEXT_PEER` blamed the one component that was up to date.
+     *
+     * Recorded rather than reported here: one announce proves the relay's behaviour, and `dial()`
+     * turns it into a named reason only where it explains something. `null` means "not yet known" —
+     * a machine with no key of its own cannot ask the question at all, and must not conclude "no".
+     */
+    if (posted && this.deviceKey !== null) {
+      const echoed = response?.json?.static_key;
+      this.relayServesKeys = typeof echoed === 'string' && echoed !== '' ? true : false;
+    }
+
     // A POST failure is the headline when there is one: the announcement is not live at
     // all. Otherwise a discovery failure is what makes this announcement incomplete.
     const error = !posted ? postError : discoveryOk ? null : discoveryError;
@@ -1142,6 +1178,9 @@ export class P2PNode extends EventEmitter {
     const fromOffer = Array.isArray(options.candidates) && options.candidates.length > 0;
 
     let announced = [];
+    // v0.6.2: the peer's static key as published in the same record the candidates came from. Lifted
+    // out of the lookup block because `lookup` is scoped to it, and the key is needed further down.
+    let announcedStaticKey = null;
     if (fromOffer) {
       announced = options.candidates;
     } else {
@@ -1166,6 +1205,8 @@ export class P2PNode extends EventEmitter {
         return fail(`P2P_LOOKUP_FAILED: ${describeLookupFailure(lookup)}`);
       }
       announced = Array.isArray(lookup.json?.peer?.candidates) ? lookup.json.peer.candidates : [];
+      const key = lookup.json?.peer?.static_key;
+      if (typeof key === 'string' && key !== '') announcedStaticKey = key;
     }
 
     const remote = [];
@@ -1176,6 +1217,52 @@ export class P2PNode extends EventEmitter {
       remote.push(usable);
       if (remote.length >= this.tuning.maxCandidates) break;
     }
+
+    /**
+     * The peer's static key, learned from its own announcement when this machine does not hold one.
+     *
+     * v0.6.2. This is the other half of the plaintext-downgrade fix, and without it the reason code
+     * alone would have been a better-worded lie: the dispatcher that reported
+     * `P2P_CRYPTO_PLAINTEXT_PEER` against a same-version peer *could* have encrypted, it simply had an
+     * empty key store and never asked. The relay has carried the peer's `static_key` in this very
+     * record since v0.6.0 (`relay/peers.mjs`), the plugin already read it, and the agent's own `dial()`
+     * was fetching the same record for the candidate list and then throwing the key away.
+     *
+     * Adopting it here is what makes the local/remote distinction possible as well as useful: a peer
+     * that publishes no key is genuinely an older build and `PLAINTEXT_PEER` is honest; a peer that
+     * publishes one we had not learned is *our* gap, and after this it is not a gap at all.
+     */
+    let peerKey = this.peerKeys.get(machineId);
+    if (peerKey === null && announcedStaticKey !== null) {
+      this.peerKeys.set(machineId, announcedStaticKey, 'relay');
+      peerKey = announcedStaticKey;
+    }
+
+    /**
+     * Why this dial cannot be encrypted, when it cannot. Named here because this is where the reason
+     * is actually known: `punch()` sees only "no crypto request" and used to guess, blaming the peer
+     * for what is usually a local condition.
+     *
+     * `null` means a handshake will be armed. `PLAINTEXT_PEER` is reserved for the one case that is
+     * about the peer -- it publishes no key, so there is nothing to encrypt with. Everything else is
+     * `NO_KEY`: this machine has no device key of its own, holds no key for that peer, or is dialling
+     * itself (a machine keeps no key for itself, so its own `respondHandshake` would refuse it with
+     * `P2P_CRYPTO_UNKNOWN_PEER`).
+     */
+    const cryptoBlockedReason =
+      this.deviceKey === null
+        ? CRYPTO_REASON.NO_KEY
+        : machineId === this.machineId
+          ? CRYPTO_REASON.NO_KEY
+          : peerKey === null
+            ? this.relayServesKeys === false
+              // The peer announced, we hold a key of our own, and no key came back for it. If this
+              // node has already proved the relay drops keys, the relay is the cause and saying
+              // otherwise sends the operator to the wrong machine.
+              ? CRYPTO_REASON.RELAY_NO_KEYS
+              : CRYPTO_REASON.PLAINTEXT_PEER
+            : null;
+
     if (remote.length === 0) {
       // `peersAnnounced` still counts what was offered, not what survived validation: a caller
       // reading "the punch failed" needs to see that there *was* a list, and that every entry in it
@@ -1210,17 +1297,19 @@ export class P2PNode extends EventEmitter {
         // sends would be refused by its own `respondHandshake` (`P2P_CRYPTO_UNKNOWN_PEER`) and the
         // task it dispatched to itself would be lost. `machineId !== this.machineId` is what makes a
         // self-lease survive a security upgrade, which is the same rule as every other fallback here.
-        ...(this.deviceKey === null ||
-        machineId === this.machineId ||
-        this.peerKeys.get(machineId) === null
-          ? {}
-          : {
+        ...(cryptoBlockedReason === null && peerKey !== null
+          ? {
             crypto: {
               deviceKey: this.deviceKey,
-              peerKey: this.peerKeys.get(machineId),
+              peerKey,
               peerMachineId: machineId,
             },
-          }),
+          }
+          : {}),
+        // v0.6.2: the reason travels with the call instead of being guessed downstream. `punch()`
+        // cannot tell a local "we hold no key" from the peer being an older build, and it used to
+        // report the peer-blaming one for both.
+        cryptoBlockedReason,
         ...(this.cryptoTuning === null ? {} : { cryptoTuning: this.cryptoTuning }),
       });
     } catch (error) {

package/src/agent/p2p.mjs

@@ -558,13 +558,25 @@ export async function punch(options) {
    * the refusal MEDIUM-4 was about.
    */
   const refusalKey = handshake === null ? null : handshake.refusalMacKey;
-  // Why there is no handshake, when there is none. `null` means one is in flight.
-  const noCryptoReason =
-    handshake !== null
-      ? null
-      : request === null
-        ? CRYPTO_REASON.PLAINTEXT_PEER
-        : CRYPTO_REASON.NO_KEY;
+  /**
+   * Why there is no handshake, when there is none. `null` means one is in flight.
+   *
+   * v0.6.2: `request === null` is *this end's* decision, not a fact about the peer. `P2PNode.dial`
+   * sends no crypto request in three situations and every one of them is local — this machine has no
+   * device key, it holds no key for that peer, or it is dialling itself (a machine keeps no key for
+   * itself, so its own `respondHandshake` would refuse it with `P2P_CRYPTO_UNKNOWN_PEER`).
+   *
+   * It used to report `PLAINTEXT_PEER` here, documented as "the peer never learned a key (an older
+   * build)". Measured consequence: a dispatcher with an empty peer-key store reported every direct
+   * channel as the peer being out of date, when both ends were the same build on the same host — an
+   * encryption downgrade recorded as normal compatibility. `dial()`'s own comment has always claimed
+   * the reason would be `NO_KEY`; this is that behaviour, and it is what the objective asks for: a
+   * punch that did not encrypt says whether the cause was ours or theirs.
+   *
+   * `PLAINTEXT_PEER` keeps its real meaning and its real sites: a handshake *was* armed and the peer
+   * answered in the clear, which is the only case where the peer is genuinely the reason.
+   */
+  const noCryptoReason = handshake !== null ? null : (options.cryptoBlockedReason ?? CRYPTO_REASON.NO_KEY);
   /** Whether this punch is trying to encrypt at all. */
   const wantCrypto = handshake !== null;
 

package/src/plugin/tools.mjs

@@ -177,7 +177,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.6.1';
+const PLUGIN_VERSION = '0.6.2';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;

package/src/relay/persistence.mjs

@@ -36,6 +36,15 @@ export class Persistence {
     this._now = now;
     /** @type {{file:string, message:string, line?:number}[]} */
     this.warnings = [];
+    /**
+     * Durability state (v0.6.2): whether the ledger is actually being written.
+     *
+     * `appendFailures` is cumulative and never reset, so "how much was lost" stays answerable after a
+     * disk fills and is freed again. `degradedSinceMs` is the live condition.
+     */
+    this.appendFailures = 0;
+    this.lastAppendError = null;
+    this.degradedSinceMs = null;
     this.devicesCorrupt = false;
     this.devicesMissing = true;
     this.revivedDevices = 0;
@@ -50,8 +59,61 @@ export class Persistence {
   get operatorTokenFile() { return this.enabled ? path.join(this.dir, OPERATOR_TOKEN_FILE) : null; }
 
   warn(file, message, extra = {}) {
-    this.warnings.push({ file, message, ...extra });
-    return this.warnings[this.warnings.length - 1];
+    // Deduplicated (v0.6.2). A full disk fails *every* append, and appending an identical entry each
+    // time buried the signal in its own repetition: this fleet's relay reached 22 byte-identical
+    // "ENOSPC" warnings and no way to ask "is this relay still recording?" without counting them. One
+    // entry that counts is what an operator can act on.
+    const existing = this.warnings.find((entry) => entry.file === file && entry.message === message);
+    if (existing !== undefined) {
+      existing.count = (existing.count ?? 1) + 1;
+      existing.last_at = rfc3339(this._now());
+      return existing;
+    }
+    const entry = { file, message, count: 1, ...extra };
+    this.warnings.push(entry);
+    return entry;
+  }
+
+  /**
+   * One ledger append failed: the relay is still serving, but it is no longer recording (v0.6.2).
+   *
+   * This is a first-class state rather than a log line because the ledger *is* the relay's durability
+   * story. Every machine's result, every lease, everything a later question would be answered from —
+   * none of it survives a restart once appends stop landing. A relay in this state accepts work
+   * exactly as before, which is precisely why it has to say so out loud.
+   *
+   * @param {string} message
+   * @returns {false}
+   */
+  noteAppendFailure(message) {
+    this.appendFailures += 1;
+    this.lastAppendError = message;
+    if (this.degradedSinceMs === null) this.degradedSinceMs = this._now();
+    this.warn(LEDGER_FILE, `append failed: ${message}`);
+    return false;
+  }
+
+  /**
+   * The ledger is being written again.
+   *
+   * The history is kept — `append_failures` is not reset — because "how much was lost" is the first
+   * question after a disk fills, and a counter that silently returns to zero cannot answer it.
+   *
+   * @returns {true}
+   */
+  noteAppendSuccess() {
+    if (this.degradedSinceMs !== null) {
+      const forMs = Math.max(0, this._now() - this.degradedSinceMs);
+      this.degradedSinceMs = null;
+      this.lastAppendError = null;
+      this.warn(LEDGER_FILE, `append recovered after ${this.appendFailures} failure(s) over ${forMs}ms`);
+    }
+    return true;
+  }
+
+  /** Is the relay serving without recording? @returns {boolean} */
+  get degraded() {
+    return this.degradedSinceMs !== null;
   }
 
   ensureDir() {
@@ -199,6 +261,14 @@ export class Persistence {
       devices_missing: this.devicesMissing,
       ledger_lines_read: this.ledgerLinesRead,
       ledger_lines_skipped: this.ledgerLinesSkipped,
+      /**
+       * v0.6.2. `degraded: true` means the relay is answering requests while failing to record them,
+       * which is the one relay failure that looks exactly like health from the outside.
+       */
+      degraded: this.degraded,
+      degraded_since: this.degradedSinceMs === null ? null : rfc3339(this.degradedSinceMs),
+      last_append_error: this.lastAppendError,
+      append_failures: this.appendFailures,
       warnings: this.warnings.map((w) => ({ ...w })),
     };
   }

package/src/relay/server.mjs

@@ -902,6 +902,16 @@ export class RelayServer {
       // so this drops to 0 by itself when nobody is refreshing.
       ...this.peers.stats(),
       ok: true,
+      /**
+       * v0.6.2: hoisted out of `persistence` so it cannot be missed by a reader that only looks at
+       * the top level. `degraded: true` means this relay is answering requests while failing to record
+       * them -- the one relay failure that presents as health. `ok` deliberately stays true: the relay
+       * still serves the fleet, and flipping it would turn a recording problem into an outage.
+       */
+      degraded: this.persistence.enabled && this.persistence.degraded,
+      degraded_reason: this.persistence.degraded
+        ? `ledger appends are failing (${this.persistence.lastAppendError ?? 'unknown error'}); results are served but not durably recorded`
+        : null,
       protocol_version: PROTOCOL_VERSION,
       rabbit_time: this.state.nowIso(),
       uptime_ms: this.state.nowMs() - this._startedAtMs,

package/src/relay/state.mjs

@@ -470,9 +470,16 @@ export class RabbitState {
   _ledger(entry) {
     if (this._restoring || !this._persist) return false;
     try {
-      return this._persist.append(entry);
+      const appended = this._persist.append(entry);
+      // v0.6.2: a successful append is what clears a degraded relay, so the outcome has to be
+      // reported back rather than assumed -- otherwise the state could only ever be entered.
+      if (appended) this._persist.noteAppendSuccess?.();
+      return appended;
     } catch (err) {
-      this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
+      // Recorded as a state, not merely as a line: this is the one relay failure that keeps serving,
+      // and so the one that is invisible from every other angle (v0.6.2).
+      if (typeof this._persist.noteAppendFailure === 'function') this._persist.noteAppendFailure(err.message);
+      else this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
       return false;
     }
   }