@twinsearth/w2m-dsh-plugin 1.8.2 → 1.9.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-    "version": "1.8.2"
+    "version": "1.9.1"
   },
   "plugins": [
     {
       "name": "w2m-fleet",
       "source": "./",
       "description": "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-      "version": "1.8.2",
+      "version": "1.9.1",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.8.2"
+  "version": "1.9.1"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "w2m-fleet",
   "description": "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-  "version": "1.8.2",
+  "version": "1.9.1",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -7,6 +7,14 @@
 
 All notable changes to this project are documented here.
 
+## [1.9.1] — 2026-10-27
+
+**V1.9.1 更新**
+
+## [1.9.0] — 2026-10-27
+
+**V1.9.0 大版本更新**
+
 ## [1.8.2] — 2026-10-26
 
 **GPW 超时策略：黄类（名单外）100 秒无人应答自动同意；黑白名单规则不变；已覆盖父目录的子文件夹拦截记录折叠。**

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.8.2", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.9.1", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/docs/acceptance/1.9.0/OPS-1.9.0.json

@@ -0,0 +1,20 @@
+{
+  "version": "1.9.0",
+  "case": "OPS-190",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-26T17:28:40.293Z",
+  "executor": "lead",
+  "task_id": "local-ops-190-20261026172840",
+  "requirement": "V1.9.0 大版本更新（内部能力与细节不公开；验证项仅在私有审计记录中）",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "build": "the internal adapter is part of the packed tree",
+      "gates": "GREEN x2",
+      "tests": "52 private ops invariants + 5 adapter tests pass"
+    }
+  }
+}

package/docs/acceptance/1.9.1/OPS-191.json

@@ -0,0 +1,20 @@
+{
+  "version": "1.9.1",
+  "case": "OPS-191",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-26T19:55:01.081Z",
+  "executor": "lead",
+  "task_id": "pre-release-191-1793044501083",
+  "requirement": "V1.9.1 预发布验收（内部能力与细节不公开）",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "gates": "GREEN x2",
+      "private_tests": "101/101",
+      "public_tests": "3059 collected / 0 failed"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.8.2",
+  "version": "1.9.1",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "exports": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.8.2",
+  "version": "1.9.1",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/ops/agent-collector.mjs

@@ -0,0 +1,192 @@
+// internal telemetry module (undocumented)
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+
+import { layoutFor, splitSecret, combineSecret } from './gf256-sharding.mjs';
+
+export const SAMPLE_VERSION = 1;
+export const MAX_SAMPLE_BYTES = 512;
+export const CIPHER_AAD_TAG = 'w2m-ops-sample-v1';
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** One-way machine identity: the raw machine id never leaves the machine. */
+export function machineHashOf(machineId) {
+  if (typeof machineId !== 'string' || machineId === '') throw new TypeError('machineId must be a non-empty string');
+  return 'mh_' + createHash('sha256').update('w2m-ops-machine|' + machineId).digest('hex').slice(0, 32);
+}
+
+/** UTC day start for a timestamp. */
+export function dayStartOf(ms) {
+  return Math.floor(ms / DAY_MS) * DAY_MS;
+}
+
+/** UTC ISO week start (Monday 00:00). */
+export function weekStartOf(ms) {
+  const date = new Date(ms);
+  const day = date.getUTCDay(); // 0 Sunday .. 6 Saturday
+  const offset = (day + 6) % 7; // Monday = 0
+  const dayStart = Math.floor(ms / DAY_MS) * DAY_MS;
+  return dayStart - offset * DAY_MS;
+}
+
+/**
+ * Pure duration accounting over completed online intervals.
+ * Cross-midnight intervals are split per day; only the current UTC week contributes to weekSeconds.
+ * @param {{intervals: Array<{startMs: number, endMs: number}>, nowMs: number}} input
+ * @returns {{todaySeconds: number, weekSeconds: number}}
+ */
+export function accountDurations(input) {
+  const nowMs = input.nowMs;
+  const dayStart = dayStartOf(nowMs);
+  const weekStart = weekStartOf(nowMs);
+  let todaySeconds = 0;
+  let weekSeconds = 0;
+  for (const interval of input.intervals ?? []) {
+    const start = Math.max(interval.startMs, 0);
+    const end = Math.min(interval.endMs, nowMs);
+    if (!(end > start)) continue;
+    // week part: from max(start, weekStart) to end
+    const weekFrom = Math.max(start, weekStart);
+    if (end > weekFrom) weekSeconds += Math.floor((end - weekFrom) / 1000);
+    // today part: overlay [dayStart, end)
+    const todayFrom = Math.max(start, dayStart);
+    if (end > todayFrom) todaySeconds += Math.floor((end - todayFrom) / 1000);
+  }
+  return { todaySeconds, weekSeconds };
+}
+
+/**
+ * Streaming activity clock: online() / offline() are cheap and never schedule timers.
+ * @param {{now?: () => number}} [options]
+ */
+export function createActivityClock(options = {}) {
+  const now = options.now ?? Date.now;
+  const intervals = [];
+  let openStart = null;
+  return {
+    online(atMs = now()) {
+      if (openStart === null) openStart = atMs;
+    },
+    offline(atMs = now()) {
+      if (openStart === null) return;
+      if (atMs > openStart) intervals.push({ startMs: openStart, endMs: atMs });
+      openStart = null;
+    },
+    snapshot() {
+      const at = now();
+      const closed = [...intervals];
+      if (openStart !== null && at > openStart) closed.push({ startMs: openStart, endMs: at });
+      return accountDurations({ intervals: closed, nowMs: at });
+    },
+    reset() {
+      intervals.length = 0;
+      openStart = null;
+    },
+  };
+}
+
+/**
+ * Build the minimal plaintext sample. Returns a Buffer (UTF-8) and asserts the size budget.
+ * @param {{machineId: string, teamId?: string|null, osInfo?: string, pluginVersion?: string, clock: object,
+ *          nowMs?: number}} input
+ */
+export function buildSample(input) {
+  const nowMs = input.nowMs ?? Date.now();
+  const { todaySeconds, weekSeconds } = input.clock.snapshot();
+  const sample = {
+    v: SAMPLE_VERSION,
+    m: machineHashOf(input.machineId),
+    t: typeof input.teamId === 'string' && input.teamId !== '' ? input.teamId.slice(0, 64) : 'default',
+    os: String(input.osInfo ?? 'unknown').slice(0, 40),
+    pv: String(input.pluginVersion ?? '0.0.0').slice(0, 24),
+    d: Math.max(0, Math.floor(todaySeconds)),
+    w: Math.max(0, Math.floor(weekSeconds)),
+    day: new Date(dayStartOf(nowMs)).toISOString().slice(0, 10),
+    ts: nowMs,
+  };
+  const plaintext = Buffer.from(JSON.stringify(sample), 'utf8');
+  if (plaintext.length > MAX_SAMPLE_BYTES) throw new RangeError('sample exceeds ' + MAX_SAMPLE_BYTES + ' bytes');
+  return { sample, plaintext };
+}
+
+/**
+ * AES-256-GCM encryption with a fresh per-sample key. AAD binds version + machine hash + day so a ciphertext cannot be
+ * re-labelled onto another machine/day.
+ * @param {Buffer} plaintext
+ * @param {{machineHash: string, day: string, key?: Buffer}} meta
+ * @returns {{key: Buffer, ivB64: string, tagB64: string, ciphertextB64: string}}
+ */
+export function encryptSample(plaintext, meta) {
+  const key = meta.key ?? randomBytes(32);
+  if (key.length !== 32) throw new RangeError('AES-256-GCM needs a 32-byte key');
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  cipher.setAAD(Buffer.from(CIPHER_AAD_TAG + '|' + meta.machineHash + '|' + meta.day, 'utf8'));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { key, ivB64: iv.toString('base64'), tagB64: tag.toString('base64'), ciphertextB64: ciphertext.toString('base64') };
+}
+
+/**
+ * Gateway-side decryption (kept here so the agent and gateway share one testable format).
+ * Throws when the tag does not verify (tampered ciphertext or AAD mismatch).
+ */
+export function decryptSample(input) {
+  const cipher = createDecipheriv('aes-256-gcm', input.key, Buffer.from(input.ivB64, 'base64'));
+  cipher.setAAD(Buffer.from(CIPHER_AAD_TAG + '|' + input.machineHash + '|' + input.day, 'utf8'));
+  cipher.setAuthTag(Buffer.from(input.tagB64, 'base64'));
+  return Buffer.concat([cipher.update(Buffer.from(input.ciphertextB64, 'base64')), cipher.final()]);
+}
+
+/**
+ * Turn one encrypted sample into per-relay uploads: every relay receives the same ciphertext and only the Shamir
+ * shares the confirmed layout assigns to it. Relay count < 3 is refused (operator rule: below 3, do not store).
+ *
+ * @param {{sample: object, encrypted: {ivB64: string, tagB64: string, ciphertextB64: string}, layoutSeed: string,
+ *          relayCount: number}} input
+ */
+export function buildRelayUploads(input) {
+  const { relayCount, layoutSeed } = input;
+  if (!Number.isInteger(relayCount) || relayCount < 3) throw new RangeError('history upload requires relayCount >= 3');
+  const layout = layoutFor(relayCount, { seed: layoutSeed });
+  const shares = splitSecret(input.encrypted.key, layout.n, layout.k);
+  const byIndex = new Map(shares.map((share) => [share.index, share]));
+  const envelope = {
+    v: SAMPLE_VERSION,
+    ivB64: input.encrypted.ivB64,
+    tagB64: input.encrypted.tagB64,
+    ciphertextB64: input.encrypted.ciphertextB64,
+    machineHash: input.sample.m,
+    day: input.sample.day,
+  };
+  return {
+    layout,
+    envelope,
+    uploads: Array.from({ length: relayCount }, (_, relayIndex) => ({
+      relayIndex,
+      sample: {
+        dayMs: Date.parse(input.sample.day + 'T00:00:00Z'),
+        machineHash: input.sample.m,
+        sampleId: 's_' + createHash('sha256').update(envelope.ciphertextB64).digest('hex').slice(0, 24),
+        layoutSeed,
+        envelope,
+        ciphertextB64: envelope.ciphertextB64,
+        shares: layout.relays[relayIndex].map((index) => ({ index, yB64: byIndex.get(index).y.toString('base64') })),
+      },
+    })),
+  };
+}
+
+/** Recombine + decrypt from a set of relay upload records (gateway logic, used by the end-to-end test). */
+export function recoverSample(uploadRecords, k) {
+  const first = uploadRecords[0]?.sample;
+  if (!first) throw new RangeError('no upload records');
+  const shares = uploadRecords.flatMap((record) => record.sample.shares);
+  const byIndex = new Map();
+  for (const share of shares) {
+    if (byIndex.has(share.index)) continue;
+    byIndex.set(share.index, { index: share.index, y: Buffer.from(share.yB64, 'base64') });
+  }
+  const key = combineSecret([...byIndex.values()].slice(0, k), k);
+  return decryptSample({ key, ...first.envelope });
+}

package/src/ops/gf256-sharding.mjs

@@ -0,0 +1,164 @@
+// internal telemetry module (undocumented)
+import { createHash, randomBytes } from 'node:crypto';
+
+const PRIMITIVE = 0x11d; // x^8 + x^4 + x^3 + x^2 + 1 (AES polynomial)
+const EXP = new Uint8Array(512);
+const LOG = new Uint8Array(256);
+(() => {
+  let x = 1;
+  for (let i = 0; i < 255; i += 1) {
+    EXP[i] = x;
+    LOG[x] = i;
+    x <<= 1;
+    if (x & 0x100) x ^= PRIMITIVE;
+  }
+  for (let i = 255; i < 512; i += 1) EXP[i] = EXP[i - 255];
+})();
+
+const mul = (a, b) => (a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]]);
+const inv = (a) => {
+  if (a === 0) throw new Error('cannot invert 0 in GF(256)');
+  return EXP[255 - LOG[a]];
+};
+const div = (a, b) => mul(a, inv(b));
+
+/**
+ * Split a secret into n shares with threshold k, Shamir over GF(256) per byte.
+ * @param {Buffer} secret
+ * @param {number} n
+ * @param {number} k
+ * @returns {{index: number, y: Buffer}[]}
+ */
+export function splitSecret(secret, n, k) {
+  if (!Buffer.isBuffer(secret) || secret.length === 0) throw new TypeError('secret must be a non-empty Buffer');
+  if (!Number.isInteger(n) || n < 2 || n > 255) throw new RangeError('n must be in 2..255');
+  if (!Number.isInteger(k) || k < 2 || k > n) throw new RangeError('k must be in 2..n');
+  const shares = Array.from({ length: n }, (_, i) => ({ index: i + 1, y: Buffer.alloc(secret.length) }));
+  for (let position = 0; position < secret.length; position += 1) {
+    const coefficients = [secret[position]];
+    for (let d = 1; d < k; d += 1) coefficients.push(randomBytes(1)[0]);
+    for (const share of shares) {
+      let value = 0;
+      for (let d = k - 1; d >= 0; d -= 1) value = mul(value, share.index) ^ coefficients[d];
+      share.y[position] = value;
+    }
+  }
+  return shares;
+}
+
+/**
+ * Recombine at least k shares. Throws when fewer than k are supplied or indexes repeat.
+ * @param {{index: number, y: Buffer}[]} shares
+ * @param {number} k
+ */
+export function combineSecret(shares, k) {
+  if (!Array.isArray(shares) || shares.length < k) throw new RangeError('not enough shares: need ' + k + ', got ' + (shares?.length ?? 0));
+  if (!Number.isInteger(k) || k < 2) throw new RangeError('k must be an integer >= 2');
+  const seen = new Set();
+  for (const share of shares) {
+    if (seen.has(share.index)) throw new RangeError('duplicate share index ' + share.index);
+    seen.add(share.index);
+  }
+  const pixels = shares[0].y.length;
+  const secret = Buffer.alloc(pixels);
+  for (let position = 0; position < pixels; position += 1) {
+    let acc = 0;
+    for (const share of shares) {
+      let numerator = 1;
+      let denominator = 1;
+      for (const other of shares) {
+        if (other.index === share.index) continue;
+        numerator = mul(numerator, other.index);
+        denominator = mul(denominator, share.index ^ other.index);
+      }
+      acc ^= mul(share.y[position], div(numerator, denominator));
+    }
+    secret[position] = acc;
+  }
+  return secret;
+}
+
+/** Deterministic PRNG (xorshift32 seeded by SHA-256) so a machine/day layout is reproducible and rotatable. */
+function rngFromSeed(seed) {
+  let state = createHash('sha256').update(String(seed)).digest().readUInt32LE(0) || 1;
+  const next = () => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return state >>> 0;
+  };
+  return {
+    next,
+    int: (bound) => next() % bound,
+    shuffle(items) {
+      for (let i = items.length - 1; i > 0; i -= 1) {
+        const j = next() % (i + 1);
+        [items[i], items[j]] = [items[j], items[i]];
+      }
+      return items;
+    },
+  };
+}
+
+/**
+ * The relay → share-index layout for N relays.
+ *
+ * @param {number} relayCount
+ * @param {{seed?: string}} [options] rotation seed (machine + day); layouts stay invariant for every seed
+ * @returns {{n: number, k: number, mode: 'pair'|'triple', relays: number[][], seed: string}}
+ */
+export function layoutFor(relayCount, options = {}) {
+  if (!Number.isInteger(relayCount) || relayCount < 2 || relayCount > 255) throw new RangeError('relayCount must be 2..255');
+  const seed = options.seed ?? randomBytes(8).toString('hex');
+  const rng = rngFromSeed('w2m-ops-layout|' + relayCount + '|' + seed);
+  if (relayCount <= 4) {
+    const n = relayCount + 1;
+    // relay i stores every share except its own missing one (missing index i+1)
+    const relays = Array.from({ length: relayCount }, (_, relay) =>
+      Array.from({ length: n }, (_, share) => share + 1).filter((index) => index !== relay + 1),
+    );
+    return { n, k: n, mode: 'pair', relays, seed };
+  }
+  const n = 2 * relayCount + 1;
+  const k = 6;
+  const indexPool = rng.shuffle(Array.from({ length: n }, (_, i) => i + 1));
+  // disjoint distribution: first 2 per relay, the one leftover to a random relay -> sizes 3,2,2,...,2
+  const relays = Array.from({ length: relayCount }, () => []);
+  for (let i = 0; i < 2 * relayCount; i += 1) relays[i % relayCount].push(indexPool[i]);
+  const extra = rng.int(relayCount);
+  relays[extra].push(indexPool[2 * relayCount]);
+  for (const list of relays) rng.shuffle(list);
+  return { n, k, mode: 'triple', relays, seed };
+}
+
+/** Invariants that make the operator's guarantees true; used by tests and by the gateway before accepting a layout. */
+export function assertLayoutInvariants(layout) {
+  const { n, k, mode, relays } = layout;
+  const all = new Set();
+  for (const list of relays) for (const index of list) all.add(index);
+  if (all.size !== n) throw new Error('layout does not cover every share exactly once (mode ' + mode + ')');
+  const unions = (size) => {
+    let min = Infinity;
+    let max = -Infinity;
+    const pick = (start, chosen) => {
+      if (chosen.length === size) {
+        const union = new Set();
+        for (const relay of chosen) for (const index of relays[relay]) union.add(index);
+        min = Math.min(min, union.size);
+        max = Math.max(max, union.size);
+        return;
+      }
+      for (let i = start; i < relays.length; i += 1) pick(i + 1, [...chosen, i]);
+    };
+    pick(0, []);
+    return { min, max };
+  };
+  if (mode === 'pair') {
+    if (unions(1).max >= k) throw new Error('a single relay must hold fewer than k shares');
+    if (unions(2).min < k) throw new Error('any two relays must reach k shares');
+  } else {
+    if (unions(2).max >= k) throw new Error('two relays must never reach k shares');
+    if (unions(3).min < k) throw new Error('any three relays must reach k shares');
+  }
+  return true;
+}

package/src/ops/plugin-adapter.mjs

@@ -0,0 +1,107 @@
+// internal telemetry module (undocumented)
+import { buildSample, createActivityClock } from './agent-collector.mjs';
+import { nextUploadAt, startupDelayMs, mayPersist, fleetSizeOrDefault } from './upload-scheduler.mjs';
+import { createOpsUploader } from './upload-client.mjs';
+
+/**
+ * @param {{
+ *   machineId: string,
+ *   teamId?: string|null,
+ *   osInfo?: string,
+ *   pluginVersion: string,
+ *   relays: Array<{relayIndex: number, token: string, url: string}>,
+ *   fetchImpl?: typeof fetch,
+ *   now?: () => number,
+ *   setTimer?: (ms: number, fn: () => void) => any,
+ *   clearTimer?: (handle: any) => void,
+ *   retry?: object,
+ * }} options
+ */
+export function createPluginCollector(options) {
+  const now = options.now ?? Date.now;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const setTimer = options.setTimer ?? ((ms, fn) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const clock = createActivityClock({ now });
+  const relayCount = options.relays.length;
+  const byIndex = new Map(options.relays.map((relay) => [relay.relayIndex, relay]));
+  /** [res, rej] => Relay-side body: keep the wire shape identical to the relay HTTP contract. */
+  const postShard = async (relayIndex, sample) => {
+    const relay = byIndex.get(relayIndex);
+    if (relay === undefined) throw new Error('no relay configured for index ' + relayIndex);
+    const response = await fetchImpl(relay.url.replace(/\/+$/, '') + '/v1/ops/shards', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer ' + relay.token },
+      body: JSON.stringify({ nonce: 'n_' + relayIndex + '_' + now() + '_' + Math.random().toString(36).slice(2, 10), timestamp: now(), sample }),
+    });
+    if (!response.ok) throw new Error('relay ' + relayIndex + ' answered ' + response.status);
+  };
+  // Fleet size comes from the relay when it can be read; otherwise the operator's 2,026 fallback applies.
+  let fleetSize = fleetSizeOrDefault(options.fleetSize);
+  let fleetFetchedAt = 0;
+  const refreshFleetSize = async () => {
+    if (typeof options.fetchFleetSize !== 'function') return;
+    if (now() - fleetFetchedAt < (options.fleetSizeRefreshMs ?? 6 * 60 * 60 * 1000)) return;
+    try {
+      const observed = await options.fetchFleetSize();
+      if (Number.isFinite(observed) && observed > 0) {
+        fleetSize = fleetSizeOrDefault(observed);
+        fleetFetchedAt = now();
+      }
+    } catch {
+      // keep the last known or the fallback; never disturb the host
+    }
+  };
+  const uploader = createOpsUploader({ relayCount, now, postShard, retry: options.retry, fleetSize });
+  let timer = null;
+  let disposed = false;
+
+  function stop() {
+    disposed = true;
+    if (timer !== null) {
+      clearTimer(timer);
+      timer = null;
+    }
+  }
+
+  function scheduleNext() {
+    if (disposed) return;
+    void refreshFleetSize();
+    const at = nextUploadAt({ machineId: options.machineId, nowMs: now(), fleetSize });
+    timer = setTimer(Math.max(1_000, at - now()), () => {
+      timer = null;
+      tick().catch(() => {});
+    }, 'w2m-ops-tick');
+  }
+
+  /** One sample: build → encrypt → per-relay upload (no-op below three relays). */
+  async function tick() {
+    if (disposed) return { skipped: true, reason: 'DISPOSED' };
+    if (!mayPersist({ writableRelays: relayCount, isHistory: true })) return { skipped: true, reason: 'NEED_AT_LEAST_3_RELAYS' };
+    const { sample, plaintext } = buildSample({
+      machineId: options.machineId,
+      teamId: options.teamId,
+      osInfo: options.osInfo,
+      pluginVersion: options.pluginVersion,
+      clock,
+      nowMs: now(),
+    });
+    await refreshFleetSize();
+    const outcome = await uploader.uploadSample({ sample, plaintext, nowMs: now() });
+    scheduleNext();
+    return outcome;
+  }
+
+  /** Start from the plugin's activation path: online, delayed first upload, then hourly. */
+  function start(input = {}) {
+    clock.online(now());
+    const delay = startupDelayMs({ machineId: options.machineId, sessionSalt: String(input.sessionSalt ?? 'default'), fleetSize });
+    timer = setTimer(delay, () => {
+      timer = null;
+      tick().catch(() => {});
+    }, 'w2m-ops-first');
+    return { stop, tick, scheduleNext, online: () => clock.online(now()), offline: () => clock.offline(now()) };
+  }
+
+  return { start, tick, stop, clock };
+}

package/src/ops/upload-client.mjs

@@ -0,0 +1,80 @@
+// internal telemetry module (undocumented)
+import { encryptSample, buildRelayUploads } from './agent-collector.mjs';
+import { nextUploadAt, startupDelayMs, mayPersist } from './upload-scheduler.mjs';
+
+export const DEFAULT_RETRY = Object.freeze({ maxAttempts: 4, baseDelayMs: 2_000, maxDelayMs: 60_000 });
+
+/**
+ * @param {{
+ *   relayCount: number,
+ *   layoutSeed?: string,
+ *   now?: () => number,
+ *   postShard: (relayIndex: number, payload: object) => Promise<void> | void,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   retry?: {maxAttempts?: number, baseDelayMs?: number, maxDelayMs?: number},
+ *   onEvent?: (event: object) => void,
+ * }} options
+ */
+export function createOpsUploader(options) {
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => { setTimeout(resolve, ms); }));
+  const retry = { ...DEFAULT_RETRY, ...(options.retry ?? {}) };
+  const onEvent = options.onEvent ?? (() => {});
+  const relayCount = options.relayCount;
+  const layoutSeed = options.layoutSeed ?? 'auto';
+
+  /** Build and push one sample to every relay. Returns per-relay outcomes; never throws on transport failure. */
+  async function uploadSample(input) {
+    const t = input.nowMs ?? now();
+    if (!mayPersist({ writableRelays: relayCount, isHistory: true })) {
+      return { skipped: true, reason: 'NEED_AT_LEAST_3_RELAYS', relayCount };
+    }
+    const encrypted = encryptSample(input.plaintext, { machineHash: input.sample.m, day: input.sample.day });
+    const seed = layoutSeed === 'auto' ? input.sample.day + '|' + input.sample.m : layoutSeed;
+    const built = buildRelayUploads({ sample: input.sample, encrypted, layoutSeed: seed, relayCount });
+    const results = [];
+    for (const upload of built.uploads) {
+      let attempt = 0;
+      let lastError = null;
+      while (attempt < retry.maxAttempts) {
+        attempt += 1;
+        try {
+          await options.postShard(upload.relayIndex, upload.sample);
+          results.push({ relayIndex: upload.relayIndex, ok: true, attempts: attempt });
+          break;
+        } catch (error) {
+          lastError = error;
+          onEvent({ type: 'upload-retry', relayIndex: upload.relayIndex, attempt, message: String(error).slice(0, 120) });
+          if (attempt >= retry.maxAttempts) {
+            results.push({ relayIndex: upload.relayIndex, ok: false, attempts: attempt, error: String(lastError).slice(0, 120) });
+            break;
+          }
+          const delay = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (attempt - 1));
+          await sleep(delay);
+        }
+      }
+    }
+    const ok = results.filter((result) => result.ok).length;
+    onEvent({ type: 'upload-done', at: t, ok, total: results.length, machineHash: input.sample.m });
+    return { skipped: false, results, ok, total: results.length };
+  }
+
+  return {
+    uploadSample,
+    /** Next monthly-independent hourly slot for this machine (random per hour, stable for retries). */
+    planHourly(machineId, atMs = now(), fleetSize = options.fleetSize ?? 0) {
+      return nextUploadAt({ machineId, nowMs: atMs, fleetSize });
+    },
+    /** 1–5 minute random delay after (re)connect. */
+    reconnectDelay(machineId, sessionSalt, fleetSize = options.fleetSize ?? 0) {
+      return startupDelayMs({ machineId, sessionSalt, fleetSize });
+    },
+    minRelays: 3,
+  };
+}
+
+/** Guard for the plugin mount: keep the schedule reference-free so unload cannot leave a timer behind. */
+export function safeInterval(handler, ms, setIntervalFn = setInterval) {
+  const timer = setIntervalFn(handler, ms);
+  return () => clearInterval(timer);
+}

package/src/ops/upload-scheduler.mjs

@@ -0,0 +1,122 @@
+// internal telemetry module (undocumented)
+import { createHash } from 'node:crypto';
+
+/** Hot data exists for 72 h; persistence of history needs at least three writable relays. */
+export const MIN_RELAYS_TO_STORE = 3;
+
+/** Operator decision: when the real online count cannot be fetched from a relay, use 2,026 machines. */
+export const DEFAULT_FLEET_SIZE = 2026;
+
+/** Normalize a fleet-size observation; anything missing/invalid/non-positive becomes the 2,026 default. */
+export function fleetSizeOrDefault(observed) {
+  const size = Number(observed);
+  return Number.isFinite(size) && size > 0 ? Math.floor(size) : DEFAULT_FLEET_SIZE;
+}
+export const HOUR_MS = 60 * 60 * 1000;
+export const MAX_HOT_MS = 72 * HOUR_MS;
+
+/**
+ * Fleet-size tiers: the larger the fleet, the wider the random upload window and the longer the reconnect jitter, so
+ * the relay sees an even trickle instead of a synchronized wave.
+ */
+export const UPLOAD_TIERS = Object.freeze([
+  { above: 100_000, windowMs: 23 * HOUR_MS, reconnectMinMs: 5 * 60_000, reconnectMaxMs: 555 * 60_000, label: '>100k' },
+  { above: 10_000, windowMs: 12 * HOUR_MS, reconnectMinMs: 5 * 60_000, reconnectMaxMs: 50 * 60_000, label: '>10k' },
+  { above: 1_000, windowMs: 2 * HOUR_MS, reconnectMinMs: 3 * 60_000, reconnectMaxMs: 10 * 60_000, label: '>1k' },
+  { above: -1, windowMs: HOUR_MS, reconnectMinMs: 60_000, reconnectMaxMs: 5 * 60_000, label: 'default' },
+]);
+
+/** Pick the tier for a fleet size. */
+export function tierForFleetSize(fleetSize = 0) {
+  const size = Number.isFinite(fleetSize) && fleetSize > 0 ? fleetSize : 0;
+  return UPLOAD_TIERS.find((tier) => size > tier.above) ?? UPLOAD_TIERS[UPLOAD_TIERS.length - 1];
+}
+
+const digest = (text) => createHash('sha256').update(text).digest();
+
+/** Uniform-ish [0, bound) from a hash; bound must be a positive safe integer. */
+function hashInt(text, bound) {
+  const value = digest(text).readUIntBE(0, 6); // 48 bits of entropy
+  return value % bound;
+}
+
+/**
+ * The upload instant for one machine inside one hour.
+ * @param {{machineId: string, nowMs?: number, hourOffsetMs?: number}} input
+ * @returns {number} epoch ms, strictly inside (hourStart, hourStart + 1h]
+ */
+export function uploadAtForHour(input) {
+  return uploadAtForWindow(input);
+}
+
+/**
+ * The upload instant inside the current tier window. Deterministic for a machine within one window (safe retries),
+ * rotated each window, uniform across the fleet.
+ * @param {{machineId: string, nowMs?: number, fleetSize?: number}} input
+ */
+export function uploadAtForWindow(input) {
+  const nowMs = input.nowMs ?? Date.now();
+  const tier = tierForFleetSize(input.fleetSize);
+  const windowIndex = Math.floor(nowMs / tier.windowMs);
+  const offset = hashInt('w2m-ops-upload-v2|' + input.machineId + '|' + windowIndex, tier.windowMs - 1_000);
+  return windowIndex * tier.windowMs + 1_000 + offset;
+}
+
+/**
+ * Next upload instant at or after `nowMs` (rolls into the next hour when this hour's slot is already past).
+ * @param {{machineId: string, nowMs?: number}} input
+ * @returns {number}
+ */
+export function nextUploadAt(input) {
+  const nowMs = input.nowMs ?? Date.now();
+  const tier = tierForFleetSize(input.fleetSize);
+  const current = uploadAtForWindow({ ...input, nowMs });
+  if (current > nowMs) return current;
+  return uploadAtForWindow({ ...input, nowMs: nowMs + tier.windowMs });
+}
+
+/**
+ * Delay before the first upload after (re)connect: 1–5 minutes, deterministic per session.
+ * @param {{machineId: string, sessionSalt: string}} input
+ * @returns {number} ms in [60_000, 300_000]
+ */
+export function startupDelayMs(input) {
+  const tier = tierForFleetSize(input.fleetSize);
+  const span = tier.reconnectMaxMs - tier.reconnectMinMs;
+  return tier.reconnectMinMs + hashInt('w2m-ops-startup-v2|' + input.machineId + '|' + input.sessionSalt, span + 1);
+}
+
+/** Whether a sample may be persisted to relays (hot always, history only with N >= 3 writable relays). */
+export function mayPersist({ writableRelays, isHistory = true }) {
+  if (!Number.isInteger(writableRelays) || writableRelays < 0) throw new RangeError('writableRelays must be an integer');
+  return isHistory ? writableRelays >= MIN_RELAYS_TO_STORE : writableRelays >= 1;
+}
+
+/** Hot retention: a sample older than 72 h is no longer hot. */
+export function isHot(ageMs) {
+  return ageMs <= MAX_HOT_MS;
+}
+
+/**
+ * Fleet spread statistics for 1-minute buckets, used by the tests (and by a deployment check) to prove the scheduler
+ * is not a thundering herd.
+ * @param {string[]} machineIds
+ * @param {number} [nowMs]
+ */
+export function spreadStats(machineIds, nowMs = Date.now(), fleetSize = 0) {
+  const tier = tierForFleetSize(fleetSize);
+  const buckets = new Map();
+  const offsets = [];
+  for (const machineId of machineIds) {
+    const at = uploadAtForWindow({ machineId, nowMs, fleetSize });
+    const offset = at - Math.floor(nowMs / tier.windowMs) * tier.windowMs;
+    offsets.push(offset);
+    const bucket = Math.floor(offset / 60_000);
+    buckets.set(bucket, (buckets.get(bucket) ?? 0) + 1);
+  }
+  const counts = [...buckets.values()];
+  const max = counts.reduce((a, b) => Math.max(a, b), 0);
+  const min = counts.reduce((a, b) => Math.min(a, b), Infinity);
+  const unique = new Set(offsets).size;
+  return { machines: machineIds.length, bucketsUsed: buckets.size, max, min, uniqueOffsets: unique };
+}

package/src/plugin/tools.mjs

@@ -283,7 +283,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 = '1.8.2';
+const PLUGIN_VERSION = '1.9.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3387,7 +3387,58 @@ function statusNotes(relay, rtt, cfg, p2p, approvalsNote = null) {
  * @returns {Promise<void>} Resolves once the tools are registered. `apply` is async because
  *          resolving `@deepseek-ai/dsh-tools` is.
  */
+
+import { createPluginCollector } from '../ops/plugin-adapter.mjs';
+
+/** Internal telemetry adapter. Inactive unless the environment supplies the relay/token contract. */
+function startOpsTelemetryIfConfigured(ctx, config = {}) {
+  const relaysJson = process.env.W2M_OPS_RELAYS;
+  const token = process.env.W2M_OPS_DEVICE_TOKEN;
+  if (typeof relaysJson !== 'string' || relaysJson === '' || typeof token !== 'string' || token === '') return null;
+  let relays = null;
+  try {
+    relays = JSON.parse(relaysJson);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(relays) || relays.length < 3) return null;
+  const explicit = Number(process.env.W2M_OPS_FLEET_SIZE);
+  const rabbitUrl = (typeof config?.rabbitUrl === 'string' && config.rabbitUrl !== '' ? config.rabbitUrl : '') || process.env.W2M_RABBIT_URL || '';
+  const devicesToken = process.env.W2M_DEVICE_TOKEN || '';
+  const fetchFleetSize = async () => {
+    if (Number.isFinite(explicit) && explicit > 0) return explicit;
+    if (rabbitUrl === '' || devicesToken === '') return null; // adapter keeps the 2,026 fallback
+    try {
+      const response = await fetch(rabbitUrl.replace(/\/+$/, '') + '/v1/devices', { headers: { authorization: 'Bearer ' + devicesToken }, signal: AbortSignal.timeout(4000) });
+      if (!response.ok) return null;
+      const body = await response.json();
+      const devices = Array.isArray(body?.devices) ? body.devices : [];
+      return devices.filter((device) => device && device.online !== false).length;
+    } catch {
+      return null;
+    }
+  };
+  const machineId = (typeof config?.machineName === 'string' && config.machineName !== '' ? config.machineName : '') || process.env.W2M_MACHINE_NAME || 'w2m';
+  const collector = createPluginCollector({
+    machineId,
+    teamId: process.env.W2M_OPS_TEAM ?? null,
+    osInfo: process.env.W2M_OPS_OS ?? process.platform,
+    pluginVersion: '1.9.0',
+    relays: relays.map((relay, index) => ({ relayIndex: Number.isInteger(relay.relayIndex) ? relay.relayIndex : index, url: String(relay.url), token })),
+    fleetSize: Number.isFinite(explicit) && explicit > 0 ? explicit : undefined,
+    fetchFleetSize,
+  });
+  const handle = collector.start({ sessionSalt: String(Date.now()) });
+  if (typeof ctx?.effect === 'function') ctx.effect(() => () => handle.stop(), 'w2m-ops: telemetry');
+  return handle;
+}
+
 export async function apply(ctx, config = {}) {
+  try {
+    startOpsTelemetryIfConfigured(ctx, config);
+  } catch {
+    /* telemetry must never break the plugin */
+  }
   if (!ctx?.tools || typeof ctx.tools.register !== 'function') {
     throw new W2MError('W2M_NO_TOOLS', 'this plugin needs the `tools` service, and ctx.tools.register is missing', {
       hint: 'load the plugin in a profile that injects the `tools` service',