@venturewild/workspace 0.1.12 → 0.1.14

package/server/src/service.mjs

@@ -1,419 +1,419 @@
-// service.mjs — installs / removes the per-OS, NO-ADMIN autostart entry that
-// launches the WorkspaceSupervisor at login. See docs/always-on-design.md.
-//
-// Windows (proven end-to-end incl. a real reboot, 2026-05-30): writes a tiny VBS
-// that runs `node <cli> service run` with no window, and registers it under
-// HKCU\...\Run (per-user, NO admin / UAC).
-//
-// macOS (code-complete + unit-tested 2026-06-01; real-Mac reboot proof pending):
-// writes a `~/Library/LaunchAgents/<label>.plist` (RunAtLoad + KeepAlive +
-// ThrottleInterval). Install does NOT start it now (no `launchctl bootstrap`) —
-// launchd auto-loads the plist at the NEXT login, mirroring the Windows HKCU\Run
-// model. (Starting it at install time would grab :5173 and collide with the
-// `wild-workspace` the user runs this session.) Uninstall uses `launchctl bootout`
-// to stop any instance loaded from a prior login. Runs as the user, NO admin —
-// macOS 13+ shows a one-time "Background item added" toast + a Login Items toggle
-// (consent, not admin). launchd provides crash-restart for free; the supervisor
-// still owns the singleton lock + child watchdog.
-//
-// Linux (systemd --user) is designed but not yet implemented — it returns a clear
-// "not yet" result so callers degrade gracefully (the user runs `wild-workspace`).
-//
-// All state (the VBS / plist, service.json, the supervisor's lock/logs) lives in
-// the machine-global dir (~/.wild-workspace) or ~/Library/LaunchAgents, NEVER the
-// synced workspace (locked principle #1). Every external touch-point (reg.exe,
-// launchctl, kill) is an injected seam for testability.
-
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-const execFileP = promisify(execFile);
-
-export const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
-export const RUN_VALUE_NAME = 'WildWorkspace';
-export const LAUNCHD_LABEL = 'llc.venturewild.workspace';
-
-export function globalDir() { return path.join(os.homedir(), '.wild-workspace'); }
-function defaultLaunchAgentsDir() { return path.join(os.homedir(), 'Library', 'LaunchAgents'); }
-function currentUid() { return typeof process.getuid === 'function' ? process.getuid() : 0; }
-
-/** Is per-user autostart implemented for this platform yet? */
-export function isSupported(platform = process.platform) {
-  return platform === 'win32' || platform === 'darwin' || platform === 'linux';
-}
-
-/** Shared: read the supervisor's pidfile and report whether that pid is alive. */
-function supervisorLiveness(dir) {
-  let supervisorPid = null, supervisorAlive = false;
-  try { supervisorPid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim()) || null; } catch { /* none */ }
-  if (supervisorPid) {
-    try { process.kill(supervisorPid, 0); supervisorAlive = true; } catch (e) { supervisorAlive = !!(e && e.code === 'EPERM'); }
-  }
-  return { supervisorPid, supervisorAlive };
-}
-
-// --- Windows implementation -------------------------------------------------
-
-// A VBS that runs `node <cli> service run` with NO window (0 = SW_HIDE,
-// False = don't wait). VBS string literals escape a `"` as `""`.
-export function buildVbs(node, cli) {
-  const cmd = `"${node}" "${cli}" service run`;
-  const vbsArg = '"' + cmd.replace(/"/g, '""') + '"';
-  return [
-    "' wild-workspace always-on launcher (generated by `wild-workspace service install`).",
-    "' Starts the workspace supervisor hidden at login. Disable via",
-    "' `wild-workspace service uninstall` (removes the HKCU\\...\\Run value).",
-    `CreateObject("WScript.Shell").Run ${vbsArg}, 0, False`,
-    '',
-  ].join('\r\n');
-}
-
-/** The HKCU\Run value: launch the VBS via the windowless wscript host. */
-export function buildRunValue(vbs) { return `wscript.exe "${vbs}"`; }
-
-async function winInstall({ node, cli, workspaceDir, port, version }, { dir, execFileImpl }) {
-  fs.mkdirSync(dir, { recursive: true });
-  const vbs = path.join(dir, 'launch-hidden.vbs');
-  const serviceJson = path.join(dir, 'service.json');
-  fs.writeFileSync(vbs, buildVbs(node, cli), 'utf8');
-  fs.writeFileSync(
-    serviceJson,
-    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
-    'utf8',
-  );
-  const runValue = buildRunValue(vbs);
-  await execFileImpl('reg', ['add', RUN_KEY, '/v', RUN_VALUE_NAME, '/t', 'REG_SZ', '/d', runValue, '/f']);
-  return { installed: true, mechanism: 'HKCU\\Run', launcher: vbs, vbs, runValue, serviceJson };
-}
-
-async function winUninstall({ dir, execFileImpl, killImpl }) {
-  let removedKey = false;
-  try { await execFileImpl('reg', ['delete', RUN_KEY, '/v', RUN_VALUE_NAME, '/f']); removedKey = true; } catch { /* not present */ }
-  let stoppedPid = null;
-  try {
-    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
-    if (pid) { killImpl(pid); stoppedPid = pid; }
-  } catch { /* none running */ }
-  for (const f of ['launch-hidden.vbs', 'service.json']) { try { fs.unlinkSync(path.join(dir, f)); } catch { /* gone */ } }
-  return { uninstalled: true, removedKey, stoppedPid };
-}
-
-async function winStatus({ dir, execFileImpl, probeImpl, port }) {
-  let installed = false, runValue = null;
-  try {
-    const { stdout } = await execFileImpl('reg', ['query', RUN_KEY, '/v', RUN_VALUE_NAME]);
-    installed = new RegExp(RUN_VALUE_NAME, 'i').test(stdout);
-    runValue = (stdout.match(/REG_SZ\s+(.*?)\s*$/m) || [])[1] || null;
-  } catch { /* value absent → not installed */ }
-  const { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
-  const serverUp = await probeImpl(port);
-  return { installed, runValue, supervisorPid, supervisorAlive, serverUp };
-}
-
-// --- macOS implementation ---------------------------------------------------
-
-export function plistPath(launchAgentsDir) {
-  return path.join(launchAgentsDir, `${LAUNCHD_LABEL}.plist`);
-}
-
-function xmlEscape(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
-// A LaunchAgent that runs `node <cli> service run` at login + relaunches it if it
-// dies (KeepAlive). ThrottleInterval bounds the restart rate. Output is logged to
-// ~/.wild-workspace so a silent death is debuggable (footgun checklist §8).
-export function buildPlist({ node, cli, workspaceDir, outLog, errLog, label = LAUNCHD_LABEL }) {
-  const args = [node, cli, 'service', 'run'].map((a) => `    <string>${xmlEscape(a)}</string>`);
-  const env = workspaceDir ? [
-    '  <key>EnvironmentVariables</key>',
-    '  <dict>',
-    '    <key>WILD_WORKSPACE_DIR</key>',
-    `    <string>${xmlEscape(workspaceDir)}</string>`,
-    '  </dict>',
-  ] : [];
-  return [
-    '<?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">',
-    '<plist version="1.0">',
-    '<dict>',
-    '  <key>Label</key>',
-    `  <string>${xmlEscape(label)}</string>`,
-    '  <key>ProgramArguments</key>',
-    '  <array>',
-    ...args,
-    '  </array>',
-    '  <key>RunAtLoad</key>',
-    '  <true/>',
-    '  <key>KeepAlive</key>',
-    '  <true/>',
-    '  <key>ThrottleInterval</key>',
-    '  <integer>10</integer>',
-    ...env,
-    '  <key>StandardOutPath</key>',
-    `  <string>${xmlEscape(outLog)}</string>`,
-    '  <key>StandardErrorPath</key>',
-    `  <string>${xmlEscape(errLog)}</string>`,
-    '</dict>',
-    '</plist>',
-    '',
-  ].join('\n');
-}
-
-async function macInstall({ node, cli, workspaceDir, port, version }, { dir, launchAgentsDir }) {
-  fs.mkdirSync(dir, { recursive: true });
-  fs.mkdirSync(launchAgentsDir, { recursive: true });
-  const plist = plistPath(launchAgentsDir);
-  const serviceJson = path.join(dir, 'service.json');
-  const outLog = path.join(dir, 'launchagent.out.log');
-  const errLog = path.join(dir, 'launchagent.err.log');
-  fs.writeFileSync(plist, buildPlist({ node, cli, workspaceDir, outLog, errLog }), 'utf8');
-  fs.writeFileSync(
-    serviceJson,
-    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
-    'utf8',
-  );
-  // Deliberately do NOT `launchctl bootstrap` here. bootstrap + RunAtLoad would
-  // start the supervisor immediately, grabbing :5173 — then the `wild-workspace`
-  // the user runs *this session* collides on the port (createServer rejects on
-  // EADDRINUSE). Dropping the plist into ~/Library/LaunchAgents is enough:
-  // launchd auto-loads it at the NEXT login (RunAtLoad fires then). This mirrors
-  // the proven Windows HKCU\Run model, which also only fires at login — so the
-  // current session is the manual `wild-workspace`, and always-on takes over
-  // from the next login/reboot (which is also the cleanest B5 proof).
-  return { installed: true, mechanism: 'LaunchAgent', launcher: plist, plist, label: LAUNCHD_LABEL, runValue: plist, serviceJson, startsAtNextLogin: true };
-}
-
-async function macUninstall({ dir, launchAgentsDir, execFileImpl, killImpl, uid }) {
-  const plist = plistPath(launchAgentsDir);
-  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
-  try {
-    await execFileImpl('launchctl', ['bootout', target]);
-  } catch {
-    try { await execFileImpl('launchctl', ['unload', '-w', plist]); } catch { /* not loaded */ }
-  }
-  // launchd's bootout SIGTERMs the launchd-managed supervisor; a manually-started
-  // one still holds the lock, so stop it too (mirrors the Windows path).
-  let stoppedPid = null;
-  try {
-    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
-    if (pid) { killImpl(pid); stoppedPid = pid; }
-  } catch { /* none running */ }
-  let removedKey = false;
-  try { if (fs.existsSync(plist)) { fs.unlinkSync(plist); removedKey = true; } } catch { /* gone */ }
-  try { fs.unlinkSync(path.join(dir, 'service.json')); } catch { /* gone */ }
-  return { uninstalled: true, removedKey, stoppedPid };
-}
-
-async function macStatus({ dir, launchAgentsDir, execFileImpl, probeImpl, uid, port }) {
-  const plist = plistPath(launchAgentsDir);
-  const installed = fs.existsSync(plist); // the plist IS the persistent registration
-  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
-  let loaded = false, launchdPid = null;
-  try {
-    const { stdout } = await execFileImpl('launchctl', ['print', target]);
-    launchdPid = Number((stdout.match(/\bpid\s*=\s*(\d+)/i) || [])[1]) || null;
-    loaded = launchdPid !== null || /state\s*=\s*running/i.test(stdout);
-  } catch { /* not loaded into launchd */ }
-  let { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
-  if (launchdPid) { supervisorPid = launchdPid; supervisorAlive = true; }
-  else if (loaded) { supervisorAlive = true; }
-  const serverUp = await probeImpl(port);
-  return { installed, runValue: installed ? plist : null, supervisorPid, supervisorAlive, serverUp, loaded };
-}
-
-// --- Linux implementation (systemd --user) ----------------------------------
-//
-// Mirrors the macOS model: write the unit, `enable` it for the NEXT login, but
-// do NOT `--now` it at install time (that would start the supervisor and grab
-// :5173, colliding with the `wild-workspace` the user runs this session). The
-// user systemd manager auto-starts WantedBy=default.target units at login.
-// Crash-restart is free via Restart=always (footgun checklist §8). `systemctl
-// --user` needs a user DBus/session bus; if it's absent (headless box) the unit
-// file is still written and `enabled:false` is reported so the caller can warn.
-
-export const SYSTEMD_UNIT = 'wild-workspace.service';
-
-function defaultSystemdUserDir() {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  return xdg ? path.join(xdg, 'systemd', 'user') : path.join(os.homedir(), '.config', 'systemd', 'user');
-}
-export function unitPath(systemdUserDir) {
-  return path.join(systemdUserDir, SYSTEMD_UNIT);
-}
-
-// A user unit that runs `node <cli> service run` at login + relaunches on exit.
-// `WantedBy=default.target` is the USER manager's login target — NOT
-// `multi-user.target` (which doesn't exist in user systemd; a real VS Code bug,
-// always-on-design.md §7). Paths are double-quoted so spaces in $HOME survive.
-export function buildUnit({ node, cli, workspaceDir }) {
-  const env = workspaceDir ? [`Environment=WILD_WORKSPACE_DIR=${workspaceDir}`] : [];
-  return [
-    '[Unit]',
-    'Description=wild-workspace always-on supervisor',
-    'After=default.target',
-    '',
-    '[Service]',
-    'Type=simple',
-    `ExecStart="${node}" "${cli}" service run`,
-    'Restart=always',
-    'RestartSec=2',
-    ...env,
-    '',
-    '[Install]',
-    'WantedBy=default.target',
-    '',
-  ].join('\n');
-}
-
-async function linuxInstall({ node, cli, workspaceDir, port, version }, { dir, systemdUserDir, execFileImpl }) {
-  fs.mkdirSync(dir, { recursive: true });
-  fs.mkdirSync(systemdUserDir, { recursive: true });
-  const unit = unitPath(systemdUserDir);
-  const serviceJson = path.join(dir, 'service.json');
-  fs.writeFileSync(unit, buildUnit({ node, cli, workspaceDir }), 'utf8');
-  fs.writeFileSync(
-    serviceJson,
-    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
-    'utf8',
-  );
-  // Enable for the NEXT login (no --now → don't grab :5173 this session). Both
-  // calls are best-effort: a box without a user session bus still gets the unit
-  // file, and `enabled:false` tells the caller to warn instead of failing hard.
-  let enabled = false, note = null;
-  try {
-    await execFileImpl('systemctl', ['--user', 'daemon-reload']);
-    await execFileImpl('systemctl', ['--user', 'enable', SYSTEMD_UNIT]);
-    enabled = true;
-  } catch (e) {
-    note = `unit written but \`systemctl --user enable\` failed (${String(e?.message || e).split('\n')[0]}); ` +
-      `run it after logging into a graphical session, or start manually with \`wild-workspace\`.`;
-  }
-  return { installed: true, mechanism: 'systemd --user', launcher: unit, unit, runValue: unit, serviceJson, enabled, startsAtNextLogin: true, note };
-}
-
-async function linuxUninstall({ dir, systemdUserDir, execFileImpl, killImpl }) {
-  // disable --now both stops a running instance and removes the login symlink.
-  let disabled = false;
-  try { await execFileImpl('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]); disabled = true; } catch { /* not enabled */ }
-  const unit = unitPath(systemdUserDir);
-  let removedKey = false;
-  try { if (fs.existsSync(unit)) { fs.unlinkSync(unit); removedKey = true; } } catch { /* gone */ }
-  try { await execFileImpl('systemctl', ['--user', 'daemon-reload']); } catch { /* no session bus */ }
-  // A manually-started supervisor still holds the lock — stop it too (mirror).
-  let stoppedPid = null;
-  try {
-    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
-    if (pid) { killImpl(pid); stoppedPid = pid; }
-  } catch { /* none running */ }
-  try { fs.unlinkSync(path.join(dir, 'service.json')); } catch { /* gone */ }
-  return { uninstalled: true, removedKey, disabled, stoppedPid };
-}
-
-async function linuxStatus({ dir, systemdUserDir, execFileImpl, probeImpl, port }) {
-  const unit = unitPath(systemdUserDir);
-  const installed = fs.existsSync(unit); // the unit file IS the persistent registration
-  let enabled = false, active = false, mainPid = null;
-  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT]); enabled = /enabled/.test(stdout); } catch { /* not enabled / no bus */ }
-  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]); active = /^active/m.test(stdout.trim()); } catch { /* inactive */ }
-  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'show', SYSTEMD_UNIT, '-p', 'MainPID', '--value']); mainPid = Number(String(stdout).trim()) || null; } catch { /* none */ }
-  let { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
-  if (mainPid) { supervisorPid = mainPid; supervisorAlive = true; }
-  else if (active) { supervisorAlive = true; }
-  const serverUp = await probeImpl(port);
-  return { installed, runValue: installed ? unit : null, supervisorPid, supervisorAlive, serverUp, enabled, active };
-}
-
-// --- public API (platform dispatch) ----------------------------------------
-
-const unsupported = (platform, key) => ({
-  [key]: false,
-  supported: false,
-  platform,
-  message: `always-on autostart for ${platform} is not implemented yet — run \`wild-workspace\` to start manually (see docs/always-on-design.md)`,
-});
-
-export async function installService(opts = {}, deps = {}) {
-  const platform = deps.platform || process.platform;
-  if (platform === 'win32') {
-    return winInstall(opts, { dir: deps.dir || globalDir(), execFileImpl: deps.execFileImpl || execFileP });
-  }
-  if (platform === 'darwin') {
-    return macInstall(opts, {
-      dir: deps.dir || globalDir(),
-      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
-    });
-  }
-  if (platform === 'linux') {
-    return linuxInstall(opts, {
-      dir: deps.dir || globalDir(),
-      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-    });
-  }
-  return unsupported(platform, 'installed');
-}
-
-export async function uninstallService(deps = {}) {
-  const platform = deps.platform || process.platform;
-  if (platform === 'win32') {
-    return winUninstall({
-      dir: deps.dir || globalDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
-    });
-  }
-  if (platform === 'darwin') {
-    return macUninstall({
-      dir: deps.dir || globalDir(),
-      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
-      uid: deps.uid ?? currentUid(),
-    });
-  }
-  if (platform === 'linux') {
-    return linuxUninstall({
-      dir: deps.dir || globalDir(),
-      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
-    });
-  }
-  return unsupported(platform, 'uninstalled');
-}
-
-export async function serviceStatus(opts = {}, deps = {}) {
-  const platform = deps.platform || process.platform;
-  if (platform === 'win32') {
-    return winStatus({
-      dir: deps.dir || globalDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      probeImpl: deps.probeImpl || (async () => false),
-      port: opts.port || 5173,
-    });
-  }
-  if (platform === 'darwin') {
-    return macStatus({
-      dir: deps.dir || globalDir(),
-      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      probeImpl: deps.probeImpl || (async () => false),
-      uid: deps.uid ?? currentUid(),
-      port: opts.port || 5173,
-    });
-  }
-  if (platform === 'linux') {
-    return linuxStatus({
-      dir: deps.dir || globalDir(),
-      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
-      execFileImpl: deps.execFileImpl || execFileP,
-      probeImpl: deps.probeImpl || (async () => false),
-      port: opts.port || 5173,
-    });
-  }
-  return { supported: false, platform };
-}
+// service.mjs — installs / removes the per-OS, NO-ADMIN autostart entry that
+// launches the WorkspaceSupervisor at login. See docs/always-on-design.md.
+//
+// Windows (proven end-to-end incl. a real reboot, 2026-05-30): writes a tiny VBS
+// that runs `node <cli> service run` with no window, and registers it under
+// HKCU\...\Run (per-user, NO admin / UAC).
+//
+// macOS (code-complete + unit-tested 2026-06-01; real-Mac reboot proof pending):
+// writes a `~/Library/LaunchAgents/<label>.plist` (RunAtLoad + KeepAlive +
+// ThrottleInterval). Install does NOT start it now (no `launchctl bootstrap`) —
+// launchd auto-loads the plist at the NEXT login, mirroring the Windows HKCU\Run
+// model. (Starting it at install time would grab :5173 and collide with the
+// `wild-workspace` the user runs this session.) Uninstall uses `launchctl bootout`
+// to stop any instance loaded from a prior login. Runs as the user, NO admin —
+// macOS 13+ shows a one-time "Background item added" toast + a Login Items toggle
+// (consent, not admin). launchd provides crash-restart for free; the supervisor
+// still owns the singleton lock + child watchdog.
+//
+// Linux (systemd --user) is designed but not yet implemented — it returns a clear
+// "not yet" result so callers degrade gracefully (the user runs `wild-workspace`).
+//
+// All state (the VBS / plist, service.json, the supervisor's lock/logs) lives in
+// the machine-global dir (~/.wild-workspace) or ~/Library/LaunchAgents, NEVER the
+// synced workspace (locked principle #1). Every external touch-point (reg.exe,
+// launchctl, kill) is an injected seam for testability.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const execFileP = promisify(execFile);
+
+export const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+export const RUN_VALUE_NAME = 'WildWorkspace';
+export const LAUNCHD_LABEL = 'llc.venturewild.workspace';
+
+export function globalDir() { return path.join(os.homedir(), '.wild-workspace'); }
+function defaultLaunchAgentsDir() { return path.join(os.homedir(), 'Library', 'LaunchAgents'); }
+function currentUid() { return typeof process.getuid === 'function' ? process.getuid() : 0; }
+
+/** Is per-user autostart implemented for this platform yet? */
+export function isSupported(platform = process.platform) {
+  return platform === 'win32' || platform === 'darwin' || platform === 'linux';
+}
+
+/** Shared: read the supervisor's pidfile and report whether that pid is alive. */
+function supervisorLiveness(dir) {
+  let supervisorPid = null, supervisorAlive = false;
+  try { supervisorPid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim()) || null; } catch { /* none */ }
+  if (supervisorPid) {
+    try { process.kill(supervisorPid, 0); supervisorAlive = true; } catch (e) { supervisorAlive = !!(e && e.code === 'EPERM'); }
+  }
+  return { supervisorPid, supervisorAlive };
+}
+
+// --- Windows implementation -------------------------------------------------
+
+// A VBS that runs `node <cli> service run` with NO window (0 = SW_HIDE,
+// False = don't wait). VBS string literals escape a `"` as `""`.
+export function buildVbs(node, cli) {
+  const cmd = `"${node}" "${cli}" service run`;
+  const vbsArg = '"' + cmd.replace(/"/g, '""') + '"';
+  return [
+    "' wild-workspace always-on launcher (generated by `wild-workspace service install`).",
+    "' Starts the workspace supervisor hidden at login. Disable via",
+    "' `wild-workspace service uninstall` (removes the HKCU\\...\\Run value).",
+    `CreateObject("WScript.Shell").Run ${vbsArg}, 0, False`,
+    '',
+  ].join('\r\n');
+}
+
+/** The HKCU\Run value: launch the VBS via the windowless wscript host. */
+export function buildRunValue(vbs) { return `wscript.exe "${vbs}"`; }
+
+async function winInstall({ node, cli, workspaceDir, port, version }, { dir, execFileImpl }) {
+  fs.mkdirSync(dir, { recursive: true });
+  const vbs = path.join(dir, 'launch-hidden.vbs');
+  const serviceJson = path.join(dir, 'service.json');
+  fs.writeFileSync(vbs, buildVbs(node, cli), 'utf8');
+  fs.writeFileSync(
+    serviceJson,
+    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
+    'utf8',
+  );
+  const runValue = buildRunValue(vbs);
+  await execFileImpl('reg', ['add', RUN_KEY, '/v', RUN_VALUE_NAME, '/t', 'REG_SZ', '/d', runValue, '/f']);
+  return { installed: true, mechanism: 'HKCU\\Run', launcher: vbs, vbs, runValue, serviceJson };
+}
+
+async function winUninstall({ dir, execFileImpl, killImpl }) {
+  let removedKey = false;
+  try { await execFileImpl('reg', ['delete', RUN_KEY, '/v', RUN_VALUE_NAME, '/f']); removedKey = true; } catch { /* not present */ }
+  let stoppedPid = null;
+  try {
+    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
+    if (pid) { killImpl(pid); stoppedPid = pid; }
+  } catch { /* none running */ }
+  for (const f of ['launch-hidden.vbs', 'service.json']) { try { fs.unlinkSync(path.join(dir, f)); } catch { /* gone */ } }
+  return { uninstalled: true, removedKey, stoppedPid };
+}
+
+async function winStatus({ dir, execFileImpl, probeImpl, port }) {
+  let installed = false, runValue = null;
+  try {
+    const { stdout } = await execFileImpl('reg', ['query', RUN_KEY, '/v', RUN_VALUE_NAME]);
+    installed = new RegExp(RUN_VALUE_NAME, 'i').test(stdout);
+    runValue = (stdout.match(/REG_SZ\s+(.*?)\s*$/m) || [])[1] || null;
+  } catch { /* value absent → not installed */ }
+  const { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
+  const serverUp = await probeImpl(port);
+  return { installed, runValue, supervisorPid, supervisorAlive, serverUp };
+}
+
+// --- macOS implementation ---------------------------------------------------
+
+export function plistPath(launchAgentsDir) {
+  return path.join(launchAgentsDir, `${LAUNCHD_LABEL}.plist`);
+}
+
+function xmlEscape(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// A LaunchAgent that runs `node <cli> service run` at login + relaunches it if it
+// dies (KeepAlive). ThrottleInterval bounds the restart rate. Output is logged to
+// ~/.wild-workspace so a silent death is debuggable (footgun checklist §8).
+export function buildPlist({ node, cli, workspaceDir, outLog, errLog, label = LAUNCHD_LABEL }) {
+  const args = [node, cli, 'service', 'run'].map((a) => `    <string>${xmlEscape(a)}</string>`);
+  const env = workspaceDir ? [
+    '  <key>EnvironmentVariables</key>',
+    '  <dict>',
+    '    <key>WILD_WORKSPACE_DIR</key>',
+    `    <string>${xmlEscape(workspaceDir)}</string>`,
+    '  </dict>',
+  ] : [];
+  return [
+    '<?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">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${xmlEscape(label)}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...args,
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '  <key>ThrottleInterval</key>',
+    '  <integer>10</integer>',
+    ...env,
+    '  <key>StandardOutPath</key>',
+    `  <string>${xmlEscape(outLog)}</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${xmlEscape(errLog)}</string>`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+async function macInstall({ node, cli, workspaceDir, port, version }, { dir, launchAgentsDir }) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(launchAgentsDir, { recursive: true });
+  const plist = plistPath(launchAgentsDir);
+  const serviceJson = path.join(dir, 'service.json');
+  const outLog = path.join(dir, 'launchagent.out.log');
+  const errLog = path.join(dir, 'launchagent.err.log');
+  fs.writeFileSync(plist, buildPlist({ node, cli, workspaceDir, outLog, errLog }), 'utf8');
+  fs.writeFileSync(
+    serviceJson,
+    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
+    'utf8',
+  );
+  // Deliberately do NOT `launchctl bootstrap` here. bootstrap + RunAtLoad would
+  // start the supervisor immediately, grabbing :5173 — then the `wild-workspace`
+  // the user runs *this session* collides on the port (createServer rejects on
+  // EADDRINUSE). Dropping the plist into ~/Library/LaunchAgents is enough:
+  // launchd auto-loads it at the NEXT login (RunAtLoad fires then). This mirrors
+  // the proven Windows HKCU\Run model, which also only fires at login — so the
+  // current session is the manual `wild-workspace`, and always-on takes over
+  // from the next login/reboot (which is also the cleanest B5 proof).
+  return { installed: true, mechanism: 'LaunchAgent', launcher: plist, plist, label: LAUNCHD_LABEL, runValue: plist, serviceJson, startsAtNextLogin: true };
+}
+
+async function macUninstall({ dir, launchAgentsDir, execFileImpl, killImpl, uid }) {
+  const plist = plistPath(launchAgentsDir);
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  try {
+    await execFileImpl('launchctl', ['bootout', target]);
+  } catch {
+    try { await execFileImpl('launchctl', ['unload', '-w', plist]); } catch { /* not loaded */ }
+  }
+  // launchd's bootout SIGTERMs the launchd-managed supervisor; a manually-started
+  // one still holds the lock, so stop it too (mirrors the Windows path).
+  let stoppedPid = null;
+  try {
+    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
+    if (pid) { killImpl(pid); stoppedPid = pid; }
+  } catch { /* none running */ }
+  let removedKey = false;
+  try { if (fs.existsSync(plist)) { fs.unlinkSync(plist); removedKey = true; } } catch { /* gone */ }
+  try { fs.unlinkSync(path.join(dir, 'service.json')); } catch { /* gone */ }
+  return { uninstalled: true, removedKey, stoppedPid };
+}
+
+async function macStatus({ dir, launchAgentsDir, execFileImpl, probeImpl, uid, port }) {
+  const plist = plistPath(launchAgentsDir);
+  const installed = fs.existsSync(plist); // the plist IS the persistent registration
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  let loaded = false, launchdPid = null;
+  try {
+    const { stdout } = await execFileImpl('launchctl', ['print', target]);
+    launchdPid = Number((stdout.match(/\bpid\s*=\s*(\d+)/i) || [])[1]) || null;
+    loaded = launchdPid !== null || /state\s*=\s*running/i.test(stdout);
+  } catch { /* not loaded into launchd */ }
+  let { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
+  if (launchdPid) { supervisorPid = launchdPid; supervisorAlive = true; }
+  else if (loaded) { supervisorAlive = true; }
+  const serverUp = await probeImpl(port);
+  return { installed, runValue: installed ? plist : null, supervisorPid, supervisorAlive, serverUp, loaded };
+}
+
+// --- Linux implementation (systemd --user) ----------------------------------
+//
+// Mirrors the macOS model: write the unit, `enable` it for the NEXT login, but
+// do NOT `--now` it at install time (that would start the supervisor and grab
+// :5173, colliding with the `wild-workspace` the user runs this session). The
+// user systemd manager auto-starts WantedBy=default.target units at login.
+// Crash-restart is free via Restart=always (footgun checklist §8). `systemctl
+// --user` needs a user DBus/session bus; if it's absent (headless box) the unit
+// file is still written and `enabled:false` is reported so the caller can warn.
+
+export const SYSTEMD_UNIT = 'wild-workspace.service';
+
+function defaultSystemdUserDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return xdg ? path.join(xdg, 'systemd', 'user') : path.join(os.homedir(), '.config', 'systemd', 'user');
+}
+export function unitPath(systemdUserDir) {
+  return path.join(systemdUserDir, SYSTEMD_UNIT);
+}
+
+// A user unit that runs `node <cli> service run` at login + relaunches on exit.
+// `WantedBy=default.target` is the USER manager's login target — NOT
+// `multi-user.target` (which doesn't exist in user systemd; a real VS Code bug,
+// always-on-design.md §7). Paths are double-quoted so spaces in $HOME survive.
+export function buildUnit({ node, cli, workspaceDir }) {
+  const env = workspaceDir ? [`Environment=WILD_WORKSPACE_DIR=${workspaceDir}`] : [];
+  return [
+    '[Unit]',
+    'Description=wild-workspace always-on supervisor',
+    'After=default.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart="${node}" "${cli}" service run`,
+    'Restart=always',
+    'RestartSec=2',
+    ...env,
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+async function linuxInstall({ node, cli, workspaceDir, port, version }, { dir, systemdUserDir, execFileImpl }) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(systemdUserDir, { recursive: true });
+  const unit = unitPath(systemdUserDir);
+  const serviceJson = path.join(dir, 'service.json');
+  fs.writeFileSync(unit, buildUnit({ node, cli, workspaceDir }), 'utf8');
+  fs.writeFileSync(
+    serviceJson,
+    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
+    'utf8',
+  );
+  // Enable for the NEXT login (no --now → don't grab :5173 this session). Both
+  // calls are best-effort: a box without a user session bus still gets the unit
+  // file, and `enabled:false` tells the caller to warn instead of failing hard.
+  let enabled = false, note = null;
+  try {
+    await execFileImpl('systemctl', ['--user', 'daemon-reload']);
+    await execFileImpl('systemctl', ['--user', 'enable', SYSTEMD_UNIT]);
+    enabled = true;
+  } catch (e) {
+    note = `unit written but \`systemctl --user enable\` failed (${String(e?.message || e).split('\n')[0]}); ` +
+      `run it after logging into a graphical session, or start manually with \`wild-workspace\`.`;
+  }
+  return { installed: true, mechanism: 'systemd --user', launcher: unit, unit, runValue: unit, serviceJson, enabled, startsAtNextLogin: true, note };
+}
+
+async function linuxUninstall({ dir, systemdUserDir, execFileImpl, killImpl }) {
+  // disable --now both stops a running instance and removes the login symlink.
+  let disabled = false;
+  try { await execFileImpl('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]); disabled = true; } catch { /* not enabled */ }
+  const unit = unitPath(systemdUserDir);
+  let removedKey = false;
+  try { if (fs.existsSync(unit)) { fs.unlinkSync(unit); removedKey = true; } } catch { /* gone */ }
+  try { await execFileImpl('systemctl', ['--user', 'daemon-reload']); } catch { /* no session bus */ }
+  // A manually-started supervisor still holds the lock — stop it too (mirror).
+  let stoppedPid = null;
+  try {
+    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
+    if (pid) { killImpl(pid); stoppedPid = pid; }
+  } catch { /* none running */ }
+  try { fs.unlinkSync(path.join(dir, 'service.json')); } catch { /* gone */ }
+  return { uninstalled: true, removedKey, disabled, stoppedPid };
+}
+
+async function linuxStatus({ dir, systemdUserDir, execFileImpl, probeImpl, port }) {
+  const unit = unitPath(systemdUserDir);
+  const installed = fs.existsSync(unit); // the unit file IS the persistent registration
+  let enabled = false, active = false, mainPid = null;
+  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT]); enabled = /enabled/.test(stdout); } catch { /* not enabled / no bus */ }
+  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]); active = /^active/m.test(stdout.trim()); } catch { /* inactive */ }
+  try { const { stdout } = await execFileImpl('systemctl', ['--user', 'show', SYSTEMD_UNIT, '-p', 'MainPID', '--value']); mainPid = Number(String(stdout).trim()) || null; } catch { /* none */ }
+  let { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
+  if (mainPid) { supervisorPid = mainPid; supervisorAlive = true; }
+  else if (active) { supervisorAlive = true; }
+  const serverUp = await probeImpl(port);
+  return { installed, runValue: installed ? unit : null, supervisorPid, supervisorAlive, serverUp, enabled, active };
+}
+
+// --- public API (platform dispatch) ----------------------------------------
+
+const unsupported = (platform, key) => ({
+  [key]: false,
+  supported: false,
+  platform,
+  message: `always-on autostart for ${platform} is not implemented yet — run \`wild-workspace\` to start manually (see docs/always-on-design.md)`,
+});
+
+export async function installService(opts = {}, deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === 'win32') {
+    return winInstall(opts, { dir: deps.dir || globalDir(), execFileImpl: deps.execFileImpl || execFileP });
+  }
+  if (platform === 'darwin') {
+    return macInstall(opts, {
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+    });
+  }
+  if (platform === 'linux') {
+    return linuxInstall(opts, {
+      dir: deps.dir || globalDir(),
+      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+    });
+  }
+  return unsupported(platform, 'installed');
+}
+
+export async function uninstallService(deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === 'win32') {
+    return winUninstall({
+      dir: deps.dir || globalDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
+    });
+  }
+  if (platform === 'darwin') {
+    return macUninstall({
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
+      uid: deps.uid ?? currentUid(),
+    });
+  }
+  if (platform === 'linux') {
+    return linuxUninstall({
+      dir: deps.dir || globalDir(),
+      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
+    });
+  }
+  return unsupported(platform, 'uninstalled');
+}
+
+export async function serviceStatus(opts = {}, deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === 'win32') {
+    return winStatus({
+      dir: deps.dir || globalDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      probeImpl: deps.probeImpl || (async () => false),
+      port: opts.port || 5173,
+    });
+  }
+  if (platform === 'darwin') {
+    return macStatus({
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      probeImpl: deps.probeImpl || (async () => false),
+      uid: deps.uid ?? currentUid(),
+      port: opts.port || 5173,
+    });
+  }
+  if (platform === 'linux') {
+    return linuxStatus({
+      dir: deps.dir || globalDir(),
+      systemdUserDir: deps.systemdUserDir || defaultSystemdUserDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      probeImpl: deps.probeImpl || (async () => false),
+      port: opts.port || 5173,
+    });
+  }
+  return { supported: false, platform };
+}