@twinsearth/w2m-dsh-plugin 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.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 } 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);
@@ -177,14 +180,33 @@ let runs = 0;
 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,
   });
 
   const result = await new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;