sensorium-mcp 3.1.0-refactor.9 → 3.1.0

package/dist/services/self-update.service.js

@@ -1,7 +1,28 @@
 /**
- * Self-update service — polls the npm registry for the version published on
- * the update channel and performs a graceful self-spawn update on ANY version
- * mismatch (newer OR older — the latter is the channel-switch rollback path).
+ * Self-update service — polls the npm registry for the version published on the
+ * update channel and triggers a graceful update. Update rules:
+ *   - SAME channel: forward-only — update only when the published version is a
+ *     strictly newer semver (an equal/older version is ignored, never a
+ *     downgrade).
+ *   - Channel CHANGED (operator edited install.config.json):
+ *       · legacy/self-spawn mode — force-switch to the new channel's published
+ *         version even if it is an OLDER semver (the self-spawn respawn pins that
+ *         exact version, so the switch lands).
+ *       · broker mode — the switch is DEFERRED, not applied: the supervisor
+ *         respawns its own frozen launch channel and ignores install.config, so
+ *         a force-switch + /restart would restart-loop. The poller keeps the
+ *         launch channel forward-only until a full-stack restart (or the pending
+ *         supervisor-side change that passes targetVersion to /restart / re-reads
+ *         install.config) makes the switch honourable.
+ *     See decideUpdate.
+ *
+ * Single lifecycle owner (plan §4.5, Phase 4): this service no longer spawns
+ * its own replacement. It quiesces the agents, then asks the supervisor
+ * (POST /restart) to run the shared teardown/respawn choreography — the spawn
+ * command re-resolves the channel version by itself (npx). The pre-Phase-4
+ * self-spawn path survives only as the legacy fallback for dev mode without a
+ * supervisor, gated by the same SENSORIUM_BROKER_SPAWN cutover flag the spawn
+ * services use (see brokerSpawnMode in spawn-common.ts).
  *
  * Entry point: startSelfUpdatePoller({ pkgVersion, httpPort })
  * Call once after the HTTP server is listening (HTTP mode only).
@@ -11,38 +32,62 @@
  *   SELF_UPDATE_POLL_INTERVAL_MS  Registry check interval (default: 60000)
  *   SELF_UPDATE_MIN_UPTIME_MS  Min uptime before first update (default: 600000)
  *   SELF_UPDATE_GRACE_MS       Grace period for agents to observe flag (default: 30000)
- *   MCP_START_COMMAND          Replacement spawn command (default: npx -y sensorium-mcp@<target> --prefer-online)
+ *   SENSORIUM_BROKER_SPAWN     Cutover flag: 1/required = supervisor-only,
+ *                              0/off = legacy self-spawn, unset = auto
+ *   MCP_START_COMMAND          Launch-time command; its "@<tag>" is the baseline
+ *                              (currently-running) channel and the fallback when
+ *                              install.config.json cannot be read.
  *
  * Update channel:
- *   Derived from MCP_START_COMMAND — the npm spec tag in "sensorium-mcp@<tag>"
- *   (e.g. @latest or @refactor). The supervisor propagates this env var from
- *   install.config.json (MCPStartCommand) via Install-Sensorium.ps1, so the
- *   channel the poller follows always matches the command the replacement
- *   process is spawned with. Switch channels by editing install.config.json
- *   and re-running Install-Sensorium.ps1. No env var / no tag = "latest".
+ *   Resolved LIVE from ~/.remote-copilot-mcp/install.config.json (MCPStartCommand
+ *   → the npm spec tag in "sensorium-mcp@<tag>", e.g. @latest or @board) on every
+ *   poll cycle. In legacy/self-spawn mode, editing that file re-points the poller
+ *   with NO restart or Install-Sensorium.ps1 re-run. In broker/production mode a
+ *   file-only edit does NOT complete the switch (see above) — the supervisor is
+ *   frozen on its launch channel, so switching production needs a full-stack
+ *   restart / installer re-run (or the pending supervisor-side change). If the
+ *   config is missing/garbled/tag-less the poller falls back to the launch-time
+ *   MCP_START_COMMAND channel; the baseline it compares against is always what
+ *   THIS process was launched on. No config / no env / no tag = "latest".
  */
 import { spawn } from "node:child_process";
-import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "../lib/logger.js";
+import { dataDir } from "../lib/paths.js";
 import { emitMaintenanceSignal, hasObservedMaintenance } from "./maintenance-signal.js";
 import { writeReconnectSnapshot } from "./reconnect-snapshot.service.js";
 import { getActiveThreadIds } from "./process.service.js";
 import { getLiveWaitingThreadIds } from "../sessions/dashboard-registry.js";
+import { brokerRequestRestart } from "./broker-client.js";
+import { brokerSpawnMode } from "./spawn-common.js";
 // ---------------------------------------------------------------------------
 // Module-level state
 // ---------------------------------------------------------------------------
-const DATA_DIR = join(homedir(), ".remote-copilot-mcp");
+const DATA_DIR = dataDir();
 const FLAG_PATH = join(DATA_DIR, "maintenance.flag");
 /** Poller state: the config trio is set once by startSelfUpdatePoller;
- * updateInProgress is the re-entrancy guard for check/update cycles. */
+ * updateInProgress is the re-entrancy guard for check/update cycles;
+ * restartDelegatedAt records when the supervisor accepted a restart — this
+ * process is then living on borrowed time until the supervisor kills it, and
+ * the poller must not fire another update cycle in the interim. */
 const state = {
     updateInProgress: false,
+    restartDelegatedAt: 0,
     currentVersion: "",
+    currentChannel: "",
+    // The desired channel we last logged a broker-mode deferral for, so a config
+    // switch the supervisor cannot honor is logged once, not every poll cycle.
+    deferredSwitchLoggedFor: "",
     httpPort: 0,
     beforeSpawnHook: null,
 };
+// How long a supervisor-accepted restart may leave this process alive before
+// the poller concludes the teardown failed (e.g. the kill EPERM-failed — the
+// exact unkillable class this machine has produced) and resumes update polling.
+// Generous: the supervisor's own ready-timeout is 5 min, so 15 min of still
+// being alive means the restart is not coming. Self-healing over latching dead.
+const DELEGATED_RESTART_GRACE_MS = 15 * 60 * 1000;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -93,8 +138,9 @@ async function notifyTelegram(text) {
     const chatId = process.env.TELEGRAM_CHAT_ID;
     if (!token || !chatId)
         return;
+    const apiBaseUrl = process.env.TELEGRAM_API_BASE_URL ?? "https://api.telegram.org";
     try {
-        await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+        await fetch(`${apiBaseUrl}/bot${token}/sendMessage`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ chat_id: chatId, text }),
@@ -135,19 +181,24 @@ async function waitForHealthy(port, targetVersion, timeoutMs = 180_000) {
 // ---------------------------------------------------------------------------
 // Core logic
 // ---------------------------------------------------------------------------
-/** Release channel = the npm dist-tag the poller follows, parsed from the
- *  "sensorium-mcp@<tag>" spec in MCP_START_COMMAND (the same command the
- *  supervisor spawns this process with, propagated from install.config.json).
- *  Because an update fires on ANY version mismatch — not only a newer one —
- *  pointing the command back at @latest from a prerelease channel
- *  automatically DOWNGRADES to the stable build on the next cycle.
- *  A bare version in the spec (e.g. @3.0.32) acts as a version pin.
- *  No env var or no @tag in it = "latest". */
+/** Extract the npm dist-tag/channel from a "sensorium-mcp@<tag>" spec inside a
+ *  spawn command. Returns null when there is no parseable @tag (e.g. no spec, or
+ *  a semver range like @^3.0.0 the poller cannot follow). The negative lookbehind
+ *  keeps a bare "sensorium-mcp@3.0.5" version pin from being mistaken for a
+ *  scoped-package boundary. */
+function parseChannelFromCommand(cmd) {
+    const m = /(?<![\w.-])sensorium-mcp@([A-Za-z0-9._-]+)/.exec(cmd);
+    return m ? m[1] : null;
+}
+/** Launch-time release channel = the dist-tag frozen into MCP_START_COMMAND at
+ *  process start (what THIS process is actually running). Used as the baseline
+ *  the live desired-channel is compared against, and as the last-resort fallback
+ *  when install.config.json cannot be resolved. No env / no @tag = "latest". */
 function getUpdateChannel() {
     const cmd = process.env.MCP_START_COMMAND ?? "";
-    const m = /(?<![\w.-])sensorium-mcp@([A-Za-z0-9._-]+)/.exec(cmd);
-    if (m)
-        return m[1];
+    const tag = parseChannelFromCommand(cmd);
+    if (tag)
+        return tag;
     if (cmd.includes("sensorium-mcp@")) {
         // e.g. a semver range spec like @^3.0.0 — poller can't follow it, so the
         // channel falls back to "latest" while the spawn command keeps the range.
@@ -156,12 +207,138 @@ function getUpdateChannel() {
     return "latest";
 }
 /**
- * Fetch the published version of sensorium-mcp for the current update channel
- * (npm dist-tag) from the registry.
+ * Resolve the DESIRED release channel LIVE from install.config.json on every
+ * call, so editing that file re-points the poller without any process restart
+ * or installer re-run (behaviour 1). The channel is the "@<tag>" in the config's
+ * MCPStartCommand — the same field Install-Sensorium.ps1 reads.
+ *
+ * Defensive by construction: any problem — file missing, unreadable, garbled
+ * JSON, MCPStartCommand absent/non-string, or no parseable @tag — falls back to
+ * the launch-time env channel (getUpdateChannel). A broken config can therefore
+ * never crash the poller nor strand it on a bad channel; worst case it keeps
+ * following the channel it was launched with.
+ */
+export function resolveDesiredChannel() {
+    try {
+        const raw = readFileSync(join(dataDir(), "install.config.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        const cmd = typeof parsed.MCPStartCommand === "string" ? parsed.MCPStartCommand : "";
+        const tag = parseChannelFromCommand(cmd);
+        if (tag)
+            return tag;
+    }
+    catch {
+        /* fall through to the launch-time env channel */
+    }
+    return getUpdateChannel();
+}
+/** Parse "3.1.0-refactor.21" → { core:[3,1,0], pre:["refactor",21] }, or null if
+ *  the string is not a recognisable semver core. Numeric prerelease identifiers
+ *  are coerced to numbers so they compare numerically (per semver §11). */
+function parseSemver(v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v.trim());
+    if (!m)
+        return null;
+    const core = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const pre = m[4] ? m[4].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id)) : [];
+    return { core, pre };
+}
+/**
+ * True iff `a` is a strictly NEWER semver than `b`. Used to keep same-channel
+ * updates forward-only. Defensive: if either version fails to parse, returns
+ * false — an unparseable version must never justify a same-channel update, which
+ * could otherwise be an accidental downgrade.
+ */
+export function isStrictlyNewer(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i])
+            return pa.core[i] > pb.core[i];
+    }
+    // Equal cores: a release (no prerelease) outranks any prerelease.
+    if (pa.pre.length === 0 && pb.pre.length === 0)
+        return false;
+    if (pa.pre.length === 0)
+        return true;
+    if (pb.pre.length === 0)
+        return false;
+    // Both prereleases: compare identifier by identifier.
+    const n = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < n; i++) {
+        const x = pa.pre[i];
+        const y = pb.pre[i];
+        if (x === undefined)
+            return false; // a has fewer identifiers → lower precedence
+        if (y === undefined)
+            return true; // b has fewer identifiers → a is higher
+        if (x === y)
+            continue;
+        const xNum = typeof x === "number";
+        const yNum = typeof y === "number";
+        if (xNum && yNum)
+            return x > y;
+        if (xNum !== yNum)
+            return yNum; // numeric identifiers rank lower than strings
+        return String(x) > String(y);
+    }
+    return false;
+}
+/**
+ * Decide what a single poll cycle should do, given the running version/channel,
+ * the freshly-resolved desired channel, and whether we are in broker mode.
+ *
+ * `remoteVersion` is the published version of the channel this cycle actually
+ * TRACKS: the desired channel in legacy/self-spawn mode, but the LAUNCH channel
+ * (currentChannel) in broker mode — because the supervisor can only respawn its
+ * own frozen launch channel (see the caller).
+ *
+ *  - Legacy/self-spawn mode, channel CHANGED (behaviour 2): force-switch to the
+ *    desired channel's published version even if it is an OLDER semver — the
+ *    self-spawn path pins that exact version, so the switch lands. If that
+ *    version is already running, just adopt the new channel label.
+ *  - Broker mode, channel CHANGED: DO NOT force-switch. The supervisor respawns
+ *    its frozen launch channel and ignores install.config, so a force-switch +
+ *    /restart would loop forever (each child comes up on the launch channel and
+ *    re-detects the mismatch). We defer the switch and keep tracking the launch
+ *    channel forward-only, so a genuine forward move on the launch channel still
+ *    applies while the switch waits for a full-stack restart.
+ *  - SAME channel (either mode): forward-only — update only when the published
+ *    version is strictly newer (an equal/older version is ignored, so a poll can
+ *    never downgrade).
+ */
+export function decideUpdate(args) {
+    const { currentVersion, currentChannel, desiredChannel, remoteVersion, brokerMode } = args;
+    const channelChanged = desiredChannel !== currentChannel;
+    // Legacy/self-spawn honours a live channel switch (the respawn pins the exact
+    // resolved version). Broker mode cannot, so it falls through to forward-only.
+    if (channelChanged && !brokerMode) {
+        if (remoteVersion === currentVersion) {
+            return { action: "adopt-channel", channel: desiredChannel };
+        }
+        return { action: "update", targetVersion: remoteVersion, reason: "channel-switch" };
+    }
+    // Forward-only on the tracked channel (launch channel in broker mode).
+    const forwardUpdate = remoteVersion !== currentVersion && isStrictlyNewer(remoteVersion, currentVersion);
+    if (forwardUpdate) {
+        return { action: "update", targetVersion: remoteVersion, reason: "forward" };
+    }
+    // No forward move available. Surface a deferred broker-mode switch so the
+    // caller can log it once; otherwise nothing to do.
+    if (channelChanged && brokerMode) {
+        return { action: "defer-channel-switch", channel: desiredChannel };
+    }
+    return { action: "none" };
+}
+/**
+ * Fetch the published version of sensorium-mcp for the given update channel
+ * (npm dist-tag) from the registry. Defaults to the live desired channel when no
+ * channel is supplied, so external callers keep the previous behaviour.
  * Returns null on any error so the caller can silently skip this poll cycle.
  */
-export async function getRemoteVersion() {
-    const channel = getUpdateChannel();
+export async function getRemoteVersion(channel = resolveDesiredChannel()) {
     try {
         const response = await fetch(`https://registry.npmjs.org/sensorium-mcp/${encodeURIComponent(channel)}`, { signal: AbortSignal.timeout(15_000) });
         if (!response.ok) {
@@ -181,15 +358,17 @@ export async function getRemoteVersion() {
     }
 }
 /**
- * Full update sequence:
+ * Full update sequence (plan §4.5 — the supervisor owns the mechanics):
  *   1. Write maintenance flag  (wakes all active poll loops via fs.watch)
  *   2. Emit in-process signal  (belt-and-suspenders for loops not using fs.watch)
  *   3. Grace period            (agents observe flag and return maintenance response)
- *   4. Write reconnect snapshot
- *   5. Spawn replacement process (detached)
- *   7. Poll health endpoint until new server responds with targetVersion
- *   8a. Healthy → remove flag, exit(0)  (new server already wrote its own server.pid)
- *   8b. Unhealthy → kill child, remove flag, abort (MCP continues on current version)
+ *   4. ACK-gated quiesce, then write reconnect snapshot
+ *   5. POST /restart to the supervisor → 202, and THIS process just keeps
+ *      serving until the supervisor tears it down and respawns the channel
+ *      version. The supervisor owns the maintenance flag from here (it rewrites
+ *      it and always clears it after the respawn) — we must not touch it again.
+ *   Fallback (supervisor unreachable / old binary without /restart): the
+ *   legacy self-spawn path, allowed only outside "required" broker mode.
  */
 async function performUpdate(targetVersion) {
     state.updateInProgress = true;
@@ -200,9 +379,12 @@ async function performUpdate(targetVersion) {
         // Write maintenance flag
         try {
             mkdirSync(DATA_DIR, { recursive: true });
+            // `timestamp` is what checkMaintenanceFlag's 5-min stale auto-clear keys
+            // on (and what the supervisor's MaintenanceFlagWriter writes) — without it
+            // a flag leaked by a failed update would suppress agents forever.
             writeFileSync(FLAG_PATH, JSON.stringify({
                 version: targetVersion,
-                writtenAt: new Date().toISOString(),
+                timestamp: new Date().toISOString(),
             }));
         }
         catch (err) {
@@ -222,7 +404,7 @@ async function performUpdate(targetVersion) {
         await quiesceAgents();
         // Write reconnect snapshot so the new instance offers lightweight reconnect
         try {
-            const threadIds = getActiveThreadIds();
+            const threadIds = await getActiveThreadIds();
             if (threadIds.length > 0) {
                 writeReconnectSnapshot(threadIds);
             }
@@ -230,73 +412,33 @@ async function performUpdate(targetVersion) {
         catch (err) {
             log.warn(`[self-update] Reconnect snapshot failed (non-fatal): ${err}`);
         }
-        // Close existing HTTP server to free the port for the replacement process
-        const beforeSpawn = state.beforeSpawnHook;
-        if (beforeSpawn) {
-            log.info("[self-update] Closing HTTP server to free port...");
-            await beforeSpawn();
-        }
-        // Spawn the replacement process (detached so it survives our exit)
-        // Pin exact version to bypass stale npx cache (EPERM prevents cache clear on Windows)
-        const defaultCmd = `npx -y sensorium-mcp@${targetVersion} --prefer-online`;
-        const cmd = process.env.MCP_START_COMMAND ?? defaultCmd;
-        log.info(`[self-update] Spawning replacement: ${cmd}`);
-        const spawnLogPath = join(DATA_DIR, "update-spawn.log");
-        mkdirSync(DATA_DIR, { recursive: true });
-        const logFd = openSync(spawnLogPath, "a");
-        const child = spawn(cmd, [], {
-            detached: true,
-            shell: true,
-            stdio: ["ignore", logFd, logFd],
-            env: { ...process.env },
-        });
-        closeSync(logFd);
-        child.unref();
-        if (child.pid == null) {
-            throw new Error("Spawned child process has no PID — cannot proceed");
-        }
-        log.info(`[self-update] Replacement PID=${child.pid}, polling health on port ${state.httpPort}…`);
-        const healthy = await waitForHealthy(state.httpPort, targetVersion);
-        if (healthy) {
-            // The new server writes its own server.pid on startup (index.ts) with the
-            // real node PID. Do NOT overwrite here — child.pid is the transient shell
-            // PID on both Windows (cmd.exe) and Unix (/bin/sh), dead by this point.
-            // Remove maintenance flag — watcher MCPs unblock, new keepAlive threads start
-            try {
-                unlinkSync(FLAG_PATH);
-            }
-            catch {
-                /* best-effort */
-            }
-            log.info(`[self-update] Update to v${targetVersion} complete. Exiting.`);
-            process.exit(0);
-        }
-        else {
-            log.error("[self-update] New process failed to become healthy. Aborting update.");
-            // On Windows with shell:true, child.pid is the transient cmd.exe shell (already dead).
-            // Attempt kill anyway, then fall back to port-based kill on Windows.
-            try {
-                child.kill();
+        // Delegate the restart to the supervisor — the single process-lifecycle
+        // owner. It answers 202 and then runs the shared teardown/respawn
+        // choreography (PrepareShutdown → kill → spawn → wait-ready → clear flag);
+        // the spawn command re-resolves the channel version via npx by itself.
+        const mode = brokerSpawnMode();
+        if (mode !== "off") {
+            const verdict = await brokerRequestRestart(`self-update v${state.currentVersion} -> v${targetVersion}`);
+            if (verdict !== null) {
+                state.restartDelegatedAt = Date.now();
+                log.info(`[self-update] Restart ${verdict === "accepted" ? "delegated to" : "already in progress at"} the supervisor — awaiting teardown (it owns the maintenance flag now).`);
+                return;
             }
-            catch {
-                /* may already be dead */
-            }
-            if (process.platform === "win32") {
+            if (mode === "required") {
+                // No fallback allowed and no restart is coming: unblock the agents by
+                // clearing our flag and retry on a later poll cycle.
+                log.error("[self-update] Supervisor unreachable (or predates /restart) and SENSORIUM_BROKER_SPAWN=required — update aborted, will retry next poll.");
                 try {
-                    const { execSync } = await import("node:child_process");
-                    // Find and kill whatever is bound to our HTTP port
-                    execSync(`for /f "tokens=5" %a in ('netstat -ano ^| findstr :${state.httpPort} ^| findstr LISTENING') do taskkill /F /PID %a`, { shell: "cmd.exe", stdio: "ignore", timeout: 10_000 });
-                    log.info(`[self-update] Killed orphan process on port ${state.httpPort}`);
+                    unlinkSync(FLAG_PATH);
                 }
                 catch {
-                    log.warn(`[self-update] Could not kill orphan on port ${state.httpPort} — manual cleanup may be needed`);
+                    /* best-effort */
                 }
+                return;
             }
-            // Leave maintenance.flag intact so supervisor doesn't immediately race
-            // with an orphaned spawned child that may still be starting.
-            log.error("[self-update] Exiting (HTTP server closed, cannot recover). Supervisor will restart.");
-            process.exit(1);
+            log.warn("[self-update] Supervisor unreachable (or predates /restart) — falling back to legacy self-spawn so an old supervisor binary cannot strand updates.");
         }
+        await legacySelfSpawnUpdate(targetVersion);
     }
     catch (err) {
         log.error(`[self-update] Update sequence failed: ${err}`);
@@ -312,10 +454,98 @@ async function performUpdate(targetVersion) {
     }
 }
 /**
- * Run one check cycle: compare remote version to current and trigger update
- * on any mismatch (an older remote means the channel moved back — downgrade).
+ * Legacy self-spawn update (pre-Phase-4): close the HTTP listener, spawn the
+ * replacement ourselves, health-poll it, and exit. Kept ONLY for dev mode
+ * without a supervisor (SENSORIUM_BROKER_SPAWN=off / non-Windows) and as the
+ * auto-mode fallback behind an old supervisor binary. The netstat/taskkill
+ * orphan-hunt this path once had is gone — no shell-outs anywhere in the stack
+ * (plan §3.2); a failed replacement is now cleaned up by whoever owns process
+ * mechanics (the supervisor's kill-by-port on its next restart) or manually in
+ * true dev mode.
+ */
+async function legacySelfSpawnUpdate(targetVersion) {
+    // Close existing HTTP server to free the port for the replacement process
+    const beforeSpawn = state.beforeSpawnHook;
+    if (beforeSpawn) {
+        log.info("[self-update] Closing HTTP server to free port...");
+        await beforeSpawn();
+    }
+    // Spawn the replacement process (detached so it survives our exit).
+    // Pin the EXACT resolved version rather than re-running the frozen
+    // MCP_START_COMMAND: its floating "@<tag>" would re-resolve to the tag's
+    // CURRENT version, which on a channel switch is a different build than the
+    // one we just decided to install. Pinning also bypasses the stale npx cache
+    // (EPERM prevents a cache clear on Windows). This path is the dev/no-supervisor
+    // fallback; the supervisor path re-resolves the channel itself.
+    const cmd = `npx -y sensorium-mcp@${targetVersion} --prefer-online`;
+    log.info(`[self-update] Spawning replacement (legacy self-spawn): ${cmd}`);
+    const spawnLogPath = join(DATA_DIR, "update-spawn.log");
+    mkdirSync(DATA_DIR, { recursive: true });
+    const logFd = openSync(spawnLogPath, "a");
+    const child = spawn(cmd, [], {
+        detached: true,
+        shell: true,
+        stdio: ["ignore", logFd, logFd],
+        env: { ...process.env },
+    });
+    closeSync(logFd);
+    child.unref();
+    if (child.pid == null) {
+        throw new Error("Spawned child process has no PID — cannot proceed");
+    }
+    log.info(`[self-update] Replacement PID=${child.pid}, polling health on port ${state.httpPort}…`);
+    const healthy = await waitForHealthy(state.httpPort, targetVersion);
+    if (healthy) {
+        // The new server writes its own server.pid on startup (index.ts) with the
+        // real node PID. Do NOT overwrite here — child.pid is the transient shell
+        // PID on both Windows (cmd.exe) and Unix (/bin/sh), dead by this point.
+        // Remove maintenance flag — watcher MCPs unblock, new keepAlive threads start
+        try {
+            unlinkSync(FLAG_PATH);
+        }
+        catch {
+            /* best-effort */
+        }
+        log.info(`[self-update] Update to v${targetVersion} complete. Exiting.`);
+        process.exit(0);
+    }
+    else {
+        log.error("[self-update] New process failed to become healthy. Aborting update.");
+        // On Windows with shell:true, child.pid is the transient cmd.exe shell
+        // (already dead) — this kill is best-effort only. The old netstat/taskkill
+        // port-hunt is deliberately gone (no shell-outs).
+        try {
+            child.kill();
+        }
+        catch {
+            /* may already be dead */
+        }
+        // Leave maintenance.flag intact so a supervisor (if any) doesn't immediately
+        // race with an orphaned spawned child that may still be starting.
+        log.error("[self-update] Exiting (HTTP server closed, cannot recover). Supervisor will restart.");
+        process.exit(1);
+    }
+}
+/**
+ * Run one check cycle. The desired channel is resolved LIVE from
+ * install.config.json each cycle (behaviour 1). A change vs the running channel
+ * force-switches to that channel's published version even if it is older
+ * (behaviour 2); a same-channel poll updates only when the published version is
+ * strictly newer. See decideUpdate for the full rule set.
  */
 export async function checkForUpdate() {
+    // Once the supervisor has accepted a restart, this process is only alive
+    // until the teardown reaches it — don't start another update cycle. But a
+    // bounded wait, not a latch: if the teardown never arrives (kill failed and
+    // we survived), resume polling rather than staying pinned to a stale version
+    // forever. The orchestrator clears the maintenance flag even on failure, so
+    // a retry starts from a clean slate.
+    if (state.restartDelegatedAt !== 0) {
+        if (Date.now() - state.restartDelegatedAt < DELEGATED_RESTART_GRACE_MS)
+            return;
+        log.warn(`[self-update] Supervisor accepted a restart ${Math.round((Date.now() - state.restartDelegatedAt) / 60_000)}m ago but this process is still alive — teardown presumed failed, resuming update polling.`);
+        state.restartDelegatedAt = 0;
+    }
     if (state.updateInProgress)
         return;
     state.updateInProgress = true;
@@ -326,17 +556,56 @@ export async function checkForUpdate() {
             log.debug(`[self-update] Deferring — uptime ${Math.round(process.uptime())}s < min ${minUptimeMs / 1000}s`);
             return;
         }
-        const remoteVersion = await getRemoteVersion();
+        const desiredChannel = resolveDesiredChannel();
+        // Broker mode can only respawn the supervisor's own frozen launch channel
+        // (it ignores install.config), so acting on a channel CHANGE there would
+        // restart-loop. We therefore TRACK the launch channel in broker mode and
+        // defer the switch; only the legacy/self-spawn path (which pins the exact
+        // resolved version on respawn) follows the desired channel live.
+        const brokerMode = brokerSpawnMode() !== "off";
+        const trackedChannel = brokerMode ? state.currentChannel : desiredChannel;
+        const remoteVersion = await getRemoteVersion(trackedChannel);
         if (remoteVersion === null)
             return;
-        if (remoteVersion === state.currentVersion) {
-            // Routine "up to date" result — not logged. It fired every check (~once a
-            // minute) and was pure noise; the meaningful events (update found/applied/
-            // failed) are logged on their own branches.
-            return;
+        const decision = decideUpdate({
+            currentVersion: state.currentVersion,
+            currentChannel: state.currentChannel,
+            desiredChannel,
+            remoteVersion,
+            brokerMode,
+        });
+        switch (decision.action) {
+            case "none":
+                // Routine "up to date" result — not logged. It fired every check (~once
+                // a minute) and was pure noise; the meaningful events (update found/
+                // applied/failed) are logged on their own branches.
+                return;
+            case "defer-channel-switch":
+                // Broker mode saw a config channel change it cannot honor yet. Log once
+                // per distinct target (not every cycle), keep currentChannel = launch so
+                // it never thrashes, and stay on the launch channel forward-only.
+                if (state.deferredSwitchLoggedFor !== decision.channel) {
+                    state.deferredSwitchLoggedFor = decision.channel;
+                    log.warn(`[self-update] channel-switch to "${decision.channel}" deferred: supervisor cannot honor targetVersion yet — staying on "${state.currentChannel}" (forward-only). A full-stack restart / installer re-run is required to switch.`);
+                }
+                return;
+            case "adopt-channel":
+                // The new channel resolves to the exact version already running, so no
+                // respawn is needed — just adopt the label so we don't re-evaluate the
+                // switch every cycle.
+                log.info(`[self-update] Channel changed "${state.currentChannel}" -> "${decision.channel}"; already on v${state.currentVersion} — adopting channel, no restart.`);
+                state.currentChannel = decision.channel;
+                return;
+            case "update":
+                if (decision.reason === "channel-switch") {
+                    log.info(`[self-update] Channel changed "${state.currentChannel}" -> "${desiredChannel}"; force-switching to v${decision.targetVersion} (current v${state.currentVersion}).`);
+                }
+                else {
+                    log.info(`[self-update] Newer version on channel "${trackedChannel}": v${decision.targetVersion} (current v${state.currentVersion}) — updating.`);
+                }
+                await performUpdate(decision.targetVersion);
+                return;
         }
-        log.info(`[self-update] Channel version changed: v${remoteVersion} (current: v${state.currentVersion}) — updating`);
-        await performUpdate(remoteVersion);
     }
     finally {
         state.updateInProgress = false;
@@ -358,12 +627,16 @@ export function startSelfUpdatePoller(config) {
         return;
     }
     state.currentVersion = config.pkgVersion;
+    // Baseline channel = what THIS process was actually launched on (frozen env).
+    // Each poll compares the live install.config.json channel against this to
+    // detect an operator-driven channel switch.
+    state.currentChannel = getUpdateChannel();
     state.httpPort = config.httpPort;
     if (config.onBeforeSpawn)
         state.beforeSpawnHook = config.onBeforeSpawn;
     const rawInterval = parseInt(process.env.SELF_UPDATE_POLL_INTERVAL_MS ?? "", 10);
     const interval = Number.isFinite(rawInterval) && rawInterval > 0 ? rawInterval : 60_000;
-    log.info(`[self-update] Poller started (current: v${state.currentVersion}, interval: ${interval}ms)`);
+    log.info(`[self-update] Poller started (current: v${state.currentVersion} @${state.currentChannel}, interval: ${interval}ms)`);
     setInterval(() => {
         void checkForUpdate();
     }, interval);