@twinsearth/w2m-dsh-plugin 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.20.0] — 2026-10-15
+
+**Version skew is refuted too, and the direct-path failure is now counted instead of read one at a time.**
+
+### Third hypothesis, third refutation
+
+The previous release established that this machine runs plugin **0.9.5** while the source tree is **0.19.0**,
+and that the failing `P2P_PUNCH_FAILED` is raised by the plugin process. The natural next step was to suspect a
+digest name that 0.9.5 used and later versions removed.
+
+**Measured, and refuted:** reading `crypto.mjs`, `p2p.mjs` and `p2p-node.mjs` **at tag `v0.9.5`** through the
+API shows the same two digest names the current tree uses — `blake2s256` and `sha256`. Then a search for
+**dynamic** algorithm arguments (`createHash(variable)`) across `src/` found **none**: every `createHash` and
+`createHmac` in this codebase is called with a string literal.
+
+**So there is no call in this codebase that can produce `Digest method not supported`.** Three hypotheses have
+now been measured and excluded — BLAKE2s, the wider primitive set, and version skew — and the cause remains
+**UNVERIFIED**. What is *not* in doubt is where it is raised: the plugin process on this machine, running
+0.9.5 while the source under study is 0.20.0.
+
+### What this release delivers instead of a fourth guess
+
+`p2pReasons()` and `classifyP2PReason()` turn the P2P reason strings into a **count**, because the finding that
+matters was invisible in every individual report: **twelve of twelve tasks travelled by relay, and no aggregate
+anywhere said so.**
+
+* `relay_only_share` is the fleet's avoidable latency as one number, and it is **`null`** for an empty
+  denominator — "no lease carried a p2p block" and "every lease failed" must not look alike.
+* an unrecognised code is counted as `OTHER` **with the raw code travelling with it**, so a new refusal name
+  is reported rather than swallowed.
+* a missing reason is distinguished from a present one, because *"no reason recorded" is not "no failure"*.
+
+### The version skew is still unresolved and still blocks diagnosis
+
+The installed plugin is **0.9.5**; the source is **0.20.0**. Until they match, every source-level conclusion
+about this machine's P2P behaviour is read from code that is not running. This needs a person: updating the
+plugin installs files into the DSH profile, which is outside what this session changes on its own.
+
+**7 new tests, 0 failures.**
+
 ## [0.19.0] — 2026-10-15
 
 **The plugin this machine runs is 0.9.5. The source tree is 0.18.0. Every source-level conclusion about the P2P failure was read from code that may not have run.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "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/fleet-scale.mjs

@@ -111,6 +111,78 @@ export function isFleetFailure(entry) {
   return classifyLease(entry).outcome === LEASE_OUTCOME.NO_RESULT;
 }
 
+/** Refusal codes the relay writes into `p2p.reason`, grouped by what they mean for a fleet. */
+export const P2P_FAILURE_KIND = Object.freeze({
+  NO_CANDIDATES: 'no candidate address was known, so no punch was attempted',
+  PUNCH_FAILED: 'a punch was attempted and did not complete',
+  PUNCH_TIMEOUT: 'a punch was attempted and nothing answered in time',
+  LEASE_NOT_RUNNABLE: 'the lease was not in a state to be handed the command',
+  REVERSE_DIAL: 'the reverse dial did not complete',
+  BLOCKED: 'a local condition stopped the direct path',
+  OTHER: 'a reason the table does not classify',
+});
+
+/**
+ * Classify one `p2p.reason` string.
+ *
+ * Reasons are prose with a machine-readable prefix (`P2P_NO_CANDIDATES: ...`), and reading them one at a time
+ * is how a fleet's direct-path problem stays invisible: the sample that prompted this had **twelve of twelve
+ * tasks on the relay** and no aggregate anywhere that said so.
+ *
+ * Returns `OTHER` for anything unrecognised rather than throwing or guessing, and the raw reason travels with
+ * the classification so a new code is reported rather than swallowed.
+ */
+export function classifyP2PReason(reason) {
+  if (typeof reason !== 'string' || reason === '') {
+    return { kind: null, code: null, detail: 'no reason recorded, which is not the same as no failure' };
+  }
+  const code = (reason.split(':')[0] ?? '').trim();
+  if (code === 'P2P_NO_CANDIDATES') return { kind: P2P_FAILURE_KIND.NO_CANDIDATES, code, detail: reason };
+  if (code === 'P2P_PUNCH_FAILED') return { kind: P2P_FAILURE_KIND.PUNCH_FAILED, code, detail: reason };
+  if (code === 'P2P_PUNCH_TIMEOUT') return { kind: P2P_FAILURE_KIND.PUNCH_TIMEOUT, code, detail: reason };
+  if (code === 'P2P_LEASE_NOT_RUNNABLE') return { kind: P2P_FAILURE_KIND.LEASE_NOT_RUNNABLE, code, detail: reason };
+  if (code.startsWith('P2P_REVERSE_DIAL')) return { kind: P2P_FAILURE_KIND.REVERSE_DIAL, code, detail: reason };
+  if (code.startsWith('P2P_UNAVAILABLE') || code.startsWith('P2P_CRYPTO')) return { kind: P2P_FAILURE_KIND.BLOCKED, code, detail: reason };
+  return { kind: P2P_FAILURE_KIND.OTHER, code, detail: reason };
+}
+
+/**
+ * Count why the direct path was not used, across a set of reports.
+ *
+ * The number worth acting on is `relay_only_share`: the fraction of leases that travelled by relay while a
+ * direct path was nominally configured. That is the fleet's avoidable latency, and it is invisible in any
+ * single report.
+ */
+export function p2pReasons(reports) {
+  const byCode = new Map();
+  let leasesWithP2P = 0;
+  let onRelay = 0;
+  let onDirect = 0;
+  for (const report of Array.isArray(reports) ? reports : []) {
+    for (const m of Array.isArray(report?.machines) ? report.machines : []) {
+      const p = m?.p2p;
+      if (p === null || p === undefined || typeof p !== 'object') continue;
+      leasesWithP2P += 1;
+      if (p.encrypted === true || (p.peer !== null && p.peer !== undefined)) onDirect += 1;
+      else onRelay += 1;
+      const c = classifyP2PReason(p.reason ?? p.encryption_reason ?? null);
+      if (c.code !== null) byCode.set(c.code, (byCode.get(c.code) ?? 0) + 1);
+    }
+  }
+  return {
+    leases_with_p2p: leasesWithP2P,
+    on_relay: onRelay,
+    on_direct: onDirect,
+    // Null rather than 0 for an empty denominator, for the same reason every other rate here is: "no leases"
+    // and "every lease failed" must not look alike.
+    relay_only_share: leasesWithP2P === 0 ? null : Math.round((onRelay / leasesWithP2P) * 1000) / 1000,
+    by_code: Object.fromEntries([...byCode].sort((a, b) => b[1] - a[1])),
+    detail: leasesWithP2P === 0
+      ? 'no lease carried a p2p block, so nothing can be said about the direct path'
+      : `${onRelay} of ${leasesWithP2P} lease(s) used the relay; ${byCode.size} distinct reason code(s)`,
+  };
+}
+
 /**
  * Summarise a set of task reports.
  *

package/src/plugin/tools.mjs

@@ -185,7 +185,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.19.0';
+const PLUGIN_VERSION = '0.20.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;