@rivalis/fleet 8.0.0

package/lib/module.js

@@ -0,0 +1,3582 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/orchestrator/Orchestrator.ts
+import { Broadcast } from "@toolcase/base";
+
+// src/util/logger.ts
+var NOOP_LOGGER = {
+  error() {
+  },
+  warning() {
+  },
+  info() {
+  },
+  debug() {
+  },
+  verbose() {
+  },
+  log() {
+  }
+};
+
+// src/orchestrator/Config.ts
+var DEFAULT_HOST = "0.0.0.0";
+var DEFAULT_HEARTBEAT_MS = 5e3;
+var DEFAULT_COMMAND_TIMEOUT_MS = 1e4;
+var MIN_KEY_LENGTH = 16;
+var WEAK_KEY_LENGTH = 32;
+function normalizeKeys(value) {
+  if (value === void 0) {
+    return [];
+  }
+  const list = Array.isArray(value) ? value : [value];
+  const seen = /* @__PURE__ */ new Set();
+  for (const key of list) {
+    if (typeof key === "string" && key.length > 0) {
+      seen.add(key);
+    }
+  }
+  return [...seen];
+}
+function resolveConfig(options) {
+  if (typeof options !== "object" || options === null) {
+    throw new Error("orchestrator config error: options must be an object");
+  }
+  if (typeof options.port !== "number" || !Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+    throw new Error(`orchestrator config error: port must be an integer in [0, 65535], got ${String(options.port)}`);
+  }
+  const agentKeys = normalizeKeys(options.agentKey);
+  if (agentKeys.length === 0) {
+    throw new Error("orchestrator config error: at least one agentKey is required");
+  }
+  const api = options.api ?? true;
+  const adminKeys = normalizeKeys(options.adminKey);
+  if (api && adminKeys.length === 0) {
+    throw new Error("orchestrator config error: adminKey is required when api is enabled");
+  }
+  const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  if (typeof heartbeatMs !== "number" || heartbeatMs <= 0) {
+    throw new Error("orchestrator config error: heartbeatMs must be a positive number");
+  }
+  const commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+  if (typeof commandTimeoutMs !== "number" || commandTimeoutMs <= 0) {
+    throw new Error("orchestrator config error: commandTimeoutMs must be a positive number");
+  }
+  let cors2 = false;
+  if (options.cors !== void 0 && options.cors !== false) {
+    if (!Array.isArray(options.cors.origins)) {
+      throw new Error("orchestrator config error: cors.origins must be an array of strings");
+    }
+    cors2 = { origins: [...options.cors.origins] };
+  }
+  return {
+    host: options.host ?? DEFAULT_HOST,
+    port: options.port,
+    agentKeys,
+    adminKeys,
+    api,
+    heartbeatMs,
+    commandTimeoutMs,
+    cors: cors2,
+    sseQueryAuth: options.sseQueryAuth ?? false,
+    trustProxy: options.trustProxy ?? false
+  };
+}
+function enforceSecurityPolicy(config, context = {}) {
+  const env2 = context.env;
+  const isProduction = env2 === "production";
+  const logger = context.logger ?? NOOP_LOGGER;
+  const adminSet = new Set(config.adminKeys);
+  const intersects = config.agentKeys.some((key) => adminSet.has(key));
+  if (intersects) {
+    const message = "orchestrator security: agentKey and adminKey lists intersect \u2014 one key serving both audiences re-opens the legacy single-token hole (\xA713)";
+    if (isProduction) {
+      throw new Error(`${message}; refusing to start when NODE_ENV=production`);
+    }
+    logger.warning(message);
+  }
+  if (!isProduction) {
+    return;
+  }
+  const allKeys = [...config.agentKeys, ...config.adminKeys];
+  for (const key of allKeys) {
+    if (key.length < MIN_KEY_LENGTH) {
+      throw new Error(
+        `orchestrator security: a configured key is shorter than ${MIN_KEY_LENGTH} characters \u2014 refusing to start when NODE_ENV=production (\xA713)`
+      );
+    }
+  }
+  for (const key of allKeys) {
+    if (key.length < WEAK_KEY_LENGTH) {
+      logger.warning(
+        `orchestrator security: a configured key is shorter than ${WEAK_KEY_LENGTH} characters \u2014 weak; prefer 32+ (\xA713)`
+      );
+    }
+  }
+}
+
+// src/orchestrator/FleetState.ts
+import { randomBytes } from "crypto";
+
+// src/util/canonical.ts
+import { createHash } from "crypto";
+function canonicalize(value) {
+  return encode(value);
+}
+function encode(value) {
+  if (value === null) {
+    return "null";
+  }
+  const type = typeof value;
+  if (type === "string") {
+    return JSON.stringify(value);
+  }
+  if (type === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (type === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (type === "bigint") {
+    return value.toString();
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => encodeArrayItem(item));
+    return "[" + items.join(",") + "]";
+  }
+  if (type === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+      const child = obj[key];
+      if (isSkippable(child)) {
+        continue;
+      }
+      parts.push(JSON.stringify(key) + ":" + encode(child));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return "null";
+}
+function encodeArrayItem(item) {
+  return isSkippable(item) ? "null" : encode(item);
+}
+function isSkippable(value) {
+  const type = typeof value;
+  return value === void 0 || type === "function" || type === "symbol";
+}
+function hash64(value) {
+  const digest = createHash("sha256").update(canonicalize(value)).digest();
+  return digest.subarray(0, 8).toString("hex");
+}
+
+// src/domain/roomId.ts
+var ROOM_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var NAMESPACE_SEPARATOR = "~";
+var ROOM_ID_CHAR = /[A-Za-z0-9_-]/;
+function isValidRoomId(id) {
+  return ROOM_ID_PATTERN.test(id);
+}
+function encodeRoomId(id) {
+  if (isValidRoomId(id)) {
+    return id;
+  }
+  let out = "";
+  for (const byte of Buffer.from(id, "utf8")) {
+    const ch = String.fromCharCode(byte);
+    out += ROOM_ID_CHAR.test(ch) ? ch : "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+  }
+  return out;
+}
+function namespaceRoomId(processUid, encodedRoomId) {
+  return processUid + NAMESPACE_SEPARATOR + encodedRoomId;
+}
+
+// src/domain/roomCreate.ts
+var roomCreateSchema = {
+  type: { type: "string", required: true, min: 1 },
+  roomId: { type: "string", pattern: ROOM_ID_PATTERN.source },
+  placement: { type: "object" }
+};
+
+// src/domain/errors.ts
+import { EndpointError } from "@toolcase/node";
+var CODE_TO_STATUS = {
+  VALIDATION: 400,
+  UNAUTHORIZED: 401,
+  INSTANCE_NOT_FOUND: 404,
+  ROOM_NOT_FOUND: 404,
+  NO_CANDIDATE: 409,
+  ROOM_EXISTS: 409,
+  INSTANCE_DRAINING: 409,
+  PAYLOAD_TOO_LARGE: 413,
+  INSTANCE_BUSY: 429,
+  AUTH_THROTTLED: 429,
+  SSE_LIMIT: 429,
+  COMMAND_FAILED: 502,
+  INSTANCE_DISCONNECTED: 502,
+  COMMAND_TIMEOUT: 504
+};
+var FleetError = class extends EndpointError {
+  constructor(code, message) {
+    super(CODE_TO_STATUS[code], code, message);
+    this.name = "FleetError";
+  }
+};
+
+// src/orchestrator/FleetState.ts
+var FleetState = class {
+  logger;
+  random;
+  /** Read model, keyed by connection-scoped `instanceId` (a reconnect is a new key). */
+  records = /* @__PURE__ */ new Map();
+  /** Live capacity reservations: token → instanceId. */
+  reservations = /* @__PURE__ */ new Map();
+  /** Reserved room slots per instance, derived from `reservations` for O(1) headroom checks. */
+  reservedByInstance = /* @__PURE__ */ new Map();
+  reservationSeq = 0;
+  /** Room ids reserved by in-flight creates (§11) — held until ack/timeout/rejection. */
+  reservedRoomIds = /* @__PURE__ */ new Set();
+  /**
+   * Room ids whose create has settled (acked OK or timed out) but whose room has
+   * not yet appeared in an applied snapshot from the owning instance (task 003).
+   * The id reservation is held *past* the command settle: releasing it on ack/timeout
+   * would free the id for up to one `heartbeatMs` before the room reconciles into the
+   * read model — the window in which the §10 retry-after-504 (or an immediate
+   * re-create) re-reserves the id and double-creates on a *different* instance, the
+   * exact cross-instance duplicate §11 exists to prevent. Keyed `roomId → owning
+   * instanceId`; cleared when the owning instance's next snapshot/poll reconciles
+   * (the read model takes over) or it is evicted. Held entries count toward both
+   * id-uniqueness ({@link isRoomIdTaken}) and `maxRooms` headroom ({@link hasHeadroom}).
+   */
+  pendingRoomIds = /* @__PURE__ */ new Map();
+  /** Pending-visibility room count per instance, for O(1) `maxRooms` headroom (task 003). */
+  pendingByInstance = /* @__PURE__ */ new Map();
+  /** Monotonic join counter — assigns each instance its tie-break order (§11). */
+  joinCounter = 0;
+  /**
+   * Instances the orchestrator has marked stale (wedged: connected but silent
+   * past 2×heartbeat — §7). Liveness bookkeeping, not snapshot-derived semantic
+   * state: it is **excluded from `stateHash`** (like `lastSyncAt`) but **excludes
+   * the instance from auto-placement**, so a wedged-yet-least-loaded node cannot
+   * keep winning placement until it is evicted at 3×heartbeat.
+   */
+  staleInstances = /* @__PURE__ */ new Set();
+  /**
+   * Agent-acked-but-not-yet-snapshotted status, kept for PLACEMENT candidacy only
+   * (task 004). On a `drain`/`undrain` ack the agent has already flipped its
+   * agent-owned status (§7), but the read-model `status` only catches up at the
+   * instance's next poll reply — up to one `heartbeatMs` later. Until then
+   * `place()` would still see the stale value and keep selecting a just-drained
+   * node (or keep excluding a just-undrained one). Like {@link staleInstances},
+   * this is a placement-only override: it is **excluded from `stateHash`** and the
+   * read model, and it **never writes the agent-owned `status`** (§7 status
+   * ownership stays intact) — it only shifts what {@link place} treats as the
+   * instance's effective status. Keyed `instanceId → effective status`; cleared the
+   * moment a snapshot/poll reconciles the matching status into the read model (the
+   * override has done its job) or the instance is removed.
+   */
+  pendingStatus = /* @__PURE__ */ new Map();
+  /**
+   * Memoized id-resolution pass ({@link resolve}) and {@link computeStateHash}
+   * result. The resolution is O(rooms) — flatten every room, group by base id,
+   * sort the collision buckets, build the public-id index, clone every instance —
+   * and was previously rebuilt on **every** read-model query (`stats`/`instances`/
+   * `rooms`/`getRoom`/…); one `GET /v1/stats` alone resolves ≥2×. Both are now
+   * computed lazily and held until the next SEMANTIC mutation.
+   *
+   * Invalidated by exactly the two mutations that change semantic state:
+   * {@link applySnapshot} (when it actually applies) and {@link removeInstance}.
+   * {@link touch} (advances `lastSyncAt`) and {@link setStale} are non-semantic —
+   * both are excluded from `stateHash` (§6) and from the resolution — so neither
+   * invalidates; `touch` instead keeps the cached `InstanceInfo.lastSyncAt` in step
+   * in place (see below). `null` ⇒ dirty, rebuild on next read.
+   *
+   * Read-only contract: the cached `InstanceInfo` / `RoomInfo` objects are now
+   * SHARED across callers and across queries (a query no longer clones afresh).
+   * They must be treated as immutable by consumers; the only sanctioned in-place
+   * write is `touch`'s `lastSyncAt` refresh, which is liveness bookkeeping outside
+   * both the resolution and the hash. The `instances`/`rooms`/`findRooms` getters
+   * still hand back a fresh array container so a caller's `sort()`/`push()` cannot
+   * corrupt the memo — only the element objects are shared.
+   */
+  resolvedView = null;
+  cachedStateHash = null;
+  constructor(options = {}) {
+    this.logger = options.logger ?? NOOP_LOGGER;
+    this.random = options.random ?? Math.random;
+  }
+  // -----------------------------------------------------------------------
+  // Read model mutation (driven by the fleet room — task 009)
+  // -----------------------------------------------------------------------
+  /**
+   * Apply a validated full `fleet/state` snapshot to the read model. Returns `true`
+   * when applied, `false` when dropped as an out-of-order/duplicate frame.
+   *
+   * `seq` is per-connection monotonic (§7); a frame whose `seq` does not
+   * strictly exceed the last applied one is **dropped, never applied** — this
+   * turns a hypothetical agent-side send-queue bug into a lost frame instead of
+   * read-model corruption (§7, §14). Field validation (§13) happens upstream;
+   * this method trusts the payload's shape.
+   */
+  applySnapshot(instanceId, payload, lastSyncAt) {
+    const existing = this.records.get(instanceId);
+    if (existing !== void 0 && payload.seq <= existing.lastSeq) {
+      this.logger.warning(
+        `fleet: dropped out-of-order snapshot from instance=${instanceId} (seq=${payload.seq} <= last=${existing.lastSeq})`
+      );
+      return false;
+    }
+    const info = buildInstanceInfo(instanceId, payload, lastSyncAt);
+    const joinSeq = existing?.joinSeq ?? ++this.joinCounter;
+    this.records.set(instanceId, { info, lastSeq: payload.seq, lastHash: payload.hash, joinSeq });
+    this.invalidate();
+    this.clearPendingVisibility(instanceId);
+    this.reconcilePendingStatus(instanceId);
+    return true;
+  }
+  /**
+   * Bump an instance's `lastSyncAt` without touching semantic state (used on
+   * a hash-only `fleet/state` reply). Deliberately does **not** affect `stateHash` — liveness
+   * bookkeeping is excluded so a quiet fleet still produces ETag 304s (§6, §10).
+   */
+  touch(instanceId, lastSyncAt) {
+    const record = this.records.get(instanceId);
+    if (record === void 0) {
+      return;
+    }
+    record.info.lastSyncAt = lastSyncAt;
+    this.clearPendingVisibility(instanceId);
+    this.reconcilePendingStatus(instanceId);
+    const cached = this.resolvedView?.byId.get(instanceId);
+    if (cached !== void 0) {
+      cached.lastSyncAt = lastSyncAt;
+    }
+  }
+  /** Remove an instance from the read model (socket close or eviction, §7). */
+  removeInstance(instanceId) {
+    const record = this.records.get(instanceId);
+    if (record === void 0) {
+      return null;
+    }
+    this.records.delete(instanceId);
+    this.staleInstances.delete(instanceId);
+    this.pendingStatus.delete(instanceId);
+    this.clearPendingVisibility(instanceId);
+    this.invalidate();
+    return record.info;
+  }
+  /**
+   * Mark/unmark an instance stale (orchestrator liveness — §7). A stale instance
+   * stays in the read model and the `stateHash` (so dashboards keep seeing it
+   * until eviction) but is dropped from auto-placement candidacy. Cleared
+   * automatically on {@link removeInstance}.
+   */
+  setStale(instanceId, stale) {
+    if (stale) {
+      this.staleInstances.add(instanceId);
+    } else {
+      this.staleInstances.delete(instanceId);
+    }
+  }
+  /**
+   * Record an agent-acked-but-not-yet-snapshotted status for PLACEMENT only
+   * (task 004) — called on a `drain`/`undrain` ack, where the agent has already
+   * flipped its status (§7) but the read model lags by up to one poll. `place()`
+   * reads this through {@link effectiveStatus} so candidacy converges at ack time
+   * (`drain` excludes the node, `undrain` re-includes it) instead of one poll
+   * interval later. Never writes the agent-owned read-model `status` and is absent
+   * from `stateHash`, so §7 status ownership and the §10 ETag are untouched. The
+   * override clears itself once a snapshot reconciles the matching status (see
+   * {@link reconcilePendingStatus}). No-op on an unknown instance — there is nothing
+   * to place onto, and a later join starts clean.
+   */
+  setPendingStatus(instanceId, status) {
+    if (!this.records.has(instanceId)) {
+      return;
+    }
+    this.pendingStatus.set(instanceId, status);
+  }
+  /** Hash of the last applied snapshot for an instance (sent as the poll `knownHash` for dedup, §7). */
+  lastHashOf(instanceId) {
+    return this.records.get(instanceId)?.lastHash ?? null;
+  }
+  // -----------------------------------------------------------------------
+  // Read model queries (§9)
+  // -----------------------------------------------------------------------
+  get instances() {
+    return [...this.resolve().instances];
+  }
+  get rooms() {
+    const rooms = [];
+    for (const instance of this.resolve().instances) {
+      rooms.push(...instance.rooms);
+    }
+    return rooms;
+  }
+  get stats() {
+    const instances = this.resolve().instances;
+    let connections = 0;
+    let rooms = 0;
+    const roomTypes = /* @__PURE__ */ new Set();
+    for (const instance of instances) {
+      connections += instance.connections;
+      rooms += instance.rooms.length;
+      for (const type of instance.roomTypes) {
+        roomTypes.add(type);
+      }
+    }
+    if (this.cachedStateHash === null) {
+      this.cachedStateHash = this.computeStateHash(instances);
+      this.logger.debug("fleet: computed semantic state hash");
+    }
+    return {
+      instances: instances.length,
+      rooms,
+      connections,
+      roomTypes: [...roomTypes].sort(),
+      stateHash: this.cachedStateHash
+    };
+  }
+  getInstance(id) {
+    return this.resolve().byId.get(id) ?? null;
+  }
+  /**
+   * Resolve an instance by its stable `processUid` (§6 pinning) to the **most
+   * recent connection** — the record with the highest `joinSeq` (task 011). During
+   * a reconnect overlap two records share a `processUid` (the live new connection
+   * plus the old wedged one not yet evicted, up to 3 poll intervals); `processUid`
+   * is the documented *stable* handle across reconnects, so it must resolve to the
+   * live connection. First-match (map insertion order) would pick the OLDEST — the
+   * dead connection in exactly the scenario `processUid` pinning exists for.
+   */
+  getInstanceByProcessUid(processUid) {
+    const record = this.latestRecordByProcessUid(processUid);
+    return record === null ? null : this.resolve().byId.get(record.info.id) ?? null;
+  }
+  /** Look up a room by its PUBLIC id (canonical, namespaced, or percent-encoded — §11). */
+  getRoom(roomId) {
+    return this.resolve().byPublicId.get(roomId)?.room ?? null;
+  }
+  /**
+   * Map a public room id (possibly namespaced or percent-encoded) back to its
+   * owning instance and the RAW id the agent knows it by — what a `fleet/cmd`
+   * `destroy` must carry, since the agent never sees the public id (§11). Returns
+   * null when no room has that public id.
+   */
+  resolveRoom(roomId) {
+    const locator = this.resolve().byPublicId.get(roomId);
+    if (locator === void 0) {
+      return null;
+    }
+    return { instanceId: locator.instanceId, rawRoomId: locator.rawRoomId };
+  }
+  /** Rooms cluster-wide, filtered by type / owning instance / owning-instance labels (§9). */
+  findRooms(filter = {}) {
+    const result = [];
+    for (const instance of this.resolve().instances) {
+      if (filter.instanceId !== void 0 && instance.id !== filter.instanceId) {
+        continue;
+      }
+      if (filter.labels !== void 0 && !matchesLabels(instance.labels, filter.labels)) {
+        continue;
+      }
+      for (const room of instance.rooms) {
+        if (filter.type !== void 0 && room.type !== filter.type) {
+          continue;
+        }
+        result.push(room);
+      }
+    }
+    return result;
+  }
+  // -----------------------------------------------------------------------
+  // Placement (§9)
+  // -----------------------------------------------------------------------
+  /**
+   * Select an instance for a new room and reserve a capacity slot on it,
+   * atomically (§9). Throws a coded {@link FleetError} on validation /
+   * no-candidate / draining-pin. The reservation must be released by the
+   * caller on ack, timeout, or rejection.
+   */
+  place(request) {
+    if (request.instanceId !== void 0 && request.processUid !== void 0) {
+      throw new FleetError("VALIDATION", "specify at most one of placement.instanceId or placement.processUid");
+    }
+    if (request.instanceId !== void 0 || request.processUid !== void 0) {
+      const instance2 = request.instanceId !== void 0 ? this.rawInstanceById(request.instanceId) : this.rawInstanceByProcessUid(request.processUid);
+      if (instance2 === null) {
+        const which = request.instanceId !== void 0 ? `instanceId=${request.instanceId}` : `processUid=${request.processUid}`;
+        throw new FleetError("INSTANCE_NOT_FOUND", `no instance matches ${which}`);
+      }
+      if (this.effectiveStatus(instance2) === "draining" && request.force !== true) {
+        throw new FleetError(
+          "INSTANCE_DRAINING",
+          `instance ${instance2.id} is draining; pin requires force: true`
+        );
+      }
+      if (this.staleInstances.has(instance2.id) && request.force !== true) {
+        throw new FleetError(
+          "INSTANCE_DISCONNECTED",
+          `instance ${instance2.id} is stale (missed poll replies); pin requires force: true`
+        );
+      }
+      if (!instance2.autoCreate) {
+        throw new FleetError("NO_CANDIDATE", `instance ${instance2.id} has autoCreate disabled`);
+      }
+      return { instance: instance2, reservation: this.reserve(instance2.id) };
+    }
+    const candidates = this.rawInstances().filter(
+      (instance2) => this.effectiveStatus(instance2) === "active" && !this.staleInstances.has(instance2.id) && instance2.autoCreate === true && instance2.roomTypes.includes(request.type) && (request.labels === void 0 || matchesLabels(instance2.labels, request.labels)) && this.hasHeadroom(instance2)
+    );
+    if (candidates.length === 0) {
+      throw new FleetError("NO_CANDIDATE", `no active instance can host room type "${request.type}"`);
+    }
+    const instance = this.pick(candidates, request.strategy ?? "least-loaded");
+    return { instance, reservation: this.reserve(instance.id) };
+  }
+  /** Release a capacity reservation (on ack, timeout, or rejection — §9). Idempotent. */
+  release(reservation) {
+    if (!this.reservations.delete(reservation.id)) {
+      return;
+    }
+    const count = this.reservedByInstance.get(reservation.instanceId) ?? 0;
+    if (count <= 1) {
+      this.reservedByInstance.delete(reservation.instanceId);
+    } else {
+      this.reservedByInstance.set(reservation.instanceId, count - 1);
+    }
+  }
+  /** Reserved (in-flight) room slots currently held against an instance. */
+  reservedRooms(instanceId) {
+    return this.reservedByInstance.get(instanceId) ?? 0;
+  }
+  // -----------------------------------------------------------------------
+  // Room-id uniqueness & reservation (§11)
+  // -----------------------------------------------------------------------
+  /**
+   * Validate, uniqueness-check, and reserve a room id for an in-flight create
+   * (§11). When `roomId` is omitted a collision-free `r_<id>` within the charset
+   * is generated. Throws {@link FleetError} `VALIDATION` (explicit id outside the
+   * charset) or `ROOM_EXISTS` (id already in the fleet or already reserved). The
+   * reservation closes the race window: two concurrent creates with the same
+   * explicit id cannot both pass — exactly one reserves, the rest fail fast. The
+   * caller must `releaseRoomId` on ack, timeout, or rejection.
+   */
+  reserveRoomId(roomId) {
+    if (roomId === void 0) {
+      const generated = this.generateFreeRoomId();
+      this.reservedRoomIds.add(generated);
+      return { roomId: generated };
+    }
+    if (!isValidRoomId(roomId)) {
+      throw new FleetError("VALIDATION", `roomId "${roomId}" must match ${ROOM_ID_PATTERN.source}`);
+    }
+    if (this.isRoomIdTaken(roomId)) {
+      throw new FleetError("ROOM_EXISTS", `room id "${roomId}" already exists or is reserved`);
+    }
+    this.reservedRoomIds.add(roomId);
+    return { roomId };
+  }
+  /** Release a room-id reservation (on ack, timeout, or rejection — §11). Idempotent. */
+  releaseRoomId(reservation) {
+    this.reservedRoomIds.delete(reservation.roomId);
+  }
+  /**
+   * Transition a create's reservations from *in-flight* to *pending-visibility*
+   * (task 003) — called by the command engine when a create **acks OK or times
+   * out**, instead of releasing. The room id stays reserved and one `maxRooms` slot
+   * stays counted until the owning instance's next snapshot/poll reconciles the room
+   * into the read model (or it is evicted). This closes the §11 window where a
+   * `504`-then-retry (§10) or an ack-then-immediate re-create would re-reserve the id
+   * after the command settled but before the room was visible, and double-create it on
+   * another instance. The original capacity reservation token is released and both
+   * holds collapse into one pending-visibility entry (still one id, one room slot).
+   */
+  holdUntilVisible(roomIdReservation, reservation) {
+    this.release(reservation);
+    this.reservedRoomIds.delete(roomIdReservation.roomId);
+    if (this.pendingRoomIds.has(roomIdReservation.roomId)) {
+      return;
+    }
+    this.pendingRoomIds.set(roomIdReservation.roomId, reservation.instanceId);
+    this.pendingByInstance.set(
+      reservation.instanceId,
+      (this.pendingByInstance.get(reservation.instanceId) ?? 0) + 1
+    );
+  }
+  /** Acked-but-not-yet-visible room slots held against an instance (task 003). */
+  pendingRooms(instanceId) {
+    return this.pendingByInstance.get(instanceId) ?? 0;
+  }
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+  /**
+   * A public id is taken when an in-flight reservation holds it, a settled-but-not-
+   * yet-visible create holds it (task 003), or a live room already uses it.
+   */
+  isRoomIdTaken(roomId) {
+    return this.reservedRoomIds.has(roomId) || this.pendingRoomIds.has(roomId) || this.getRoom(roomId) !== null;
+  }
+  /**
+   * Clear every pending-visibility hold for an instance (task 003) — called when the
+   * instance's snapshot/poll reconciles its room set (the read model now holds
+   * whatever rooms truly exist) or when it is evicted (its rooms vanish). Either way
+   * the in-flight hold has done its job: a present room is taken via the read model,
+   * an absent one is genuinely free. Idempotent.
+   */
+  clearPendingVisibility(instanceId) {
+    if (this.pendingByInstance.get(instanceId) === void 0) {
+      return;
+    }
+    for (const [roomId, owner] of [...this.pendingRoomIds]) {
+      if (owner === instanceId) {
+        this.pendingRoomIds.delete(roomId);
+      }
+    }
+    this.pendingByInstance.delete(instanceId);
+  }
+  /**
+   * The status `place()` should treat the instance as having (task 004): the
+   * pending placement override when one is held, else the snapshot-derived
+   * read-model `status`. The override exists only between a `drain`/`undrain` ack
+   * and the snapshot that confirms it.
+   */
+  effectiveStatus(instance) {
+    return this.pendingStatus.get(instance.id) ?? instance.status;
+  }
+  /**
+   * Drop the placement override once the read model has caught up (task 004) — i.e.
+   * the last-applied snapshot's status now equals the pending value. Called on every
+   * snapshot apply and hash-only poll reply. Idempotent; no-op when no override is held.
+   */
+  reconcilePendingStatus(instanceId) {
+    const pending = this.pendingStatus.get(instanceId);
+    if (pending !== void 0 && this.records.get(instanceId)?.info.status === pending) {
+      this.pendingStatus.delete(instanceId);
+    }
+  }
+  /** Generate a `r_<id>` not currently reserved or in use; near-certain on the first try. */
+  generateFreeRoomId() {
+    for (let attempt = 0; attempt < 1e3; attempt++) {
+      const candidate = generateRoomId();
+      if (!this.isRoomIdTaken(candidate)) {
+        return candidate;
+      }
+    }
+    throw new FleetError("ROOM_EXISTS", "could not generate a unique room id after 1000 attempts");
+  }
+  /** Raw read-model rows (raw room ids) — the placement candidate source. */
+  rawInstances() {
+    return [...this.records.values()].map((record) => record.info);
+  }
+  rawInstanceById(id) {
+    return this.records.get(id)?.info ?? null;
+  }
+  rawInstanceByProcessUid(processUid) {
+    return this.latestRecordByProcessUid(processUid)?.info ?? null;
+  }
+  /**
+   * The record for `processUid` with the highest `joinSeq` — the most recent
+   * connection (task 011). Shared by {@link getInstanceByProcessUid} (read API)
+   * and the pinned {@link place} path so both resolve a reconnect-overlapped
+   * `processUid` to the live connection, never the wedged old one.
+   */
+  latestRecordByProcessUid(processUid) {
+    let latest = null;
+    for (const record of this.records.values()) {
+      if (record.info.processUid === processUid && (latest === null || record.joinSeq > latest.joinSeq)) {
+        latest = record;
+      }
+    }
+    return latest;
+  }
+  /**
+   * Resolve raw agent-reported room ids into the fleet-unique PUBLIC id space
+   * (§11). Pure function of the current read model — derivable from snapshots
+   * alone (§3), so it survives an orchestrator restart. Rules:
+   *  - Local ids outside the charset are percent-encoded ({@link encodeRoomId}).
+   *  - When several rooms map to the same base id, exactly one keeps it: a
+   *    `fleet` room beats a `local` one, then the earliest joiner wins, then the
+   *    lower instance id (deterministic — never map-iteration order). The losers
+   *    surface namespaced as `<processUid>~<base>`, flagged `local` per their own
+   *    origin. Two `fleet` rooms colliding can only happen across a restart, so
+   *    that case is logged naming both instances (post-restart tie-break, §11).
+   */
+  resolve() {
+    if (this.resolvedView !== null) {
+      return this.resolvedView;
+    }
+    const entries = [];
+    for (const record of this.records.values()) {
+      for (const room of record.info.rooms) {
+        entries.push({
+          instanceId: record.info.id,
+          processUid: record.info.processUid,
+          joinSeq: record.joinSeq,
+          rawId: room.id,
+          base: encodeRoomId(room.id),
+          origin: room.local ? "local" : "fleet",
+          room,
+          publicId: ""
+        });
+      }
+    }
+    const groups = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const bucket = groups.get(entry.base);
+      if (bucket === void 0) {
+        groups.set(entry.base, [entry]);
+      } else {
+        bucket.push(entry);
+      }
+    }
+    for (const [base, bucket] of groups) {
+      if (bucket.length === 1) {
+        bucket[0].publicId = base;
+        continue;
+      }
+      const ordered = [...bucket].sort(compareForCanonical);
+      const keeper = ordered[0];
+      keeper.publicId = base;
+      for (const entry of ordered) {
+        if (entry !== keeper) {
+          entry.publicId = namespaceRoomId(entry.processUid, base);
+        }
+      }
+      const fleetDuplicates = ordered.filter((entry) => entry.origin === "fleet");
+      if (fleetDuplicates.length > 1) {
+        for (const loser of fleetDuplicates) {
+          if (loser !== keeper) {
+            this.logger.warning(
+              `fleet: duplicate room id "${base}" reported by instance ${keeper.instanceId} (joined earliest, keeps the canonical id) and instance ${loser.instanceId} (surfaced as "${loser.publicId}") \u2014 \xA711 post-restart tie-break, no room hidden or destroyed`
+            );
+          }
+        }
+      }
+    }
+    const roomsByInstance = /* @__PURE__ */ new Map();
+    const byPublicId = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const room = { ...entry.room, id: entry.publicId };
+      const list = roomsByInstance.get(entry.instanceId);
+      if (list === void 0) {
+        roomsByInstance.set(entry.instanceId, [room]);
+      } else {
+        list.push(room);
+      }
+      byPublicId.set(entry.publicId, { room, instanceId: entry.instanceId, rawRoomId: entry.rawId });
+    }
+    const instances = [];
+    const byId = /* @__PURE__ */ new Map();
+    for (const record of this.records.values()) {
+      const instance = { ...record.info, rooms: roomsByInstance.get(record.info.id) ?? [] };
+      instances.push(instance);
+      byId.set(instance.id, instance);
+    }
+    this.logger.debug("fleet: rebuilt id-resolution view");
+    this.resolvedView = { instances, byId, byPublicId };
+    return this.resolvedView;
+  }
+  /**
+   * Drop the memoized resolution + state hash. Called by the two SEMANTIC
+   * mutations only ({@link applySnapshot}, {@link removeInstance}); the next read
+   * rebuilds. Non-semantic mutations ({@link touch}, {@link setStale}) never call
+   * this — see {@link resolvedView}.
+   */
+  invalidate() {
+    this.resolvedView = null;
+    this.cachedStateHash = null;
+  }
+  reserve(instanceId) {
+    const id = `res_${++this.reservationSeq}`;
+    this.reservations.set(id, instanceId);
+    this.reservedByInstance.set(instanceId, (this.reservedByInstance.get(instanceId) ?? 0) + 1);
+    return { id, instanceId };
+  }
+  /**
+   * Headroom against capacity, counting in-flight reservations as rooms (§9).
+   * A pending create occupies a room slot but contributes no connections (the
+   * room is empty until clients join), so reservations gate `maxRooms` only;
+   * `maxConnections` is gated by the real connection count.
+   */
+  hasHeadroom(instance) {
+    const capacity = instance.capacity;
+    if (capacity.maxRooms !== null) {
+      const projected = instance.rooms.length + this.reservedRooms(instance.id) + this.pendingRooms(instance.id);
+      if (projected >= capacity.maxRooms) {
+        return false;
+      }
+    }
+    if (capacity.maxConnections !== null && instance.connections >= capacity.maxConnections) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Pick among filtered candidates (§9 steps 2–3). `least-loaded`/`most-loaded`
+   * score by `connections / maxConnections` only when *every* candidate
+   * declares `maxConnections`; if any leaves it undeclared, all are scored by
+   * raw `connections` (a normalized 0.93 and a raw 1500 are not comparable).
+   * Ties are broken randomly; `random` ignores load entirely.
+   */
+  pick(candidates, strategy) {
+    if (strategy === "random") {
+      return this.choose(candidates);
+    }
+    const allDeclare = candidates.every((instance) => instance.capacity.maxConnections !== null);
+    const scoreOf = (instance) => allDeclare ? instance.connections / instance.capacity.maxConnections : instance.connections;
+    let best = scoreOf(candidates[0]);
+    for (const instance of candidates) {
+      const score = scoreOf(instance);
+      best = strategy === "most-loaded" ? Math.max(best, score) : Math.min(best, score);
+    }
+    const tied = candidates.filter((instance) => scoreOf(instance) === best);
+    return this.choose(tied);
+  }
+  /** Uniform random choice from a non-empty list (placement tie-break / `random` strategy). */
+  choose(list) {
+    const index = Math.floor(this.random() * list.length);
+    return list[Math.min(index, list.length - 1)];
+  }
+  /**
+   * Hash of SEMANTIC fleet state only (§6): instances, rooms, counts, statuses,
+   * capacities, versions — explicitly EXCLUDING `lastSyncAt` and all liveness
+   * bookkeeping, so the §10 ETag does not churn on every heartbeat. Order-
+   * independent: instances are sorted by id before encoding.
+   */
+  computeStateHash(instances) {
+    const projection = instances.map((instance) => ({
+      id: instance.id,
+      name: instance.name,
+      processUid: instance.processUid,
+      endpointUrl: instance.endpointUrl,
+      labels: instance.labels,
+      roomTypes: instance.roomTypes,
+      connections: instance.connections,
+      capacity: instance.capacity,
+      autoCreate: instance.autoCreate,
+      status: instance.status,
+      agentVersion: instance.agentVersion,
+      protocolVersion: instance.protocolVersion,
+      rooms: instance.rooms.map((room) => ({
+        id: room.id,
+        type: room.type,
+        connections: room.connections,
+        instanceId: room.instanceId,
+        endpointUrl: room.endpointUrl,
+        local: room.local
+      }))
+    })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return hash64(projection);
+  }
+};
+function buildInstanceInfo(instanceId, payload, lastSyncAt) {
+  const rooms = payload.rooms.map((room) => ({
+    id: room.id,
+    type: room.type,
+    connections: room.connections,
+    instanceId,
+    // Denormalized from the owning instance so room lookups carry the URL (§6).
+    endpointUrl: payload.endpointUrl,
+    // Provenance is the agent's call, never inferred here (§6).
+    local: room.origin === "local"
+  }));
+  let connections = 0;
+  for (const room of rooms) {
+    connections += room.connections;
+  }
+  return {
+    id: instanceId,
+    name: payload.name,
+    processUid: payload.processUid,
+    endpointUrl: payload.endpointUrl,
+    labels: payload.labels,
+    roomTypes: payload.roomTypes,
+    rooms,
+    connections,
+    capacity: payload.capacity,
+    autoCreate: payload.autoCreate,
+    status: payload.status,
+    lastSyncAt,
+    agentVersion: payload.agentVersion,
+    protocolVersion: payload.protocolVersion
+  };
+}
+function matchesLabels(instanceLabels, required) {
+  for (const key of Object.keys(required)) {
+    if (instanceLabels[key] !== required[key]) {
+      return false;
+    }
+  }
+  return true;
+}
+function compareForCanonical(a, b) {
+  const rankA = a.origin === "fleet" ? 0 : 1;
+  const rankB = b.origin === "fleet" ? 0 : 1;
+  if (rankA !== rankB) {
+    return rankA - rankB;
+  }
+  if (a.joinSeq !== b.joinSeq) {
+    return a.joinSeq - b.joinSeq;
+  }
+  return a.instanceId < b.instanceId ? -1 : a.instanceId > b.instanceId ? 1 : 0;
+}
+var ROOM_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+var ROOM_ID_RANDOM_LENGTH = 21;
+function generateRoomId() {
+  const bytes = randomBytes(ROOM_ID_RANDOM_LENGTH);
+  let id = "r_";
+  for (let i = 0; i < ROOM_ID_RANDOM_LENGTH; i++) {
+    id += ROOM_ID_ALPHABET[bytes[i] & 63];
+  }
+  return id;
+}
+
+// src/orchestrator/AgentAuthenticator.ts
+import { createHash as createHash2, timingSafeEqual } from "crypto";
+function matchKey(presented, keys) {
+  if (typeof presented !== "string" || presented.length === 0 || keys.length === 0) {
+    return null;
+  }
+  const presentedDigest = createHash2("sha256").update(presented).digest();
+  let matched = null;
+  for (const key of keys) {
+    const candidate = createHash2("sha256").update(key).digest();
+    if (timingSafeEqual(presentedDigest, candidate)) {
+      matched = key;
+    }
+  }
+  return matched;
+}
+var AgentAuthenticator = class {
+  constructor(agentKeys) {
+    this.agentKeys = agentKeys;
+  }
+  agentKeys;
+  /** True when `ticket` is one of the configured agent keys (constant-time, §13). */
+  matches(ticket) {
+    return matchKey(ticket, this.agentKeys) !== null;
+  }
+};
+
+// src/wire/topics.ts
+var PROTOCOL_VERSION = 3;
+var WS_SUBPROTOCOL = "rivalis-fleet.v1";
+var MAX_INFLIGHT_COMMANDS = 32;
+var Topics = {
+  /** orch → agent: assigns id + heartbeat (poll cadence) on join; followed by the first poll. */
+  hello: "fleet/hello",
+  /** orch → agent: state poll. Carries `knownHash` (dedup) + the last recorded `status` (echo). */
+  poll: "fleet/poll",
+  /** agent → orch: poll reply. Full snapshot when the hash differs from `knownHash`, hash-only otherwise. */
+  state: "fleet/state",
+  /** orch → agent: command push. */
+  cmd: "fleet/cmd",
+  /** agent → orch: command result. */
+  ack: "fleet/ack"
+};
+
+// src/wire/snapshotSchema.ts
+var MAX_ENDPOINT_URL_LENGTH = 512;
+var MAX_NAME_LENGTH = 64;
+var MAX_LABELS = 32;
+var MAX_LABEL_KEY_LENGTH = 64;
+var MAX_LABEL_VALUE_LENGTH = 64;
+var MAX_ROOM_TYPES = 256;
+var MAX_ROOMS = 5e4;
+var MAX_ROOM_ID_LENGTH = 256;
+var MAX_ROOM_TYPE_LENGTH = 64;
+var MAX_ROOM_CONNECTIONS = 1e6;
+var ALLOWED_ENDPOINT_SCHEMES = /* @__PURE__ */ new Set(["ws:", "wss:", "http:", "https:"]);
+var syncPayloadSchema = {
+  endpointUrl: { type: "string", required: true, max: MAX_ENDPOINT_URL_LENGTH },
+  name: { type: "string", required: true, max: MAX_NAME_LENGTH },
+  labels: { type: "object", required: true },
+  roomTypes: { type: "array", required: true, max: MAX_ROOM_TYPES, items: { type: "string", max: MAX_ROOM_TYPE_LENGTH } },
+  rooms: { type: "array", required: true, max: MAX_ROOMS, items: { type: "object" } }
+};
+function checkRule(field, value, rule) {
+  if (value === void 0 || value === null) {
+    return rule.required === true ? `${field} is required` : null;
+  }
+  switch (rule.type) {
+    case "string":
+      if (typeof value !== "string") {
+        return `${field} must be a string`;
+      }
+      if (rule.max !== void 0 && value.length > rule.max) {
+        return `${field} exceeds ${rule.max} characters`;
+      }
+      if (rule.min !== void 0 && value.length < rule.min) {
+        return `${field} must be at least ${rule.min} characters`;
+      }
+      if (rule.pattern !== void 0 && !new RegExp(rule.pattern).test(value)) {
+        return `${field} has an invalid format`;
+      }
+      return null;
+    case "number":
+    case "integer":
+      if (typeof value !== "number" || rule.type === "integer" && !Number.isInteger(value)) {
+        return `${field} must be a number`;
+      }
+      if (rule.max !== void 0 && value > rule.max) {
+        return `${field} exceeds ${rule.max}`;
+      }
+      if (rule.min !== void 0 && value < rule.min) {
+        return `${field} is below ${rule.min}`;
+      }
+      return null;
+    case "boolean":
+      return typeof value === "boolean" ? null : `${field} must be a boolean`;
+    case "object":
+      return typeof value === "object" && !Array.isArray(value) ? null : `${field} must be an object`;
+    case "array":
+      if (!Array.isArray(value)) {
+        return `${field} must be an array`;
+      }
+      if (rule.max !== void 0 && value.length > rule.max) {
+        return `${field} exceeds ${rule.max} entries`;
+      }
+      if (rule.min !== void 0 && value.length < rule.min) {
+        return `${field} must have at least ${rule.min} entries`;
+      }
+      if (rule.items !== void 0) {
+        for (const entry of value) {
+          const reason = checkRule(`${field} entry`, entry, rule.items);
+          if (reason !== null) {
+            return reason;
+          }
+        }
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+function checkSchema(schema, data) {
+  for (const key of Object.keys(schema)) {
+    const rule = schema[key];
+    if (rule === void 0) {
+      continue;
+    }
+    const reason = checkRule(key, data[key], rule);
+    if (reason !== null) {
+      return reason;
+    }
+  }
+  return null;
+}
+function validateSnapshot(payload) {
+  const data = payload;
+  const reason = checkSchema(syncPayloadSchema, data);
+  if (reason !== null) {
+    return reason;
+  }
+  let parsed;
+  try {
+    parsed = new URL(payload.endpointUrl);
+  } catch {
+    return "endpointUrl is not a valid URL";
+  }
+  if (!ALLOWED_ENDPOINT_SCHEMES.has(parsed.protocol)) {
+    return "endpointUrl scheme is not allowed";
+  }
+  const labels = payload.labels;
+  const labelKeys = Object.keys(labels);
+  if (labelKeys.length > MAX_LABELS) {
+    return `labels exceeds ${MAX_LABELS} entries`;
+  }
+  for (const key of labelKeys) {
+    if (key.length > MAX_LABEL_KEY_LENGTH) {
+      return `a label key exceeds ${MAX_LABEL_KEY_LENGTH} characters`;
+    }
+    const value = labels[key];
+    if (typeof value !== "string" || value.length > MAX_LABEL_VALUE_LENGTH) {
+      return `a label value is not a string of at most ${MAX_LABEL_VALUE_LENGTH} characters`;
+    }
+  }
+  const rooms = payload.rooms;
+  for (const entry of rooms) {
+    const id = entry.id;
+    if (typeof id !== "string" || id.length > MAX_ROOM_ID_LENGTH) {
+      return `a room id is not a string of at most ${MAX_ROOM_ID_LENGTH} characters`;
+    }
+    const type = entry.type;
+    if (typeof type !== "string" || type.length > MAX_ROOM_TYPE_LENGTH) {
+      return `a room type is not a string of at most ${MAX_ROOM_TYPE_LENGTH} characters`;
+    }
+    const connections = entry.connections;
+    if (typeof connections !== "number" || connections > MAX_ROOM_CONNECTIONS) {
+      return `a room connections value exceeds ${MAX_ROOM_CONNECTIONS}`;
+    }
+  }
+  return null;
+}
+
+// src/wire/serializer.ts
+import { createRequire } from "module";
+var WIRE_MAJOR = PROTOCOL_VERSION;
+var WIRE_MINOR = 0;
+var HEADER_BYTES = 2;
+var WireVersionError = class extends Error {
+  /** The major byte read off the incompatible frame (123 for a legacy JSON `{...}` frame). */
+  theirVersion;
+  /** This build's protocol major. */
+  ourVersion;
+  constructor(theirVersion) {
+    super(
+      `fleet wire protocol version mismatch: peer speaks major v${theirVersion}, this build speaks v${PROTOCOL_VERSION} \u2014 agents and orchestrator must run the same @rivalis/fleet major (\xA77). A v1 (JSON) peer against a v${PROTOCOL_VERSION} peer is exactly this case; upgrade both halves in lockstep.`
+    );
+    this.name = "WireVersionError";
+    this.theirVersion = theirVersion;
+    this.ourVersion = PROTOCOL_VERSION;
+  }
+};
+var Type = {
+  Label: "Label",
+  SyncRoom: "SyncRoom",
+  Capacity: "Capacity",
+  AckRoom: "AckRoom",
+  Hello: "Hello",
+  Poll: "Poll",
+  State: "State",
+  Cmd: "Cmd",
+  Ack: "Ack"
+};
+var TOPIC_TYPE = {
+  [Topics.hello]: Type.Hello,
+  [Topics.poll]: Type.Poll,
+  [Topics.state]: Type.State,
+  [Topics.cmd]: Type.Cmd,
+  [Topics.ack]: Type.Ack
+};
+var serializer = null;
+function getSerializer() {
+  if (serializer !== null) {
+    return serializer;
+  }
+  const metaUrl = import.meta.url;
+  const req = metaUrl ? createRequire(metaUrl) : __require;
+  const mod = req("@toolcase/serializer");
+  const Serializer = mod.Serializer ?? mod.default;
+  const F = Serializer.FieldType;
+  const s = new Serializer("fleet");
+  s.define(Type.Label, [
+    { key: "key", type: F.STRING, rule: "optional" },
+    { key: "value", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.SyncRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" },
+    { key: "connections", type: F.UINT32, rule: "optional" },
+    { key: "origin", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Capacity, [
+    // null = unlimited (§6). Absent on the wire ⇒ null; an explicit 0 ⇒ 0.
+    { key: "maxConnections", type: F.INT32, rule: "optional", default: null },
+    { key: "maxRooms", type: F.INT32, rule: "optional", default: null }
+  ]);
+  s.define(Type.AckRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Hello, [
+    { key: "instanceId", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "heartbeatMs", type: F.UINT32, rule: "optional" }
+  ]);
+  s.define(Type.Poll, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // Absent ⇒ null (no prior state / forced full, subsumes the old fleet/resync).
+    { key: "knownHash", type: F.STRING, rule: "optional" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.State, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // full=false is a hash-only liveness reply: the snapshot fields below are
+    // omitted on the wire (preserving the old sync/ping dedup, orch-initiated).
+    { key: "full", type: F.BOOL, rule: "optional" },
+    { key: "seq", type: F.UINT32, rule: "optional" },
+    { key: "hash", type: F.STRING, rule: "optional" },
+    { key: "name", type: F.STRING, rule: "optional" },
+    { key: "processUid", type: F.STRING, rule: "optional" },
+    { key: "agentVersion", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "endpointUrl", type: F.STRING, rule: "optional" },
+    { key: "labels", type: Type.Label, rule: "repeated" },
+    { key: "capacity", type: Type.Capacity, rule: "optional" },
+    { key: "autoCreate", type: F.BOOL, rule: "optional" },
+    { key: "roomTypes", type: F.STRING, rule: "repeated" },
+    { key: "rooms", type: Type.SyncRoom, rule: "repeated" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Cmd, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "op", type: F.STRING, rule: "optional" },
+    { key: "roomId", type: F.STRING, rule: "optional" },
+    { key: "roomType", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Ack, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "ok", type: F.BOOL, rule: "optional" },
+    { key: "error", type: F.STRING, rule: "optional" },
+    { key: "alreadyGone", type: F.BOOL, rule: "optional" },
+    { key: "room", type: Type.AckRoom, rule: "optional" },
+    // APPEND-ONLY (task 003): the room-already-exists signal must stay LAST so
+    // existing tags are unmoved (see the append-only tag rule in the file header).
+    { key: "exists", type: F.BOOL, rule: "optional" }
+  ]);
+  serializer = s;
+  return s;
+}
+function present(obj, key) {
+  return obj !== null && obj !== void 0 && Object.prototype.hasOwnProperty.call(obj, key);
+}
+function labelsToList(labels) {
+  return Object.entries(labels ?? {}).map(([key, value]) => ({ key, value }));
+}
+function labelsFromList(list) {
+  const labels = {};
+  for (const entry of list ?? []) {
+    labels[entry.key ?? ""] = entry.value ?? "";
+  }
+  return labels;
+}
+function capacityToMessage(capacity) {
+  return {
+    maxConnections: capacity?.maxConnections ?? null,
+    maxRooms: capacity?.maxRooms ?? null
+  };
+}
+function capacityFromMessage(capacity) {
+  return {
+    // Absent ⇒ null (unlimited, §6); an explicit 0 is preserved as 0.
+    maxConnections: present(capacity, "maxConnections") ? capacity.maxConnections : null,
+    maxRooms: present(capacity, "maxRooms") ? capacity.maxRooms : null
+  };
+}
+function stateToMessage(p) {
+  if (!p.full) {
+    return { reqId: p.reqId, full: false, seq: p.seq, hash: p.hash };
+  }
+  return {
+    reqId: p.reqId,
+    full: true,
+    seq: p.seq,
+    hash: p.hash,
+    name: p.name,
+    processUid: p.processUid,
+    agentVersion: p.agentVersion,
+    protocolVersion: p.protocolVersion,
+    endpointUrl: p.endpointUrl,
+    labels: labelsToList(p.labels),
+    capacity: capacityToMessage(p.capacity),
+    autoCreate: p.autoCreate,
+    roomTypes: p.roomTypes ?? [],
+    rooms: (p.rooms ?? []).map((r) => ({
+      id: r.id,
+      type: r.type,
+      connections: r.connections,
+      origin: r.origin
+    })),
+    status: p.status
+  };
+}
+function stateFromMessage(m) {
+  return {
+    reqId: m.reqId ?? "",
+    full: m.full ?? false,
+    seq: m.seq ?? 0,
+    hash: m.hash ?? "",
+    name: m.name ?? "",
+    processUid: m.processUid ?? "",
+    agentVersion: m.agentVersion ?? "",
+    protocolVersion: m.protocolVersion ?? 0,
+    endpointUrl: m.endpointUrl ?? "",
+    labels: labelsFromList(m.labels),
+    capacity: capacityFromMessage(m.capacity),
+    autoCreate: m.autoCreate ?? false,
+    roomTypes: Array.isArray(m.roomTypes) ? m.roomTypes : [],
+    rooms: (Array.isArray(m.rooms) ? m.rooms : []).map((r) => ({
+      id: r.id ?? "",
+      type: r.type ?? "",
+      connections: r.connections ?? 0,
+      origin: r.origin ?? "local"
+    })),
+    status: m.status ?? "active"
+  };
+}
+function toMessage(topic, payload) {
+  switch (topic) {
+    case Topics.state:
+      return stateToMessage(payload);
+    case Topics.poll: {
+      const p = payload;
+      const msg = { reqId: p.reqId, status: p.status };
+      if (p.knownHash !== null && p.knownHash !== void 0) {
+        msg.knownHash = p.knownHash;
+      }
+      return msg;
+    }
+    default:
+      return payload;
+  }
+}
+function fromMessage(topic, m) {
+  switch (topic) {
+    case Topics.hello:
+      return {
+        instanceId: m.instanceId ?? "",
+        protocolVersion: m.protocolVersion ?? 0,
+        heartbeatMs: m.heartbeatMs ?? 0
+      };
+    case Topics.poll:
+      return {
+        reqId: m.reqId ?? "",
+        // Absent knownHash ⇒ null (no prior state / forced full).
+        knownHash: present(m, "knownHash") ? m.knownHash : null,
+        status: m.status ?? "active"
+      };
+    case Topics.state:
+      return stateFromMessage(m);
+    case Topics.cmd: {
+      const cmd = { cmdId: m.cmdId ?? "", op: m.op };
+      if (present(m, "roomId")) {
+        cmd.roomId = m.roomId;
+      }
+      if (present(m, "roomType")) {
+        cmd.roomType = m.roomType;
+      }
+      return cmd;
+    }
+    case Topics.ack: {
+      const ack = { cmdId: m.cmdId ?? "", ok: m.ok ?? false };
+      if (present(m, "error")) {
+        ack.error = m.error;
+      }
+      if (present(m, "alreadyGone")) {
+        ack.alreadyGone = m.alreadyGone;
+      }
+      if (present(m, "exists")) {
+        ack.exists = m.exists;
+      }
+      if (present(m, "room")) {
+        ack.room = { id: m.room.id ?? "", type: m.room.type ?? "" };
+      }
+      return ack;
+    }
+    default:
+      return m;
+  }
+}
+function encodeFrame(topic, payload) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  const body = getSerializer().encode(type, toMessage(topic, payload));
+  const frame = new Uint8Array(HEADER_BYTES + body.length);
+  frame[0] = WIRE_MAJOR;
+  frame[1] = WIRE_MINOR;
+  frame.set(body, HEADER_BYTES);
+  return frame;
+}
+function decodeFrame(topic, frame) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  if (frame === null || frame === void 0 || frame.length < HEADER_BYTES) {
+    throw new Error("fleet wire: truncated frame (shorter than the 2-byte version header)");
+  }
+  const major = frame[0];
+  if (major !== WIRE_MAJOR) {
+    throw new WireVersionError(major);
+  }
+  const body = frame.subarray(HEADER_BYTES);
+  const decoded = getSerializer().decode(type, body);
+  return fromMessage(topic, decoded);
+}
+
+// src/util/errors.ts
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/orchestrator/CommandEngine.ts
+var CommandEngine = class {
+  constructor(scheduler, reservations, commandTimeoutMs) {
+    this.scheduler = scheduler;
+    this.reservations = reservations;
+    this.commandTimeoutMs = commandTimeoutMs;
+  }
+  scheduler;
+  reservations;
+  commandTimeoutMs;
+  /** Pending commands keyed by instance id, then by `cmdId`. */
+  pending = /* @__PURE__ */ new Map();
+  cmdSeq = 0;
+  /** Monotonic command id (`cmd_N`) — connection-agnostic, unique per orchestrator. */
+  nextCmdId() {
+    return `cmd_${++this.cmdSeq}`;
+  }
+  /** How many commands are currently in flight for an instance. */
+  inFlight(instanceId) {
+    return this.pending.get(instanceId)?.size ?? 0;
+  }
+  /**
+   * Push a `fleet/cmd` and return a promise that resolves on its `fleet/ack`
+   * (rejects on `COMMAND_FAILED`), or rejects on timeout (`COMMAND_TIMEOUT`) /
+   * disconnect (`INSTANCE_DISCONNECTED`). Caps in-flight commands per instance at
+   * {@link MAX_INFLIGHT_COMMANDS} → `INSTANCE_BUSY` rather than queueing unbounded
+   * promises behind a slow agent (§7). Reservations (create only) ride on the
+   * pending entry and are released on every settle path.
+   */
+  send(link, cmd, reservation = null, roomIdReservation = null) {
+    const map = this.mapFor(link.instanceId);
+    if (map.size >= MAX_INFLIGHT_COMMANDS) {
+      if (reservation !== null) {
+        this.reservations.release(reservation);
+      }
+      if (roomIdReservation !== null) {
+        this.reservations.releaseRoomId(roomIdReservation);
+      }
+      return Promise.reject(new FleetError(
+        "INSTANCE_BUSY",
+        `instance ${link.instanceId} has ${map.size} commands in flight (max ${MAX_INFLIGHT_COMMANDS})`
+      ));
+    }
+    return new Promise((resolve, reject) => {
+      const timer = this.scheduler.setTimeout(() => {
+        this.settle(link.instanceId, cmd.cmdId, (pending) => {
+          this.holdOrRelease(pending);
+          pending.reject(new FleetError(
+            "COMMAND_TIMEOUT",
+            `command ${cmd.cmdId} (${cmd.op}) timed out after ${this.commandTimeoutMs}ms`
+          ));
+        });
+      }, this.commandTimeoutMs);
+      map.set(cmd.cmdId, { resolve, reject, timer, reservation, roomIdReservation });
+      try {
+        link.send(Topics.cmd, cmd);
+      } catch (error) {
+        this.settle(link.instanceId, cmd.cmdId, (pending) => {
+          this.releaseReservations(pending);
+          pending.reject(new FleetError(
+            "INSTANCE_DISCONNECTED",
+            `failed to send command ${cmd.cmdId} (${cmd.op}) to instance ${link.instanceId}: ${describe(error)}`
+          ));
+        });
+      }
+    });
+  }
+  /**
+   * Resolve/reject the originating promise for an inbound `fleet/ack`. Returns
+   * `false` when no such pending exists (a late ack after a timeout, or an unknown
+   * cmd) so the caller can log-and-drop — never a double-resolve (§14).
+   */
+  ack(instanceId, ack) {
+    return this.settle(instanceId, ack.cmdId, (pending) => {
+      if (ack.ok) {
+        this.holdOrRelease(pending);
+        pending.resolve(ack);
+      } else {
+        this.releaseReservations(pending);
+        pending.reject(ack.exists === true ? new FleetError("ROOM_EXISTS", ack.error ?? "room id already exists") : new FleetError("COMMAND_FAILED", ack.error ?? "agent reported command failure"));
+      }
+    });
+  }
+  /**
+   * Reject every in-flight command for a disconnected/evicted instance immediately
+   * with `INSTANCE_DISCONNECTED` — callers never wait out `commandTimeoutMs` for an
+   * instance the orchestrator already knows is gone (§7).
+   */
+  rejectAll(instanceId, reason) {
+    const map = this.pending.get(instanceId);
+    if (map === void 0) {
+      return;
+    }
+    for (const cmdId of [...map.keys()]) {
+      this.settle(instanceId, cmdId, (pending) => {
+        this.releaseReservations(pending);
+        pending.reject(new FleetError("INSTANCE_DISCONNECTED", `instance ${instanceId} disconnected (${reason})`));
+      });
+    }
+    this.pending.delete(instanceId);
+  }
+  /**
+   * Settle exactly one pending command: delete it and clear its timer, then run
+   * `action` (which disposes the reservations — release or {@link holdOrRelease} —
+   * and resolves/rejects). Returns `false` when no such pending exists (already
+   * settled) — the single guard against double-resolve from a timeout-then-late-ack
+   * or disconnect-then-ack race (§14). Reservation disposition moved into the per-path
+   * `action` callbacks (task 003): ack-OK / timeout hold until visible, every other
+   * path releases.
+   */
+  settle(instanceId, cmdId, action) {
+    const map = this.pending.get(instanceId);
+    const pending = map?.get(cmdId);
+    if (map === void 0 || pending === void 0) {
+      return false;
+    }
+    map.delete(cmdId);
+    this.scheduler.clearTimeout(pending.timer);
+    action(pending);
+    return true;
+  }
+  /**
+   * Hold a create's reservations until its room is visible (task 003) — used on
+   * ack-OK and timeout. A create carries BOTH a capacity and a room-id reservation;
+   * any other command (destroy/drain/undrain) carries neither, so this degrades to a
+   * release of whatever (if anything) is present.
+   */
+  holdOrRelease(pending) {
+    if (pending.reservation !== null && pending.roomIdReservation !== null) {
+      this.reservations.holdUntilVisible(pending.roomIdReservation, pending.reservation);
+    } else {
+      this.releaseReservations(pending);
+    }
+  }
+  /** Release a settled command's reservations immediately (failure / disconnect / busy). */
+  releaseReservations(pending) {
+    if (pending.reservation !== null) {
+      this.reservations.release(pending.reservation);
+    }
+    if (pending.roomIdReservation !== null) {
+      this.reservations.releaseRoomId(pending.roomIdReservation);
+    }
+  }
+  mapFor(instanceId) {
+    let map = this.pending.get(instanceId);
+    if (map === void 0) {
+      map = /* @__PURE__ */ new Map();
+      this.pending.set(instanceId, map);
+    }
+    return map;
+  }
+};
+
+// src/orchestrator/Poller.ts
+var FORCE_FULL_EVERY_POLLS = 12;
+var Poller = class {
+  constructor(scheduler, intervalMs, callbacks) {
+    this.scheduler = scheduler;
+    this.intervalMs = intervalMs;
+    this.callbacks = callbacks;
+  }
+  scheduler;
+  intervalMs;
+  callbacks;
+  entries = /* @__PURE__ */ new Map();
+  reqSeq = 0;
+  /** True while the instance is being polled (started and not yet forgotten). */
+  has(instanceId) {
+    return this.entries.has(instanceId);
+  }
+  /** Begin polling an instance: send the first poll now, then one every `intervalMs`. */
+  start(instanceId) {
+    this.entries.set(instanceId, { timer: null, outstandingReqId: null, missed: 0, pollCount: 0 });
+    this.poll(instanceId);
+    this.schedule(instanceId);
+  }
+  /**
+   * Consume the outstanding poll's reply (§7 enforcement). Returns `true` when
+   * `reqId` matches the in-flight poll (resets the missed counter); `false` when it
+   * matches no outstanding poll — an unsolicited / duplicate / post-settle
+   * `fleet/state`, which the caller turns into a kick.
+   */
+  reply(instanceId, reqId) {
+    const entry = this.entries.get(instanceId);
+    if (entry === void 0 || entry.outstandingReqId === null || entry.outstandingReqId !== reqId) {
+      return false;
+    }
+    entry.outstandingReqId = null;
+    entry.missed = 0;
+    return true;
+  }
+  /** Stop polling an instance and cancel its timer (teardown). Idempotent. */
+  forget(instanceId) {
+    const entry = this.entries.get(instanceId);
+    if (entry !== void 0) {
+      this.scheduler.clearTimeout(entry.timer);
+      this.entries.delete(instanceId);
+    }
+  }
+  schedule(instanceId) {
+    const entry = this.entries.get(instanceId);
+    if (entry === void 0) {
+      return;
+    }
+    entry.timer = this.scheduler.setTimeout(() => this.tick(instanceId), this.intervalMs);
+  }
+  tick(instanceId) {
+    const entry = this.entries.get(instanceId);
+    if (entry === void 0) {
+      return;
+    }
+    if (entry.outstandingReqId !== null) {
+      entry.missed += 1;
+      if (entry.missed === 2) {
+        this.callbacks.onStale(instanceId);
+      }
+      if (entry.missed >= 3) {
+        this.callbacks.onEvict(instanceId);
+        return;
+      }
+      this.schedule(instanceId);
+      return;
+    }
+    this.poll(instanceId);
+    this.schedule(instanceId);
+  }
+  poll(instanceId) {
+    const entry = this.entries.get(instanceId);
+    if (entry === void 0) {
+      return;
+    }
+    const reqId = `poll_${++this.reqSeq}`;
+    const forceFull = entry.pollCount % FORCE_FULL_EVERY_POLLS === 0;
+    entry.pollCount += 1;
+    entry.outstandingReqId = reqId;
+    this.callbacks.sendPoll(instanceId, reqId, forceFull);
+  }
+};
+
+// src/orchestrator/EventReconciler.ts
+var EventReconciler = class {
+  constructor(state, emit) {
+    this.state = state;
+    this.emit = emit;
+  }
+  state;
+  emit;
+  knownInstanceIds = /* @__PURE__ */ new Set();
+  knownRooms = /* @__PURE__ */ new Map();
+  lastStatsHash = "";
+  /**
+   * Diff the read model and emit the derived events: `instance:join` for a new
+   * instance, `room:create`/`room:destroy` for room churn, and `sync` whenever the
+   * semantic `stateHash` changes. `instance:leave` is emitted by
+   * {@link instanceRemoved}, not here.
+   */
+  reconcile() {
+    const instances = this.state.instances;
+    const currentInstanceIds = /* @__PURE__ */ new Set();
+    const currentRoomIds = /* @__PURE__ */ new Set();
+    for (const instance of instances) {
+      currentInstanceIds.add(instance.id);
+      if (!this.knownInstanceIds.has(instance.id)) {
+        this.knownInstanceIds.add(instance.id);
+        this.emit("instance:join", instance);
+      }
+      for (const room of instance.rooms) {
+        currentRoomIds.add(room.id);
+        if (!this.knownRooms.has(room.id)) {
+          this.knownRooms.set(room.id, room);
+          this.emit("room:create", room);
+        }
+      }
+    }
+    for (const [roomId, room] of [...this.knownRooms]) {
+      if (!currentRoomIds.has(roomId)) {
+        this.knownRooms.delete(roomId);
+        this.emit("room:destroy", room);
+      }
+    }
+    for (const id of [...this.knownInstanceIds]) {
+      if (!currentInstanceIds.has(id)) {
+        this.knownInstanceIds.delete(id);
+      }
+    }
+    const stats = this.state.stats;
+    if (stats.stateHash !== this.lastStatsHash) {
+      this.lastStatsHash = stats.stateHash;
+      this.emit("sync", stats);
+    }
+  }
+  /**
+   * An instance was removed from the read model (socket close or eviction): forget
+   * it and emit `instance:leave`. The caller follows with a {@link reconcile} so the
+   * vanished instance's rooms surface as `room:destroy` and the `sync` fires.
+   */
+  instanceRemoved(removed) {
+    this.knownInstanceIds.delete(removed.id);
+    this.emit("instance:leave", removed);
+  }
+};
+
+// src/orchestrator/FleetControl.ts
+var FleetControl = class {
+  constructor(state, commands, getLink) {
+    this.state = state;
+    this.commands = commands;
+    this.getLink = getLink;
+  }
+  state;
+  commands;
+  getLink;
+  /** Place a new room and push an acknowledged `create` command (§9 command flow). */
+  async createRoom(request) {
+    const roomIdReservation = this.state.reserveRoomId(request.roomId);
+    let placement;
+    try {
+      placement = this.state.place({ type: request.type, ...request.placement ?? {} });
+    } catch (error) {
+      this.state.releaseRoomId(roomIdReservation);
+      throw error;
+    }
+    const link = this.getLink(placement.instance.id);
+    if (link === void 0) {
+      this.state.release(placement.reservation);
+      this.state.releaseRoomId(roomIdReservation);
+      throw new FleetError("INSTANCE_DISCONNECTED", `instance ${placement.instance.id} is no longer connected`);
+    }
+    const cmd = {
+      cmdId: this.commands.nextCmdId(),
+      op: "create",
+      roomId: roomIdReservation.roomId,
+      roomType: request.type
+    };
+    await this.commands.send(link, cmd, placement.reservation, roomIdReservation);
+    return {
+      id: roomIdReservation.roomId,
+      type: request.type,
+      connections: 0,
+      instanceId: placement.instance.id,
+      endpointUrl: placement.instance.endpointUrl,
+      local: false
+    };
+  }
+  /** Destroy a room by its fleet-unique public id; the orchestrator resolves the owner (§9, §10). */
+  async destroyRoom(roomId) {
+    const located = this.state.resolveRoom(roomId);
+    if (located === null) {
+      throw new FleetError("ROOM_NOT_FOUND", `room ${roomId} not found`);
+    }
+    const link = this.getLink(located.instanceId);
+    if (link === void 0) {
+      throw new FleetError("INSTANCE_DISCONNECTED", `instance ${located.instanceId} is no longer connected`);
+    }
+    await this.commands.send(link, { cmdId: this.commands.nextCmdId(), op: "destroy", roomId: located.rawRoomId });
+  }
+  /** Ask an instance to drain via `fleet/cmd {op:'drain'}` — the agent owns status (§7). */
+  drainInstance(instanceId) {
+    return this.sendStatusCommand(instanceId, "drain");
+  }
+  /** Reverse of {@link drainInstance}. */
+  undrainInstance(instanceId) {
+    return this.sendStatusCommand(instanceId, "undrain");
+  }
+  async sendStatusCommand(instanceId, op) {
+    if (this.state.getInstance(instanceId) === null) {
+      throw new FleetError("INSTANCE_NOT_FOUND", `instance ${instanceId} not found`);
+    }
+    const link = this.getLink(instanceId);
+    if (link === void 0) {
+      throw new FleetError("INSTANCE_DISCONNECTED", `instance ${instanceId} is no longer connected`);
+    }
+    await this.commands.send(link, { cmdId: this.commands.nextCmdId(), op });
+    this.state.setPendingStatus(instanceId, op === "drain" ? "draining" : "active");
+  }
+};
+
+// src/orchestrator/transport.ts
+import { createServer } from "http";
+import { WSTransport } from "@rivalis/node";
+
+// src/orchestrator/FleetRoom.ts
+var AGENT_TOPICS = [Topics.state, Topics.ack];
+function createFleetRoomClass(core, controller) {
+  const Base = core.Room;
+  class FleetRoom extends Base {
+    // Strict request/reply (task 011): an unbound topic is an unsolicited frame
+    // → kick. Supersedes the pre-011 'drop' forward-compat stance (§7).
+    unknownTopicPolicy = "kick";
+    onCreate() {
+      const room = this;
+      for (const topic of AGENT_TOPICS) {
+        room.bind(topic, (actor, payload) => {
+          controller.handleAgentMessage(actor.id, topic, payload);
+        });
+      }
+    }
+    onJoin(actor) {
+      controller.handleAgentJoin(this.linkFor(actor));
+    }
+    onLeave(actor) {
+      controller.handleAgentLeave(actor.id);
+    }
+    /** Wrap an actor as an {@link AgentLink}; `send`/`kick` are core `Room` methods. */
+    linkFor(actor) {
+      const room = this;
+      return {
+        instanceId: actor.id,
+        send: (topic, payload) => {
+          room.send(actor, topic, encodeFrame(topic, payload));
+        },
+        close: () => {
+          room.kick(actor);
+        }
+      };
+    }
+  }
+  return FleetRoom;
+}
+
+// src/orchestrator/transport.ts
+var FLEET_ROOM_TYPE = "@rivalis/fleet";
+var FLEET_ROOM_ID = "fleet";
+var MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024;
+var HEADERS_TIMEOUT_MS = 1e4;
+var REQUEST_TIMEOUT_MS = 3e4;
+function selectSubprotocol(protocols) {
+  if (protocols.has(WS_SUBPROTOCOL)) {
+    return WS_SUBPROTOCOL;
+  }
+  for (const protocol of protocols) {
+    return protocol;
+  }
+  return false;
+}
+function controlPlaneRateLimiterOptions() {
+  const maxOutstanding = MAX_INFLIGHT_COMMANDS + 1;
+  return {
+    capacity: 2 * maxOutstanding,
+    refillPerSecond: maxOutstanding
+  };
+}
+function createSharedHttpServer(handler) {
+  const server = createServer((req, res) => handler(req, res));
+  server.headersTimeout = HEADERS_TIMEOUT_MS;
+  server.requestTimeout = REQUEST_TIMEOUT_MS;
+  return server;
+}
+function attachControlPlane(core, httpServer, deps) {
+  class FleetAuth extends core.AuthMiddleware {
+    async authenticate(ticket) {
+      return deps.authenticator.matches(ticket) ? { data: null, roomId: FLEET_ROOM_ID } : null;
+    }
+  }
+  const transport = new WSTransport(
+    { server: httpServer },
+    null,
+    { ticketSource: "protocol", maxPayload: MAX_SNAPSHOT_BYTES }
+  );
+  const wss = transport.ws;
+  if (wss?.options !== void 0) {
+    wss.options.handleProtocols = (protocols) => {
+      const selected = selectSubprotocol(protocols);
+      if (selected !== false && selected !== WS_SUBPROTOCOL) {
+        deps.logger.warning(
+          `fleet: WS 101 fell back to echoing a client-offered subprotocol that is not the '${WS_SUBPROTOCOL}' sentinel \u2014 this round-trips the connection ticket (agent key) into the response headers (\xA713). Upgrade the agent client to offer the sentinel. (value not logged)`
+        );
+      }
+      return selected;
+    };
+  } else {
+    deps.logger.warning("fleet: could not install WS subprotocol selector \u2014 101 may echo the ticket (\xA713)");
+  }
+  const rivalis = new core.Rivalis({
+    transports: [transport],
+    authMiddleware: new FleetAuth(),
+    rateLimiter: new core.TokenBucketRateLimiter(controlPlaneRateLimiterOptions())
+  });
+  const FleetRoomClass = createFleetRoomClass(core, deps.controller);
+  rivalis.rooms.define(FLEET_ROOM_TYPE, FleetRoomClass);
+  rivalis.rooms.create(FLEET_ROOM_TYPE, FLEET_ROOM_ID);
+  return rivalis;
+}
+
+// src/env.ts
+function env(key, defaultValue = null, type = "string") {
+  if (typeof process === "undefined") {
+    throw new Error("env works only with NodeJS");
+  }
+  const value = process.env[key];
+  if (type === "number") {
+    if (value === void 0) {
+      return defaultValue;
+    }
+    const numberValue = parseInt(value, 10);
+    return numberValue.toString() === value ? numberValue : defaultValue;
+  }
+  if (type === "boolean") {
+    const boolValue = `${value}`.toLowerCase();
+    if (boolValue === "true") {
+      return true;
+    }
+    if (boolValue === "false") {
+      return false;
+    }
+    return defaultValue;
+  }
+  return value !== void 0 ? value : defaultValue;
+}
+function nodeEnv() {
+  return env("NODE_ENV");
+}
+
+// src/routers/index.ts
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import { Router } from "@toolcase/node";
+
+// src/routers/shared.ts
+import { createHash as createHash3 } from "crypto";
+import { HTTP } from "@toolcase/base";
+import { errorMeta } from "@toolcase/node";
+var MAX_BODY_BYTES = 64 * 1024;
+var SSE_PING_MS = 15e3;
+var AUTH_FAILURE_LIMIT = 10;
+var AUTH_FAILURE_WINDOW_MS = 6e4;
+var MAX_SSE_STREAMS = 100;
+var MAX_THROTTLE_BUCKETS = 4096;
+function createContext(deps) {
+  const now = deps.now ?? Date.now;
+  return {
+    deps,
+    throttle: new AuthThrottle(AUTH_FAILURE_LIMIT, AUTH_FAILURE_WINDOW_MS, now),
+    streams: /* @__PURE__ */ new Set(),
+    pingMs: deps.ssePingMs ?? SSE_PING_MS,
+    maxStreams: deps.maxSseStreams ?? MAX_SSE_STREAMS,
+    authInfo: /* @__PURE__ */ new WeakMap()
+  };
+}
+function restOk(reply, data, status = HTTP.Status.OK) {
+  reply.code(status);
+  return new HTTP.RESTResponse(status, data);
+}
+function restError(reply, status, cause) {
+  reply.code(status);
+  return new HTTP.RESTError(status, cause).toJSON();
+}
+function installErrorHandlers(fastify, getLogger) {
+  fastify.setNotFoundHandler((req, reply) => restError(reply, HTTP.Status.NOT_FOUND, "NOT_FOUND"));
+  fastify.setErrorHandler((error, req, reply) => {
+    const meta = errorMeta(error);
+    if (meta !== null) {
+      return restError(reply, meta.status, meta.code ?? "INTERNAL");
+    }
+    const status = error.statusCode;
+    if (status === HTTP.Status.PAYLOAD_TOO_LARGE) {
+      return restError(reply, HTTP.Status.PAYLOAD_TOO_LARGE, "PAYLOAD_TOO_LARGE");
+    }
+    if (typeof status === "number" && status >= 400 && status < 500) {
+      return restError(reply, status, "VALIDATION");
+    }
+    getLogger().error(`unhandled error on ${req.method} ${pathOf(req)}: ${describe(error)}`);
+    return restError(reply, HTTP.Status.INTERNAL_SERVER_ERROR, "INTERNAL");
+  });
+}
+function sendConditional(req, reply, deps, data) {
+  const etag = weakEtag(deps.fleet.stats.stateHash);
+  reply.header("etag", etag);
+  if (ifNoneMatchMatches(req, etag)) {
+    reply.code(HTTP.Status.NOT_MODIFIED);
+    return null;
+  }
+  return restOk(reply, data);
+}
+function weakEtag(stateHash) {
+  return `W/"${stateHash}"`;
+}
+function ifNoneMatchMatches(req, etag) {
+  const header = req.headers["if-none-match"];
+  if (typeof header !== "string") {
+    return false;
+  }
+  if (header.trim() === "*") {
+    return true;
+  }
+  return header.split(",").some((candidate) => candidate.trim() === etag);
+}
+function bearerToken(req) {
+  const header = req.headers["authorization"];
+  if (typeof header !== "string") {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match === null ? null : match[1];
+}
+function fingerprint(key) {
+  return "key#" + createHash3("sha256").update(key).digest("hex").slice(0, 8);
+}
+function remoteIp(req) {
+  return req.ip ?? "unknown";
+}
+function pathOf(req) {
+  const url = req.url;
+  const q = url.indexOf("?");
+  return q === -1 ? url : url.slice(0, q);
+}
+function isEventsPath(req) {
+  return req.method === "GET" && pathOf(req) === "/v1/events";
+}
+function isMutatingRoute(req) {
+  const path = pathOf(req);
+  if (req.method === "POST" && path === "/v1/rooms") {
+    return true;
+  }
+  if (req.method === "DELETE" && /^\/v1\/rooms\/.+$/.test(path)) {
+    return true;
+  }
+  if (req.method === "POST" && /^\/v1\/instances\/[^/]+\/(drain|undrain)$/.test(path)) {
+    return true;
+  }
+  return false;
+}
+async function authHook(ctx, req) {
+  const ip = remoteIp(req);
+  const path = pathOf(req);
+  if (ctx.throttle.blocked(ip)) {
+    ctx.deps.getLogger().warning(`auth throttled ip=${ip} route=${req.method} ${path}`);
+    throw new FleetError("AUTH_THROTTLED", "too many failed authentication attempts");
+  }
+  let matched = matchKey(bearerToken(req), ctx.deps.config.adminKeys);
+  if (matched === null && isEventsPath(req) && ctx.deps.config.sseQueryAuth) {
+    const queryKey = req.query?.["key"];
+    if (typeof queryKey === "string") {
+      matched = matchKey(queryKey, ctx.deps.config.adminKeys);
+    }
+  }
+  if (matched === null) {
+    ctx.throttle.recordFailure(ip);
+    ctx.deps.getLogger().warning(`auth failure ip=${ip} route=${req.method} ${path}`);
+    throw new FleetError("UNAUTHORIZED", "missing or invalid admin key");
+  }
+  ctx.authInfo.set(req, { fingerprint: fingerprint(matched), ip });
+}
+async function auditHook(ctx, req, reply) {
+  if (!isMutatingRoute(req)) {
+    return;
+  }
+  const info = ctx.authInfo.get(req);
+  ctx.deps.getLogger().info(
+    `audit route=${req.method} ${pathOf(req)} key=${info?.fingerprint ?? "unknown"} ip=${info?.ip ?? remoteIp(req)} outcome=${reply.statusCode}`
+  );
+}
+function corsHeadersForSse(req, cors2) {
+  if (cors2 === false) {
+    return {};
+  }
+  const origin = req.headers["origin"];
+  if (typeof origin !== "string") {
+    return {};
+  }
+  if (cors2.origins.includes("*")) {
+    return { "access-control-allow-origin": "*" };
+  }
+  if (cors2.origins.includes(origin)) {
+    return { "access-control-allow-origin": origin, vary: "Origin" };
+  }
+  return {};
+}
+var AuthThrottle = class {
+  constructor(limit, windowMs, now, maxBuckets = MAX_THROTTLE_BUCKETS) {
+    this.limit = limit;
+    this.windowMs = windowMs;
+    this.now = now;
+    this.maxBuckets = maxBuckets;
+  }
+  limit;
+  windowMs;
+  now;
+  maxBuckets;
+  buckets = /* @__PURE__ */ new Map();
+  /** Wall-clock of the last opportunistic sweep; gates pruning to once per window. */
+  lastPruneAt = -Infinity;
+  /** True when the IP is over its failed-auth budget (no tokens left). */
+  blocked(ip) {
+    return this.refill(ip).tokens < 1;
+  }
+  /** Charge one token for a failed attempt (floored at zero). */
+  recordFailure(ip) {
+    const bucket = this.refill(ip);
+    bucket.tokens = Math.max(0, bucket.tokens - 1);
+  }
+  /** Current bucket count — a test seam for the §13 memory-bound assertions. */
+  get size() {
+    return this.buckets.size;
+  }
+  refill(ip) {
+    const now = this.now();
+    this.prune(now);
+    let bucket = this.buckets.get(ip);
+    if (bucket === void 0) {
+      bucket = { tokens: this.limit, last: now };
+      this.buckets.set(ip, bucket);
+      this.evictIfOver();
+      return bucket;
+    }
+    const elapsed = now - bucket.last;
+    if (elapsed > 0) {
+      bucket.tokens = Math.min(this.limit, bucket.tokens + elapsed / this.windowMs * this.limit);
+      bucket.last = now;
+    }
+    return bucket;
+  }
+  /**
+   * Opportunistic sweep (≤ once per window): delete every bucket that has fully
+   * refilled and not been touched within the last window. Such a bucket holds no
+   * information — a fresh IP starts full — so removing it cannot un-throttle anyone.
+   * Computing the *refilled* token count (not the stored one) also reclaims buckets
+   * stuck below full only because the IP never returned after a single failure.
+   */
+  prune(now) {
+    if (now - this.lastPruneAt < this.windowMs) {
+      return;
+    }
+    this.lastPruneAt = now;
+    for (const [ip, bucket] of this.buckets) {
+      const elapsed = now - bucket.last;
+      if (elapsed <= this.windowMs) {
+        continue;
+      }
+      const refilled = Math.min(this.limit, bucket.tokens + elapsed / this.windowMs * this.limit);
+      if (refilled >= this.limit) {
+        this.buckets.delete(ip);
+      }
+    }
+  }
+  /** Hard cap: when over {@link maxBuckets}, evict the oldest-touched bucket. */
+  evictIfOver() {
+    if (this.buckets.size <= this.maxBuckets) {
+      return;
+    }
+    let oldestIp = null;
+    let oldest = Infinity;
+    for (const [ip, bucket] of this.buckets) {
+      if (bucket.last < oldest) {
+        oldest = bucket.last;
+        oldestIp = ip;
+      }
+    }
+    if (oldestIp !== null) {
+      this.buckets.delete(oldestIp);
+    }
+  }
+};
+
+// src/routers/HealthRouter.ts
+import { RouteHandler } from "@toolcase/node";
+import { HTTP as HTTP2 } from "@toolcase/base";
+var HealthRouter = class extends RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/healthz", async (_req, reply) => restOk(reply));
+    fastify.get("/readyz", async (_req, reply) => {
+      if (this.ctx.deps.isReady()) {
+        return restOk(reply);
+      }
+      return restError(reply, HTTP2.Status.SERVICE_UNAVAILABLE, "NOT_READY");
+    });
+  }
+};
+
+// src/routers/StatsRouter.ts
+import { RouteHandler as RouteHandler2 } from "@toolcase/node";
+var StatsRouter = class extends RouteHandler2 {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/stats", async (req, reply) => sendConditional(req, reply, this.ctx.deps, this.ctx.deps.fleet.stats));
+  }
+};
+
+// src/routers/InstancesRouter.ts
+import { RouteHandler as RouteHandler3 } from "@toolcase/node";
+var InstancesRouter = class extends RouteHandler3 {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    const deps = this.ctx.deps;
+    fastify.get("/instances", async (req, reply) => sendConditional(req, reply, deps, deps.fleet.instances));
+    fastify.get("/instances/:id", async (req, reply) => {
+      const id = paramId(req);
+      const instance = deps.fleet.getInstance(id);
+      if (instance === null) {
+        throw new FleetError("INSTANCE_NOT_FOUND", `instance ${id} not found`);
+      }
+      return restOk(reply, instance);
+    });
+    fastify.get("/instances/:id/rooms", async (req, reply) => {
+      const id = paramId(req);
+      if (deps.fleet.getInstance(id) === null) {
+        throw new FleetError("INSTANCE_NOT_FOUND", `instance ${id} not found`);
+      }
+      return restOk(reply, deps.fleet.findRooms({ instanceId: id }));
+    });
+    fastify.post("/instances/:id/drain", async (req, reply) => {
+      await deps.fleet.drainInstance(paramId(req));
+      return restOk(reply);
+    });
+    fastify.post("/instances/:id/undrain", async (req, reply) => {
+      await deps.fleet.undrainInstance(paramId(req));
+      return restOk(reply);
+    });
+  }
+};
+function paramId(req) {
+  return req.params.id;
+}
+
+// src/routers/RoomsRouter.ts
+import { RouteHandler as RouteHandler4, deriveJsonSchema } from "@toolcase/node";
+import { HTTP as HTTP3 } from "@toolcase/base";
+var roomCreateBodySchema = deriveJsonSchema(roomCreateSchema, "create");
+var RoomsRouter = class extends RouteHandler4 {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    const deps = this.ctx.deps;
+    fastify.get("/rooms", async (req, reply) => sendConditional(req, reply, deps, deps.fleet.findRooms(roomFilter(req))));
+    fastify.post("/rooms", { schema: { body: roomCreateBodySchema } }, async (req, reply) => {
+      const created = await deps.fleet.createRoom(
+        req.body
+      );
+      return restOk(reply, created, HTTP3.Status.CREATED);
+    });
+    fastify.get("/rooms/:roomId", async (req, reply) => {
+      const roomId = publicRoomId(req);
+      const room = deps.fleet.getRoom(roomId);
+      if (room === null) {
+        throw new FleetError("ROOM_NOT_FOUND", `room ${roomId} not found`);
+      }
+      return restOk(reply, room);
+    });
+    fastify.delete("/rooms/:roomId", async (req, reply) => {
+      await deps.fleet.destroyRoom(publicRoomId(req));
+      return restOk(reply);
+    });
+  }
+};
+function roomFilter(req) {
+  const query = req.query ?? {};
+  const filter = {};
+  if (typeof query.type === "string") {
+    filter.type = query.type;
+  }
+  if (typeof query.instanceId === "string") {
+    filter.instanceId = query.instanceId;
+  }
+  const raw = query.label;
+  const labelParams = Array.isArray(raw) ? raw : raw !== void 0 ? [raw] : [];
+  if (labelParams.length > 0) {
+    const labels = {};
+    for (const entry of labelParams) {
+      if (typeof entry !== "string") {
+        continue;
+      }
+      const idx = entry.indexOf(":");
+      if (idx > 0) {
+        labels[entry.slice(0, idx)] = entry.slice(idx + 1);
+      }
+    }
+    filter.labels = labels;
+  }
+  return filter;
+}
+function publicRoomId(req) {
+  const path = pathnameOf(req);
+  const segments = path.split("/");
+  return segments[segments.length - 1] ?? "";
+}
+function pathnameOf(req) {
+  const url = req.url;
+  const q = url.indexOf("?");
+  return q === -1 ? url : url.slice(0, q);
+}
+
+// src/routers/EventsRouter.ts
+import { RouteHandler as RouteHandler5 } from "@toolcase/node";
+var EventsRouter = class extends RouteHandler5 {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/events", async (req, reply) => this.stream(req, reply));
+  }
+  stream(req, reply) {
+    const ctx = this.ctx;
+    if (ctx.streams.size >= ctx.maxStreams) {
+      ctx.deps.getLogger().warning(
+        `sse stream cap reached (${ctx.maxStreams}) \u2014 rejecting new stream from ip=${remoteIp(req)}`
+      );
+      throw new FleetError("SSE_LIMIT", `concurrent SSE stream cap reached (${ctx.maxStreams})`);
+    }
+    reply.hijack();
+    const raw = reply.raw;
+    raw.writeHead(200, {
+      ...corsHeadersForSse(req, ctx.deps.config.cors),
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      // No Last-Event-ID replay (§10): a reconnecting consumer re-GETs stats+instances.
+      "x-accel-buffering": "no"
+    });
+    const write = (chunk) => {
+      if (raw.writableEnded || raw.destroyed) {
+        return;
+      }
+      try {
+        raw.write(chunk);
+      } catch {
+      }
+    };
+    write(": connected\n\n");
+    const unsubscribe = ctx.deps.subscribe((event) => {
+      write(`event: ${event.type}
+data: ${JSON.stringify(event.data ?? null)}
+
+`);
+    });
+    const ping = setInterval(() => write(": ping\n\n"), ctx.pingMs);
+    ping.unref?.();
+    const stream = {
+      end: () => {
+        if (!raw.writableEnded) {
+          raw.end();
+        }
+      },
+      cleanup: () => {
+        clearInterval(ping);
+        unsubscribe();
+        ctx.streams.delete(stream);
+      }
+    };
+    ctx.streams.add(stream);
+    req.raw.on("close", () => stream.cleanup());
+  }
+};
+
+// src/routers/index.ts
+function createHttpApi(deps, options = {}) {
+  const ctx = createContext(deps);
+  const base = { logger: false, bodyLimit: MAX_BODY_BYTES, trustProxy: deps.config.trustProxy };
+  const fastify = options.serverFactory !== void 0 ? Fastify({ ...base, serverFactory: options.serverFactory }) : Fastify({ ...base });
+  installErrorHandlers(fastify, deps.getLogger);
+  if (deps.config.cors !== false) {
+    const origins = deps.config.cors.origins;
+    void fastify.register(cors, { origin: origins.includes("*") ? "*" : origins });
+  }
+  new HealthRouter(ctx).register(fastify);
+  if (deps.config.api) {
+    void fastify.register(async (v1) => {
+      v1.addHook("onRequest", (req) => authHook(ctx, req));
+      v1.addHook("onResponse", (req, reply) => auditHook(ctx, req, reply));
+      new Router().add(new StatsRouter(ctx)).add(new InstancesRouter(ctx)).add(new RoomsRouter(ctx)).add(new EventsRouter(ctx)).register(v1);
+    }, { prefix: "/v1" });
+  }
+  const drainStreams = () => {
+    for (const stream of [...ctx.streams]) {
+      stream.cleanup();
+      stream.end();
+    }
+  };
+  return {
+    fastify,
+    ready: async () => {
+      await fastify.ready();
+    },
+    listen: async (opts) => {
+      await fastify.listen(opts);
+    },
+    shutdown: drainStreams,
+    close: async () => {
+      drainStreams();
+      await fastify.close();
+    }
+  };
+}
+
+// src/util/loadCore.ts
+import { createRequire as createRequire2 } from "module";
+function loadCore() {
+  const metaUrl = import.meta.url;
+  const req = metaUrl ? createRequire2(metaUrl) : __require;
+  return req("@rivalis/core");
+}
+
+// src/util/scheduler.ts
+var defaultScheduler = {
+  setTimeout: (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    t.unref?.();
+    return t;
+  },
+  clearTimeout: (h) => clearTimeout(h),
+  setInterval: (fn, ms) => {
+    const t = setInterval(fn, ms);
+    t.unref?.();
+    return t;
+  },
+  clearInterval: (h) => clearInterval(h)
+};
+
+// src/orchestrator/Orchestrator.ts
+var Orchestrator = class extends Broadcast {
+  fleet;
+  config;
+  state;
+  now;
+  logger;
+  /** `fleet:http` logger; NOOP until `listen()` loads core's logging factory. */
+  httpLogger;
+  /** Fastify-based REST /v1 surface over the same `node:http` server (§10, task 006). */
+  httpApi;
+  // Injected collaborators (§15) — each a separately unit-tested concern.
+  auth;
+  commands;
+  poller;
+  reconciler;
+  control;
+  /** Live agent links keyed by connection-scoped instance id. */
+  links = /* @__PURE__ */ new Map();
+  rivalis = null;
+  httpServer = null;
+  listening = false;
+  transportAttached = false;
+  constructor(options, internals = {}) {
+    super();
+    this.config = resolveConfig(options);
+    const scheduler = internals.scheduler ?? defaultScheduler;
+    this.now = internals.now ?? Date.now;
+    this.logger = internals.logger ?? NOOP_LOGGER;
+    this.httpLogger = this.logger;
+    const resolvedNodeEnv = internals.env ?? nodeEnv();
+    const securityContext = { logger: this.logger };
+    if (resolvedNodeEnv != null) {
+      securityContext.env = resolvedNodeEnv;
+    }
+    enforceSecurityPolicy(this.config, securityContext);
+    this.state = new FleetState({ logger: this.logger });
+    this.auth = new AgentAuthenticator(this.config.agentKeys);
+    this.commands = new CommandEngine(scheduler, this.state, this.config.commandTimeoutMs);
+    this.poller = new Poller(scheduler, this.config.heartbeatMs, {
+      sendPoll: (id, reqId, forceFull) => this.sendPoll(id, reqId, forceFull),
+      onStale: (id) => this.onStale(id),
+      onEvict: (id) => this.onEvict(id)
+    });
+    this.reconciler = new EventReconciler(this.state, (event, data) => this.emitEvent(event, data));
+    this.control = new FleetControl(this.state, this.commands, (id) => this.links.get(id));
+    const self = this;
+    this.fleet = {
+      get stats() {
+        return self.state.stats;
+      },
+      get instances() {
+        return self.state.instances;
+      },
+      get rooms() {
+        return self.state.rooms;
+      },
+      getInstance: (id) => self.state.getInstance(id),
+      getRoom: (id) => self.state.getRoom(id),
+      findRooms: (filter) => self.state.findRooms(filter ?? {}),
+      createRoom: (request) => self.control.createRoom(request),
+      destroyRoom: (roomId) => self.control.destroyRoom(roomId),
+      drainInstance: (instanceId) => self.control.drainInstance(instanceId),
+      undrainInstance: (instanceId) => self.control.undrainInstance(instanceId)
+    };
+    this.httpApi = createHttpApi(
+      {
+        config: this.config,
+        fleet: this.fleet,
+        isReady: () => this.ready,
+        subscribe: (listener) => this.subscribeFleetEvents(listener),
+        getLogger: () => this.httpLogger,
+        now: this.now
+      },
+      {
+        serverFactory: (handler) => {
+          const server = createSharedHttpServer(handler);
+          this.httpServer = server;
+          return server;
+        }
+      }
+    );
+  }
+  /**
+   * Bridge every {@link FleetEventType} broadcast (§9) into one SSE listener as a
+   * {@link FleetEvent} `{ type, data }`; returns an unsubscribe (called on stream close, §10).
+   */
+  subscribeFleetEvents(listener) {
+    const types = [
+      "instance:join",
+      "instance:leave",
+      "instance:stale",
+      "room:create",
+      "room:destroy",
+      "sync"
+    ];
+    const handlers = types.map((type) => {
+      const handler = (data) => listener({ type, data });
+      this.on(type, handler);
+      return { type, handler };
+    });
+    return () => {
+      for (const { type, handler } of handlers) {
+        this.off(type, handler);
+      }
+    };
+  }
+  /** True once HTTP is listening and the WS transport is attached (drives `/readyz`, task 010). */
+  get ready() {
+    return this.listening && this.transportAttached;
+  }
+  // ---- Lifecycle ----
+  /** Start the HTTP/WS server, attach the internal Rivalis room, begin accepting agents (§9). */
+  async listen() {
+    if (this.listening) {
+      return;
+    }
+    const core = loadCore();
+    const httpServer = this.httpServer;
+    if (httpServer === null) {
+      throw new Error("orchestrator: http server was not created by the REST layer");
+    }
+    const rivalis = attachControlPlane(core, httpServer, { authenticator: this.auth, controller: this, logger: this.logger });
+    this.rivalis = rivalis;
+    this.logger = rivalis.logging.getLogger("fleet");
+    this.httpLogger = rivalis.logging.getLogger("fleet:http");
+    this.transportAttached = true;
+    await this.httpApi.listen({ host: this.config.host, port: this.config.port });
+    this.listening = true;
+    this.logger.info(
+      `orchestrator listening host=(${this.config.host}) port=(${this.config.port}) api=(${this.config.api ? "/v1" : "off"}) heartbeat=(${this.config.heartbeatMs}ms)`
+    );
+  }
+  /** Gracefully stop: reject in-flight commands, destroy rooms, dispose transport, close HTTP (§9). */
+  async shutdown() {
+    this.httpApi.shutdown();
+    for (const instanceId of [...this.links.keys()]) {
+      this.teardownInstance(instanceId, "orchestrator shutdown");
+    }
+    if (this.rivalis !== null) {
+      try {
+        await this.rivalis.shutdown();
+      } catch (error) {
+        this.logger.warning(`rivalis shutdown error: ${describe(error)}`);
+      }
+      this.rivalis = null;
+    }
+    await this.httpApi.close();
+    this.httpServer = null;
+    this.transportAttached = false;
+    this.listening = false;
+  }
+  // ---- FleetController — driven by the FleetRoom (agent transport, §7) ----
+  /** @internal Agent joined: assign id, send `fleet/hello`, start polling (§7, task 011). */
+  handleAgentJoin(link) {
+    this.guard(`agent join instance=${link.instanceId}`, () => {
+      this.links.set(link.instanceId, link);
+      link.send(Topics.hello, {
+        instanceId: link.instanceId,
+        protocolVersion: PROTOCOL_VERSION,
+        heartbeatMs: this.config.heartbeatMs
+      });
+      this.poller.start(link.instanceId);
+      this.logger.info(`agent joined instance=${link.instanceId}`);
+    });
+  }
+  /** @internal Agent socket closed: evict instantly, rejecting any in-flight commands (§7). */
+  handleAgentLeave(instanceId) {
+    this.guard(`agent leave instance=${instanceId}`, () => {
+      this.teardownInstance(instanceId, "socket close");
+    });
+  }
+  /**
+   * @internal Inbound agent frame (task 011). Every agent frame must be a reply to
+   * an outstanding orchestrator request — `fleet/state` to a `fleet/poll`,
+   * `fleet/ack` to a `fleet/cmd`. A well-formed frame whose correlation id matches
+   * no outstanding request (spontaneous, duplicate, or post-settle) is an
+   * unsolicited frame → kick. A malformed / version-incompatible frame is logged
+   * and dropped (the lockstep-mismatch path is evicted by missed polls, §7/§8).
+   */
+  handleAgentMessage(instanceId, topic, payload) {
+    this.guard(`agent message instance=${instanceId} topic=${topic}`, () => {
+      if (!this.links.has(instanceId)) {
+        return;
+      }
+      switch (topic) {
+        case Topics.state: {
+          const decoded = this.decode(instanceId, Topics.state, payload);
+          if (decoded !== null) {
+            this.handleState(instanceId, decoded);
+          }
+          return;
+        }
+        case Topics.ack: {
+          const decoded = this.decode(instanceId, Topics.ack, payload);
+          if (decoded !== null) {
+            this.handleAck(instanceId, decoded);
+          }
+          return;
+        }
+        default:
+          this.kick(instanceId, `unexpected topic on the control plane`);
+      }
+    });
+  }
+  // ---- Poll dispatch + reply ingestion (§7, task 011) ----
+  /** Build and send a `fleet/poll`: knownHash drives dedup, status echoes for drain confirmation. */
+  sendPoll(instanceId, reqId, forceFull) {
+    this.guard(`poll instance=${instanceId}`, () => {
+      const link = this.links.get(instanceId);
+      if (link === void 0) {
+        return;
+      }
+      const knownHash = forceFull ? null : this.state.lastHashOf(instanceId);
+      const status = this.state.getInstance(instanceId)?.status ?? "active";
+      link.send(Topics.poll, { reqId, knownHash, status });
+    });
+  }
+  /**
+   * Ingest a `fleet/state` poll reply (task 011). The reply must match the
+   * outstanding poll's `reqId` (consumed via the poller); an unmatched reply is
+   * unsolicited → kick. A full reply is bounds-checked (§13) and applied; a
+   * hash-only reply just refreshes liveness (the snapshot is unchanged).
+   */
+  handleState(instanceId, state) {
+    if (!this.poller.reply(instanceId, state.reqId)) {
+      this.kick(instanceId, "unsolicited or duplicate fleet/state (no matching outstanding poll)");
+      return;
+    }
+    this.state.setStale(instanceId, false);
+    if (!state.full) {
+      this.state.touch(instanceId, this.now());
+      return;
+    }
+    const reason = validateSnapshot(state);
+    if (reason !== null) {
+      this.logger.warning(`rejected snapshot from instance=${instanceId}: ${reason} (\xA713)`);
+      return;
+    }
+    if (this.state.applySnapshot(instanceId, state, this.now())) {
+      this.reconciler.reconcile();
+    }
+  }
+  handleAck(instanceId, ack) {
+    if (!this.commands.ack(instanceId, ack)) {
+      this.kick(instanceId, "ack for unknown or already-settled command");
+    }
+  }
+  /**
+   * Kick an agent that broke the request/reply contract (task 011): tear it down
+   * (rejecting in-flight commands, removing it from the read model) and close the
+   * socket so it reconnects fresh. The log line names the cause and the instance —
+   * never the offending payload's contents (§13).
+   */
+  kick(instanceId, reason) {
+    const link = this.links.get(instanceId);
+    this.logger.warning(`kicking instance=${instanceId}: ${reason} (request/reply enforcement, \xA77)`);
+    this.teardownInstance(instanceId, "protocol violation");
+    link?.close();
+  }
+  // ---- Liveness callbacks (read-model + events); timers owned by the Poller ----
+  onStale(instanceId) {
+    this.guard(`stale instance=${instanceId}`, () => {
+      this.state.setStale(instanceId, true);
+      this.logger.warning(`instance=${instanceId} stale (2 missed poll replies) \u2014 excluded from placement`);
+      const info = this.state.getInstance(instanceId);
+      if (info !== null) {
+        this.emitEvent("instance:stale", info);
+      }
+    });
+  }
+  onEvict(instanceId) {
+    this.guard(`evict instance=${instanceId}`, () => {
+      const link = this.links.get(instanceId);
+      this.logger.warning(`evicting wedged instance=${instanceId} (3 missed poll replies)`);
+      this.teardownInstance(instanceId, "liveness eviction");
+      link?.close();
+    });
+  }
+  /**
+   * Remove an instance from every table, reject its in-flight commands immediately
+   * with `INSTANCE_DISCONNECTED` (§7), and reconcile (its rooms → `room:destroy`, `sync`).
+   */
+  teardownInstance(instanceId, reason) {
+    if (!this.links.has(instanceId) && !this.poller.has(instanceId)) {
+      return;
+    }
+    this.links.delete(instanceId);
+    this.poller.forget(instanceId);
+    this.commands.rejectAll(instanceId, reason);
+    const removed = this.state.removeInstance(instanceId);
+    if (removed !== null) {
+      this.reconciler.instanceRemoved(removed);
+    }
+    this.reconciler.reconcile();
+  }
+  // ---- Internals ----
+  /**
+   * Decode a binary agent frame for `topic` (§7). Returns `null` on any failure —
+   * never throws into the host (§8): a protocol-incompatible frame (e.g. a legacy
+   * JSON agent against this v2 orchestrator) or a malformed/truncated one is logged
+   * and dropped, and the read model keeps its last good state.
+   */
+  decode(instanceId, topic, payload) {
+    const bytes = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+    try {
+      return decodeFrame(topic, bytes);
+    } catch (error) {
+      if (error instanceof WireVersionError) {
+        this.logger.warning(
+          `dropped protocol-incompatible frame from instance=${instanceId} topic=${topic} (peer major=${error.theirVersion}, orchestrator=${PROTOCOL_VERSION}) \u2014 agents and orchestrator must run the same @rivalis/fleet major (\xA77)`
+        );
+      } else {
+        this.logger.warning(`failed to decode agent frame topic=${topic} from instance=${instanceId}: ${describe(error)}`);
+      }
+      return null;
+    }
+  }
+  emitEvent(event, data) {
+    try {
+      this.emit(event, data);
+    } catch (error) {
+      this.logger.error(`listener for ${event} threw: ${describe(error)}`);
+    }
+  }
+  /**
+   * Run a timer- / transport- / core-dispatch-driven callback, swallowing and
+   * logging any throw so it never escapes into a raw `setTimeout` (an
+   * `uncaughtException` that would crash the whole control plane) or back into
+   * core's room dispatch (§14 failure modes). Mirrors the agent's host-safety
+   * `guard` (§8): the orchestrator is the single point of coordination, so one
+   * unhandled throw on a poll tick, a snapshot application, or a liveness deadline
+   * must degrade to a logged failure on one instance, never an orchestrator-wide
+   * outage. Never rethrows.
+   */
+  guard(label, fn) {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.error(`orchestrator ${label} handler error: ${describe(error)}`);
+    }
+  }
+};
+
+// src/agent/FleetAgent.ts
+import { Broadcast as Broadcast2 } from "@toolcase/base";
+
+// src/agent/Snapshot.ts
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/util/packageVersion.ts
+import { createRequire as createRequire3 } from "module";
+function packageVersion() {
+  try {
+    const metaUrl = import.meta.url;
+    const req = metaUrl ? createRequire3(metaUrl) : __require;
+    const pkg = req("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/agent/Snapshot.ts
+var MAX_SNAPSHOT_BYTES2 = 4 * 1024 * 1024;
+var WARN_RATIO = 0.5;
+var ERROR_RATIO = 0.9;
+var MIN_CORE_VERSION = "6.1.0";
+function generateProcessUid() {
+  return "p_" + randomBytes2(12).toString("hex");
+}
+var Snapshot = class {
+  /** Stable per-process id (§6) — constant across reconnects. */
+  processUid;
+  rivalis;
+  logger;
+  name;
+  endpointUrl;
+  labels;
+  capacity;
+  autoCreate;
+  agentVersion;
+  protocolVersion;
+  /** Room ids created in response to `fleet/cmd` → stamped `origin: 'fleet'`. */
+  fleetOrigins = /* @__PURE__ */ new Set();
+  /** Agent owns `status` (§7); flipped via `setStatus`. */
+  statusValue;
+  /** Per-connection monotonic frame counter — defensive hardening only (§7). */
+  seq = 0;
+  constructor(rivalis, options, logger) {
+    this.assertCoreSupport(rivalis);
+    this.rivalis = rivalis;
+    this.logger = logger ?? rivalis.logging?.getLogger?.("fleet:agent") ?? NOOP_LOGGER;
+    this.name = options.name;
+    this.endpointUrl = options.endpointUrl;
+    this.labels = options.labels ?? {};
+    this.capacity = {
+      maxConnections: options.capacity?.maxConnections ?? null,
+      maxRooms: options.capacity?.maxRooms ?? null
+    };
+    this.autoCreate = options.autoCreate ?? true;
+    this.agentVersion = options.agentVersion ?? packageVersion();
+    this.protocolVersion = options.protocolVersion ?? PROTOCOL_VERSION;
+    this.processUid = options.processUid ?? generateProcessUid();
+    this.statusValue = options.status ?? "active";
+  }
+  get status() {
+    return this.statusValue;
+  }
+  /** Flip the agent-owned status (§7). The next snapshot carries the new value. */
+  setStatus(status) {
+    this.statusValue = status;
+  }
+  /** Stamp a room as fleet-created (`origin: 'fleet'`). Called on a `fleet/cmd` create. */
+  markFleetOrigin(roomId) {
+    this.fleetOrigins.add(roomId);
+  }
+  /** Drop provenance for a destroyed room so a future id reuse is not mis-stamped. */
+  forgetRoom(roomId) {
+    this.fleetOrigins.delete(roomId);
+  }
+  /**
+   * New connection (reconnect): reset the `seq` counter. The reconnect assigns a
+   * fresh `instanceId`, so the orchestrator holds no prior hash and its first poll
+   * carries `knownHash: null` → the next reply is always a full snapshot (§7).
+   */
+  resetConnection() {
+    this.seq = 0;
+  }
+  /**
+   * Rebuild the full semantic snapshot from live core state and hash it. Pure:
+   * no `seq`, no size guard, no dedup-state mutation — used for hash inspection
+   * and as the basis for {@link pollReply}.
+   */
+  rebuild() {
+    const content = this.buildContent();
+    return { content, hash: hash64(content) };
+  }
+  /**
+   * Build a `fleet/state` reply to an orchestrator `fleet/poll` (§7, task 011).
+   * The orchestrator drives the dedup: a FULL snapshot when the rebuilt hash
+   * differs from the poll's `knownHash` (or `knownHash` is null — no prior state /
+   * forced full), a hash-only reply otherwise. Always advances `seq`.
+   */
+  pollReply(reqId, knownHash) {
+    const { content, hash } = this.rebuild();
+    const seq = this.nextSeq();
+    if (knownHash !== null && hash === knownHash) {
+      const payload2 = { reqId, full: false, seq, hash, ...content };
+      return { kind: "state", full: false, hash, encodedBytes: 0, payload: payload2 };
+    }
+    const payload = { reqId, full: true, seq, hash, ...content };
+    const encodedBytes = encodeFrame(Topics.state, payload).length;
+    this.checkSize(encodedBytes, content.rooms.length);
+    return { kind: "state", full: true, hash, encodedBytes, payload };
+  }
+  nextSeq() {
+    this.seq += 1;
+    return this.seq;
+  }
+  buildContent() {
+    const manager = this.rivalis.rooms;
+    const roomTypes = [...manager.definitions()].sort();
+    const rooms = [];
+    for (const id of manager.keys()) {
+      const room = manager.get(id);
+      if (room === null) {
+        continue;
+      }
+      if (typeof room.type !== "string") {
+        throw new Error(this.coreSupportError(`room id=(${id}) has no string \`type\``));
+      }
+      rooms.push({
+        id,
+        type: room.type,
+        connections: room.actorCount,
+        origin: this.fleetOrigins.has(id) ? "fleet" : "local"
+      });
+    }
+    rooms.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return {
+      name: this.name,
+      processUid: this.processUid,
+      agentVersion: this.agentVersion,
+      protocolVersion: this.protocolVersion,
+      endpointUrl: this.endpointUrl,
+      labels: this.labels,
+      capacity: this.capacity,
+      autoCreate: this.autoCreate,
+      roomTypes,
+      rooms,
+      status: this.statusValue
+    };
+  }
+  checkSize(bytes, roomCount) {
+    const pct = Math.round(bytes / MAX_SNAPSHOT_BYTES2 * 100);
+    if (bytes >= MAX_SNAPSHOT_BYTES2 * ERROR_RATIO) {
+      this.logger.error(
+        `fleet snapshot at ${pct}% of the 4 MiB transport frame limit (${bytes} bytes, ${roomCount} rooms). An oversized snapshot is terminated by the transport, which causes a permanent reconnect loop. Remediation: host fewer rooms per instance, raise the orchestrator's WSTransport.maxPayload, or split the fleet across more instances (chunked sync is roadmap \xA716).`
+      );
+    } else if (bytes >= MAX_SNAPSHOT_BYTES2 * WARN_RATIO) {
+      this.logger.warning(
+        `fleet snapshot at ${pct}% of the 4 MiB transport frame limit (${bytes} bytes, ${roomCount} rooms) \u2014 approaching the size guard.`
+      );
+    }
+  }
+  /**
+   * Feature-detect the §4 core additions and throw an actionable, version-naming
+   * error when they are absent — a clean failure at startup instead of
+   * `undefined` types in snapshots at runtime. `Room.type` can only be checked
+   * against rooms that already exist; with zero rooms the `definitions()` gate
+   * is the primary guard (and `buildContent` re-checks each room defensively).
+   */
+  assertCoreSupport(rivalis) {
+    const manager = rivalis?.rooms;
+    if (manager === void 0 || manager === null) {
+      throw new Error(this.coreSupportError("rivalis.rooms is not available"));
+    }
+    if (typeof manager.definitions !== "function") {
+      throw new Error(this.coreSupportError("rivalis.rooms.definitions() is not available"));
+    }
+    if (typeof manager.keys !== "function" || typeof manager.get !== "function") {
+      throw new Error(this.coreSupportError("rivalis.rooms.keys()/get() are not available"));
+    }
+    for (const id of manager.keys()) {
+      const room = manager.get(id);
+      if (room !== null && typeof room.type !== "string") {
+        throw new Error(this.coreSupportError(`Room.type is not available (room id=(${id}) has no string \`type\`)`));
+      }
+    }
+  }
+  coreSupportError(detail) {
+    return `@rivalis/fleet requires @rivalis/core >= ${MIN_CORE_VERSION}: ${detail}. Upgrade @rivalis/core to >= ${MIN_CORE_VERSION} (the \xA74 additions: Room.type, RoomManager.definitions()).`;
+  }
+};
+
+// src/agent/FleetAgent.ts
+import { WSClient } from "@rivalis/node";
+var DEFAULT_BACKOFF_BASE_MS = 500;
+var DEFAULT_BACKOFF_CAP_MS = 3e4;
+var DEFAULT_AWAIT_EMPTY_POLL_MS = 200;
+function defaultCreateClient(url) {
+  return new WSClient(url, {
+    ticketSource: "protocol",
+    subprotocols: [WS_SUBPROTOCOL]
+  });
+}
+var FleetAgent = class extends Broadcast2 {
+  rivalis;
+  logger;
+  snapshot;
+  url;
+  key;
+  autoCreate;
+  maxRooms;
+  connectTimeoutMs;
+  client;
+  scheduler;
+  random;
+  backoffBaseMs;
+  backoffCapMs;
+  awaitEmptyPollMs;
+  installSignalHandlers;
+  lifecycle = "closed";
+  instanceId = null;
+  /** Set once `connect()`/reconnects should stop (intentional `disconnect()` or fatal error). */
+  closed = false;
+  /** Distinguishes an operator-driven close from a transport drop that should reconnect. */
+  intentionalClose = false;
+  reconnectTimer = null;
+  connectDeadline = null;
+  reconnectAttempt = 0;
+  connectResolve = null;
+  connectReject = null;
+  /**
+   * Pending `drain()` / `undrain()` promises (task 011): each waits for a
+   * `fleet/poll` echoing its target status — the orchestrator's acknowledged
+   * confirmation that it recorded the agent-owned status flip. No unsolicited frame.
+   */
+  pendingStatus = [];
+  uninstallSignals = null;
+  /**
+   * Whether the room/transport listeners are currently attached (task 008). The
+   * subscription lifecycle tracks the connection lifecycle: attached on construct
+   * and on every `connect()`, detached on the terminal paths (`disconnect()`,
+   * `failConnect()`) so a discarded/replaced agent stops reacting to room events
+   * and the host can drop it (otherwise `RoomManager`'s broadcast retains it).
+   */
+  listenersAttached = false;
+  /**
+   * Drop provenance when a room is destroyed so a future id reuse is not mis-stamped
+   * (§7). Room create/destroy/define no longer trigger a push — changes surface at
+   * the next orchestrator poll (task 011).
+   */
+  onRoomDestroy = (roomId) => {
+    this.snapshot.forgetRoom(roomId);
+  };
+  constructor(rivalis, options, internals = {}) {
+    super();
+    this.rivalis = rivalis;
+    this.logger = rivalis.logging?.getLogger?.("fleet:agent") ?? NOOP_LOGGER;
+    const snapshotOptions = {
+      name: options.name,
+      endpointUrl: options.endpointUrl,
+      agentVersion: packageVersion()
+    };
+    if (options.labels !== void 0) {
+      snapshotOptions.labels = options.labels;
+    }
+    if (options.capacity !== void 0) {
+      snapshotOptions.capacity = options.capacity;
+    }
+    if (options.autoCreate !== void 0) {
+      snapshotOptions.autoCreate = options.autoCreate;
+    }
+    this.snapshot = new Snapshot(rivalis, snapshotOptions, this.logger);
+    this.url = options.url;
+    this.key = options.key;
+    this.autoCreate = options.autoCreate ?? true;
+    this.maxRooms = options.capacity?.maxRooms ?? null;
+    this.connectTimeoutMs = options.connectTimeoutMs;
+    this.scheduler = internals.scheduler ?? defaultScheduler;
+    this.random = internals.random ?? Math.random;
+    this.backoffBaseMs = internals.backoff?.baseMs ?? DEFAULT_BACKOFF_BASE_MS;
+    this.backoffCapMs = internals.backoff?.capMs ?? DEFAULT_BACKOFF_CAP_MS;
+    this.awaitEmptyPollMs = internals.awaitEmptyPollMs ?? DEFAULT_AWAIT_EMPTY_POLL_MS;
+    this.installSignalHandlers = internals.installSignalHandlers;
+    this.client = (internals.createClient ?? defaultCreateClient)(this.url);
+    this.attachListeners();
+  }
+  /** Lifecycle status (§8): `'connecting' | 'connected' | 'draining' | 'closed'`. */
+  get status() {
+    return this.lifecycle;
+  }
+  /** Stable per-process id (§6), constant across reconnects. */
+  get processUid() {
+    return this.snapshot.processUid;
+  }
+  /**
+   * Connect to the orchestrator; resolves on the first `fleet/hello`. Default:
+   * retries forever (backoff per §7) — the promise stays pending while the
+   * orchestrator is unreachable. With `connectTimeoutMs` set, rejects after the
+   * deadline and transitions to `'closed'` with no background retry loop (§8).
+   */
+  connect() {
+    if (this.lifecycle === "connected" || this.lifecycle === "draining") {
+      return Promise.resolve();
+    }
+    if (this.connectResolve !== null) {
+      return new Promise((resolve, reject) => {
+        const prevResolve = this.connectResolve;
+        const prevReject = this.connectReject;
+        this.connectResolve = () => {
+          prevResolve();
+          resolve();
+        };
+        this.connectReject = (e) => {
+          prevReject(e);
+          reject(e);
+        };
+      });
+    }
+    this.closed = false;
+    this.intentionalClose = false;
+    this.lifecycle = "connecting";
+    this.reconnectAttempt = 0;
+    this.attachListeners();
+    return new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+      if (this.connectTimeoutMs !== void 0) {
+        this.connectDeadline = this.scheduler.setTimeout(
+          () => this.failConnect(new Error("fleet:agent connect timeout exceeded")),
+          this.connectTimeoutMs
+        );
+      }
+      this.openConnection();
+    });
+  }
+  /**
+   * Mark this instance draining (§7, task 011): flips the agent-owned status
+   * immediately (so the next `fleet/state` reply carries it) and resolves only when
+   * a subsequent `fleet/poll` echoes `status: 'draining'` — the orchestrator's
+   * acknowledged confirmation that it recorded the flip. No unsolicited frame.
+   */
+  drain() {
+    return this.requestStatus("draining");
+  }
+  /** Reverse of `drain()` — restore the instance to `active`; resolves on the poll echo (§7). */
+  undrain() {
+    return this.requestStatus("active");
+  }
+  /** Resolve once every local room is empty (zero connections), or reject on `timeoutMs` (§8). */
+  awaitEmpty({ timeoutMs } = {}) {
+    const empty = () => {
+      for (const id of this.rivalis.rooms.keys()) {
+        const room = this.rivalis.rooms.get(id);
+        if (room !== null && room.actorCount > 0) {
+          return false;
+        }
+      }
+      return true;
+    };
+    if (empty()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      let poll = null;
+      let deadline = null;
+      const cleanup = () => {
+        if (poll !== null) {
+          this.scheduler.clearInterval(poll);
+          poll = null;
+        }
+        if (deadline !== null) {
+          this.scheduler.clearTimeout(deadline);
+          deadline = null;
+        }
+      };
+      poll = this.scheduler.setInterval(() => {
+        if (empty()) {
+          cleanup();
+          resolve();
+        }
+      }, this.awaitEmptyPollMs);
+      if (timeoutMs !== void 0) {
+        deadline = this.scheduler.setTimeout(() => {
+          cleanup();
+          reject(new Error("fleet:agent awaitEmpty timeout exceeded"));
+        }, timeoutMs);
+      }
+    });
+  }
+  /** Detach cleanly: stop all timers, close the transport, no further reconnects (§8). */
+  async disconnect() {
+    this.intentionalClose = true;
+    this.closed = true;
+    this.clearAllTimers();
+    this.rejectPendingStatus(new Error("fleet:agent disconnected"));
+    try {
+      this.client.disconnect();
+    } catch (error) {
+      this.logger.warning(`fleet:agent transport disconnect error: ${describe(error)}`);
+    }
+    this.detachListeners();
+    this.lifecycle = "closed";
+    if (this.connectReject !== null) {
+      const reject = this.connectReject;
+      this.connectResolve = null;
+      this.connectReject = null;
+      reject(new Error("fleet:agent disconnected before connect resolved"));
+    }
+    this.emit("disconnect", Buffer.from("closed"));
+  }
+  /**
+   * Wire `SIGTERM`/`SIGINT` to the graceful sequence (§8):
+   * drain → awaitEmpty → disconnect → `rivalis.shutdown()`.
+   */
+  enableGracefulShutdown({ emptyTimeoutMs = 6e4 } = {}) {
+    if (this.uninstallSignals !== null) {
+      this.uninstallSignals();
+      this.uninstallSignals = null;
+    }
+    const handler = () => {
+      void this.gracefulShutdown(emptyTimeoutMs);
+    };
+    if (this.installSignalHandlers !== void 0) {
+      this.uninstallSignals = this.installSignalHandlers(handler);
+      return;
+    }
+    process.once("SIGTERM", handler);
+    process.once("SIGINT", handler);
+    this.uninstallSignals = () => {
+      process.removeListener("SIGTERM", handler);
+      process.removeListener("SIGINT", handler);
+    };
+  }
+  async gracefulShutdown(emptyTimeoutMs) {
+    try {
+      await this.drain();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful drain failed: ${describe(error)}`);
+    }
+    try {
+      await this.awaitEmpty({ timeoutMs: emptyTimeoutMs });
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful awaitEmpty: ${describe(error)}`);
+    }
+    try {
+      await this.disconnect();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful disconnect failed: ${describe(error)}`);
+    }
+    try {
+      await this.rivalis.shutdown();
+    } catch (error) {
+      this.logger.warning(`fleet:agent graceful rivalis.shutdown failed: ${describe(error)}`);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Transport wiring
+  // -----------------------------------------------------------------------
+  /**
+   * Attach the room-provenance and transport listeners (task 008). Idempotent —
+   * re-`connect()` after a `disconnect()` calls this again but it no-ops while
+   * already attached, so listeners are never doubled.
+   */
+  attachListeners() {
+    if (this.listenersAttached) {
+      return;
+    }
+    this.wireClient();
+    this.subscribeRooms();
+    this.listenersAttached = true;
+  }
+  /**
+   * Detach every listener on the terminal paths (task 008): the rooms broadcast
+   * stops retaining this agent (no more `forgetRoom` on room destroy) and the
+   * transport handlers are removed. Without this a discarded agent leaks — the
+   * `RoomManager` broadcast keeps it alive for the host process's lifetime.
+   */
+  detachListeners() {
+    if (!this.listenersAttached) {
+      return;
+    }
+    this.unsubscribeRooms();
+    try {
+      this.client.removeAllListeners();
+    } catch (error) {
+      this.logger.warning(`fleet:agent transport removeAllListeners error: ${describe(error)}`);
+    }
+    this.listenersAttached = false;
+  }
+  wireClient() {
+    this.client.on("client:connect", () => this.guard("transport open", () => this.onTransportOpen()));
+    this.client.on("client:disconnect", (reason) => this.guard("transport close", () => this.onTransportClose(reason)));
+    this.client.on("client:error", (error) => this.guard("transport error", () => this.onTransportError(error)));
+    this.client.on(Topics.hello, (payload) => this.guard("hello", () => this.onHello(payload)));
+    this.client.on(Topics.poll, (payload) => this.guard("poll", () => this.onPoll(payload)));
+    this.client.on(Topics.cmd, (payload) => this.guard("cmd", () => this.onCmd(payload)));
+  }
+  subscribeRooms() {
+    this.rivalis.rooms.on("destroy", this.onRoomDestroy);
+  }
+  unsubscribeRooms() {
+    this.rivalis.rooms.off("destroy", this.onRoomDestroy);
+  }
+  openConnection() {
+    if (this.closed) {
+      return;
+    }
+    try {
+      this.client.connect(this.key);
+    } catch (error) {
+      this.logger.warning(`fleet:agent connect attempt threw: ${describe(error)}`);
+      this.scheduleReconnect();
+    }
+  }
+  onTransportOpen() {
+    this.logger.debug?.("fleet:agent transport open \u2014 awaiting fleet/hello");
+  }
+  onTransportClose(reason) {
+    if (this.closed || this.intentionalClose) {
+      return;
+    }
+    this.rejectPendingStatus(new Error("fleet:agent connection lost"));
+    this.lifecycle = "connecting";
+    this.emit("disconnect", reason);
+    this.scheduleReconnect();
+  }
+  onTransportError(error) {
+    this.logger.warning(`fleet:agent transport error: ${describe(error)}`);
+    this.emit("error", error);
+  }
+  scheduleReconnect() {
+    if (this.closed || this.intentionalClose || this.reconnectTimer !== null) {
+      return;
+    }
+    const delay = this.backoffDelay();
+    this.reconnectAttempt += 1;
+    this.reconnectTimer = this.scheduler.setTimeout(() => {
+      this.reconnectTimer = null;
+      this.openConnection();
+    }, delay);
+  }
+  /** Full-jitter exponential backoff: random in `[0, min(cap, base·2^attempt)]` (§7). */
+  backoffDelay() {
+    const ceiling = Math.min(this.backoffCapMs, this.backoffBaseMs * Math.pow(2, this.reconnectAttempt));
+    return Math.floor(this.random() * ceiling);
+  }
+  // -----------------------------------------------------------------------
+  // Protocol handlers (orch → agent)
+  // -----------------------------------------------------------------------
+  onHello(raw) {
+    let hello;
+    try {
+      hello = decodeFrame(Topics.hello, toBytes(raw));
+    } catch (error) {
+      if (error instanceof WireVersionError) {
+        this.logger.error(error.message);
+        this.emit("error", error);
+        this.failConnect(error);
+        return;
+      }
+      this.logger.warning(`fleet:agent failed to decode fleet/hello: ${describe(error)}`);
+      return;
+    }
+    if (hello.protocolVersion !== PROTOCOL_VERSION) {
+      const error = new Error(
+        `fleet protocol major mismatch: orchestrator=${hello.protocolVersion}, agent=${PROTOCOL_VERSION} \u2014 upgrade so both speak the same major (\xA77)`
+      );
+      this.logger.error(error.message);
+      this.emit("error", error);
+      this.failConnect(error);
+      return;
+    }
+    this.instanceId = hello.instanceId;
+    this.reconnectAttempt = 0;
+    this.clearReconnect();
+    this.clearConnectDeadline();
+    this.snapshot.resetConnection();
+    this.lifecycle = this.snapshot.status === "draining" ? "draining" : "connected";
+    if (this.connectResolve !== null) {
+      const resolve = this.connectResolve;
+      this.connectResolve = null;
+      this.connectReject = null;
+      resolve();
+    }
+    this.emit("connect", { instanceId: this.instanceId, processUid: this.snapshot.processUid });
+  }
+  /**
+   * Answer an orchestrator `fleet/poll` with a `fleet/state` reply (§7, task 011):
+   * full snapshot when our hash differs from the poll's `knownHash`, hash-only
+   * otherwise. A poll echoing a pending `drain()`/`undrain()` target status also
+   * resolves that promise (the acknowledged confirmation, no unsolicited frame).
+   */
+  onPoll(raw) {
+    const poll = this.decodeInbound(Topics.poll, raw);
+    if (poll === null) {
+      return;
+    }
+    this.resolveStatusOnEcho(poll.status);
+    if (this.client.connected) {
+      this.sendState(this.snapshot.pollReply(poll.reqId, poll.knownHash));
+    }
+  }
+  onCmd(raw) {
+    const cmd = this.decodeInbound(Topics.cmd, raw);
+    if (cmd === null) {
+      return;
+    }
+    this.emit("command", cmd);
+    switch (cmd.op) {
+      case "create":
+        return this.execCreate(cmd);
+      case "destroy":
+        return this.execDestroy(cmd);
+      case "drain":
+        return this.execStatusCmd(cmd, "draining");
+      case "undrain":
+        return this.execStatusCmd(cmd, "active");
+      default:
+        this.sendAck({ cmdId: cmd.cmdId, ok: false, error: `unknown op: ${String(cmd.op)}` });
+    }
+  }
+  execCreate(cmd) {
+    if (!this.autoCreate) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "autoCreate is disabled on this instance" });
+      return;
+    }
+    if (typeof cmd.roomType !== "string") {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "create requires roomType" });
+      return;
+    }
+    if (this.maxRooms !== null && this.rivalis.rooms.count >= this.maxRooms) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: `capacity exhausted: maxRooms=${this.maxRooms}` });
+      return;
+    }
+    if (typeof cmd.roomId === "string" && this.rivalis.rooms.get(cmd.roomId) !== null) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, exists: true, error: "room id already exists" });
+      return;
+    }
+    try {
+      const room = this.rivalis.rooms.create(cmd.roomType, cmd.roomId ?? null);
+      this.snapshot.markFleetOrigin(room.id);
+      this.sendAck({ cmdId: cmd.cmdId, ok: true, room: { id: room.id, type: room.type } });
+    } catch (error) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: describe(error) });
+    }
+  }
+  execDestroy(cmd) {
+    if (typeof cmd.roomId !== "string") {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: "destroy requires roomId" });
+      return;
+    }
+    if (this.rivalis.rooms.get(cmd.roomId) === null) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: true, alreadyGone: true });
+      return;
+    }
+    try {
+      this.rivalis.rooms.destroy(cmd.roomId);
+      this.snapshot.forgetRoom(cmd.roomId);
+      this.sendAck({ cmdId: cmd.cmdId, ok: true });
+    } catch (error) {
+      this.sendAck({ cmdId: cmd.cmdId, ok: false, error: describe(error) });
+    }
+  }
+  execStatusCmd(cmd, status) {
+    this.snapshot.setStatus(status);
+    this.lifecycle = status === "draining" ? "draining" : "connected";
+    this.sendAck({ cmdId: cmd.cmdId, ok: true });
+  }
+  // -----------------------------------------------------------------------
+  // Outbound (agent → orch) — replies only (task 011)
+  // -----------------------------------------------------------------------
+  requestStatus(target) {
+    this.snapshot.setStatus(target);
+    this.lifecycle = target === "draining" ? "draining" : "connected";
+    return new Promise((resolve, reject) => {
+      this.pendingStatus.push({ target, resolve, reject });
+    });
+  }
+  /** Resolve every pending drain()/undrain() whose target matches the poll-echoed status. */
+  resolveStatusOnEcho(echoed) {
+    if (this.pendingStatus.length === 0) {
+      return;
+    }
+    const remaining = [];
+    for (const pending of this.pendingStatus) {
+      if (pending.target === echoed) {
+        pending.resolve();
+      } else {
+        remaining.push(pending);
+      }
+    }
+    this.pendingStatus = remaining;
+  }
+  sendState(frame) {
+    this.send(Topics.state, frame.payload);
+  }
+  sendAck(ack) {
+    this.send(Topics.ack, ack);
+  }
+  send(topic, payload) {
+    try {
+      this.client.send(topic, encodeFrame(topic, payload));
+    } catch (error) {
+      this.logger.warning(`fleet:agent send failed topic=${topic}: ${describe(error)}`);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Teardown helpers
+  // -----------------------------------------------------------------------
+  /** Fatal connect failure (timeout or protocol mismatch): reject, close, stop retrying (§8). */
+  failConnect(error) {
+    this.closed = true;
+    this.intentionalClose = true;
+    this.clearAllTimers();
+    this.rejectPendingStatus(error);
+    try {
+      this.client.disconnect();
+    } catch (disconnectError) {
+      this.logger.warning(`fleet:agent disconnect during failConnect: ${describe(disconnectError)}`);
+    }
+    this.detachListeners();
+    this.lifecycle = "closed";
+    if (this.connectReject !== null) {
+      const reject = this.connectReject;
+      this.connectResolve = null;
+      this.connectReject = null;
+      reject(error);
+    }
+  }
+  rejectPendingStatus(error) {
+    const pending = this.pendingStatus;
+    this.pendingStatus = [];
+    for (const entry of pending) {
+      entry.reject(error);
+    }
+  }
+  clearReconnect() {
+    if (this.reconnectTimer !== null) {
+      this.scheduler.clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  clearConnectDeadline() {
+    if (this.connectDeadline !== null) {
+      this.scheduler.clearTimeout(this.connectDeadline);
+      this.connectDeadline = null;
+    }
+  }
+  clearAllTimers() {
+    this.clearReconnect();
+    this.clearConnectDeadline();
+    if (this.uninstallSignals !== null) {
+      this.uninstallSignals();
+      this.uninstallSignals = null;
+    }
+  }
+  /** Run a transport/timer callback, swallowing+logging any throw (§8 host-safety contract). */
+  guard(label, fn) {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.error(`fleet:agent ${label} handler error: ${describe(error)}`);
+      this.emit("error", error instanceof Error ? error : new Error(describe(error)));
+    }
+  }
+  /**
+   * Decode an inbound binary frame for a non-hello topic (§7, task 005). Logs +
+   * returns `null` on any failure — never throws into the host (§8). A
+   * protocol-incompatible frame is logged as a version mismatch; a
+   * malformed/truncated frame is logged and dropped. (`fleet/hello` handles a
+   * version mismatch itself — a loud connect failure — so it does not use this.)
+   */
+  decodeInbound(topic, raw) {
+    try {
+      return decodeFrame(topic, toBytes(raw));
+    } catch (error) {
+      if (error instanceof WireVersionError) {
+        this.logger.warning(`fleet:agent dropped protocol-incompatible ${topic} frame (peer major=${error.theirVersion}, agent=${PROTOCOL_VERSION})`);
+      } else {
+        this.logger.warning(`fleet:agent failed to decode ${topic}: ${describe(error)}`);
+      }
+      return null;
+    }
+  }
+};
+function toBytes(raw) {
+  if (raw instanceof Uint8Array) {
+    return raw;
+  }
+  if (typeof raw === "string") {
+    return Buffer.from(raw, "utf-8");
+  }
+  return new Uint8Array(0);
+}
+export {
+  FleetAgent,
+  FleetError,
+  Orchestrator,
+  PROTOCOL_VERSION
+};