lunibee 0.3.0 → 0.3.1

package/dist/sharding/index.js

@@ -2,7 +2,7 @@
 // packages/sharding/package.json
 var package_default = {
   name: "@lunibee/sharding",
-  version: "0.3.0",
+  version: "0.3.1",
   type: "module",
   module: "./src/index.ts",
   types: "./src/index.ts",
@@ -38,6 +38,37 @@ async function fetchGatewayBot(token) {
     };
   return info;
 }
+var MAX_GUILDS_PER_SHARD = 2500;
+function assertGuildsPerShard(value) {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_GUILDS_PER_SHARD)
+    throw new RangeError(`guildsPerShard must be an integer from 1 to ${MAX_GUILDS_PER_SHARD}.`);
+}
+function shardsForGuilds(guilds, guildsPerShard) {
+  assertGuildsPerShard(guildsPerShard);
+  if (!Number.isInteger(guilds) || guilds < 0)
+    throw new RangeError("guildCount must be a non-negative integer.");
+  return Math.max(1, Math.ceil(guilds / guildsPerShard));
+}
+async function fetchGuildCount(token) {
+  const response = await fetch("https://discord.com/api/v10/applications/@me", {
+    headers: {
+      Authorization: `Bot ${token}`,
+      "User-Agent": `Lunibee/${package_default.version}`
+    }
+  });
+  if (!response.ok)
+    throw new Error(`Guild count discovery failed with status ${response.status}`);
+  const data = await response.json();
+  const count = data.approximate_guild_count;
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 0)
+    throw new Error("Discord did not report a guild count.");
+  return count;
+}
+async function resolveShardCount(token, info, options) {
+  if (options.guildsPerShard === undefined)
+    return info.shards;
+  return shardsForGuilds(options.guildCount ?? await fetchGuildCount(token), options.guildsPerShard);
+}
 
 // packages/ws/src/session.ts
 class GatewaySession {
@@ -1036,7 +1067,7 @@ class Gateway {
   }
   connect(url = DEFAULT_GATEWAY_URL) {
     if (this.state === "CLOSED" /* Closed */)
-      throw new GatewayError("Gateway has been permanently closed.");
+      return Promise.reject(new GatewayError("Gateway has been permanently closed."));
     const inFlight = this.#reconnect.attemptPromise;
     if (inFlight)
       return inFlight;
@@ -1310,6 +1341,238 @@ class Gateway {
     this.#emit("stateChange", { previous, next });
   }
 }
+
+// packages/sharding/src/context.ts
+var WORKER_MARKER = "LUNIBEE_CLUSTER_WORKER";
+function isClusterWorker(env = process.env) {
+  return env[WORKER_MARKER] === "1";
+}
+function validateShardIds(shardIds, total) {
+  if (!Number.isInteger(total) || total < 1)
+    throw new RangeError("Shard count must be a positive integer.");
+  const seen = new Set;
+  for (const id of shardIds) {
+    if (!Number.isInteger(id) || id < 0 || id >= total)
+      throw new RangeError(`Shard ID ${String(id)} is outside 0-${total - 1}.`);
+    if (seen.has(id))
+      throw new RangeError(`Shard ID ${id} is listed twice.`);
+    seen.add(id);
+  }
+}
+function allocateShards(shardIds, clusterCount) {
+  if (!Number.isInteger(clusterCount) || clusterCount < 1)
+    throw new RangeError("clusterCount must be a positive integer.");
+  const chunks = Array.from({ length: clusterCount }, () => []);
+  shardIds.forEach((id, index) => chunks[index % clusterCount].push(id));
+  return chunks;
+}
+function assertCompleteAllocation(chunks, expected) {
+  const owners = new Map;
+  const duplicate = [];
+  chunks.forEach((chunk, cluster) => {
+    for (const id of chunk) {
+      if (owners.has(id))
+        duplicate.push(id);
+      owners.set(id, cluster);
+    }
+  });
+  const want = new Set(expected);
+  const missing = expected.filter((id) => !owners.has(id));
+  const extra = [...owners.keys()].filter((id) => !want.has(id));
+  if (duplicate.length || missing.length || extra.length)
+    throw new Error(`Shard allocation is not exact: duplicate [${duplicate}], missing [${missing}], unexpected [${extra}].`);
+}
+function parseInteger(name, value) {
+  if (value === undefined || !/^\d+$/.test(value))
+    throw new RangeError(`${name} must be a non-negative integer.`);
+  return Number(value);
+}
+function readClusterContext(env = process.env) {
+  if (!isClusterWorker(env))
+    return null;
+  const shardCount = parseInteger("SHARD_COUNT", env.SHARD_COUNT);
+  const shardIds = (env.SHARD_LIST ?? "").split(",").filter((part) => part !== "").map((part) => parseInteger("SHARD_LIST", part));
+  validateShardIds(shardIds, shardCount);
+  return {
+    clusterId: parseInteger("CLUSTER_ID", env.CLUSTER_ID),
+    clusterCount: parseInteger("CLUSTER_COUNT", env.CLUSTER_COUNT),
+    shardCount,
+    shardIds,
+    coordinatedIdentify: env.LUNIBEE_IDENTIFY === "coordinated"
+  };
+}
+
+// packages/sharding/src/protocol.ts
+var CLUSTER_FRAME = "__lunibeeCluster";
+var PARENT_ID = -1;
+var REQUEST_HEALTH = "__lunibee:health";
+var REQUEST_ASSIGN = "__lunibee:assign";
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isShardId = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+function parseChildFrame(value) {
+  if (!isRecord(value))
+    return null;
+  switch (value.kind) {
+    case "ready":
+      return Array.isArray(value.shardIds) && value.shardIds.every(isShardId) ? { kind: "ready", shardIds: value.shardIds } : null;
+    case "identify":
+      return typeof value.id === "number" && isShardId(value.shardId) ? { kind: "identify", id: value.id, shardId: value.shardId } : null;
+    case "identify-done":
+      return isShardId(value.shardId) ? { kind: "identify-done", shardId: value.shardId } : null;
+    case "reply":
+      return typeof value.id === "string" && (value.error === undefined || typeof value.error === "string") ? {
+        kind: "reply",
+        id: value.id,
+        ...value.error !== undefined ? { error: value.error } : { result: value.result }
+      } : null;
+    case "health":
+      return isRecord(value.report) && Array.isArray(value.report.shards) && typeof value.report.reportedAt === "number" ? { kind: "health", report: value.report } : null;
+    default:
+      return null;
+  }
+}
+function parseParentFrame(value) {
+  if (!isRecord(value))
+    return null;
+  switch (value.kind) {
+    case "identify-grant":
+      return typeof value.id === "number" ? { kind: "identify-grant", id: value.id } : null;
+    case "identify-deny":
+      return typeof value.id === "number" && typeof value.error === "string" ? { kind: "identify-deny", id: value.id, error: value.error } : null;
+    case "request":
+      return typeof value.id === "string" && typeof value.type === "string" ? {
+        kind: "request",
+        id: value.id,
+        type: value.type,
+        data: value.data
+      } : null;
+    default:
+      return null;
+  }
+}
+
+// packages/sharding/src/worker.ts
+class ClusterWorker {
+  static #current;
+  static current() {
+    if (!ClusterWorker.#current) {
+      const context = readClusterContext();
+      if (context && typeof process.send === "function")
+        ClusterWorker.#current = new ClusterWorker(context, process);
+    }
+    return ClusterWorker.#current;
+  }
+  static reset() {
+    ClusterWorker.#current?.close();
+    ClusterWorker.#current = undefined;
+  }
+  context;
+  #endpoint;
+  #handlers = new Map;
+  #waiting = new Map;
+  #onMessage;
+  #onDisconnect;
+  #counter = 0;
+  #closed = false;
+  constructor(context, endpoint = process) {
+    if (typeof endpoint.send !== "function")
+      throw new Error("ClusterWorker needs an IPC channel: run it in a process forked by ClusterManager.");
+    this.context = context;
+    this.#endpoint = endpoint;
+    this.#onMessage = (frame) => this.#handle(frame);
+    this.#onDisconnect = () => this.#failAll("The parent went away.");
+    endpoint.on("message", this.#onMessage);
+    endpoint.on("disconnect", this.#onDisconnect);
+  }
+  get identifyGate() {
+    return this.context.coordinatedIdentify ? this.#gate : undefined;
+  }
+  #gate = {
+    acquire: (shardId) => {
+      if (this.#closed)
+        return Promise.reject(new Error("The cluster worker is closed."));
+      const id = ++this.#counter;
+      return new Promise((resolve, reject) => {
+        this.#waiting.set(id, { resolve, reject });
+        this.#send({ kind: "identify", id, shardId });
+      });
+    },
+    release: (shardId) => this.#send({ kind: "identify-done", shardId })
+  };
+  ready(shardIds = this.context.shardIds) {
+    this.#send({ kind: "ready", shardIds: [...shardIds] });
+  }
+  reportHealth(report) {
+    this.#send({ kind: "health", report });
+  }
+  onRequest(type, handler) {
+    if (!type.trim() || typeof handler !== "function")
+      throw new TypeError("A request type and handler are required.");
+    this.#handlers.set(type, handler);
+    return this;
+  }
+  close() {
+    this.#closed = true;
+    this.#endpoint.off("message", this.#onMessage);
+    this.#endpoint.off("disconnect", this.#onDisconnect);
+    this.#failAll("The cluster worker closed.");
+  }
+  #send(body) {
+    try {
+      this.#endpoint.send({ [CLUSTER_FRAME]: body });
+    } catch (error) {
+      this.#failAll(error instanceof Error ? error.message : String(error));
+    }
+  }
+  #failAll(reason) {
+    for (const waiter of this.#waiting.values())
+      waiter.reject(new Error(reason));
+    this.#waiting.clear();
+  }
+  #handle(frame) {
+    if (!frame || typeof frame !== "object" || !(CLUSTER_FRAME in frame))
+      return;
+    const parsed = parseParentFrame(frame[CLUSTER_FRAME]);
+    if (!parsed)
+      return;
+    if (parsed.kind === "identify-grant" || parsed.kind === "identify-deny") {
+      const waiter = this.#waiting.get(parsed.id);
+      if (!waiter)
+        return;
+      this.#waiting.delete(parsed.id);
+      if (parsed.kind === "identify-grant")
+        waiter.resolve();
+      else
+        waiter.reject(new Error(parsed.error));
+      return;
+    }
+    const handler = this.#handlers.get(parsed.type);
+    const id = parsed.id;
+    if (!handler) {
+      this.#send({
+        kind: "reply",
+        id,
+        error: `No handler for "${parsed.type}".`
+      });
+      return;
+    }
+    (async () => {
+      try {
+        this.#send({
+          kind: "reply",
+          id,
+          result: await handler(parsed.data)
+        });
+      } catch (error) {
+        this.#send({
+          kind: "reply",
+          id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    })();
+  }
+}
 // packages/sharding/src/transport.ts
 class BroadcastChannelTransport {
   #channel;
@@ -1370,6 +1633,13 @@ function defaultTransport(name) {
 
 // packages/sharding/src/bus.ts
 var REPLY_TYPE = "__lunibee:reply";
+var MAX_NAME_LENGTH = 256;
+function isShardMessage(message) {
+  if (!message || typeof message !== "object")
+    return false;
+  const m = message;
+  return typeof m.type === "string" && m.type.length > 0 && m.type.length <= MAX_NAME_LENGTH && typeof m.id === "string" && m.id.length <= MAX_NAME_LENGTH && Number.isInteger(m.source) && m.source >= -1 && (m.target === null || Number.isInteger(m.target) && m.target >= -1);
+}
 
 class ShardBus {
   #transport;
@@ -1381,6 +1651,7 @@ class ShardBus {
   channelName;
   #counter = 0;
   #pending = new Map;
+  #closed = false;
   constructor(shardId, channelName, options = {}) {
     if (!Number.isInteger(shardId) || shardId < 0)
       throw new RangeError("Shard ID must be a non-negative integer.");
@@ -1453,6 +1724,8 @@ class ShardBus {
   }
   #collect(target, type, data, timeoutMs, expected, rejectOnPeerDown = false) {
     const replies = [];
+    if (this.#closed)
+      return Promise.reject(new Error("ShardBus is closed."));
     if (this.#pending.size >= this.#maxPending)
       return Promise.reject(new Error(`Too many shard requests waiting for a reply (${this.#maxPending}).`));
     return new Promise((resolve, reject) => {
@@ -1464,24 +1737,33 @@ class ShardBus {
       };
       const timer = setTimeout(finish, timeoutMs);
       requestId = this.#publish(target, type, data, true);
+      const fail = (error) => {
+        if (!rejectOnPeerDown)
+          return;
+        clearTimeout(timer);
+        this.#pending.delete(requestId);
+        reject(error);
+      };
       this.#pending.set(requestId, {
         target,
+        seen: new Set,
         reply: (reply) => {
           replies.push(reply);
           if (replies.length >= expected)
             finish();
         },
-        fail: (error) => {
-          if (rejectOnPeerDown) {
-            clearTimeout(timer);
-            this.#pending.delete(requestId);
-            reject(error);
-          }
-        }
+        fail,
+        cancel: (error) => rejectOnPeerDown ? fail(error) : finish()
       });
     });
   }
   close() {
+    if (this.#closed)
+      return;
+    this.#closed = true;
+    for (const pending of [...this.#pending.values()])
+      pending.cancel(new Error("ShardBus is closed."));
+    this.#pending.clear();
     this.#transport.close();
     this.#handlers.clear();
     this.#errorHandlers.clear();
@@ -1489,6 +1771,8 @@ class ShardBus {
   #publish(target, type, data, expectsReply = false) {
     if (!type.trim())
       throw new TypeError("Shard message type is required.");
+    if (this.#closed)
+      throw new Error("ShardBus is closed.");
     const id = `${this.#namespace}:${this.#shardId}:${++this.#counter}`;
     this.#transport.post({
       source: this.#shardId,
@@ -1501,15 +1785,21 @@ class ShardBus {
     return id;
   }
   #dispatch(message) {
-    if (!message || typeof message !== "object" || typeof message.type !== "string")
+    if (this.#closed || !isShardMessage(message))
       return;
     if (message.source === this.#shardId || message.target !== null && message.target !== this.#shardId)
       return;
     if (message.type === REPLY_TYPE) {
       const reply = message.data;
-      this.#pending.get(reply?.requestId)?.reply({
+      if (!reply || typeof reply !== "object" || typeof reply.requestId !== "string")
+        return;
+      const pending = this.#pending.get(reply.requestId);
+      if (!pending || pending.seen.has(message.source) || pending.target !== null && pending.target !== message.source)
+        return;
+      pending.seen.add(message.source);
+      pending.reply({
         shardId: message.source,
-        ...reply.error !== undefined ? { error: reply.error } : { result: reply.result }
+        ...reply.error !== undefined ? { error: String(reply.error) } : { result: reply.result }
       });
       return;
     }
@@ -1590,163 +1880,1523 @@ class ShardSupervisor {
 // packages/sharding/src/cluster.ts
 import { fork } from "child_process";
 import { cpus } from "os";
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-class ClusterManager {
-  clusters = new Map;
-  shardCount = 0;
-  #options;
-  #auto;
-  #autoScaleTimer;
-  #spawned = false;
-  #stopping = false;
-  #restartTimers = new Set;
-  #supervisor;
-  constructor(options) {
-    if (!options.token?.trim())
-      throw new TypeError("A Discord bot token is required.");
-    if (!options.script?.trim())
-      throw new TypeError("A script path is required for clustering.");
-    if (options.autoScaleInterval !== undefined && (!Number.isInteger(options.autoScaleInterval) || options.autoScaleInterval < 1000)) {
-      throw new RangeError("autoScaleInterval must be an integer of at least 1000 milliseconds.");
-    }
-    this.#auto = options.shardCount === "auto";
-    this.#options = { ...options };
-    this.#supervisor = new ShardSupervisor({
-      restartDelay: options.restartDelay,
-      ...options.supervisor
+// packages/sharding/src/identify.ts
+var IDENTIFY_INTERVAL = 5000;
+
+class IdentifyCoordinator {
+  maxConcurrency;
+  #interval;
+  #holdTimeout;
+  #now;
+  #schedule;
+  #cancel;
+  #onBudgetWait;
+  #keys = new Map;
+  #remaining;
+  #total;
+  #resetAt = Number.POSITIVE_INFINITY;
+  #timer;
+  #timerAt = Number.POSITIVE_INFINITY;
+  #closed = false;
+  constructor(options = {}) {
+    const concurrency = options.maxConcurrency ?? 1;
+    if (!Number.isInteger(concurrency) || concurrency < 1)
+      throw new RangeError("maxConcurrency must be a positive integer.");
+    const interval = options.interval ?? IDENTIFY_INTERVAL;
+    const hold = options.holdTimeout ?? 60000;
+    if (!(interval >= 0) || !(hold > 0))
+      throw new RangeError("interval cannot be negative and holdTimeout must be positive.");
+    this.maxConcurrency = concurrency;
+    this.#interval = interval;
+    this.#holdTimeout = hold;
+    this.#now = options.now ?? Date.now;
+    this.#schedule = options.schedule ?? ((callback, ms) => {
+      const timer = setTimeout(callback, ms);
+      timer.unref?.();
+      return timer;
     });
+    this.#cancel = options.cancel ?? ((handle) => clearTimeout(handle));
+    this.#onBudgetWait = options.onBudgetWait;
+    if (options.budget) {
+      this.#total = options.budget.total;
+      this.#remaining = options.budget.remaining;
+      this.#resetAt = this.#now() + options.budget.resetAfter;
+    }
   }
-  async fetchRecommendedShardCount() {
-    return (await fetchGatewayBot(this.#options.token)).shards;
+  get remaining() {
+    return this.#remaining;
+  }
+  get waiting() {
+    let count = 0;
+    for (const key of this.#keys.values())
+      count += key.queue.length;
+    return count;
+  }
+  get holding() {
+    let count = 0;
+    for (const key of this.#keys.values())
+      if (key.holder)
+        count++;
+    return count;
+  }
+  acquire(owner, shardId) {
+    if (this.#closed)
+      return Promise.reject(new Error("IDENTIFY coordinator is closed."));
+    const index = shardId % this.maxConcurrency;
+    let key = this.#keys.get(index);
+    if (!key)
+      this.#keys.set(index, key = { queue: [], nextAt: 0 });
+    return new Promise((grant, fail) => {
+      key.queue.push({ owner, shardId, grant, fail });
+      this.pump();
+    });
   }
-  async spawn() {
-    if (this.#spawned)
+  release(owner, shardId) {
+    const key = this.#keys.get(shardId % this.maxConcurrency);
+    const holder = key?.holder;
+    if (!key || !holder || holder.owner !== owner || holder.shardId !== shardId)
       return;
-    if (typeof process?.versions?.bun === "string") {
-      throw new Error("ClusterManager requires the Node.js runtime; Bun does not support child_process.fork() for this clustering mode.");
+    this.#free(key);
+    this.pump();
+  }
+  drop(owner, reason = "The cluster went away.") {
+    for (const key of this.#keys.values()) {
+      const keep = [];
+      for (const waiter of key.queue)
+        if (waiter.owner === owner)
+          waiter.fail(new Error(reason));
+        else
+          keep.push(waiter);
+      key.queue = keep;
+      if (key.holder?.owner === owner)
+        this.#free(key);
     }
-    this.#spawned = true;
-    const count = this.#options.shardCount === "auto" || this.#options.shardCount === undefined ? await this.fetchRecommendedShardCount() : this.#options.shardCount;
-    this.shardCount = count;
-    const clusterCount = this.#options.clusterCount ?? cpus().length;
-    const chunks = Array.from({ length: clusterCount }, () => []);
-    for (let i = 0;i < count; i++) {
-      chunks[i % clusterCount]?.push(i);
+    this.pump();
+  }
+  close() {
+    this.#closed = true;
+    if (this.#timer !== undefined)
+      this.#cancel(this.#timer);
+    this.#timer = undefined;
+    this.#timerAt = Number.POSITIVE_INFINITY;
+    for (const key of this.#keys.values()) {
+      if (key.holder)
+        this.#cancel(key.holder.timer);
+      key.holder = undefined;
+      for (const waiter of key.queue)
+        waiter.fail(new Error("IDENTIFY coordinator is closed."));
+      key.queue = [];
+    }
+  }
+  pump() {
+    if (this.#closed)
+      return;
+    const now = this.#now();
+    if (this.#total !== undefined && now >= this.#resetAt) {
+      this.#remaining = this.#total;
+      this.#resetAt = Number.POSITIVE_INFINITY;
     }
-    for (const [i, chunk] of chunks.entries()) {
-      if (chunk.length === 0)
+    let next = Number.POSITIVE_INFINITY;
+    for (const key of this.#keys.values()) {
+      if (key.holder || key.queue.length === 0)
+        continue;
+      if (key.nextAt > now) {
+        next = Math.min(next, key.nextAt);
+        continue;
+      }
+      if (this.#remaining !== undefined && this.#remaining <= 0) {
+        const waiter = key.queue[0];
+        if (this.#resetAt === Number.POSITIVE_INFINITY) {
+          key.queue.shift();
+          waiter.fail(new Error("The session start limit is exhausted."));
+          continue;
+        }
+        this.#onBudgetWait?.({
+          shardId: waiter.shardId,
+          waitMs: this.#resetAt - now
+        });
+        next = Math.min(next, this.#resetAt);
         continue;
-      this.#launch(i, chunk, count);
-      await sleep(500);
+      }
+      const waiter = key.queue.shift();
+      if (this.#remaining !== undefined)
+        this.#remaining--;
+      const timer = this.#schedule(() => {
+        if (key.holder?.timer === timer) {
+          this.#free(key);
+          this.pump();
+        }
+      }, this.#holdTimeout);
+      key.holder = {
+        owner: waiter.owner,
+        shardId: waiter.shardId,
+        timer
+      };
+      waiter.grant();
     }
-    if (this.#options.autoScaleInterval && this.#options.autoScaleInterval > 0) {
-      this.#autoScaleTimer = setInterval(() => {
-        this.checkAutoScale();
-      }, this.#options.autoScaleInterval);
+    this.#arm(next);
+  }
+  #free(key) {
+    if (key.holder)
+      this.#cancel(key.holder.timer);
+    key.holder = undefined;
+    key.nextAt = this.#now() + this.#interval;
+  }
+  #arm(at) {
+    if (at === this.#timerAt && this.#timer !== undefined)
+      return;
+    if (this.#timer !== undefined)
+      this.#cancel(this.#timer);
+    this.#timer = undefined;
+    this.#timerAt = Number.POSITIVE_INFINITY;
+    if (at === Number.POSITIVE_INFINITY)
+      return;
+    this.#timerAt = at;
+    this.#timer = this.#schedule(() => {
+      this.#timer = undefined;
+      this.#timerAt = Number.POSITIVE_INFINITY;
+      this.pump();
+    }, Math.max(0, at - this.#now()));
+  }
+}
+
+// packages/sharding/src/remote.ts
+import { EventEmitter } from "events";
+import { randomBytes } from "crypto";
+
+// packages/sharding/src/remote-protocol.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var REMOTE_PROTOCOL_VERSION = 1;
+var MAX_REMOTE_FRAME_BYTES = 8 * 1024 * 1024;
+var RemoteClose = {
+  BadRequest: 4400,
+  AuthFailed: 4401,
+  HelloTimeout: 4408,
+  DuplicateHost: 4409,
+  TooManyConnections: 4429,
+  UnknownHost: 4410,
+  VersionMismatch: 4426,
+  HostLost: 4504,
+  Shutdown: 4500
+};
+var SPAWN_ENV_KEYS = new Set([
+  "SHARD_LIST",
+  "SHARD_COUNT",
+  "CLUSTER_ID",
+  "CLUSTER_COUNT",
+  "LUNIBEE_SHARD_BUS",
+  "LUNIBEE_CLUSTER_WORKER",
+  "LUNIBEE_IDENTIFY"
+]);
+var KILL_SIGNALS = new Set([
+  "SIGTERM",
+  "SIGKILL",
+  "SIGINT"
+]);
+function isLoopbackHost(hostname) {
+  return /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|::1)$/i.test(hostname);
+}
+var HOST_ID = /^[A-Za-z0-9._-]{1,64}$/;
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isInt = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+function utf8Bytes(text) {
+  return Buffer.byteLength(text, "utf8");
+}
+function parseJson(text, maxBytes) {
+  if (typeof text !== "string")
+    return null;
+  if (text.length > maxBytes)
+    return null;
+  if (text.length * 3 > maxBytes && utf8Bytes(text) > maxBytes)
+    return null;
+  try {
+    const value = JSON.parse(text);
+    return isRecord2(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function signChallenge(secret, nonce, hostId) {
+  return createHmac("sha256", secret).update(`${nonce}:${hostId}`).digest("hex");
+}
+function verifyChallenge(secret, nonce, hostId, mac) {
+  if (typeof mac !== "string")
+    return false;
+  const expected = Buffer.from(signChallenge(secret, nonce, hostId), "hex");
+  const given = Buffer.from(mac, "hex");
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+function parseToHost(text, maxBytes = MAX_REMOTE_FRAME_BYTES) {
+  const v = parseJson(text, maxBytes);
+  if (!v)
+    return null;
+  switch (v.t) {
+    case "challenge":
+      return typeof v.nonce === "string" && isInt(v.version) ? { t: "challenge", nonce: v.nonce, version: v.version } : null;
+    case "welcome":
+      return isInt(v.leaseMs) && isInt(v.pingMs) ? { t: "welcome", leaseMs: v.leaseMs, pingMs: v.pingMs } : null;
+    case "ping":
+      return isInt(v.n) ? { t: "ping", n: v.n } : null;
+    case "spawn": {
+      if (!isInt(v.cluster) || !isInt(v.epoch) || !isRecord2(v.env))
+        return null;
+      const env = {};
+      for (const [key, value] of Object.entries(v.env)) {
+        if (!SPAWN_ENV_KEYS.has(key) || typeof value !== "string")
+          return null;
+        env[key] = value;
+      }
+      return { t: "spawn", cluster: v.cluster, epoch: v.epoch, env };
     }
+    case "frame":
+      return isInt(v.cluster) && isInt(v.epoch) ? {
+        t: "frame",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        frame: v.frame
+      } : null;
+    case "kill":
+      return isInt(v.cluster) && isInt(v.epoch) && typeof v.signal === "string" && KILL_SIGNALS.has(v.signal) ? {
+        t: "kill",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        signal: v.signal
+      } : null;
+    case "bye":
+      return typeof v.reason === "string" ? { t: "bye", reason: v.reason } : null;
+    default:
+      return null;
   }
-  #launch(id, shards, shardCount) {
-    const child = fork(this.#options.script, [], {
-      env: {
-        ...process.env,
-        SHARD_LIST: shards.join(","),
-        SHARD_COUNT: shardCount.toString(),
-        CLUSTER_ID: id.toString(),
-        LUNIBEE_SHARD_BUS: "ipc"
+}
+function parseToCoordinator(text, maxBytes = MAX_REMOTE_FRAME_BYTES) {
+  const v = parseJson(text, maxBytes);
+  if (!v)
+    return null;
+  switch (v.t) {
+    case "hello":
+      return typeof v.id === "string" && typeof v.mac === "string" && isInt(v.version) ? { t: "hello", id: v.id, mac: v.mac, version: v.version } : null;
+    case "pong":
+      return isInt(v.n) ? { t: "pong", n: v.n } : null;
+    case "spawned":
+      return isInt(v.cluster) && isInt(v.epoch) && (v.pid === undefined || isInt(v.pid)) ? {
+        t: "spawned",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        ...v.pid !== undefined ? { pid: v.pid } : {}
+      } : null;
+    case "frame":
+      return isInt(v.cluster) && isInt(v.epoch) ? {
+        t: "frame",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        frame: v.frame
+      } : null;
+    case "exit":
+      return isInt(v.cluster) && isInt(v.epoch) && (v.code === null || typeof v.code === "number") && (v.signal === null || typeof v.signal === "string") ? {
+        t: "exit",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        code: v.code,
+        signal: v.signal
+      } : null;
+    case "error":
+      return isInt(v.cluster) && isInt(v.epoch) && typeof v.message === "string" ? {
+        t: "error",
+        cluster: v.cluster,
+        epoch: v.epoch,
+        message: v.message
+      } : null;
+    default:
+      return null;
+  }
+}
+
+// packages/sharding/src/remote.ts
+class RemoteChild extends EventEmitter {
+  host;
+  cluster;
+  epoch;
+  pid;
+  exitCode = null;
+  signalCode = null;
+  connected = true;
+  #send;
+  #kill;
+  constructor(host, cluster, epoch, send, kill) {
+    super();
+    this.host = host;
+    this.cluster = cluster;
+    this.epoch = epoch;
+    this.#send = send;
+    this.#kill = kill;
+  }
+  send(frame) {
+    return this.connected && this.exitCode === null && this.signalCode === null ? this.#send(frame) : false;
+  }
+  kill(signal = "SIGTERM") {
+    if (this.exitCode !== null || this.signalCode !== null)
+      return false;
+    return this.#kill(signal);
+  }
+  spawned(pid) {
+    this.pid = pid;
+  }
+  deliver(frame) {
+    if (this.exitCode === null && this.signalCode === null)
+      this.emit("message", frame);
+  }
+  finish(code, signal) {
+    if (this.exitCode !== null || this.signalCode !== null)
+      return;
+    this.connected = false;
+    this.exitCode = code ?? (signal === null ? 1 : null);
+    this.signalCode = signal ?? null;
+    this.emit("exit", code, signal);
+  }
+}
+
+class RemoteHosts {
+  #options;
+  #links = new Map;
+  #waiters = new Set;
+  #hooks;
+  #server;
+  #watchdog;
+  #epoch = 0;
+  #ping = 0;
+  #unauthenticated = 0;
+  constructor(options, hooks) {
+    if (typeof options.secret !== "string" || options.secret.length < 16)
+      throw new RangeError("remote.secret must be a string of at least 16 characters.");
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535)
+      throw new RangeError("remote.port must be an integer from 0 to 65535.");
+    if (options.tls && (typeof options.tls.cert !== "string" || typeof options.tls.key !== "string" || !options.tls.cert || !options.tls.key))
+      throw new TypeError("remote.tls needs a non-empty cert and key.");
+    if (!options.tls && !options.allowInsecure && !isLoopbackHost(options.hostname ?? "127.0.0.1"))
+      throw new RangeError("remote listens on a network address without TLS: set remote.tls, bind 127.0.0.1 behind a TLS proxy, or set remote.allowInsecure for a network you fully trust.");
+    const lease = options.lease ?? 15000;
+    if (!Number.isFinite(lease) || lease < 30)
+      throw new RangeError("remote.lease must be at least 30 milliseconds.");
+    for (const id of options.hosts ?? [])
+      if (!HOST_ID.test(id))
+        throw new RangeError(`"${id}" is not a valid host ID.`);
+    if (options.hosts && (options.hosts.length === 0 || new Set(options.hosts).size !== options.hosts.length))
+      throw new RangeError("remote.hosts must be unique and not empty.");
+    if (options.minHosts !== undefined && (!Number.isInteger(options.minHosts) || options.minHosts < 1))
+      throw new RangeError("remote.minHosts must be a positive integer.");
+    this.#options = { ...options, lease };
+    this.#hooks = hooks;
+  }
+  get port() {
+    return this.#server?.port;
+  }
+  connected() {
+    return [...this.#links.keys()].sort();
+  }
+  start() {
+    if (this.#server)
+      return;
+    const { port, hostname, tls, lease } = this.#options;
+    this.#server = Bun.serve({
+      port,
+      hostname: hostname ?? "127.0.0.1",
+      ...tls ? { tls } : {},
+      fetch: (request, server) => {
+        if (server.upgrade(request, {
+          data: { nonce: randomBytes(16).toString("hex") }
+        }))
+          return;
+        return new Response("Lunibee cluster coordinator", {
+          status: 426
+        });
+      },
+      websocket: {
+        maxPayloadLength: MAX_REMOTE_FRAME_BYTES,
+        idleTimeout: 0,
+        open: (ws) => this.#open(ws),
+        message: (ws, raw) => this.#message(ws, raw),
+        close: (ws, _code, reason) => this.#closed(ws, reason)
       }
     });
-    const info = { id, process: child, shards };
-    this.clusters.set(id, info);
-    child.on("message", (frame) => this.#relay(id, frame));
-    child.once("exit", (code, signal) => {
-      if (this.clusters.get(id)?.process !== child)
-        return;
-      try {
-        this.#options.onClusterExit?.(info, code, signal);
-      } catch {}
-      if (!this.#stopping)
-        this.#announceDown(id, shards);
-      if (this.#stopping || this.#options.restartOnExit === false)
-        return;
-      this.clusters.delete(id);
-      const delay = this.#supervisor.next(id);
-      if (delay === null) {
-        try {
-          this.#options.onGiveUp?.(info);
-        } catch {}
-        return;
-      }
+    const pingMs = Math.max(10, Math.floor(lease / 3));
+    this.#watchdog = setInterval(() => this.#tick(), pingMs);
+    this.#watchdog.unref?.();
+  }
+  stop() {
+    if (this.#watchdog)
+      clearInterval(this.#watchdog);
+    this.#watchdog = undefined;
+    for (const link of [...this.#links.values()]) {
+      this.#post(link, { t: "bye", reason: "The coordinator stopped." });
+      this.#drop(link, "The coordinator stopped.", RemoteClose.Shutdown);
+    }
+    this.#server?.stop(true);
+    this.#server = undefined;
+    this.abortWaits();
+  }
+  waitFor(hosts, count, timeoutMs) {
+    const done = () => hosts ? hosts.every((id) => this.#links.has(id)) : this.#links.size >= count;
+    if (done())
+      return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        check: () => {
+          if (!done())
+            return;
+          clearTimeout(timer);
+          this.#waiters.delete(waiter);
+          resolve();
+        },
+        abort: (error) => {
+          clearTimeout(timer);
+          this.#waiters.delete(waiter);
+          reject(error);
+        }
+      };
       const timer = setTimeout(() => {
-        this.#restartTimers.delete(timer);
-        if (this.#stopping || !this.#spawned)
-          return;
-        this.#launch(id, shards, shardCount);
-      }, delay);
-      timer.unref?.();
-      this.#restartTimers.add(timer);
+        const missing = hosts?.filter((id) => !this.#links.has(id));
+        waiter.abort(new Error(hosts ? `Hosts did not join within ${timeoutMs}ms: [${missing}].` : `Only ${this.#links.size} of ${count} hosts joined within ${timeoutMs}ms.`));
+      }, timeoutMs);
+      this.#waiters.add(waiter);
     });
-    return info;
   }
-  #relay(from, frame) {
-    if (!frame || typeof frame !== "object" || !(BUS_FRAME in frame))
-      return;
-    for (const [id, cluster] of this.clusters)
-      if (id !== from)
-        this.#sendFrame(cluster, frame);
+  abortWaits() {
+    for (const waiter of [...this.#waiters])
+      waiter.abort(new Error("The coordinator stopped."));
   }
-  #announceDown(exited, shards) {
-    for (const [id, cluster] of this.clusters)
-      if (id !== exited)
-        this.#sendFrame(cluster, { [PEER_DOWN_FRAME]: shards });
+  status(declared = []) {
+    const ids = new Set([...declared, ...this.#links.keys()]);
+    return [...ids].sort().map((id) => {
+      const link = this.#links.get(id);
+      return {
+        id,
+        connected: link !== undefined,
+        lastSeen: link?.lastSeen ?? 0,
+        clusters: link ? [...link.children.keys()].sort((a, b) => a - b) : []
+      };
+    });
   }
-  #sendFrame(cluster, frame) {
-    const child = cluster.process;
-    if (typeof child.send !== "function" || !child.connected)
-      return;
+  createChild(hostId, cluster, env) {
+    const epoch = ++this.#epoch;
+    const link = this.#links.get(hostId);
+    const child = new RemoteChild(hostId, cluster, epoch, (frame) => link !== undefined && this.#post(link, { t: "frame", cluster, epoch, frame }), (signal) => link !== undefined && this.#post(link, { t: "kill", cluster, epoch, signal }));
+    if (!link) {
+      queueMicrotask(() => child.finish(null, "SIGHUP"));
+      return child;
+    }
+    link.children.get(cluster)?.finish(null, "SIGKILL");
+    link.children.set(cluster, child);
+    if (!this.#post(link, { t: "spawn", cluster, epoch, env }))
+      queueMicrotask(() => child.finish(null, "SIGHUP"));
+    return child;
+  }
+  #post(link, message) {
     try {
-      child.send(frame);
-    } catch {}
+      return link.ws.send(JSON.stringify(message)) > 0;
+    } catch {
+      return false;
+    }
   }
-  async checkAutoScale() {
-    if (!this.#auto)
+  #open(ws) {
+    if (this.#unauthenticated >= (this.#options.maxUnauthenticated ?? 16)) {
+      ws.close(RemoteClose.TooManyConnections, "Too many connections.");
       return;
-    try {
-      const recommended = await this.fetchRecommendedShardCount();
-      if (recommended !== this.shardCount) {
-        await this.respawn(recommended);
-      }
-    } catch (error) {
-      const normalized = error instanceof Error ? error : new Error(String(error));
-      this.#options.onAutoScaleError?.(normalized);
     }
+    this.#unauthenticated++;
+    ws.data.counted = true;
+    ws.data.helloTimer = setTimeout(() => ws.close(RemoteClose.HelloTimeout, "No hello."), this.#options.helloTimeout ?? 1e4);
+    ws.send(JSON.stringify({
+      t: "challenge",
+      nonce: ws.data.nonce,
+      version: REMOTE_PROTOCOL_VERSION
+    }));
   }
-  async respawn(newShardCount) {
-    this.#options.shardCount = newShardCount;
-    await this.shutdownAll();
-    this.#spawned = false;
-    this.#supervisor.reset();
+  #message(ws, raw) {
+    if (typeof raw !== "string") {
+      ws.close(RemoteClose.BadRequest, "Text frames only.");
+      return;
+    }
+    const message = parseToCoordinator(raw);
+    if (!message) {
+      ws.close(RemoteClose.BadRequest, "Malformed frame.");
+      return;
+    }
+    if (ws.data.id === undefined) {
+      this.#hello(ws, message);
+      return;
+    }
+    const link = this.#links.get(ws.data.id);
+    if (!link || link.ws !== ws)
+      return;
+    link.lastSeen = Date.now();
+    if (message.t === "pong" || message.t === "hello")
+      return;
+    const child = link.children.get(message.cluster);
+    if (!child || child.epoch !== message.epoch)
+      return;
+    switch (message.t) {
+      case "spawned":
+        child.spawned(message.pid);
+        break;
+      case "frame":
+        child.deliver(message.frame);
+        break;
+      case "exit":
+        link.children.delete(message.cluster);
+        child.finish(message.code, message.signal);
+        break;
+      case "error":
+        this.#hooks.error(new Error(`Host ${link.id} could not run cluster ${message.cluster}: ${message.message}`));
+        link.children.delete(message.cluster);
+        child.finish(1, null);
+        break;
+    }
+  }
+  #hello(ws, message) {
+    if (message?.t !== "hello") {
+      ws.close(RemoteClose.BadRequest, "Expected hello.");
+      return;
+    }
+    const { id } = message;
+    if (message.version !== REMOTE_PROTOCOL_VERSION) {
+      ws.close(RemoteClose.VersionMismatch, "Protocol version mismatch.");
+      return;
+    }
+    if (!HOST_ID.test(id) || !verifyChallenge(this.#options.secret, ws.data.nonce, id, message.mac)) {
+      ws.close(RemoteClose.AuthFailed, "Authentication failed.");
+      return;
+    }
+    if (this.#options.hosts && !this.#options.hosts.includes(id)) {
+      ws.close(RemoteClose.UnknownHost, "Host is not part of this deployment.");
+      return;
+    }
+    if (this.#links.has(id)) {
+      ws.close(RemoteClose.DuplicateHost, "A host with this ID is connected.");
+      return;
+    }
+    clearTimeout(ws.data.helloTimer);
+    this.#uncount(ws);
+    ws.data.id = id;
+    const link = {
+      id,
+      ws,
+      lastSeen: Date.now(),
+      children: new Map
+    };
+    this.#links.set(id, link);
+    const lease = this.#options.lease;
+    this.#post(link, {
+      t: "welcome",
+      leaseMs: lease,
+      pingMs: Math.max(10, Math.floor(lease / 3))
+    });
+    this.#hooks.join(id);
+    for (const waiter of [...this.#waiters])
+      waiter.check();
+  }
+  #uncount(ws) {
+    if (ws.data.counted) {
+      ws.data.counted = false;
+      this.#unauthenticated--;
+    }
+  }
+  #closed(ws, reason) {
+    clearTimeout(ws.data.helloTimer);
+    this.#uncount(ws);
+    const link = ws.data.id ? this.#links.get(ws.data.id) : undefined;
+    if (link && link.ws === ws)
+      this.#drop(link, reason || "The connection closed.");
+  }
+  #drop(link, reason, code) {
+    if (this.#links.get(link.id) !== link)
+      return;
+    this.#links.delete(link.id);
+    if (code !== undefined)
+      try {
+        link.ws.close(code, reason.slice(0, 100));
+      } catch {}
+    for (const child of [...link.children.values()])
+      child.finish(null, "SIGHUP");
+    link.children.clear();
+    this.#hooks.leave(link.id, reason);
+  }
+  #tick() {
+    const now = Date.now();
+    for (const link of [...this.#links.values()]) {
+      if (now - link.lastSeen > this.#options.lease * 2) {
+        this.#drop(link, "The host stopped answering.", RemoteClose.HostLost);
+        continue;
+      }
+      this.#post(link, { t: "ping", n: ++this.#ping });
+    }
+  }
+}
+
+// packages/sharding/src/requests.ts
+class RequestTracker {
+  #pending = new Map;
+  #maxPending;
+  #prefix;
+  #counter = 0;
+  constructor(prefix = "parent", maxPending = 1e4) {
+    if (!Number.isInteger(maxPending) || maxPending < 1)
+      throw new RangeError("maxPending must be a positive integer.");
+    this.#prefix = prefix;
+    this.#maxPending = maxPending;
+  }
+  get size() {
+    return this.#pending.size;
+  }
+  begin(options) {
+    if (this.#pending.size >= this.#maxPending)
+      throw new Error(`Too many requests waiting for a reply (${this.#maxPending}).`);
+    const id = `${this.#prefix}:${++this.#counter}`;
+    const done = new Promise((resolve) => {
+      const finish = () => {
+        const entry = this.#pending.get(id);
+        if (!entry)
+          return;
+        this.#pending.delete(id);
+        clearTimeout(entry.timer);
+        entry.cleanup?.();
+        resolve({
+          replies: entry.replies,
+          missing: [...entry.keys.keys()].filter((key) => !entry.answered.has(key))
+        });
+      };
+      const entry = {
+        keys: new Map(options.keys),
+        replies: [],
+        answered: new Set,
+        finish,
+        timer: setTimeout(finish, options.timeoutMs)
+      };
+      if (options.signal) {
+        const signal = options.signal;
+        if (signal.aborted)
+          queueMicrotask(finish);
+        else {
+          signal.addEventListener("abort", finish, { once: true });
+          entry.cleanup = () => signal.removeEventListener("abort", finish);
+        }
+      }
+      this.#pending.set(id, entry);
+      if (entry.keys.size === 0)
+        queueMicrotask(finish);
+    });
+    return { id, done };
+  }
+  answer(id, key, from, value) {
+    const entry = this.#pending.get(id);
+    if (!entry || entry.keys.get(key) !== from)
+      return false;
+    if (entry.answered.has(key))
+      return false;
+    entry.answered.add(key);
+    entry.replies.push({ key, ...value });
+    if (entry.replies.length >= entry.keys.size)
+      entry.finish();
+    return true;
+  }
+  failOwner(owner, error) {
+    for (const entry of [...this.#pending.values()]) {
+      for (const [key, keyOwner] of entry.keys)
+        if (keyOwner === owner && !entry.answered.has(key)) {
+          entry.answered.add(key);
+          entry.replies.push({ key, error });
+        }
+      if (entry.replies.length >= entry.keys.size)
+        entry.finish();
+    }
+  }
+  close() {
+    for (const entry of [...this.#pending.values()])
+      entry.finish();
+  }
+}
+
+// packages/sharding/src/cluster.ts
+var DEFAULT_MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+function payloadSize(value) {
+  if (value === undefined || value === null)
+    return 0;
+  if (typeof value === "string")
+    return Buffer.byteLength(value, "utf8");
+  if (typeof value !== "object")
+    return String(value).length;
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? 0 : Buffer.byteLength(text, "utf8");
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+var isLive = (state) => state === "starting" || state === "ready";
+
+class ClusterManager {
+  clusters = new Map;
+  shardCount = 0;
+  #options;
+  #auto;
+  #autoScaleTimer;
+  #infos = new Map;
+  #owner = new Map;
+  #startPromise;
+  #stopPromise;
+  #wasStarted = false;
+  #stopping = false;
+  #restartTimers = new Set;
+  #startTimers = new Map;
+  #pauses = new Set;
+  #readyWaiters = new Set;
+  #supervisor;
+  #tracker;
+  #coordinator;
+  #allReady = false;
+  #clusterCount = 0;
+  #identifyWaiting = new Map;
+  #remote;
+  #hostOf = new Map;
+  #lastWait = "";
+  #listeners = new Map;
+  constructor(options) {
+    if (!options.token?.trim())
+      throw new TypeError("A Discord bot token is required.");
+    if (!options.script?.trim())
+      throw new TypeError("A script path is required for clustering.");
+    if (options.autoScaleInterval !== undefined && (!Number.isInteger(options.autoScaleInterval) || options.autoScaleInterval < 1000)) {
+      throw new RangeError("autoScaleInterval must be an integer of at least 1000 milliseconds.");
+    }
+    if (options.clusterCount !== undefined && options.shardsPerCluster !== undefined)
+      throw new RangeError("Set either clusterCount or shardsPerCluster, not both.");
+    for (const [name, value] of [
+      ["clusterCount", options.clusterCount],
+      ["shardsPerCluster", options.shardsPerCluster],
+      ["maxConcurrency", options.maxConcurrency]
+    ])
+      if (value !== undefined && (!Number.isInteger(value) || value < 1))
+        throw new RangeError(`${name} must be a positive integer.`);
+    if (options.maxMessageBytes !== undefined && (!Number.isInteger(options.maxMessageBytes) || options.maxMessageBytes < 1))
+      throw new RangeError("maxMessageBytes must be a positive integer.");
+    for (const [name, value] of [
+      ["spawnInterval", options.spawnInterval],
+      ["startTimeout", options.startTimeout],
+      ["requestTimeout", options.requestTimeout]
+    ])
+      if (value !== undefined && !(value >= 0))
+        throw new RangeError(`${name} cannot be negative.`);
+    if (options.guildsPerShard !== undefined) {
+      assertGuildsPerShard(options.guildsPerShard);
+      if (typeof options.shardCount === "number")
+        throw new RangeError('guildsPerShard needs shardCount: "auto".');
+    }
+    if (options.shardIds && typeof options.shardCount === "number")
+      validateShardIds(options.shardIds, options.shardCount);
+    this.#auto = options.shardCount === "auto";
+    this.#options = { ...options };
+    this.#supervisor = new ShardSupervisor({
+      restartDelay: options.restartDelay,
+      ...options.supervisor
+    });
+    this.#tracker = new RequestTracker("parent", options.maxPendingRequests);
+    if (options.remote)
+      this.#remote = new RemoteHosts(options.remote, {
+        join: (id) => this.#emit("hostJoin", id),
+        leave: (id, reason) => this.#emit("hostLeave", id, reason),
+        error: (error) => this.#emit("error", error)
+      });
+  }
+  on(event, listener) {
+    let set = this.#listeners.get(event);
+    if (!set)
+      this.#listeners.set(event, set = new Set);
+    set.add(listener);
+    return this;
+  }
+  off(event, listener) {
+    this.#listeners.get(event)?.delete(listener);
+    return this;
+  }
+  #emit(event, ...args) {
+    for (const listener of this.#listeners.get(event) ?? [])
+      try {
+        listener(...args);
+      } catch {}
+  }
+  async fetchRecommendedShardCount() {
+    return resolveShardCount(this.#options.token, await fetchGatewayBot(this.#options.token), this.#options);
+  }
+  clusterForShard(shardId) {
+    const id = this.#owner.get(shardId);
+    return id === undefined ? undefined : this.#infos.get(id);
+  }
+  assignments() {
+    return new Map(this.#owner);
+  }
+  spawn() {
+    if (isClusterWorker())
+      return Promise.reject(new Error("A cluster worker cannot start a ClusterManager: it would fork the whole fleet again."));
+    if (this.#stopPromise)
+      return this.#stopPromise.then(() => this.spawn());
+    if (!this.#startPromise) {
+      const attempt = this.#start();
+      this.#startPromise = attempt;
+      attempt.catch(() => {
+        if (this.#startPromise === attempt)
+          this.#startPromise = undefined;
+      });
+    }
+    return this.#startPromise;
+  }
+  async#resolveGateway() {
+    const { shardCount, maxConcurrency, fetchLimits } = this.#options;
+    let info;
+    let count;
+    if (shardCount === "auto" || shardCount === undefined) {
+      info = await fetchGatewayBot(this.#options.token);
+      count = await resolveShardCount(this.#options.token, info, this.#options);
+    } else if (fetchLimits)
+      try {
+        info = await fetchGatewayBot(this.#options.token);
+      } catch (error) {
+        this.#emit("error", error instanceof Error ? error : new Error(String(error)));
+      }
+    const limit = info?.sessionStartLimit;
+    return {
+      count: count ?? shardCount,
+      maxConcurrency: Math.min(maxConcurrency ?? limit?.maxConcurrency ?? 1, limit?.maxConcurrency ?? Number.POSITIVE_INFINITY),
+      ...limit ? {
+        budget: {
+          total: limit.total,
+          remaining: limit.remaining,
+          resetAfter: limit.resetAfter
+        }
+      } : {}
+    };
+  }
+  async#start() {
+    const { count, maxConcurrency, budget } = await this.#resolveGateway();
+    if (this.#stopping)
+      return;
+    const ids = this.#options.shardIds ?? Array.from({ length: count }, (_, i) => i);
+    validateShardIds(ids, count);
+    const clusterCount = this.#options.clusterCount ?? (this.#options.shardsPerCluster ? Math.ceil(ids.length / this.#options.shardsPerCluster) : cpus().length);
+    const chunks = allocateShards(ids, clusterCount);
+    assertCompleteAllocation(chunks, ids);
+    const placement = await this.#placeHosts().catch((error) => {
+      if (this.#stopping)
+        return;
+      throw error;
+    });
+    if (!placement || this.#stopping)
+      return;
+    this.shardCount = count;
+    this.#wasStarted = true;
+    this.#owner.clear();
+    this.#infos.clear();
+    const identify = this.#options.identify;
+    this.#coordinator = identify?.coordinate === false ? undefined : new IdentifyCoordinator({
+      maxConcurrency,
+      interval: identify?.interval,
+      holdTimeout: identify?.holdTimeout,
+      budget,
+      onBudgetWait: (wait) => {
+        const key = `${wait.shardId}:${Math.round(wait.waitMs / 1000)}`;
+        if (key === this.#lastWait)
+          return;
+        this.#lastWait = key;
+        this.#emit("identifyWait", wait);
+      }
+    });
+    const active = chunks.map((shards, id) => ({ id, shards })).filter((chunk) => chunk.shards.length > 0);
+    this.#clusterCount = active.length;
+    this.#hostOf.clear();
+    for (const chunk of active)
+      this.#hostOf.set(chunk.id, placement[chunk.id % placement.length]);
+    for (const [index, chunk] of active.entries()) {
+      if (this.#stopping)
+        return;
+      for (const shard of chunk.shards)
+        this.#owner.set(shard, chunk.id);
+      this.#launch(chunk.id, chunk.shards);
+      const gap = this.#options.spawnInterval ?? 500;
+      if (index < active.length - 1 && gap > 0)
+        await this.#pause(gap);
+    }
+    if (this.#stopping)
+      return;
+    if (this.#options.waitForReady)
+      await this.ready();
+    if (this.#options.autoScaleInterval && this.#options.autoScaleInterval > 0) {
+      this.#autoScaleTimer = setInterval(() => {
+        this.checkAutoScale();
+      }, this.#options.autoScaleInterval);
+    }
+  }
+  async#placeHosts() {
+    const remote = this.#remote;
+    const options = this.#options.remote;
+    if (!remote || !options)
+      return ["local"];
+    remote.start();
+    try {
+      await remote.waitFor(options.hosts, options.minHosts ?? 1, options.joinTimeout ?? 60000);
+    } catch (error) {
+      remote.stop();
+      throw error;
+    }
+    const ids = options.hosts ?? remote.connected();
+    return options.local ? ["local", ...ids] : ids;
+  }
+  get remotePort() {
+    return this.#remote?.port;
+  }
+  hosts() {
+    return this.#remote?.status(this.#options.remote?.hosts) ?? [];
+  }
+  #pause(ms) {
+    return new Promise((resolve) => {
+      const wake = () => {
+        clearTimeout(timer);
+        this.#pauses.delete(wake);
+        resolve();
+      };
+      const timer = setTimeout(wake, ms);
+      this.#pauses.add(wake);
+    });
+  }
+  #launch(id, shards) {
+    const contract = {
+      SHARD_LIST: shards.join(","),
+      SHARD_COUNT: this.shardCount.toString(),
+      CLUSTER_ID: id.toString(),
+      CLUSTER_COUNT: this.#clusterCount.toString(),
+      LUNIBEE_SHARD_BUS: "ipc",
+      [WORKER_MARKER]: "1",
+      LUNIBEE_IDENTIFY: this.#coordinator ? "coordinated" : "local"
+    };
+    const host = this.#hostOf.get(id) ?? "local";
+    const env = {
+      ...process.env,
+      ...contract
+    };
+    const child = host !== "local" && this.#remote ? this.#remote.createChild(host, id, contract) : this.#options.fork ? this.#options.fork(this.#options.script, env) : fork(this.#options.script, [], {
+      env
+    });
+    const known = this.#infos.get(id);
+    const info = known ?? {
+      id,
+      host,
+      process: child,
+      shards,
+      state: "starting",
+      restarts: 0,
+      startedAt: Date.now()
+    };
+    info.process = child;
+    info.state = "starting";
+    info.startedAt = Date.now();
+    info.readyAt = undefined;
+    this.#infos.set(id, info);
+    this.clusters.set(id, info);
+    this.#allReady = false;
+    child.on("message", (frame) => this.#onFrame(info, child, frame));
+    child.once("exit", (code, signal) => this.#onExit(info, child, code, signal));
+    const timeout = this.#options.startTimeout;
+    if (timeout) {
+      const timer = setTimeout(() => {
+        this.#startTimers.delete(id);
+        if (info.process !== child || info.state !== "starting")
+          return;
+        this.#emit("clusterStartTimeout", info);
+        try {
+          child.kill("SIGKILL");
+        } catch {}
+      }, timeout);
+      timer.unref?.();
+      this.#startTimers.set(id, timer);
+    }
+    this.#emit("clusterSpawn", info);
+    return info;
+  }
+  #onExit(info, child, code, signal) {
+    if (info.process !== child)
+      return;
+    child.removeAllListeners("message");
+    this.#clearStartTimer(info.id);
+    this.#coordinator?.drop(info.id, `Cluster ${info.id} exited.`);
+    this.#identifyWaiting.delete(info.id);
+    this.#tracker.failOwner(info.id, `Cluster ${info.id} exited.`);
+    this.clusters.delete(info.id);
+    this.#allReady = false;
+    try {
+      this.#options.onClusterExit?.(info, code, signal);
+    } catch {}
+    const expected = this.#stopping || info.state === "stopping" || info.state === "stopped";
+    this.#emit("clusterExit", info, code, signal, expected);
+    if (expected) {
+      info.state = "stopped";
+      return;
+    }
+    this.#announceDown(info.id, info.shards);
+    if (this.#options.restartOnExit === false) {
+      info.state = "failed";
+      this.#checkReady();
+      return;
+    }
+    const delay = this.#supervisor.next(info.id);
+    if (delay === null) {
+      info.state = "failed";
+      try {
+        this.#options.onGiveUp?.(info);
+      } catch {}
+      this.#emit("clusterGiveUp", info);
+      this.#checkReady();
+      if (this.#options.reassignOnGiveUp)
+        this.#reassign(info);
+      return;
+    }
+    info.state = "restarting";
+    info.restarts++;
+    this.#emit("clusterRestart", info, { delay, attempt: info.restarts });
+    if (info.restarts >= 3)
+      this.#emit("clusterUnstable", info, {
+        attempt: info.restarts,
+        delay
+      });
+    const timer = setTimeout(() => {
+      this.#restartTimers.delete(timer);
+      if (this.#stopping || info.state !== "restarting")
+        return;
+      this.#launch(info.id, info.shards);
+    }, delay);
+    timer.unref?.();
+    this.#restartTimers.add(timer);
+  }
+  async#reassign(failed) {
+    const shardIds = [...failed.shards];
+    const target = [...this.#infos.values()].filter((cluster) => cluster.state === "ready").sort((a, b) => a.shards.length - b.shards.length)[0];
+    if (!target) {
+      this.#emit("error", new Error(`No ready cluster can take over shards [${shardIds}] of cluster ${failed.id}.`));
+      return;
+    }
+    try {
+      await this.requestCluster(target.id, REQUEST_ASSIGN, { shardIds }, { timeoutMs: this.#options.startTimeout ?? 120000 });
+    } catch (error) {
+      this.#emit("error", new Error(`Cluster ${target.id} could not take over shards [${shardIds}]: ${error instanceof Error ? error.message : String(error)}`));
+      return;
+    }
+    if (this.#stopping || failed.state !== "failed")
+      return;
+    for (const shard of shardIds)
+      this.#owner.set(shard, target.id);
+    target.shards.push(...shardIds);
+    failed.shards = [];
+    this.#emit("shardsReassigned", {
+      shardIds,
+      from: failed.id,
+      to: target.id
+    });
+  }
+  #clearStartTimer(id) {
+    const timer = this.#startTimers.get(id);
+    if (timer)
+      clearTimeout(timer);
+    this.#startTimers.delete(id);
+  }
+  #sendFrame(cluster, frame) {
+    const child = cluster.process;
+    if (!isLive(cluster.state) || typeof child.send !== "function" || !child.connected)
+      return false;
+    try {
+      child.send(frame);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  #announceDown(exited, shards) {
+    for (const [id, cluster] of this.clusters)
+      if (id !== exited)
+        this.#sendFrame(cluster, { [PEER_DOWN_FRAME]: shards });
+  }
+  #onFrame(info, child, frame) {
+    if (info.process !== child)
+      return;
+    if (!frame || typeof frame !== "object")
+      return;
+    if (BUS_FRAME in frame) {
+      this.#onBus(info, frame[BUS_FRAME]);
+      return;
+    }
+    if (CLUSTER_FRAME in frame) {
+      const body = parseChildFrame(frame[CLUSTER_FRAME]);
+      if (body)
+        this.#onControl(info, child, body);
+      else
+        this.#emit("error", new Error(`Cluster ${info.id} sent a malformed control frame.`));
+    }
+  }
+  #onControl(info, child, frame) {
+    switch (frame.kind) {
+      case "ready": {
+        if (!frame.shardIds.every((id) => info.shards.includes(id))) {
+          this.#emit("error", new Error(`Cluster ${info.id} reported shards it does not own: [${frame.shardIds}].`));
+          return;
+        }
+        this.#clearStartTimer(info.id);
+        info.state = "ready";
+        info.readyAt = info.lastReadyAt = Date.now();
+        this.#emit("clusterReady", info);
+        this.#checkReady();
+        return;
+      }
+      case "identify": {
+        const reply = (body) => {
+          if (info.process === child)
+            this.#sendFrame(info, { [CLUSTER_FRAME]: body });
+        };
+        if (!this.#coordinator) {
+          reply({
+            kind: "identify-deny",
+            id: frame.id,
+            error: "IDENTIFY coordination is off."
+          });
+          return;
+        }
+        if (!info.shards.includes(frame.shardId)) {
+          reply({
+            kind: "identify-deny",
+            id: frame.id,
+            error: `Shard ${frame.shardId} does not belong to cluster ${info.id}.`
+          });
+          return;
+        }
+        let waiting = this.#identifyWaiting.get(info.id);
+        if (!waiting)
+          this.#identifyWaiting.set(info.id, waiting = new Set);
+        if (waiting.has(frame.shardId)) {
+          reply({
+            kind: "identify-deny",
+            id: frame.id,
+            error: `Shard ${frame.shardId} is already waiting for a slot.`
+          });
+          return;
+        }
+        waiting.add(frame.shardId);
+        const settled = () => {
+          waiting.delete(frame.shardId);
+        };
+        this.#coordinator.acquire(info.id, frame.shardId).then(() => {
+          settled();
+          reply({ kind: "identify-grant", id: frame.id });
+        }, (error) => {
+          settled();
+          reply({
+            kind: "identify-deny",
+            id: frame.id,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        });
+        return;
+      }
+      case "identify-done":
+        this.#coordinator?.release(info.id, frame.shardId);
+        return;
+      case "reply": {
+        const tooBig = frame.error === undefined && this.#tooBig(frame.result);
+        this.#tracker.answer(frame.id, `c:${info.id}`, info.id, {
+          ...frame.error !== undefined ? { error: frame.error } : tooBig ? {
+            error: `Cluster ${info.id} answered with more than ${this.#maxBytes} bytes.`
+          } : { result: frame.result }
+        });
+        return;
+      }
+      case "health":
+        if (this.#tooBig(frame.report)) {
+          this.#emit("error", new Error(`Cluster ${info.id} sent a health report of more than ${this.#maxBytes} bytes.`));
+          return;
+        }
+        info.report = frame.report;
+        return;
+    }
+  }
+  get #maxBytes() {
+    return this.#options.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+  }
+  #tooBig(value) {
+    return payloadSize(value) > this.#maxBytes;
+  }
+  #assertSize(data, what) {
+    if (this.#tooBig(data))
+      throw new RangeError(`${what} is larger than maxMessageBytes (${this.#maxBytes}).`);
+  }
+  #onBus(from, raw) {
+    const message = raw;
+    if (!message || typeof message !== "object" || typeof message.type !== "string" || typeof message.source !== "number" || message.target !== null && !Number.isInteger(message.target))
+      return;
+    if (this.#tooBig(message.data)) {
+      this.#emit("error", new Error(`Cluster ${from.id} sent a shard-bus message of more than ${this.#maxBytes} bytes; it was not relayed.`));
+      return;
+    }
+    const frame = { [BUS_FRAME]: message };
+    if (message.target === PARENT_ID) {
+      const reply = message.data;
+      if (message.type === REPLY_TYPE && reply && typeof reply.requestId === "string")
+        this.#tracker.answer(reply.requestId, `s:${message.source}`, from.id, reply.error !== undefined ? { error: String(reply.error) } : { result: reply.result });
+      return;
+    }
+    if (message.target === null) {
+      for (const [id, cluster] of this.clusters)
+        if (id !== from.id)
+          this.#sendFrame(cluster, frame);
+      return;
+    }
+    const owner = this.clusterForShard(message.target);
+    if (!owner || owner.id === from.id)
+      return;
+    if (!this.#sendFrame(owner, frame))
+      this.#sendFrame(from, {
+        [PEER_DOWN_FRAME]: [message.target]
+      });
+  }
+  async request(shardId, type, data, options = {}) {
+    this.#assertSize(data, "The request data");
+    const owner = this.clusterForShard(shardId);
+    if (!owner)
+      throw new RangeError(`Shard ${shardId} is not part of this deployment.`);
+    const { id, done } = this.#tracker.begin({
+      keys: new Map([[`s:${shardId}`, owner.id]]),
+      timeoutMs: options.timeoutMs ?? this.#options.requestTimeout ?? 5000,
+      signal: options.signal
+    });
+    const sent = this.#sendFrame(owner, {
+      [BUS_FRAME]: {
+        source: PARENT_ID,
+        target: shardId,
+        type,
+        data,
+        id,
+        expectsReply: true
+      }
+    });
+    if (!sent) {
+      this.#tracker.failOwner(owner.id, `Shard ${shardId} is down: cluster ${owner.id} is ${owner.state}.`);
+    }
+    const { replies } = await done;
+    const reply = replies[0];
+    if (!reply)
+      throw new Error(`Shard ${shardId} did not reply to "${type}" in time.`);
+    if (reply.error !== undefined)
+      throw new Error(reply.error);
+    return reply.result;
+  }
+  async broadcast(type, data, options = {}) {
+    this.#assertSize(data, "The request data");
+    const keys = new Map;
+    const down = [];
+    for (const [shard, clusterId] of this.#owner) {
+      const cluster = this.#infos.get(clusterId);
+      if (cluster && isLive(cluster.state))
+        keys.set(`s:${shard}`, clusterId);
+      else
+        down.push(shard);
+    }
+    const { id, done } = this.#tracker.begin({
+      keys,
+      timeoutMs: options.timeoutMs ?? this.#options.requestTimeout ?? 5000,
+      signal: options.signal
+    });
+    const frame = {
+      [BUS_FRAME]: {
+        source: PARENT_ID,
+        target: null,
+        type,
+        data,
+        id,
+        expectsReply: true
+      }
+    };
+    for (const cluster of this.clusters.values())
+      if (!this.#sendFrame(cluster, frame))
+        this.#tracker.failOwner(cluster.id, `Cluster ${cluster.id} is ${cluster.state}.`);
+    const { replies, missing } = await done;
+    return {
+      replies: replies.map((reply) => ({
+        shardId: Number(reply.key.slice(2)),
+        ...reply.error !== undefined ? { error: reply.error } : { result: reply.result }
+      })),
+      missing: [
+        ...down,
+        ...missing.map((key) => Number(key.slice(2)))
+      ].sort((a, b) => a - b)
+    };
+  }
+  async requestCluster(clusterId, type, data, options = {}) {
+    this.#assertSize(data, "The request data");
+    const cluster = this.#infos.get(clusterId);
+    if (!cluster)
+      throw new RangeError(`Cluster ${clusterId} does not exist.`);
+    const { id, done } = this.#tracker.begin({
+      keys: new Map([[`c:${clusterId}`, clusterId]]),
+      timeoutMs: options.timeoutMs ?? this.#options.requestTimeout ?? 5000,
+      signal: options.signal
+    });
+    if (!this.#sendFrame(cluster, {
+      [CLUSTER_FRAME]: { kind: "request", id, type, data }
+    }))
+      this.#tracker.failOwner(clusterId, `Cluster ${clusterId} is ${cluster.state}.`);
+    const { replies } = await done;
+    const reply = replies[0];
+    if (!reply)
+      throw new Error(`Cluster ${clusterId} did not reply to "${type}" in time.`);
+    if (reply.error !== undefined)
+      throw new Error(reply.error);
+    return reply.result;
+  }
+  ready(timeoutMs) {
+    if (this.#isReady())
+      return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        resolve: () => {
+          if (waiter.timer)
+            clearTimeout(waiter.timer);
+          this.#readyWaiters.delete(waiter);
+          resolve();
+        },
+        reject: (error) => {
+          if (waiter.timer)
+            clearTimeout(waiter.timer);
+          this.#readyWaiters.delete(waiter);
+          reject(error);
+        }
+      };
+      if (timeoutMs !== undefined)
+        waiter.timer = setTimeout(() => waiter.reject(new Error(`Clusters were not all ready within ${timeoutMs}ms.`)), timeoutMs);
+      this.#readyWaiters.add(waiter);
+    });
+  }
+  #isReady() {
+    if (this.#infos.size === 0)
+      return false;
+    for (const cluster of this.#infos.values())
+      if (cluster.state !== "ready")
+        return false;
+    return true;
+  }
+  #checkReady() {
+    if (!this.#isReady())
+      return;
+    for (const waiter of [...this.#readyWaiters])
+      waiter.resolve();
+    if (!this.#allReady) {
+      this.#allReady = true;
+      this.#emit("ready");
+    }
+  }
+  health() {
+    const now = Date.now();
+    const clusters = [...this.#infos.values()].sort((a, b) => a.id - b.id).map((cluster) => ({
+      id: cluster.id,
+      state: cluster.state,
+      ...cluster.process.pid !== undefined && isLive(cluster.state) ? { pid: cluster.process.pid } : {},
+      host: cluster.host,
+      shardIds: [...cluster.shards],
+      uptimeMs: isLive(cluster.state) ? now - cluster.startedAt : 0,
+      restarts: cluster.restarts,
+      startedAt: cluster.startedAt,
+      ...cluster.readyAt !== undefined ? { readyAt: cluster.readyAt } : {},
+      ...cluster.lastReadyAt !== undefined ? { lastReadyAt: cluster.lastReadyAt } : {},
+      shards: cluster.report?.shards ?? [],
+      ...cluster.report?.metrics ? { metrics: cluster.report.metrics } : {},
+      ...cluster.report ? { reportedAt: cluster.report.reportedAt } : {}
+    }));
+    const missingShards = [...this.#owner].filter(([, id]) => this.#infos.get(id)?.state !== "ready").map(([shard]) => shard).sort((a, b) => a - b);
+    const states = clusters.map((cluster) => cluster.state);
+    const state = this.#stopping ? "stopping" : clusters.length === 0 ? this.#wasStarted ? "stopped" : "idle" : states.every((s) => s === "stopped") ? "stopped" : states.every((s) => s === "ready") ? "ready" : states.some((s) => s === "restarting" || s === "failed") ? "degraded" : "starting";
+    return {
+      state,
+      totalShards: this.shardCount,
+      clusters,
+      readyClusters: states.filter((s) => s === "ready").length,
+      missingShards
+    };
+  }
+  async refreshHealth(options = {}) {
+    await Promise.all([...this.clusters.values()].map(async (cluster) => {
+      try {
+        cluster.report = await this.requestCluster(cluster.id, REQUEST_HEALTH, { metrics: options.metrics === true }, { timeoutMs: options.timeoutMs ?? 2000 });
+      } catch {}
+    }));
+    return this.health();
+  }
+  async checkAutoScale() {
+    if (!this.#auto)
+      return;
+    try {
+      const recommended = await this.fetchRecommendedShardCount();
+      if (recommended !== this.shardCount) {
+        await this.respawn(recommended);
+      }
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      this.#options.onAutoScaleError?.(normalized);
+    }
+  }
+  async respawn(newShardCount) {
+    this.#options.shardCount = newShardCount;
+    await this.#stop(this.#options.shutdownTimeout ?? 5000, true);
+    this.#supervisor.reset();
     await this.spawn();
   }
-  async shutdownAll(timeoutMs = this.#options.shutdownTimeout ?? 5000) {
+  shutdownAll(timeoutMs = this.#options.shutdownTimeout ?? 5000) {
+    return this.#stop(timeoutMs, false);
+  }
+  #stop(timeoutMs, keepRemote) {
+    this.#stopPromise ??= this.#shutdown(timeoutMs, keepRemote).finally(() => {
+      this.#stopPromise = undefined;
+    });
+    return this.#stopPromise;
+  }
+  async#shutdown(timeoutMs, keepRemote) {
     this.#stopping = true;
-    this.#clearRestartTimers();
-    if (this.#autoScaleTimer) {
-      clearInterval(this.#autoScaleTimer);
-      this.#autoScaleTimer = undefined;
-    }
+    this.#halt();
+    await this.#startPromise?.catch(() => {
+      return;
+    });
     await Promise.all([...this.clusters.values()].map((cluster) => this.#shutdownCluster(cluster, timeoutMs)));
+    for (const cluster of this.#infos.values())
+      cluster.state = "stopped";
     this.clusters.clear();
-    this.#spawned = false;
+    this.#startPromise = undefined;
+    if (!keepRemote)
+      this.#remote?.stop();
     this.#stopping = false;
   }
-  #clearRestartTimers() {
+  #halt() {
     for (const timer of this.#restartTimers)
       clearTimeout(timer);
     this.#restartTimers.clear();
+    for (const id of [...this.#startTimers.keys()])
+      this.#clearStartTimer(id);
+    for (const wake of [...this.#pauses])
+      wake();
+    if (this.#autoScaleTimer) {
+      clearInterval(this.#autoScaleTimer);
+      this.#autoScaleTimer = undefined;
+    }
+    this.#coordinator?.close();
+    this.#coordinator = undefined;
+    this.#remote?.abortWaits();
+    this.#tracker.close();
+    for (const waiter of [...this.#readyWaiters])
+      waiter.reject(new Error("The cluster manager is stopping."));
   }
   async#shutdownCluster(cluster, timeoutMs) {
     const child = cluster.process;
+    cluster.state = "stopping";
     if (child.exitCode !== null || child.signalCode !== null)
       return;
     await new Promise((resolve) => {
@@ -1773,24 +3423,293 @@ class ClusterManager {
   }
   killAll() {
     this.#stopping = true;
-    this.#clearRestartTimers();
-    if (this.#autoScaleTimer) {
-      clearInterval(this.#autoScaleTimer);
-      this.#autoScaleTimer = undefined;
-    }
-    for (const cluster of this.clusters.values()) {
+    this.#halt();
+    for (const cluster of this.#infos.values()) {
+      cluster.state = "stopped";
       try {
         cluster.process.kill();
       } catch {}
     }
     this.clusters.clear();
-    this.#spawned = false;
+    this.#startPromise = undefined;
+    this.#remote?.stop();
     this.#stopping = false;
   }
 }
+// packages/sharding/src/host.ts
+import { fork as fork2 } from "child_process";
+class ClusterHost {
+  #options;
+  #running = new Map;
+  #listeners = new Map;
+  #socket;
+  #lease = 15000;
+  #lastRx = 0;
+  #watchdog;
+  #retry;
+  #delay;
+  #closed = true;
+  #connected = false;
+  #firstConnect;
+  constructor(options) {
+    if (!HOST_ID.test(options.id))
+      throw new RangeError("id must be 1-64 letters, digits, '.', '_' or '-'.");
+    if (!options.secret || options.secret.length < 16)
+      throw new RangeError("secret must be at least 16 characters.");
+    if (!options.script?.trim())
+      throw new TypeError("A worker script path is required.");
+    let url;
+    try {
+      url = new URL(options.url);
+    } catch {
+      throw new TypeError("url must be an absolute ws:// or wss:// URL.");
+    }
+    if (url.protocol !== "ws:" && url.protocol !== "wss:")
+      throw new TypeError("url must start with ws:// or wss://.");
+    if (url.username || url.password)
+      throw new TypeError("url must not contain credentials.");
+    if (url.protocol === "ws:" && !options.allowInsecure && !isLoopbackHost(url.hostname))
+      throw new TypeError("url must use wss:// to reach another machine (allowInsecure: true overrides this for a network you fully trust).");
+    this.#options = options;
+    this.#delay = options.reconnectDelay ?? 1000;
+  }
+  get connected() {
+    return this.#connected;
+  }
+  clusters() {
+    return [...this.#running.keys()].sort((a, b) => a - b);
+  }
+  on(event, listener) {
+    let set = this.#listeners.get(event);
+    if (!set)
+      this.#listeners.set(event, set = new Set);
+    set.add(listener);
+    return this;
+  }
+  off(event, listener) {
+    this.#listeners.get(event)?.delete(listener);
+    return this;
+  }
+  #emit(event, ...args) {
+    for (const listener of this.#listeners.get(event) ?? [])
+      try {
+        listener(...args);
+      } catch {}
+  }
+  connect() {
+    if (!this.#closed)
+      return Promise.resolve();
+    this.#closed = false;
+    return new Promise((resolve, reject) => {
+      this.#firstConnect = { resolve, reject };
+      this.#open();
+    });
+  }
+  close() {
+    this.#closed = true;
+    if (this.#retry)
+      clearTimeout(this.#retry);
+    this.#retry = undefined;
+    this.#fence();
+    if (this.#watchdog)
+      clearInterval(this.#watchdog);
+    this.#watchdog = undefined;
+    this.#connected = false;
+    const socket = this.#socket;
+    this.#socket = undefined;
+    this.#firstConnect?.reject(new Error("The host was closed."));
+    this.#firstConnect = undefined;
+    if (!socket || socket.readyState === WebSocket.CLOSED)
+      return Promise.resolve();
+    return new Promise((resolve) => {
+      socket.addEventListener("close", () => resolve(), { once: true });
+      try {
+        socket.close(1000, "Host closed.");
+      } catch {
+        resolve();
+      }
+    });
+  }
+  #open() {
+    const socket = new WebSocket(this.#options.url);
+    this.#socket = socket;
+    socket.addEventListener("message", (event) => this.#message(socket, event.data));
+    socket.addEventListener("error", () => {});
+    socket.addEventListener("close", (event) => {
+      if (this.#socket === socket)
+        this.#lost(event.code, event.reason);
+    });
+  }
+  #send(socket, message) {
+    if (socket.readyState !== WebSocket.OPEN)
+      return false;
+    try {
+      socket.send(JSON.stringify(message));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  #message(socket, data) {
+    if (this.#socket !== socket)
+      return;
+    const message = parseToHost(data);
+    if (!message) {
+      this.#emit("error", new Error("The coordinator sent a malformed frame."));
+      return;
+    }
+    this.#lastRx = Date.now();
+    switch (message.t) {
+      case "challenge":
+        if (message.version !== REMOTE_PROTOCOL_VERSION) {
+          socket.close(RemoteClose.VersionMismatch, "Protocol version mismatch.");
+          return;
+        }
+        this.#send(socket, {
+          t: "hello",
+          id: this.#options.id,
+          mac: signChallenge(this.#options.secret, message.nonce, this.#options.id),
+          version: REMOTE_PROTOCOL_VERSION
+        });
+        return;
+      case "welcome":
+        this.#lease = message.leaseMs;
+        this.#connected = true;
+        this.#delay = this.#options.reconnectDelay ?? 1000;
+        this.#startWatchdog();
+        this.#firstConnect?.resolve();
+        this.#firstConnect = undefined;
+        this.#emit("connected");
+        return;
+      case "ping":
+        this.#send(socket, { t: "pong", n: message.n });
+        return;
+      case "bye":
+        this.#fence();
+        return;
+      case "spawn":
+        this.#spawn(socket, message.cluster, message.epoch, message.env);
+        return;
+      case "frame": {
+        const run = this.#running.get(message.cluster);
+        if (run?.epoch === message.epoch && run.child.connected)
+          try {
+            run.child.send(message.frame);
+          } catch {}
+        return;
+      }
+      case "kill": {
+        const run = this.#running.get(message.cluster);
+        if (run?.epoch === message.epoch && KILL_SIGNALS.has(message.signal))
+          try {
+            run.child.kill(message.signal);
+          } catch {}
+        return;
+      }
+    }
+  }
+  #spawn(socket, cluster, epoch, env) {
+    const reply = (message) => {
+      if (this.#socket === socket)
+        this.#send(socket, message);
+    };
+    if (this.#running.has(cluster)) {
+      reply({
+        t: "error",
+        cluster,
+        epoch,
+        message: `Cluster ${cluster} is already running here.`
+      });
+      return;
+    }
+    let child;
+    try {
+      const forkWorker = this.#options.fork ?? defaultFork;
+      child = forkWorker(this.#options.script, {
+        ...process.env,
+        ...env
+      });
+    } catch (error) {
+      reply({
+        t: "error",
+        cluster,
+        epoch,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      return;
+    }
+    this.#running.set(cluster, { epoch, child });
+    child.on("message", (frame) => reply({ t: "frame", cluster, epoch, frame }));
+    child.once("exit", (code, signal) => {
+      if (this.#running.get(cluster)?.child === child)
+        this.#running.delete(cluster);
+      this.#emit("clusterExit", cluster, code, signal);
+      reply({ t: "exit", cluster, epoch, code, signal });
+    });
+    child.on("error", (error) => this.#emit("error", error instanceof Error ? error : new Error(String(error))));
+    reply({
+      t: "spawned",
+      cluster,
+      epoch,
+      ...child.pid ? { pid: child.pid } : {}
+    });
+    this.#emit("clusterSpawn", cluster);
+  }
+  #fence() {
+    for (const { child } of [...this.#running.values()])
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+  }
+  #startWatchdog() {
+    if (this.#watchdog)
+      clearInterval(this.#watchdog);
+    this.#lastRx = Date.now();
+    this.#watchdog = setInterval(() => {
+      if (Date.now() - this.#lastRx > this.#lease) {
+        this.#fence();
+        this.#socket?.close(RemoteClose.HostLost, "Coordinator silent.");
+      }
+    }, Math.max(10, Math.floor(this.#lease / 3)));
+    this.#watchdog.unref?.();
+  }
+  #lost(code, reason) {
+    if (this.#watchdog)
+      clearInterval(this.#watchdog);
+    this.#watchdog = undefined;
+    this.#socket = undefined;
+    const wasConnected = this.#connected;
+    this.#connected = false;
+    this.#fence();
+    if (wasConnected)
+      this.#emit("disconnected", { code, reason });
+    if (this.#closed)
+      return;
+    const refused = code === RemoteClose.AuthFailed || code === RemoteClose.UnknownHost || code === RemoteClose.DuplicateHost || code === RemoteClose.VersionMismatch;
+    const first = this.#firstConnect;
+    if (first) {
+      this.#firstConnect = undefined;
+      this.#closed = true;
+      first.reject(new Error(`The coordinator refused this host (${code}${reason ? `: ${reason}` : ""}).`));
+      return;
+    }
+    if (refused)
+      this.#emit("error", new Error(`The coordinator refused this host (${code}: ${reason}).`));
+    const wait = Math.round(this.#delay * (1 + Math.random() * 0.2));
+    this.#delay = Math.min(this.#options.maxReconnectDelay ?? 30000, this.#delay * 2);
+    this.#retry = setTimeout(() => {
+      this.#retry = undefined;
+      if (!this.#closed)
+        this.#open();
+    }, wait);
+  }
+}
+function defaultFork(script, env) {
+  return fork2(script, [], { env });
+}
 
 // packages/sharding/src/index.ts
-var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function needsConnection(gateway) {
   return gateway.state === "CONNECT" /* Connect */ || gateway.state === "RECONNECT" /* Reconnect */ || gateway.state === "CLOSED" /* Closed */;
 }
@@ -1824,9 +3743,17 @@ class ShardManager {
   static IDENTIFY_INTERVAL = 5000;
   shards = new Map;
   get shardCount() {
-    return this.shards.size;
+    return this.#resolved ? this.#total : 0;
+  }
+  get shardIds() {
+    return [...this.shards.keys()].sort((a, b) => a - b);
   }
   #options;
+  #ids;
+  #gate;
+  #worker;
+  #lifecycle = new Map;
+  #announced = false;
   #resolved = false;
   #destroyed = false;
   #auto;
@@ -1839,9 +3766,30 @@ class ShardManager {
       throw new TypeError("A Discord bot token is required.");
     if (!Array.isArray(options.intents))
       throw new TypeError("Gateway intents must be an array, e.g. [GatewayIntentBits.Guilds].");
-    const count = options.shardCount === "auto" || options.shardCount === undefined ? 1 : options.shardCount;
+    const context = options.cluster === false ? null : options.cluster ?? readClusterContext();
+    if (context) {
+      if (options.shardCount === "auto")
+        throw new RangeError(`shardCount "auto" is the ClusterManager's decision inside a cluster worker.`);
+      if (options.shardCount !== undefined && options.shardCount !== context.shardCount)
+        throw new RangeError(`shardCount ${options.shardCount} differs from the cluster's ${context.shardCount}.`);
+      if (options.autoScaleInterval !== undefined)
+        throw new TypeError("autoScaleInterval belongs to ClusterManager inside a cluster worker.");
+      if (options.shardIds && !options.shardIds.every((id) => context.shardIds.includes(id)))
+        throw new RangeError("shardIds must be a subset of the cluster's own shards.");
+    }
+    const count = context ? context.shardCount : options.shardCount === "auto" || options.shardCount === undefined ? 1 : options.shardCount;
     if (!Number.isInteger(count) || count < 1)
       throw new RangeError("Shard count must be a positive integer.");
+    if (options.guildsPerShard !== undefined) {
+      assertGuildsPerShard(options.guildsPerShard);
+      if (options.shardCount !== "auto")
+        throw new RangeError('guildsPerShard needs shardCount: "auto".');
+    }
+    this.#ids = options.shardIds ?? context?.shardIds;
+    if (this.#ids && options.shardCount !== "auto")
+      validateShardIds(this.#ids, count);
+    this.#worker = options.worker === false ? undefined : options.worker ?? (context && options.cluster === undefined ? ClusterWorker.current() : undefined);
+    this.#gate = options.identify === false ? undefined : options.identify ?? (context?.coordinatedIdentify ? this.#worker?.identifyGate : undefined);
     if (options.autoScaleInterval !== undefined && (!Number.isInteger(options.autoScaleInterval) || options.autoScaleInterval < 1000))
       throw new RangeError("autoScaleInterval must be an integer of at least 1000 milliseconds.");
     if (options.spawnDelay !== undefined && (!Number.isFinite(options.spawnDelay) || options.spawnDelay < 0))
@@ -1856,11 +3804,19 @@ class ShardManager {
       spawnDelay: ShardManager.IDENTIFY_INTERVAL,
       ...options
     };
+    this.#worker?.onRequest(REQUEST_HEALTH, (data) => this.report(data?.metrics === true));
+    this.#worker?.onRequest(REQUEST_ASSIGN, async (data) => {
+      const ids = data?.shardIds;
+      if (!Array.isArray(ids))
+        throw new TypeError("shardIds must be an array.");
+      await this.addShards(ids);
+      return { shardIds: ids };
+    });
     if (options.shardCount !== "auto")
       this.#initialize(count);
   }
   async fetchRecommendedShardCount() {
-    return (await this.fetchGatewayInfo()).shards;
+    return resolveShardCount(this.#options.token, await this.fetchGatewayInfo(), this.#options);
   }
   async fetchGatewayInfo() {
     const info = await fetchGatewayBot(this.#options.token);
@@ -1873,8 +3829,63 @@ class ShardManager {
       this.#autoScaleTimer = undefined;
     }
     await this.#ensureInitialized();
+    await this.#start([...this.shards].filter(([, gateway]) => needsConnection(gateway)).map(([id]) => id));
+    if (this.#options.autoScaleInterval && !this.#autoScaleTimer) {
+      this.#autoScaleTimer = setInterval(() => {
+        this.checkAutoScale();
+      }, this.#options.autoScaleInterval);
+    }
+  }
+  async addShards(shardIds) {
+    await this.#ensureInitialized();
+    validateShardIds(shardIds, this.#total);
+    for (const id of shardIds)
+      if (this.shards.has(id))
+        throw new RangeError(`Shard ${id} is already owned.`);
+    for (const id of shardIds)
+      this.shards.set(id, this.#createShard(id, this.#total));
+    if (this.#ids)
+      this.#ids = [...this.#ids, ...shardIds];
+    this.#announced = false;
+    try {
+      await this.#start([...shardIds], false);
+    } catch (error) {
+      for (const id of shardIds) {
+        this.shards.get(id)?.close();
+        this.shards.delete(id);
+        this.#lifecycle.delete(id);
+      }
+      if (this.#ids)
+        this.#ids = this.#ids.filter((id) => !shardIds.includes(id));
+      throw error;
+    }
+  }
+  async#start(ids, destroyOnFailure = true) {
+    const gate = this.#gate;
+    if (gate) {
+      const timeout = this.#options.handshakeTimeout ?? 15000;
+      const results = await Promise.allSettled(ids.map(async (id) => {
+        const gateway = this.shards.get(id);
+        this.#setStatus(id, "connecting");
+        await gate.acquire(id);
+        try {
+          await gateway.connect();
+          await handshakeSent(gateway, timeout);
+        } finally {
+          gate.release(id);
+        }
+      }));
+      const failed = results.findIndex((result) => result.status === "rejected");
+      if (failed !== -1) {
+        if (destroyOnFailure)
+          this.destroy();
+        throw new Error(`Failed to connect shard ${ids[failed]}.`, {
+          cause: results[failed].reason
+        });
+      }
+      return;
+    }
     const limit = this.#gatewayInfo?.sessionStartLimit;
-    const ids = [...this.shards].filter(([, gateway]) => needsConnection(gateway)).map(([id]) => id);
     if (limit && limit.remaining < ids.length)
       throw new Error(`Session start limit exhausted: ${limit.remaining} of ${limit.total} IDENTIFYs left for ${ids.length} shards; resets in ${Math.ceil(limit.resetAfter / 1000)}s.`);
     const concurrency = Math.min(this.#options.maxConcurrency ?? limit?.maxConcurrency ?? 1, limit?.maxConcurrency ?? Infinity);
@@ -1890,24 +3901,22 @@ class ShardManager {
     const rounds = Math.max(0, ...[...buckets.values()].map((bucket) => bucket.length));
     for (let index = 0;index < rounds; index++) {
       const round = [...buckets.values()].map((bucket) => bucket[index]).filter((id) => id !== undefined);
+      for (const id of round)
+        this.#setStatus(id, "connecting");
       const results = await Promise.allSettled(round.map((id) => this.shards.get(id).connect()));
       const failed = results.findIndex((result) => result.status === "rejected");
       if (failed !== -1) {
-        this.destroy();
+        if (destroyOnFailure)
+          this.destroy();
         throw new Error(`Failed to connect shard ${round[failed]}.`, {
           cause: results[failed].reason
         });
       }
       if (index + 1 < rounds && this.#options.spawnDelay && this.#options.spawnDelay > 0) {
         await Promise.all(round.map((id) => handshakeSent(this.shards.get(id), this.#options.handshakeTimeout ?? 15000)));
-        await sleep2(this.#options.spawnDelay);
+        await sleep(this.#options.spawnDelay);
       }
     }
-    if (this.#options.autoScaleInterval && !this.#autoScaleTimer) {
-      this.#autoScaleTimer = setInterval(() => {
-        this.checkAutoScale();
-      }, this.#options.autoScaleInterval);
-    }
   }
   async checkAutoScale() {
     if (!this.#auto)
@@ -1929,7 +3938,11 @@ class ShardManager {
   destroy() {
     for (const shard of this.shards.values())
       shard.close();
+    for (const id of this.shards.keys())
+      this.#setStatus(id, "destroyed");
     this.shards.clear();
+    this.#lifecycle.clear();
+    this.#announced = false;
     this.#resolved = false;
     this.#destroyed = true;
     if (this.#autoScaleTimer) {
@@ -1965,11 +3978,60 @@ class ShardManager {
     return this.shards.get(id);
   }
   health() {
-    return [...this.shards].map(([id, gateway]) => ({
-      id,
-      state: gateway.state,
-      ping: gateway.ping
-    }));
+    return [...this.shards].map(([id, gateway]) => {
+      const life = this.#lifecycle.get(id);
+      return {
+        id,
+        state: gateway.state,
+        ping: gateway.ping,
+        status: life?.status ?? "idle",
+        ...life?.readyAt !== undefined ? { readyAt: life.readyAt } : {},
+        ...life?.disconnectedAt !== undefined ? { disconnectedAt: life.disconnectedAt } : {}
+      };
+    });
+  }
+  report(metrics = false) {
+    let numbers;
+    if (metrics) {
+      const memory = process.memoryUsage();
+      const cpu = process.cpuUsage();
+      numbers = {
+        rssBytes: memory.rss,
+        heapUsedBytes: memory.heapUsed,
+        cpuUserMicros: cpu.user,
+        cpuSystemMicros: cpu.system
+      };
+    }
+    return {
+      shards: this.health(),
+      ...numbers ? { metrics: numbers } : {},
+      reportedAt: Date.now()
+    };
+  }
+  #setStatus(id, status) {
+    const life = this.#lifecycle.get(id) ?? { status };
+    life.status = status;
+    const now = Date.now();
+    if (status === "ready")
+      life.readyAt = now;
+    if (status === "disconnected")
+      life.disconnectedAt = now;
+    this.#lifecycle.set(id, life);
+    if (status !== "ready")
+      this.#announced = false;
+    else
+      this.#maybeAnnounce();
+  }
+  #maybeAnnounce() {
+    if (this.#announced || this.shards.size === 0)
+      return;
+    for (const id of this.shards.keys())
+      if (this.#lifecycle.get(id)?.status !== "ready")
+        return;
+    this.#announced = true;
+    this.#emit("ready");
+    this.#worker?.ready(this.shardIds);
+    this.#worker?.reportHealth(this.report());
   }
   values() {
     return [...this.shards].map(([id, gateway]) => ({ id, gateway }));
@@ -1986,7 +4048,9 @@ class ShardManager {
     if (this.#resolved)
       return;
     this.#total = count;
-    for (let id = 0;id < count; id++)
+    const ids = this.#ids ?? Array.from({ length: count }, (_, i) => i);
+    validateShardIds(ids, count);
+    for (const id of ids)
       this.shards.set(id, this.#createShard(id, count));
     this.#resolved = true;
   }
@@ -1998,23 +4062,50 @@ class ShardManager {
       shardCount: count,
       reconnect: this.#options.reconnect ?? true
     });
-    gateway.on("ready", () => this.#emit("shardReady", id));
-    gateway.on("resumed", () => this.#emit("shardResume", id));
-    gateway.on("close", (close) => this.#emit("shardDisconnect", id, close));
+    gateway.on("ready", () => {
+      this.#setStatus(id, "ready");
+      this.#emit("shardReady", id);
+    });
+    gateway.on("resumed", () => {
+      this.#setStatus(id, "ready");
+      this.#emit("shardResume", id);
+    });
+    gateway.on("close", (close) => {
+      this.#setStatus(id, "disconnected");
+      this.#emit("shardDisconnect", id, close);
+    });
     gateway.on("error", (error) => this.#emit("shardError", id, error));
-    gateway.on("unstable", (info) => this.#emit("shardUnstable", id, info));
+    gateway.on("unstable", (info) => {
+      this.#setStatus(id, "unstable");
+      this.#emit("shardUnstable", id, info);
+    });
     return gateway;
   }
 }
 export {
   BroadcastChannelTransport,
+  ClusterHost,
   ClusterManager,
+  ClusterWorker,
+  IDENTIFY_INTERVAL,
+  IdentifyCoordinator,
   IpcTransport,
+  MAX_GUILDS_PER_SHARD,
+  REMOTE_PROTOCOL_VERSION,
+  RemoteClose,
+  RequestTracker,
   ShardBus,
   ShardManager,
   ShardSupervisor,
   ShardManager as ShardingManager,
-  fetchGatewayBot
+  allocateShards,
+  assertCompleteAllocation,
+  fetchGatewayBot,
+  fetchGuildCount,
+  isClusterWorker,
+  readClusterContext,
+  shardsForGuilds,
+  validateShardIds
 };
 
-//# debugId=8B521E4F34BB811E64756E2164756E21
+//# debugId=7D2FE3134CAB1F3364756E2164756E21