@twinsearth/w2m-dsh-plugin 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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.5.0] — 2026-10-10
+
+The release that stops treating "the relay carried it" as the only answer for a machine behind a
+symmetric NAT. Measured before it: a dispatcher behind carrier-grade NAT (an iPhone hotspot, in this
+fleet) could not push an offer to a peer, the peer's result could not come back, and both halves fell
+to the relay on **every** task — `P2P_PUNCH_TIMEOUT` on the push, `transport: relay` on the result.
+
+### Added
+
+* **Simultaneous two-way punch.** The dispatcher publishes its punch in the offer it puts on the relay
+  (`POST /v1/task`'s `p2p`: `{mode, punch, candidates?}`), and the executor — which previously could
+  only wait in `accept()` — **dials the dispatcher back** on the same derived session, concurrently
+  with execution, bounded by the new `tuning.reverseDialTimeoutMs` (default **8000 ms**). Two NATs
+  that each open a mapping toward the other can then meet; one of them no longer has to be dialable.
+* **Reverse dial on the result path.** `planDirectDelivery` dials the dispatcher before falling back
+  to the relay, reusing the offer-time attempt when there was one (one bounded window per task, never
+  two) and starting its own when the channel died in between. This is the direction that works for a
+  symmetric-NAT machine: it dials *out*.
+* **The ladder is now recorded, rung by rung.** `p2p.opened_by` names the mechanism
+  (`dispatcher-punch` | `simultaneous-punch` | `result-reverse-dial`); `p2p.reverse_dial`,
+  `p2p.reverse_dial_ms` and `p2p.reverse_dial_reason` say whether a dial was attempted, what it cost
+  and why it lost (`P2P_REVERSE_DIAL_TIMEOUT`, `P2P_REVERSE_DIAL_FAILED`, `P2P_CHANNEL_LIVE`,
+  `P2P_NO_SESSION`, `P2P_NO_ORIGIN`, `P2P_DISABLED`, `P2P_UNREACHABLE`, `P2P_NO_TASK_ID`). The
+  mechanism is shared with the plugin (`punchSession()` lives in one place, imported, not copied).
+* **`deploy/networking/`** — the ladder written down: five rungs with what the ledger shows for each,
+  `acceptance.mjs` to measure which rung a real dispatch takes (it mints a real punch id, because a
+  body without one exercises neither new path), and `wireguard/server-setup.sh` for rung 4.
+
+### Fixed
+
+* **`P2PChannel.close()` could never send its BYE.** It set `closed = true` and *then* called
+  `sendFrame(BYE, …)`, and `sendFrame` refuses to send once closed — so the goodbye was unreachable
+  dead code. The measured consequence sat exactly on the path this release is about: `pushOffer`
+  closes the channel it pushed over, the executor kept a channel it believed was live, sent its result
+  into it and fell back only after `P2P_FRAGMENT_UNACKED … after 8 attempts` — **with no reverse dial
+  attempted**, because a channel for the task still existed. Change B alone could not have fixed the
+  measured failure; this is the other half. `close(reason, {silent: true})` exists for discarding a
+  duplicate local view of a live session (a simultaneous punch legitimately creates two channel
+  objects on one side, and a BYE there would tear down the peer's working channel).
+
+### Changed
+
+* **`transport` widens.** It is `p2p` when the direct path carried **either** half — the offer over a
+  channel **or** the result acknowledged over one — and `relay` only when the relay carried both.
+  `p2p.offer_path` keeps its exact meaning ("how the offer arrived"), which is what keeps the two
+  halves distinguishable: `transport: p2p` + `offer_path: relay` is a result that found its own way
+  home. Anything reading `transport` alone should read `offer_path`/`opened_by` beside it.
+
+### Compatibility
+
+No protocol version bump: `envelope_version` stays `1.0`, the new keys live inside the optional `p2p`
+object, and `transport`'s value set is unchanged. A v0.4.x relay stores and republishes the extended
+object **verbatim**, and a v0.4.x agent ignores keys it does not know — both are pinned by tests, on
+both sides, rather than argued from intent.
+
+### Verification
+
+* Required suites: **424 tests, 421 pass, 1 fail, 2 skipped** (baseline 407/404/1/2 → +17 new tests,
+  all passing). The failure is the pre-existing bundled-python case.
+* Every other suite: 340 tests, 335 pass, 2 fail (the pre-existing `pipeline-e2e` cases).
+* `eslint .`: 0 errors, the same 79 pre-existing warnings.
+* **Not verified, and it matters:** every punch in the suites is loopback, which crosses no NAT, and
+  no genuine v0.4.x binary was run — compatibility is argued from the relay's validation code plus
+  round-trip tests. Real traversal needs a fleet running this build; that is the next measurement, not
+  a claim in this entry.
+
+## [0.4.9] — 2026-10-10
+
+### Fixed
+
+* **The Windows supervisor silently dropped every `-AgentArgs` value.** `install-service.ps1` writes
+  `agentArgs` into `agent.json`, and `ConvertTo-Json` collapses a single-element array to a string —
+  while the supervisor's passthrough only handled an array. So `-AgentArgs '--p2p-mode auto'` was
+  accepted, written, and then ignored, and the agent ran on its defaults. Nothing failed; the field
+  simply had no effect. It now accepts both shapes (a string is split on whitespace) — the same class
+  of bug as the camelCase key mismatch fixed in v0.4.4: **a config field that is read but not
+  understood is indistinguishable from one that was never set.**
+* Found while pinning this machine's punch port (`--p2p-port 51820`), which was the first agent
+  argument whose absence would have been visible — that is what exposed the dropped-arguments path.
+
+### Notes
+
+* No protocol change, and no behavioural change for an `agentArgs` that was already an array (what
+  the installer writes for two or more arguments). This makes the documented `-AgentArgs` real.
+
 ## [0.4.8] — 2026-10-09
 
 ### Added

package/deploy/networking/README.md

@@ -0,0 +1,130 @@
+# Networking: how the fleet gets from one machine to another
+
+This directory is about the one thing that decides whether a fleet is pleasant or infuriating:
+**which path the bytes actually take**, and what to do when the direct one is not available.
+
+The control plane is never in question. Devices, tasks, leases, results and the ledger all go through
+the relay on the shared server (`http://202.182.123.154:8787`), because that is what makes a task
+*auditable*: one place holds what was asked, who took it, what came back and by which path. The data
+plane is where the interesting failures live, so it is arranged as a ladder — each rung is tried,
+and a rung that cannot be opened is recorded with its reason rather than guessed at.
+
+## The ladder
+
+| rung | mechanism | what the ledger shows | what it costs |
+|---|---|---|---|
+| 1 | a channel is already open | `transport: p2p`, `offer_path: p2p` | nothing |
+| 2 | **simultaneous punch (A)** — the dispatcher punches, and the executor dials the same session it was told about | `transport: p2p`, `offer_path: p2p` | two NATs must agree, or one side must be dialable |
+| 3 | **reverse dial (B)** — no channel existed, so the receiving side dialled out to deliver the result | `transport: p2p`, `offer_path: relay` | the result found its own way home while the offer needed the relay |
+| 4 | **tunnel (C)** — WireGuard on the shared server, and every machine gets a routable `10.66.0.x` | `transport: p2p` — **indistinguishable from rung 1–2** | see the warning below |
+| 5 | relay | `transport: relay` + a `p2p.reason` naming why | the relay carries the data |
+
+**Rung 4 is the one to read carefully.** WireGuard has no NAT traversal of its own — that is exactly
+what Tailscale adds on top of it (disco/DERP) and what rungs 2 and 3 are for. So with two machines
+behind NAT, traffic between their `10.66.0.x` addresses is **forwarded through the VPS**. The ledger
+will say `p2p`, and it will not be lying: from W2M's point of view that socket is direct. But the
+bytes cross a server. If you asked for "the data goes peer to peer", rung 4 does not satisfy that —
+it satisfies "the fleet works regardless of NAT, encrypted, with no third party", which is a
+different and still useful promise. Rung 2/3 are the ones that make the data path direct.
+
+## What is measured, and by what
+
+`acceptance.mjs` dispatches a real command to every online machine through the relay's HTTP API and
+then reads back what each machine recorded. It is deliberately blunt: it does not synthesise packets
+or poke at NATs itself, because a script that punched its own holes would prove that the script can
+punch, which nobody doubts.
+
+```bash
+node deploy/networking/acceptance.mjs \
+  --rabbit http://202.182.123.154:8787 \
+  --token <operator token> \
+  --project /path/to/the/fleet/project \
+  --command 'git rev-parse HEAD' \
+  --require-direct          # optional: exit non-zero if any machine lands on rung 5
+```
+
+Requirements and behaviour worth knowing before you read its output:
+
+* **Both credentials.** Dispatching needs the **operator** token (`--token`, or
+  `W2M_OPERATOR_TOKEN`); reading a task back is a device-scoped read and needs the **device** token
+  from `device.json` (`--state-dir`, default `$DSH_HOME/xclient`). Measured: the operator token alone
+  answers `401 missing or invalid device_token`. The split is deliberate — the credential that can
+  order work around cannot also read every machine's results.
+* **Every machine must be on the same commit.** The script fingerprints `--project` with
+  `git-temp-index-tree/v1` and sends it as the anchor; machines that are not there refuse or report
+  `unverifiable`. That is the mechanism working, not the script failing.
+* **`--command` takes plain text** (`--command 'git rev-parse HEAD'`). A JSON array is the natural
+  spelling and it does not survive a Windows command line: `'["git","rev-parse","HEAD"]'` arrives as
+  `[git,rev-parse,HEAD]`. The script still accepts JSON when the shell passes it through intact.
+* **Transient network failures retry.** An acceptance run that reported "the fleet is broken" because
+  one TCP connect to another continent timed out would be worse than useless.
+* **What it exercises is rungs 3 and 5 (and 2 once A lands).** Because the script dispatches *through
+  the relay*, the offer arrives by relay — which is exactly the situation the reverse-dial work
+  addresses. The dispatcher-side punch is performed by the plugin's own `w2m_run`, which pushes to
+  each peer directly before falling back. So the two commands answer different questions:
+
+  | command | question |
+  |---|---|
+  | `w2m_run` + `w2m_wait` (the DSH tools) | what does the whole delivery path do, including the dispatcher's push? |
+  | `acceptance.mjs` | what do the **machines** do when the offer arrives by relay? |
+
+  Run both. If `w2m_run` shows `p2p` while `acceptance.mjs` shows rung 5 for the same pair, the
+  dispatcher's push is working and the receiving side is not dialling back — which is precisely the
+  gap rungs 2 and 3 close.
+
+## Baseline, measured 2026-10-10 (before A/B landed)
+
+```
+machine      outcome  exit  rung  path   offer  note
+jp-shared    ok       0     5     relay  relay  relay fallback -- P2P_NO_CANDIDATES ...
+win-desktop  ok       0     5     relay  relay  relay fallback -- P2P_NO_CANDIDATES ...
+macmini      ok       0     5     relay  relay  relay fallback -- P2P_NO_CANDIDATES ...
+```
+
+The same fleet, dispatched through the plugin's `w2m_run` instead (which pushes directly), gets
+`p2p` for the two machines that can be dialled. Both readings are true; they are readings of
+different layers. Keep the baseline above and re-run it after the reverse-dial work lands: rung 5
+becoming rung 2 or 3 for a machine that used to fall back is the evidence that it worked.
+
+## Rung 4: the WireGuard hub on the shared server
+
+Set up and running on the Tokyo VPS. `deploy/networking/wireguard/server-setup.sh` is the whole
+thing: it generates keys once (and reuses them afterwards, so a client that already has a config
+keeps working), writes `/etc/wireguard/wg0.conf`, opens the port and starts the hub. It prints a
+client config on demand — that is the only thing a client needs from this host:
+
+```bash
+bash server-setup.sh                    # on the always-on host, as root
+bash server-setup.sh --client macmini   # prints a config to paste into the WireGuard app
+```
+
+```
+interface wg0   listening 51820/udp   server 10.66.0.1/24
+peers: 10.66.0.2 (win-desktop), 10.66.0.3 (macmini)      ufw: 51820/udp allowed
+```
+
+Each client routes **only** `10.66.0.0/24`, so nothing of your ordinary traffic can travel through
+the VPS and no DNS is touched. Client install: Windows `winget install WireGuard.WireGuard` (needs
+elevation) then import the `.conf`; macOS the WireGuard app or `brew install --cask wireguard-tools`.
+Verify from the server with `wg show`: a `latest handshake` line per peer is the proof it is up.
+
+Two port notes, both learned the hard way:
+
+* **51820 is WireGuard's default, so do not give it to anything else.** The W2M agent on this machine
+  was briefly pinned to 51820 (to match an inbound firewall rule) and was moved to **41235** when the
+  tunnel arrived.
+* **An inbound firewall rule is not a route.** A rule for `51820/udp` on a machine behind
+  carrier-grade NAT cannot make that machine dialable: the carrier drops the packet before the host
+  firewall ever sees it. Rules matter again the moment the machine has a real mapping (a normal
+  router, or the tunnel).
+
+## The honesty section
+
+* **Rung 5 is not a failure.** A task that completes over the relay completed. The ledger naming the
+  path is the feature; pretending every path is direct would be the bug.
+* **A `p2p` reading on a tunnel (rung 4) does not mean the bytes avoided a server.** See above.
+* **A symmetric NAT cannot be dialled into, ever.** Not by this project, not by Tailscale. What can
+  be done is to have the symmetric side dial *out* (rungs 2 and 3) or to stop being behind it
+  (rung 4, or another network).
+* **Nothing here injects prompts into another machine's model session.** The fleet transports
+  commands, their output, and the comparison between them.

package/deploy/networking/acceptance.mjs

@@ -0,0 +1,306 @@
+// ============================================================================
+//  acceptance.mjs -- does the fleet actually take the direct path?
+// ============================================================================
+//
+//  This script answers one question with evidence instead of optimism: for a real
+//  dispatched task, which rung of the delivery ladder did each machine land on, and
+//  why. It dispatches a command to every online machine through the relay's own
+//  HTTP API, waits for the aggregate, and maps each machine's recorded facts
+//  (`transport`, `p2p.offer_path`, `p2p.reason`) onto the ladder in README.md.
+//
+//  THE LADDER, and what the ledger calls it:
+//
+//    1  live channel       transport p2p + offer_path p2p     (a channel was already open)
+//    2  simultaneous punch transport p2p + offer_path p2p     (both sides dialled -- A)
+//    3  reverse dial       transport p2p + offer_path relay   (the result found its own way back -- B)
+//       ...and the result of a level-3 task may itself report result_path p2p in the agent's log;
+//       that log is on the machine, which is why this script reads the aggregate the relay keeps.
+//    4  tunnel             transport p2p on a WireGuard address. NOT DETECTABLE FROM THE LEDGER:
+//                          level 4 looks exactly like level 1-2 from here. See README.md -- a
+//                          tunnel makes the fleet reachable, and the bytes still cross the VPS.
+//    5  relay              transport relay                   (the fallback, always available)
+//
+//  USAGE
+//
+//    node deploy/networking/acceptance.mjs \
+//      --rabbit http://202.182.123.154:8787 \
+//      --token <operator token> \
+//      --project /path/to/the/fleet/project \
+//      --command 'git rev-parse HEAD'
+//
+//    --require-direct   exit non-zero when any machine falls to the relay, so this can
+//                       be a gate rather than a report
+//    --json             print the aggregate as JSON instead of a table
+//
+//  WHY --command TAKES PLAIN TEXT
+//
+//  A JSON array is the natural spelling and it does not survive the trip: measured on Windows,
+//  `--command '["git","rev-parse","HEAD"]'` arrives as `[git,rev-parse,HEAD]` -- the quotes are
+//  consumed before the script ever sees them (the same trap that produced the config file in
+//  deploy/windows). So plain whitespace-separated text is the documented form; a string that does
+//  start with `[` is still parsed as JSON for callers whose shell does not mangle it.
+//
+//  WHAT IT DELIBERATELY DOES NOT DO
+//
+//  It does not test the punch itself, inject packets, or bypass the relay. The punch is the
+//  protocol's business; this only reads what the protocol recorded after a real task. A script
+//  that synthesised its own punches would prove that the script can punch, which nobody doubts.
+// ============================================================================
+import { headCommit, treeFingerprint } from '../../src/agent/git.mjs';
+import { mintPunchId } from '../../src/agent/p2p.mjs';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const USAGE = `acceptance.mjs --rabbit <url> [--token <operator token>] [--project <dir>]
+               [--command '<json argv>'] [--timeout-ms <n>] [--poll-ms <n>]
+               [--require-direct] [--json] [--state-dir <dir>]`;
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) out[key] = true;
+    else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const rabbit = String(args.rabbit ?? 'http://202.182.123.154:8787').replace(/\/+$/, '');
+const token = typeof args.token === 'string' ? args.token : (process.env.W2M_OPERATOR_TOKEN ?? '');
+const project = String(args.project ?? process.cwd());
+const timeoutMs = Number(args['timeout-ms'] ?? 180_000);
+const pollMs = Number(args['poll-ms'] ?? 1500);
+const requireDirect = args['require-direct'] === true;
+const asJson = args.json === true;
+const rawCommand = typeof args.command === 'string' ? args.command.trim() : '';
+const commandArgv = rawCommand === ''
+  ? ['git', 'rev-parse', 'HEAD']
+  : rawCommand.startsWith('[')
+    ? JSON.parse(rawCommand)
+    : rawCommand.split(/\s+/).filter(Boolean);
+
+if (!token) {
+  console.error('no operator token: pass --token or set W2M_OPERATOR_TOKEN (the relay prints it once)');
+  process.exit(2);
+}
+if (!Array.isArray(commandArgv) || commandArgv.length === 0) {
+  console.error("--command must be a command, e.g. --command 'git rev-parse HEAD' (or a JSON array)");
+  process.exit(2);
+}
+
+const headers = { 'content-type': 'application/json', authorization: `Bearer ${token}` };
+
+/**
+ * Reading a task back is a DEVICE-scoped read, so it needs the device token; dispatching is what the
+ * operator token is for. Measured: `GET /v1/tasks/<id>` carrying the operator token answers
+ * `401 UNAUTHORIZED: missing or invalid device_token`. The split is deliberate -- the credential that
+ * can order work around cannot also read every machine's results -- so this script carries both,
+ * exactly as the plugin does.
+ */
+async function get(path) {
+  // Transient transport failures are the norm on a link between continents (measured: this exact
+  // script dispatched fine and then had its first poll time out connecting to the relay). An
+  // acceptance run that reports "the fleet is broken" because one TCP connect timed out would be
+  // worse than useless, so polls retry; an HTTP error still fails immediately, because that is the
+  // relay telling us something.
+  let lastError = null;
+  for (let attempt = 1; attempt <= 5; attempt += 1) {
+    try {
+      const res = await fetch(`${rabbit}${path}`, {
+        headers: { accept: 'application/json', authorization: `Bearer ${deviceToken ?? token}` },
+      });
+      if (!res.ok) {
+        const text = (await res.text()).slice(0, 200);
+        if (res.status === 401) {
+          throw new Error(
+            `GET ${path} -> 401 ${text}\n` +
+              'reading a task needs a device token: point --state-dir at the directory holding device.json',
+          );
+        }
+        throw new Error(`GET ${path} -> ${res.status} ${text}`);
+      }
+      return res.json();
+    } catch (error) {
+      lastError = error;
+      const transient = error?.cause?.code !== undefined || /fetch failed|timeout/i.test(String(error?.message ?? ''));
+      if (!transient) throw error;
+      await new Promise((resolve) => {
+        setTimeout(resolve, 2000 * attempt);
+      });
+    }
+  }
+  throw new Error(`GET ${path} failed after 5 attempts: ${lastError?.message ?? lastError}`);
+}
+
+/** This machine's own identity, when it has one -- `origin_machine_id` must be a real machine. */
+function localIdentity() {
+  const stateDir = typeof args['state-dir'] === 'string'
+    ? String(args['state-dir'])
+    : join(process.env.DSH_HOME ?? join(process.env.USERPROFILE ?? process.env.HOME ?? '.', '.dsh'), 'xclient');
+  try {
+    const device = JSON.parse(readFileSync(join(stateDir, 'device.json'), 'utf8').replace(/^\uFEFF/, ''));
+    return {
+      machine_id: device.machine_id ?? null,
+      name: device.machine_name ?? device.name ?? null,
+      device_token: typeof device.device_token === 'string' && device.device_token !== '' ? device.device_token : null,
+    };
+  } catch {
+    return { machine_id: null, name: null, device_token: null };
+  }
+}
+
+/**
+ * One machine's recorded path, read as a rung of the ladder.
+ *
+ * `opened_by` is the precise answer when the build provides it: it names which mechanism opened the
+ * channel (`dispatcher-punch`, `simultaneous-punch`, `result-reverse-dial`). Without it, `transport`
+ * plus `offer_path` still separate "the result found its own way back" (rung 3) from "the relay
+ * carried everything" (rung 5) -- that is why the two halves are recorded separately and why this
+ * script never reads `transport` alone.
+ */
+function classify(machine) {
+  const transport = machine.transport ?? null;
+  const offerPath = machine.p2p?.offer_path ?? null;
+  const openedBy = machine.p2p?.opened_by ?? null;
+  const reason = machine.p2p?.reverse_dial_reason ?? machine.p2p?.reason ?? null;
+  if (machine.outcome === 'ok' && transport === 'p2p') {
+    if (openedBy === 'result-reverse-dial') return { rung: 3, label: 'reverse dial (B)', reason };
+    if (openedBy === 'simultaneous-punch') return { rung: 2, label: 'simultaneous punch (A)', reason };
+    if (openedBy === 'dispatcher-punch') return { rung: 2, label: 'dispatcher punch', reason };
+    return {
+      rung: offerPath === 'relay' ? 3 : 2,
+      label: offerPath === 'relay' ? 'reverse dial (offer by relay, result direct)' : 'direct channel',
+      reason,
+    };
+  }
+  if (machine.outcome === 'ok' && transport === 'relay') return { rung: 5, label: 'relay fallback', reason };
+  if (machine.outcome === 'ok') return { rung: null, label: `ok over ${transport ?? 'an unknown path'}`, reason };
+  return { rung: null, label: `${machine.outcome ?? 'no outcome'}`, reason: machine.refusal_reason ?? reason };
+}
+
+const identity = localIdentity();
+// Declared before the first read: reading a task needs the device token, and this machine's own
+// device.json is where it lives (`--state-dir` when it is somewhere else).
+const deviceToken = identity.device_token;
+
+const health = await get('/healthz');
+const devices = health.devices ?? health.device_count ?? '?';
+
+const commit = await headCommit({ cwd: project });
+const tree = await treeFingerprint({ cwd: project });
+if (!commit || !tree.fingerprint) {
+  console.error(`cannot fingerprint ${project}: commit=${commit} tree=${tree.fingerprint} error=${tree.error ?? 'none'}`);
+  console.error('every machine is compared against these anchors, so the project must be a git work tree');
+  console.error('sitting at the same commit as the machines you are testing.');
+  process.exit(2);
+}
+
+const cwdRel = '.';
+const body = {
+  mode: 'replicate',
+  command_argv: commandArgv,
+  cwd_rel: cwdRel,
+  index_total: 1,
+  timeout_ms: timeoutMs,
+  write: false,
+  base_commit: commit,
+  base_tree: tree.fingerprint,
+  requirements: { toolchain: {}, platform: [] },
+  compare_policy: { strip_ansi: true, normalize_crlf: true, strip_trailing_blank_lines: true, redact: [] },
+  halt: 'never',
+  created_by: identity.name ?? 'acceptance',
+  // THE PUNCH FACTS ARE THE WHOLE POINT OF THIS SCRIPT.
+  //
+  // A v0.4.x-style body (`p2p: {mode}`) exercises neither A nor B: the executor only dials back when
+  // the offer actually publishes a punch id (or candidates), so a task without one lands on rung 5 by
+  // construction and would make this script report the old behaviour forever. Measured, by the very
+  // work that added the rungs. `mintPunchId` is imported from the node's own module rather than
+  // re-implemented, so the script mints exactly what a real dispatcher mints.
+  p2p: { mode: 'auto', punch: mintPunchId() },
+  ...(identity.machine_id ? { origin_machine_id: identity.machine_id } : {}),
+};
+
+const created = await fetch(`${rabbit}/v1/task`, { method: 'POST', headers, body: JSON.stringify(body) });
+if (!created.ok) {
+  console.error(`POST /v1/task -> ${created.status} ${(await created.text()).slice(0, 300)}`);
+  process.exit(2);
+}
+const { task_id: taskId, seq } = await created.json();
+if (!asJson) {
+  console.log(`task ${taskId} (seq ${seq}) -- ${commandArgv.join(' ')}`);
+  console.log(`anchors  ${commit.slice(0, 12)} / ${tree.fingerprint.slice(0, 12)}  (${tree.fingerprint_algo ?? 'git-temp-index-tree/v1'})`);
+  console.log(`relay    ${rabbit}  devices ${devices}\n`);
+}
+
+const TERMINAL = new Set(['done', 'refused', 'expired', 'failed']);
+let aggregate = null;
+const started = Date.now();
+while (Date.now() - started < timeoutMs) {
+  const status = await get(`/v1/tasks/${encodeURIComponent(taskId)}`);
+  aggregate = status.aggregate;
+  const leases = status.leases ?? [];
+  if (leases.length > 0 && leases.every((lease) => TERMINAL.has(lease.state))) break;
+  if (aggregate && aggregate.state && aggregate.state !== 'pending' && leases.length === 0) break;
+  await new Promise((resolve) => {
+    setTimeout(resolve, pollMs);
+  });
+}
+
+if (!aggregate) {
+  console.error('no aggregate came back before the timeout');
+  process.exit(1);
+}
+
+if (asJson) {
+  console.log(JSON.stringify({ task_id: taskId, anchors: { base_commit: commit, base_tree: tree.fingerprint }, aggregate }, null, 2));
+} else {
+  // `|| 'unknown'` rather than `??`: an empty `states` array joins to '' and `??` would happily
+  // print nothing, which is the one thing a verdict line must not do.
+  const verdict = aggregate.state ?? aggregate.verdict ?? ((aggregate.states ?? []).join(', ') || 'unknown');
+  console.log(`verdict  ${verdict}\n`);
+  const rows = (aggregate.machines ?? []).map((machine) => {
+    const verdict = classify(machine);
+    return {
+      machine: machine.machine_name ?? machine.machine_id,
+      outcome: machine.outcome ?? '',
+      exit: machine.exit_code ?? '',
+      rung: verdict.rung ?? '-',
+      path: machine.transport ?? '-',
+      offer: machine.p2p?.offer_path ?? '-',
+      note: verdict.label + (verdict.reason ? ` -- ${verdict.reason}` : ''),
+    };
+  });
+  const width = Math.max(...rows.map((row) => row.machine.length), 7);
+  console.log(`${'machine'.padEnd(width)}  outcome  exit  rung  path   offer  note`);
+  for (const row of rows) {
+    console.log(
+      `${String(row.machine).padEnd(width)}  ${String(row.outcome).padEnd(7)}  ${String(row.exit).padEnd(4)}  ` +
+        `${String(row.rung).padEnd(4)}  ${String(row.path).padEnd(5)}  ${String(row.offer).padEnd(5)}  ${row.note}`,
+    );
+  }
+  const ladderRungs = rows.map((row) => row.rung).filter((rung) => typeof rung === 'number');
+  console.log(
+    `\nladder: ${ladderRungs.length > 0 ? ladderRungs.join(', ') : 'no rung recorded'}  ` +
+      `(5 = relay; see deploy/networking/README.md for what each rung claims)`,
+  );
+  if (aggregate.notes?.length) for (const note of aggregate.notes) console.log(`note: ${note}`);
+}
+
+const fellBack = (aggregate.machines ?? []).some((machine) => classify(machine).rung === 5);
+const incomplete = (aggregate.machines ?? []).some((machine) => machine.outcome !== 'ok');
+if (requireDirect && (fellBack || incomplete)) {
+  console.error('\n--require-direct: at least one machine did not take a direct path (or did not answer)');
+  process.exit(1);
+}

package/deploy/networking/wireguard/server-setup.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# ============================================================================
+#  WireGuard hub for a W2M fleet -- rung 4 of the ladder in ../README.md
+# ============================================================================
+#
+#  WHAT THIS IS FOR, AND WHAT IT IS NOT
+#
+#  It makes every machine reachable by a stable address (10.66.0.x) no matter what its NAT does,
+#  encrypted, with no third-party coordination service. That is rung 4.
+#
+#  It is NOT a direct path between two machines behind NAT. WireGuard has no NAT traversal: with
+#  both machines as peers of this hub, their traffic to each other is forwarded through this VPS.
+#  Direct paths are rungs 2 and 3 of the ladder -- the simultaneous punch and the reverse dial --
+#  which live in the plugin, not here. Stated plainly because a tunnel that reports `p2p` in the
+#  ledger while the bytes cross a server is exactly the kind of thing that misleads an operator.
+#
+#  RUN IT ON THE ALWAYS-ON HOST (the shared server), as root, once:
+#
+#    bash server-setup.sh                 # keys are generated if absent, config is rewritten, wg0 up
+#    bash server-setup.sh --client mac    # print one client config to paste into the WireGuard app
+#
+#  Idempotent: re-running keeps existing keys (so paired clients keep working) and only rewrites the
+#  hub config and its peers.
+# ============================================================================
+set -euo pipefail
+
+HUB_ADDRESS="${HUB_ADDRESS:-10.66.0.1/24}"
+LISTEN_PORT="${LISTEN_PORT:-51820}"
+KEYS=/etc/wireguard/keys
+WG=/etc/wireguard/wg0.conf
+# Client name -> tunnel address. Add a line here to add a machine.
+CLIENTS=("win-desktop:10.66.0.2" "macmini:10.66.0.3")
+
+# 51820 is WireGuard's default and the fleet's own punch port is deliberately somewhere else
+# (41235 on this fleet) so the two never contend.
+if [ "$(id -u)" != "0" ]; then echo "run as root (this writes /etc/wireguard and edits the firewall)" >&2; exit 1; fi
+
+export DEBIAN_FRONTEND=noninteractive
+command -v wg >/dev/null 2>&1 || { apt-get update -qq; apt-get install -y -qq wireguard wireguard-tools >/dev/null; }
+
+umask 077
+mkdir -p "$KEYS"
+[ -f "$KEYS/server.key" ] || wg genkey > "$KEYS/server.key"
+wg pubkey < "$KEYS/server.key" > "$KEYS/server.pub"
+for entry in "${CLIENTS[@]}"; do
+  name="${entry%%:*}"
+  [ -f "$KEYS/$name.key" ] || wg genkey > "$KEYS/$name.key"
+  wg pubkey < "$KEYS/$name.key" > "$KEYS/$name.pub"
+done
+
+# Print one client's config and exit -- the only thing a client needs from this host.
+if [ "${1:-}" = "--client" ]; then
+  name="${2:-}"
+  address=""
+  for entry in "${CLIENTS[@]}"; do [ "${entry%%:*}" = "$name" ] && address="${entry##*:}"; done
+  [ -n "$address" ] || { echo "unknown client '$name'; known: ${CLIENTS[*]%%:*}" >&2; exit 1; }
+  endpoint="${ENDPOINT:-$(curl -fsS -m 8 https://api.ipify.org)}"
+  cat <<EOF
+[Interface]
+# $name -- rung 4 of the W2M delivery ladder (see deploy/networking/README.md)
+PrivateKey = $(cat "$KEYS/$name.key")
+Address = $address/24
+# No DNS line on purpose: only $HUB_ADDRESS is routed, so your resolver stays untouched.
+
+[Peer]
+PublicKey = $(cat "$KEYS/server.pub")
+Endpoint = $endpoint:$LISTEN_PORT
+AllowedIPs = $(echo "$HUB_ADDRESS" | cut -d/ -f1 | awk -F. '{print $1"."$2"."$3".0/24"}')
+PersistentKeepalive = 25
+EOF
+  exit 0
+fi
+
+{
+  echo "# W2M rung 4: a private hub so the fleet is reachable whatever the NATs do."
+  echo "# Traffic between clients is forwarded here -- WireGuard does not punch. See README.md."
+  echo "[Interface]"
+  echo "Address = $HUB_ADDRESS"
+  echo "ListenPort = $LISTEN_PORT"
+  echo "PrivateKey = $(cat "$KEYS/server.key")"
+  echo "# No PostUp MASQUERADE: clients route only the tunnel subnet here, so nothing needs NATing"
+  echo "# and none of their other traffic can leak through this host."
+  echo "SaveConfig = false"
+  echo
+  for entry in "${CLIENTS[@]}"; do
+    name="${entry%%:*}"; address="${entry##*:}"
+    echo "[Peer]"
+    echo "# $name"
+    echo "PublicKey = $(cat "$KEYS/$name.pub")"
+    echo "AllowedIPs = $address/32"
+    echo
+  done
+} > "$WG"
+chmod 600 "$WG"
+
+sysctl -qw net.ipv4.ip_forward=1
+grep -q '^net.ipv4.ip_forward=1' /etc/sysctl.conf || echo 'net.ipv4.ip_forward=1' >> /etc/sysctl.conf
+command -v ufw >/dev/null 2>&1 && ufw allow "$LISTEN_PORT/udp" >/dev/null || true
+
+systemctl enable wg-quick@wg0 >/dev/null 2>&1 || true
+systemctl restart wg-quick@wg0
+sleep 2
+systemctl is-active wg-quick@wg0
+wg show
+echo
+echo "client configs: bash $0 --client <name>   (known: ${CLIENTS[*]%%:*})"

package/deploy/windows/w2m-agent-supervisor.mjs

@@ -128,7 +128,12 @@ const consumed = new Set([
 ]);
 const passthrough = [];
 const fileAgentArgs = file.agentArgs ?? file['agent-args'];
+// BOTH SHAPES, because both happen. The installer writes an array, but `ConvertTo-Json` collapses a
+// single-element array to a string -- and this only handled the array, so `--p2p-mode auto` was
+// silently dropped and the agent ran on its defaults. Silent, because an ignored field is not an
+// error. A string is split on whitespace instead.
 if (Array.isArray(fileAgentArgs)) passthrough.push(...fileAgentArgs.map(String));
+else if (typeof fileAgentArgs === 'string') passthrough.push(...fileAgentArgs.split(/\s+/).filter(Boolean));
 if (typeof args['agent-args'] === 'string') passthrough.push(...args['agent-args'].split(/\s+/).filter(Boolean));
 for (const [key, value] of Object.entries(args)) {
   if (consumed.has(key)) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.4.8",
+  "version": "0.5.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",