@algosuite/vo-mcp 0.2.0-beta.11 → 0.2.0-beta.13

package/dist/runner-supervisor.js

@@ -31,9 +31,10 @@ var init_control_plane_auth_stub = __esm({
 
 // src/runner-supervisor.mjs
 import { spawn } from "node:child_process";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 
 // ../../scripts/virtual-office/code-runner/control-plane-client.mjs
 var cachedFirebaseToken = null;
@@ -54,22 +55,41 @@ async function resolveBearer(env) {
 function createControlPlaneClient({
   baseUrl = process.env.VO_CONTROL_PLANE_URL || "",
   env = process.env,
-  fetchImpl = fetch
+  fetchImpl = fetch,
+  heartbeatTimeoutMs = Math.min(
+    Math.max(Number(env.VO_CODE_RUNNER_HEARTBEAT_TIMEOUT_MS) || 15e3, 1e3),
+    6e4
+  )
 } = {}) {
   if (!baseUrl) {
     throw new Error("VO_CONTROL_PLANE_URL is required for the code-runner daemon");
   }
   const root = baseUrl.replace(/\/+$/, "");
-  async function req(method, path, body) {
+  async function req(method, path, body, { timeoutMs } = {}) {
     const bearer = await resolveBearer(env);
-    return fetchImpl(`${root}${path}`, {
+    const controller = timeoutMs ? new AbortController() : null;
+    let timeoutId;
+    const request = Promise.resolve(fetchImpl(`${root}${path}`, {
       method,
       headers: {
         "content-type": "application/json",
         authorization: `Bearer ${bearer}`
       },
-      body: body === void 0 ? void 0 : JSON.stringify(body)
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      ...controller ? { signal: controller.signal } : {}
+    }));
+    if (!timeoutMs) return request;
+    const timeout = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        controller.abort();
+        reject(new Error(`control-plane ${path} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
     });
+    try {
+      return await Promise.race([request, timeout]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
   return {
     /**
@@ -85,6 +105,10 @@ function createControlPlaneClient({
       if (Array.isArray(operatorIds) && operatorIds.length > 0) body.operator_ids = operatorIds;
       if (session.runnerInstanceId) body.runner_instance_id = session.runnerInstanceId;
       if (session.runnerInstanceId && session.reconcileStale) body.reconcile_stale = true;
+      if (session.defaultAgent) body.default_agent = session.defaultAgent;
+      if (Array.isArray(session.availableAgents)) {
+        body.available_agents = session.availableAgents.filter((entry) => entry?.installed === true && entry?.authenticated === true).map((entry) => entry.agent);
+      }
       const res = await req("POST", "/api/v1/code-task/claim", body);
       if (res.status === 401) {
         cachedFirebaseToken = null;
@@ -228,13 +252,20 @@ function createControlPlaneClient({
      * authenticated operator so the web shows a TRUE "runner online" signal.
      * Best-effort caller; throws on 401/non-ok so the daemon can log + retry.
      */
-    async postHeartbeat({ runnerId: runnerId2, operatorId, uptimeSec, activeTasks, version, daemonVersion, servedRepos, servedOperators, availableAgents, accountUsage }) {
+    async postHeartbeat({ runnerId: runnerId2, runnerInstanceId, operatorId, uptimeSec, activeTasks, version, daemonVersion, defaultAgent, supervisorInstanceId: supervisorInstanceId2, supervisorVersion: supervisorVersion2, supervisorCapabilities, servedRepos, servedOperators, availableAgents, accountUsage }) {
       const body = { runner_id: runnerId2 };
+      if (runnerInstanceId) body.runner_instance_id = runnerInstanceId;
       if (operatorId) body.operator_id = operatorId;
       if (typeof uptimeSec === "number") body.uptime_sec = uptimeSec;
       if (typeof activeTasks === "number") body.active_tasks = activeTasks;
       if (version) body.version = version;
       if (daemonVersion) body.daemon_version = daemonVersion;
+      if (defaultAgent) body.default_agent = defaultAgent;
+      if (supervisorInstanceId2) body.supervisor_instance_id = supervisorInstanceId2;
+      if (supervisorVersion2) body.supervisor_version = supervisorVersion2;
+      if (Array.isArray(supervisorCapabilities) && supervisorCapabilities.length > 0) {
+        body.supervisor_capabilities = supervisorCapabilities;
+      }
       if (Array.isArray(servedRepos) && servedRepos.length > 0) body.served_repos = servedRepos;
       if (Array.isArray(servedOperators) && servedOperators.length > 0) {
         body.served_operator_ids = servedOperators;
@@ -245,7 +276,9 @@ function createControlPlaneClient({
       if (Array.isArray(accountUsage) && accountUsage.length > 0) {
         body.account_usage = accountUsage;
       }
-      const res = await req("POST", "/api/v1/runner/heartbeat", body);
+      const res = await req("POST", "/api/v1/runner/heartbeat", body, {
+        timeoutMs: heartbeatTimeoutMs
+      });
       if (res.status === 401) {
         cachedFirebaseToken = null;
         throw new Error("heartbeat unauthorized (401)");
@@ -253,10 +286,27 @@ function createControlPlaneClient({
       if (!res.ok) throw new Error(`heartbeat failed: HTTP ${res.status}`);
       return true;
     },
+    /** Read the server-authoritative heartbeat ledger without mutating it. */
+    async getRunnerStatus({ operatorId } = {}) {
+      const query = operatorId ? `?operator_id=${encodeURIComponent(operatorId)}` : "";
+      const res = await req("GET", `/api/v1/runner/status${query}`, void 0, {
+        timeoutMs: heartbeatTimeoutMs
+      });
+      if (res.status === 401) {
+        cachedFirebaseToken = null;
+        throw new Error("runner status unauthorized (401)");
+      }
+      if (!res.ok) throw new Error(`runner status failed: HTTP ${res.status}`);
+      const body = await res.json();
+      return Array.isArray(body?.runners) ? body.runners : [];
+    },
     /** Poll one authenticated runner's durable Mission Control action queue. */
-    async pollRunnerControl({ runnerId: runnerId2, operatorId }) {
+    async pollRunnerControl({ runnerId: runnerId2, operatorId, supervisorInstanceId: supervisorInstanceId2, supervisorVersion: supervisorVersion2, capabilities }) {
       const body = { runner_id: runnerId2 };
       if (operatorId) body.operator_id = operatorId;
+      if (supervisorInstanceId2) body.supervisor_instance_id = supervisorInstanceId2;
+      if (supervisorVersion2) body.supervisor_version = supervisorVersion2;
+      if (Array.isArray(capabilities) && capabilities.length > 0) body.capabilities = capabilities;
       const res = await req("POST", "/api/v1/runner/control/poll", body);
       if (res.status === 401) {
         cachedFirebaseToken = null;
@@ -268,9 +318,12 @@ function createControlPlaneClient({
       return action && typeof action.action_id === "string" && action.action_id ? { ...action, actionId: action.action_id } : null;
     },
     /** Acknowledge a maintenance action after the host has restarted the child. */
-    async completeRunnerControl(actionId, { runnerId: runnerId2, operatorId, status, detail }) {
+    async completeRunnerControl(actionId, { runnerId: runnerId2, operatorId, supervisorInstanceId: supervisorInstanceId2, supervisorVersion: supervisorVersion2, capabilities, status, detail }) {
       const body = { runner_id: runnerId2, status };
       if (operatorId) body.operator_id = operatorId;
+      if (supervisorInstanceId2) body.supervisor_instance_id = supervisorInstanceId2;
+      if (supervisorVersion2) body.supervisor_version = supervisorVersion2;
+      if (Array.isArray(capabilities) && capabilities.length > 0) body.capabilities = capabilities;
       if (detail) body.detail = detail;
       const res = await req("POST", `/api/v1/runner/control/${encodeURIComponent(actionId)}/complete`, body);
       if (res.status === 401) {
@@ -438,6 +491,739 @@ function runHostMaintenance(kind, {
   return { ok: status === 0, status, command: command.command, args: command.args, detail };
 }
 
+// src/runner/bundled-runtime-updater.mjs
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
+import {
+  existsSync as existsSync3,
+  lstatSync as lstatSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  readdirSync as readdirSync2,
+  renameSync as renameSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { basename, isAbsolute as isAbsolute2, join as join2, resolve as resolve2 } from "node:path";
+import { spawnSync as spawnSync2 } from "node:child_process";
+
+// src/runner/bundled-runtime-store.mjs
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync as existsSync2,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+var SLOT_ID_RE = /^vo-mcp-[0-9A-Za-z._-]{1,96}$/u;
+var ACTION_ID_RE = /^[0-9A-Za-z._-]{1,128}$/u;
+var INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]{86}==$/u;
+var VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+var ENTRY_REL = join("node_modules", "@algosuite", "vo-mcp", "bin", "vo-mcp");
+var SUPERVISOR_REL = join("node_modules", "@algosuite", "vo-mcp", "dist", "runner-supervisor.js");
+var PACKAGE_REL = join("node_modules", "@algosuite", "vo-mcp", "package.json");
+var CREDENTIAL_HELPER_REL = join("node_modules", "@algosuite", "vo-mcp", "dist", "supervisor-credential-helper.js");
+var MANIFEST_FILE = "runtime-manifest.json";
+function within(parent, candidate) {
+  const rel = relative(resolve(parent), resolve(candidate));
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function runtimeRootFromEnv(env = process.env) {
+  const value = String(env.VO_RUNNER_RUNTIME_ROOT || "").trim();
+  return value && isAbsolute(value) ? resolve(value) : null;
+}
+function hashFileSha512(file) {
+  return `sha512-${createHash("sha512").update(readFileSync(file)).digest("base64")}`;
+}
+function hashRuntimeTree(root) {
+  const hasher = createHash("sha512");
+  const files = [];
+  const visit = (directory, prefix = "") => {
+    const rootStat = lstatSync(directory);
+    if (rootStat.isSymbolicLink()) throw new Error("runtime tree contains a link/reparse point");
+    if (!rootStat.isDirectory()) throw new Error("runtime tree root is not a directory");
+    for (const name of readdirSync(directory).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
+      const absolute = join(directory, name);
+      const relativePath = prefix ? `${prefix}/${name}` : name;
+      const stat = lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error("runtime tree contains a link/reparse point");
+      if (stat.isDirectory()) visit(absolute, relativePath);
+      else if (stat.isFile() && relativePath !== MANIFEST_FILE) files.push({ absolute, relativePath, size: stat.size });
+      else if (!stat.isFile()) throw new Error("runtime tree contains a non-regular file");
+    }
+  };
+  visit(root);
+  files.sort((a, b) => Buffer.compare(Buffer.from(a.relativePath), Buffer.from(b.relativePath)));
+  for (const file of files) {
+    const pathBytes = Buffer.from(file.relativePath, "utf8");
+    hasher.update(`${pathBytes.length}:`);
+    hasher.update(pathBytes);
+    hasher.update(`:${file.size}:`);
+    hasher.update(readFileSync(file.absolute));
+    hasher.update("\n");
+  }
+  return `sha512-${hasher.digest("base64")}`;
+}
+function atomicWriteJson(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = join(dirname(file), `.${randomUUID()}.tmp`);
+  const fd = openSync(temp, "wx", 384);
+  try {
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(temp, file);
+    if (process.platform !== "win32") {
+      try {
+        const parentFd = openSync(dirname(file), "r");
+        try {
+          fsyncSync(parentFd);
+        } finally {
+          closeSync(parentFd);
+        }
+      } catch {
+      }
+    }
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+function readActivation(runtimeRoot) {
+  const file = join(runtimeRoot, "current.json");
+  if (!existsSync2(file)) return null;
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    return value?.schema_version === 1 ? value : null;
+  } catch {
+    return null;
+  }
+}
+function slotPaths(runtimeRoot, slotId) {
+  if (!SLOT_ID_RE.test(slotId)) throw new Error("invalid runtime slot id");
+  const slotRoot = join(runtimeRoot, "slots", slotId);
+  return {
+    slotRoot,
+    entry: join(slotRoot, ENTRY_REL),
+    supervisor: join(slotRoot, SUPERVISOR_REL),
+    packageJson: join(slotRoot, PACKAGE_REL),
+    credentialHelper: join(slotRoot, CREDENTIAL_HELPER_REL),
+    manifest: join(slotRoot, MANIFEST_FILE)
+  };
+}
+function validActive(active) {
+  return active && SLOT_ID_RE.test(active.slot_id) && VERSION_RE.test(active.version) && INTEGRITY_RE.test(active.integrity) && INTEGRITY_RE.test(active.entry_sha512) && INTEGRITY_RE.test(active.supervisor_sha512) && INTEGRITY_RE.test(active.tree_sha512);
+}
+function validateSlot(runtimeRoot, active) {
+  if (!validActive(active)) return { ok: false, detail: "invalid activation metadata" };
+  const paths = slotPaths(runtimeRoot, active.slot_id);
+  try {
+    const manifest = JSON.parse(readFileSync(paths.manifest, "utf8"));
+    const pkg = JSON.parse(readFileSync(paths.packageJson, "utf8"));
+    const expected = {
+      slot_id: active.slot_id,
+      version: active.version,
+      integrity: active.integrity,
+      entry_sha512: active.entry_sha512,
+      supervisor_sha512: active.supervisor_sha512,
+      tree_sha512: active.tree_sha512
+    };
+    for (const [key, value] of Object.entries(expected)) {
+      if (manifest?.[key] !== value) return { ok: false, detail: `manifest ${key} mismatch` };
+    }
+    if (manifest?.schema_version !== 1 || pkg?.name !== "@algosuite/vo-mcp" || pkg?.version !== active.version) {
+      return { ok: false, detail: "package identity mismatch" };
+    }
+    if (lstatSync(paths.entry).isSymbolicLink() || lstatSync(paths.supervisor).isSymbolicLink() || lstatSync(paths.credentialHelper).isSymbolicLink()) {
+      return { ok: false, detail: "runtime entry cannot be a link" };
+    }
+    if (!within(paths.slotRoot, realpathSync(paths.entry)) || !within(paths.slotRoot, realpathSync(paths.supervisor)) || !within(paths.slotRoot, realpathSync(paths.credentialHelper))) {
+      return { ok: false, detail: "runtime entry escaped its slot" };
+    }
+    if (hashFileSha512(paths.entry) !== active.entry_sha512) return { ok: false, detail: "entry hash mismatch" };
+    if (hashFileSha512(paths.supervisor) !== active.supervisor_sha512) return { ok: false, detail: "supervisor hash mismatch" };
+    if (hashRuntimeTree(paths.slotRoot) !== active.tree_sha512) return { ok: false, detail: "runtime tree hash mismatch" };
+    return { ok: true, paths, manifest };
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+function journalActivation(runtimeRoot, actionId, state, detail = "") {
+  if (!ACTION_ID_RE.test(actionId)) throw new Error("invalid runner action id");
+  atomicWriteJson(join(runtimeRoot, "transactions", `${actionId}.json`), {
+    schema_version: 1,
+    action_id: actionId,
+    state,
+    detail: String(detail).slice(0, 400),
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function activateSlot(runtimeRoot, active, action) {
+  if (!validActive(active)) throw new Error("cannot activate invalid runtime metadata");
+  if (!ACTION_ID_RE.test(action.actionId)) throw new Error("invalid runner action id");
+  if (!UUID_RE.test(String(action.supervisorInstanceId || ""))) throw new Error("invalid claiming supervisor instance id");
+  const validated = validateSlot(runtimeRoot, active);
+  if (!validated.ok) throw new Error(`cannot activate invalid runtime slot: ${validated.detail}`);
+  const current = readActivation(runtimeRoot);
+  if (current?.pending) throw new Error("another runtime activation is still pending");
+  const pointer = {
+    schema_version: 1,
+    generation: randomUUID(),
+    active,
+    previous: validActive(current?.active) ? current.active : null,
+    pending: {
+      action_id: action.actionId,
+      runner_id: String(action.runnerId || ""),
+      operator_id: String(action.operatorId || ""),
+      supervisor_instance_id: action.supervisorInstanceId,
+      activated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      ack_attempts: 0
+    }
+  };
+  journalActivation(runtimeRoot, action.actionId, "prepared", `${active.version} ${active.integrity}`);
+  atomicWriteJson(join(runtimeRoot, "current.json"), pointer);
+  return pointer;
+}
+function activationSupervisorInstanceId(runtimeRoot, fallback) {
+  const current = runtimeRoot ? readActivation(runtimeRoot) : null;
+  const pending = String(current?.pending?.supervisor_instance_id || "");
+  if (UUID_RE.test(pending)) return pending;
+  return UUID_RE.test(String(fallback || "")) ? fallback : null;
+}
+function recordActivationRetry(runtimeRoot, pointer, detail) {
+  const current = readActivation(runtimeRoot);
+  if (current?.generation !== pointer?.generation || current?.pending?.action_id !== pointer?.pending?.action_id) {
+    throw new Error("runtime activation generation changed before retry");
+  }
+  const attempts = Math.max(0, Number(current.pending.ack_attempts || 0)) + 1;
+  const updated = {
+    ...current,
+    pending: { ...current.pending, ack_attempts: attempts, last_error: String(detail).slice(0, 240) }
+  };
+  atomicWriteJson(join(runtimeRoot, "current.json"), updated);
+  journalActivation(runtimeRoot, current.pending.action_id, "ack-retry", `attempt ${attempts}: ${detail}`);
+  return updated;
+}
+function attestCurrentSupervisor({ runtimeRoot, selfPath: selfPath2, version }) {
+  const pointer = readActivation(runtimeRoot);
+  if (!pointer?.pending || !validActive(pointer.active)) return { ok: false, detail: "no pending activation" };
+  const validated = validateSlot(runtimeRoot, pointer.active);
+  if (!validated.ok) return validated;
+  try {
+    if (realpathSync(selfPath2) !== realpathSync(validated.paths.supervisor)) {
+      return { ok: false, detail: "running supervisor is not the activated supervisor" };
+    }
+  } catch {
+    return { ok: false, detail: "could not resolve running supervisor path" };
+  }
+  if (version !== pointer.active.version) return { ok: false, detail: "running supervisor version mismatch" };
+  return { ok: true, pointer, active: pointer.active, paths: validated.paths };
+}
+function finalizeActivation(runtimeRoot, pointer) {
+  const current = readActivation(runtimeRoot);
+  if (current?.generation !== pointer?.generation || current?.pending?.action_id !== pointer?.pending?.action_id) {
+    throw new Error("runtime activation generation changed before finalization");
+  }
+  journalActivation(runtimeRoot, pointer.pending.action_id, "attesting", `${pointer.active.version} verified`);
+  atomicWriteJson(join(runtimeRoot, "current.json"), {
+    schema_version: 1,
+    generation: pointer.generation,
+    active: pointer.active,
+    previous: pointer.previous || null,
+    pending: null
+  });
+  try {
+    journalActivation(runtimeRoot, pointer.pending.action_id, "attested", `${pointer.active.version} active`);
+  } catch {
+  }
+}
+function rollbackActivation(runtimeRoot, pointer, detail) {
+  const current = readActivation(runtimeRoot);
+  if (current?.generation !== pointer?.generation || current?.pending?.action_id !== pointer?.pending?.action_id) {
+    throw new Error("runtime activation generation changed before rollback");
+  }
+  journalActivation(runtimeRoot, pointer.pending.action_id, "rolling-back", detail);
+  const rolledBack = {
+    schema_version: 1,
+    generation: randomUUID(),
+    active: validActive(pointer?.previous) ? pointer.previous : null,
+    previous: null,
+    pending: {
+      ...pointer.pending,
+      terminal_status: "failed",
+      terminal_detail: String(detail).slice(0, 400),
+      rolled_back_at: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  atomicWriteJson(join(runtimeRoot, "current.json"), rolledBack);
+  try {
+    journalActivation(runtimeRoot, pointer.pending.action_id, "rolled-back", detail);
+  } catch {
+  }
+  return rolledBack;
+}
+function acknowledgeActivationFailure(runtimeRoot, pointer) {
+  const current = readActivation(runtimeRoot);
+  if (current?.generation !== pointer?.generation || current?.pending?.action_id !== pointer?.pending?.action_id || current?.pending?.terminal_status !== "failed") {
+    throw new Error("runtime rollback acknowledgement obligation changed");
+  }
+  atomicWriteJson(join(runtimeRoot, "current.json"), { ...current, pending: null });
+  try {
+    journalActivation(runtimeRoot, pointer.pending.action_id, "failure-acknowledged", pointer.pending.terminal_detail);
+  } catch {
+  }
+}
+
+// src/runner/bundled-runtime-updater.mjs
+var PACKAGE_NAME = "@algosuite/vo-mcp";
+var PACKAGE_SPEC_RE2 = /^@algosuite\/vo-mcp@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+var INTEGRITY_RE2 = /^sha512-[A-Za-z0-9+/]{86}==$/u;
+var MAX_TARBALL_BYTES = 100 * 1024 * 1024;
+var PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+function buildMinimalMaintenanceEnv(env = process.env, runtimeRoot = "") {
+  const allowed = /* @__PURE__ */ new Set([
+    "PATH",
+    "Path",
+    "path",
+    "PATHEXT",
+    "SystemRoot",
+    "SYSTEMROOT",
+    "WINDIR",
+    "COMSPEC",
+    "TEMP",
+    "TMP",
+    "TMPDIR",
+    "HOME",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "ProgramFiles",
+    "ProgramFiles(x86)",
+    "ProgramW6432",
+    "LANG",
+    "LC_ALL"
+  ]);
+  const clean = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (allowed.has(key) && typeof value === "string") clean[key] = value;
+  }
+  return {
+    ...clean,
+    npm_config_ignore_scripts: "true",
+    npm_config_bin_links: "false",
+    npm_config_audit: "false",
+    npm_config_fund: "false",
+    npm_config_update_notifier: "false",
+    npm_config_registry: PUBLIC_REGISTRY,
+    ...runtimeRoot ? {
+      npm_config_userconfig: join2(runtimeRoot, "maintenance", "user.npmrc"),
+      npm_config_globalconfig: join2(runtimeRoot, "maintenance", "global.npmrc"),
+      npm_config_cache: join2(runtimeRoot, "maintenance", "npm-cache")
+    } : {}
+  };
+}
+function defaultRun(command, args, options) {
+  return spawnSync2(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    env: options.env,
+    shell: false,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeout ?? 12e4
+  });
+}
+function commandRunner({ platform, execPath, env, fileExists, run }) {
+  const npmCli = platform === "win32" ? resolveNpmCli({ env, execPath, fileExists }) : null;
+  if (platform === "win32" && !npmCli) throw new Error("trusted npm CLI not found");
+  const npmCommand = platform === "win32" ? execPath : "npm";
+  const prefix = npmCli ? [npmCli] : [];
+  return {
+    npm(args, options) {
+      return run(npmCommand, [...prefix, ...args], options);
+    },
+    node(args, options) {
+      return run(execPath, args, options);
+    }
+  };
+}
+function parseJsonOutput(result, operation) {
+  if (result?.status !== 0) {
+    throw new Error(`${operation} failed: ${String(result?.stderr || result?.error?.message || `exit ${result?.status ?? 1}`)}`);
+  }
+  try {
+    return JSON.parse(String(result.stdout || ""));
+  } catch {
+    throw new Error(`${operation} returned invalid JSON`);
+  }
+}
+function tarballIntegrity(file) {
+  return `sha512-${createHash2("sha512").update(readFileSync2(file)).digest("base64")}`;
+}
+function assertNoLinks(root) {
+  const pending = [root];
+  while (pending.length) {
+    const current = pending.pop();
+    const stat = lstatSync2(current);
+    if (stat.isSymbolicLink()) throw new Error("installed runtime contains a link/reparse point");
+    if (!stat.isDirectory()) continue;
+    for (const entry of readdirSync2(current)) pending.push(join2(current, entry));
+  }
+}
+function validateDependencyLock(payloadRoot, expected) {
+  const lock = JSON.parse(readFileSync2(join2(payloadRoot, "package-lock.json"), "utf8"));
+  if (Number(lock.lockfileVersion) < 3 || !lock.packages || typeof lock.packages !== "object") {
+    throw new Error("runtime dependency lock is missing or unsupported");
+  }
+  let foundPackage = false;
+  for (const [key, item] of Object.entries(lock.packages)) {
+    if (!key) continue;
+    if (item?.link === true) throw new Error(`runtime dependency lock contains link: ${key}`);
+    const isRunner = key.replaceAll("\\", "/").endsWith("node_modules/@algosuite/vo-mcp");
+    if (isRunner) {
+      foundPackage = item.version === expected.version && item.integrity === expected.integrity;
+      continue;
+    }
+    if (!INTEGRITY_RE2.test(String(item?.integrity || ""))) throw new Error(`dependency lacks sha512 integrity: ${key}`);
+    if (!String(item?.resolved || "").startsWith("https://registry.npmjs.org/")) {
+      throw new Error(`dependency is not registry-pinned: ${key}`);
+    }
+  }
+  if (!foundPackage) throw new Error("installed runner package does not match registry integrity");
+}
+function buildActive(slotId, metadata, paths) {
+  return {
+    slot_id: slotId,
+    version: metadata.version,
+    integrity: metadata.integrity,
+    entry_sha512: hashFileSha512(paths.entry),
+    supervisor_sha512: hashFileSha512(paths.supervisor),
+    tree_sha512: hashRuntimeTree(paths.slotRoot ?? paths.payloadRoot)
+  };
+}
+function installSlot({ runtimeRoot, metadata, tarball, runner, npmEnv, runOptions, force }) {
+  const digest = createHash2("sha256").update(metadata.integrity).digest("hex").slice(0, 16);
+  const suffix = force ? `${digest}-${randomUUID2().slice(0, 8)}` : digest;
+  const slotId = `vo-mcp-${metadata.version}-${suffix}`;
+  const finalPaths = slotPaths(runtimeRoot, slotId);
+  if (!force && existsSync3(finalPaths.slotRoot)) {
+    const manifest = JSON.parse(readFileSync2(finalPaths.manifest, "utf8"));
+    const active = buildActive(slotId, metadata, finalPaths);
+    const validated = validateSlot(runtimeRoot, active);
+    if (validated.ok && manifest.integrity === metadata.integrity) return { active, created: false };
+  }
+  const staging = join2(runtimeRoot, "staging", randomUUID2());
+  const payload = join2(staging, "payload");
+  let installedSlot = false;
+  try {
+    mkdirSync2(payload, { recursive: true });
+    writeFileSync2(join2(payload, "package.json"), `${JSON.stringify({ name: "algohq-runner-runtime", version: "0.0.0", private: true })}
+`);
+    const install = runner.npm([
+      "install",
+      "--ignore-scripts",
+      "--no-bin-links",
+      "--no-audit",
+      "--no-fund",
+      "--package-lock=true",
+      "--save-exact",
+      `--registry=${PUBLIC_REGISTRY}`,
+      tarball
+    ], { ...runOptions, cwd: payload, env: npmEnv, timeout: 18e4 });
+    if (install.status !== 0) throw new Error(`npm install failed: ${install.stderr || install.error?.message || install.status}`);
+    assertNoLinks(payload);
+    validateDependencyLock(payload, metadata);
+    const stagedPaths = {
+      entry: join2(payload, "node_modules", "@algosuite", "vo-mcp", "bin", "vo-mcp"),
+      supervisor: join2(payload, "node_modules", "@algosuite", "vo-mcp", "dist", "runner-supervisor.js"),
+      packageJson: join2(payload, "node_modules", "@algosuite", "vo-mcp", "package.json"),
+      credentialHelper: join2(payload, "node_modules", "@algosuite", "vo-mcp", "dist", "supervisor-credential-helper.js"),
+      slotRoot: payload
+    };
+    const pkg = JSON.parse(readFileSync2(stagedPaths.packageJson, "utf8"));
+    if (pkg.name !== PACKAGE_NAME || pkg.version !== metadata.version) throw new Error("installed package identity mismatch");
+    if (!lstatSync2(stagedPaths.credentialHelper).isFile()) throw new Error("installed credential helper is missing");
+    const smoke = runner.node([stagedPaths.entry, "runner", "--version"], { ...runOptions, cwd: payload, env: npmEnv, timeout: 3e4 });
+    if (smoke.status !== 0 || String(smoke.stdout || "").trim() !== `vo-mcp runner ${metadata.version}`) {
+      throw new Error("bundled runtime smoke check failed");
+    }
+    const active = buildActive(slotId, metadata, stagedPaths);
+    atomicWriteJson(join2(payload, "runtime-manifest.json"), { schema_version: 1, ...active });
+    mkdirSync2(join2(runtimeRoot, "slots"), { recursive: true });
+    if (existsSync3(finalPaths.slotRoot)) throw new Error("immutable runtime slot already exists");
+    renameSync2(payload, finalPaths.slotRoot);
+    installedSlot = true;
+    const validated = validateSlot(runtimeRoot, active);
+    if (!validated.ok) throw new Error(`staged runtime validation failed: ${validated.detail}`);
+    return { active, created: true };
+  } catch (error) {
+    if (installedSlot) rmSync2(finalPaths.slotRoot, { recursive: true, force: true });
+    throw error;
+  } finally {
+    rmSync2(staging, { recursive: true, force: true });
+  }
+}
+function stageBundledRuntimeSlot(options) {
+  const {
+    runtimeRoot,
+    packageSpec,
+    expectedVersion,
+    expectedIntegrity,
+    platform = process.platform,
+    execPath = process.execPath,
+    env = process.env,
+    fileExists = existsSync3,
+    run = defaultRun,
+    force = false
+  } = options;
+  if (!runtimeRoot || !isAbsolute2(runtimeRoot)) return { ok: false, status: 2, detail: "bundled runtime root unavailable" };
+  if (!expectedVersion || !PACKAGE_SPEC_RE2.test(`${PACKAGE_NAME}@${expectedVersion}`)) {
+    return { ok: false, status: 2, detail: "invalid expected runner version" };
+  }
+  if (!expectedIntegrity || !INTEGRITY_RE2.test(expectedIntegrity)) {
+    return { ok: false, status: 2, detail: "invalid expected runner integrity" };
+  }
+  const exactSpec = `${PACKAGE_NAME}@${expectedVersion}`;
+  if (packageSpec !== exactSpec) return { ok: false, status: 2, detail: "runner package spec does not match authorized version" };
+  const resolvedRoot = resolve2(runtimeRoot);
+  const npmEnv = buildMinimalMaintenanceEnv(env, resolvedRoot);
+  const runOptions = { env: npmEnv, cwd: resolvedRoot };
+  let tarDir = null;
+  try {
+    mkdirSync2(resolvedRoot, { recursive: true });
+    mkdirSync2(join2(resolvedRoot, "maintenance"), { recursive: true });
+    writeFileSync2(npmEnv.npm_config_userconfig, "", { mode: 384 });
+    writeFileSync2(npmEnv.npm_config_globalconfig, "", { mode: 384 });
+    const runner = commandRunner({ platform, execPath, env: npmEnv, fileExists, run });
+    const metadata = { version: expectedVersion, integrity: expectedIntegrity };
+    tarDir = join2(resolvedRoot, "staging", randomUUID2());
+    mkdirSync2(tarDir, { recursive: true });
+    const packed = parseJsonOutput(runner.npm([
+      "pack",
+      exactSpec,
+      "--ignore-scripts",
+      "--json",
+      "--pack-destination",
+      tarDir,
+      `--registry=${PUBLIC_REGISTRY}`
+    ], runOptions), "npm pack");
+    const record = Array.isArray(packed) ? packed[0] : packed;
+    const tarball = join2(tarDir, basename(String(record?.filename || "")));
+    if (!existsSync3(tarball) || !basename(tarball).endsWith(".tgz")) throw new Error("npm pack returned no tarball");
+    if (lstatSync2(tarball).size > MAX_TARBALL_BYTES) throw new Error("runner package tarball exceeds size limit");
+    if (record.integrity !== metadata.integrity || tarballIntegrity(tarball) !== metadata.integrity) {
+      throw new Error("runner package sha512 integrity mismatch");
+    }
+    const installed = installSlot({ runtimeRoot: resolvedRoot, metadata, tarball, runner, npmEnv, runOptions, force });
+    return { ok: true, status: 0, ...installed };
+  } catch (error) {
+    return { ok: false, status: 1, detail: sanitizeMaintenanceDiagnostic(error instanceof Error ? error.message : String(error), env) };
+  } finally {
+    if (tarDir) rmSync2(tarDir, { recursive: true, force: true });
+  }
+}
+function stageAndActivateBundledUpdate(options) {
+  const staged = stageBundledRuntimeSlot(options);
+  if (!staged.ok) return staged;
+  try {
+    activateSlot(resolve2(options.runtimeRoot), staged.active, options.action);
+    return { ...staged, handoff: true };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 1,
+      detail: sanitizeMaintenanceDiagnostic(error instanceof Error ? error.message : String(error), options.env ?? process.env)
+    };
+  }
+}
+
+// src/runner/supervisor-activation.mjs
+var MAX_ACK_ATTEMPTS = 3;
+var delay = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+async function waitForAuthoritativeRunnerHeartbeat({
+  client,
+  runnerId: runnerId2,
+  operatorId,
+  runnerInstanceId,
+  excludeRunnerInstanceId,
+  daemonVersion,
+  supervisorIdentity,
+  timeoutMs = 6e4,
+  pollMs = 1e3
+}) {
+  if (!runnerInstanceId && !excludeRunnerInstanceId) throw new Error("runner instance identity proof unavailable");
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const runners = await client.getRunnerStatus({ ...operatorId ? { operatorId } : {} });
+      const runner = runners.find((item) => item?.runner_id === runnerId2 && item.status === "online" && (runnerInstanceId ? item.runner_meta?.runner_instance_id === runnerInstanceId : Boolean(item.runner_meta?.runner_instance_id) && item.runner_meta.runner_instance_id !== excludeRunnerInstanceId) && item.runner_meta?.daemon_version === daemonVersion && item.runner_meta?.supervisor_instance_id === supervisorIdentity.supervisorInstanceId && item.runner_meta?.supervisor_version === supervisorIdentity.supervisorVersion && supervisorIdentity.capabilities.every((value) => item.runner_meta?.supervisor_capabilities?.includes(value)) && Array.isArray(item.runner_meta?.available_agents) && item.runner_meta.available_agents.some((agent) => agent.agent === item.runner_meta.default_agent && agent.installed === true && agent.authenticated === true));
+      if (runner) return runner;
+    } catch {
+    }
+    await delay(pollMs);
+  }
+  throw new Error("authoritative child heartbeat attestation timed out");
+}
+async function finishPendingActivation({
+  client,
+  child,
+  runtimeRoot,
+  operatorId,
+  runnerId: runnerId2,
+  selfPath: selfPath2,
+  packageVersion: packageVersion2,
+  supervisorIdentity,
+  waitForLocalRunner: waitForLocalRunner2,
+  localStatus: localStatus2,
+  waitForCloudRunner = waitForAuthoritativeRunnerHeartbeat,
+  cloudTimeoutMs,
+  cloudPollMs,
+  stopChild: stopChild2,
+  launchPreviousChild,
+  log = () => {
+  }
+}) {
+  const pointer = runtimeRoot ? readActivation(runtimeRoot) : null;
+  if (!pointer?.pending) return true;
+  const runnerIdForAction = pointer.pending.runner_id || runnerId2;
+  const operatorIdForAction = pointer.pending.operator_id || operatorId;
+  if (pointer.pending.terminal_status === "failed") {
+    try {
+      await client.completeRunnerControl(pointer.pending.action_id, {
+        runnerId: runnerIdForAction,
+        ...operatorIdForAction ? { operatorId: operatorIdForAction } : {},
+        ...supervisorIdentity,
+        status: "failed",
+        detail: pointer.pending.terminal_detail
+      });
+      acknowledgeActivationFailure(runtimeRoot, pointer);
+      return true;
+    } catch (error) {
+      log(`activation failure acknowledgement remains pending: ${error instanceof Error ? error.message : String(error)}`);
+      await stopChild2(child);
+      return false;
+    }
+  }
+  let attestation;
+  try {
+    attestation = attestCurrentSupervisor({ runtimeRoot, selfPath: selfPath2, version: packageVersion2 });
+    if (!attestation.ok) throw new Error(attestation.detail);
+    if (!await waitForLocalRunner2(child)) throw new Error("activated runner did not become locally ready");
+  } catch (error) {
+    let detail = `activation attestation failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 400);
+    let rolledBack = null;
+    try {
+      rolledBack = rollbackActivation(runtimeRoot, pointer, detail);
+    } catch (rollbackError) {
+      detail = `${detail}; rollback pending: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`.slice(0, 400);
+    }
+    try {
+      await client.completeRunnerControl(pointer.pending.action_id, {
+        runnerId: runnerIdForAction,
+        ...operatorIdForAction ? { operatorId: operatorIdForAction } : {},
+        ...supervisorIdentity,
+        status: "failed",
+        detail
+      });
+      if (rolledBack) acknowledgeActivationFailure(runtimeRoot, rolledBack);
+    } catch {
+    } finally {
+      await stopChild2(child);
+    }
+    return false;
+  }
+  let activatedRunnerInstanceId = null;
+  try {
+    const status = await localStatus2();
+    activatedRunnerInstanceId = status?.runnerInstanceId || null;
+    await waitForCloudRunner({
+      client,
+      runnerId: runnerIdForAction,
+      operatorId: operatorIdForAction,
+      runnerInstanceId: status?.runnerInstanceId,
+      daemonVersion: `vo-mcp/${attestation.active.version}`,
+      supervisorIdentity,
+      timeoutMs: cloudTimeoutMs,
+      pollMs: cloudPollMs
+    });
+    await client.completeRunnerControl(pointer.pending.action_id, {
+      runnerId: runnerIdForAction,
+      ...operatorIdForAction ? { operatorId: operatorIdForAction } : {},
+      ...supervisorIdentity,
+      status: "succeeded",
+      detail: `attested new supervisor ${attestation.active.version} ${attestation.active.integrity}`
+    });
+    finalizeActivation(runtimeRoot, attestation.pointer);
+    return true;
+  } catch (error) {
+    const failure = `activation acknowledgement failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 400);
+    let retry;
+    try {
+      retry = recordActivationRetry(runtimeRoot, attestation.pointer, failure);
+    } catch (retryError) {
+      log(`activation retry could not be recorded: ${retryError instanceof Error ? retryError.message : String(retryError)}`);
+      await stopChild2(child);
+      return false;
+    }
+    if (retry.pending.ack_attempts < MAX_ACK_ATTEMPTS) {
+      log(`activation acknowledgement pending (${retry.pending.ack_attempts}/${MAX_ACK_ATTEMPTS})`);
+      await stopChild2(child);
+      return false;
+    }
+    const previous = validateSlot(runtimeRoot, retry.previous);
+    let detail = `${failure}; retry limit reached; previous runtime restored`.slice(0, 400);
+    let rollbackChild = null;
+    let rolledBack = null;
+    try {
+      if (!previous.ok) throw new Error(`previous runtime invalid: ${previous.detail}`, { cause: error });
+      rolledBack = rollbackActivation(runtimeRoot, retry, detail);
+      await stopChild2(child);
+      rollbackChild = launchPreviousChild(previous.paths.entry);
+      if (!await waitForLocalRunner2(rollbackChild)) throw new Error("previous runner did not become locally ready", { cause: error });
+      const status = await localStatus2();
+      await waitForCloudRunner({
+        client,
+        runnerId: runnerIdForAction,
+        operatorId: operatorIdForAction,
+        runnerInstanceId: status?.runnerInstanceId,
+        excludeRunnerInstanceId: status?.runnerInstanceId ? void 0 : activatedRunnerInstanceId,
+        daemonVersion: `vo-mcp/${retry.previous.version}`,
+        supervisorIdentity,
+        timeoutMs: cloudTimeoutMs,
+        pollMs: cloudPollMs
+      });
+    } catch (rollbackError) {
+      detail = `${detail}; rollback proof failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`.slice(0, 400);
+    }
+    try {
+      await client.completeRunnerControl(retry.pending.action_id, {
+        runnerId: runnerIdForAction,
+        ...operatorIdForAction ? { operatorId: operatorIdForAction } : {},
+        ...supervisorIdentity,
+        status: "failed",
+        detail
+      });
+      if (rolledBack) acknowledgeActivationFailure(runtimeRoot, rolledBack);
+    } catch {
+    }
+    if (rollbackChild) await stopChild2(rollbackChild);
+    else await stopChild2(child);
+    return false;
+  }
+}
+
 // src/runner/supervisor-child-env.mjs
 import { hostname as systemHostname } from "node:os";
 
@@ -618,23 +1404,24 @@ async function prepareSupervisorAuth({
 }
 
 // src/runner/supervisor-credential-reader.mjs
-import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
-import { dirname, join } from "node:path";
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname2, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
 function defaultCredentialHelperPath(metaUrl = import.meta.url) {
-  const moduleDir = dirname(fileURLToPath(metaUrl));
-  const bundled = join(moduleDir, "supervisor-credential-helper.js");
-  const source = join(moduleDir, "..", "supervisor-credential-helper.mjs");
-  return existsSync2(source) ? source : bundled;
+  const moduleDir = dirname2(fileURLToPath(metaUrl));
+  const bundled = join3(moduleDir, "supervisor-credential-helper.js");
+  const source = join3(moduleDir, "..", "supervisor-credential-helper.mjs");
+  return existsSync4(source) ? source : bundled;
 }
 function readStoredCredentialIsolated({
-  spawn: spawn2 = spawnSync2,
+  spawn: spawn2 = spawnSync3,
   execPath = process.execPath,
   helperPath = defaultCredentialHelperPath(),
+  helperArgs = [],
   env = process.env
 } = {}) {
-  const result = spawn2(execPath, [helperPath], {
+  const result = spawn2(execPath, [helperPath, ...helperArgs], {
     env,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
@@ -657,8 +1444,11 @@ function readStoredCredentialIsolated({
 var DEFAULT_CONTROL_PLANE_URL = "https://vo-control-plane-bzjphrajaq-uc.a.run.app";
 var POLL_MS = 5e3;
 var CHILD_START_MS = 1500;
-var childEntry = join2(dirname2(fileURLToPath2(import.meta.url)), "runner-cli.js");
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var SUPERVISOR_CAPABILITIES = ["bundled-runtime-slots-v1"];
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+var selfPath = fileURLToPath2(import.meta.url);
+var childEntry = join4(dirname3(selfPath), "runner-cli.js");
+var sleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 var runnerId = resolveSupervisorRunnerId(process.env);
 function packageVersion() {
   try {
@@ -667,6 +1457,17 @@ function packageVersion() {
     return "unknown";
   }
 }
+var requestedSupervisorInstanceId = UUID_RE2.test(String(process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID || "")) ? process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID : randomUUID3();
+var supervisorInstanceId = activationSupervisorInstanceId(
+  runtimeRootFromEnv(process.env),
+  requestedSupervisorInstanceId
+);
+var supervisorVersion = packageVersion();
+var supervisorControlIdentity = {
+  supervisorInstanceId,
+  supervisorVersion,
+  capabilities: SUPERVISOR_CAPABILITIES
+};
 function spawnChild(childEnv) {
   return spawn(process.execPath, [childEntry], {
     env: childEnv,
@@ -674,6 +1475,13 @@ function spawnChild(childEnv) {
     windowsHide: true
   });
 }
+function spawnPreviousChild(entry, childEnv) {
+  return spawn(process.execPath, [entry, "runner"], {
+    env: childEnv,
+    stdio: "inherit",
+    windowsHide: true
+  });
+}
 async function localStatus() {
   try {
     const port = Number(process.env.VO_CODE_RUNNER_CONTROL_PORT || 7787);
@@ -689,7 +1497,8 @@ async function waitForLocalRunner(child) {
   const deadline = Date.now() + 15e3;
   while (Date.now() < deadline) {
     if (child.exitCode !== null) return false;
-    if ((await localStatus())?.running === true) return true;
+    const status = await localStatus();
+    if (status?.running === true && Number(status.pid) === Number(child.pid)) return true;
     await sleep(500);
   }
   return false;
@@ -698,7 +1507,7 @@ async function stopChild(child) {
   if (!child || child.exitCode !== null) return;
   child.kill(process.platform === "win32" ? void 0 : "SIGTERM");
   await Promise.race([
-    new Promise((resolve) => child.once("exit", resolve)),
+    new Promise((resolve3) => child.once("exit", resolve3)),
     sleep(15e3)
   ]);
   if (child.exitCode === null) child.kill("SIGKILL");
@@ -711,14 +1520,43 @@ async function main() {
     storedCredential: stored,
     controlPlaneUrl
   });
+  Object.assign(childEnv, {
+    VO_RUNNER_SUPERVISOR_INSTANCE_ID: supervisorInstanceId,
+    VO_RUNNER_SUPERVISOR_VERSION: supervisorVersion,
+    VO_RUNNER_SUPERVISOR_CAPABILITIES: SUPERVISOR_CAPABILITIES.join(",")
+  });
   const client = createControlPlaneClient({ baseUrl: controlPlaneUrl, env: clientEnv });
-  let child = spawnChild(childEnv);
+  const runtimeRoot = runtimeRootFromEnv(process.env);
+  let child = null;
   let stopping = false;
   let handling = false;
   const respawn = () => {
-    if (!stopping && !handling && (!child || child.exitCode !== null)) child = spawnChild(childEnv);
+    if (!stopping && !handling && (!child || child.exitCode !== null)) child = launchChild();
   };
-  child.on("exit", () => setTimeout(respawn, 2e3));
+  const launchChild = () => {
+    const next = spawnChild(childEnv);
+    next.on("exit", () => setTimeout(respawn, 2e3));
+    return next;
+  };
+  child = launchChild();
+  if (!await finishPendingActivation({
+    client,
+    child,
+    runtimeRoot,
+    operatorId,
+    runnerId,
+    selfPath,
+    packageVersion: supervisorVersion,
+    supervisorIdentity: supervisorControlIdentity,
+    waitForLocalRunner,
+    localStatus,
+    stopChild,
+    launchPreviousChild: (entry) => spawnPreviousChild(entry, childEnv),
+    log: (message) => console.error(`[vo-runner supervisor] ${message}`)
+  })) {
+    stopping = true;
+    return;
+  }
   const shutdown = async () => {
     if (stopping) return;
     stopping = true;
@@ -732,7 +1570,11 @@ async function main() {
   });
   while (!stopping) {
     try {
-      const action = await client.pollRunnerControl({ runnerId, ...operatorId ? { operatorId } : {} });
+      const action = await client.pollRunnerControl({
+        runnerId,
+        ...operatorId ? { operatorId } : {},
+        ...supervisorControlIdentity
+      });
       if (!action) {
         await sleep(POLL_MS);
         continue;
@@ -743,6 +1585,7 @@ async function main() {
         await client.completeRunnerControl(action.actionId, {
           runnerId,
           ...operatorId ? { operatorId } : {},
+          ...supervisorControlIdentity,
           status: "failed",
           detail: `deferred safely: ${beforeStop.activeTasks} active task(s); retry when the runner is idle`
         });
@@ -750,16 +1593,35 @@ async function main() {
         continue;
       }
       await stopChild(child);
-      const result = runHostMaintenance(action.kind, {
+      const bundledAction = action.kind === "update" || action.kind === "reinstall";
+      const result = bundledAction ? stageAndActivateBundledUpdate({
+        runtimeRoot,
+        packageSpec: `@algosuite/vo-mcp@${action.desired_package_version}`,
+        expectedVersion: action.desired_package_version,
+        expectedIntegrity: action.desired_package_integrity,
+        action: {
+          actionId: action.actionId,
+          runnerId,
+          operatorId: operatorId || "",
+          supervisorInstanceId
+        },
+        env: process.env,
+        force: action.kind === "reinstall"
+      }) : runHostMaintenance(action.kind, {
         env: clientEnv,
         log: (message) => console.warn(`[vo-runner supervisor] ${message}`)
       });
-      child = spawnChild(childEnv);
+      if (result.ok && result.handoff) {
+        console.warn(`[vo-runner supervisor] activated ${result.active.version}; exiting for new-process attestation`);
+        return;
+      }
+      child = launchChild();
       await sleep(CHILD_START_MS);
       if (child.exitCode !== null || !await waitForLocalRunner(child)) result.ok = false;
       await client.completeRunnerControl(action.actionId, {
         runnerId,
         ...operatorId ? { operatorId } : {},
+        ...supervisorControlIdentity,
         status: result.ok ? "succeeded" : "failed",
         detail: result.ok ? `runner ${packageVersion()} reconnected` : `maintenance exited ${result.status}${result.detail ? `: ${result.detail}` : ""}`
       });