@venturewild/workspace 0.3.5 → 0.3.7

package/server/src/supervisor.mjs

@@ -1,647 +1,647 @@
-// WorkspaceSupervisor — keeps the wild-workspace server alive in the background.
-//
-// The server itself auto-starts the bmo-sync daemon on boot (DaemonSupervisor),
-// so keeping the server up brings the whole local stack — public URL included —
-// back to life. This is the watchdog half of the always-on feature
-// (docs/always-on-design.md); `service.mjs` is the per-OS autostart half that
-// launches this hidden at login via `wild-workspace service run`.
-//
-// Design (all proven on Windows incl. a real reboot, 2026-05-30):
-//  - Health-driven: polls GET /api/health and (re)spawns the server only when
-//    it is down — so it never fights a server someone else started and handles
-//    crash recovery naturally.
-//  - Singleton: an exclusive lockfile in the machine-global dir
-//    (~/.wild-workspace, NEVER the synced workspace — locked principle #1).
-//    A stale lock whose pid is dead is taken over.
-//  - Exponential backoff (capped) so a crash-looping server can't spin the CPU.
-//  - Everything is logged — silent death is the #1 un-debuggable failure mode.
-//
-// Every external touch-point (spawn, health probe, clock) is an injected seam
-// so the suite never spawns a real process.
-
-import { spawn } from 'node:child_process';
-import http from 'node:http';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { resolveDaemonVersion } from './daemon-bin.mjs';
-import { restartSelf } from './service.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_SERVER_ENTRY = path.join(__dirname, 'index.mjs');
-
-/** Resolve true iff the local server answers /api/health. Never throws. */
-export function probeHealth(port, timeoutMs = 2500) {
-  return new Promise((resolve) => {
-    const req = http.get(
-      { host: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs },
-      (res) => { res.resume(); resolve(res.statusCode > 0); },
-    );
-    req.on('error', () => resolve(false));
-    req.on('timeout', () => { req.destroy(); resolve(false); });
-  });
-}
-
-/**
- * Ask the running server its version via /api/health. Returns the version string
- * or null (server down / no version field / parse error). Never throws. Used by
- * the version-drift check (RC1) — a stale server keeps running its OLD code after
- * an upgrade, so we compare what's RUNNING to what's INSTALLED on disk.
- */
-export function probeHealthVersion(port, timeoutMs = 2500) {
-  return new Promise((resolve) => {
-    const req = http.get(
-      { host: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs },
-      (res) => {
-        let body = '';
-        res.on('data', (d) => { body += d; if (body.length > 4096) req.destroy(); });
-        res.on('end', () => {
-          try { resolve(JSON.parse(body).version || null); } catch { resolve(null); }
-        });
-      },
-    );
-    req.on('error', () => resolve(null));
-    req.on('timeout', () => { req.destroy(); resolve(null); });
-  });
-}
-
-/**
- * The version installed on disk RIGHT NOW — read fresh from the package.json that
- * ships next to this file, NOT the in-memory APP_VERSION constant. The supervisor
- * is long-lived: after `npm i -g` (or the operator `reinstall-daemon`) swaps the
- * package, the supervisor's own constant is stale too, so only a fresh disk read
- * sees the new version. Respawning the server child reloads index.mjs from this
- * same path, so the restart actually picks up the new code. Returns null on error.
- */
-export function installedVersion(entry = DEFAULT_SERVER_ENTRY) {
-  try {
-    // index.mjs lives at <pkg>/server/src/index.mjs → package.json is ../../.
-    const pkg = path.resolve(path.dirname(entry), '..', '..', 'package.json');
-    return JSON.parse(fs.readFileSync(pkg, 'utf8')).version || null;
-  } catch {
-    return null;
-  }
-}
-
-// Captured ONCE at module load = the version of the code THIS supervisor process
-// is running. A fresh installedVersion() reads disk, which moves ahead after an
-// in-place `npm i -g`; the difference is the supervisor's OWN staleness (the
-// Part-8 gap). Distinct from APP_VERSION only in that we read the same file the
-// drift check reads, so they're guaranteed equal at startup (no false drift).
-export const SUPERVISOR_VERSION = installedVersion();
-
-export class WorkspaceSupervisor {
-  constructor({
-    serverEntry = DEFAULT_SERVER_ENTRY,
-    workspaceDir = process.cwd(),
-    port = Number(process.env.WILD_WORKSPACE_PORT || 5173),
-    globalDir = path.join(os.homedir(), '.wild-workspace'),
-    node = process.execPath,
-    pollMs = 3000,
-    backoffStartMs = 1000,
-    backoffMaxMs = 30000,
-    probeTimeoutMs = 2500,
-    spawnImpl = spawn,
-    probeImpl = probeHealth,
-    nowImpl = () => Date.now(),
-    env = process.env,
-    crashLoopThreshold = 3,
-    diagnosticsImpl = null,
-    // RC1 version-drift auto-restart: when the RUNNING server reports an older
-    // version than what's INSTALLED on disk, restart it so it picks up the new
-    // code. On by default; seams injected for tests. WILD_WORKSPACE_NO_AUTORESTART=1
-    // disables it (e.g. a developer running an intentionally-older server).
-    autoRestartOnVersionDrift = env.WILD_WORKSPACE_NO_AUTORESTART !== '1',
-    versionImpl = probeHealthVersion,
-    installedVersionImpl = () => installedVersion(serverEntry),
-    // Phase 2 auto-update (Pillar B): the always-on supervisor self-updates the
-    // whole stack on the user's channel, with health-gated rollback. On by
-    // default; the env kill switch + the persisted off switch both disable it.
-    // Only wired up in start() (not in the unit-test path, which calls tick()
-    // directly) — see start(). updatePollMs is the *wake* cadence; the actual
-    // check interval lives inside AutoUpdater (6h) and self-rate-limits.
-    autoUpdate = env.WILD_WORKSPACE_NO_AUTOUPDATE !== '1',
-    updatePollMs = 60 * 60 * 1000, // wake hourly; AutoUpdater gates real checks
-    autoUpdaterFactory = null, //     test seam: (supervisor) => AutoUpdater-like
-    // Phase 3 (Pillar A prerequisite): the always-on supervisor keeps the bmo-sync
-    // DAEMON alive too, independent of the workspace server. The daemon hosts the
-    // out-of-band support channel (reachable when :5173 is down), so it must not
-    // depend on the server being up. The server still ensureRunning()s the daemon
-    // at boot (idempotent); this is the keep-alive owner. On by default; kill switch
-    // WILD_WORKSPACE_NO_DAEMON_SUPERVISION=1. Only wired in start() (not the unit
-    // -test path, which calls daemonTick() directly with an injected factory).
-    superviseDaemon = env.WILD_WORKSPACE_NO_DAEMON_SUPERVISION !== '1',
-    daemonPollMs = 10000, //          probe the daemon every 10s
-    daemonSupervisorFactory = null, // test seam: (supervisor) => DaemonSupervisor-like
-    // Daemon version-drift restart (the daemon analog of RC1b): after an
-    // auto-update installs a new daemon binary, the long-lived daemon process
-    // keeps running the OLD code until something restarts it — so the support
-    // channel silently won't activate. We recycle the daemon when the installed
-    // subpackage version differs from the version the running daemon was spawned
-    // under (tracked in `daemon-runtime.json`, since the daemon's /health reports
-    // no version). Test seam: inject a version function.
-    daemonVersionImpl = () => resolveDaemonVersion({ env }),
-    // Supervisor self-restart after auto-update (the Part-8 stale-process fix):
-    // once an update installs new code and the server child restarts + verifies
-    // healthy, the supervisor must restart ITSELF so its own new code (e.g. the
-    // daemon-drift recycle) loads — RC1b only restarts the child. Per-OS re-exec
-    // lives in service.mjs::restartSelf. On by default; kill switch
-    // WILD_WORKSPACE_NO_SELF_RESTART=1. A cooldown + a once-per-process guard
-    // prevent any restart loop; the delay lets the triggering update tick unwind
-    // and logs flush first. All seams injected (no real exit/spawn in tests).
-    selfRestart = env.WILD_WORKSPACE_NO_SELF_RESTART !== '1',
-    selfRestartCooldownMs = 10 * 60 * 1000,
-    selfRestartDelayMs = 3000,
-    restartSelfImpl = restartSelf,
-    exitImpl = (code = 0) => process.exit(code),
-    scheduleImpl = (fn, ms) => { const t = setTimeout(fn, ms); if (t.unref) t.unref(); return t; },
-    // The version THIS supervisor process is running (captured at module load).
-    // The self-drift backstop self-restarts when the installed-on-disk version
-    // moves ahead of this — covering EVERY update path (our auto-updater, the
-    // operator `update-now`, the CLI `update apply`, a manual `npm i -g`), not
-    // just our own. null disables the backstop (tests default to null).
-    selfVersion = SUPERVISOR_VERSION,
-  } = {}) {
-    Object.assign(this, {
-      serverEntry, workspaceDir, port, globalDir, node, pollMs,
-      backoffStartMs, backoffMaxMs, probeTimeoutMs, spawnImpl, probeImpl, nowImpl, env,
-      crashLoopThreshold, diagnosticsImpl,
-      autoRestartOnVersionDrift, versionImpl, installedVersionImpl,
-      autoUpdate, updatePollMs, autoUpdaterFactory,
-      superviseDaemon, daemonPollMs, daemonSupervisorFactory, daemonVersionImpl,
-      selfRestart, selfRestartCooldownMs, selfRestartDelayMs, restartSelfImpl, exitImpl, scheduleImpl,
-      selfVersion,
-    });
-    this.autoUpdater = null;
-    this.updateTimer = null;
-    this.daemonSupervisor = null;
-    this.daemonTimer = null;
-    this._daemonTicking = false;
-    this.daemonRuntimeFile = path.join(globalDir, 'daemon-runtime.json');
-    // Persists the last self-restart time so a fresh post-re-exec supervisor
-    // honours the cooldown too (belt-and-suspenders against a restart loop).
-    this.selfRestartFile = path.join(globalDir, 'self-restart.json');
-    this._selfRestartScheduled = false;
-    this.logFile = path.join(globalDir, 'supervisor.log');
-    this.serverLogFile = path.join(globalDir, 'server.out.log');
-    this.lockFile = path.join(globalDir, 'supervisor.lock');
-    // Phase 3.2: the bmo-sync daemon drops this file (a consented support
-    // `restart-server` action) for us to action — so a restart can be triggered
-    // out-of-band even when :5173 is wedged. We kill the child; the next tick
-    // respawns it from disk (new code loads). Safe: absent file = no-op.
-    this.restartRequestFile = path.join(globalDir, 'restart-request.json');
-    this.child = null;
-    this.backoff = backoffStartMs;
-    this.lastSpawn = 0;
-    this.timer = null;
-    this.spawnCount = 0; //        consecutive spawns without becoming healthy
-    this.pushedThisEpisode = false; // crash-loop diagnostics pushed once per episode
-  }
-
-  log(msg) {
-    try { fs.appendFileSync(this.logFile, `[${new Date().toISOString()}] ${msg}\n`); } catch { /* best-effort */ }
-  }
-
-  /** Is a pid alive? EPERM means "exists, not ours" → still alive. */
-  pidAlive(pid) {
-    try { process.kill(pid, 0); return true; } catch (e) { return !!(e && e.code === 'EPERM'); }
-  }
-
-  /** Exclusive lock; take over ONLY a stale lock (recorded pid no longer alive). */
-  acquireLock() {
-    try { fs.mkdirSync(this.globalDir, { recursive: true }); } catch { /* surfaced below */ }
-    try {
-      const fd = fs.openSync(this.lockFile, 'wx');
-      fs.writeSync(fd, String(process.pid));
-      fs.closeSync(fd);
-      return true;
-    } catch {
-      let old = null;
-      try { old = Number(fs.readFileSync(this.lockFile, 'utf8').trim()); } catch { /* unreadable */ }
-      if (old && this.pidAlive(old)) {
-        this.log(`live supervisor pid=${old} already running; exiting`);
-        return false;
-      }
-      try { fs.writeFileSync(this.lockFile, String(process.pid)); this.log('took over stale lock'); return true; }
-      catch { return false; }
-    }
-  }
-
-  releaseLock() {
-    try {
-      if (Number(fs.readFileSync(this.lockFile, 'utf8').trim()) === process.pid) fs.unlinkSync(this.lockFile);
-    } catch { /* already gone */ }
-  }
-
-  spawnServer() {
-    let out = 'ignore';
-    try { out = fs.openSync(this.serverLogFile, 'a'); } catch { /* output discarded */ }
-    this.child = this.spawnImpl(this.node, [this.serverEntry], {
-      cwd: this.workspaceDir,
-      windowsHide: true,
-      stdio: ['ignore', out, out],
-      env: { ...this.env, WILD_WORKSPACE_NO_OPEN: '1', WILD_WORKSPACE_DIR: this.workspaceDir },
-    });
-    if (typeof out === 'number') { try { fs.closeSync(out); } catch { /* parent fd */ } }
-    this.lastSpawn = this.nowImpl();
-    const pid = this.child && this.child.pid;
-    this.log(`spawned server pid=${pid} (backoff=${this.backoff}ms)`);
-    if (this.child && this.child.on) {
-      this.child.on('exit', (code, sig) => { this.log(`server pid=${pid} exited code=${code} sig=${sig}`); this.child = null; });
-    }
-    return this.child;
-  }
-
-  /**
-   * Consume a pending support `restart-server` request (Phase 3.2). Returns true
-   * iff a request file was present (and removes it). Reading-then-deleting makes
-   * "present" mean "unhandled" — idempotent across ticks.
-   */
-  consumeRestartRequest() {
-    try {
-      fs.readFileSync(this.restartRequestFile); // throws if absent
-    } catch {
-      return false;
-    }
-    try { fs.unlinkSync(this.restartRequestFile); } catch { /* best-effort */ }
-    return true;
-  }
-
-  /** One supervision step. Returns its decision (exposed for tests). */
-  async tick() {
-    // Phase 3.2: a consented support restart request takes priority — kill the
-    // child so the next tick respawns it from disk (picks up any new code).
-    if (this.consumeRestartRequest()) {
-      this.log('restart-server requested (support channel) — restarting');
-      this.restartChild();
-      return 'restart-requested';
-    }
-    // Part-8 backstop: if disk moved ahead of our own code (any update path),
-    // schedule a supervisor self-restart. Side-effect only — never changes the
-    // tick decision below (server/daemon healing proceeds as usual meanwhile).
-    this.maybeSelfRestartOnDrift();
-    if (await this.probeImpl(this.port, this.probeTimeoutMs)) {
-      this.backoff = this.backoffStartMs; // healthy → reset backoff
-      this.spawnCount = 0; //              healthy → not a crash loop
-      this.pushedThisEpisode = false;
-      // RC1 version drift: a healthy-but-STALE server (running older code than
-      // what's installed) should be restarted so the upgrade actually lands.
-      // Only when WE own the child — we restart by killing it and letting the
-      // next tick respawn (which reloads index.mjs from disk). A server started
-      // by someone else (foreground `wild-workspace`) we leave alone; we have no
-      // handle on it. The restarted server reports the installed version, so the
-      // drift clears and this won't loop.
-      if (this.autoRestartOnVersionDrift && this.child) {
-        try {
-          const running = await this.versionImpl(this.port, this.probeTimeoutMs);
-          const installed = this.installedVersionImpl();
-          if (running && installed && running !== installed) {
-            this.log(`version drift: running=${running} installed=${installed} — restarting server`);
-            try { this.child.kill(); } catch { /* exit handler clears child */ }
-            this.child = null;
-            this.backoff = this.backoffStartMs; // upgrade is intentional, not a crash
-            return 'version-drift-restart';
-          }
-        } catch (e) {
-          this.log(`version-drift check error: ${e?.message || e}`);
-        }
-      }
-      return 'healthy';
-    }
-    if (this.child) return 'booting';                                  // spawned, still coming up
-    if (this.nowImpl() - this.lastSpawn < this.backoff) return 'backoff';
-    this.spawnServer();
-    this.backoff = Math.min(this.backoff * 2, this.backoffMaxMs);
-    this.spawnCount += 1;
-    // Crash loop: the server won't stay up, so the operator channel (which rides
-    // the :5173 server) can't reach this machine at all. Push an install-down
-    // `doctor` bundle to bmo-sync ONCE per episode so support sees it anyway —
-    // the install-failed-before-server-up case (docs/user-experience.md §5).
-    if (this.spawnCount >= this.crashLoopThreshold && !this.pushedThisEpisode) {
-      this.pushedThisEpisode = true;
-      Promise.resolve(this.pushDiagnostics()).catch((e) => this.log(`diag push error: ${e?.message || e}`));
-    }
-    return 'spawned';
-  }
-
-  /**
-   * Push an install-down diagnostic bundle to bmo-sync. Injected (`diagnosticsImpl`)
-   * in tests; the real path is consent- + token-gated and never runs under the
-   * test runner. Best-effort, never throws into the supervision loop.
-   */
-  async pushDiagnostics() {
-    if (this.diagnosticsImpl) return this.diagnosticsImpl(this);
-    if (process.env.VITEST || process.env.NODE_ENV === 'test') return;
-    try {
-      const [{ buildConfig }, { runDoctor }, { loadObservabilityConsent }] = await Promise.all([
-        import('./config.mjs'),
-        import('./doctor.mjs'),
-        import('./observability.mjs'),
-      ]);
-      const config = buildConfig({ workspaceDir: this.workspaceDir, port: this.port });
-      if (!config.accountToken) return; //                        can't key it to a user
-      if (process.env.WILD_WORKSPACE_NO_TELEMETRY === '1') return; // kill switch
-      if (!loadObservabilityConsent(config.dataDir).enabled) return; // consent
-      const report = await runDoctor({ config });
-      const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
-      const ctrl = new AbortController();
-      const t = setTimeout(() => ctrl.abort(), 5000);
-      try {
-        await fetch(url, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({
-            account_token: config.accountToken,
-            slug: config.account?.slug || null,
-            workspace_id: config.workspaceId,
-            kind: 'install-down',
-            doctor: report,
-            sent_at: Math.floor(Date.now() / 1000),
-          }),
-          signal: ctrl.signal,
-        });
-        this.log(`pushed install-down diagnostics (fail=${report.summary?.fail})`);
-      } finally {
-        clearTimeout(t);
-      }
-    } catch (e) {
-      this.log(`diagnostics push failed: ${e?.message || e}`);
-    }
-  }
-
-  /**
-   * Restart the supervised server child so freshly installed code is loaded.
-   * Kills it and lets the next tick respawn (which reloads index.mjs from disk) —
-   * the same mechanism as the version-drift restart, exposed for the AutoUpdater.
-   * No-op (returns false) when we don't own a child (foreground server).
-   */
-  restartChild() {
-    if (!this.child) return false;
-    this.log('restartChild: killing server to load new code');
-    try { this.child.kill(); } catch { /* exit handler clears child */ }
-    this.child = null;
-    this.backoff = this.backoffStartMs; // an intentional restart, not a crash
-    return true;
-  }
-
-  /** The last self-restart time (epoch ms), or 0. Used for the loop-guard cooldown. */
-  readLastSelfRestart() {
-    try { return Number(JSON.parse(fs.readFileSync(this.selfRestartFile, 'utf8')).at) || 0; }
-    catch { return 0; }
-  }
-
-  writeLastSelfRestart(at) {
-    try {
-      fs.mkdirSync(this.globalDir, { recursive: true });
-      fs.writeFileSync(this.selfRestartFile, JSON.stringify({ at }));
-    } catch { /* best-effort */ }
-  }
-
-  /**
-   * Schedule a supervisor self-restart so freshly-installed SUPERVISOR code loads
-   * (the Part-8 stale-process fix). Called from the AutoUpdater's onUpdate hook
-   * AFTER an update installed + restarted the server child + verified it healthy —
-   * so a bad release has already rolled back before we re-exec ourselves. Guarded
-   * three ways against a restart loop: the kill switch, a once-per-process flag,
-   * and a persisted cooldown (survives the re-exec). Returns a status string
-   * ('scheduled' | 'disabled' | 'already' | 'cooldown') for tests/logging. The
-   * actual restart runs on a short delay so the triggering tick unwinds first.
-   */
-  scheduleSelfRestart(reason) {
-    if (!this.selfRestart) return 'disabled';
-    if (this._selfRestartScheduled) return 'already';
-    const now = this.nowImpl();
-    const last = this.readLastSelfRestart();
-    if (last && now - last < this.selfRestartCooldownMs) {
-      this.log(`self-restart skipped (cooldown, last ${Math.round((now - last) / 1000)}s ago) — ${reason}`);
-      return 'cooldown';
-    }
-    this._selfRestartScheduled = true;
-    this.writeLastSelfRestart(now);
-    this.log(`self-restart scheduled in ${this.selfRestartDelayMs}ms — ${reason}`);
-    this.scheduleImpl(() => {
-      this._performSelfRestart(reason).catch((e) => this.log(`self-restart error: ${e?.message || e}`));
-    }, this.selfRestartDelayMs);
-    return 'scheduled';
-  }
-
-  /**
-   * Carry out the self-restart. On mac/Linux the service manager kills+relaunches
-   * us (we just issue the command and get SIGTERM'd → our exit handler releases the
-   * lock). On Windows restartSelf spawned a hidden successor and returns
-   * willExit:true — we then release the lock (via stop()) and exit so the successor
-   * can take it. A non-managed run reports restarted:false and we stay up on the
-   * old code (no worse than before this feature). Never throws.
-   */
-  async _performSelfRestart(reason) {
-    this.log(`self-restart now — ${reason}`);
-    let r;
-    try {
-      r = await this.restartSelfImpl({ dir: this.globalDir, port: this.port });
-    } catch (e) {
-      this.log(`self-restart impl error: ${e?.message || e}`);
-      return { restarted: false, error: e?.message || String(e) };
-    }
-    this.log(`self-restart result: ${JSON.stringify(r)}`);
-    if (r && r.willExit) {
-      this.stop(); // clears timers + releases the lock so the successor can take it
-      this.exitImpl(0);
-    }
-    return r;
-  }
-
-  /**
-   * Backstop for the Part-8 gap on EVERY update path, not just our own auto-
-   * updater: when the version installed on disk no longer matches the code THIS
-   * supervisor is running, the supervisor is stale → schedule a self-restart.
-   * RC1b already restarts the stale server child and daemonTick recycles the
-   * stale daemon; this is the missing third leg (the supervisor itself), so an
-   * operator `update-now` / CLI `update apply` / manual `npm i -g` also lands new
-   * supervisor code with no reboot. Skipped while OUR auto-updater is mid-flight
-   * so the rollback window is respected (that path self-restarts via the onUpdate
-   * hook, only after verify succeeds). Cheap (an in-memory compare guarding a disk
-   * read) and idempotent (scheduleSelfRestart de-dupes). Never throws.
-   */
-  maybeSelfRestartOnDrift() {
-    if (!this.selfRestart || !this.selfVersion) return false;
-    if (this._selfRestartScheduled) return false;
-    if (this.autoUpdater && this.autoUpdater.inProgress) return false; // respect rollback window
-    let installed = null;
-    try { installed = this.installedVersionImpl(); } catch { return false; }
-    if (!installed || installed === this.selfVersion) return false;
-    this.log(`supervisor version drift: running=${this.selfVersion} installed=${installed} — self-restarting`);
-    this.scheduleSelfRestart(`supervisor drift ${this.selfVersion}→${installed}`);
-    return true;
-  }
-
-  /** Build the AutoUpdater bound to this supervisor. Separated for the test seam. */
-  async buildAutoUpdater() {
-    if (this.autoUpdaterFactory) return this.autoUpdaterFactory(this);
-    // Lazy import keeps the unit-test path (which never calls start()) free of the
-    // auto-update module + its registry/npm seams.
-    const { AutoUpdater } = await import('./auto-update.mjs');
-    return new AutoUpdater({
-      globalDir: this.globalDir,
-      port: this.port,
-      installedVersionImpl: this.installedVersionImpl,
-      healthVersionImpl: (port) => this.versionImpl(port, this.probeTimeoutMs),
-      restartImpl: async () => { this.restartChild(); },
-      nowImpl: this.nowImpl,
-      env: this.env,
-      logImpl: (m) => this.log(m),
-      onUpdate: (rec) => {
-        this.log(`auto-update result: ${rec.from || '?'}→${rec.to} ${rec.status}`);
-        // A genuine version change landed healthy → restart the supervisor itself
-        // so its own new code loads (Part-8 stale-process fix). Guarded against
-        // loops inside scheduleSelfRestart. Fires only on a real bump (to≠from),
-        // never on rollback/failure (those statuses aren't 'ok').
-        if (rec.status === 'ok' && rec.to && rec.from && rec.to !== rec.from) {
-          this.scheduleSelfRestart(`auto-update ${rec.from}→${rec.to}`);
-        }
-      },
-    });
-  }
-
-  runUpdateTick(opts = {}) {
-    if (!this.autoUpdater) return;
-    this.autoUpdater.tick(opts)
-      .then((r) => { if (r && !['not-due', 'disabled', 'up-to-date', 'busy'].includes(r)) this.log(`auto-update tick: ${r}`); })
-      .catch((e) => this.log(`auto-update error: ${e?.message || e}`));
-  }
-
-  /**
-   * Build the DaemonSupervisor the always-on layer owns. Reads a FRESH config
-   * (not the stale module constant) so the account token / relay in effect when
-   * always-on starts are used. Lazy import keeps the unit-test path (which never
-   * calls start()) free of config + daemon-supervisor. Test seam: factory.
-   */
-  async buildDaemonSupervisor() {
-    if (this.daemonSupervisorFactory) return this.daemonSupervisorFactory(this);
-    const [{ buildConfig }, { DaemonSupervisor }] = await Promise.all([
-      import('./config.mjs'),
-      import('./daemon-supervisor.mjs'),
-    ]);
-    const config = buildConfig({ workspaceDir: this.workspaceDir, port: this.port });
-    return new DaemonSupervisor({
-      httpBase: config.daemonHttpUrl,
-      globalDir: this.globalDir,
-      accountToken: config.accountToken,
-      serverUrl: config.bmoSyncServerUrl,
-    });
-  }
-
-  /**
-   * One daemon-supervision step: if the daemon isn't answering /health, (re)start
-   * it. Deliberately INDEPENDENT of server health — the daemon (and its support
-   * channel) must stay up even when the server is crashed/mid-upgrade. Re-entrancy
-   * guarded so a slow spawn can't overlap the next tick. Never throws.
-   */
-  /** The daemon version the currently-running daemon was spawned under, or null. */
-  readDaemonMarker() {
-    try {
-      const v = JSON.parse(fs.readFileSync(this.daemonRuntimeFile, 'utf8'))?.daemonVersion;
-      return typeof v === 'string' ? v : null;
-    } catch {
-      return null;
-    }
-  }
-
-  writeDaemonMarker(version) {
-    if (!version) return; // unknown installed version (PATH/vendor) — don't pin
-    try {
-      fs.mkdirSync(this.globalDir, { recursive: true });
-      fs.writeFileSync(this.daemonRuntimeFile, JSON.stringify({ daemonVersion: version }));
-    } catch {
-      /* best-effort */
-    }
-  }
-
-  async daemonTick() {
-    if (!this.daemonSupervisor || this._daemonTicking) return 'skip';
-    this._daemonTicking = true;
-    try {
-      const installed = this.daemonVersionImpl();
-      const h = await this.daemonSupervisor.health();
-      if (h && h.running) {
-        // Running — but is it the CURRENT binary? After an auto-update the daemon
-        // keeps the old code until recycled (RC1b analog). Recycle when the
-        // installed version differs from what we recorded at spawn (a null marker
-        // = spawned by a pre-drift-aware supervisor → treat as drift, recycle once).
-        if (installed && this.readDaemonMarker() !== installed && this.daemonSupervisor.recycle) {
-          this.log(
-            `daemon version drift (marker=${this.readDaemonMarker() || 'none'} installed=${installed}) — recycling`,
-          );
-          const r = await this.daemonSupervisor.recycle();
-          if (r && r.started) {
-            this.writeDaemonMarker(installed);
-            this.log(`daemon recycled to ${installed} (pid=${r.pid})`);
-            return 'recycled';
-          }
-          this.log(`daemon recycle failed: ${r?.error || 'unknown'}`);
-          return 'recycle-failed';
-        }
-        return 'healthy';
-      }
-      const r = await this.daemonSupervisor.ensureRunning();
-      if (r && r.started) {
-        this.writeDaemonMarker(installed);
-        this.log(`daemon respawned (pid=${r.pid})`);
-        return 'respawned';
-      }
-      if (r && r.alreadyRunning) return 'healthy';
-      this.log(`daemon down, respawn not started: ${r?.error || 'unknown'}`);
-      return 'failed';
-    } catch (e) {
-      this.log(`daemon-tick error: ${e?.message || e}`);
-      return 'error';
-    } finally {
-      this._daemonTicking = false;
-    }
-  }
-
-  /** Acquire the lock and start the supervision loop. Idempotent across processes. */
-  start() {
-    if (!this.acquireLock()) return { started: false, reason: 'already-running' };
-    process.on('exit', () => this.releaseLock());
-    process.on('SIGTERM', () => process.exit(0));
-    process.on('SIGINT', () => process.exit(0));
-    this.log(`supervisor start pid=${process.pid} v${this.selfVersion || '?'} watching http://127.0.0.1:${this.port}/api/health (workspace=${this.workspaceDir})`);
-    this.timer = setInterval(() => { this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`)); }, this.pollMs);
-    this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`));
-
-    // Phase 2 auto-update: wake on a slow timer; the first check fires shortly
-    // after start so the server has time to come up (verify reads its /health).
-    if (this.autoUpdate && this.env.VITEST !== 'true' && this.env.NODE_ENV !== 'test') {
-      this.buildAutoUpdater().then((u) => {
-        this.autoUpdater = u;
-        this.updateTimer = setInterval(() => this.runUpdateTick(), this.updatePollMs);
-        if (this.updateTimer.unref) this.updateTimer.unref();
-        // FORCE the first post-boot check (bypass the 6h dueForCheck): a restart
-        // should always pull the latest, so a rebooted/woken machine can't sit on
-        // a stale version just because it last checked <6h ago.
-        const kick = setTimeout(() => this.runUpdateTick({ force: true }), 60_000);
-        if (kick.unref) kick.unref();
-      }).catch((e) => this.log(`auto-update init error: ${e?.message || e}`));
-    }
-
-    // Phase 3: keep the bmo-sync daemon alive independent of the server, so the
-    // out-of-band support channel survives the server being down.
-    if (this.superviseDaemon && this.env.VITEST !== 'true' && this.env.NODE_ENV !== 'test') {
-      this.buildDaemonSupervisor().then((d) => {
-        this.daemonSupervisor = d;
-        this.daemonTimer = setInterval(() => { this.daemonTick().catch((e) => this.log(`daemon-tick error: ${e?.message || e}`)); }, this.daemonPollMs);
-        if (this.daemonTimer.unref) this.daemonTimer.unref();
-        this.daemonTick().catch(() => {}); // first probe now
-      }).catch((e) => this.log(`daemon supervision init error: ${e?.message || e}`));
-    }
-    return { started: true };
-  }
-
-  stop() {
-    if (this.timer) { clearInterval(this.timer); this.timer = null; }
-    if (this.updateTimer) { clearInterval(this.updateTimer); this.updateTimer = null; }
-    if (this.daemonTimer) { clearInterval(this.daemonTimer); this.daemonTimer = null; }
-    this.releaseLock();
-  }
-}
+// WorkspaceSupervisor — keeps the wild-workspace server alive in the background.
+//
+// The server itself auto-starts the bmo-sync daemon on boot (DaemonSupervisor),
+// so keeping the server up brings the whole local stack — public URL included —
+// back to life. This is the watchdog half of the always-on feature
+// (docs/always-on-design.md); `service.mjs` is the per-OS autostart half that
+// launches this hidden at login via `wild-workspace service run`.
+//
+// Design (all proven on Windows incl. a real reboot, 2026-05-30):
+//  - Health-driven: polls GET /api/health and (re)spawns the server only when
+//    it is down — so it never fights a server someone else started and handles
+//    crash recovery naturally.
+//  - Singleton: an exclusive lockfile in the machine-global dir
+//    (~/.wild-workspace, NEVER the synced workspace — locked principle #1).
+//    A stale lock whose pid is dead is taken over.
+//  - Exponential backoff (capped) so a crash-looping server can't spin the CPU.
+//  - Everything is logged — silent death is the #1 un-debuggable failure mode.
+//
+// Every external touch-point (spawn, health probe, clock) is an injected seam
+// so the suite never spawns a real process.
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveDaemonVersion } from './daemon-bin.mjs';
+import { restartSelf } from './service.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SERVER_ENTRY = path.join(__dirname, 'index.mjs');
+
+/** Resolve true iff the local server answers /api/health. Never throws. */
+export function probeHealth(port, timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs },
+      (res) => { res.resume(); resolve(res.statusCode > 0); },
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+/**
+ * Ask the running server its version via /api/health. Returns the version string
+ * or null (server down / no version field / parse error). Never throws. Used by
+ * the version-drift check (RC1) — a stale server keeps running its OLD code after
+ * an upgrade, so we compare what's RUNNING to what's INSTALLED on disk.
+ */
+export function probeHealthVersion(port, timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs },
+      (res) => {
+        let body = '';
+        res.on('data', (d) => { body += d; if (body.length > 4096) req.destroy(); });
+        res.on('end', () => {
+          try { resolve(JSON.parse(body).version || null); } catch { resolve(null); }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * The version installed on disk RIGHT NOW — read fresh from the package.json that
+ * ships next to this file, NOT the in-memory APP_VERSION constant. The supervisor
+ * is long-lived: after `npm i -g` (or the operator `reinstall-daemon`) swaps the
+ * package, the supervisor's own constant is stale too, so only a fresh disk read
+ * sees the new version. Respawning the server child reloads index.mjs from this
+ * same path, so the restart actually picks up the new code. Returns null on error.
+ */
+export function installedVersion(entry = DEFAULT_SERVER_ENTRY) {
+  try {
+    // index.mjs lives at <pkg>/server/src/index.mjs → package.json is ../../.
+    const pkg = path.resolve(path.dirname(entry), '..', '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkg, 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+// Captured ONCE at module load = the version of the code THIS supervisor process
+// is running. A fresh installedVersion() reads disk, which moves ahead after an
+// in-place `npm i -g`; the difference is the supervisor's OWN staleness (the
+// Part-8 gap). Distinct from APP_VERSION only in that we read the same file the
+// drift check reads, so they're guaranteed equal at startup (no false drift).
+export const SUPERVISOR_VERSION = installedVersion();
+
+export class WorkspaceSupervisor {
+  constructor({
+    serverEntry = DEFAULT_SERVER_ENTRY,
+    workspaceDir = process.cwd(),
+    port = Number(process.env.WILD_WORKSPACE_PORT || 5173),
+    globalDir = path.join(os.homedir(), '.wild-workspace'),
+    node = process.execPath,
+    pollMs = 3000,
+    backoffStartMs = 1000,
+    backoffMaxMs = 30000,
+    probeTimeoutMs = 2500,
+    spawnImpl = spawn,
+    probeImpl = probeHealth,
+    nowImpl = () => Date.now(),
+    env = process.env,
+    crashLoopThreshold = 3,
+    diagnosticsImpl = null,
+    // RC1 version-drift auto-restart: when the RUNNING server reports an older
+    // version than what's INSTALLED on disk, restart it so it picks up the new
+    // code. On by default; seams injected for tests. WILD_WORKSPACE_NO_AUTORESTART=1
+    // disables it (e.g. a developer running an intentionally-older server).
+    autoRestartOnVersionDrift = env.WILD_WORKSPACE_NO_AUTORESTART !== '1',
+    versionImpl = probeHealthVersion,
+    installedVersionImpl = () => installedVersion(serverEntry),
+    // Phase 2 auto-update (Pillar B): the always-on supervisor self-updates the
+    // whole stack on the user's channel, with health-gated rollback. On by
+    // default; the env kill switch + the persisted off switch both disable it.
+    // Only wired up in start() (not in the unit-test path, which calls tick()
+    // directly) — see start(). updatePollMs is the *wake* cadence; the actual
+    // check interval lives inside AutoUpdater (6h) and self-rate-limits.
+    autoUpdate = env.WILD_WORKSPACE_NO_AUTOUPDATE !== '1',
+    updatePollMs = 60 * 60 * 1000, // wake hourly; AutoUpdater gates real checks
+    autoUpdaterFactory = null, //     test seam: (supervisor) => AutoUpdater-like
+    // Phase 3 (Pillar A prerequisite): the always-on supervisor keeps the bmo-sync
+    // DAEMON alive too, independent of the workspace server. The daemon hosts the
+    // out-of-band support channel (reachable when :5173 is down), so it must not
+    // depend on the server being up. The server still ensureRunning()s the daemon
+    // at boot (idempotent); this is the keep-alive owner. On by default; kill switch
+    // WILD_WORKSPACE_NO_DAEMON_SUPERVISION=1. Only wired in start() (not the unit
+    // -test path, which calls daemonTick() directly with an injected factory).
+    superviseDaemon = env.WILD_WORKSPACE_NO_DAEMON_SUPERVISION !== '1',
+    daemonPollMs = 10000, //          probe the daemon every 10s
+    daemonSupervisorFactory = null, // test seam: (supervisor) => DaemonSupervisor-like
+    // Daemon version-drift restart (the daemon analog of RC1b): after an
+    // auto-update installs a new daemon binary, the long-lived daemon process
+    // keeps running the OLD code until something restarts it — so the support
+    // channel silently won't activate. We recycle the daemon when the installed
+    // subpackage version differs from the version the running daemon was spawned
+    // under (tracked in `daemon-runtime.json`, since the daemon's /health reports
+    // no version). Test seam: inject a version function.
+    daemonVersionImpl = () => resolveDaemonVersion({ env }),
+    // Supervisor self-restart after auto-update (the Part-8 stale-process fix):
+    // once an update installs new code and the server child restarts + verifies
+    // healthy, the supervisor must restart ITSELF so its own new code (e.g. the
+    // daemon-drift recycle) loads — RC1b only restarts the child. Per-OS re-exec
+    // lives in service.mjs::restartSelf. On by default; kill switch
+    // WILD_WORKSPACE_NO_SELF_RESTART=1. A cooldown + a once-per-process guard
+    // prevent any restart loop; the delay lets the triggering update tick unwind
+    // and logs flush first. All seams injected (no real exit/spawn in tests).
+    selfRestart = env.WILD_WORKSPACE_NO_SELF_RESTART !== '1',
+    selfRestartCooldownMs = 10 * 60 * 1000,
+    selfRestartDelayMs = 3000,
+    restartSelfImpl = restartSelf,
+    exitImpl = (code = 0) => process.exit(code),
+    scheduleImpl = (fn, ms) => { const t = setTimeout(fn, ms); if (t.unref) t.unref(); return t; },
+    // The version THIS supervisor process is running (captured at module load).
+    // The self-drift backstop self-restarts when the installed-on-disk version
+    // moves ahead of this — covering EVERY update path (our auto-updater, the
+    // operator `update-now`, the CLI `update apply`, a manual `npm i -g`), not
+    // just our own. null disables the backstop (tests default to null).
+    selfVersion = SUPERVISOR_VERSION,
+  } = {}) {
+    Object.assign(this, {
+      serverEntry, workspaceDir, port, globalDir, node, pollMs,
+      backoffStartMs, backoffMaxMs, probeTimeoutMs, spawnImpl, probeImpl, nowImpl, env,
+      crashLoopThreshold, diagnosticsImpl,
+      autoRestartOnVersionDrift, versionImpl, installedVersionImpl,
+      autoUpdate, updatePollMs, autoUpdaterFactory,
+      superviseDaemon, daemonPollMs, daemonSupervisorFactory, daemonVersionImpl,
+      selfRestart, selfRestartCooldownMs, selfRestartDelayMs, restartSelfImpl, exitImpl, scheduleImpl,
+      selfVersion,
+    });
+    this.autoUpdater = null;
+    this.updateTimer = null;
+    this.daemonSupervisor = null;
+    this.daemonTimer = null;
+    this._daemonTicking = false;
+    this.daemonRuntimeFile = path.join(globalDir, 'daemon-runtime.json');
+    // Persists the last self-restart time so a fresh post-re-exec supervisor
+    // honours the cooldown too (belt-and-suspenders against a restart loop).
+    this.selfRestartFile = path.join(globalDir, 'self-restart.json');
+    this._selfRestartScheduled = false;
+    this.logFile = path.join(globalDir, 'supervisor.log');
+    this.serverLogFile = path.join(globalDir, 'server.out.log');
+    this.lockFile = path.join(globalDir, 'supervisor.lock');
+    // Phase 3.2: the bmo-sync daemon drops this file (a consented support
+    // `restart-server` action) for us to action — so a restart can be triggered
+    // out-of-band even when :5173 is wedged. We kill the child; the next tick
+    // respawns it from disk (new code loads). Safe: absent file = no-op.
+    this.restartRequestFile = path.join(globalDir, 'restart-request.json');
+    this.child = null;
+    this.backoff = backoffStartMs;
+    this.lastSpawn = 0;
+    this.timer = null;
+    this.spawnCount = 0; //        consecutive spawns without becoming healthy
+    this.pushedThisEpisode = false; // crash-loop diagnostics pushed once per episode
+  }
+
+  log(msg) {
+    try { fs.appendFileSync(this.logFile, `[${new Date().toISOString()}] ${msg}\n`); } catch { /* best-effort */ }
+  }
+
+  /** Is a pid alive? EPERM means "exists, not ours" → still alive. */
+  pidAlive(pid) {
+    try { process.kill(pid, 0); return true; } catch (e) { return !!(e && e.code === 'EPERM'); }
+  }
+
+  /** Exclusive lock; take over ONLY a stale lock (recorded pid no longer alive). */
+  acquireLock() {
+    try { fs.mkdirSync(this.globalDir, { recursive: true }); } catch { /* surfaced below */ }
+    try {
+      const fd = fs.openSync(this.lockFile, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      let old = null;
+      try { old = Number(fs.readFileSync(this.lockFile, 'utf8').trim()); } catch { /* unreadable */ }
+      if (old && this.pidAlive(old)) {
+        this.log(`live supervisor pid=${old} already running; exiting`);
+        return false;
+      }
+      try { fs.writeFileSync(this.lockFile, String(process.pid)); this.log('took over stale lock'); return true; }
+      catch { return false; }
+    }
+  }
+
+  releaseLock() {
+    try {
+      if (Number(fs.readFileSync(this.lockFile, 'utf8').trim()) === process.pid) fs.unlinkSync(this.lockFile);
+    } catch { /* already gone */ }
+  }
+
+  spawnServer() {
+    let out = 'ignore';
+    try { out = fs.openSync(this.serverLogFile, 'a'); } catch { /* output discarded */ }
+    this.child = this.spawnImpl(this.node, [this.serverEntry], {
+      cwd: this.workspaceDir,
+      windowsHide: true,
+      stdio: ['ignore', out, out],
+      env: { ...this.env, WILD_WORKSPACE_NO_OPEN: '1', WILD_WORKSPACE_DIR: this.workspaceDir },
+    });
+    if (typeof out === 'number') { try { fs.closeSync(out); } catch { /* parent fd */ } }
+    this.lastSpawn = this.nowImpl();
+    const pid = this.child && this.child.pid;
+    this.log(`spawned server pid=${pid} (backoff=${this.backoff}ms)`);
+    if (this.child && this.child.on) {
+      this.child.on('exit', (code, sig) => { this.log(`server pid=${pid} exited code=${code} sig=${sig}`); this.child = null; });
+    }
+    return this.child;
+  }
+
+  /**
+   * Consume a pending support `restart-server` request (Phase 3.2). Returns true
+   * iff a request file was present (and removes it). Reading-then-deleting makes
+   * "present" mean "unhandled" — idempotent across ticks.
+   */
+  consumeRestartRequest() {
+    try {
+      fs.readFileSync(this.restartRequestFile); // throws if absent
+    } catch {
+      return false;
+    }
+    try { fs.unlinkSync(this.restartRequestFile); } catch { /* best-effort */ }
+    return true;
+  }
+
+  /** One supervision step. Returns its decision (exposed for tests). */
+  async tick() {
+    // Phase 3.2: a consented support restart request takes priority — kill the
+    // child so the next tick respawns it from disk (picks up any new code).
+    if (this.consumeRestartRequest()) {
+      this.log('restart-server requested (support channel) — restarting');
+      this.restartChild();
+      return 'restart-requested';
+    }
+    // Part-8 backstop: if disk moved ahead of our own code (any update path),
+    // schedule a supervisor self-restart. Side-effect only — never changes the
+    // tick decision below (server/daemon healing proceeds as usual meanwhile).
+    this.maybeSelfRestartOnDrift();
+    if (await this.probeImpl(this.port, this.probeTimeoutMs)) {
+      this.backoff = this.backoffStartMs; // healthy → reset backoff
+      this.spawnCount = 0; //              healthy → not a crash loop
+      this.pushedThisEpisode = false;
+      // RC1 version drift: a healthy-but-STALE server (running older code than
+      // what's installed) should be restarted so the upgrade actually lands.
+      // Only when WE own the child — we restart by killing it and letting the
+      // next tick respawn (which reloads index.mjs from disk). A server started
+      // by someone else (foreground `wild-workspace`) we leave alone; we have no
+      // handle on it. The restarted server reports the installed version, so the
+      // drift clears and this won't loop.
+      if (this.autoRestartOnVersionDrift && this.child) {
+        try {
+          const running = await this.versionImpl(this.port, this.probeTimeoutMs);
+          const installed = this.installedVersionImpl();
+          if (running && installed && running !== installed) {
+            this.log(`version drift: running=${running} installed=${installed} — restarting server`);
+            try { this.child.kill(); } catch { /* exit handler clears child */ }
+            this.child = null;
+            this.backoff = this.backoffStartMs; // upgrade is intentional, not a crash
+            return 'version-drift-restart';
+          }
+        } catch (e) {
+          this.log(`version-drift check error: ${e?.message || e}`);
+        }
+      }
+      return 'healthy';
+    }
+    if (this.child) return 'booting';                                  // spawned, still coming up
+    if (this.nowImpl() - this.lastSpawn < this.backoff) return 'backoff';
+    this.spawnServer();
+    this.backoff = Math.min(this.backoff * 2, this.backoffMaxMs);
+    this.spawnCount += 1;
+    // Crash loop: the server won't stay up, so the operator channel (which rides
+    // the :5173 server) can't reach this machine at all. Push an install-down
+    // `doctor` bundle to bmo-sync ONCE per episode so support sees it anyway —
+    // the install-failed-before-server-up case (docs/user-experience.md §5).
+    if (this.spawnCount >= this.crashLoopThreshold && !this.pushedThisEpisode) {
+      this.pushedThisEpisode = true;
+      Promise.resolve(this.pushDiagnostics()).catch((e) => this.log(`diag push error: ${e?.message || e}`));
+    }
+    return 'spawned';
+  }
+
+  /**
+   * Push an install-down diagnostic bundle to bmo-sync. Injected (`diagnosticsImpl`)
+   * in tests; the real path is consent- + token-gated and never runs under the
+   * test runner. Best-effort, never throws into the supervision loop.
+   */
+  async pushDiagnostics() {
+    if (this.diagnosticsImpl) return this.diagnosticsImpl(this);
+    if (process.env.VITEST || process.env.NODE_ENV === 'test') return;
+    try {
+      const [{ buildConfig }, { runDoctor }, { loadObservabilityConsent }] = await Promise.all([
+        import('./config.mjs'),
+        import('./doctor.mjs'),
+        import('./observability.mjs'),
+      ]);
+      const config = buildConfig({ workspaceDir: this.workspaceDir, port: this.port });
+      if (!config.accountToken) return; //                        can't key it to a user
+      if (process.env.WILD_WORKSPACE_NO_TELEMETRY === '1') return; // kill switch
+      if (!loadObservabilityConsent(config.dataDir).enabled) return; // consent
+      const report = await runDoctor({ config });
+      const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 5000);
+      try {
+        await fetch(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            account_token: config.accountToken,
+            slug: config.account?.slug || null,
+            workspace_id: config.workspaceId,
+            kind: 'install-down',
+            doctor: report,
+            sent_at: Math.floor(Date.now() / 1000),
+          }),
+          signal: ctrl.signal,
+        });
+        this.log(`pushed install-down diagnostics (fail=${report.summary?.fail})`);
+      } finally {
+        clearTimeout(t);
+      }
+    } catch (e) {
+      this.log(`diagnostics push failed: ${e?.message || e}`);
+    }
+  }
+
+  /**
+   * Restart the supervised server child so freshly installed code is loaded.
+   * Kills it and lets the next tick respawn (which reloads index.mjs from disk) —
+   * the same mechanism as the version-drift restart, exposed for the AutoUpdater.
+   * No-op (returns false) when we don't own a child (foreground server).
+   */
+  restartChild() {
+    if (!this.child) return false;
+    this.log('restartChild: killing server to load new code');
+    try { this.child.kill(); } catch { /* exit handler clears child */ }
+    this.child = null;
+    this.backoff = this.backoffStartMs; // an intentional restart, not a crash
+    return true;
+  }
+
+  /** The last self-restart time (epoch ms), or 0. Used for the loop-guard cooldown. */
+  readLastSelfRestart() {
+    try { return Number(JSON.parse(fs.readFileSync(this.selfRestartFile, 'utf8')).at) || 0; }
+    catch { return 0; }
+  }
+
+  writeLastSelfRestart(at) {
+    try {
+      fs.mkdirSync(this.globalDir, { recursive: true });
+      fs.writeFileSync(this.selfRestartFile, JSON.stringify({ at }));
+    } catch { /* best-effort */ }
+  }
+
+  /**
+   * Schedule a supervisor self-restart so freshly-installed SUPERVISOR code loads
+   * (the Part-8 stale-process fix). Called from the AutoUpdater's onUpdate hook
+   * AFTER an update installed + restarted the server child + verified it healthy —
+   * so a bad release has already rolled back before we re-exec ourselves. Guarded
+   * three ways against a restart loop: the kill switch, a once-per-process flag,
+   * and a persisted cooldown (survives the re-exec). Returns a status string
+   * ('scheduled' | 'disabled' | 'already' | 'cooldown') for tests/logging. The
+   * actual restart runs on a short delay so the triggering tick unwinds first.
+   */
+  scheduleSelfRestart(reason) {
+    if (!this.selfRestart) return 'disabled';
+    if (this._selfRestartScheduled) return 'already';
+    const now = this.nowImpl();
+    const last = this.readLastSelfRestart();
+    if (last && now - last < this.selfRestartCooldownMs) {
+      this.log(`self-restart skipped (cooldown, last ${Math.round((now - last) / 1000)}s ago) — ${reason}`);
+      return 'cooldown';
+    }
+    this._selfRestartScheduled = true;
+    this.writeLastSelfRestart(now);
+    this.log(`self-restart scheduled in ${this.selfRestartDelayMs}ms — ${reason}`);
+    this.scheduleImpl(() => {
+      this._performSelfRestart(reason).catch((e) => this.log(`self-restart error: ${e?.message || e}`));
+    }, this.selfRestartDelayMs);
+    return 'scheduled';
+  }
+
+  /**
+   * Carry out the self-restart. On mac/Linux the service manager kills+relaunches
+   * us (we just issue the command and get SIGTERM'd → our exit handler releases the
+   * lock). On Windows restartSelf spawned a hidden successor and returns
+   * willExit:true — we then release the lock (via stop()) and exit so the successor
+   * can take it. A non-managed run reports restarted:false and we stay up on the
+   * old code (no worse than before this feature). Never throws.
+   */
+  async _performSelfRestart(reason) {
+    this.log(`self-restart now — ${reason}`);
+    let r;
+    try {
+      r = await this.restartSelfImpl({ dir: this.globalDir, port: this.port });
+    } catch (e) {
+      this.log(`self-restart impl error: ${e?.message || e}`);
+      return { restarted: false, error: e?.message || String(e) };
+    }
+    this.log(`self-restart result: ${JSON.stringify(r)}`);
+    if (r && r.willExit) {
+      this.stop(); // clears timers + releases the lock so the successor can take it
+      this.exitImpl(0);
+    }
+    return r;
+  }
+
+  /**
+   * Backstop for the Part-8 gap on EVERY update path, not just our own auto-
+   * updater: when the version installed on disk no longer matches the code THIS
+   * supervisor is running, the supervisor is stale → schedule a self-restart.
+   * RC1b already restarts the stale server child and daemonTick recycles the
+   * stale daemon; this is the missing third leg (the supervisor itself), so an
+   * operator `update-now` / CLI `update apply` / manual `npm i -g` also lands new
+   * supervisor code with no reboot. Skipped while OUR auto-updater is mid-flight
+   * so the rollback window is respected (that path self-restarts via the onUpdate
+   * hook, only after verify succeeds). Cheap (an in-memory compare guarding a disk
+   * read) and idempotent (scheduleSelfRestart de-dupes). Never throws.
+   */
+  maybeSelfRestartOnDrift() {
+    if (!this.selfRestart || !this.selfVersion) return false;
+    if (this._selfRestartScheduled) return false;
+    if (this.autoUpdater && this.autoUpdater.inProgress) return false; // respect rollback window
+    let installed = null;
+    try { installed = this.installedVersionImpl(); } catch { return false; }
+    if (!installed || installed === this.selfVersion) return false;
+    this.log(`supervisor version drift: running=${this.selfVersion} installed=${installed} — self-restarting`);
+    this.scheduleSelfRestart(`supervisor drift ${this.selfVersion}→${installed}`);
+    return true;
+  }
+
+  /** Build the AutoUpdater bound to this supervisor. Separated for the test seam. */
+  async buildAutoUpdater() {
+    if (this.autoUpdaterFactory) return this.autoUpdaterFactory(this);
+    // Lazy import keeps the unit-test path (which never calls start()) free of the
+    // auto-update module + its registry/npm seams.
+    const { AutoUpdater } = await import('./auto-update.mjs');
+    return new AutoUpdater({
+      globalDir: this.globalDir,
+      port: this.port,
+      installedVersionImpl: this.installedVersionImpl,
+      healthVersionImpl: (port) => this.versionImpl(port, this.probeTimeoutMs),
+      restartImpl: async () => { this.restartChild(); },
+      nowImpl: this.nowImpl,
+      env: this.env,
+      logImpl: (m) => this.log(m),
+      onUpdate: (rec) => {
+        this.log(`auto-update result: ${rec.from || '?'}→${rec.to} ${rec.status}`);
+        // A genuine version change landed healthy → restart the supervisor itself
+        // so its own new code loads (Part-8 stale-process fix). Guarded against
+        // loops inside scheduleSelfRestart. Fires only on a real bump (to≠from),
+        // never on rollback/failure (those statuses aren't 'ok').
+        if (rec.status === 'ok' && rec.to && rec.from && rec.to !== rec.from) {
+          this.scheduleSelfRestart(`auto-update ${rec.from}→${rec.to}`);
+        }
+      },
+    });
+  }
+
+  runUpdateTick(opts = {}) {
+    if (!this.autoUpdater) return;
+    this.autoUpdater.tick(opts)
+      .then((r) => { if (r && !['not-due', 'disabled', 'up-to-date', 'busy'].includes(r)) this.log(`auto-update tick: ${r}`); })
+      .catch((e) => this.log(`auto-update error: ${e?.message || e}`));
+  }
+
+  /**
+   * Build the DaemonSupervisor the always-on layer owns. Reads a FRESH config
+   * (not the stale module constant) so the account token / relay in effect when
+   * always-on starts are used. Lazy import keeps the unit-test path (which never
+   * calls start()) free of config + daemon-supervisor. Test seam: factory.
+   */
+  async buildDaemonSupervisor() {
+    if (this.daemonSupervisorFactory) return this.daemonSupervisorFactory(this);
+    const [{ buildConfig }, { DaemonSupervisor }] = await Promise.all([
+      import('./config.mjs'),
+      import('./daemon-supervisor.mjs'),
+    ]);
+    const config = buildConfig({ workspaceDir: this.workspaceDir, port: this.port });
+    return new DaemonSupervisor({
+      httpBase: config.daemonHttpUrl,
+      globalDir: this.globalDir,
+      accountToken: config.accountToken,
+      serverUrl: config.bmoSyncServerUrl,
+    });
+  }
+
+  /**
+   * One daemon-supervision step: if the daemon isn't answering /health, (re)start
+   * it. Deliberately INDEPENDENT of server health — the daemon (and its support
+   * channel) must stay up even when the server is crashed/mid-upgrade. Re-entrancy
+   * guarded so a slow spawn can't overlap the next tick. Never throws.
+   */
+  /** The daemon version the currently-running daemon was spawned under, or null. */
+  readDaemonMarker() {
+    try {
+      const v = JSON.parse(fs.readFileSync(this.daemonRuntimeFile, 'utf8'))?.daemonVersion;
+      return typeof v === 'string' ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  writeDaemonMarker(version) {
+    if (!version) return; // unknown installed version (PATH/vendor) — don't pin
+    try {
+      fs.mkdirSync(this.globalDir, { recursive: true });
+      fs.writeFileSync(this.daemonRuntimeFile, JSON.stringify({ daemonVersion: version }));
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  async daemonTick() {
+    if (!this.daemonSupervisor || this._daemonTicking) return 'skip';
+    this._daemonTicking = true;
+    try {
+      const installed = this.daemonVersionImpl();
+      const h = await this.daemonSupervisor.health();
+      if (h && h.running) {
+        // Running — but is it the CURRENT binary? After an auto-update the daemon
+        // keeps the old code until recycled (RC1b analog). Recycle when the
+        // installed version differs from what we recorded at spawn (a null marker
+        // = spawned by a pre-drift-aware supervisor → treat as drift, recycle once).
+        if (installed && this.readDaemonMarker() !== installed && this.daemonSupervisor.recycle) {
+          this.log(
+            `daemon version drift (marker=${this.readDaemonMarker() || 'none'} installed=${installed}) — recycling`,
+          );
+          const r = await this.daemonSupervisor.recycle();
+          if (r && r.started) {
+            this.writeDaemonMarker(installed);
+            this.log(`daemon recycled to ${installed} (pid=${r.pid})`);
+            return 'recycled';
+          }
+          this.log(`daemon recycle failed: ${r?.error || 'unknown'}`);
+          return 'recycle-failed';
+        }
+        return 'healthy';
+      }
+      const r = await this.daemonSupervisor.ensureRunning();
+      if (r && r.started) {
+        this.writeDaemonMarker(installed);
+        this.log(`daemon respawned (pid=${r.pid})`);
+        return 'respawned';
+      }
+      if (r && r.alreadyRunning) return 'healthy';
+      this.log(`daemon down, respawn not started: ${r?.error || 'unknown'}`);
+      return 'failed';
+    } catch (e) {
+      this.log(`daemon-tick error: ${e?.message || e}`);
+      return 'error';
+    } finally {
+      this._daemonTicking = false;
+    }
+  }
+
+  /** Acquire the lock and start the supervision loop. Idempotent across processes. */
+  start() {
+    if (!this.acquireLock()) return { started: false, reason: 'already-running' };
+    process.on('exit', () => this.releaseLock());
+    process.on('SIGTERM', () => process.exit(0));
+    process.on('SIGINT', () => process.exit(0));
+    this.log(`supervisor start pid=${process.pid} v${this.selfVersion || '?'} watching http://127.0.0.1:${this.port}/api/health (workspace=${this.workspaceDir})`);
+    this.timer = setInterval(() => { this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`)); }, this.pollMs);
+    this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`));
+
+    // Phase 2 auto-update: wake on a slow timer; the first check fires shortly
+    // after start so the server has time to come up (verify reads its /health).
+    if (this.autoUpdate && this.env.VITEST !== 'true' && this.env.NODE_ENV !== 'test') {
+      this.buildAutoUpdater().then((u) => {
+        this.autoUpdater = u;
+        this.updateTimer = setInterval(() => this.runUpdateTick(), this.updatePollMs);
+        if (this.updateTimer.unref) this.updateTimer.unref();
+        // FORCE the first post-boot check (bypass the 6h dueForCheck): a restart
+        // should always pull the latest, so a rebooted/woken machine can't sit on
+        // a stale version just because it last checked <6h ago.
+        const kick = setTimeout(() => this.runUpdateTick({ force: true }), 60_000);
+        if (kick.unref) kick.unref();
+      }).catch((e) => this.log(`auto-update init error: ${e?.message || e}`));
+    }
+
+    // Phase 3: keep the bmo-sync daemon alive independent of the server, so the
+    // out-of-band support channel survives the server being down.
+    if (this.superviseDaemon && this.env.VITEST !== 'true' && this.env.NODE_ENV !== 'test') {
+      this.buildDaemonSupervisor().then((d) => {
+        this.daemonSupervisor = d;
+        this.daemonTimer = setInterval(() => { this.daemonTick().catch((e) => this.log(`daemon-tick error: ${e?.message || e}`)); }, this.daemonPollMs);
+        if (this.daemonTimer.unref) this.daemonTimer.unref();
+        this.daemonTick().catch(() => {}); // first probe now
+      }).catch((e) => this.log(`daemon supervision init error: ${e?.message || e}`));
+    }
+    return { started: true };
+  }
+
+  stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    if (this.updateTimer) { clearInterval(this.updateTimer); this.updateTimer = null; }
+    if (this.daemonTimer) { clearInterval(this.daemonTimer); this.daemonTimer = null; }
+    this.releaseLock();
+  }
+}