mobygate 0.3.0

package/lib/platform.js

@@ -0,0 +1,584 @@
+/**
+ * Platform-aware service management for mobygate.
+ *
+ * Each supported OS has a native scheduler/supervisor we target:
+ *   - macOS   → launchd (plist files in ~/Library/LaunchAgents/)
+ *   - Linux   → systemd user units (~/.config/systemd/user/)
+ *   - Windows → Task Scheduler + nssm (if available) or a simple
+ *               Start Menu startup shortcut
+ *
+ * For v0.1 we ship full automation on macOS and emit clear manual
+ * instructions on Linux/Windows. Enough to unblock the team today;
+ * the other paths land as the brothers test on their boxes.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join, dirname, resolve } from 'path';
+import { execSync, spawnSync } from 'child_process';
+import { LOGS_DIR } from './config.js';
+
+export const PLATFORM = platform();         // 'darwin' | 'linux' | 'win32'
+export const IS_MAC = PLATFORM === 'darwin';
+export const IS_LINUX = PLATFORM === 'linux';
+export const IS_WIN = PLATFORM === 'win32';
+
+const LAUNCH_AGENTS_DIR = join(homedir(), 'Library', 'LaunchAgents');
+const SERVER_LABEL = 'ai.mobygate.server';
+const AUTH_LABEL = 'ai.mobygate.auth-refresh';
+
+/**
+ * Resolve the node binary to use for spawned services. launchd/systemd
+ * do NOT source shell rc files, so fnm/nvm paths won't exist unless we
+ * hand them a concrete path. Strategy:
+ *   1. Honor MOBYGATE_NODE_BIN env var if set (lets users override)
+ *   2. Try the current process.execPath (Node we're running under)
+ *   3. Fall back to `which node` via shell
+ */
+export function resolveNodeBin() {
+  if (process.env.MOBYGATE_NODE_BIN) return process.env.MOBYGATE_NODE_BIN;
+  if (process.execPath && existsSync(process.execPath)) return process.execPath;
+  try {
+    const r = spawnSync(IS_WIN ? 'where' : 'which', ['node'], { encoding: 'utf8' });
+    if (r.status === 0) return r.stdout.trim().split('\n')[0];
+  } catch {}
+  return 'node';
+}
+
+/**
+ * Emit a launchd plist for the server. Writes and returns the file path.
+ * Caller is responsible for loading it via `launchctl load`.
+ */
+export function writeMacServerPlist({ installPath, nodeBin, port, logsDir }) {
+  if (!IS_MAC) throw new Error('writeMacServerPlist called on non-macOS');
+  if (!existsSync(LAUNCH_AGENTS_DIR)) mkdirSync(LAUNCH_AGENTS_DIR, { recursive: true });
+  const plistPath = join(LAUNCH_AGENTS_DIR, `${SERVER_LABEL}.plist`);
+  const pathChain = [
+    dirname(nodeBin),
+    '/usr/local/bin', '/usr/bin', '/bin', '/opt/homebrew/bin',
+    join(homedir(), '.local/bin'),
+  ].join(':');
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Generated by \`mobygate init\` on ${new Date().toISOString()}.
+  Manages the mobygate server as a user-level launchd service:
+    - Starts at login (RunAtLoad = true)
+    - Restarts on crash (KeepAlive = true)
+    - Logs to ${logsDir}/server.{log,err.log}
+
+  Install:   launchctl load ~/Library/LaunchAgents/${SERVER_LABEL}.plist
+  Uninstall: launchctl unload ~/Library/LaunchAgents/${SERVER_LABEL}.plist
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${SERVER_LABEL}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodeBin}</string>
+        <string>server.js</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>${installPath}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${pathChain}</string>
+        <key>HOME</key>
+        <string>${homedir()}</string>
+        <key>PORT</key>
+        <string>${port}</string>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>${logsDir}/server.log</string>
+    <key>StandardErrorPath</key>
+    <string>${logsDir}/server.err.log</string>
+</dict>
+</plist>
+`;
+  writeFileSync(plistPath, xml);
+  return plistPath;
+}
+
+/**
+ * Install (copy + load) a plist. Returns {installed: true, path}.
+ * Safe to call when already loaded — we unload first.
+ */
+export function launchctlLoad(plistPath) {
+  if (!IS_MAC) throw new Error('launchctlLoad called on non-macOS');
+  try { execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
+  execSync(`launchctl load "${plistPath}"`);
+  return { loaded: true, path: plistPath };
+}
+
+export function launchctlUnload(plistPath) {
+  if (!IS_MAC) return { unloaded: false, path: plistPath };
+  try { execSync(`launchctl unload "${plistPath}"`); } catch {}
+  return { unloaded: true, path: plistPath };
+}
+
+/** List of plist labels we own, in install order. */
+export const MANAGED_LABELS = [SERVER_LABEL, AUTH_LABEL];
+
+export function plistPathForLabel(label) {
+  return join(LAUNCH_AGENTS_DIR, `${label}.plist`);
+}
+
+/**
+ * Remove our plists (unload + delete the files in ~/Library/LaunchAgents).
+ * Returns a list of {label, removed} results.
+ */
+export function uninstallAllServices() {
+  if (!IS_MAC) return [];
+  const results = [];
+  for (const label of MANAGED_LABELS) {
+    const p = plistPathForLabel(label);
+    if (existsSync(p)) {
+      try { execSync(`launchctl unload "${p}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
+      try { unlinkSync(p); results.push({ label, removed: true, path: p }); }
+      catch (e) { results.push({ label, removed: false, error: e.message }); }
+    } else {
+      results.push({ label, removed: false, reason: 'not installed' });
+    }
+  }
+  return results;
+}
+
+/**
+ * Ask launchd whether a given label is currently loaded. Returns
+ * {loaded, lastExit, pid} — pid is null if loaded but not running.
+ */
+export function queryLaunchd(label) {
+  if (!IS_MAC) return { supported: false };
+  const r = spawnSync('launchctl', ['list', label], { encoding: 'utf8' });
+  if (r.status !== 0) return { loaded: false };
+  // Output is a plist-ish dict with Label, PID, LastExitStatus keys
+  const pidMatch = /"PID"\s*=\s*(\d+);/.exec(r.stdout);
+  const exitMatch = /"LastExitStatus"\s*=\s*(-?\d+);/.exec(r.stdout);
+  return {
+    loaded: true,
+    pid: pidMatch ? parseInt(pidMatch[1], 10) : null,
+    lastExit: exitMatch ? parseInt(exitMatch[1], 10) : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Windows — Task Scheduler automation
+// ---------------------------------------------------------------------------
+// We register two user-level scheduled tasks (no admin required):
+//   mobygate-server         at logon, auto-restart on failure, KeepAlive
+//   mobygate-auth-refresh   every 4h, one-shot
+//
+// User-level tasks run as the current user with their normal privileges
+// (RunLevel: Limited), which is all we need. No nssm, no admin elevation.
+
+const WIN_SERVER_TASK = 'mobygate-server';
+const WIN_AUTH_TASK   = 'mobygate-auth-refresh';
+
+/** Run a PowerShell command, return {ok, stdout, stderr, code}. */
+function runPowershell(script, { timeoutMs = 30_000 } = {}) {
+  if (!IS_WIN) throw new Error('runPowershell called on non-Windows');
+  const r = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    windowsHide: true,
+  });
+  return {
+    ok: r.status === 0,
+    code: r.status,
+    stdout: (r.stdout || '').trim(),
+    stderr: (r.stderr || '').trim(),
+  };
+}
+
+/**
+ * Register both scheduled tasks and start the server task now.
+ * Returns { ok, installed: [names], errors: [] }.
+ */
+export function installWindowsServices({ installPath, nodeBin, port, authRefreshHours = 4 }) {
+  if (!IS_WIN) throw new Error('installWindowsServices called on non-Windows');
+  const esc = (p) => p.replace(/'/g, "''"); // PowerShell single-quote escape
+  const installed = [];
+  const errors = [];
+
+  // ---- Logs dir must exist before cmd.exe >> tries to write to it ----
+  const logsDir = LOGS_DIR;
+  if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
+
+  // ---- Server: .cmd launcher ----
+  // Task Scheduler + cmd.exe + stdout redirection is a quote-escaping swamp.
+  // Instead of wrestling with /c "\"node\" ... >> \"log\"" gymnastics, we
+  // emit a standalone .cmd launcher that handles redirection itself, and
+  // Task Scheduler just executes that file directly. Standard Windows
+  // pattern, zero quoting ambiguity.
+  const launcherPath = join(installPath, '.mobygate-server.cmd');
+  const launcher = [
+    '@echo off',
+    `cd /d "${installPath}"`,
+    `"${nodeBin}" server.js >> "${join(logsDir, 'server.log').replace(/\//g, '\\')}" 2>&1`,
+    '',
+  ].join('\r\n');
+  writeFileSync(launcherPath, launcher);
+
+  // ---- Server task ----
+  // Executes the launcher directly. RestartCount=3 + RestartInterval=1min
+  // gives auto-restart on crash. ExecutionTimeLimit=0 = run indefinitely.
+  const serverScript = `
+    $action    = New-ScheduledTaskAction -Execute '${esc(launcherPath)}' -WorkingDirectory '${esc(installPath)}'
+    $trigger   = New-ScheduledTaskTrigger -AtLogon
+    $settings  = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit (New-TimeSpan -Seconds 0) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
+    $principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Limited
+    Register-ScheduledTask -TaskName '${WIN_SERVER_TASK}' -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Force | Out-Null
+    # Start it immediately so the server is running now, not only after next logon
+    Start-ScheduledTask -TaskName '${WIN_SERVER_TASK}'
+    Write-Output 'ok'
+  `;
+  const r1 = runPowershell(serverScript);
+  if (r1.ok) installed.push(WIN_SERVER_TASK);
+  else errors.push({ task: WIN_SERVER_TASK, stderr: r1.stderr });
+
+  // ---- Auth refresh task ----
+  const authIntervalHours = Math.max(1, Math.floor(Number(authRefreshHours) || 4));
+  const authScript = `
+    $action   = New-ScheduledTaskAction -Execute '${esc(nodeBin)}' -Argument 'scripts/auth-refresh.js' -WorkingDirectory '${esc(installPath)}'
+    $trigger  = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) -RepetitionInterval (New-TimeSpan -Hours ${authIntervalHours})
+    $settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
+    $principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Limited
+    Register-ScheduledTask -TaskName '${WIN_AUTH_TASK}' -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Force | Out-Null
+    Write-Output 'ok'
+  `;
+  const r2 = runPowershell(authScript);
+  if (r2.ok) installed.push(WIN_AUTH_TASK);
+  else errors.push({ task: WIN_AUTH_TASK, stderr: r2.stderr });
+
+  return { ok: errors.length === 0, installed, errors };
+}
+
+/** Query Task Scheduler for one task. Returns {exists, state, lastResult}. */
+export function queryWindowsTask(taskName) {
+  if (!IS_WIN) return { supported: false };
+  const r = runPowershell(`
+    $t = Get-ScheduledTask -TaskName '${taskName}' -ErrorAction SilentlyContinue
+    if (-not $t) { Write-Output 'NOTFOUND'; exit 0 }
+    $info = Get-ScheduledTaskInfo -TaskName '${taskName}'
+    Write-Output "STATE=$($t.State);LASTRESULT=$($info.LastTaskResult);NEXTRUN=$($info.NextRunTime)"
+  `);
+  if (!r.ok) return { exists: false, error: r.stderr };
+  const out = r.stdout;
+  if (out === 'NOTFOUND') return { exists: false };
+  const stateMatch = /STATE=([^;]+)/.exec(out);
+  const resultMatch = /LASTRESULT=(-?\d+)/.exec(out);
+  return {
+    exists: true,
+    state: stateMatch ? stateMatch[1] : null,   // Ready | Running | Disabled
+    lastResult: resultMatch ? parseInt(resultMatch[1], 10) : null,
+  };
+}
+
+export function startWindowsTask(taskName) {
+  if (!IS_WIN) return { ok: false };
+  return runPowershell(`Start-ScheduledTask -TaskName '${taskName}'; Write-Output 'ok'`);
+}
+
+export function stopWindowsTask(taskName) {
+  if (!IS_WIN) return { ok: false };
+  // Stop-ScheduledTask errors if not running; silence that case.
+  return runPowershell(`Stop-ScheduledTask -TaskName '${taskName}' -ErrorAction SilentlyContinue; Write-Output 'ok'`);
+}
+
+export function uninstallWindowsServices({ installPath } = {}) {
+  if (!IS_WIN) return [];
+  const results = [];
+  for (const name of [WIN_SERVER_TASK, WIN_AUTH_TASK]) {
+    const r = runPowershell(`
+      $t = Get-ScheduledTask -TaskName '${name}' -ErrorAction SilentlyContinue
+      if ($t) {
+        Stop-ScheduledTask -TaskName '${name}' -ErrorAction SilentlyContinue
+        Unregister-ScheduledTask -TaskName '${name}' -Confirm:$false
+        Write-Output 'removed'
+      } else {
+        Write-Output 'notfound'
+      }
+    `);
+    if (!r.ok) results.push({ name, removed: false, error: r.stderr });
+    else results.push({ name, removed: r.stdout === 'removed', reason: r.stdout });
+  }
+  // Best-effort cleanup of the launcher file
+  if (installPath) {
+    const launcherPath = join(installPath, '.mobygate-server.cmd');
+    try {
+      if (existsSync(launcherPath)) unlinkSync(launcherPath);
+    } catch {}
+  }
+  return results;
+}
+
+export const WIN_LABELS = {
+  server: WIN_SERVER_TASK,
+  auth: WIN_AUTH_TASK,
+};
+
+// ---------------------------------------------------------------------------
+// Linux — systemd user units
+// ---------------------------------------------------------------------------
+// Three units installed to ~/.config/systemd/user/:
+//   mobygate-server.service   — long-running proxy, Restart=on-failure
+//   mobygate-auth.service     — oneshot refresh probe (invoked by timer)
+//   mobygate-auth.timer       — fires every 4h
+//
+// `systemctl --user` runs as the current user, no sudo needed. Note that
+// without `loginctl enable-linger <user>`, user services only run while
+// the user is logged in (interactive or SSH). That's fine for dev boxes;
+// print a tip about enable-linger for headless servers.
+
+const SYSTEMD_USER_DIR = join(homedir(), '.config', 'systemd', 'user');
+const LINUX_SERVER_UNIT = 'mobygate-server.service';
+const LINUX_AUTH_UNIT   = 'mobygate-auth.service';
+const LINUX_AUTH_TIMER  = 'mobygate-auth.timer';
+
+export const LINUX_UNITS = {
+  server: LINUX_SERVER_UNIT,
+  auth: LINUX_AUTH_UNIT,
+  timer: LINUX_AUTH_TIMER,
+};
+
+function systemctlUser(args, { timeoutMs = 15_000 } = {}) {
+  if (!IS_LINUX) throw new Error('systemctlUser called on non-Linux');
+  const r = spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8', timeout: timeoutMs });
+  return {
+    ok: r.status === 0,
+    code: r.status,
+    stdout: (r.stdout || '').trim(),
+    stderr: (r.stderr || '').trim(),
+  };
+}
+
+function writeSystemdUnit(name, content) {
+  if (!existsSync(SYSTEMD_USER_DIR)) mkdirSync(SYSTEMD_USER_DIR, { recursive: true });
+  const path = join(SYSTEMD_USER_DIR, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+/**
+ * Generate + install + enable both systemd user units (server + auth timer).
+ * Returns { ok, installed, errors }.
+ */
+export function installLinuxServices({ installPath, nodeBin, port, authRefreshHours = 4 }) {
+  if (!IS_LINUX) throw new Error('installLinuxServices called on non-Linux');
+  const installed = [];
+  const errors = [];
+
+  // Ensure logs dir exists before StandardOutput=append tries to write.
+  const logsDir = LOGS_DIR;
+  if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
+
+  // ---- Server unit ----
+  const serverUnit = `[Unit]
+Description=mobygate — OpenAI → Claude Max gateway
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=${installPath}
+ExecStart=${nodeBin} server.js
+Environment=PORT=${port}
+Environment=HOME=${homedir()}
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:${logsDir}/server.log
+StandardError=append:${logsDir}/server.err.log
+
+[Install]
+WantedBy=default.target
+`;
+  writeSystemdUnit(LINUX_SERVER_UNIT, serverUnit);
+
+  // ---- Auth service (oneshot, triggered by timer) ----
+  const authService = `[Unit]
+Description=mobygate — OAuth refresh probe
+
+[Service]
+Type=oneshot
+WorkingDirectory=${installPath}
+ExecStart=${nodeBin} scripts/auth-refresh.js
+Environment=HOME=${homedir()}
+StandardOutput=append:${logsDir}/auth-refresh.log
+StandardError=append:${logsDir}/auth-refresh.err.log
+`;
+  writeSystemdUnit(LINUX_AUTH_UNIT, authService);
+
+  // ---- Auth timer (every Nh, also fires 1 min after boot) ----
+  const authIntervalHours = Math.max(1, Math.floor(Number(authRefreshHours) || 4));
+  const authTimer = `[Unit]
+Description=mobygate — auth refresh every ${authIntervalHours}h
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=${authIntervalHours}h
+Unit=${LINUX_AUTH_UNIT}
+
+[Install]
+WantedBy=timers.target
+`;
+  writeSystemdUnit(LINUX_AUTH_TIMER, authTimer);
+
+  // ---- Reload + enable + start ----
+  const reload = systemctlUser(['daemon-reload']);
+  if (!reload.ok) errors.push({ unit: 'daemon-reload', stderr: reload.stderr });
+
+  const enableServer = systemctlUser(['enable', '--now', LINUX_SERVER_UNIT]);
+  if (enableServer.ok) installed.push(LINUX_SERVER_UNIT);
+  else errors.push({ unit: LINUX_SERVER_UNIT, stderr: enableServer.stderr });
+
+  const enableTimer = systemctlUser(['enable', '--now', LINUX_AUTH_TIMER]);
+  if (enableTimer.ok) installed.push(LINUX_AUTH_TIMER);
+  else errors.push({ unit: LINUX_AUTH_TIMER, stderr: enableTimer.stderr });
+
+  return { ok: errors.length === 0, installed, errors };
+}
+
+/** Stop + disable + remove all mobygate systemd user units. */
+export function uninstallLinuxServices() {
+  if (!IS_LINUX) return [];
+  const results = [];
+  // Stop + disable in reverse (timer first, then service)
+  for (const name of [LINUX_AUTH_TIMER, LINUX_SERVER_UNIT]) {
+    const r1 = systemctlUser(['disable', '--now', name]);
+    const path = join(SYSTEMD_USER_DIR, name);
+    let removed = false;
+    if (existsSync(path)) {
+      try { unlinkSync(path); removed = true; } catch (e) {/* ignore */}
+    }
+    results.push({ unit: name, removed, stopped: r1.ok });
+  }
+  // Auth .service is plain (only reachable via timer), remove it too
+  const authPath = join(SYSTEMD_USER_DIR, LINUX_AUTH_UNIT);
+  if (existsSync(authPath)) {
+    try { unlinkSync(authPath); results.push({ unit: LINUX_AUTH_UNIT, removed: true, stopped: true }); }
+    catch { results.push({ unit: LINUX_AUTH_UNIT, removed: false, stopped: false }); }
+  }
+  systemctlUser(['daemon-reload']);
+  return results;
+}
+
+/**
+ * Query a systemd user unit. Returns { exists, active, sub, mainPid, exitStatus }.
+ */
+export function queryLinuxUnit(unitName) {
+  if (!IS_LINUX) return { supported: false };
+  const r = systemctlUser(['show', '-p', 'LoadState,ActiveState,SubState,MainPID,ExecMainStatus', unitName]);
+  if (!r.ok) return { exists: false, error: r.stderr };
+  const pairs = {};
+  for (const line of r.stdout.split('\n')) {
+    const [k, ...rest] = line.split('=');
+    if (k) pairs[k] = rest.join('=');
+  }
+  const exists = pairs.LoadState && pairs.LoadState !== 'not-found';
+  return {
+    exists: !!exists,
+    active: pairs.ActiveState,    // active | inactive | failed | activating
+    sub: pairs.SubState,           // running | dead | ...
+    mainPid: pairs.MainPID && pairs.MainPID !== '0' ? parseInt(pairs.MainPID, 10) : null,
+    exitStatus: pairs.ExecMainStatus ? parseInt(pairs.ExecMainStatus, 10) : null,
+  };
+}
+
+export function startLinuxUnit(unitName) {
+  if (!IS_LINUX) return { ok: false };
+  return systemctlUser(['start', unitName]);
+}
+
+export function stopLinuxUnit(unitName) {
+  if (!IS_LINUX) return { ok: false };
+  return systemctlUser(['stop', unitName]);
+}
+
+/**
+ * Render installation instructions for non-macOS platforms as a string.
+ * mobygate init uses this as a fallback when auto-install fails, and
+ * Linux still gets printed instructions (systemd automation is next).
+ */
+export function nonMacInstallInstructions({ installPath, nodeBin, port }) {
+  if (IS_LINUX) {
+    return `
+Linux install — systemd user unit:
+
+  mkdir -p ~/.config/systemd/user
+
+  cat > ~/.config/systemd/user/mobygate-server.service <<EOF
+  [Unit]
+  Description=mobygate — OpenAI → Claude Max gateway
+  After=network.target
+
+  [Service]
+  Type=simple
+  WorkingDirectory=${installPath}
+  ExecStart=${nodeBin} server.js
+  Environment=PORT=${port}
+  Restart=on-failure
+  RestartSec=5
+
+  [Install]
+  WantedBy=default.target
+  EOF
+
+  systemctl --user daemon-reload
+  systemctl --user enable --now mobygate-server
+
+  # Auth refresh every 4h (service + timer pair):
+  cat > ~/.config/systemd/user/mobygate-auth.service <<EOF
+  [Unit]
+  Description=mobygate — OAuth refresh probe
+  [Service]
+  Type=oneshot
+  WorkingDirectory=${installPath}
+  ExecStart=${nodeBin} scripts/auth-refresh.js
+  EOF
+
+  cat > ~/.config/systemd/user/mobygate-auth.timer <<EOF
+  [Unit]
+  Description=mobygate — auth refresh every 4h
+  [Timer]
+  OnBootSec=1min
+  OnUnitActiveSec=4h
+  [Install]
+  WantedBy=timers.target
+  EOF
+
+  systemctl --user enable --now mobygate-auth.timer
+`;
+  }
+  if (IS_WIN) {
+    return `
+Windows install — Task Scheduler (PowerShell, elevated):
+
+  $node   = "${nodeBin.replace(/\\/g, '\\\\')}"
+  $script = "${installPath.replace(/\\/g, '\\\\')}"
+
+  # Server service (runs at login, restarts on crash via action retry):
+  $a = New-ScheduledTaskAction -Execute $node -Argument "server.js" -WorkingDirectory $script
+  $t = New-ScheduledTaskTrigger -AtLogon
+  Register-ScheduledTask -TaskName "mobygate-server" -Action $a -Trigger $t -RunLevel Highest
+
+  # Auth refresh every 4h:
+  $a2 = New-ScheduledTaskAction -Execute $node -Argument "scripts/auth-refresh.js" -WorkingDirectory $script
+  $t2 = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Hours 4)
+  Register-ScheduledTask -TaskName "mobygate-auth-refresh" -Action $a2 -Trigger $t2
+
+  # For more robust crash-restart, install the \`nssm\` service wrapper
+  # (https://nssm.cc/) and register mobygate as a proper Windows service.
+`;
+  }
+  return '(unsupported platform — install manually by running `node server.js`)';
+}

package/lib/session-store.js

@@ -0,0 +1,112 @@
+/**
+ * File-backed session store.
+ *
+ * Sessions map (client-supplied key → SDK session state) was previously
+ * in-memory only, which meant every `mobygate restart` or service
+ * crash wiped all active sessions. Any in-flight Hermes conversation
+ * using session keys had to start a fresh SDK session on the next
+ * request, losing its Claude-side context.
+ *
+ * This module persists that map to ~/.mobygate/sessions.json on every
+ * mutation (debounced 500 ms to absorb bursts) and rehydrates on boot.
+ * JSON is safe here — entries are small (< 200 B each) and we expect
+ * O(tens) of concurrent sessions, not thousands. No SQLite needed.
+ *
+ * Invariants:
+ *   - Expired sessions are filtered out on load, so the on-disk file
+ *     never grows unbounded even if cleanup didn't run before shutdown.
+ *   - All writes are atomic via write-to-tmp-then-rename, so a crash
+ *     mid-write never leaves a corrupt sessions.json.
+ *   - A corrupt file on load is logged and treated as empty — we never
+ *     refuse to start the server because sessions.json is malformed.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { CONFIG_DIR } from './config.js';
+
+export const SESSIONS_PATH = join(CONFIG_DIR, 'sessions.json');
+const TMP_SUFFIX = '.tmp';
+const DEBOUNCE_MS = 500;
+
+/**
+ * Read sessions.json and return a Map<string, SessionEntry>.
+ * Expired entries (older than ttlMs since lastUsed) are dropped.
+ * A missing or corrupt file is treated as "no sessions".
+ */
+export function loadSessions(ttlMs) {
+  if (!existsSync(SESSIONS_PATH)) return new Map();
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(SESSIONS_PATH, 'utf8'));
+  } catch (e) {
+    console.warn(`[session] failed to parse ${SESSIONS_PATH}: ${e.message} — starting fresh`);
+    return new Map();
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return new Map();
+  }
+  const now = Date.now();
+  const map = new Map();
+  let skipped = 0;
+  for (const [key, entry] of Object.entries(parsed)) {
+    if (!entry || typeof entry !== 'object') continue;
+    if (typeof entry.lastUsed !== 'number' || typeof entry.sdkSessionId !== 'string') {
+      skipped++;
+      continue;
+    }
+    if (now - entry.lastUsed > ttlMs) {
+      skipped++;
+      continue;
+    }
+    map.set(key, entry);
+  }
+  if (skipped > 0) {
+    console.log(`[session] loaded ${map.size} from disk (skipped ${skipped} expired or malformed)`);
+  }
+  return map;
+}
+
+// --- debounced persistence ------------------------------------------------
+let pendingTimer = null;
+let lastMap = null;
+
+/**
+ * Schedule a write of the given Map to sessions.json. If another save is
+ * already scheduled within DEBOUNCE_MS, the later call wins and the
+ * earlier one is coalesced. Any Map mutations the caller made since the
+ * previous save are captured because the Map is passed by reference.
+ */
+export function saveSessions(map) {
+  lastMap = map;
+  if (pendingTimer) return;
+  pendingTimer = setTimeout(() => {
+    pendingTimer = null;
+    writeNow(lastMap);
+  }, DEBOUNCE_MS);
+}
+
+/**
+ * Force an immediate synchronous flush. Intended for SIGTERM / SIGINT
+ * handlers so a shutdown during the debounce window doesn't lose the
+ * last few session updates.
+ */
+export function flushSessionsNow() {
+  if (pendingTimer) {
+    clearTimeout(pendingTimer);
+    pendingTimer = null;
+  }
+  if (lastMap) writeNow(lastMap);
+}
+
+function writeNow(map) {
+  try {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+    const obj = Object.fromEntries(map);
+    const tmp = SESSIONS_PATH + TMP_SUFFIX;
+    writeFileSync(tmp, JSON.stringify(obj, null, 2));
+    renameSync(tmp, SESSIONS_PATH); // atomic on POSIX, best-effort on Windows
+  } catch (e) {
+    console.warn(`[session] failed to save ${SESSIONS_PATH}: ${e.message}`);
+  }
+}