docs(reference): import Dune: Awakening server-manager references

Phase 2 references for the host-agent Dune adapter, moved out of volatile /tmp
into docs/reference-repos/ (per Commander). Three upstream projects, .git +
node_modules + compiled binaries stripped (16MB source). Nested AI-instruction
files (.claude/, CLAUDE.md) removed so they don't pollute Corrosion sessions.

- icehunter/    dune-admin (Go+React) — 4 control planes; SETUP_DOCKER.md is the
                closest analog to our agent's Dune docker control plane (compose
                lifecycle, docker logs, RabbitMQ-via-exec, dune Postgres schema)
- adainrivers/  Rust/Tauri desktop — SSH+k8s BattleGroup control, maintenance
                daemon, in-game admin console (Rust idiom reference)
- the4rchangel/ Node web UI replacing battlegroup.bat — matches the Commander's
                Hyper-V self-host path + game-config schema

See docs/reference-repos/README.md for the full index + how we use each.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/reference-repos/the4rchangel/lib/paths.js

@@ -0,0 +1,114 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+let cachedLocalAppData = null;
+
+function isWsl() {
+  if (process.env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft/i.test(fs.readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function getWindowsLocalAppData() {
+  if (cachedLocalAppData) return cachedLocalAppData;
+  if (process.env.LOCALAPPDATA) {
+    cachedLocalAppData = process.env.LOCALAPPDATA;
+    return cachedLocalAppData;
+  }
+  if (process.env.USERPROFILE) {
+    cachedLocalAppData = path.join(process.env.USERPROFILE, 'AppData', 'Local');
+    return cachedLocalAppData;
+  }
+  try {
+    const out = execSync(
+      'powershell.exe -NoProfile -NonInteractive -Command "[Environment]::GetFolderPath(\'LocalApplicationData\')"',
+      { encoding: 'utf8', windowsHide: true, timeout: 15000 }
+    ).trim();
+    if (out) {
+      cachedLocalAppData = out;
+      return cachedLocalAppData;
+    }
+  } catch { /* fall through */ }
+  throw new Error(
+    'Could not resolve Windows LOCALAPPDATA. Start the manager with start_as_admin.bat on Windows.'
+  );
+}
+
+function windowsToWslPath(winPath) {
+  const normalized = winPath.replace(/\\/g, '/');
+  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
+  if (!match) return winPath;
+  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
+}
+
+function getDuneKeyDir() {
+  return path.join(getWindowsLocalAppData(), 'DuneAwakeningServer');
+}
+
+function getKeyPath() {
+  return path.join(getDuneKeyDir(), 'sshKey');
+}
+
+function getWslKeyMirrorPath() {
+  return path.join(os.homedir(), '.dune-awakening-server-manager', 'sshKey');
+}
+
+function sshKeyExists() {
+  try {
+    const keyPath = isWsl() ? windowsToWslPath(getKeyPath()) : getKeyPath();
+    return fs.existsSync(keyPath);
+  } catch {
+    return false;
+  }
+}
+
+function getSshIdentityPath() {
+  const keyPath = getKeyPath();
+  if (!isWsl()) return keyPath;
+
+  const source = windowsToWslPath(keyPath);
+  if (!fs.existsSync(source)) {
+    throw new Error(
+      `SSH key not found at ${keyPath}. Use Settings → Rotate SSH Key, or re-run Setup → Security.`
+    );
+  }
+
+  const localKey = getWslKeyMirrorPath();
+  fs.mkdirSync(path.dirname(localKey), { recursive: true });
+
+  const srcStat = fs.statSync(source);
+  let needsCopy = !fs.existsSync(localKey);
+  if (!needsCopy) {
+    const dstStat = fs.statSync(localKey);
+    needsCopy = srcStat.mtimeMs > dstStat.mtimeMs || srcStat.size !== dstStat.size;
+  }
+  if (needsCopy) {
+    fs.copyFileSync(source, localKey);
+  }
+  fs.chmodSync(localKey, 0o600);
+  return localKey;
+}
+
+function removeWslKeyMirror() {
+  try {
+    const mirror = getWslKeyMirrorPath();
+    if (fs.existsSync(mirror)) fs.unlinkSync(mirror);
+  } catch { /* ignore */ }
+}
+
+module.exports = {
+  isWsl,
+  getWindowsLocalAppData,
+  getDuneKeyDir,
+  getKeyPath,
+  getSshIdentityPath,
+  getWslKeyMirrorPath,
+  sshKeyExists,
+  removeWslKeyMirror,
+  windowsToWslPath,
+};

docs/reference-repos/the4rchangel/lib/powershell.js

@@ -0,0 +1,52 @@
+const { spawn } = require('child_process');
+
+const PS_ARGS = ['-NoProfile', '-NoLogo', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'];
+
+function run(command, onData) {
+  return new Promise((resolve, reject) => {
+    const ps = spawn('powershell.exe', [...PS_ARGS, command], {
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    ps.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (onData) onData(text);
+    });
+
+    ps.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (onData) onData(text);
+    });
+
+    ps.on('error', (err) => reject(err));
+    ps.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        const err = new Error(stderr.trim() || `PowerShell exited with code ${code}`);
+        err.code = code;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        reject(err);
+      }
+    });
+  });
+}
+
+function runJson(command) {
+  return run(command).then((out) => {
+    try {
+      return JSON.parse(out);
+    } catch {
+      return null;
+    }
+  });
+}
+
+module.exports = { run, runJson };

docs/reference-repos/the4rchangel/lib/ssh.js

@@ -0,0 +1,98 @@
+const { spawn } = require('child_process');
+const paths = require('./paths');
+
+/**
+ * @param {string} ip
+ * @param {string} command
+ * @param {function} [onData]  — streaming callback
+ * @param {object}  [opts]
+ * @param {number}  [opts.timeout]  — kill after N ms (default 300000 = 5 min)
+ * @param {boolean} [opts.tty]      — force pseudo-terminal (-tt)
+ * @param {string}  [opts.stdin]    — data to write to stdin then close
+ */
+function run(ip, command, onData, opts = {}) {
+  return new Promise((resolve, reject) => {
+    let keyPath;
+    try {
+      keyPath = paths.getSshIdentityPath();
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const timeout = opts.timeout || 300000;
+
+    const args = [
+      '-o', 'StrictHostKeyChecking=no',
+      '-o', 'LogLevel=QUIET',
+      '-o', 'ConnectTimeout=10',
+      '-o', 'ServerAliveInterval=15',
+      '-o', 'ServerAliveCountMax=4',
+    ];
+
+    if (opts.tty) args.push('-tt');
+
+    args.push('-i', keyPath, `dune@${ip}`, command);
+
+    const needsStdinPipe = opts.tty || opts.stdin != null;
+
+    const proc = spawn('ssh', args, {
+      windowsHide: true,
+      stdio: [needsStdinPipe ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+    });
+
+    if (needsStdinPipe) {
+      if (opts.stdin != null) proc.stdin.write(opts.stdin);
+      proc.stdin.end();
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+
+    const timer = setTimeout(() => {
+      killed = true;
+      proc.kill('SIGKILL');
+    }, timeout);
+
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (onData) onData(text);
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (onData) onData(text);
+    });
+
+    proc.on('error', (err) => { clearTimeout(timer); reject(err); });
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      if (killed) {
+        const err = new Error(`SSH command timed out after ${timeout / 1000}s`);
+        err.stdout = stdout;
+        err.stderr = stderr;
+        return reject(err);
+      }
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        const stderrTrim = stderr.trim();
+        const stdoutTrim = stdout.trim();
+        const ptyClosed = /Connection to .+ closed\.?$/m.test(stderrTrim);
+        if (stdoutTrim && (!stderrTrim || ptyClosed)) {
+          resolve(stdoutTrim);
+          return;
+        }
+        const err = new Error(stderrTrim || stdoutTrim || `SSH exited with code ${code}`);
+        err.code = code;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        reject(err);
+      }
+    });
+  });
+}
+
+module.exports = { run, getKeyPath: paths.getKeyPath, sshKeyExists: paths.sshKeyExists };

docs/reference-repos/the4rchangel/lib/vm.js

@@ -0,0 +1,126 @@
+const ps = require('./powershell');
+
+const VM_NAME = 'dune-awakening';
+const MIN_MEMORY_GB = 12;
+const STEP_DOWN_GB = [40, 32, 30, 24, 20, 18, 16, 14, 12];
+
+function isOutOfMemoryError(err) {
+  const msg = `${err && err.message || ''}\n${err && err.stderr || ''}`;
+  return /OutOfMemory|Not enough memory|0x8007000E/i.test(msg);
+}
+
+function shortVmError(message) {
+  if (!message) return 'Unknown error';
+  if (/Not enough memory|OutOfMemory|0x8007000E/i.test(message)) {
+    const match = message.match(/ram size (\d+) megabytes/i);
+    const gb = match ? Math.round(parseInt(match[1], 10) / 1024) : null;
+    return gb
+      ? `Not enough free RAM on this PC to start the VM at ${gb} GB. Choose a lower memory setting and try again.`
+      : 'Not enough free RAM on this PC to start the VM. Choose a lower memory setting and try again.';
+  }
+  const line = message.split(/\r?\n/).find((l) => l.trim() && !l.startsWith('At line:'));
+  return (line || message).trim().slice(0, 240);
+}
+
+function buildStepDownList(configuredGB) {
+  const cap = Math.max(MIN_MEMORY_GB, configuredGB || 30);
+  return STEP_DOWN_GB.filter((gb) => gb >= MIN_MEMORY_GB && gb <= cap)
+    .filter((gb, i, arr) => arr.indexOf(gb) === i)
+    .sort((a, b) => b - a);
+}
+
+async function getVmStartupMemoryGB() {
+  const raw = await ps.run(`(Get-VM -Name '${VM_NAME}').MemoryStartup`);
+  const bytes = parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(bytes) || bytes <= 0) return null;
+  return Math.round(bytes / 1073741824);
+}
+
+async function setVmMemoryGB(memoryGB, log) {
+  const memBytes = memoryGB * 1073741824;
+  if (log) log(`Setting VM memory to ${memoryGB} GB...\n`);
+  await ps.run(`Set-VMMemory -VMName '${VM_NAME}' -StartupBytes ${memBytes}`, log);
+}
+
+async function waitForVmIp(log, maxAttempts = 60) {
+  for (let i = 0; i < maxAttempts; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    try {
+      const raw = await ps.run(
+        `(Get-VMNetworkAdapter -VMName '${VM_NAME}').IPAddresses | ` +
+        `Where-Object { $_ -match '^\\d+\\.\\d+\\.\\d+\\.\\d+$' } | ` +
+        `Select-Object -First 1`
+      );
+      const ip = String(raw || '').trim();
+      if (/^\d+\.\d+\.\d+\.\d+$/.test(ip)) return ip;
+    } catch { /* keep waiting */ }
+  }
+  return null;
+}
+
+async function startVm({ memoryGB, log, autoStepDown = true } = {}) {
+  let configuredGB = memoryGB;
+  if (!configuredGB) {
+    try {
+      configuredGB = await getVmStartupMemoryGB();
+    } catch {
+      configuredGB = 30;
+    }
+  }
+
+  const tryList = memoryGB
+    ? [memoryGB]
+    : autoStepDown
+      ? buildStepDownList(configuredGB)
+      : [configuredGB];
+
+  let lastErr = null;
+
+  for (let i = 0; i < tryList.length; i++) {
+    const gb = tryList[i];
+    const needsSet = gb !== configuredGB || Boolean(memoryGB) || i > 0;
+    if (needsSet) {
+      await setVmMemoryGB(gb, log);
+    }
+
+    try {
+      if (log) log('Starting VM...\n');
+      await ps.run(`Start-VM -Name '${VM_NAME}' -ErrorAction Stop`, log);
+      if (log) log('Waiting for IP address...\n');
+      const ip = await waitForVmIp(log);
+      if (ip) {
+        if (log) log(`VM ready at ${ip}\n`);
+        return { success: true, ip, memoryGB: gb };
+      }
+      if (log) log('VM started but could not detect IP within 2 minutes.\n');
+      return { success: true, ip: null, memoryGB: gb };
+    } catch (err) {
+      lastErr = err;
+      if (!isOutOfMemoryError(err) || memoryGB) throw err;
+      if (log) {
+        log(`\nNot enough host RAM for ${gb} GB (${shortVmError(err.message)})\n`);
+        if (i < tryList.length - 1) {
+          log(`Trying ${tryList[i + 1]} GB instead...\n`);
+        }
+      }
+    }
+  }
+
+  const err = new Error(shortVmError(lastErr && lastErr.message));
+  err.code = 'OUT_OF_MEMORY';
+  err.cause = lastErr;
+  err.attemptedGB = tryList;
+  throw err;
+}
+
+module.exports = {
+  VM_NAME,
+  MIN_MEMORY_GB,
+  STEP_DOWN_GB,
+  isOutOfMemoryError,
+  shortVmError,
+  getVmStartupMemoryGB,
+  setVmMemoryGB,
+  waitForVmIp,
+  startVm,
+};