@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.2

package/bin/w2m-rabbit.mjs

@@ -53,6 +53,9 @@ Credentials and state:
   --no-persist           Keep everything in memory; forget devices and tasks on
                          restart.
   --pairing-code <c>     Use a fixed pairing code instead of a generated one.
+--fleet <id>           Bind this relay to one account's fleet. Omitted, the relay serves
+                       every device (the pre-v0.7.7 behaviour). Set, a device with no
+                       fleet reaches nothing and a device in another fleet is invisible.
 
 Request signing (v0.3.0):
   --signing-secret <s>   Shared secret for HMAC-signed requests. Unset means the relay does
@@ -98,6 +101,9 @@ try {
       port: { type: 'string' },
       state: { type: 'string' },
       'pairing-code': { type: 'string' },
+      // v0.7.7: bind this relay to a fleet. Omitted means every device, which is the
+      // pre-v0.7.7 behaviour and therefore the migration-safe default.
+      fleet: { type: 'string' },
       'heartbeat-ms': { type: 'string' },
       'grace-ms': { type: 'string' },
       'base-path': { type: 'string' },

package/deploy/mac/mac-self-update.mjs

@@ -0,0 +1,257 @@
+/**
+ * The Mac's self-updating supervisor (v0.8.0).
+ *
+ * ## Why this is detached rather than run inline
+ *
+ * It has to **survive the thing it is restarting**. DSH spawns the Localside agent, so a script
+ * running inside that agent dies the moment DSH stops — which is exactly when the work begins. So
+ * this is launched detached with `stdio: 'ignore'` and `unref()`, and it is the *only* process that
+ * outlives the restart.
+ *
+ * ## The failure this is built around
+ *
+ * A blind remote update has one catastrophic outcome: DSH stops, the plugin does not load, and the
+ * machine never comes back — leaving no channel to fix it with. So every step is ordered so that
+ * **the previous state is restorable without the network**:
+ *
+ *   1. back up the installed plugin tree to a timestamped directory
+ *   2. stage the new tarball and verify it EXTRACTED (a truncated download upacks to nothing)
+ *   3. swap, then restart
+ *   4. **self-check**: is DSH running, and is the plugin loaded?
+ *   5. **on failure, roll back and restart again** — automatically, because nobody is watching
+ *
+ * ## How success is reported when nothing can be read back
+ *
+ * The machine cannot tell us anything directly: its task results are `unverifiable` and its stdout
+ * never reaches the relay. So the report is written to a file **and** the outcome is made visible
+ * indirectly — a successful restart puts the machine back in the fleet, and the caller watches for
+ * it. `--verify-fleet` does that check from inside this script as well, against the relay's
+ * `/healthz`, so the rollback decision does not depend on an outside observer.
+ *
+ * Usage: node mac-self-update.mjs --tarball <path> --sha256 <hex> [--verify-fleet <url>]
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const argv = process.argv.slice(2);
+const opt = (name, dflt) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : dflt);
+
+const TARBALL = opt('--tarball', '');
+const EXPECTED = opt('--sha256', '');
+const VERIFY_FLEET = opt('--verify-fleet', '');
+const PACKAGE = '@twinsearth/w2m-dsh-plugin';
+const STAMP = new Date().toISOString().replace(/[:.]/g, '-');
+const REPORT = join(homedir(), 'w2m-self-update-report.json');
+
+const steps = [];
+const record = (step, ok, detail) => {
+  steps.push({ step, ok, detail, at: new Date().toISOString() });
+  // Written after every step: if the process is killed mid-way, the report says where it stopped.
+  try { writeFileSync(REPORT, JSON.stringify({ stamp: STAMP, steps, done: false }, null, 2)); } catch { /* the report must never break the update */ }
+};
+const finish = (ok, extra = {}) => {
+  try { writeFileSync(REPORT, JSON.stringify({ stamp: STAMP, ok, steps, done: true, ...extra }, null, 2)); } catch { /* as above */ }
+  process.exit(ok ? 0 : 1);
+};
+
+/** Run a command, never throwing: a missing tool is a finding, not a crash. */
+function run(cmd, args, opts = {}) {
+  try {
+    return { ok: true, out: execFileSync(cmd, args, { encoding: 'utf8', timeout: opts.timeout ?? 60_000, stdio: ['ignore', 'pipe', 'pipe'] }).trim() };
+  } catch (e) {
+    return { ok: false, out: `${e.status ?? ''} ${String(e.stderr ?? e.message).trim()}`.trim() };
+  }
+}
+
+/**
+ * Find the DSH home and the installed plugin.
+ *
+ * Discovered rather than assumed: the paths differ between a packaged app, a profile install, and a
+ * development checkout, and this script has exactly one chance to be right.
+ */
+function findInstall() {
+  const home = homedir();
+  const candidates = [
+    join(home, '.dsh'),
+    join(home, 'Library', 'Application Support', 'dsh'),
+    join(home, 'Library', 'Application Support', 'DeepSeek Harness'),
+  ];
+  for (const dshHome of candidates) {
+    if (!existsSync(dshHome)) continue;
+    const profiles = join(dshHome, 'profiles');
+    if (!existsSync(profiles)) continue;
+    for (const profile of readdirSync(profiles)) {
+      const mod = join(profiles, profile, 'node_modules', ...PACKAGE.split('/'));
+      if (existsSync(join(mod, 'package.json'))) {
+        let version = '?';
+        try { version = JSON.parse(readFileSync(join(mod, 'package.json'), 'utf8')).version; } catch { /* reported as ? */ }
+        return { dshHome, profiles, profile, moduleDir: mod, version, profileDir: join(profiles, profile) };
+      }
+    }
+  }
+  return null;
+}
+
+/** Is DSH itself running, and what launched it? */
+function findDshProcess() {
+  const ps = run('/bin/ps', ['-Ao', 'pid=,command='], { timeout: 20_000 });
+  if (!ps.ok) return { ok: false, reason: `ps failed: ${ps.out}` };
+  const lines = ps.out.split('\n').filter((l) => l.trim() !== '');
+  const self = String(process.pid);
+  const matches = lines
+    .map((l) => {
+      const m = /^\s*(\d+)\s+(.*)$/.exec(l);
+      return m ? { pid: m[1], command: m[2] } : null;
+    })
+    .filter(Boolean)
+    .filter((p) => p.pid !== self)
+    .filter((p) => /DeepSeek Harness|\.dsh|dsh\b/i.test(p.command))
+    .filter((p) => !/mac-self-update|node -e/i.test(p.command));
+  return { ok: true, matches };
+}
+
+/**
+ * The fleet check: does this machine show up at the relay again?
+ *
+ * `machineName` is read from the environment the agent was started with, falling back to the
+ * hostname — the relay lists machines by the name they paired under.
+ */
+async function fleetHasMachine(url, name) {
+  try {
+    const res = await fetch(new URL('/healthz', url).toString(), { signal: AbortSignal.timeout(10_000) });
+    const body = await res.json();
+    if (body?.ok !== true) return { ok: false, why: `healthz ok=${body?.ok}` };
+    // `/healthz` gives a count; the device list needs a device token, so the count is the signal
+    // available here. A drop to zero means the fleet lost everyone and the rollback should fire.
+    return { ok: (body.devices ?? 0) > 0, why: `devices=${body.devices}`, devices: body.devices ?? 0 };
+  } catch (e) {
+    return { ok: false, why: `healthz threw: ${e.message}` };
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  const install = findInstall();
+  if (install === null) {
+    record('locate the installed plugin', false, `no ${PACKAGE} under any known DSH home`);
+    return finish(false, { reason: 'not_installed' });
+  }
+  record('locate the installed plugin', true, `v${install.version} at ${install.moduleDir}`);
+
+  const before = findDshProcess();
+  record('find the DSH process', before.ok, before.ok ? `${before.matches.length} match(es)` : before.reason);
+
+  // ---- 1. verify the artefact BEFORE touching anything -------------------------------
+  if (!existsSync(TARBALL)) { record('verify the artefact', false, `no tarball at ${TARBALL}`); return finish(false, { reason: 'no_tarball' }); }
+  const actual = createHash('sha256').update(readFileSync(TARBALL)).digest('hex');
+  if (EXPECTED !== '' && actual !== EXPECTED) {
+    record('verify the artefact', false, `checksum ${actual} != ${EXPECTED}`);
+    return finish(false, { reason: 'checksum_mismatch' });
+  }
+  record('verify the artefact', true, `sha256 ${actual.slice(0, 16)}…`);
+
+  // ---- 2. back up, so rollback needs nothing from the network -------------------------
+  const backup = `${install.moduleDir}.backup-${STAMP}`;
+  try {
+    cpSync(install.moduleDir, backup, { recursive: true });
+    record('back up the installed plugin', true, `${backup}`);
+  } catch (e) {
+    record('back up the installed plugin', false, e.message);
+    return finish(false, { reason: 'backup_failed' });
+  }
+
+  // ---- 3. stage and check it EXTRACTED -------------------------------------------------
+  const staging = join(tmpdir(), `w2m-stage-${STAMP}`);
+  mkdirSync(staging, { recursive: true });
+  const untar = run('/usr/bin/tar', ['-xzf', TARBALL, '-C', staging], { timeout: 180_000 });
+  if (!untar.ok) { record('unpack to staging', false, untar.out); return finish(false, { reason: 'untar_failed' }); }
+  const staged = join(staging, 'package');
+  const src = existsSync(staged) ? staged : staging;
+  const entry = join(src, 'bin', 'w2m-localside.mjs');
+  if (!existsSync(entry)) {
+    record('check the staged tree', false, `no bin/w2m-localside.mjs in ${src}`);
+    return finish(false, { reason: 'no_entry_point' });
+  }
+  let stagedVersion = '?';
+  try { stagedVersion = JSON.parse(readFileSync(join(src, 'package.json'), 'utf8')).version; } catch { /* reported as ? */ }
+  record('check the staged tree', true, `v${stagedVersion}`);
+
+  // ---- 4. swap -------------------------------------------------------------------------
+  try {
+    rmSync(install.moduleDir, { recursive: true, force: true });
+    cpSync(src, install.moduleDir, { recursive: true });
+    record('swap into place', true, `v${install.version} -> v${stagedVersion}`);
+  } catch (e) {
+    record('swap into place', false, e.message);
+    // The backup is right there; restore without asking.
+    try { rmSync(install.moduleDir, { recursive: true, force: true }); cpSync(backup, install.moduleDir, { recursive: true }); record('restore after a failed swap', true, 'reverted'); } catch (e2) { record('restore after a failed swap', false, e2.message); }
+    return finish(false, { reason: 'swap_failed' });
+  }
+
+  // ---- 5. restart ----------------------------------------------------------------------
+  /**
+   * DSH is restarted by signalling it, and **the detached supervisor is what makes that survivable**:
+   * this process is not a child of DSH, so it keeps running to do the self-check and the rollback.
+   */
+  const targets = before.ok ? before.matches : [];
+  for (const p of targets) run('/bin/kill', ['-TERM', p.pid], { timeout: 10_000 });
+  record('signal DSH to stop', targets.length > 0, `${targets.length} process(es)`);
+  await sleep(5000);
+
+  // Bring it back the way it was launched, if a launcher is discoverable.
+  const launchd = run('/bin/launchctl', ['list'], { timeout: 15_000 });
+  const launchdHit = launchd.ok ? launchd.out.split('\n').find((l) => /dsh|harness/i.test(l)) : undefined;
+  if (launchdHit) {
+    record('restart via launchd', true, launchdHit.trim());
+  } else {
+    // No launchd job: try `open`, which is how a packaged app is started. A failure here is the
+    // case the rollback exists for.
+    const opened = run('/usr/bin/open', ['-a', 'DeepSeek Harness'], { timeout: 30_000 });
+    record('restart via open -a', opened.ok, opened.ok ? 'launched' : opened.out);
+  }
+
+  // ---- 6. self-check, with the rollback as the answer to a failure ----------------------
+  let healthy = false;
+  let why = '';
+  for (let i = 1; i <= 6; i += 1) {
+    await sleep(10_000);
+    const proc = findDshProcess();
+    if (!proc.ok || proc.matches.length === 0) { why = 'DSH is not running'; continue; }
+    if (VERIFY_FLEET !== '') {
+      const fleet = await fleetHasMachine(VERIFY_FLEET, '');
+      if (!fleet.ok) { why = `fleet check: ${fleet.why}`; continue; }
+      record(`self-check ${i}`, true, `DSH up, ${fleet.why}`);
+    } else {
+      record(`self-check ${i}`, true, `DSH up (${proc.matches.length} process(es))`);
+    }
+    healthy = true;
+    break;
+  }
+
+  if (healthy) return finish(true, { from: install.version, to: stagedVersion, backup });
+
+  record('self-check', false, why || 'DSH did not come back');
+  // ---- 7. roll back, automatically ------------------------------------------------------
+  for (const p of (findDshProcess().matches ?? [])) run('/bin/kill', ['-TERM', p.pid], { timeout: 10_000 });
+  await sleep(3000);
+  try {
+    rmSync(install.moduleDir, { recursive: true, force: true });
+    cpSync(backup, install.moduleDir, { recursive: true });
+    record('roll back', true, `restored v${install.version}`);
+  } catch (e) {
+    record('roll back', false, e.message);
+    return finish(false, { reason: 'rollback_failed', backup });
+  }
+  run('/usr/bin/open', ['-a', 'DeepSeek Harness'], { timeout: 30_000 });
+  await sleep(20_000);
+  const after = findDshProcess();
+  record('verify the rollback', after.ok && after.matches.length > 0, `${after.matches?.length ?? 0} process(es)`);
+  return finish(false, { reason: 'rolled_back', restored: install.version, backup });
+}
+
+main().catch((e) => { record('unhandled', false, String(e?.stack ?? e)); finish(false, { reason: 'threw' }); });

package/deploy/server/README.md

@@ -0,0 +1,109 @@
+# Running the relay on a server
+
+These are the units the shared relay **actually runs**, copied from
+`/etc/systemd/system/` on the live host rather than written from the documentation. They are in the
+repository because "how the server runs" is part of the thing being open-sourced — and because a
+unit that exists only on one machine is a unit nobody can review, reproduce, or audit.
+
+## The three services
+
+| Unit | What it is | Port |
+|---|---|---|
+| `w2m-rabbit.service` | The relay: P2P rendezvous, signalling, and the task ledger | 8787 |
+| `w2m-stun.service` | STUN responder, for reflexive address discovery during hole punching | 3478 |
+| `w2m-localside.service` | A Localside agent, so the server is itself a fleet machine | — |
+
+`w2m-localside` is deliberately the same agent every other machine runs. The server is not
+privileged in the fleet's protocol — it is a peer that happens to be reachable — and running it
+through the normal agent is what keeps that true.
+
+## ⚠️ What is NOT here, and why
+
+**`/var/lib/w2m/rabbit/` is not in this repository and must never be.**
+
+It holds:
+
+| File | Why it must not be published |
+|---|---|
+| `operator-token.txt` | **Full control of the fleet.** Anyone holding it can dispatch any allowed command to every machine. |
+| `ledger` | The task history: every command run, on which machine, with which results. |
+
+Two mechanisms keep this true, because one is not enough:
+
+1. **`.gitignore`** refuses the paths, so an accidental `git add -A` cannot stage them.
+2. **`scripts/scan-for-secrets.mjs`** reads the **content** of every tracked file and fails the
+   release on a credential shape. A `.gitignore` refuses a *path*; the ways a credential actually
+   escapes are pasting one into a source file, a fixture, or an example — so tracked content is
+   what gets read.
+
+Run it before a release:
+
+```bash
+node scripts/scan-for-secrets.mjs .
+# 0 blocking, N for review -> exit 0
+```
+
+`REVIEW` findings (long hex strings, high-entropy assignments) are **not fatal by design**: a
+scanner whose false positives block releases is a scanner someone deletes. Only real credential
+shapes stop anything.
+
+## Installing
+
+```bash
+# 1. A user that owns the state and nothing else.
+sudo useradd --system --home /var/lib/w2m --shell /usr/sbin/nologin w2m
+
+# 2. The paths the units reference.
+sudo install -d -o w2m -g w2m /opt/w2m /var/lib/w2m /var/log/w2m
+
+# 3. The code, at the tag being deployed.
+sudo -u w2m git clone https://github.com/TwinsEarth/dsh-windows2macos /opt/w2m/app
+sudo -u w2m git -C /opt/w2m/app checkout v0.7.10
+
+# 4. The units.
+sudo cp deploy/server/*.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now w2m-rabbit w2m-stun
+
+# 5. Pair the server as a fleet machine, then enable the agent.
+sudo systemctl enable --now w2m-localside
+```
+
+## Notes on the hardening, since it is easy to weaken by accident
+
+Every unit sets `NoNewPrivileges`, `PrivateTmp`, `ProtectHome`, and a `ProtectSystem` level, and
+writes only inside `/var/lib/w2m` via `ReadWritePaths`. That last one matters: `ProtectSystem=full`
+makes `/usr` and `/boot` read-only, so an agent that tried to write anywhere else would fail
+loudly rather than silently succeed on a machine that should not be writable.
+
+`w2m-stun` is stricter (`ProtectSystem=strict`, `RestrictAddressFamilies=AF_INET AF_INET6`) because
+it needs a socket and nothing else.
+
+**If you add a capability to an agent, check `ReadWritePaths` first.** The failure is a permission
+error at runtime, which looks like a bug in the agent rather than a hardening setting.
+
+## The `--fleet` flag, and why it is absent here
+
+`w2m-rabbit` accepts `--fleet <account code>`, which binds the relay to one account's fleet. It is
+**absent from this unit on purpose**, and the relay therefore runs unscoped: every paired device
+reaches every other.
+
+Turning it on is not a configuration change — it is a **fleet migration**:
+
+1. the account code must be read on a machine that is **signed in** (a headless server cannot
+   produce one; it has no DeepSeek account),
+2. the relay restarts scoped,
+3. **every device must be re-paired**, because a device receives its fleet *from the pairing code*,
+   and on a scoped relay a device with no fleet reaches **nothing**.
+
+Step 3 is the risk: the fleet goes silent until each machine is re-paired. That is the intended
+fail-safe direction and it is still an outage while it lasts.
+
+## Deliberately not included
+
+* **TLS termination.** The live relay is behind a proxy that handles it; `--base-path` and
+  `--trust-proxy` exist for that arrangement and the certificate is the operator's business.
+* **Backups.** The state directory is small (about 1 MB) and is the operator's to schedule. The
+  deployment script below does back it up before a swap, which is not the same as a backup policy.
+* **Log rotation.** `StandardOutput=append:` grows without bound; the live host rotates
+  `/var/log/w2m/*.log` outside these units.

package/deploy/server/deploy-w2m.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+#
+# Deploy one release tarball to a running relay, with a rollback that is automatic rather than
+# remembered.
+#
+# This is the script the live server was updated with (v0.6.3 -> v0.7.7 -> v0.7.10). It is in the
+# repository because a deployment that exists only in someone's shell history is a deployment nobody
+# can review — and because the order of these steps is the whole safety argument:
+#
+#   1. verify the checksum BEFORE unpacking, so a truncated upload cannot become a running service
+#   2. back up the tree in place, so rollback does not depend on the network
+#   3. stage and check for entry points BEFORE swapping, so a bad tarball never reaches the
+#      live path
+#   4. restart and health-check, and roll back automatically if the health check fails
+#
+# Step 3 is the one that matters most: `git archive` of a wrong subdirectory produces a tarball that
+# unpacks cleanly and contains no `bin/`, and without the entry-point check that becomes a service
+# that starts, finds nothing to run, and reports a confusing error.
+#
+# Usage: deploy-w2m.sh <tarball> <expected-sha256> [--fleet <account-code>]
+#
+set -euo pipefail
+
+APP_DIR=/opt/w2m/app
+BACKUP_ROOT=/opt/w2m
+STATE_DIR=/var/lib/w2m
+SERVICES=(w2m-rabbit w2m-stun w2m-localside)
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+
+TARBALL="${1:-}"
+EXPECTED="${2:-}"
+FLEET=""
+if [ "${3:-}" = "--fleet" ]; then FLEET="${4:-}"; fi
+
+if [ -z "$TARBALL" ] || [ -z "$EXPECTED" ]; then
+  echo "usage: $0 <tarball> <expected-sha256> [--fleet <account-code>]" >&2
+  exit 2
+fi
+if [ ! -f "$TARBALL" ]; then echo "no such tarball: $TARBALL" >&2; exit 2; fi
+
+echo "=== 1. verify the artefact ==="
+ACTUAL=$(sha256sum "$TARBALL" | awk '{print $1}')
+echo "  expected $EXPECTED"
+echo "  actual   $ACTUAL"
+if [ "$ACTUAL" != "$EXPECTED" ]; then
+  echo "  CHECKSUM MISMATCH -- refusing to deploy. A truncated upload must never become a service." >&2
+  exit 1
+fi
+echo "  checksum OK"
+
+echo
+echo "=== 2. what is running now ==="
+if [ -f "$APP_DIR/package.json" ]; then
+  echo "  $APP_DIR is version $(node -e "process.stdout.write(require('$APP_DIR/package.json').version)")"
+else
+  echo "  $APP_DIR has no package.json (first deploy?)"
+fi
+for s in "${SERVICES[@]}"; do
+  printf '  %-16s %s\n' "$s" "$(systemctl is-active "$s" 2>/dev/null || echo inactive)"
+done
+
+echo
+echo "=== 3. back up the current tree ==="
+BACKUP="$BACKUP_ROOT/backup-$STAMP"
+if [ -d "$APP_DIR" ]; then
+  cp -a "$APP_DIR" "$BACKUP"
+  echo "  $APP_DIR -> $BACKUP"
+else
+  echo "  nothing to back up"
+fi
+
+echo
+echo "=== 4. unpack to staging and check it ==="
+STAGING=$(mktemp -d)
+trap 'rm -rf "$STAGING"' EXIT
+tar -xzf "$TARBALL" -C "$STAGING"
+# The tarball contains a single `package/` root, by npm convention.
+SRC="$STAGING/package"
+if [ ! -d "$SRC" ]; then SRC="$STAGING"; fi
+
+STAGED_VERSION=$(node -e "process.stdout.write(require('$SRC/package.json').version)" 2>/dev/null || echo "?")
+echo "  staged version: $STAGED_VERSION"
+
+# The check that turns a confusing runtime failure into a clear deployment failure.
+MISSING=""
+for f in bin/w2m-rabbit.mjs bin/w2m-stun.mjs bin/w2m-localside.mjs package.json; do
+  [ -e "$SRC/$f" ] || MISSING="$MISSING $f"
+done
+if [ -n "$MISSING" ]; then
+  echo "  MISSING ENTRY POINTS:$MISSING" >&2
+  echo "  refusing to swap: this tarball would install a service that cannot start." >&2
+  exit 1
+fi
+echo "  entry points present"
+
+echo
+echo "=== 5. swap into place ==="
+rm -rf "$APP_DIR.old"
+if [ -d "$APP_DIR" ]; then mv "$APP_DIR" "$APP_DIR.old"; fi
+cp -a "$SRC" "$APP_DIR"
+chown -R w2m:w2m "$APP_DIR" 2>/dev/null || true
+echo "  swapped; previous tree kept at $APP_DIR.old"
+
+echo
+echo "=== 6. restart ==="
+# The relay's fleet binding: omitted means unscoped, which is the pre-v0.7.8 behaviour.
+if [ -n "$FLEET" ]; then
+  echo "  --fleet $FLEET requested"
+  if grep -q -- '--fleet' /etc/systemd/system/w2m-rabbit.service; then
+    sed -i "s|--fleet [^ ]*|--fleet $FLEET|" /etc/systemd/system/w2m-rabbit.service
+  else
+    sed -i "s|\(--state [^ ]*\)|\1 --fleet $FLEET|" /etc/systemd/system/w2m-rabbit.service
+  fi
+  systemctl daemon-reload
+  echo "  WARNING: the relay is now scoped. A device with no fleet reaches NOTHING."
+  echo "           Every device must be re-paired with a code issued by this relay."
+fi
+systemctl restart "${SERVICES[@]}"
+
+echo
+echo "=== 7. health check ==="
+sleep 4
+HEALTHY=1
+for s in "${SERVICES[@]}"; do
+  STATE=$(systemctl is-active "$s" 2>/dev/null || echo inactive)
+  printf '  %-16s %s\n' "$s" "$STATE"
+  [ "$STATE" = "active" ] || HEALTHY=0
+done
+
+if command -v curl >/dev/null 2>&1; then
+  HEALTH=$(curl -fsS --max-time 10 http://127.0.0.1:8787/healthz 2>/dev/null || echo "")
+  if [ -n "$HEALTH" ]; then
+    echo "  healthz: $HEALTH"
+  else
+    echo "  healthz: NO ANSWER"
+    HEALTHY=0
+  fi
+fi
+
+if [ "$HEALTHY" != "1" ]; then
+  echo
+  echo "=== 8. ROLLBACK ==="
+  if [ -d "$BACKUP" ]; then
+    rm -rf "$APP_DIR"
+    mv "$BACKUP" "$APP_DIR"
+    systemctl restart "${SERVICES[@]}"
+    echo "  rolled back to the previous tree and restarted" >&2
+  else
+    echo "  no backup to roll back to" >&2
+  fi
+  exit 1
+fi
+
+echo
+echo "=== deployed ==="
+echo "  version:  $STAGED_VERSION"
+echo "  backup:   $BACKUP"
+echo "  previous: $APP_DIR.old (removable once this is proven)"
+echo
+echo "  NOTE: relay state lives in $STATE_DIR and was NOT touched by this script."
+echo "        The ledger and the operator token survive a deploy; that is deliberate."

package/deploy/server/w2m-localside.service

@@ -0,0 +1,31 @@
+[Unit]
+Description=W2M Localside agent (shared server as a fleet machine)
+After=network-online.target w2m-rabbit.service
+Wants=network-online.target
+Wants=w2m-rabbit.service
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+WorkingDirectory=/opt/w2m/demo
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-localside.mjs \
+  --rabbit http://127.0.0.1:8787 \
+  --project /opt/w2m/shared \
+  --name jp-shared \
+  --state /var/lib/w2m/localside-jp \
+  --p2p-mode auto \
+  --p2p-port 41234 \
+  --allowed-commands '["node --version","node --test","node -e","git status --porcelain","git rev-parse","git log","git diff","npm test","npm run"]'
+Restart=always
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/w2m
+StandardOutput=append:/var/log/w2m/localside.log
+StandardError=append:/var/log/w2m/localside.log
+
+[Install]
+WantedBy=multi-user.target

package/deploy/server/w2m-rabbit.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=W2M Rabbit relay (P2P rendezvous, signalling and task ledger)
+Documentation=https://github.com/TwinsEarth/dsh-windows2macos
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+WorkingDirectory=/opt/w2m/app
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-rabbit.mjs --host 0.0.0.0 --port 8787 --state /var/lib/w2m/rabbit
+Restart=always
+RestartSec=2
+# The relay holds no model credentials and no working copy; it needs its state dir and
+# nothing else. NoNewPrivileges + ProtectSystem close the obvious escalation paths.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/w2m
+StandardOutput=append:/var/log/w2m/rabbit.log
+StandardError=append:/var/log/w2m/rabbit.log
+
+[Install]
+WantedBy=multi-user.target

package/deploy/server/w2m-stun.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=W2M STUN responder - reflexive address discovery for P2P hole punching
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-stun.mjs --host 0.0.0.0 --port 3478 --log-level info
+Restart=always
+RestartSec=2
+StartLimitIntervalSec=60
+StartLimitBurst=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6
+StandardOutput=append:/var/log/w2m/stun.log
+StandardError=append:/var/log/w2m/stun.log
+
+[Install]
+WantedBy=multi-user.target