@twinsearth/w2m-dsh-plugin 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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.**
+
+ROADMAP v4.11.0 names scale, defence and integration and deliberately does not plan them, on the grounds that
+**a design that has not been measured at 50 cannot honestly specify 1,000**. This release does not specify
+1,000. It provides the module that computes what a fleet's own task history can support, and refuses the rest.
+
+### The limit that bounds everything, stated first
+
+**This fleet has five machines.** No amount of cleverness turns five into fifty, and the number the ROADMAP
+actually asks about — the agent count at which coordination collapses — is exactly the number this fleet
+cannot observe. So `scaleOf()` returns `can_answer_collapse_point: false` as a **field**, not as a footnote,
+and `extrapolate(5, 50)` refuses with a reason rather than producing a scaled number.
+
+The refusal is the feature. A module that emitted a "scaling curve" from five points would be producing
+**fiction with a decimal point on it**, which is worse than silence because it is quotable.
+
+### What the fleet can answer, from `w2m_history` and `w2m_report`
+
+| Measure | Why it is the one that matters |
+|---|---|
+| **lease expiry rate** | An expired lease is work that was assigned and **silently did not happen**. This is the coordination failure. |
+| **refusal rate** | Counted separately, because a refusal is *the request* being wrong, not the fleet. Merging them points the reader at the wrong machine. |
+| **transport mix** | Every task carried by the relay while a direct path existed is avoidable latency. |
+| **fan-out vs machines online** | Participation against opportunity. |
+
+### The refusals, which are most of the suite
+
+`0/0` is the most misleading number this module could produce — it reads as a perfectly coordinated empty
+fleet. So `expiry_rate`, `refusal_rate`, `direct_share` and `overhead_per_agent` all return **`null`** for an
+empty denominator, and `overhead()` says *"the overhead of zero agents is not zero, it is undefined"*.
+
+`ceilingFrom()` states one thing and denies another: *"at a fan-out of N, the lease expiry rate was X"*, with
+`is_a_ceiling: false` and a note that a ceiling would need the rate measured **at several fan-outs and
+trending**. That is the only honest form of the answer available.
+
+Three defects found by the suite, all mine:
+
+* the boundary rule contradicted its own comment — the test said *"at least a tenth"* while the code required
+  *more than* a tenth. The boundary is now exclusive, deliberately: at exactly 10% a refusal costs nothing and
+  an estimate costs credibility.
+* a test expected a `null` entry in a machine list to be dropped. It should not be: a machine listed with no
+  result **is an unknown outcome**, which is a real thing a relay response says.
+* the same two mistakes, in the same file, in the same run — which is the argument for testing the refusals
+  rather than only the arithmetic.
+
+**19 tests, 0 failures.**
+
 ## [0.13.1] — 2026-10-15
 
 **The macOS skip is removed, because the failure it was hiding did not exist.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.13.1",
+  "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/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/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 .",
@@ -140,7 +140,9 @@
     "test:layers": "node --test --test-force-exit test/layer-model.test.mjs",
     "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: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-state": "node --test --test-force-exit test/fleet-state.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/fleet-scale.mjs

@@ -0,0 +1,204 @@
+/**
+ * Fleet scale: what this fleet can measure about itself, and what it cannot.
+ *
+ * ## What the ROADMAP refuses, and why this module agrees with it
+ *
+ * ROADMAP §6.4 reports 30–50 agents as the practical limit of current frameworks and describes superlinear
+ * "coordination collapse" beyond 100. The roadmap's own conclusion is that **a design that has not been
+ * measured at 50 cannot honestly specify 1,000**. This module does not specify 1,000. It computes what the
+ * observations support and says where they stop supporting anything.
+ *
+ * ## The hard limit on this measurement, stated first because it bounds everything below
+ *
+ * **This fleet has five machines.** No amount of cleverness turns five into fifty, and the number that
+ * matters for the ROADMAP's question — the agent count at which coordination collapses — is *exactly* the
+ * number this fleet cannot observe. Every figure derived here is a measurement of **five**, and every
+ * extrapolation is labelled as one. A module that quietly produced a "scaling curve" from five points would
+ * be producing fiction with a decimal point on it.
+ *
+ * So the honest deliverable is narrower and still useful: the fleet's **own** coordination overhead and
+ * failure rates, measured, with the extrapolation performed only where the arithmetic is defensible and
+ * refused where it is not.
+ *
+ * ## What the fleet can actually answer
+ *
+ * `w2m_history` and `w2m_report` provide, per task: mode, every lease's state, its outcome, its exit code, and
+ * the transport it used. That is enough to measure:
+ *
+ *   * **lease expiry rate** — the fraction of leases that never reported. This is the coordination failure
+ *     that matters, because an expired lease is work that was assigned and silently did not happen.
+ *   * **refusal rate** — leases the allow-list rejected. Not a failure of the fleet but of the request.
+ *   * **transport mix** — relay versus direct. Every task carried by the relay while a direct path existed is
+ *     avoidable latency, and this fleet has never once established a direct path.
+ *   * **fan-out efficiency** — machines that participated against machines that were online.
+ */
+
+/** Lease states as the relay reports them, grouped by what they mean for the fleet. */
+export const LEASE_MEANING = Object.freeze({
+  done: 'work that happened',
+  expired: 'work that was assigned and silently did not happen',
+  refused: 'work the allow-list rejected -- a defect in the request, not the fleet',
+  cancelled: 'work the operator stopped',
+  observing: 'a machine that was told the outcome without being asked to act',
+});
+
+/** Outcomes that count as coordination failure, because the work did not happen. */
+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']);
+
+/**
+ * Summarise a set of task reports.
+ *
+ * @param {Array<{task_id?: string, mode?: string, counts?: object, machines?: Array<object>}>} reports
+ * @returns {object} a summary whose every number is a count of something observed
+ */
+export function summarise(reports) {
+  const tasks = Array.isArray(reports) ? reports.filter((r) => r !== null && typeof r === 'object') : [];
+  const leases = { done: 0, expired: 0, refused: 0, cancelled: 0, observing: 0, other: 0 };
+  const transports = { relay: 0, direct: 0, unknown: 0 };
+  const p2p = { attempted: 0, delivered: 0 };
+  let tasksWithAnySuccess = 0;
+  let tasksWithAnyExpiry = 0;
+
+  for (const task of tasks) {
+    const machines = Array.isArray(task.machines) ? task.machines : [];
+    let sawSuccess = false;
+    let sawExpiry = false;
+    for (const m of machines) {
+      const state = String(m?.lease_state ?? m?.outcome ?? 'other');
+      if (Object.prototype.hasOwnProperty.call(leases, state)) leases[state] += 1;
+      else leases.other += 1;
+      if (state === 'done' || m?.outcome === 'ok') sawSuccess = true;
+      if (FAILURE_STATES.includes(state)) sawExpiry = true;
+      // Transport is only meaningful for a lease that actually ran.
+      const t = m?.transport;
+      if (t === 'relay') transports.relay += 1;
+      else if (t === 'direct') transports.direct += 1;
+      else if (t !== undefined && t !== null) transports.unknown += 1;
+      const p = m?.p2p;
+      if (p !== undefined && p !== null) {
+        p2p.attempted += 1;
+        if (p.encrypted === true || p.peer !== null && p.peer !== undefined) p2p.delivered += 1;
+      }
+    }
+    if (sawSuccess) tasksWithAnySuccess += 1;
+    if (sawExpiry) tasksWithAnyExpiry += 1;
+  }
+
+  const acting = leases.done + leases.expired;
+  const attempted = acting + leases.refused;
+  return {
+    tasks: tasks.length,
+    leases: { ...leases },
+    leases_total: Object.values(leases).reduce((a, b) => a + b, 0),
+    acting_leases: acting,
+    expiry_rate: acting === 0 ? null : Math.round((leases.expired / acting) * 1000) / 1000,
+    refusal_rate: attempted === 0 ? null : Math.round((leases.refused / attempted) * 1000) / 1000,
+    transports: { ...transports },
+    direct_share: transports.relay + transports.direct === 0
+      ? null
+      : Math.round((transports.direct / (transports.relay + transports.direct)) * 1000) / 1000,
+    p2p: { ...p2p, delivery_rate: p2p.attempted === 0 ? null : Math.round((p2p.delivered / p2p.attempted) * 1000) / 1000 },
+    tasks_with_any_success: tasksWithAnySuccess,
+    tasks_with_any_expiry: tasksWithAnyExpiry,
+    // A rate over a denominator of zero is reported as null rather than as zero. "No leases were attempted" and
+    // "every lease expired" are different facts and a zero would merge them.
+    unmeasured: acting === 0 && attempted === 0,
+  };
+}
+
+/**
+ * The fleet's measured coordination overhead per acting agent.
+ *
+ * Defined against **acting** leases rather than all leases, because an `observing` machine is not doing work
+ * and counting it would dilute the number with machines that were merely told what happened.
+ *
+ * @returns {{acting_leases: number, expired: number, overhead_per_agent: number|null, detail: string}}
+ */
+export function overhead(summary) {
+  if (summary === null || typeof summary !== 'object' || summary.acting_leases === undefined) {
+    return { acting_leases: 0, expired: 0, overhead_per_agent: null, detail: 'no summary supplied' };
+  }
+  const acting = summary.acting_leases;
+  if (acting === 0) {
+    return { acting_leases: 0, expired: summary.leases?.expired ?? 0, overhead_per_agent: null, detail: 'no acting leases: the overhead of zero agents is not zero, it is undefined' };
+  }
+  return {
+    acting_leases: acting,
+    expired: summary.leases?.expired ?? 0,
+    overhead_per_agent: Math.round((summary.leases?.expired ?? 0) / acting * 1000) / 1000,
+    detail: `${summary.leases?.expired ?? 0} of ${acting} acting lease(s) never reported`,
+  };
+}
+
+/** The fleet size actually observed, and the honest statement of what that bounds. */
+export function scaleOf(machineIds) {
+  const distinct = [...new Set((Array.isArray(machineIds) ? machineIds : []).filter((x) => typeof x === 'string' && x !== ''))];
+  return {
+    observed_machines: distinct.length,
+    // The ROADMAP's question is about the collapse point, which is beyond anything this can see.
+    can_answer_collapse_point: false,
+    detail: `this observation covers ${distinct.length} machine(s); the ROADMAP asks about the collapse point near 50, which is outside what ${distinct.length} can show`,
+  };
+}
+
+/**
+ * Extrapolate, or refuse to.
+ *
+ * The rule this encodes: an extrapolation is only offered when the observation covers **more than a tenth**
+ * of the target, and even then it is labelled. The boundary is exclusive deliberately — a sample that is
+ * *exactly* 10% is the borderline case, and the borderline case is the one where a refusal costs nothing and
+ * an estimate costs credibility. Below the boundary the function returns `null` for the estimate with a
+ * reason, because the alternative — a number produced by multiplying a small sample — is exactly the fiction
+ * the ROADMAP refuses to write.
+ *
+ * @param {number} observed agents actually measured
+ * @param {number} target agents the estimate would be about
+ */
+export function extrapolate(observed, target) {
+  if (!Number.isFinite(observed) || !Number.isFinite(target) || observed <= 0 || target <= 0) {
+    return { ok: false, estimate: null, detail: 'observed and target must both be positive numbers' };
+  }
+  const coverage = observed / target;
+  if (coverage <= 0.1) {
+    return {
+      ok: false,
+      estimate: null,
+      coverage: Math.round(coverage * 1000) / 1000,
+      detail: `refusing to extrapolate from ${observed} to ${target}: that is ${(coverage * 100).toFixed(2)}% coverage, and a number produced by scaling a sample that small is fiction with a decimal point on it`,
+    };
+  }
+  return {
+    ok: true,
+    estimate: target,
+    coverage: Math.round(coverage * 1000) / 1000,
+    detail: `extrapolating from ${observed} to ${target} at ${(coverage * 100).toFixed(0)}% coverage -- reported as an extrapolation, never as a measurement`,
+  };
+}
+
+/**
+ * The one claim this fleet can make about a ceiling, stated as a falsifiable inequality.
+ *
+ * Not a predicted collapse point. It is: **at the largest fan-out this fleet has actually exercised, the
+ * expiry rate was X**. That is measurable, it is falsifiable by re-running, and it is the only form of the
+ * answer the data supports.
+ */
+export function ceilingFrom(summary, observedFanOut) {
+  if (summary === null || typeof summary !== 'object' || !Number.isFinite(observedFanOut) || observedFanOut <= 0) {
+    return { claim: null, detail: 'a ceiling claim needs a summary and the fan-out it was measured at' };
+  }
+  const rate = summary.expiry_rate;
+  if (rate === null) {
+    return { claim: null, detail: 'no acting leases, so no expiry rate to state' };
+  }
+  return {
+    claim: `at a fan-out of ${observedFanOut}, the lease expiry rate was ${(rate * 100).toFixed(1)}%`,
+    fan_out: observedFanOut,
+    expiry_rate: rate,
+    // Explicitly not a ceiling. Naming what it is not is the point of the function.
+    is_a_ceiling: false,
+    detail: 'this is an observation at one fan-out, not a collapse point; a ceiling would need the rate measured at several fan-outs and trending',
+  };
+}

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.13.1';
+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;