@twinsearth/w2m-dsh-plugin 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ 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.15.0] — 2026-10-15
+
+**The fleet is three machines, not five — and two relay endpoints disagree about it.**
+
+### The measurement, which is the whole point of this release
+
+`w2m_stats` and `w2m_devices` both answer "is this machine usable?" and **they do not agree**:
+
+| Machine | `w2m_devices` | `w2m_stats` | silent for |
+|---|---|---|---|
+| jp-shared | online | online, RTT **6 ms** | 2.4 s |
+| macmini | online | online, RTT **538 ms** | 4.4 s |
+| ToFuture | online | online, RTT **122 ms** | 0 s |
+| win-desktop ×2 | **online** | **offline, `silent`** | **61 384 s ≈ 17 h** |
+
+**A fleet whose size is reported two ways is a fleet whose plans are wrong by a factor of 1.7** — and the
+failure is silent, because both answers look authoritative. `src/agent/fleet-state.mjs` prefers `w2m_stats`
+(it is the one carrying a *reason*), treats a listing without a heartbeat age as unverified, and
+`reconcile()` reports **every machine the two endpoints disagree about** rather than picking one and staying
+quiet.
+
+### The second divergence, which would have flattered the fleet
+
+`w2m_history` lists a `lease_states` map per task. **It is not the execution outcome.** Of forty tasks in the
+sample, every one recorded macmini as `done` — while the session's own result envelopes included several
+`expired` with no exit code at all. The map records the *current* lease state.
+
+`historyIsOutcomeRecord()` returns `false` unconditionally with the reason, and its suite asserts on the
+measured payload. The finding matters because of its direction: **a reliability measurement built on the
+history listing would have shown a perfectly reliable fleet** — the most dangerous possible error in a module
+whose whole purpose is to notice trouble.
+
+The number to plan against is therefore **three usable machines**, and `readStats()` takes it from the
+per-machine entries rather than from `counts.online`, while still reporting the relay's own claim rather than
+hiding it.
+
+### A fixture typo that invented a disagreement
+
+Two tests failed because a machine id in a fixture was written `tob` where the payload says `tof` — so the
+reconciler correctly reported a *third* machine claimed online but not usable. **The code was right and the
+fixture was wrong**, which is the third time in this project that a failing test was the test's fault; the
+argument for testing refusals is that they fail loudly enough to be told apart.
+
+**16 tests, 0 failures.**
+
 ## [0.14.0] — 2026-10-15
 
 **Fleet scale: the arithmetic the observations support, and the refusals where they support nothing.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -113,13 +113,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",
@@ -141,7 +141,8 @@
     "test:log-bounds": "node --test --test-force-exit test/log-bounds.test.mjs",
     "layer-check": "node scripts/layer-check.mjs",
     "test:test-report": "node --test --test-force-exit test/test-report.test.mjs",
-    "test:fleet-scale": "node --test --test-force-exit test/fleet-scale.test.mjs"
+    "test:fleet-scale": "node --test --test-force-exit test/fleet-scale.test.mjs",
+    "test:fleet-state": "node --test --test-force-exit test/fleet-state.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/fleet-state.mjs

@@ -0,0 +1,167 @@
+/**
+ * Fleet state: what the relay's own accounting does and does not say, and the one place it disagrees with itself.
+ *
+ * ## The disagreement, measured
+ *
+ * Two relay endpoints answer "is this machine usable?" and they do not agree:
+ *
+ *   * `w2m_devices` reports every paired machine as `state: "online"` -- including two that had been silent
+ *     for **61,384 seconds (about 17 hours)** at the time of measurement.
+ *   * `w2m_stats` reports the same two as `online: false` with `offline_reason: "silent"`, and counts
+ *     `online: 3` out of `devices: 5`.
+ *
+ * A caller that asked the first one would plan work for five machines and get three. **A fleet whose size is
+ * reported two ways is a fleet whose plans are wrong by a factor of 1.7**, and the failure is silent because
+ * both answers look authoritative.
+ *
+ * So this module prefers `w2m_stats` — it is the one that carries a *reason* — and treats a device listing
+ * without a heartbeat age as **unverified rather than online**.
+ *
+ * ## The second disagreement, which is about history
+ *
+ * `w2m_history` lists, per task, a `lease_states` map. It is NOT the execution outcome: a task that expired
+ * mid-run can show `done` afterwards, because the map records the *current* lease state rather than what
+ * happened. Measured directly: of forty tasks in the sample, every one recorded macmini as `done`, while the
+ * session's own result envelopes included several `expired` with no exit code at all.
+ *
+ * Extracting the outcome requires `w2m_report`, which is a request per task. **A history listing is therefore
+ * a poor input for a reliability measurement, and using it as one would have produced a fleet that looked
+ * perfectly reliable** — the most dangerous possible error in a module whose purpose is to notice trouble.
+ */
+
+/** How a machine's usability was determined, in descending order of trust. */
+export const EVIDENCE = Object.freeze({
+  HEARTBEAT_WITH_RTT: 'a live heartbeat and a measured round trip',
+  HEARTBEAT_ALONE: 'a live heartbeat with no round trip measured',
+  STALE_OR_ABSENT: 'no recent heartbeat',
+  UNKNOWN: 'the relay did not say',
+});
+
+/**
+ * Classify one machine from a `w2m_stats` entry.
+ *
+ * `silent_ms` is the decisive field. A machine that is "online" but silent is not online, and the reason is
+ * reported alongside so a caller can distinguish "went away" from "never arrived".
+ */
+export function classifyMachine(entry) {
+  if (entry === null || typeof entry !== 'object' || typeof entry.machine_id !== 'string') {
+    return { machine_id: null, usable: false, evidence: EVIDENCE.UNKNOWN, reason: 'no machine entry', detail: 'the relay did not describe this machine' };
+  }
+  const online = entry.online === true;
+  const rtt = entry.rtt_ms;
+  const stale = entry.rtt_stale === true;
+  if (online && !stale && Number.isFinite(rtt)) {
+    return { machine_id: entry.machine_id, name: entry.machine_name ?? null, usable: true, evidence: EVIDENCE.HEARTBEAT_WITH_RTT, rtt_ms: rtt, reason: null, detail: `live, ${rtt} ms` };
+  }
+  if (online && !stale) {
+    return { machine_id: entry.machine_id, name: entry.machine_name ?? null, usable: true, evidence: EVIDENCE.HEARTBEAT_ALONE, rtt_ms: null, reason: null, detail: 'live, round trip not measured' };
+  }
+  return {
+    machine_id: entry.machine_id,
+    name: entry.machine_name ?? null,
+    usable: false,
+    evidence: EVIDENCE.STALE_OR_ABSENT,
+    rtt_ms: Number.isFinite(rtt) && !stale ? rtt : null,
+    reason: entry.offline_reason ?? 'not online',
+    silent_ms: Number.isFinite(entry.silent_ms) ? entry.silent_ms : null,
+    detail: entry.offline_reason === 'silent'
+      ? `silent for ${Math.round((entry.silent_ms ?? 0) / 1000)}s`
+      : String(entry.offline_reason ?? 'not online'),
+  };
+}
+
+/**
+ * Read a `w2m_stats` payload.
+ *
+ * @returns {{
+ *   paired: number, online: number, usable: number, silent: Array<object>,
+ *   usable_machines: Array<object>, detail: string
+ * }}
+ */
+export function readStats(stats) {
+  const machines = Array.isArray(stats?.machines) ? stats.machines : [];
+  const classified = machines.map(classifyMachine);
+  const paired = Number.isFinite(stats?.counts?.devices) ? stats.counts.devices : machines.length;
+  const usable = classified.filter((m) => m.usable);
+  const silent = classified.filter((m) => !m.usable);
+  // The number a caller should plan against is the number of machines that can actually run something.
+  return {
+    paired,
+    online: Number.isFinite(stats?.counts?.online) ? stats.counts.online : usable.length,
+    usable: usable.length,
+    usable_machines: usable,
+    silent,
+    runner_up_rtt_ms: usable.filter((m) => Number.isFinite(m.rtt_ms)).sort((a, b) => a.rtt_ms - b.rtt_ms)[0]?.rtt_ms ?? null,
+    detail: `${usable.length} of ${paired} paired machine(s) can run work`,
+  };
+}
+
+/**
+ * Compare a device listing against the stats reading, and report every machine they disagree about.
+ *
+ * **The disagreement is the product.** A caller that saw only the device listing would believe the fleet is
+ * larger than it is; a caller that saw only the stats would not know the listing claimed otherwise. Reporting
+ * the gap makes the gap fixable, and until it is fixed the smaller number is the true one.
+ */
+export function reconcile(devices, stats) {
+  const listed = Array.isArray(devices?.devices) ? devices.devices : [];
+  const reading = readStats(stats);
+  const usableIds = new Set(reading.usable_machines.map((m) => m.machine_id));
+  const claimedOnline = listed.filter((d) => d?.state === 'online');
+  const disagreements = claimedOnline
+    .filter((d) => !usableIds.has(d.machine_id))
+    .map((d) => {
+      const m = reading.silent.find((s) => s.machine_id === d.machine_id);
+      return {
+        machine_id: d.machine_id,
+        name: d.name ?? null,
+        devices_says: 'online',
+        stats_says: m?.reason ?? 'not usable',
+        silent_ms: m?.silent_ms ?? null,
+      };
+    });
+  return {
+    devices_claims_online: claimedOnline.length,
+    stats_says_usable: reading.usable,
+    disagreements,
+    // The trust decision, stated as a field rather than left to the reader.
+    trust: 'stats',
+    reason: disagreements.length === 0
+      ? 'the two endpoints agree'
+      : `a device listing reports a machine as online when it has not been heard from; the stats reading carries a reason and is the one to plan against`,
+    detail: `${claimedOnline.length} claimed online, ${reading.usable} usable, ${disagreements.length} disagreement(s)`,
+  };
+}
+
+/**
+ * Whether a `w2m_history` payload can be used as a reliability measurement.
+ *
+ * It cannot, and this function exists so that conclusion is a checked fact rather than a comment. Every entry
+ * in the sample recorded the same state for the same machine, which is exactly what a current-state map looks
+ * like and exactly what an outcome record does not.
+ *
+ * @returns {{usable_as_outcome_record: boolean, reason: string, homogeneous: Array<string>}}
+ */
+export function historyIsOutcomeRecord(history) {
+  const tasks = Array.isArray(history?.tasks) ? history.tasks : [];
+  if (tasks.length === 0) {
+    return { usable_as_outcome_record: false, reason: 'no tasks in the sample', homogeneous: [] };
+  }
+  // Per machine, how many distinct states appear across tasks. A machine at "done" in every task, including
+  // tasks that expired, is a current-state map rather than a record of what happened.
+  const states = new Map();
+  for (const task of tasks) {
+    for (const [id, state] of Object.entries(task?.lease_states ?? {})) {
+      if (!states.has(id)) states.set(id, new Set());
+      states.get(id).add(String(state));
+    }
+  }
+  const homogeneous = [...states.entries()].filter(([, set]) => set.size === 1).map(([id]) => id);
+  return {
+    usable_as_outcome_record: false,
+    homogeneous,
+    reason: homogeneous.length === states.size && states.size > 0
+      ? `every one of the ${states.size} machine(s) holds a single state across ${tasks.length} task(s) -- a current-state map, not an outcome record; use w2m_report per task instead`
+      : `a lease_states map reports the current state, not what happened; use w2m_report per task instead`,
+  };
+}

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