@twinsearth/w2m-dsh-plugin 0.4.9 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,106 @@ 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
+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

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/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);
+}