@irtio/cli 0.1.0 → 0.2.0

package/dist/{dev-BFWFWJ4J.js → dev-LOSTB4CD.js}

@@ -1,14 +1,29 @@
+import {
+  clientImportsRoom
+} from "./chunk-TQU6345E.js";
 import {
   BundleError,
   bundleRoom
-} from "./chunk-ZWCLCYCS.js";
+} from "./chunk-KRQUAEN2.js";
+import {
+  DEFAULT_SAVE_RETAIN,
+  DiskStore,
+  KV_ERRORS,
+  PLAYER_ISSUER_RE,
+  PRE_MIGRATION_SAVE_ID,
+  listSaves,
+  mintSaveId,
+  pruneSaves,
+  saveKey
+} from "./chunk-BPE452KF.js";
 
 // src/dev.ts
 import { existsSync } from "fs";
 import { watch } from "fs";
-import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
-import * as path2 from "path";
-import { fileURLToPath } from "url";
+import { mkdir, readFile } from "fs/promises";
+import { createRequire } from "module";
+import * as path from "path";
+import { fileURLToPath, pathToFileURL as pathToFileURL3 } from "url";
 
 // ../supervisor/src/contract.ts
 var DEFAULT_LIMITS = {
@@ -24,7 +39,8 @@ var DEFAULT_LIMITS = {
   workerReadyTimeoutMs: 1e4,
   relayIdleMs: 3e4,
   relayReconnectGraceMs: 3e4,
-  relayMaxClients: 64
+  relayMaxClients: 64,
+  saveRetain: DEFAULT_SAVE_RETAIN
 };
 
 // ../supervisor/src/resilience.ts
@@ -65,75 +81,13 @@ async function putSnapshotWithRetry(store, key, bytes, metrics, log) {
   return false;
 }
 
-// ../store/dist/index.js
-import { mkdir, readFile, readdir, rename, rm, writeFile } from "fs/promises";
-import * as path from "path";
-var DiskStore = class {
-  constructor(dir) {
-    this.dir = dir;
-  }
-  dir;
-  fileFor(key) {
-    if (!/^[A-Za-z0-9_.@/-]+$/.test(key) || key.includes("..")) {
-      throw new Error(`invalid object store key ${JSON.stringify(key)}`);
-    }
-    return path.join(this.dir, `${key}.snap`);
-  }
-  async put(key, bytes) {
-    const file = this.fileFor(key);
-    await mkdir(path.dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-    await writeFile(tmp, bytes);
-    for (let attempt = 0; ; attempt++) {
-      try {
-        await rename(tmp, file);
-        return;
-      } catch (err) {
-        const code = err.code;
-        if ((code === "EPERM" || code === "EBUSY") && attempt < 10) {
-          await new Promise((resolve2) => setTimeout(resolve2, 5 * (attempt + 1)));
-          continue;
-        }
-        throw err;
-      }
-    }
-  }
-  async get(key) {
-    try {
-      return new Uint8Array(await readFile(this.fileFor(key)));
-    } catch (err) {
-      if (err.code === "ENOENT") return void 0;
-      throw err;
-    }
-  }
-  async delete(key) {
-    await rm(this.fileFor(key), { force: true });
-  }
-  async list(prefix) {
-    const out = [];
-    const walk = async (dir, rel) => {
-      let entries;
-      try {
-        entries = await readdir(dir, { withFileTypes: true });
-      } catch (err) {
-        if (err.code === "ENOENT") return;
-        throw err;
-      }
-      for (const e of entries) {
-        const r = rel ? `${rel}/${e.name}` : e.name;
-        if (e.isDirectory()) await walk(path.join(dir, e.name), r);
-        else if (e.name.endsWith(".snap")) out.push(r.slice(0, -".snap".length));
-      }
-    };
-    await walk(this.dir, "");
-    return out.filter((k) => k.startsWith(prefix)).sort();
-  }
-};
-
 // ../supervisor/src/server.ts
 import { execFile } from "child_process";
 import { randomBytes, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { mkdtemp, writeFile } from "fs/promises";
 import { createServer } from "http";
+import { tmpdir } from "os";
+import * as nodePath from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   ErrorCode as ErrorCode2,
@@ -158,6 +112,147 @@ import { bytesEqual } from "@irtio/schema";
 import { isRoomDefinition } from "@irtio/server";
 import { WebSocketServer } from "ws";
 
+// ../supervisor/src/alarms.ts
+var MAX_TIMER_MS = 2 ** 31 - 1;
+var systemAlarmClock = {
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    t.unref?.();
+    return t;
+  },
+  clearTimeout: (h) => clearTimeout(h)
+};
+var AlarmSet = class {
+  constructor(clock = systemAlarmClock) {
+    this.clock = clock;
+  }
+  clock;
+  /** `name` -> wall-clock ms the alarm is due at. Wall clock, not monotonic: it has to mean the
+   *  same thing to a control plane on another machine and across a tenant restart. */
+  due = /* @__PURE__ */ new Map();
+  timer;
+  /** Called when one or more alarms come due, with the names in deterministic (name) order. */
+  deliver;
+  /**
+   * Where due alarms go. Attached for the room's whole life, **including while it is
+   * hibernated** — that is what makes the hibernated case work at all: the timer fires, delivery
+   * wakes the room, and the alarm lands in a running room a moment later. The worker going away
+   * is not a reason to stop counting down; only the room being gone is.
+   */
+  attach(deliver) {
+    this.deliver = deliver;
+    this.rearm();
+  }
+  /** The room is closed for good. The timer goes; the map is no longer anyone's business. */
+  detach() {
+    this.deliver = void 0;
+    this.clearTimer();
+  }
+  /** `atMs === undefined` cancels. Arming a name that is already armed replaces its due time. */
+  set(name, atMs) {
+    if (atMs === void 0) this.due.delete(name);
+    else this.due.set(name, atMs);
+    this.rearm();
+    this.onChange?.();
+  }
+  get size() {
+    return this.due.size;
+  }
+  /** Called whenever the armed set changes, so the supervisor can persist it. */
+  onChange;
+  /** Replaces the armed set wholesale — how a room start re-arms from the persisted sidecar. */
+  load(entries) {
+    this.due.clear();
+    for (const e of entries) this.due.set(e.name, e.dueAt);
+    this.rearm();
+  }
+  /** Snapshot for `/admin/rooms` and for tests. */
+  entries() {
+    return [...this.due.entries()].map(([name, dueAt]) => ({ name, dueAt })).sort((a, b) => a.dueAt - b.dueAt || (a.name < b.name ? -1 : 1));
+  }
+  /** The earliest due time, or `undefined` when nothing is armed. What control is told. */
+  get earliestDueAt() {
+    let best;
+    for (const at of this.due.values()) if (best === void 0 || at < best) best = at;
+    return best;
+  }
+  /**
+   * Fires everything due at or before `now`, in **name order** so a room with two alarms coming
+   * due in the same instant behaves identically on every machine and every replay (D34). Each is
+   * removed *before* it is delivered, so a handler that re-arms its own name arms the next one
+   * rather than having this pass immediately cancel it back out.
+   */
+  fireDue(now = this.clock.now()) {
+    const names = [...this.due.entries()].filter(([, at]) => at <= now).map(([name]) => name).sort();
+    if (names.length === 0) return names;
+    for (const name of names) this.due.delete(name);
+    this.deliver?.(names);
+    this.rearm();
+    this.onChange?.();
+    return names;
+  }
+  clearTimer() {
+    if (this.timer !== void 0) {
+      this.clock.clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  /**
+   * One timer, for the earliest alarm. Recomputed after every change rather than incrementally
+   * maintained: an alarm set is a handful of entries, and the incremental version is where the
+   * stale-timer bugs live.
+   */
+  rearm() {
+    this.clearTimer();
+    if (!this.deliver) return;
+    const earliest = this.earliestDueAt;
+    if (earliest === void 0) return;
+    const delay = Math.min(MAX_TIMER_MS, Math.max(0, earliest - this.clock.now()));
+    this.timer = this.clock.setTimeout(() => {
+      this.timer = void 0;
+      if (this.fireDue().length === 0) this.rearm();
+    }, delay);
+  }
+};
+function alarmsKey(liveKey) {
+  return `${liveKey}/alarms`;
+}
+function roomIdOfAlarmsKey(projectPrefix, key) {
+  if (!key.startsWith(projectPrefix)) return void 0;
+  const rest = key.slice(projectPrefix.length);
+  if (!rest.endsWith("/alarms")) return void 0;
+  const liveKey = rest.slice(0, -"/alarms".length);
+  if (liveKey === "" || liveKey.includes("/")) return void 0;
+  const at = liveKey.lastIndexOf("@v");
+  if (at === -1) return liveKey;
+  const version = liveKey.slice(at + 2);
+  if (!/^[0-9]+$/.test(version)) return liveKey;
+  const room = liveKey.slice(0, at);
+  return room === "" ? void 0 : room;
+}
+function encodeAlarms(entries) {
+  return new TextEncoder().encode(JSON.stringify({ v: 1, alarms: entries }));
+}
+function decodeAlarms(bytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return [];
+  }
+  const list = parsed?.alarms;
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const entry of list) {
+    const e = entry;
+    if (typeof e.name !== "string" || e.name === "") continue;
+    if (typeof e.dueAt !== "number" || !Number.isFinite(e.dueAt)) continue;
+    out.push({ name: e.name, dueAt: e.dueAt });
+  }
+  return out;
+}
+
 // ../supervisor/src/auth.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var TokenBucket = class {
@@ -208,6 +303,80 @@ function originAllowed(origins, allowNoOrigin, origin) {
   if (origins.includes("*")) return true;
   return origins.includes(origin);
 }
+var JWT_CLOCK_SKEW_MS = 6e4;
+var JWT_SUB_RE = /^[\x21-\x7e]{1,128}$/;
+function verifyJwt(issuers, token, projectId, now = Date.now()) {
+  const malformed = (reason) => ({
+    ok: false,
+    code: "E_TOKEN_MALFORMED",
+    reason
+  });
+  const parts = token.split(".");
+  if (parts.length !== 3) return malformed("not three dot-separated segments");
+  const [headerB64, payloadB64, signatureB64] = parts;
+  let header2;
+  let claims;
+  try {
+    header2 = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+    claims = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+  } catch {
+    return malformed("header or payload is not base64url JSON");
+  }
+  if (typeof claims.sub !== "string" || !JWT_SUB_RE.test(claims.sub)) {
+    return malformed("sub is required: 1-128 printable ASCII characters, no spaces");
+  }
+  if (typeof claims.iss !== "string" || !PLAYER_ISSUER_RE.test(claims.iss)) {
+    return malformed("iss is required: 1-64 of a-z 0-9 . _ - (never a colon)");
+  }
+  if (typeof claims.aud !== "string") {
+    return malformed("aud (the project id) is required");
+  }
+  if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
+    return malformed("exp (unix seconds) is required");
+  }
+  if (claims.aud !== projectId) {
+    return { ok: false, code: "E_TOKEN_WRONG_PROJECT", reason: "aud is another project" };
+  }
+  const accepted = issuers.filter((i) => i.issuer === claims.iss);
+  if (accepted.length === 0) {
+    return { ok: false, code: "E_TOKEN_BAD_ISSUER", reason: String(claims.iss) };
+  }
+  if (!accepted.some((i) => i.alg === header2.alg)) {
+    return { ok: false, code: "E_TOKEN_BAD_ALG", reason: String(header2.alg) };
+  }
+  const signedPart = `${headerB64}.${payloadB64}`;
+  const provided = Buffer.from(signatureB64, "base64url");
+  let signed = false;
+  for (const entry of accepted) {
+    if (entry.alg !== "HS256") continue;
+    const expected = createHmac("sha256", entry.secret).update(signedPart).digest();
+    if (provided.length === expected.length && timingSafeEqual(provided, expected)) {
+      signed = true;
+      break;
+    }
+  }
+  if (!signed) return { ok: false, code: "E_TOKEN_INVALID", reason: "signature mismatch" };
+  if (claims.exp * 1e3 + JWT_CLOCK_SKEW_MS <= now) {
+    return { ok: false, code: "E_TOKEN_EXPIRED", reason: "exp is in the past" };
+  }
+  if (typeof claims.iat === "number" && Number.isFinite(claims.iat) && claims.iat * 1e3 - JWT_CLOCK_SKEW_MS > now) {
+    return { ok: false, code: "E_TOKEN_EXPIRED", reason: "iat is in the future" };
+  }
+  if (claims.roomId !== void 0 && typeof claims.roomId !== "string") {
+    return malformed("roomId claim must be a string");
+  }
+  if (claims.role !== void 0 && typeof claims.role !== "string") {
+    return malformed("role claim must be a string");
+  }
+  return {
+    ok: true,
+    iss: claims.iss,
+    sub: claims.sub,
+    playerId: `${claims.iss}:${claims.sub}`,
+    ...claims.role !== void 0 ? { role: claims.role } : {},
+    ...claims.roomId !== void 0 ? { roomId: claims.roomId } : {}
+  };
+}
 function mac(secret, payload) {
   return createHmac("sha256", secret).update(payload).digest("base64url");
 }
@@ -505,7 +674,135 @@ async function wakeRoom(sup, room) {
   });
   await room.transition;
 }
+async function migrateRoom(sup, room, toVersion) {
+  const left = (reason) => ({
+    roomId: room.id,
+    outcome: "left",
+    reason
+  });
+  const failed = (reason) => ({
+    roomId: room.id,
+    outcome: "failed",
+    reason
+  });
+  if (room.relay) return left("relay room; nothing to migrate");
+  await room.transition.catch(() => {
+  });
+  if (room.state === "closed") return left("room is closed");
+  if (room.version >= toVersion) return left(`already on v${room.version}`);
+  if (room.state !== "running" && room.state !== "hibernated") {
+    return left(`room is ${room.state}`);
+  }
+  const fromVersion = room.version;
+  const oldKey = sup.storeKey(room);
+  let chain;
+  try {
+    chain = sup.migrationChain(fromVersion, toVersion);
+  } catch (err) {
+    return failed(err instanceof Error ? err.message : String(err));
+  }
+  let outcome = failed("migration did not complete");
+  const startedAt = performance.now();
+  const work = (async () => {
+    let bytes;
+    const worker = room.worker;
+    if (room.state === "running" && worker) {
+      room.state = "hibernating";
+      bytes = await worker.serialize();
+      if (!bytes) {
+        room.state = "running";
+        outcome = failed("the worker produced no snapshot; room left running");
+        return;
+      }
+      const log = (level, ...args) => sup.roomLog(room, level, ...args);
+      if (!await putSnapshotWithRetry(sup.store, oldKey, bytes, sup.processMetrics, log)) {
+        room.state = "running";
+        outcome = failed("could not persist the pre-migration snapshot; room left running");
+        return;
+      }
+      if (!await putSnapshotWithRetry(
+        sup.store,
+        saveKey(oldKey, PRE_MIGRATION_SAVE_ID),
+        bytes,
+        sup.processMetrics,
+        log
+      )) {
+        room.state = "running";
+        outcome = failed("could not retain the pre-migration save; room left running");
+        return;
+      }
+      worker.post({ t: "stop" });
+      await worker.terminate();
+      room.worker = void 0;
+      sup.clearRoomTimer(room);
+    } else {
+      bytes = await sup.store.get(oldKey) ?? void 0;
+      if (!bytes) {
+        outcome = failed("hibernated room has no snapshot to migrate");
+        return;
+      }
+      const ok = await putSnapshotWithRetry(
+        sup.store,
+        saveKey(oldKey, PRE_MIGRATION_SAVE_ID),
+        bytes,
+        sup.processMetrics,
+        (level, ...args) => sup.roomLog(room, level, ...args)
+      );
+      if (!ok) {
+        outcome = failed("could not retain the pre-migration save; room left hibernated");
+        return;
+      }
+    }
+    room.state = "waking";
+    room.version = toVersion;
+    const started = await sup.startWorker(room, bytes, chain);
+    if (!started) {
+      room.version = fromVersion;
+      const revived = await sup.startWorker(room, bytes);
+      if (!revived) {
+        room.worker = void 0;
+        room.state = "hibernated";
+        outcome = failed(
+          `migration to v${toVersion} failed and the v${fromVersion} worker would not restart; room left hibernated with its state intact`
+        );
+        return;
+      }
+      await sup.rejoinAll(room);
+      for (const frame of room.wakeQueue.splice(0)) sup.deliverQueued(room, frame);
+      room.state = "running";
+      outcome = failed(`migration to v${toVersion} failed; room restarted on v${fromVersion}`);
+      return;
+    }
+    sup.failOutdatedSessions(room, toVersion);
+    await sup.rejoinAll(room);
+    for (const clientId of room.pendingLeaves) {
+      room.worker?.post({ t: "leave", clientId, reason: "timeout" });
+    }
+    room.pendingLeaves.clear();
+    const queued = room.wakeQueue.splice(0);
+    for (const frame of queued) sup.deliverQueued(room, frame);
+    if (room.state === "waking") room.state = "running";
+    room.metrics.wakes++;
+    const ms = performance.now() - startedAt;
+    room.metrics.lastWakeMs = ms;
+    if (ms > room.metrics.maxWakeMs) room.metrics.maxWakeMs = ms;
+    sup.roomLog(room, "info", `migrated v${fromVersion} \u2192 v${toVersion}, gap ${ms.toFixed(1)} ms`);
+    outcome = { roomId: room.id, outcome: "migrated" };
+  })();
+  room.transition = work.catch((err) => {
+    sup.roomLog(room, "error", "migrate failed", err);
+    outcome = failed(err instanceof Error ? err.message : String(err));
+    if (room.state === "waking" || room.state === "hibernating") {
+      room.version = fromVersion;
+      room.state = room.worker ? "running" : "hibernated";
+    }
+  });
+  await room.transition;
+  return outcome;
+}
 async function flushAll(sup) {
+  sup.quiesceAlarms();
+  let allOk = true;
   for (const room of sup.registry.values()) {
     await room.transition.catch(() => {
     });
@@ -518,29 +815,35 @@ async function flushAll(sup) {
       continue;
     }
     const worker = room.worker;
-    if (worker) {
-      try {
-        const bytes = await worker.serialize();
-        if (bytes) {
-          await putSnapshotWithRetry(
-            sup.store,
-            sup.storeKey(room),
-            bytes,
-            sup.processMetrics,
-            (level, ...args) => sup.roomLog(room, level, ...args)
-          );
-        }
-      } catch (err) {
-        sup.roomLog(room, "error", "flush: snapshot failed", err);
+    if (!worker) {
+      sup.clearRoomTimer(room);
+      room.state = "hibernated";
+      continue;
+    }
+    try {
+      const bytes = await worker.serialize();
+      if (bytes) {
+        const ok = await putSnapshotWithRetry(
+          sup.store,
+          sup.storeKey(room),
+          bytes,
+          sup.processMetrics,
+          (level, ...args) => sup.roomLog(room, level, ...args)
+        );
+        if (!ok) throw new Error("snapshot flush abandoned after retries");
       }
       worker.post({ t: "stop" });
       await worker.terminate();
       room.worker = void 0;
       room.metrics.hibernations++;
+      sup.clearRoomTimer(room);
+      room.state = "hibernated";
+    } catch (err) {
+      sup.roomLog(room, "error", "flush: snapshot failed, leaving the room running", err);
+      allOk = false;
     }
-    sup.clearRoomTimer(room);
-    room.state = "hibernated";
   }
+  return allOk;
 }
 
 // ../supervisor/src/metrics.ts
@@ -629,6 +932,18 @@ var RoomRecord = class {
    * before a deploy keep theirs until they idle (per-room drain, plan §3.3).
    */
   version = 0;
+  /**
+   * D26: this room's durable alarms. Deliberately on the *record*, not on the worker: the record
+   * outlives every hibernation, which is exactly the lifetime an alarm needs. Nothing here is
+   * ever serialized into the hibernation blob.
+   */
+  alarms = new AlarmSet();
+  /**
+   * D24: a save generation to start this room from instead of its live snapshot, set from the
+   * placement instruction and consumed by the next start. One shot: a restore is an event, not a
+   * standing property of the room.
+   */
+  pendingRestoreSaveId;
   /** Serialises room-level async work (start / wake / restart / hibernate). */
   transition = Promise.resolve();
   /** Periodic crash-safety snapshot (event-mode bundle rooms) or the relay idle timer. */
@@ -653,6 +968,7 @@ var RoomRecord = class {
     this.logs.push(level, args);
   }
   info() {
+    const dueAlarmAt = this.alarms.earliestDueAt;
     return {
       id: this.id,
       state: this.state,
@@ -660,7 +976,9 @@ var RoomRecord = class {
       tick: this.lastTick,
       clients: [...this.clients.values()].map((s) => s.info()),
       metrics: { ...this.metrics, workerElu: this.worker?.elu ?? 0 },
-      createdAt: this.createdAt
+      createdAt: this.createdAt,
+      ...dueAlarmAt !== void 0 ? { dueAlarmAt } : {},
+      ...this.alarms.size > 0 ? { alarms: this.alarms.size } : {}
     };
   }
 };
@@ -716,6 +1034,14 @@ var Session = class {
   room;
   role = "";
   name = "";
+  /** Week 13 (D27): the verified JWT subject, when this session authenticated with one. Flows
+   *  to `JoinOptions.playerId` and therefore `ctx.playerId`; undefined for key joins, whose
+   *  playerId stays the client id exactly as before. */
+  playerId;
+  /** The schema hash the client presented at HELLO (week 13, D28): a migrate must close a
+   *  session whose schema is older than the room's new version by name (`E_SCHEMA_MISMATCH`)
+   *  rather than send it a resync WELCOME it cannot decode. */
+  schemaHash8;
   /** Set when the session was rejected/kicked: no grace window on close. */
   fatal = false;
   /** Slow consumers are closed but keep their grace window (a resume gets a fresh snapshot). */
@@ -910,9 +1236,13 @@ var WorkerHost = class {
     });
   }
   /** Hibernation/crash-safety snapshot. `undefined` when the worker died or timed out. */
-  async serialize(timeoutMs = 1e4) {
+  /**
+   * `forSave` (D24) takes the snapshot without the hibernation side effects, so a `room.save()`
+   * leaves the room running — and, crucially, does not reject the very host call that asked.
+   */
+  async serialize(timeoutMs = 1e4, forSave = false) {
     const msg = await this.request(
-      (reqId) => ({ t: "serialize", reqId }),
+      (reqId) => ({ t: "serialize", reqId, ...forSave ? { forSave: true } : {} }),
       timeoutMs
     );
     return msg?.t === "serialized" ? msg.bytes : void 0;
@@ -949,6 +1279,14 @@ var WS_PING_MS = 2e4;
 var WS_PING_MISSES = 2;
 var MAX_STRIKES = 3;
 var JOIN_TIMEOUT_MS = 15e3;
+var KvUnavailable = class extends Error {
+  code = KV_ERRORS.unavailable;
+  name = "KvUnavailable";
+};
+function codeOf(err) {
+  const code = err?.code;
+  return typeof code === "string" && code.startsWith("E_") ? code : void 0;
+}
 function defaultSetSystemTime(epochMs) {
   if (process.platform !== "linux") return Promise.resolve(false);
   return new Promise((resolve2, reject) => {
@@ -979,6 +1317,15 @@ var SupervisorImpl = class {
     this.config = config;
     this.limits = { ...DEFAULT_LIMITS, ...config.limits };
     this.store = config.store;
+    for (const [roomId, saveId] of Object.entries(config.restoreRooms ?? {})) {
+      if (typeof saveId === "string" && saveId !== "") this.pendingRestores.set(roomId, saveId);
+    }
+    if (this.pendingRestores.size > 0) {
+      this.log(
+        "info",
+        `placement carries ${this.pendingRestores.size} pending restore(s): ` + [...this.pendingRestores].map(([r, sv]) => `${r}<-${sv}`).join(", ")
+      );
+    }
     this.resumeSecret = config.resumeSecret ?? randomBytes(32).toString("base64url");
     if (config.resumeSecret === void 0) {
       this.log("warn", "no resumeSecret configured: resume tokens die with this process");
@@ -1050,8 +1397,20 @@ var SupervisorImpl = class {
   /** True only once the tenant-idle flush has *completed* — `/admin/idle` reports idle from this,
    *  so the host agent never snapshots a VM whose rooms are still mid-flush to the store. */
   idleFlushed = false;
+  /** Consecutive tenant-idle flush attempts (§10.8) that left at least one room unflushed —
+   *  reported on `/admin/idle` so the host-agent can escalate instead of reading "not idle yet"
+   *  forever. Reset the moment a flush succeeds cleanly, or a client reconnects. */
+  flushFailures = 0;
   idleTimer;
   pingTimer;
+  /**
+   * D24: `roomId -> saveId` placement instructions that have not been consumed yet. Populated
+   * from `SupervisorConfig.restoreRooms` at boot — placement is the only channel into a tenant,
+   * because the agent's admin view of one is read-only by design.
+   */
+  pendingRestores = /* @__PURE__ */ new Map();
+  /** D26: serialises the alarm-sidecar writes for one room, so the last change wins. */
+  alarmWrites = /* @__PURE__ */ new Map();
   // -------------------------------------------------------------------------
   // Boot / shutdown
   // -------------------------------------------------------------------------
@@ -1082,6 +1441,110 @@ var SupervisorImpl = class {
       "info",
       `supervisor listening on ${this.port} (${this.bundle ? "bundle" : "relay"} tenant)`
     );
+    await this.resumeAlarmedRooms();
+  }
+  /**
+   * D26, and the piece staging caught missing: **start every room that owes an alarm**, at boot.
+   *
+   * Rooms are created lazily, by a joining client. That is right for every other purpose and
+   * exactly wrong here: the whole point of the tenant-stopped case is that control places a tenant
+   * for a room *nobody is in*. Without this, the tenant came up, created no rooms, fired nothing,
+   * and control re-placed it every backoff window forever — which is precisely what the staging
+   * run showed, with `dueAlarmAt` still set two and a half minutes past due and the room's
+   * `lastSeen` frozen before the stop.
+   *
+   * Deliberately driven from the **store**, not from the placement instruction. Control could name
+   * the due room — it queried it — but that only fixes the case where the tenant was placed *for*
+   * that alarm. A tenant placed for an ordinary join, with some other room's alarm overdue, would
+   * still never fire it. Scanning the sidecars means any tenant boot, for any reason,
+   * re-establishes everything the project owes.
+   *
+   * Cost is one prefix list per boot plus one room start per armed alarm. A room whose alarm is
+   * days out is started and hibernates again ~`idleMs` later; the timer lives on the record, which
+   * survives that.
+   */
+  async resumeAlarmedRooms() {
+    if (!this.bundle) {
+      this.log("info", "no bundle on this tenant \u2014 no rooms to resume for pending alarms");
+      return;
+    }
+    const prefix = `${this.config.projectId}/`;
+    let keys;
+    try {
+      keys = await this.store.list(prefix);
+    } catch (err) {
+      this.log("warn", `could not list "${prefix}" for rooms with pending alarms at boot`, err);
+      return;
+    }
+    const rooms = /* @__PURE__ */ new Set();
+    for (const key of keys) {
+      const roomId = roomIdOfAlarmsKey(prefix, key);
+      if (roomId !== void 0 && !this.registry.get(roomId)) rooms.add(roomId);
+    }
+    if (rooms.size === 0) {
+      this.log(
+        "info",
+        `no rooms to resume: listed ${keys.length} key(s) under "${prefix}", none an alarm sidecar` + (keys.length > 0 ? ` (e.g. ${keys.slice(0, 3).join(", ")})` : "")
+      );
+      return;
+    }
+    this.log(
+      "info",
+      `resuming ${rooms.size} room(s) with pending alarms: ${[...rooms].join(", ")}`
+    );
+    for (const roomId of [...rooms].sort()) {
+      try {
+        await this.ensureRoom(roomId);
+      } catch (err) {
+        this.log("warn", `could not resume room ${roomId} for its pending alarm`, err);
+      }
+    }
+  }
+  /**
+   * Everything a **VM-snapshot restore** owes the alarm clock, run from `/admin/resume` once the
+   * guest wall clock has been corrected.
+   *
+   * This exists because the fleet's restart path is not a process restart. `stopTenant` snapshots
+   * the VM and the next placement loads that snapshot with `resume_vm: true`, so the supervisor
+   * comes back *mid-flight*: `boot()` finished minutes or hours ago and does not run again. Every
+   * recovery step wired into boot — `resumeAlarmedRooms` included — is therefore invisible on the
+   * only restart production actually performs. Staging showed it exactly: control placed a tenant
+   * within 3.6 s of the alarm being due, eight times, and the tenant came up with no rooms, no
+   * logs, and nothing armed (docs/m2-week12-report.md §4.3).
+   *
+   * Two halves, because a restore can be missing a room in two different ways:
+   *
+   *  - **Rooms the snapshot carried.** Their `RoomRecord`s are restored intact, `due` map and all,
+   *    but with no timer and no delivery handler: `quiesceAlarms()` detaches both before the
+   *    tenant flushes, and only a room *start* re-attaches them. So they come back holding a
+   *    perfectly good set of alarms that nothing will ever fire. `loadAlarms` re-attaches and
+   *    re-arms, and `attach()`'s `rearm()` fires anything already overdue on the next turn.
+   *  - **Rooms it did not.** A tenant snapshotted before a room existed, or one whose record was
+   *    dropped, still owes that room's sidecar — `resumeAlarmedRooms` starts those, skipping the
+   *    ones the first half just handled.
+   *
+   * Order matters: re-arm what we have before listing the store, so the sweep sees a registry that
+   * is already correct and does not start a room that only needed its clock back.
+   *
+   * The clock correction has to land first for any of it to be right. `AlarmSet` measures due
+   * times against `Date.now()` — wall clock, because "due at" has to survive a process that was
+   * not running — and a restored guest's clock is behind by however long the VM was paused (89.5 s
+   * in the staging trace). Re-arming before the correction would compute every delay against the
+   * stale clock and put every alarm that far into the future.
+   */
+  async resumeFromVmSnapshot() {
+    const rooms = this.registry.values().filter((r) => !r.relay && r.state !== "closed");
+    if (rooms.length > 0) {
+      this.log("info", `resume: re-arming alarms for ${rooms.length} restored room(s)`);
+      for (const room of rooms) {
+        try {
+          await this.loadAlarms(room);
+        } catch (err) {
+          this.roomLog(room, "warn", "could not re-arm this room's alarms after a VM resume", err);
+        }
+      }
+    }
+    await this.resumeAlarmedRooms();
   }
   ready() {
     return this.readyPromise;
@@ -1114,6 +1577,7 @@ var SupervisorImpl = class {
   async close() {
     if (this.closing) return;
     this.closing = true;
+    this.quiesceAlarms();
     if (this.idleTimer) clearInterval(this.idleTimer);
     if (this.pingTimer) clearInterval(this.pingTimer);
     try {
@@ -1183,7 +1647,11 @@ var SupervisorImpl = class {
         json({
           idle: this.idleFlushed && this.sessions.size === 0,
           sockets: this.sessions.size,
-          idleForMs: this.idleSince > 0 ? Date.now() - this.idleSince : 0
+          idleForMs: this.idleSince > 0 ? Date.now() - this.idleSince : 0,
+          // §10.8 escalation: consecutive flush passes that left a room unflushed. The host agent
+          // treats >=3 as worth an error-level log (once, deduped) instead of reading the tenant
+          // as merely slow to go idle.
+          flushFailures: this.flushFailures
         });
         return true;
       case "/admin/rooms":
@@ -1239,6 +1707,95 @@ var SupervisorImpl = class {
               );
             }
             json({ ok: true, applied, beforeMs, afterMs: Date.now() });
+            try {
+              await this.resumeFromVmSnapshot();
+            } catch (err) {
+              this.log("warn", "resume recovery failed", err);
+            }
+          })();
+        });
+        return true;
+      }
+      // Week 13, §2: the SECOND write on this otherwise read-only surface (`/admin/resume` is the
+      // first, and the carve-out reasoning is the same): a deployment created while this tenant
+      // is running has no other way in — the bundle drive is a read-only image packed at boot, so
+      // the agent POSTs the new versions' bytes here and the supervisor registers them from
+      // tmpfs. `strategy: 'drain'` stops there (new rooms take the new version, running rooms
+      // drain); `'migrate'` additionally moves every live room onto it (D28, §1.2).
+      case "/admin/deploy": {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end('{"error":"POST only"}');
+          return true;
+        }
+        let body = "";
+        req.on("data", (d) => {
+          body += d.toString();
+        });
+        req.on("end", () => {
+          void (async () => {
+            let parsed;
+            try {
+              parsed = JSON.parse(body || "{}");
+            } catch {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"body is not JSON"}');
+              return;
+            }
+            const strategy = parsed.strategy ?? "drain";
+            if (strategy !== "drain" && strategy !== "migrate") {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: `unknown strategy ${String(strategy)}` }));
+              return;
+            }
+            if (!Array.isArray(parsed.deployments)) {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"body must carry a deployments array"}');
+              return;
+            }
+            try {
+              const added = [];
+              let dir;
+              for (const d of parsed.deployments) {
+                if (typeof d.version !== "number" || !Number.isInteger(d.version)) {
+                  throw new Error("every deployment needs an integer version");
+                }
+                if (this.deployments.has(d.version)) continue;
+                dir ??= await mkdtemp(nodePath.join(tmpdir(), "irtio-deploy-"));
+                let bundlePath;
+                let migrationPath;
+                if (typeof d.bundleB64 === "string") {
+                  bundlePath = nodePath.join(dir, `v${d.version}.mjs`);
+                  await writeFile(bundlePath, Buffer.from(d.bundleB64, "base64"));
+                }
+                if (typeof d.migrationB64 === "string") {
+                  migrationPath = nodePath.join(dir, `m${d.version}.mjs`);
+                  await writeFile(migrationPath, Buffer.from(d.migrationB64, "base64"));
+                }
+                await this.addBundle({
+                  version: d.version,
+                  ...typeof d.schemaJson === "string" ? { schemaJson: d.schemaJson } : {},
+                  ...bundlePath !== void 0 ? { bundlePath } : {},
+                  ...migrationPath !== void 0 ? { migrationPath } : {}
+                });
+                added.push(d.version);
+              }
+              const rooms = strategy === "migrate" ? await this.migrateAllRooms() : void 0;
+              json({
+                ok: true,
+                deploymentVersion: this.deploymentVersion,
+                added,
+                ...rooms !== void 0 ? { rooms } : {}
+              });
+            } catch (err) {
+              this.log("error", "admin deploy failed", err);
+              res.writeHead(500, { "content-type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: err instanceof Error ? err.message : String(err)
+                })
+              );
+            }
           })();
         });
         return true;
@@ -1321,6 +1878,19 @@ var SupervisorImpl = class {
       `deployment v${ref.version} registered; new rooms use v${this.deploymentVersion}, ${draining.length} room(s) draining on older versions`
     );
   }
+  /**
+   * Week 13 (D28): moves every live room onto the newest deployment, **one at a time** — a
+   * tenant is one vCPU (week-12 §9.1), and a fleet of workers spawning at once on it is how the
+   * week would find that out. Registry order; each room's outcome is reported, never thrown.
+   */
+  async migrateAllRooms() {
+    const target = this.deploymentVersion;
+    const out = [];
+    for (const room of [...this.registry.values()]) {
+      out.push(await migrateRoom(this, room, target));
+    }
+    return out;
+  }
   /**
    * The newest snapshot for a room across every version prefix, plus the version it was written
    * under. Week-3 keys with no `@v` suffix read as version 0.
@@ -1386,6 +1956,7 @@ var SupervisorImpl = class {
     this.idleSince = 0;
     this.idleFired = false;
     this.idleFlushed = false;
+    this.flushFailures = 0;
     ws.on("close", () => this.onSocketClose(session));
     ws.on("error", () => {
     });
@@ -1551,14 +2122,30 @@ var SupervisorImpl = class {
       );
       return;
     }
-    if (hello.credential.kind !== "key" || hello.credential.key !== this.config.projectId) {
+    const credential = hello.credential;
+    if (credential.kind === "token" || credential.key !== this.config.projectId) {
       session.fail("E_AUTH", formatError("E_AUTH"));
       return;
     }
-    if (!this.helloBuckets.take(hello.credential.key)) {
+    if (!this.helloBuckets.take(credential.key)) {
       session.fail("E_RATE_LIMITED", formatError("E_RATE_LIMITED"));
       return;
     }
+    let jwt;
+    if (credential.kind === "jwt") {
+      const issuers = this.config.jwtIssuers;
+      if (issuers === void 0 || issuers.length === 0) {
+        session.fail("E_AUTH", "this project has no JWT secret \u2014 mint one: irtio keys jwt-secret");
+        return;
+      }
+      const verdict = verifyJwt(issuers, credential.token, this.config.projectId);
+      if (!verdict.ok) {
+        const vars = verdict.code === "E_TOKEN_MALFORMED" ? { reason: verdict.reason } : verdict.code === "E_TOKEN_BAD_ISSUER" ? { issuer: verdict.reason } : verdict.code === "E_TOKEN_BAD_ALG" ? { alg: verdict.reason } : {};
+        session.fail(verdict.code, formatError(verdict.code, vars));
+        return;
+      }
+      jwt = verdict;
+    }
     if (this.bundle) {
       const known = [...this.deployments.values()].some(
         (d) => d.bundle !== void 0 && bytesEqual(hello.schemaHash8, d.bundle.hash8)
@@ -1572,8 +2159,10 @@ var SupervisorImpl = class {
       return;
     }
     session.state = "joining";
-    session.role = hello.role ?? "";
+    session.role = jwt?.role ?? hello.role ?? "";
     session.name = hello.name ?? "";
+    session.playerId = jwt?.playerId;
+    session.schemaHash8 = hello.schemaHash8;
     let resume;
     if (hello.resumeToken !== void 0 && hello.resumeToken !== "") {
       resume = verifyResume(this.resumeSecret, hello.resumeToken);
@@ -1599,6 +2188,10 @@ var SupervisorImpl = class {
     } else {
       roomId = newRoomCode((code) => this.registry.has(code));
     }
+    if (jwt?.roomId !== void 0 && jwt.roomId !== roomId) {
+      session.fail("E_TOKEN_WRONG_ROOM", formatError("E_TOKEN_WRONG_ROOM"));
+      return;
+    }
     const room = await this.ensureRoom(roomId);
     if (!room) {
       session.fail("E_INTERNAL", formatError("E_INTERNAL"));
@@ -1652,8 +2245,11 @@ var SupervisorImpl = class {
       const config = this.bundle ? this.bundle.config : relayConfig(this.limits);
       const room = new RoomRecord(roomId, this.bundle === void 0, config);
       room.version = this.deploymentVersion;
+      room.pendingRestoreSaveId = this.pendingRestores.get(roomId);
+      this.pendingRestores.delete(roomId);
       this.registry.set(room);
-      const found = await this.findSnapshot(roomId);
+      const restored = await this.loadPendingRestore(room);
+      const found = restored ?? await this.findSnapshot(roomId);
       const snapshot = found?.bytes;
       if (room.relay) {
         room.relayRoom = snapshot ? RelayRoom.restore(snapshot) : RelayRoom.create();
@@ -1662,6 +2258,15 @@ var SupervisorImpl = class {
         this.armRelayIdle(room);
         return room;
       }
+      if (found && found.version > room.version) {
+        this.roomLog(
+          room,
+          "error",
+          `snapshot is at v${found.version}, newer than the serving deployment v${room.version} (rolled back?); refusing to decode it with an older schema`
+        );
+        this.registry.delete(roomId);
+        return void 0;
+      }
       let migrate;
       if (found && found.version !== room.version) {
         try {
@@ -1686,6 +2291,8 @@ var SupervisorImpl = class {
       }
       room.state = "running";
       this.armSnapshotTimer(room);
+      if (restored) await this.commitRestore(room);
+      await this.loadAlarms(room);
       return room;
     })();
     this.creating.set(roomId, create);
@@ -1752,6 +2359,282 @@ var SupervisorImpl = class {
     }
     return true;
   }
+  // -------------------------------------------------------------------------
+  // Week 12: saves (D24), player KV (D25), durable alarms (D26)
+  // -------------------------------------------------------------------------
+  /**
+   * Serves one `room.save()` / `room.kv.*`. Every path answers exactly once, including the
+   * failures — a room holding a promise the host silently dropped would wedge until the
+   * runtime's own 10 s deadline, and the room deserves the real reason before then.
+   */
+  async runHostCall(room, reqId, call) {
+    let result;
+    try {
+      result = await this.performHostCall(room, call);
+    } catch (err) {
+      result = {
+        ok: false,
+        code: codeOf(err) ?? "E_INTERNAL",
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+    room.worker?.post({ t: "hostResult", reqId, result });
+  }
+  async performHostCall(room, call) {
+    switch (call.kind) {
+      case "save": {
+        const saveId = await this.saveRoom(room);
+        return { ok: true, value: saveId };
+      }
+      case "kvGet": {
+        const value = await this.requireKv().get(call.playerId, call.key);
+        return value === void 0 ? { ok: true } : { ok: true, value };
+      }
+      case "kvSet":
+        await this.requireKv().set(call.playerId, call.key, call.value);
+        return { ok: true };
+      case "kvDelete":
+        await this.requireKv().delete(call.playerId, call.key);
+        return { ok: true };
+    }
+  }
+  requireKv() {
+    const kv = this.config.kv;
+    if (!kv) {
+      throw new KvUnavailable(
+        "player kv is not configured for this tenant (no control plane behind it)"
+      );
+    }
+    return kv;
+  }
+  /**
+   * D24: one save generation. Serializes exactly the way hibernation does — same
+   * `worker.serialize()`, same bytes, same `putSnapshotWithRetry` durability — writes it under
+   * the room's `…/saves/` prefix, and prunes down to the retention limit.
+   *
+   * Containment, matching `hibernateRoom`'s rule: a failed save throws (so the room's promise
+   * rejects with the reason) and touches nothing. The live hibernation key is not written on this
+   * path at all, so a room can never be left worse off than if it had never called `save()`.
+   */
+  async saveRoom(room) {
+    const worker = room.worker;
+    if (!worker || room.state !== "running") {
+      throw new Error(`room.save: the room is ${room.state}, not running`);
+    }
+    const bytes = await worker.serialize(1e4, true);
+    if (!bytes) throw new Error("room.save: the worker produced no snapshot");
+    const liveKey = this.storeKey(room);
+    const saveId = mintSaveId(Date.now(), randomBytes(2).readUInt16BE(0));
+    const key = saveKey(liveKey, saveId);
+    const ok = await putSnapshotWithRetry(
+      this.store,
+      key,
+      bytes,
+      this.processMetrics,
+      (level, ...args) => this.roomLog(room, level, ...args)
+    );
+    if (!ok) throw new Error("room.save: the store would not take the snapshot");
+    this.roomLog(room, "info", `saved generation ${saveId} (${bytes.length} bytes)`);
+    try {
+      const saves = await listSaves(this.store, liveKey);
+      const deleted = await pruneSaves(
+        this.store,
+        saves,
+        this.limits.saveRetain,
+        (level, ...a) => this.roomLog(room, level, ...a)
+      );
+      if (deleted > 0) {
+        this.roomLog(room, "info", `save retention: pruned ${deleted} old generation(s)`);
+      }
+    } catch (err) {
+      this.roomLog(room, "warn", "save retention failed (the save itself is fine)", err);
+    }
+    return saveId;
+  }
+  /**
+   * D24: the bytes a pending restore names, or `undefined` when there is no restore pending.
+   *
+   * A named save that has gone (pruned, or a bad id) logs a warning and returns `undefined`, so
+   * the room starts from its live snapshot. That is deliberate and it is the single most
+   * important decision in this path: failing the start instead would lose a live room because a
+   * *save* went missing, which is far worse than not restoring.
+   */
+  async loadPendingRestore(room) {
+    const saveId = room.pendingRestoreSaveId;
+    if (saveId === void 0) return void 0;
+    const liveKey = this.storeKey(room);
+    let bytes;
+    try {
+      bytes = await this.store.get(saveKey(liveKey, saveId));
+    } catch (err) {
+      this.roomLog(room, "error", `restore: could not read save ${saveId}`, err);
+    }
+    if (!bytes) {
+      this.roomLog(
+        room,
+        "warn",
+        `restore: save ${saveId} is gone; starting from the room's own snapshot instead`
+      );
+      room.pendingRestoreSaveId = void 0;
+      return void 0;
+    }
+    this.roomLog(room, "info", `restoring from save ${saveId} (${bytes.length} bytes)`);
+    return { bytes, version: room.version };
+  }
+  /**
+   * Writes the restored state over the live key. Without this a restore would survive only until
+   * the next wake, which would read the *old* live snapshot and quietly undo it — the kind of bug
+   * that looks like "the restore worked and then stopped working".
+   */
+  async commitRestore(room) {
+    const worker = room.worker;
+    if (!worker) return;
+    const bytes = await worker.serialize(1e4, true).catch(() => void 0);
+    if (!bytes) {
+      this.roomLog(room, "warn", "restore: could not re-write the live snapshot");
+      return;
+    }
+    const ok = await putSnapshotWithRetry(
+      this.store,
+      this.storeKey(room),
+      bytes,
+      this.processMetrics,
+      (level, ...args) => this.roomLog(room, level, ...args)
+    );
+    if (!ok) this.roomLog(room, "error", "restore: the live snapshot could not be re-written");
+    else await this.dropNewerLiveKeys(room);
+    room.pendingRestoreSaveId = void 0;
+  }
+  /**
+   * Week 13 (D28 rollback): a restore that commits under version V must not leave a live key at
+   * a NEWER version behind — `findSnapshot` picks the newest, so the next cold start would
+   * resurrect exactly the state the restore replaced and migrate it forward again. Before
+   * rollback this case could not occur (a pending restore always landed on the newest version);
+   * a rollback is precisely the case where it does. Save generations are untouched — only live
+   * keys (and their alarm sidecars) go.
+   */
+  async dropNewerLiveKeys(room) {
+    const base = `${this.config.projectId}/${room.id}`;
+    let keys;
+    try {
+      keys = await this.store.list(base);
+    } catch {
+      return;
+    }
+    for (const key of keys) {
+      let version;
+      if (key === base) version = 0;
+      else if (key.startsWith(`${base}@v`)) {
+        version = Number(key.slice(base.length + 2));
+        if (!Number.isInteger(version)) continue;
+      } else continue;
+      if (version > room.version) {
+        this.roomLog(room, "info", `restore: dropping the rolled-back live key ${key}`);
+        await this.store.delete(key).catch(() => {
+        });
+        await this.store.delete(alarmsKey(key)).catch(() => {
+        });
+      }
+    }
+  }
+  /**
+   * D26: re-arms this room's alarms from the sidecar and starts persisting changes to it.
+   *
+   * Anything already due fires immediately — an alarm is "at or after", never before, and a
+   * tenant that was stopped for an hour owes the room an hour-late alarm rather than nothing.
+   */
+  async loadAlarms(room) {
+    if (room.relay) return;
+    let persisted = [];
+    try {
+      const bytes = await this.store.get(alarmsKey(this.storeKey(room)));
+      if (bytes) persisted = decodeAlarms(bytes);
+    } catch (err) {
+      this.roomLog(room, "warn", "could not read this room's alarms; starting with none", err);
+    }
+    room.alarms.onChange = () => this.persistAlarms(room);
+    room.alarms.attach((names) => this.deliverAlarms(room, names));
+    if (persisted.length > 0) {
+      room.alarms.load(persisted);
+      const overdue = room.alarms.fireDue();
+      if (overdue.length > 0) {
+        this.roomLog(
+          room,
+          "info",
+          `firing ${overdue.length} overdue alarm(s): ${overdue.join(", ")}`
+        );
+      }
+    }
+  }
+  /**
+   * Delivers due alarms into the room, **waking it first if it is asleep**. This is the whole
+   * hibernated case: the timer kept counting because it lives on the record rather than in the
+   * worker, and the wake is the same one a joining client would have triggered.
+   *
+   * The loop is not defensive padding — it is the fix for a real race that cost an hour to find.
+   * `fireDue` removes an alarm before delivering it, so between the state check and the `await`
+   * the room can slip into hibernation (`hibernateRoom` flips the state synchronously). A single
+   * check-then-await therefore saw `running`, woke up to `hibernated`, and dropped an alarm that
+   * no longer existed anywhere — a round timer that simply never fired, with a warning nobody was
+   * watching. Re-checking after every transition covers the slip, and anything still undeliverable
+   * is **re-armed** rather than discarded: a durable alarm that this process could not deliver is
+   * the next placement's problem, not a lost one.
+   */
+  deliverAlarms(room, names) {
+    void (async () => {
+      for (let attempt = 0; attempt < 4; attempt++) {
+        if (room.state === "closed") return;
+        if (room.state === "running" && room.worker) {
+          for (const name of names) room.worker.post({ t: "alarm", name });
+          return;
+        }
+        if (room.state === "hibernated") {
+          await wakeRoom(this, room);
+          continue;
+        }
+        await room.transition.catch(() => {
+        });
+      }
+      this.roomLog(
+        room,
+        "warn",
+        `alarm(s) ${names.join(", ")} came due while the room was ${room.state}; re-armed for the next start rather than dropped`
+      );
+      const now = Date.now();
+      for (const name of names) room.alarms.set(name, now);
+    })();
+  }
+  /**
+   * Persists the armed set. Serialised per room so the last change wins: two alarms armed in the
+   * same handler must not race into the sidecar in the wrong order and leave it describing a
+   * state the room was never in.
+   */
+  persistAlarms(room) {
+    const key = alarmsKey(this.storeKey(room));
+    const prior = this.alarmWrites.get(room.id) ?? Promise.resolve();
+    const next = prior.catch(() => {
+    }).then(async () => {
+      const entries = room.alarms.entries();
+      try {
+        if (entries.length === 0) await this.store.delete(key);
+        else await this.store.put(key, encodeAlarms(entries));
+      } catch (err) {
+        this.roomLog(room, "warn", "could not persist this room's alarms", err);
+      }
+    });
+    this.alarmWrites.set(room.id, next);
+  }
+  /**
+   * Stops every room's alarm clock without touching what is armed. Used on shutdown and on the
+   * tenant-idle flush: in both, the process is about to stop being the thing that owes the room
+   * an alarm, and the persisted sidecar is about to become the only record of it.
+   */
+  quiesceAlarms() {
+    for (const room of this.registry.values()) {
+      room.alarms.onChange = void 0;
+      room.alarms.detach();
+    }
+  }
   armSnapshotTimer(room) {
     this.clearRoomTimer(room);
     const every = this.limits.snapshotEveryMs;
@@ -1787,12 +2670,15 @@ var SupervisorImpl = class {
   /** A hibernated room with no sessions left has nothing in memory worth keeping (plan §3.4). */
   dropRoomIfIdle(room) {
     if (room.clients.size > 0) return;
+    if (room.alarms.size > 0) return;
     if (room.state === "hibernated" || room.state === "closed") this.registry.delete(room.id);
   }
   closeRoom(room, code, message) {
     if (room.state === "closed") return;
     room.state = "closed";
     this.clearRoomTimer(room);
+    room.alarms.detach();
+    room.alarms.onChange = void 0;
     for (const session of [...room.clients.values()]) {
       session.fatal = true;
       session.sendError(code, message, true);
@@ -1807,6 +2693,8 @@ var SupervisorImpl = class {
     this.registry.delete(room.id);
     void this.store.delete(this.storeKey(room)).catch(() => {
     });
+    void this.store.delete(alarmsKey(this.storeKey(room))).catch(() => {
+    });
     this.roomLog(room, "info", `room closed: ${message}`);
   }
   // -------------------------------------------------------------------------
@@ -1851,6 +2739,8 @@ var SupervisorImpl = class {
         clientId: session.clientId,
         ...session.role !== "" ? { role: session.role } : {},
         ...session.name !== "" ? { name: session.name } : {},
+        // D27: the verified JWT subject; absent for key joins (playerId stays the client id).
+        ...session.playerId !== void 0 ? { playerId: session.playerId } : {},
         ...reconnecting ? { reconnecting: true } : {}
       });
     });
@@ -1905,6 +2795,25 @@ var SupervisorImpl = class {
       room.metrics.framesOut++;
     }
   }
+  /**
+   * Week 13 (D28): run between a migrate's worker start and its `rejoinAll`. A connected client
+   * whose schema hash is not the migrated version's cannot decode the resync WELCOME that is
+   * about to be sent — close it with `E_SCHEMA_MISMATCH` (fatal, by name) so the game can fetch
+   * the new client, instead of feeding it bytes it will mis-decode. Clients already on the new
+   * schema (the page reloaded after the client shipped) rejoin normally.
+   */
+  failOutdatedSessions(room, version) {
+    const hash8 = this.deployments.get(version)?.bundle?.hash8;
+    if (!hash8) return;
+    for (const session of room.connected()) {
+      if (session.schemaHash8 !== void 0 && !bytesEqual(session.schemaHash8, hash8)) {
+        session.fail(
+          "E_SCHEMA_MISMATCH",
+          "the room migrated to a newer deployment; reconnect with an updated client"
+        );
+      }
+    }
+  }
   /** Re-joins every still-connected socket after a wake or a crash restart, with a resync WELCOME. */
   async rejoinAll(room) {
     for (const session of room.connected()) {
@@ -2105,6 +3014,12 @@ var SupervisorImpl = class {
       case "sleep":
         void hibernateRoom(this, room);
         return;
+      case "hostCall":
+        void this.runHostCall(room, msg.reqId, msg.call);
+        return;
+      case "setAlarm":
+        room.alarms.set(msg.name, msg.atMs);
+        return;
       case "log":
         room.log(msg.level, ...msg.args);
         return;
@@ -2173,13 +3088,21 @@ var SupervisorImpl = class {
     this.idleFired = true;
     void (async () => {
       this.log("info", "tenant idle: flushing every room");
+      let allOk = false;
       try {
-        await flushAll(this);
+        allOk = await flushAll(this);
       } catch (err) {
         this.log("error", "tenant-idle flush failed", err);
       }
-      this.idleFlushed = true;
-      this.config.onTenantIdle?.();
+      if (allOk) {
+        this.idleFlushed = true;
+        this.flushFailures = 0;
+        this.config.onTenantIdle?.();
+      } else {
+        this.idleFired = false;
+        this.flushFailures++;
+        this.log("warn", `tenant idle: flush left rooms unflushed (attempt ${this.flushFailures})`);
+      }
     })();
   }
   // -------------------------------------------------------------------------
@@ -2469,12 +3392,12 @@ var WATCHED_EXTENSIONS = [".ts", ".js", ".mts", ".mjs", ".tsx", ".jsx"];
 var LOG_LIMIT = 100;
 function resolveEntry(cwd, room) {
   if (room !== void 0) {
-    const file = path2.resolve(cwd, room);
+    const file = path.resolve(cwd, room);
     if (!existsSync(file)) throw new Error(`irtio dev: no room file at ${file}`);
     return file;
   }
   for (const candidate of ROOM_CANDIDATES) {
-    const file = path2.resolve(cwd, candidate);
+    const file = path.resolve(cwd, candidate);
     if (existsSync(file)) return file;
   }
   throw new Error(
@@ -2484,11 +3407,11 @@ function resolveEntry(cwd, room) {
   );
 }
 async function readProjectId(cwd) {
-  const file = path2.join(cwd, "irtio.json");
+  const file = path.join(cwd, "irtio.json");
   if (!existsSync(file)) return "dev";
   let parsed;
   try {
-    parsed = JSON.parse(await readFile2(file, "utf8"));
+    parsed = JSON.parse(await readFile(file, "utf8"));
   } catch (err) {
     throw new Error(`irtio dev: ${file} is not valid JSON: ${String(err)}`);
   }
@@ -2499,6 +3422,54 @@ async function readProjectId(cwd) {
   }
   return project;
 }
+async function readClientEntry(cwd) {
+  const file = path.join(cwd, "irtio.json");
+  if (!existsSync(file)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(file, "utf8"));
+  } catch (err) {
+    throw new Error(`irtio dev: ${file} is not valid JSON: ${String(err)}`);
+  }
+  const client = parsed?.client;
+  if (client === void 0) return void 0;
+  if (typeof client !== "string" || client.length === 0) {
+    throw new Error(`irtio dev: ${file} has a "client" that is not a non-empty string`);
+  }
+  return client;
+}
+async function warnIfClientImportsRoom(cwd, entry, log) {
+  const client = await readClientEntry(cwd);
+  if (client === void 0) return;
+  const clientFile = path.resolve(cwd, client);
+  if (await clientImportsRoom(clientFile, entry)) {
+    log(
+      pc.yellow(
+        `irtio: WARNING: the client entry ${client} imports the room file ${path.relative(cwd, entry)} \u2014 room code must never ship to clients; move shared code (e.g. the physics world builder) into its own module both sides import`
+      )
+    );
+  }
+}
+function rapierAbsolutePlugin(fromPackageDir) {
+  let resolved;
+  try {
+    resolved = createRequire(path.join(fromPackageDir, "package.json")).resolve(
+      "@dimforge/rapier3d-compat"
+    );
+  } catch {
+    return void 0;
+  }
+  const specifier = pathToFileURL3(resolved).href;
+  return {
+    name: "irtio-dev-rapier-absolute",
+    setup(build2) {
+      build2.onResolve({ filter: /^@dimforge\/rapier3d-compat$/ }, () => ({
+        path: specifier,
+        external: true
+      }));
+    }
+  };
+}
 async function resolveWorkerEntry2(outDir) {
   const resolver = import.meta.resolve;
   if (typeof resolver === "function") {
@@ -2509,14 +3480,15 @@ async function resolveWorkerEntry2(outDir) {
     } catch {
     }
   }
-  const packagesDir = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "../..");
-  const source = path2.join(packagesDir, "runtime/src/worker/index.ts");
+  const packagesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  const source = path.join(packagesDir, "runtime/src/worker/index.ts");
   if (!existsSync(source)) {
     throw new Error(
       "irtio dev: could not resolve @irtio/runtime/worker \u2014 is @irtio/runtime installed and built?"
     );
   }
-  const outfile = path2.join(outDir, "worker.mjs");
+  const outfile = path.join(outDir, "worker.mjs");
+  const rapierPlugin = rapierAbsolutePlugin(path.join(packagesDir, "runtime"));
   await esbuild.build({
     entryPoints: [source],
     bundle: true,
@@ -2524,11 +3496,18 @@ async function resolveWorkerEntry2(outDir) {
     platform: "node",
     outfile,
     alias: {
-      "@irtio/schema": path2.join(packagesDir, "schema/src/index.ts"),
-      "@irtio/server": path2.join(packagesDir, "server/src/index.ts"),
-      "@irtio/protocol": path2.join(packagesDir, "protocol/src/index.ts")
+      "@irtio/schema": path.join(packagesDir, "schema/src/index.ts"),
+      "@irtio/server": path.join(packagesDir, "server/src/index.ts"),
+      "@irtio/protocol": path.join(packagesDir, "protocol/src/index.ts")
     },
-    external: ["node:worker_threads", "node:url"]
+    ...rapierPlugin !== void 0 ? { plugins: [rapierPlugin] } : {},
+    // Rapier stays external for the same reason it does in packages/supervisor/test/support.ts:
+    // it is a dependency of `@irtio/runtime`, resolved once at load time. Bundling a second copy
+    // here would give the dev worker its own WASM instance, separate from the one the room
+    // bundle resolves via node_modules. `rapierPlugin` (above) already externalizes it at an
+    // absolute path when `@irtio/runtime`'s own copy can be found; this string entry is the
+    // fallback for a published install where that resolution comes for free from node_modules.
+    external: ["node:worker_threads", "node:url", "@dimforge/rapier3d-compat"]
   });
   return outfile;
 }
@@ -2572,13 +3551,14 @@ function send(res, status, type, body) {
   res.end(body);
 }
 async function startDev(options = {}) {
-  const cwd = path2.resolve(options.cwd ?? process.cwd());
+  const cwd = path.resolve(options.cwd ?? process.cwd());
   const log = options.log ?? ((line) => console.log(line));
   const entry = resolveEntry(cwd, options.room);
   const projectId = await readProjectId(cwd);
-  const outDir = path2.join(cwd, ".irtio", "dev");
+  const outDir = path.join(cwd, ".irtio", "dev");
   const port = options.port ?? DEFAULT_PORT;
-  await mkdir2(outDir, { recursive: true });
+  await mkdir(outDir, { recursive: true });
+  await warnIfClientImportsRoom(cwd, entry, log);
   const bundleOptions = {
     entry,
     outDir,
@@ -2618,13 +3598,14 @@ async function startDev(options = {}) {
     return false;
   };
   const supervisor = createSupervisor({
+    ...options.limits ? { limits: options.limits } : {},
     projectId,
     bundlePath: bundle.file,
     origins: ["*"],
     port,
     host: "127.0.0.1",
     tenantIdleMs: 0,
-    store: new DiskStore(path2.join(cwd, ".irtio", "snapshots")),
+    store: new DiskStore(path.join(cwd, ".irtio", "snapshots")),
     publicUrl: `http://localhost:${port}`,
     httpHandler,
     log: (level, ...args) => {
@@ -2650,7 +3631,7 @@ async function startDev(options = {}) {
   const watcher = options.watch === false ? void 0 : startWatch();
   let stopped = false;
   function startWatch() {
-    const dir = path2.dirname(entry);
+    const dir = path.dirname(entry);
     let timer;
     let rebuilding = Promise.resolve();
     let handle;
@@ -2659,7 +3640,7 @@ async function startDev(options = {}) {
         if (filename === null) return;
         const name = filename.toString();
         if (name.split(/[\\/]/).some((p) => p === ".irtio" || p === "node_modules")) return;
-        if (!WATCHED_EXTENSIONS.includes(path2.extname(name))) return;
+        if (!WATCHED_EXTENSIONS.includes(path.extname(name))) return;
         if (timer) clearTimeout(timer);
         timer = setTimeout(() => {
           timer = void 0;