@twinsearth/w2m-dsh-plugin 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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.2] — 2026-10-10
+
+### Fixed
+
+* **The supervisor now says what it is doing, in a file.** A death that arrives with the console
+  cannot be logged from inside the process it kills — the log simply stops — so the supervisor
+  records `supervisor-heartbeat.json` (written atomically) with its state (`running` / `backoff` /
+  `degraded` / `stopped`), the child pid, restarts within ten minutes, the last exit code, and a note
+  that `3221225786` is `0xC000013A` rather than a crash of the agent logic. After three exits inside
+  ten minutes the state becomes `degraded` and the backoff grows to five minutes: not "give up", but
+  "stop hammering and say so", so the fleet sees a machine that is present and unwell instead of one
+  that vanished.
+* **Orphan agents are reaped at start.** Detaching the agent (v0.5.1) is what stops a console
+  teardown from taking the machine off the fleet, and it leaked: three agents with one identity were
+  found running at once, the newest unable to bind the punch port (`P2P_BIND_FAILED: EADDRINUSE
+  0.0.0.0:41235`) because an orphan held it, while `MultipleInstances IgnoreNew` kept a fresh
+  supervisor from starting at all. The heartbeat names the last child, so a new supervisor terminates
+  that pid before it spawns anything.
+
+### Added
+
+* **`docs/AUDIT.md`** — what is implemented, what is running and how it works, with every claim
+  labelled `[M]` measured live, `[T]` asserted by the suites, or `[?]` **not verified**. It records
+  the uncomfortable half on purpose: A and B have no live proof yet, the macOS machine's state is
+  unconfirmed, the WireGuard hub has never seen a handshake, the session-0 service has never been
+  executed, and the link from the Windows machine to the relay is intermittently down. Its last
+  section is the commands to re-run each check, so the next reader need not trust the snapshot.
+
+### Notes
+
+* This release exists because `deploy/` and `docs/` are inside the published package: after v0.5.1 the
+  tag and the tarball had drifted, and a release is the only honest way to close that.
+* No runtime change to the eight tools.
+## [0.5.1] — 2026-10-10
+
+### Fixed
+
+* **The agent no longer dies with its console.** Measured twice on the fleet: the whole process
+  tree — supervisor and agent together — was killed with code `0xC000013A` (`STATUS_CONTROL_C_EXIT`,
+  its console went away), the log ended mid-sentence, and Task Scheduler did not restart it, so the
+  fleet silently lost the machine. A supervisor that shares the console dies with the thing it
+  supervises, which was its one job. The supervisor now spawns the agent with `detached: true` and
+  **file-descriptor stdio** — never `inherit`, never pipes, because a detached child writing into a
+  pipe whose reader has died blocks instead of failing loudly.
+* **The scheduled task heals itself, without elevation.** The interactive mode now also registers a
+  repeating trigger (default every 5 minutes) which, with `MultipleInstances IgnoreNew`, means "be
+  running, or start": a death from any cause is repaired at the next tick. It exists because
+  `RestartCount 999` was measured not to fire at all.
+
+### Added
+
+* **`deploy/networking/LESSONS.md`** — a read-only study of 2dust/v2rayN (GPL-3.0, so description
+  with citations only and nothing copied) recording the transport disciplines this project was
+  missing, and the decision it changed: **no TUN/VPN mode.** v2rayN never creates an adapter itself
+  and contains no peer-to-peer anywhere; a tunnel is hub-and-spoke by construction, so it would make
+  our "the data path is peer-to-peer" claim false for exactly the traffic a tunnel exists to carry.
+
+### Notes
+
+* A regression introduced and caught during the fix is recorded in the code: the first version also
+  called `child.unref()`, which leaves the supervisor with no handle at all, so its event loop
+  drains and it exits immediately after spawning the agent. The evidence was that no supervisor
+  process existed — found while looking for a different property.
+* Verified on the machine that had the defect: supervisor and agent both present, and killing the
+  supervisor leaves the agent alive with its punch socket still bound (`0.0.0.0:41235`).
+* Also included: the test fix for `test/outbound-only.test.mjs`, whose port was being read from the
+  timestamp rather than from the field that states it (commit `57dbc5f`).
 ## [0.5.0] — 2026-10-10
 
 The release that stops treating "the relay carried it" as the only answer for a machine behind a

package/deploy/networking/LESSONS.md

@@ -0,0 +1,90 @@
+# What a mature proxy client taught us about transport — and what it did not
+
+This file records a **read-only study of [2dust/v2rayN](https://github.com/2dust/v2rayN)**, done to
+find out which transport disciplines this project is missing. It exists because the study's
+conclusions are only worth anything if they can be checked, and because one of them is a decision we
+would otherwise have made wrongly.
+
+## Provenance and licence
+
+* Read at branch **`master`**, commit **`b501efbc45bca3c465df99af7d4ec092c2f4c40f`**. Paths below are
+  relative to that clone, so every claim can be checked at that revision.
+* **v2rayN is GPL-3.0** (`LICENSE`, the verbatim GNU GPL v3 text; no other licence statement in the
+  repository). **This project is MIT.** No code, text or file was copied from it — not a fragment,
+  not a paraphrase of code. Everything below is *description with citations*, and any implementation
+  we write from it is our own.
+* We did not modify v2rayN, and we did not open issues or pull requests against it.
+
+## The decision this study changed: do not add a TUN/VPN mode
+
+The tempting idea was "add a VPN so two machines behind hard NAT can reach each other". The study
+says plainly that this does not do what it sounds like:
+
+* v2rayN never creates an adapter or touches the routing table itself; it writes a declarative config
+  and the external core (Xray/sing-box/mihomo) does the privileged work
+  (`v2rayN/ServiceLib/Services/CoreConfig/V2ray/V2rayInboundService.cs:75-77`;
+  `Sample/tun_singbox_inbound:10-13`).
+* Its local inbound is loopback-only (`Sample/SampleInbound:5`), and every path is client → remote
+  server. There is **no peer-to-peer anywhere in the codebase**: no hole punching, no candidate
+  exchange, no relay of our kind — a grep for the concepts returns nothing, and the only STUN code is
+  a UDP reachability *diagnostic* (`ServiceLib.UdpTest/Tester/StunService.cs:8-48`), not a data path.
+* So a TUN interface is **hub-and-spoke by construction**: traffic between two of our machines would
+  transit the hub. Our promise — "the data path is peer-to-peer" — would become **false for exactly
+  the traffic the tunnel exists to carry**.
+
+**Therefore: no TUN in this project for now.** It would cost administrator rights, a kernel driver,
+and the truth of our central claim, while solving only part of what the delivery ladder already
+addresses. If it is ever added, two invariants have to hold, and both belong in the ladder's
+documentation rather than in a commit message: the control plane and the punch sockets must be
+exempted from the tunnel, and tunnelled traffic must never be reported as `p2p`.
+
+## Disciplines worth adopting, in the order we should adopt them
+
+1. **Declare policy; let one worker enforce it.** v2rayN's central shape is an ordered, declarative
+   policy consumed by a single enforcer (`Services/CoreConfig/…`), with validation that aborts a start
+   rather than launching something broken (`Manager/CoreManager.cs:75-80`), mutating a deep copy
+   rather than live config. Our ladder should be *data* — ordered rungs, each with its own bound and
+   its own reason code — executed in one place.
+2. **One named constant per network bound, and a bigger budget for the relayed leg.** `LocalFetch`
+   5 s, `DirectDownloadConnect` 5 s, **`ProxyDownloadConnect` 10 s**, selected per hop
+   (`Global.cs:100,103-104`; `Helper/DownloaderHelper.cs:336-339`). We cross NAT *and* a relay; the
+   relay leg deserves its own larger bound instead of sharing one timeout with a LAN attempt.
+3. **A distinguished failure value, never a silent zero.** `-1` as a failure sentinel
+   (`Handler/ConnectionHandler.cs:34,72`), with dependent work explicitly skipped when a probe fails
+   (`Services/SpeedtestService.cs:499-509`). Our `HELLO`/`HELLO_ACK` path should separate *no answer
+   yet* / *refused* / *timed out* / *answered wrong*, and the ledger should name **which rung** failed
+   rather than reporting a single boolean.
+4. **Bounded attempts, then fall down the ladder.** `MaxTryAgainOnFailure = 2`, twice with a 500 ms
+   gap (`DownloaderHelper.cs:37,71`; `ConnectionHandler.cs:39-47`). Give the simultaneous punch and
+   the reverse dial two or three attempts each, and record the reason each one lost.
+5. **Exempt the transport's own traffic from the transport.** v2rayN forces its cores and its own
+   directory to go direct (`Services/CoreConfig/V2ray/V2rayRoutingService.cs:239-278`, emitted at
+   `:16-30`). This is the most load-bearing lesson in the whole study: a control plane routed through
+   the thing it controls is the most likely way to brick a machine.
+6. **Teardown that is enforced by the OS, plus reaping at start.** Cores are assigned to a
+   kill-on-close job object (`Services/WindowsJobService.cs:15-18`; `Manager/CoreManager.cs:360,365-376`)
+   so a GUI crash still kills them, and stale devices are swept at the *next* launch
+   (`Common/WindowsUtils.cs:55-75`). Our analogue: reap stale state and half-open punches on start
+   instead of trusting a graceful exit.
+7. **Validate, warn, fall back to a safe value.** Errors and warnings are separate lists; an
+   unresolvable tag falls back with a warning; invalid values are blanked and reported
+   (`Handler/Builder/CoreConfigContextBuilder.cs:3-26,70-136`).
+8. **Ordered rules with a documented catch-all.** Tunnel/DNS/loop rules first, user rules next,
+   catch-all last (`V2rayRoutingService.cs:9-64,215-237`). Only relevant to us if routing ever enters
+   the picture — which, per the decision above, it has not.
+
+## What we deliberately are not copying
+
+Everything requiring an external core or administrator rights: Wintun/WFP plumbing, WinINet/RAS proxy
+configuration with a registry fallback, PAC serving, route supernet arithmetic, TUN address pools,
+per-process/per-domain routing, and core-level observatories/balancers. None of it is our shape, and
+most of it is licensed work we must not take even if it were.
+
+## One thing v2rayN does *not* do, which we should not admire
+
+There is **no core auto-restart and no core-death notification**: the `Exited` handler only
+unsubscribes log handlers (`Services/ProcessService.cs:132-142`). Its safety net is the job object
+killing things reliably — not noticing and repairing. We already learned this the hard way: this
+project's agent was twice found dead with a `0xC000013A` and nothing restarting it. Reliability by
+construction is better than reliability by hope, and where we cannot have the former we now at least
+have a watchdog that notices.

package/deploy/windows/install-service.ps1

@@ -56,6 +56,7 @@ param(
   [string]$Bin = '',
   [string]$AgentArgs = '',
   [int]$RestartBackoffMs = 60000,
+  [int]$WatchdogMinutes = 5,
   [switch]$Interactive,
   [switch]$Uninstall,
   [switch]$WhatIfOnly
@@ -133,11 +134,34 @@ $json = $config | ConvertTo-Json -Depth 4
 Write-Host "wrote $configPath"
 
 $action = New-ScheduledTaskAction -Execute $node -Argument ($arguments -join ' ') -WorkingDirectory $PSScriptRoot
+# ---------------------------------------------------------------------------------------------
+# SELF-HEALING WITHOUT ELEVATION
+#
+# Measured twice on this machine: the whole process tree (supervisor + agent) is killed with
+# 0xC000013A (STATUS_CONTROL_C_EXIT -- its console went away), the log ends mid-sentence, and Task
+# Scheduler does NOT bring it back even with RestartCount 999: the task simply ends. The fleet then
+# silently loses the machine, which is exactly the failure a supervisor was supposed to prevent --
+# a supervisor that shares the console dies with it.
+#
+# A repeating trigger fixes that without any administrator right: combined with
+# `MultipleInstances IgnoreNew` the task means "be running, or start", so a death from any cause is
+# repaired at the next tick. The window is the repetition interval, and that is the honest trade:
+# up to N minutes offline after a console-close death, versus needing elevation for a session-0
+# service (the real fix, and the default mode above).
+# ---------------------------------------------------------------------------------------------
+$repetition = if ($Interactive) {
+  # `[TimeSpan]::MaxValue` is NOT a valid duration here -- Task Scheduler rejects it and the whole
+  # registration fails (measured: the script had already stopped the old task, so the machine was
+  # left with no agent at all). Ten years is the idiomatic stand-in for "repeat indefinitely".
+  New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) `
+    -RepetitionInterval (New-TimeSpan -Minutes $WatchdogMinutes) `
+    -RepetitionDuration ([TimeSpan]::FromDays(3650))
+} else { $null }
 # AtStartup only makes sense for the session-0 (S4U) shape, which also runs whether or not anyone is
 # signed in. Registering an AtStartup trigger on an interactive task is refused without elevation --
 # measured, and the reason this list is conditional rather than always two entries.
 $triggers = if ($Interactive) {
-  @(New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME")
+  @((New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"), $repetition)
 } else {
   @(
     (New-ScheduledTaskTrigger -AtStartup),

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

@@ -35,7 +35,7 @@
 //
 // Nothing here is Windows-specific except the defaults; the same supervisor works on POSIX hosts.
 import { spawn } from 'node:child_process';
-import { createWriteStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 /** Minimal `--flag value` / `--flag` parser: no dependency, no surprises. */
@@ -149,6 +149,9 @@ if (!existsSync(bin)) {
 
 mkdirSync(dirname(logPath), { recursive: true });
 const log = createWriteStream(logPath, { flags: 'a' });
+// A second handle on the same file, as a descriptor: this is what the detached agent writes into,
+// because a descriptor is not connected to this process's console or to any pipe of ours.
+const logFd = openSync(logPath, 'a');
 const stamp = () => new Date().toISOString();
 const say = (line) => {
   console.log(line);
@@ -173,19 +176,140 @@ for (const signal of ['SIGINT', 'SIGTERM', 'SIGBREAK']) {
   });
 }
 
+// Declared before the heartbeat block, which reads it: a `let` referenced earlier in the same scope
+// would be a temporal-dead-zone throw, not an undefined value.
 let runs = 0;
+
+// ---------------------------------------------------------------------------------------------
+// HEARTBEAT AND DEGRADED MARKER
+//
+// WHY FILES AND NOT LOG LINES: the failure this exists for is a console-teardown death, and a death
+// that arrives with the console cannot be logged from inside the process it kills -- the log simply
+// stops. A file that an outside observer reads has no such dependency, so a watchdog task, a human,
+// or (later) the fleet can answer "is this machine working?" without parsing a log that may itself be
+// truncated.
+//
+// The state is one of:
+//   running   a worker is alive right now
+//   backoff   between runs, within the healthy band
+//   degraded  the crash-loop breaker has tripped: too many exits inside the window, so the fleet
+//             should see a machine that is present but unhealthy rather than one that is gone
+//
+// Written atomically (temp file + rename) so a reader never sees half a JSON document.
+// ---------------------------------------------------------------------------------------------
+const heartbeatPath = join(dirname(logPath), 'supervisor-heartbeat.json');
+const degradedAfter = Number.isFinite(Number(pick('degraded-after', 3))) ? Number(pick('degraded-after', 3)) : 3;
+const degradedWindowMs = 10 * 60_000;
+const degradedBackoffMs = Number.isFinite(Number(pick('degraded-backoff-ms', 300_000)))
+  ? Number(pick('degraded-backoff-ms', 300_000))
+  : 300_000;
+const exitTimes = [];
+
+function writeHeartbeat(patch) {
+  const recent = exitTimes.filter((at) => Date.now() - at < degradedWindowMs).length;
+  const state = patch.state ?? (recent >= degradedAfter ? 'degraded' : 'backoff');
+  const record = {
+    updated_at: stamp(),
+    state,
+    supervisor_pid: process.pid,
+    run: patch.run ?? runs,
+    child_pid: patch.child_pid ?? null,
+    child_started_at: patch.child_started_at ?? null,
+    restarts_total: Math.max(0, runs - 1),
+    restarts_within_10min: recent,
+    last_exit_code: patch.last_exit_code ?? null,
+    last_exit_at: patch.last_exit_at ?? null,
+    // The known killer, recorded in decimal because that is how Node reports it: 3221225786 is
+    // 0xC000013A, STATUS_CONTROL_C_EXIT. Signed, it is -1073741510.
+    note: 'exit code 3221225786 means the console went away; it is not a crash of the agent logic',
+    project,
+    rabbit,
+  };
+  try {
+    const tmp = `${heartbeatPath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    renameSync(tmp, heartbeatPath);
+  } catch (error) {
+    say(`[w2m-supervisor] could not write the heartbeat: ${error.message}`);
+  }
+  return record;
+}
+
+writeHeartbeat({ state: 'backoff' });
+// ---------------------------------------------------------------------------------------------
+// START-TIME REAPING -- the cost of detaching the agent, paid here
+//
+// Detaching the agent is what stops a console teardown from taking the machine off the fleet, and it
+// has a price that was measured: every supervisor generation that dies without stopping its child
+// leaves an orphan behind. Three agents with one identity were found running at once, the newest
+// unable to bind the punch port (`P2P_BIND_FAILED: EADDRINUSE 0.0.0.0:41235`) because an orphan held
+// it -- two streams on one device token, and a port that pins nothing.
+//
+// So the supervisor reaps what it did not start: the heartbeat names the last child, and if that pid
+// is still alive when a new supervisor starts, it is a previous generation's orphan and is terminated
+// before anything else runs. "Trust a graceful exit" is exactly the assumption that failed.
+// ---------------------------------------------------------------------------------------------
+try {
+  const previous = JSON.parse(readFileSync(heartbeatPath, 'utf8').replace(/^\uFEFF/, ''));
+  const orphan = Number(previous.child_pid);
+  if (Number.isInteger(orphan) && orphan > 0 && orphan !== process.pid) {
+    let alive = true;
+    try {
+      process.kill(orphan, 0);
+    } catch {
+      alive = false;
+    }
+    if (alive) {
+      try {
+        process.kill(orphan);
+        say(`[w2m-supervisor] reaped orphan agent pid=${orphan} left by an earlier supervisor`);
+        await new Promise((resolve) => {
+          setTimeout(resolve, 1500);
+        });
+      } catch (error) {
+        say(`[w2m-supervisor] could not reap orphan pid=${orphan}: ${error.message}`);
+      }
+    }
+  }
+} catch {
+  // No heartbeat yet, or unreadable: nothing to reap, and that is not an error worth stopping for.
+}
+// A periodic beat, so "the supervisor itself is alive but a worker is wedged" is visible too.
+const beat = setInterval(() => writeHeartbeat({}), 30_000);
+beat.unref();
+
 while (!stopping) {
   runs += 1;
   const startedAt = Date.now();
-  const child = spawn(process.execPath, argv, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-  child.stdout.on('data', (chunk) => {
-    process.stdout.write(chunk);
-    log.write(chunk);
-  });
-  child.stderr.on('data', (chunk) => {
-    process.stderr.write(chunk);
-    log.write(chunk);
+  // ---------------------------------------------------------------------------------------------
+  // THE AGENT MUST NOT SHARE THIS PROCESS'S CONSOLE.
+  //
+  // Measured twice on the fleet: the whole tree -- supervisor and agent together -- is killed with
+  // 0xC000013A (STATUS_CONTROL_C_EXIT, "the console went away"), the log ends mid-sentence, and
+  // nothing restarts it. A supervisor that shares the console dies with the thing it supervises,
+  // which was its one job. A study of v2rayN (GPL-3.0, read-only; see deploy/networking/LESSONS.md)
+  // turned up why its core cannot die this way: it is started with no console window and redirected
+  // stdio at all.
+  //
+  // `detached: true` plus stdio that is NOT connected to this process is the documented way to make
+  // a long-running child independent of its parent's console: with `detached`, a long-running child
+  // "will not stay running in the background after the parent exits unless it is provided with a
+  // `stdio` configuration that is not connected to the parent". So the agent gets file descriptors --
+  // never `inherit`, never pipes -- and that is the whole of the console-severing change.
+  //
+  // NOT `child.unref()`. It was the obvious-looking addition and it is wrong here: unref'ing the
+  // child leaves this process with no handle at all, so its event loop drains and **the supervisor
+  // exits immediately after spawning the agent** -- measured, and caught by noticing that no
+  // supervisor process existed at all. `unref()` is for a parent that intends to leave; this one
+  // exists to stay. Pipes would be the other trap: a detached child writing into a pipe whose reader
+  // has died blocks instead of failing loudly, which is why the log is a descriptor.
+  // ---------------------------------------------------------------------------------------------
+  const child = spawn(process.execPath, argv, {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    windowsHide: true,
   });
+  writeHeartbeat({ state: 'running', child_pid: child.pid ?? null, child_started_at: stamp() });
 
   const result = await new Promise((resolve) => {
     child.on('exit', (exitCode, signal) => resolve({ exitCode, signal }));
@@ -194,6 +318,7 @@ while (!stopping) {
       resolve({ exitCode: null, signal: null });
     });
   });
+  exitTimes.push(Date.now());
 
   const lived = Math.round((Date.now() - startedAt) / 1000);
   say(
@@ -201,10 +326,22 @@ while (!stopping) {
       `${stopping ? ' (stopping)' : ' -- restarting'}`,
   );
   if (stopping) break;
+  const record = writeHeartbeat({ last_exit_code: result.exitCode, last_exit_at: stamp() });
+  // Degraded is not "give up": it is "stop hammering and say so". The marker file is what makes the
+  // difference visible from outside -- the fleet can then see a machine that is present and unwell
+  // instead of one that silently vanished, which is the failure this whole file exists for.
+  const wait = record.state === 'degraded' ? degradedBackoffMs : backoffMs;
+  if (record.state === 'degraded') {
+    say(
+      `[w2m-supervisor] degraded: ${record.restarts_within_10min} exits within 10 minutes -- ` +
+        `backing off ${Math.round(wait / 1000)}s and marking ${heartbeatPath}`,
+    );
+  }
   // Deliberately NOT unref'ed: an unref'ed timer with nothing else pending lets Node exit during the
   // backoff, which is the silent death this loop exists to prevent.
   await new Promise((resolve) => {
-    setTimeout(resolve, backoffMs);
+    setTimeout(resolve, wait);
   });
 }
+writeHeartbeat({ state: 'stopped' });
 log.end();

package/docs/AUDIT.md

@@ -0,0 +1,130 @@
+# Audit — what is implemented, what is running, and how it works
+
+Written 2026-10-10 (UTC) against `main` at `460c437`, plus the live behaviour observed during the
+session that built v0.4.1 … v0.5.1. Every claim is labelled with how it is known, because an audit
+whose evidence cannot be told apart from its assumptions is worse than no audit:
+
+* **[M]** measured live on the three-machine fleet during the session,
+* **[T]** asserted by the repository's own test suites or CI,
+* **[?]** **not verified** — stated as an open item rather than assumed.
+
+Re-run the checks in §5 rather than trusting this file; it records a moment, not a guarantee.
+
+## 1. Designed features: implemented?
+
+| Designed feature | State | Evidence |
+|---|---|---|
+| Eight DSH tools (`w2m_devices`, `run`, `wait`, `report`, `status`, `update`, `history`, `stats`) | ✅ | **[T]** `scripts/verify-installed.mjs` on the packed artifact (`PASS: 8 tools registered`), plus a test that every tool returns a **string** (the host refuses anything else) |
+| Four modes: replicate / split / broadcast / pipeline | ✅ | **[M]** replicate across three machines; **[T]** dedicated suites for the others |
+| Nine aggregate verdicts | ✅ | **[M]** `consistent`, `divergent-platform`, `partial` observed live; **[T]** the rest covered by `test/relay`, `broadcast`, `recovery` |
+| Anchor comparability (`base_commit` + `git-temp-index-tree/v1`) | ✅ | **[M]** Windows and Linux produced the **same** fingerprint `d6d39082…` for commit `a1e7dc0` — cross-platform comparison is real, not assumed |
+| Default-deny allow-list, token-wise prefix match | ✅ | **[M]** allowed and refused commands observed on two machines; v0.4.1 unified the plugin's pre-flight with the agent's matcher |
+| P2P direct path (punch / accept / dial, reliable fragmented channel) | ✅ | **[M]** `transport: p2p` between Windows and the Tokyo server, repeatedly |
+| **A** simultaneous two-way punch, **B** reverse dial for results | ✅ code | **[T]** +17 tests, all passing (loopback). **[?]** **no live proof yet** — the fleet has not run this build on all three machines at once |
+| Pinned punch port (`--p2p-port`) | ✅ | **[M]** `0.0.0.0:41235` bound on Windows after pinning |
+| Windows deployment without elevation: supervisor + self-healing trigger | ✅ | **[M]** killing the supervisor left the agent alive with its socket bound; `every=PT5M` trigger registered |
+| Supervisor heartbeat file + `degraded` marker + orphan reaping | ✅ | **[M]** marker reaches `degraded` after three exits; a clean start leaves exactly one supervisor and one agent, heartbeat `running` |
+| Session-0 service mode (fully immune to console teardown) | ✅ script | **[?]** requires one elevation; **not executed** |
+| **C** self-hosted WireGuard hub | ✅ server side | **[M]** `wg0` active on `:51820`, two peers configured. **[?]** no `latest handshake` has ever appeared: **no client has connected**, so rung 4 is not end-to-end |
+| Delivery-ladder documentation + acceptance script | ✅ | **[M]** `deploy/networking/acceptance.mjs` ran against the live fleet; baseline recorded (all three machines on rung 5 for a relay-dispatched task) |
+| npm publication with Trusted Publishing | ✅ | **[M]** `@twinsearth/w2m-dsh-plugin@0.5.1`, latest, with a SLSA provenance attestation |
+| dsh-plugin.org listing | ✅ | **[M]** listed and marked *Verified*; the page's own snapshot is stale (submission issue #141 asks for a re-scan) |
+| TUN/VPN mode | ❌ **deliberately not built** | Decision and reasoning in `deploy/networking/LESSONS.md`: a tunnel is hub-and-spoke, so it would make "the data path is peer-to-peer" false for exactly the traffic a tunnel exists to carry |
+
+**Also not built, and known:** the ladder is not yet ordered *data* with per-rung budgets; the
+plugin has no `p2pPort` of its own (only the agent CLI needs one, since a dispatcher only dials out).
+
+## 2. Modules: running, and correct?
+
+| Module | State | Notes |
+|---|---|---|
+| Relay `w2m-rabbit` (`:8787`) | ✅ active | **[M]** three devices tracked, ledger persisted across a restart (`revived_devices`) |
+| STUN (`:3478/udp`) | ✅ active | |
+| Localside `jp-shared` (Tokyo) | ✅ v0.5.x, streaming | Re-deployed from the GitHub release asset; sha256 matched the locally built tarball byte for byte |
+| Localside `win-desktop` (this machine) | ✅ supervisor + agent, socket `41235`, heartbeat `running` | **[M]** after reaping three orphans that a previous generation had left behind |
+| Localside `macmini` | **[?]** version and liveness unconfirmed | Four-line self-check for its owner is in `deploy/networking/README.md`'s section on rungs; it previously showed *online but not accepting work* (`expired` leases) |
+| DSH plugin in this profile | ✅ v0.5.0 installed, eight tools live | Configuration is picked up by hot reload, verified via `w2m_status` twice |
+| CI / Release / npm | ✅ | CI green on four platforms; Release #31 green; npm publish automatic via OIDC |
+| v2ray-agent (same server, unrelated to this project) | ✅ xray active | TLS entry on **556** with live `accepted` log lines; nothing listens on 443, which that configuration does not need |
+| WireGuard `wg0` | ✅ server, ❌ clients | No handshake yet (§1) |
+| **Known environmental blocker** | ⚠️ | The link from this machine (an iPhone hotspot behind carrier-grade NAT) to Tokyo is intermittently unreachable — HTTP and SSH together. It takes the Windows machine off the fleet while it lasts, and it is the reason several checks above are marked **[?]** |
+
+**Known defect classes found and fixed during the session, recorded because they are the kind that
+recur:** the plugin's dispatch pre-flight could never match a multi-token allow-list entry; the punch
+port could not be pinned; `w2m_update` returned an object where the host requires a string; the
+Windows supervisor silently dropped every `-AgentArgs` value; a test read the punch port out of a
+timestamp; and detaching the agent (which fixed the console-teardown death) leaked orphan agents.
+Each is fixed with a test or a verification, and each is described in `CHANGELOG.md` under its
+version.
+
+## 3. How it works
+
+```
+DSH plugin (any machine)        Relay (the shared server)        Localside agent (each machine)
+  eight tools  ──HTTPS────▶  /v1/task · leases · ledger · SSE ──▶  executes argv within the allow-list
+      │                              ▲                                        │
+      └──── UDP hole punch: task offer + result ──────────────────────────────┘
+                                     └─ when no direct path opens, the relay carries it
+```
+
+**Control plane is centralised, data plane tries to be direct, and every task records which path it
+took.** That sentence is the whole design; everything below is mechanism.
+
+* **Two credentials, deliberately split.** The operator token authorises *dispatching* work; a
+  per-machine device token authorises *taking* and *reporting* it. Measured: reading a task back with
+  the operator token answers `401 missing or invalid device_token`. The credential that can order work
+  around cannot also read every machine's results.
+* **Anchors make "same revision" provable.** The dispatcher fingerprints its work tree
+  (`git-temp-index-tree/v1`); each machine must reproduce it or the comparison is refused as
+  `unverifiable`. A peer that is merely on a different commit cannot produce a misleading "the results
+  differ".
+* **The delivery ladder, recorded rung by rung.** A live channel, then a simultaneous two-way punch
+  (**A**), then a reverse dial for the result (**B**), then a tunnel (**C**), then the relay — with
+  `offer_path`, `result_path`, `p2p.opened_by` and per-rung reason codes saying which one served the
+  command and why the ones above it did not.
+* **Verdicts are computed in a fixed order** (§6.3 of the protocol): refusal, then anchors, then
+  execution, then comparison. `divergent-platform` exists so that "the toolchains differ" is never
+  reported as "the results disagree".
+* **Identity and state** live in files, not in a process: `device.json` per machine, an agent state
+  directory (spool and cursor), and the relay's `devices.json` + `ledger.jsonl`, which is why a relay
+  restart does not lose the fleet.
+* **The eight tools are the interface.** A model calls `w2m_devices` → `w2m_run` → `w2m_wait` →
+  `w2m_report`; nothing about the transport is required knowledge to use it, and nothing about the
+  transport is hidden once you ask (`w2m_status`, `w2m_history`, the aggregate's `transport`).
+
+## 4. Open items, stated plainly
+
+1. **A/B have no live proof yet.** They are implemented and unit-tested (loopback crosses no NAT), but
+   the three-machine measurement needs all machines on this build at once.
+2. **The MAC's state is unverified**, and one earlier episode had it online but not accepting work.
+3. **WireGuard rung 4 is not end-to-end**: hub yes, clients no. When it is, the honest label is
+   "direct socket over a tunnel the VPS forwards" — not "the bytes avoided a server".
+4. **The session-0 service is unexecuted**; the interactive task remains vulnerable to sign-out, and
+   its self-healing window is up to five minutes.
+5. **The relay link from this machine is unreliable**, which is an environmental fact about a hotspot
+   behind carrier-grade NAT, not a property of this project — and it is precisely why A/B and C exist.
+6. `deploy/` and `docs/` are inside the published package, so any change to them owes a release for
+   tag/artifact consistency; 0.5.2 is owed at the time of writing (this file included).
+
+## 5. How to re-run this audit
+
+```bash
+# the eight tools exist in the packed artifact
+node scripts/verify-installed.mjs "$(mktemp -d)"     # after extracting dist/*.tgz into it
+
+# the suites this project gates on (see release.yml for the authoritative list)
+node --test --test-force-exit test/p2p-*.test.mjs test/agent.test.mjs test/tools.test.mjs \
+  test/e2e.test.mjs test/crossnetwork.test.mjs test/recovery.test.mjs test/outbound-only.test.mjs
+
+# what path did a real dispatch take, per machine
+node deploy/networking/acceptance.mjs --rabbit http://202.182.123.154:8787 \
+  --token <operator token> --project <fleet checkout> --command 'git rev-parse HEAD'
+
+# the Windows side, locally
+Get-ScheduledTask -TaskName 'W2M Localside agent' | Get-ScheduledTaskInfo
+Get-NetUDPEndpoint -LocalPort 41235
+Get-Content "$env:USERPROFILE\.dsh\w2m\supervisor-heartbeat.json"
+
+# the tunnel
+wg show    # on the server: a `latest handshake` line per peer is the only proof
+```

package/package.json

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

package/src/plugin/tools.mjs

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