@twinsearth/w2m-dsh-plugin 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -4,6 +4,143 @@ 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.54.0] — 2026-10-15
+
+**The fleet is published as an MCP server — read-only, and every declared route is checked against the relay's
+own router.**
+
+### Five tools, and nothing that can change anything
+
+```
+w2m_devices  -> /v1/devices
+w2m_stats    -> /healthz
+w2m_history  -> /v1/tasks
+w2m_report   -> /v1/tasks/{id}/report
+w2m_status   -> /v1/agents/{id}/status
+```
+
+**`w2m_run` is deliberately absent.** A server that hands fleet execution to any process able to start it gives
+away the ability to run commands on every machine in the fleet — and this project has already learned that a
+guard which is merely *named* well is not a guard: the `--dry-run` flag in `scripts/ilink-fleet-bridge.mjs`
+**dispatched for real while its name promised otherwise**. So the first version exposes five reads, and a test
+asserts by name that no mutating tool appears — **a later edit adding `w2m_run` has to delete an assertion rather
+than quietly widen what the fleet exposes.**
+
+### I invented two routes, and the check that catches that now exists
+
+My first draft declared `/v1/stats` and `/v1/status`. **Neither exists.** The relay's complete GET surface is
+`/healthz`, `/metrics`, `/v1/stream`, `/v1/devices`, `/v1/tasks`, `/v1/tasks/{id}`, `/v1/tasks/{id}/report` and
+`/v1/agents/{id}/status`.
+
+**A fabricated route does not fail loudly.** The relay answers 404, the MCP client reports a broken server, and
+the bug is in this package — a failure that surfaces in somebody else's tool, at a time nobody connects to this
+commit. So `scripts/mcp-check.mjs` **reads the routes back out of `src/relay/server.mjs` and compares them**, and
+the pre-flight runs it as a fifteenth check. Verified by injection: adding `/v1/invented` turns it red and names
+the route.
+
+**Two routes needed canonicalising to compare at all** — the router carries `/v1/tasks/([^/]+)/report` where the
+tool declares `/v1/tasks/{id}/report`. The first version of the check failed on two routes that *are* routed,
+which is its own lesson: **a check that fails on correct input gets disabled.**
+
+### Both protocol eras, because the deployed clients are on the older one
+
+The current revision (`2026-07-28`) is **stateless** — version, identity and capabilities travel as per-request
+`_meta`, and there is **no handshake**. Every earlier revision opens with `initialize`.
+
+**A server implementing only the modern contract is unreachable from most deployed clients**, which is exactly
+the population this exists to serve. So `initialize` is answered for legacy clients, `_meta` is honoured for
+modern ones, and an unsupported version gets the `-32022` error **with the `supported` list**, as the
+specification requires. `server/discover`, which the current revision demands of every server, is implemented.
+
+**A notification is never answered** — JSON-RPC forbids it, and `notifications/initialized` is sent by every
+legacy client, so getting that wrong breaks every connection.
+
+### stdout carries protocol messages and nothing else
+
+Over stdio a stray `console.log` corrupts the stream, and the symptom is a **hung client**, not a chatty server.
+Every diagnostic in this file goes to stderr through one `log()`, and the test drives the real `serve()` loop
+over in-memory streams rather than spawning a process — **because a test that needs a subprocess is skipped
+wherever piped stdio is refused, which is exactly where a protocol regression must still be caught.**
+
+### Four mistakes of mine, three of them the same mistake
+
+* **`/v1/stats` and `/v1/status` were fabricated.** Read the router; do not write the route you expect.
+* **`mcp-check.mjs` ran its whole check and called `process.exit` on import**, so the consuming suite reported
+  **1 test instead of 25** with no failure named. **This is the third file in this project to need the same
+  guarded-`main()` fix** — `skill-check.mjs` and `plugin-manifest-check.mjs` were the first two — and each one
+  now carries the guard with a comment saying why.
+* **I deleted a doc comment's closing `*/`**, which commented out `export const TOOLS` and produced
+  `TOOLS is not defined`. **That is the fourth time in this project that an edit matched anchor text without
+  reading the block containing it.**
+* **One assertion failed three times for three different incidental reasons** — a sample value substituted
+  where the builder applied a default, a `{id}` that `canonicalRoute` refuses to collapse, and an optional
+  property left unset. **The fix was to narrow what it tests**: the property is *"this tool can reach the route
+  it declares"*, and the query string is not part of that.
+
+**25 new tests, 0 failures.** Full suite 2302 in 85 files. **Pre-flight GREEN with FIFTEEN checks.**
+
+## [0.53.0] — 2026-10-15
+
+**The shared-memory layer gets a suite, and it corrected three things this session had already "verified".**
+
+### The layer was measured by hand; now it is measured by the suite
+
+Field-level omission at level 0, the refusal of an unproducible ancestor, the level 0/70 difference — **all of
+that was real evidence, produced through actual dispatches to an actual machine.** It was also **not
+repeatable**: it lived in a session, not in the suite. **A measurement that cannot be re-run is a memory of a
+measurement.**
+
+`test/memory-layer.test.mjs` adds **22 assertions**, and the suite grew to 84 files.
+
+### Three corrections, each of which the hand-run had got wrong
+
+**1. `evidence` costs 50, not 70.**
+
+```
+FIELD_LEVELS = { subject: 0, body: 0, evidence: 50 }
+```
+
+A level-70 dispatch succeeded, and **70 was written down as the threshold.** It is not: 49 is refused and 50 is
+allowed, and **50 is not arbitrary — it is the bottom of the `captain` band**, which is why the number is what
+it is.
+
+**2. `confidence` is an invariant, not a high-cost field.**
+
+`NEVER_ACCEPTED.confidence` = *"a receiver does not adopt the sender's certainty (**invariant, not a
+default**)"*. Level 90 is refused exactly as level 0 is, and there is no level that satisfies it. **The reason
+string says "invariant" on purpose: a reader who thinks it is a threshold will try to raise it.**
+
+**3. `FIELD_UNDECLARED` does not mean "forbidden", and the two APIs answer different questions.**
+
+| call | question | `origin` / `observed_at` / `lineage` |
+|---|---|---|
+| `acceptField` | *may a receiver choose this?* | `FIELD_UNDECLARED` — no rule lets a receiver pick it |
+| `acceptWithAuthority` | *what does this receiver keep?* | **present in `accepted`** — they are inherited |
+
+**So `UNDECLARED` means "not a receiver's to choose", not "refused".** Reading it as a refusal would have the
+receiver drop the ancestry that makes the block meaningful — and `INHERITED_FIELDS` plus
+`RECEIVER_CHOOSABLE_FIELDS` partition the seven exactly, so neither list can change without the other.
+
+### Four assertions of mine that were wrong, and the last one is the interesting one
+
+* **`ancestry` takes a `Map`, not an array**, and returns `{chain, missing, cycle, depth}` — **there is no `ok`
+  and no `code`.**
+* **`MISSING_PARENT` is not an `ancestry` outcome.** `ancestry` **collects** gaps in `missing` — *"knowing how
+  much of a history is absent is more useful than knowing that some of it is"* — while `acceptBlock` is what
+  **refuses**, returning `accepted: null`.
+* **`isDescendantOf` returns `{descendant, chain, missing, checked}`, not a boolean.** It returns more than a
+  boolean because that is its point: *"a claim that descends from something this machine already thought is an
+  **echo**, not corroboration, and **a fleet that cannot tell those apart will confidently agree with
+  itself**."* A parent that is not held gives `descendant: false` — and my assertion had demanded `true`.
+* **I could not construct a cycle, and that turned out to be the finding.** `blockHash` covers `lineage`, so
+  rebuilding a block changes its hash and the edge no longer closes — **a real cycle would need a hash
+  preimage.** The walk produces a *diamond* instead, and `CYCLE` is reachable **only** from a `have` map whose
+  keys disagree with the blocks under them: a corrupted or hostile store, where **terminating is the point,
+  because an unbounded walk on hostile input is a denial of service.**
+
+**Three attempts at that test asserted a cycle the code was right not to report.** The fourth printed the
+traversal instead of predicting it, which is the only one of the four that produced a fact.
+
 ## [0.52.0] — 2026-10-15
 
 **Agent Plugins 1.0.0 manifests, validated against the published schemas — and the honest note about who

package/bin/w2m-mcp.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * Publish this fleet as an MCP server, read-only (v0.54.0).
+ *
+ * ## Why read-only, and why that is the whole design
+ *
+ * The point of exposing the fleet to Claude Code, Cursor and anything else that speaks MCP is that a *different*
+ * agent can ask what the fleet is. **`w2m_run` is deliberately absent.** A server that hands `w2m_run` to any
+ * process able to start it gives away fleet execution rights, and this project has already learned that a guard
+ * which is merely *named* well is not a guard -- the `--dry-run` flag in `scripts/ilink-fleet-bridge.mjs`
+ * dispatched for real while its name promised otherwise.
+ *
+ * **So the first version exposes five tools that cannot change anything**, and each one is a thin wrapper over
+ * an endpoint the plugin already calls. **Nothing new is invented here**; if a tool is not already a read the
+ * plugin performs, it is not in this file.
+ *
+ * ## Two protocol eras, because the clients in the wild are on the older one
+ *
+ * The current revision (`2026-07-28`) is **modern**: version, identity and capabilities travel as per-request
+ * `_meta`, and there is **no handshake**. Every earlier revision (`2025-11-25` and back) is **legacy**: an
+ * `initialize` handshake, then `notifications/initialized`, then requests.
+ *
+ * **A server that implements only the modern contract is unreachable from most deployed clients**, which is
+ * exactly the population this exists to serve. So this is **dual-era**: `initialize` is answered for legacy
+ * clients, a request carrying `_meta` is answered for modern ones, and an unknown version gets the
+ * `-32022 UnsupportedProtocolVersionError` the specification requires, listing what is supported.
+ *
+ * ## stdout carries protocol messages and nothing else
+ *
+ * Over stdio, **one stray `console.log` corrupts the stream** and the failure looks like a hung client rather
+ * than a chatty server. So every diagnostic in this file goes to **stderr**, and `log()` is the only way to
+ * write one. There is no `console.log` here by construction, and the test asserts that.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+/** Versions this server can speak, newest first. */
+export const SUPPORTED_VERSIONS = Object.freeze(['2026-07-28', '2025-11-25']);
+/** The version assumed when a legacy client sends no `_meta` at all. */
+export const LEGACY_VERSION = '2025-11-25';
+export const SERVER_NAME = 'w2m-dsh-fleet';
+export const SERVER_VERSION = '0.54.0';
+
+/** JSON-RPC and MCP error codes this server can return. */
+export const ERROR = Object.freeze({
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+  UNSUPPORTED_PROTOCOL_VERSION: -32022,
+});
+
+/** Diagnostics, on stderr only. */
+const log = (message) => process.stderr.write(`[w2m-mcp] ${message}\n`);
+
+/**
+ * Where the relay and this machine's identity come from.
+ *
+ * Read from the same sources the plugin uses, so an MCP client sees the fleet the rest of the tooling sees
+ * rather than a second, separately configured one.
+ */
+export function readConfig(env = process.env) {
+  const home = env.DSH_HOME ?? join(homedir(), '.dsh');
+  const deviceFile = env.W2M_DEVICE_FILE ?? join(home, 'xclient', 'device.json');
+  let device = null;
+  if (existsSync(deviceFile)) {
+    try { device = JSON.parse(readFileSync(deviceFile, 'utf8')); } catch (error) { log(`device.json unreadable: ${error.message}`); }
+  }
+  return {
+    relayUrl: env.W2M_RABBIT_URL ?? 'http://202.182.123.154:8787',
+    operatorToken: env.W2M_OPERATOR_TOKEN ?? '',
+    device,
+    deviceFile,
+  };
+}
+
+/** Headers for a relay call: the device token identifies this machine, the operator token authorises reads. */
+const headers = (config) => {
+  const h = { 'content-type': 'application/json' };
+  if (config.device?.device_token) h['x-w2m-device-token'] = config.device.device_token;
+  if (config.operatorToken !== '') h.authorization = `Bearer ${config.operatorToken}`;
+  return h;
+};
+
+/**
+ * The five read-only tools.
+ *
+ * ## Every route here was read out of `src/relay/server.mjs`, not guessed
+ *
+ * The relay's complete GET surface is `/healthz`, `/metrics`, `/v1/stream`, `/v1/devices`, `/v1/tasks`,
+ * `/v1/tasks/{id}`, `/v1/tasks/{id}/report` and `/v1/agents/{id}/status`. **My first draft of this file
+ * invented `/v1/stats` and `/v1/status`, which do not exist** -- and a tool whose route is fabricated returns
+ * a 404 that reads as a broken relay rather than as a bug in this file.
+ *
+ * ## These are relay reads, not the DSH tools
+ *
+ * `w2m_stats` and `w2m_status` in the plugin both begin from `/healthz`, and each adds context the relay
+ * cannot know: which profile directory is in play, where `rabbitUrl` came from, whether a bundled runtime
+ * resolved. **That context lives in the plugin's process, so an MCP client calling this server gets the relay's
+ * half of the answer.** The descriptions say so rather than implying parity.
+ *
+ * `routes` names the paths a tool may call, and `scripts/mcp-check.mjs` asserts each one appears in the
+ * relay's router -- **so a fabricated route fails the pre-flight instead of failing in someone's client.**
+ */
+export const TOOLS = Object.freeze([
+  {
+    name: 'w2m_devices',
+    description: 'List the machines the relay holds a lease for: id, name, platform, online state and last-seen. Read-only. Answers "who is in the fleet" without running anything.',
+    routes: ['/v1/devices'],
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    requests: () => ['/v1/devices'],
+  },
+  {
+    name: 'w2m_stats',
+    description: "The relay's own snapshot of the fleet: relay identity, uptime, device and task counts, aggregate round-trip times, and whether the relay restarted. Read-only. This is the relay's half of the answer -- the parts of the plugin's w2m_stats that come from the local profile are not reachable over MCP.",
+    routes: ['/healthz'],
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    requests: () => ['/healthz'],
+  },
+  {
+    name: 'w2m_history',
+    description: 'List recent tasks newest first: id, mode, shard count, which machines hold leases, and whether each was cancelled. Read-only, and deliberately narrower than w2m_status: it names what ran without fetching any result.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', minimum: 1, maximum: 200, description: 'How many tasks to return, newest first. Defaults to 20.' },
+      },
+      additionalProperties: false,
+    },
+    routes: ['/v1/tasks'],
+    requests: (args) => {
+      const raw = args.limit;
+      if (raw === undefined) return ['/v1/tasks'];
+      if (!Number.isInteger(raw) || raw < 1) throw new Error(`limit must be a positive integer, got ${JSON.stringify(raw)}`);
+      return [`/v1/tasks?limit=${raw}`];
+    },
+  },
+  {
+    name: 'w2m_report',
+    description: 'Fetch the rendered report for one finished task as markdown or json. Markdown is the human summary; json is the same aggregate shape w2m_status returns. Read-only, and does not start, resume or cancel anything.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', minLength: 1, description: 'Task id returned by a dispatch.' },
+        format: { type: 'string', enum: ['md', 'json'], description: 'md for the rendered report, json for the aggregate. Defaults to md.' },
+      },
+      required: ['task_id'],
+      additionalProperties: false,
+    },
+    routes: ['/v1/tasks/{id}/report'],
+    requests: (args) => {
+      // A task id is opaque, but it lands in a URL path -- so anything that could change which endpoint is
+      // addressed is refused rather than escaped into place.
+      const id = String(args.task_id ?? '');
+      if (!/^[A-Za-z0-9_-]{1,64}$/.test(id)) throw new Error(`task_id ${JSON.stringify(id)} is not a plausible task id`);
+      return [`/v1/tasks/${id}/report?format=${args.format === 'json' ? 'json' : 'md'}`];
+    },
+  },
+  {
+    name: 'w2m_status',
+    description: "This plugin's own view of itself: the machine identity on disk, which relay it is talking to and where that address came from, whether the relay answers, and this machine's round-trip time. Read-only, and usable while the configuration is still broken.",
+    routes: ['/v1/agents/{id}/status'],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        machine_id: { type: 'string', minLength: 1, description: 'Machine id, as listed by w2m_devices.' },
+      },
+      required: ['machine_id'],
+      additionalProperties: false,
+    },
+    requests: (args) => {
+      const id = String(args.machine_id ?? '');
+      if (!/^[A-Za-z0-9_-]{1,64}$/.test(id)) throw new Error(`machine_id ${JSON.stringify(id)} is not a plausible machine id`);
+      return [`/v1/agents/${id}/status`];
+    },
+  },
+]);
+
+/** Tool names, for the tests and for a caller that wants the list without the schemas. */
+export const TOOL_NAMES = Object.freeze(TOOLS.map((t) => t.name));
+
+/**
+ * Perform one tool call.
+ *
+ * Returns the MCP `tools/call` result shape. **A failure is reported as `isError: true` with the reason in the
+ * text rather than as a JSON-RPC error**, because the model can act on the former and a transport-level error
+ * reads as a broken server.
+ *
+ * @param {string} name
+ * @param {object} args
+ * @param {{config: object, fetchImpl: Function}} deps
+ */
+export async function callTool(name, args, deps) {
+  const tool = TOOLS.find((t) => t.name === name);
+  if (tool === undefined) {
+    return { content: [{ type: 'text', text: `no such tool: ${name}. This server exposes ${TOOL_NAMES.join(', ')}.` }], isError: true };
+  }
+  let paths;
+  try {
+    paths = tool.requests(args ?? {});
+  } catch (error) {
+    return { content: [{ type: 'text', text: `bad arguments: ${error.message}` }], isError: true };
+  }
+  const base = deps.config.relayUrl.replace(/\/+$/, '');
+  try {
+    // Sequential rather than concurrent: a tool that reads two endpoints should report the first failure rather
+    // than racing two errors against each other.
+    const parts = [];
+    for (const path of paths) {
+      const response = await deps.fetchImpl(`${base}${path}`, { headers: headers(deps.config) });
+      const body = await response.text();
+      if (!response.ok) {
+        return { content: [{ type: 'text', text: `the relay answered ${response.status} for ${name} ${path}: ${body.slice(0, 400)}` }], isError: true };
+      }
+      parts.push(paths.length === 1 ? body : `${path}\n${body}`);
+    }
+    return { content: [{ type: 'text', text: parts.join('\n\n') }], isError: false };
+  } catch (error) {
+    return { content: [{ type: 'text', text: `could not reach the relay at ${deps.config.relayUrl}: ${error.message}` }], isError: true };
+  }
+}
+
+/** Build a JSON-RPC success or error envelope. */
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+
+/** The protocol version a request declares, from `_meta`, or null for a legacy client. */
+const declaredVersion = (request) => {
+  const meta = request?.params?._meta;
+  const v = meta?.['io.modelcontextprotocol/protocolVersion'];
+  return typeof v === 'string' ? v : null;
+};
+
+/**
+ * Answer one JSON-RPC message, or return null when nothing should be written.
+ *
+ * A notification has no `id` and **MUST NOT** be answered -- writing a reply to one is a protocol violation
+ * that some clients treat as a desynchronised stream.
+ *
+ * @param {object} request
+ * @param {{config: object, fetchImpl: Function}} deps
+ * @returns {Promise<object|null>}
+ */
+export async function handleMessage(request, deps) {
+  if (request === null || typeof request !== 'object' || Array.isArray(request)) {
+    return fail(null, ERROR.INVALID_REQUEST, 'not a JSON-RPC request object');
+  }
+  const { id, method, params } = request;
+  const isNotification = id === undefined || id === null;
+
+  const version = declaredVersion(request);
+  if (version !== null && !SUPPORTED_VERSIONS.includes(version)) {
+    // The specification requires the supported list, so a client can retry rather than give up.
+    return isNotification ? null : fail(id, ERROR.UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', { supported: [...SUPPORTED_VERSIONS], requested: version });
+  }
+
+  switch (method) {
+    case 'initialize': {
+      // Legacy handshake. `protocolVersion` echoes the client's choice when it is one this server speaks.
+      const asked = params?.protocolVersion;
+      const chosen = SUPPORTED_VERSIONS.includes(asked) ? asked : LEGACY_VERSION;
+      return ok(id, {
+        protocolVersion: chosen,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        instructions: 'Read-only view of a W2M fleet. These tools report; none of them can dispatch a command or change any machine.',
+      });
+    }
+
+    case 'notifications/initialized':
+      // A notification: acknowledged by doing nothing, never answered.
+      return null;
+
+    case 'server/discover':
+      // Required of every server by the current revision: name the versions supported.
+      return ok(id, { protocolVersion: SUPPORTED_VERSIONS[0], supportedVersions: [...SUPPORTED_VERSIONS], serverInfo: { name: SERVER_NAME, version: SERVER_VERSION } });
+
+    case 'tools/list':
+      return ok(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+
+    case 'tools/call': {
+      const name = params?.name;
+      if (typeof name !== 'string' || name === '') return fail(id, ERROR.INVALID_PARAMS, 'tools/call requires a tool name');
+      return ok(id, await callTool(name, params?.arguments ?? {}, deps));
+    }
+
+    case 'ping':
+      return ok(id, {});
+
+    default:
+      if (isNotification) return null;
+      return fail(id, ERROR.METHOD_NOT_FOUND, `method not found: ${String(method)}`);
+  }
+}
+
+/**
+ * Read newline-delimited JSON from `input` and answer each message on `output`.
+ *
+ * Exported so the test drives the same loop the process runs, without spawning anything -- a suite that needs a
+ * subprocess is skipped wherever piped stdio is refused, which is exactly where this needs to be testable.
+ */
+export function serve({ input, output, deps }) {
+  let buffer = '';
+  let pending = Promise.resolve();
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let newline = buffer.indexOf('\n');
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line !== '') {
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch (error) {
+          output.write(`${JSON.stringify(fail(null, ERROR.PARSE, `invalid JSON: ${error.message}`))}\n`);
+          newline = buffer.indexOf('\n');
+          continue;
+        }
+        // Serialised so two calls cannot interleave their frames on stdout.
+        pending = pending.then(async () => {
+          const reply = await handleMessage(parsed, deps);
+          if (reply !== null) output.write(`${JSON.stringify(reply)}\n`);
+        }).catch((error) => {
+          log(`handler threw: ${error?.stack ?? error}`);
+          output.write(`${JSON.stringify(fail(parsed?.id ?? null, ERROR.INTERNAL, String(error?.message ?? error)))}\n`);
+        });
+      }
+      newline = buffer.indexOf('\n');
+    }
+  });
+  return pending;
+}
+
+function main() {
+  const config = readConfig();
+  log(`starting; relay ${config.relayUrl}; device ${config.device?.machine_name ?? '(none)'}`);
+  log(`read-only tools: ${TOOL_NAMES.join(', ')}`);
+  serve({ input: process.stdin, output: process.stdout, deps: { config, fetchImpl: fetch } });
+}
+
+// Only when run as a program, so importing this module in a test starts no server.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/mcp.json

@@ -1,4 +1,11 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
-  "mcpServers": {}
+  "mcpServers": {
+    "w2m-fleet": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./bin/w2m-mcp.mjs"],
+      "cwd": "${PLUGIN_ROOT}"
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.52.0",
+  "version": "0.54.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",
@@ -116,13 +116,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/plan-sec-cmd.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/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.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/agent-plugins.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/plan-sec-cmd.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/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.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/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.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/plan-sec-cmd.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/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.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/agent-plugins.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/plan-sec-cmd.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/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.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/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Cross-platform fleet execution between Windows and macOS: one DeepSeek Harness account, a Rabbit relay, and signed device identity. Ships four Agent Skills describing fleet dispatch, field-level memory acceptance, session references, and resource scheduling.",
   "license": "MIT",
   "keywords": [

package/skills/memory-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-sync
-description: Use when writing or reading a block through w2m_memory, when a field was omitted rather than nulled, when a block names an ancestor the caller cannot produce, or when deciding whether a fact belongs in durable memory at all. Covers field-level acceptance, the per-actor cost of each field, and the refusal codes that mean "kept, but not for you".
+description: Use when writing or reading a block through w2m_memory, when a field was omitted rather than nulled, when a block names an ancestor the caller cannot produce, or when deciding whether a fact belongs in durable memory at all. Covers the seven CAT7 fields by their real names, the per-field cost a receiver pays, the one field no authority can accept, and why a refused ancestor is never re-rooted.
 ---
 
 # Memory sync
@@ -8,54 +8,115 @@ description: Use when writing or reading a block through w2m_memory, when a fiel
 `w2m_memory` stores blocks that carry **provenance**, and it decides field by field what each reader may see.
 The tool is small; the rules are the part that matters.
 
+## The seven fields, by their real names
+
+```
+CAT7_FIELDS = [origin, subject, body, evidence, confidence, observed_at, lineage]
+```
+
+**The order is part of the hash**, so a block is not a bag of fields — it is a canonical serialization.
+`blockHash` covers all seven, which is why tampering with any one of them fails `verifyBlock` with
+`BLOCK_HASH_MISMATCH`.
+
+They split into exactly two groups, and the split is the reason a receiver cannot rewrite provenance:
+
+| Group | Fields | Why |
+|---|---|---|
+| **inherited** | `origin`, `observed_at`, `lineage` | where it came from and when it was seen — **never offered to a receiver's chooser** |
+| **receiver-choosable** | `subject`, `body`, `evidence`, `confidence` | what the receiver decides to keep |
+
+**The two lists partition the seven**, so neither can grow without the other shrinking.
+
+### Names that are NOT part of this implementation
+
+A description circulating elsewhere names the seven as *focus, issue, intent, motivation, commitment,
+perspective, mood*, and refers to **`SVAF`** and **`remix`**. **None of those names exist here.** Measured:
+`SVAF` and `remix` occur **zero** times in the source. The mechanisms have different names:
+
+| Described elsewhere | What this implementation actually has |
+|---|---|
+| the seven-field cognitive model | `CAT7_FIELDS`, as listed above |
+| `SVAF`, per-receiver role anchoring | `RECEIVER_CHOOSABLE_FIELDS` + `acceptField(field, actor)` |
+| lineage by content-hash parent | `lineage` + `blockHash` + `ancestry` + `isDescendantOf` |
+| `remix` storing only the receiver's own evaluation | `INHERITED_FIELDS` and `defaultChoose` |
+
+**Writing the other names produces `BLOCK_UNKNOWN_FIELD` or `FIELD_NOT_A_FIELD`**, so a block built from that
+description is refused at the wire rather than silently misread.
+
+## Cost is per field, and one field is not a threshold
+
+```js
+FIELD_LEVELS = { subject: 0, body: 0, evidence: 50 }
+NEVER_ACCEPTED = { confidence: "a receiver does not adopt the sender's certainty (invariant, not a default)" }
+```
+
+**`evidence` costs 50** — the bottom of the `captain` band, which is why the number is what it is. Level 49 is
+refused with `FIELD_BELOW_AUTHORITY` and `required: 50`; level 50 is allowed.
+
+**`confidence` is refused at every level, including 90 and above**, with `FIELD_ALWAYS_REFUSED` and
+`required: null`. **The reason string says "invariant" on purpose: a reader who thinks it is a threshold will
+try to raise it.** There is no level that satisfies it.
+
+`origin`, `observed_at` and `lineage` answer `FIELD_UNDECLARED` to `acceptField` — **which does not mean
+"forbidden".** They have no rule because **a receiver does not choose them**, and `acceptWithAuthority` still
+returns them in `accepted`. **Reading `UNDECLARED` as a refusal would drop the ancestry that makes the block
+meaningful.**
+
 ## Acceptance is per field, and omission is not null
 
-A block is a set of named fields. When an actor's authority cannot cover a field, **the field is absent from
-what they receive — it is not present-with-`null`, and it is not an error.**
+When an actor's authority cannot cover a field, **the field is absent from what they receive — it is not
+present-with-`null`, and it is not an error.**
 
 ```
-accepted = [subject, body]      refused = [evidence]
-hasOwnProperty('evidence') === false
+level 0   accepted = [origin, observed_at, lineage, subject, body]   refused = [evidence, confidence]
+level 50  accepted = [origin, observed_at, lineage, subject, body, evidence]   refused = [confidence]
 ```
 
 **Test for the key, not for a falsy value.** `if (!block.evidence)` cannot tell "omitted" from "empty", and
 those mean different things: one is a permission decision, the other is content.
 
+`acceptBlock` returns a **partition**, not a filtered copy — *"the refused half is evidence: 'this machine
+declined the confidence and kept the body' is a decision worth being able to inspect, and a filtered object
+silently loses it."*
+
 **Never reconstruct a refused field.** If you need it, the answer is a higher-authority actor or a different
 block, not a guess.
 
 ## A block cannot name an ancestor its caller cannot produce
 
-Providing a block whose `parent` is not in the caller's own reachable set is refused as `BLOCK_MISSING_PARENT`,
-and **the block is rejected rather than re-rooted.**
+`acceptBlock(block, { lineage })` refuses a block whose `lineage` names an ancestor outside the set the
+receiver can produce:
 
-**This is deliberate.** Silently re-rooting would make the ancestry claim unfalsifiable — every block would
-"fit" somewhere, and the chain would stop carrying information. When you hit this refusal, supply the missing
-ancestor or drop the claim; do not look for a flag that relaxes it.
+```
+{ accepted: null, refused: [{ field: 'lineage', why: 'BLOCK_MISSING_PARENT: cannot produce ancestor(s) …;
+  refusing rather than re-rooting' }], accepted_fields: [], verified: true }
+```
 
-## Cost is a property of the field, not of the request
+**`verified: true` — the block itself is well formed; the ancestry is what is absent.** And it is refused
+rather than re-rooted, for the reason the source states:
 
-Authority bands, and what they reach:
+> Re-rooting — keeping the block and emptying its lineage — turns a claim with an unverifiable history into one
+> with **no history**, which reads as a fresh, independent assertion. **That is precisely how a fabricated
+> claim acquires respectability.**
 
-| Band | Range | Reaches |
-|---|---|---|
-| `ordinary` | 0–49 | the low-cost fields |
-| `captain` | 50–69 | more, including some evidence |
-| `org_admin` | 70–89 | `evidence` and above |
-| `system_admin` | 90+ | everything |
+**`ancestry` answers a different question and does not fail.** It takes a `Map<hash, block>` and returns
+`{chain, missing, cycle, depth}` — **there is no `ok` and no `code`.** Gaps are **collected** in `missing`
+because *"knowing how much of a history is absent is more useful than knowing that some of it is."*
 
-**A field's cost is declared where the field is declared**, and the acceptance decision is made against the
-actor's level at write and at read. So the same block read by two actors is two different objects, and that is
-the feature rather than a leak.
+**`isDescendantOf` returns `{descendant, chain, missing, checked}` — not a boolean.** It returns more than a
+boolean on purpose: *"a claim that descends from something this machine already thought is an **echo**, not
+corroboration, and a fleet that cannot tell those apart will confidently agree with itself."*
 
-Do not design a workflow that depends on a high-authority actor being present to make a low-authority read
-work. **Model the read you actually need.**
+**You cannot construct a cycle.** `blockHash` covers `lineage`, so rebuilding a block changes its hash and the
+edge no longer closes — a real cycle would need a hash preimage. `BLOCK_CYCLE` guards a `have` map whose keys
+disagree with the blocks under them: **a corrupted or hostile store, where terminating is the point.**
 
 ## Writing: say what you can prove
 
 - **Name the ancestor only if you hold it.** A parent you cannot produce fails the whole block.
-- **Put the load-bearing fact in the cheapest field that can carry it.** A fact in `evidence` is invisible to
-  everyone below `org_admin`, so a block whose meaning lives in `evidence` means nothing to most readers.
+- **Put the load-bearing fact in the cheapest field that can carry it.** A fact in `evidence` is invisible
+  below level 50, so a block whose meaning lives in `evidence` means nothing to most readers.
+- **Never write `confidence` expecting it to travel.** It is refused by every receiver by construction.
 - **One block, one claim.** Ancestry is how blocks relate; packing two claims into one block makes each
   unreadable to whoever may see only one of them.
 - **Expect omission to be silent.** Nothing in the result says "a field was hidden from you" beyond the field
@@ -65,5 +126,5 @@ work. **Model the read you actually need.**
 
 1. What is the **cheapest field** that can carry this fact?
 2. Do you **hold the parent** you are about to name?
-3. Who needs to read this, and **what band do they hold**? If the answer is "everyone", the fact does not
-   belong in a costly field.
+3. Who needs to read this, and **what band do they hold**? `ordinary` is 0–49, `captain` 50–69, `org_admin`
+   70–89, `system_admin` 90+. If the answer is "everyone", the fact does not belong in `evidence`.

package/src/plugin/tools.mjs

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