@twinsearth/w2m-dsh-plugin 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -4,6 +4,135 @@ 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.55.0] — 2026-10-15
+
+**A second transport binding — and `mcp.json` now declares both.**
+
+### The same protocol, two bindings, and no logic shared between them
+
+The MCP overview states it plainly: **"protocol semantics are identical on every transport. A transport is a
+binding."** So `src/mcp/http-transport.mjs` contains **no protocol decisions** — it decodes a request, hands the
+body to the same `handleMessage` the stdio binding uses, and encodes the reply. **Neither binding imports the
+other.** The single command reaches the fleet over both.
+
+### What revision `2026-07-28` removed, which made this smaller than expected
+
+* **The GET stream endpoint is gone.** A bare `GET /mcp` gets **405 naming the revision**, not a 404 — a client
+  written against the older revision should learn *why* rather than guess at the URL.
+* **Protocol-level sessions are gone.** No `Mcp-Session-Id`, no session table, no state between requests. Two
+  identical requests return identical bytes, and the test asserts it.
+
+`GET /mcp?discover` still answers, **gated on an explicit parameter**: a bare GET is what the removed stream
+client sends, and handing it a description document to parse as a stream would be worse than refusing it.
+
+### The `Origin` rule is a MUST, and it is easy to skip
+
+> **"Servers MUST validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks."**
+
+A loopback MCP server is reachable by **any page the user's browser loads**, and a rebinding attack makes that
+page same-origin. So a refused `Origin` gets **403 before the body is read** — asserted with an unparseable body,
+because ordering is the property.
+
+**A missing `Origin` is allowed, and that is a decision rather than an oversight**: the header constrains
+*browsers*, an attacker's browser always sends one, and refusing an absent header would break every
+command-line client while stopping no attack. The default bind is **127.0.0.1**, per the specification's SHOULD.
+
+### `mcp.json` declares both, and one of them is not a subprocess
+
+```json
+"w2m-fleet":      { "type": "stdio",           "command": "node", "args": ["./bin/w2m-mcp.mjs"], "cwd": "${PLUGIN_ROOT}" },
+"w2m-fleet-http": { "type": "streamable-http", "url": "http://127.0.0.1:8766/mcp" }
+```
+
+**The HTTP entry names a server that must be started separately** — `node bin/w2m-mcp.mjs --http` — because a
+remote-transport entry has no `command` to launch. That is what the transport type means, and the alternative —
+declaring only stdio — would leave an HTTP-only client with nothing to connect to. **The `cwd` is
+`${PLUGIN_ROOT}` rather than a path, so the entry works wherever the package is installed**, and
+`plugin-manifest-check.mjs` validates both entries against the schema's closed per-transport field sets.
+
+### One assertion I wrote wrong, and the fix was the implementation
+
+My discovery handler matched `GET /mcp` **exactly**, while the test sent `GET /mcp?discover=1`. **The test was
+right and the code was wrong** — the two GETs are different callers with different needs, and telling them apart
+by a parameter is honest where guessing at intent is not. Fixed the handler, not the test.
+
+**16 new tests, 0 failures.** Full suite 2318 in 86 files. **Pre-flight GREEN with FIFTEEN checks.**
+
+## [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".**

package/bin/w2m-mcp.mjs

@@ -0,0 +1,378 @@
+#!/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;
+}
+
+/**
+ * Start the server on the transport the caller asked for.
+ *
+ * **stdio is the default because it is what `mcp.json` declares and what a client launches.** `--http` is for
+ * the clients that require an HTTP endpoint -- one of them is known to insist on a local HTTP server with a
+ * discovery file rather than a subprocess -- and it is an explicit flag rather than a guess, because the two
+ * transports have different threat models: a subprocess talks to its parent, a socket talks to whatever can
+ * reach the port.
+ */
+async function main() {
+  const argv = process.argv.slice(2);
+  const flag = (name, dflt) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : dflt);
+  const config = readConfig();
+  log(`starting; relay ${config.relayUrl}; device ${config.device?.machine_name ?? '(none)'}`);
+  log(`read-only tools: ${TOOL_NAMES.join(', ')}`);
+
+  if (argv.includes('--http')) {
+    const { createMcpHttpServer } = await import('../src/mcp/http-transport.mjs');
+    const host = flag('--host', '127.0.0.1');
+    const port = Number(flag('--port', 8766));
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      log(`--port ${flag('--port')} is not a port number`);
+      process.exit(2);
+    }
+    const running = await createMcpHttpServer({ host, port, deps: { config, fetchImpl: fetch } });
+    // Printed so a launcher can read the port when it asked for 0, and on stderr so it never touches a protocol
+    // stream -- this binding has no stdout protocol, but the rule is the same one the stdio binding follows.
+    log(`streamable-http listening on ${running.url}`);
+    const stop = async () => { await running.close(); process.exit(0); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    return;
+  }
+
+  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,15 @@
 {
   "$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}"
+    },
+    "w2m-fleet-http": {
+      "type": "streamable-http",
+      "url": "http://127.0.0.1:8766/mcp"
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.53.0",
+  "version": "0.55.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/memory-layer.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/mcp-http.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/memory-layer.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/mcp-http.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.53.0",
+  "version": "0.55.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/mcp/http-transport.mjs

@@ -0,0 +1,216 @@
+/**
+ * The Streamable HTTP binding for the MCP server (v0.55.0).
+ *
+ * ## Why this is a separate file from the stdio binding
+ *
+ * The MCP overview says it directly: **"Protocol semantics are identical on every transport. A transport is a
+ * binding"** -- it defines framing and delivery, never meaning. So this file contains no protocol decisions: it
+ * decodes a request, hands the body to `handleMessage`, and encodes the reply. **`bin/w2m-mcp.mjs` holds the
+ * semantics and neither binding imports the other.**
+ *
+ * ## What revision 2026-07-28 removed, which simplifies this by a lot
+ *
+ * * **The GET stream endpoint is gone.** A GET is refused rather than half-supported.
+ * * **Protocol-level sessions are gone.** No `Mcp-Session-Id`, no session table, no state between requests --
+ *   which is what the overview means by "stateless, self-contained requests".
+ *
+ * ## The security requirement that is easy to skip
+ *
+ * **"Servers MUST validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks."**
+ * A local MCP server bound to a loopback port is reachable by any page the user's browser loads, and a
+ * rebinding attack makes that page same-origin. So an invalid `Origin` gets **403**, and the default bind is
+ * **127.0.0.1** rather than every interface.
+ *
+ * ## Two response shapes, and why JSON is chosen
+ *
+ * The specification allows a plain JSON object or a request-scoped SSE stream. **SSE exists to interleave
+ * request-related notifications with the final response**, and this server emits no notifications during a call
+ * -- its only outbound messages are responses. So the JSON shape carries everything, and SSE would be a stream
+ * with one frame. `?stream=1` is honoured for a client that insists, because a client written against the
+ * stream form is entitled to it.
+ */
+import { createServer } from 'node:http';
+import { handleMessage, TOOL_NAMES, SUPPORTED_VERSIONS, SERVER_NAME, SERVER_VERSION } from '../../bin/w2m-mcp.mjs';
+
+/** The path the MCP endpoint is mounted at. A single endpoint, per the specification. */
+export const MCP_PATH = '/mcp';
+
+/**
+ * Origins that may call this server.
+ *
+ * **Loopback only, and by exact match.** A rebinding attack arrives with an `Origin` the attacker chose, so the
+ * rule has to be an allow-list rather than a check for something suspicious -- and `null` (a `file://` page, a
+ * sandboxed iframe) is refused for the same reason.
+ */
+export const ALLOWED_ORIGINS = Object.freeze([
+  'http://127.0.0.1',
+  'http://localhost',
+  'https://127.0.0.1',
+  'https://localhost',
+]);
+
+/**
+ * Is this `Origin` acceptable?
+ *
+ * A missing `Origin` is allowed: a non-browser client (curl, an SDK) sends none, and the header exists to
+ * constrain *browsers*. **Refusing an absent header would break every command-line client while stopping no
+ * attack**, because an attacker's browser always sends one.
+ *
+ * @param {string|undefined} origin
+ */
+export function originAllowed(origin) {
+  if (origin === undefined || origin === '') return true;
+  // Compare origin+port only, so any port on loopback is acceptable.
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  const bare = `${parsed.protocol}//${parsed.hostname}`;
+  return ALLOWED_ORIGINS.includes(bare);
+}
+
+/** Read a request body, bounded so a hostile client cannot exhaust memory. */
+const readBody = (req, limit = 4 * 1024 * 1024) => new Promise((resolve, reject) => {
+  const chunks = [];
+  let size = 0;
+  req.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > limit) {
+      reject(new Error(`body exceeds ${limit} bytes`));
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  req.on('error', reject);
+});
+
+const sendJson = (res, status, body) => {
+  const text = JSON.stringify(body);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
+  res.end(text);
+};
+
+/**
+ * Build the request handler.
+ *
+ * Exported separately from `createMcpHttpServer` so a test can call it with fake request and response objects --
+ * **the same reason `handleMessage` is exported**: a socket is not needed to prove framing.
+ *
+ * @param {{deps: object}} options
+ */
+export function createRequestHandler({ deps }) {
+  return async (req, res) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
+
+    // 1. Origin, before anything else -- the specification makes this a MUST, and it must precede parsing.
+    if (!originAllowed(req.headers.origin)) {
+      sendJson(res, 403, { jsonrpc: '2.0', id: null, error: { code: -32600, message: `Origin ${JSON.stringify(req.headers.origin)} is not allowed`, data: { allowed: [...ALLOWED_ORIGINS] } } });
+      return;
+    }
+
+    /**
+     * 2. A discovery GET, so an operator can see what is here without speaking the protocol.
+     *
+     * **Gated on an explicit `?discover=1`, and that is not decoration.** A bare `GET /mcp` is what a client
+     * written against the removed stream endpoint sends, and it must be told the endpoint is gone rather than
+     * handed a document it will fail to parse as a stream. **Two different requests with two different answers,
+     * decided by a parameter rather than by guessing at the caller's intent.**
+     */
+    if (req.method === 'GET' && url.pathname === MCP_PATH && url.searchParams.has('discover')) {
+      sendJson(res, 200, {
+        server: { name: SERVER_NAME, version: SERVER_VERSION },
+        transport: 'streamable-http',
+        endpoint: MCP_PATH,
+        method: 'POST',
+        protocolVersions: [...SUPPORTED_VERSIONS],
+        tools: [...TOOL_NAMES],
+      });
+      return;
+    }
+
+    // 3. The GET *stream* endpoint was removed in 2026-07-28. Refused explicitly rather than 404, because a
+    //    client written against the older revision should learn why rather than guess.
+    if (req.method === 'GET') {
+      sendJson(res, 405, { jsonrpc: '2.0', id: null, error: { code: -32600, message: `the GET stream endpoint was removed in protocol revision 2026-07-28; POST to the MCP endpoint instead, or GET ${MCP_PATH}?discover for a description`, data: { endpoint: MCP_PATH } } });
+      return;
+    }
+
+    if (req.method !== 'POST') {
+      res.writeHead(405, { allow: 'POST, GET' });
+      res.end();
+      return;
+    }
+
+    if (url.pathname !== MCP_PATH) {
+      sendJson(res, 404, { jsonrpc: '2.0', id: null, error: { code: -32601, message: `no endpoint at ${url.pathname}; the MCP endpoint is ${MCP_PATH}` } });
+      return;
+    }
+
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch (error) {
+      sendJson(res, 413, { jsonrpc: '2.0', id: null, error: { code: -32600, message: error.message } });
+      return;
+    }
+
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch (error) {
+      // A parse failure is a JSON-RPC error response, not an HTTP 400: the transport delivered the bytes, and
+      // the protocol layer is what rejects them.
+      sendJson(res, 200, { jsonrpc: '2.0', id: null, error: { code: -32700, message: `invalid JSON: ${error.message}` } });
+      return;
+    }
+
+    const reply = await handleMessage(message, deps);
+    if (reply === null) {
+      // A notification: JSON-RPC forbids a response, and the HTTP binding says so with 202 Accepted.
+      res.writeHead(202);
+      res.end();
+      return;
+    }
+
+    if (url.searchParams.get('stream') === '1') {
+      // Request-scoped SSE, for a client written against the stream form. One frame: this server emits no
+      // notifications during a call, so there is nothing to interleave.
+      res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', connection: 'keep-alive' });
+      res.write(`event: message\ndata: ${JSON.stringify(reply)}\n\n`);
+      res.end();
+      return;
+    }
+
+    sendJson(res, 200, reply);
+  };
+}
+
+/**
+ * Start the server.
+ *
+ * **Binds 127.0.0.1 by default.** The specification says a local server SHOULD bind only to loopback, and a
+ * fleet-control endpoint reachable from the network is a different threat than one reachable from this machine.
+ *
+ * @param {{host?: string, port?: number, deps: object}} options
+ * @returns {Promise<{server: object, url: string, close: () => Promise<void>}>}
+ */
+export function createMcpHttpServer({ host = '127.0.0.1', port = 8766, deps }) {
+  const server = createServer(createRequestHandler({ deps }));
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      const address = server.address();
+      resolve({
+        server,
+        url: `http://${host}:${address.port}${MCP_PATH}`,
+        // A block body, not a concise arrow: `() => done()` returns `done()`'s value into a Promise executor,
+        // which nothing reads.
+        close: () => new Promise((done) => { server.close(() => { done(); }); }),
+      });
+    });
+  });
+}

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