@twinsearth/w2m-dsh-plugin 0.5.1 → 0.5.2

package/CHANGELOG.md

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

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, openSync, 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. */
@@ -176,7 +176,108 @@ 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();
@@ -208,6 +309,7 @@ while (!stopping) {
     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 }));
@@ -216,6 +318,7 @@ while (!stopping) {
       resolve({ exitCode: null, signal: null });
     });
   });
+  exitTimes.push(Date.now());
 
   const lived = Math.round((Date.now() - startedAt) / 1000);
   say(
@@ -223,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.1",
+  "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.1';
+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;