@twinsearth/w2m-dsh-plugin 0.14.0 → 0.16.0

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.16.0] — 2026-10-15
+
+**A non-zero exit code is not a fleet failure, and this session conflated them repeatedly.**
+
+Twelve real task reports were fetched one request at a time — the only correct input, since `w2m_history`
+records current lease state rather than outcomes — and the measured result was **12 acting leases, 12 `done`,
+0 expired, 0 refused**. Yet several runs in the same session produced no result at all. Both facts are true.
+
+They are different failures, and the difference decides where a reader looks:
+
+| Observation | What it means | Where the fault is |
+|---|---|---|
+| `exit_code: 70`, `lease_state: done` | **The command ran and reported 70.** The fleet worked. | the command |
+| `exit_code: null`, `lease_state: expired` | **No result was ever produced.** | the machine, the lease, or the network |
+
+`classifyLease()` and `isFleetFailure()` now encode that distinction, and **`exit_code` is the decisive field,
+not the lease state** — a lease can be `done` while its command returned non-zero, which is a *successful
+execution of a failing command*. `isFleetFailure` returns true only for the no-result case; a refusal is the
+request being wrong, and an observer was never asked to act.
+
+A rate that merged the two would report a healthy fleet as broken, or a broken one as healthy, depending on
+which it happened to count.
+
+### The measured fleet, this round
+
+| Measure | Value | Note |
+|---|---|---|
+| acting leases | 12 of 12 | a bounded sample, fetched per task |
+| expiry rate | **0.0 %** | 0 expired in the sample |
+| refusal rate | **0.0 %** | 0 refused |
+| direct share | **0.0 %** | **every task went by relay** |
+| P2P delivery rate | **0.0 %** | no direct channel was ever established |
+| fleet size | **3 usable of 5 paired** | two `win-desktop` silent ≈ 17.2 h |
+
+**The 0 % direct share is the finding worth acting on**: not one task in the sample used a direct path, so the
+entire fleet has been running on the relay at RTT **354 ms** (macmini) and **336 ms** (ToFuture) where
+jp-shared answers in **20 ms**.
+
+### Still not fixed
+
+The two relay endpoints still disagree about whether the silent machines are online — `reconcile()` detects it
+and says which to trust, but the disagreement itself needs a change on the relay, and this session has no shell
+on that host.
+
+**24 tests, 0 failures.**
+
+## [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.16.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-scale.mjs

@@ -48,6 +48,69 @@ export const FAILURE_STATES = Object.freeze(['expired', 'timeout']);
 /** Outcomes that are not the fleet's fault, so they are counted separately. */
 export const REQUEST_FAULT_STATES = Object.freeze(['refused']);
 
+/**
+ * How a lease ended, told apart properly.
+ *
+ * ## The conflation this exists to prevent
+ *
+ * This session repeatedly read `exit_code: 70` as a failure and `lease_state: expired` as the same kind of
+ * failure. **They are not the same kind of thing at all**, and the difference decides where a reader looks:
+ *
+ *   * `exit_code: 70` with `lease_state: done` means **the command ran and reported 70**. The fleet worked.
+ *     The number is the command's answer, and the machine is fine.
+ *   * `exit_code: null` with `lease_state: expired` means **no result was ever produced**. The command may not
+ *     have started. Nothing is known about what it did, and the machine — or the lease, or the network — is
+ *     where the fault is.
+ *
+ * Measured: twelve consecutive real reports showed **12 acting leases, 12 `done`, 0 expired** — while several
+ * runs in the same session had produced no result at all. Both facts are true; they are different failures.
+ * A rate that merged them would report a healthy fleet as broken, or a broken one as healthy, depending on
+ * which it happened to count.
+ */
+export const LEASE_OUTCOME = Object.freeze({
+  RAN: 'ran',                 // a result was produced, whatever it said
+  NO_RESULT: 'no_result',     // nothing came back; the command's behaviour is unknown
+  REFUSED: 'refused',         // the allow-list rejected it before it could run
+  OBSERVED_ONLY: 'observed',  // the machine was told the outcome without being asked to act
+  UNKNOWN: 'unknown',
+});
+
+/**
+ * Classify one machine entry from a task report.
+ *
+ * `exit_code` is the decisive field, **not** the lease state: a lease can be `done` while its command
+ * returned non-zero, and that is a successful execution of a failing command.
+ */
+export function classifyLease(entry) {
+  if (entry === null || typeof entry !== 'object') return { outcome: LEASE_OUTCOME.UNKNOWN, ran: false, exit_code: null, detail: 'no machine entry' };
+  const state = String(entry.lease_state ?? entry.outcome ?? '');
+  const code = entry.exit_code;
+  if (state === 'observing') return { outcome: LEASE_OUTCOME.OBSERVED_ONLY, ran: false, exit_code: null, detail: 'told the outcome, not asked to act' };
+  if (state === 'refused') return { outcome: LEASE_OUTCOME.REFUSED, ran: false, exit_code: null, detail: entry.refusal_reason ?? 'refused' };
+  if (state === 'done') {
+    return {
+      outcome: LEASE_OUTCOME.RAN,
+      ran: true,
+      exit_code: Number.isFinite(code) ? code : null,
+      detail: Number.isFinite(code) && code !== 0
+        ? `ran and reported ${code} -- the command's answer, not a fleet failure`
+        : 'ran and reported success',
+    };
+  }
+  if (state === 'expired' || state === 'timeout') {
+    return { outcome: LEASE_OUTCOME.NO_RESULT, ran: false, exit_code: null, detail: 'no result was produced; what the command did is unknown' };
+  }
+  return { outcome: LEASE_OUTCOME.UNKNOWN, ran: false, exit_code: null, detail: `unrecognised lease state ${JSON.stringify(state)}` };
+}
+
+/**
+ * Whether a non-zero exit code is a fleet failure. It is not, and this function exists so a caller does not
+ * have to decide that for itself each time.
+ */
+export function isFleetFailure(entry) {
+  return classifyLease(entry).outcome === LEASE_OUTCOME.NO_RESULT;
+}
+
 /**
  * Summarise a set of task reports.
  *

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