@homie-rocks/studio 0.45.3 → 0.46.2

package/worker/index.mjs

@@ -1,3 +1,4 @@
+import { characterStore, characterRequest } from './characters.mjs';
 export { useFunctions } from './functions.mjs';
 import { appAccess, appRecordsRoute } from './app-records.mjs';
 import { appRole, openPath } from './app-format.mjs';
@@ -88,7 +89,7 @@ import { appRole, openPath } from './app-format.mjs';
  */
 import { playerEnabled, EMBED_GAME_JS } from './embed.mjs';
 import { NetRoom, WATCH_POLICIES, departure, errorLine, versionOf } from './room.mjs';
-import { hostedGame, hostedBuild, startHost } from './hosted.mjs';
+import { hostedGame, hostedBuild, compiledFor, startHost } from './hosted.mjs';
 import { roomStore, restoreDelay } from './room-store.mjs';
 import { appCors, isAppOrigin } from './standalone.mjs';
 import { ROOM_ID, badRoomPage, embedAncestors, embedPreview, frameAncestors, noWatchPage, playPage, watchPage } from './pages.mjs';
@@ -104,7 +105,8 @@ import { forgetLines, historyOf, keepLines, keptLine } from './lounge-store.mjs'
 import { isLoungePath, loungeRoutes } from './lounge.mjs';
 import { doorPage, serverPage, serversPage } from './site.mjs';
 import { isLocalOrigin, qrSvg } from './qr.mjs';
-import { acceptMultiplex, gateFor } from './gate.mjs';
+import { acceptMultiplex, diagnosticsOf, gateFor, nextGate } from './gate.mjs';
+import { worldSource } from './world-wire.mjs';
 export { Gate, Concentrator } from './gate.mjs';
 import { seatCount, paramsFrom, perAddress, seatsOf } from './seats.mjs';
 import {
@@ -122,6 +124,7 @@ import {
 // The back office knows the studio's player accounts: a signed-in player is named in the office and held by a kick on
 // every device, and the owner's own account (`homie-studio players owner`) counts as the owner.
 usePlayers(playerAccounts);
+import { STUDIO_BUILD } from './build-id.mjs';
 import { STUDIO_VERSION_TAG } from './version.mjs';
 import { reconcileOrders, readiness, roomBadge, shellShop, shopOf, shopRoutes } from './shop.mjs';
 import { DISCOVERY_FILES, discoveryResponse, llmsTxt, robotsTxt, sitemapXml } from './discover.mjs';
@@ -711,6 +714,7 @@ async function route(request, env, ctx) {
     return json({
       v: 1,
       kind: 'homie-studio',
+      toolkit: STUDIO_BUILD,
       name: cat.studio?.name ?? env.STUDIO_NAME ?? 'Studio',
       slug: cat.studio?.slug ?? null,
       ...(cat.studio?.tagline ? { tagline: cat.studio.tagline } : {}),
@@ -1024,6 +1028,7 @@ async function route(request, env, ctx) {
         srv = h && h.state === 'open' ? h : serverById('public') ?? PUBLIC_SERVER;
       }
       const d = await pageDoor(srv);
+      if (meta.room?.characters && !screen && !embed && (!d.acct || !(await chatWho(env, game, srv, d.acct)).acct)) return Response.redirect(`${url.origin}/account/?next=${encodeURIComponent(url.pathname + url.search)}`, 303);
       // The owner hid the public server: Play shows the servers to pick from, and a named room is off (owner aside).
       if (srv.id === 'public' && publicHidden() && !d.owner) {
         if (named) return doorPage(cat, meta, srv, { why: 'closed' });
@@ -1112,6 +1117,11 @@ async function route(request, env, ctx) {
       // Lobby is told it came from an app (`app=1`) and keeps only a few such builds' rooms (LOBBY_APP_VERSIONS).
       const ver = app ? versionOf(url.searchParams.get('gv')) : versionOf(meta?.netplay?.version);
       if (app && meta?.room?.host === 'server' && ver !== meta.room.build) return json({ ok: false, error: 'stale', message: 'Update the app to play online.' }, 409);
+      if (meta.room?.lifetime === 'persistent') {
+        const room = srv.id === 'public' ? 'pub-1' : `s-${srv.id}-1`;
+        if (not.split(',').includes(room)) return json({ ok: false, error: 'world-unavailable', message: 'This world is unavailable. Choose another named world.' }, 409);
+        return json({ room, players: 0, max: humanSeats(pol), server: srv.id });
+      }
       return lobby().fetch(`https://lobby/join?max=${humanSeats(pol)}&server=${srv.id}&rooms=${srv.roomsMax}${not ? `&not=${encodeURIComponent(not)}` : ''}${ver ? `&ver=${encodeURIComponent(ver)}` : ''}${app ? '&app=1' : ''}`, { method: 'POST' });
     }
     if (sub === 'api/agent') {
@@ -1318,6 +1328,12 @@ export class Table {
      * room next needs the object's one alarm (the house guides and the day's counters share it).
      */
     this.hostRt = null;
+    this.characterGrants = new Map();
+    this.accountTokens = {};
+    this.inputTransit = [];
+    this.relayed = false;
+    this.gateHeld = new Map();
+    this.gatePromised = new Map();
     this.roomAlarmAt = 0;
     this.durable = null;
     this.roomSave = null;
@@ -1345,7 +1361,21 @@ export class Table {
       maxPlayers: max,
       perIp: perAddress(max),
       store: {
-        save: (o) => { if (this.hostRt) this.saveRoom(this.hostRt.save()); else if (!hostedGame(game)) storage.put('net', o).catch(() => {}); },
+        save: (o) => {
+          if (this.hostRt && !this.relayFrame) this.saveRoom(this.hostRt.save());
+          else if (this.hostRt) {
+            // All admissions in one relay turn share a checkpoint. The microtask
+            // runs before the relay's timer flush, retaining the storage output gate.
+            if (!this.admissionSaveQueued) {
+              this.admissionSaveQueued = true;
+              const host = this.hostRt;
+              queueMicrotask(() => {
+                this.admissionSaveQueued = false;
+                if (this.hostRt === host) { try { this.saveRoom(host.save()); } catch (error) { this.storageProblem(error); } }
+              });
+            }
+          } else if (!hostedGame(game)) storage.put('net', o).catch(() => {});
+        },
         clear: () => { this.clearRoom(); },
       },
       // The room's lifecycle, one line each with its time and room (worker/room.mjs `log`): a hello, a leave, an
@@ -1353,6 +1383,7 @@ export class Table {
       // are told apart by these. HOMIE_ROOM_LOG=0 keeps only the failures.
       log: (line) => this.say(line),
     });
+    this.room.gateFacts = () => [...(this.gateMetrics?.values() ?? [])];
     if (this.saved && !hostedGame(game)) this.room.restore(this.saved);
     if (this.officeSaved) this.room.restoreOffice(this.officeSaved);
     this.vocabRead = this.readVocab(game).catch(() => false);
@@ -1366,6 +1397,7 @@ export class Table {
     this.room.decider = (state, questions, opts) => this.decide(state, questions, opts);
     // A server-hosted room that forgets everything (nobody came back, or the owner closed it) ends its host runtime.
     this.room.onForget = () => { if (this.hostRt) this.finishRoom('forgotten'); };
+    if (this.isPersistent()) this.room.forgetMs = Infinity;
     return this.room;
   }
 
@@ -1376,6 +1408,8 @@ export class Table {
    * elected. `hosted`: the Worker's word that this game's settings say `host: server`. Rules that are missing from
    * this build, or do not fit the contract, do not start: the room refuses joins and says why.
    */
+  isPersistent() { return this.persistentStored === true || hostedBuild(this.game)?.settings?.lifetime === 'persistent'; }
+
   ensureHost(room, hosted) {
     if (this.hostRt || !this.game) return;
     if (!hostedGame(this.game)) {
@@ -1386,9 +1420,11 @@ export class Table {
     let pauseWriteFailed = false;
     try {
       const build = hostedBuild(this.game);
-      try { this.durable ??= roomStore(this.ctx.storage); } catch (error) { this.storageProblem(error); }
+      const persistent = this.isPersistent();
+      try { this.durable ??= roomStore(this.ctx.storage, { persistent: this.isPersistent() }); } catch (error) { if (persistent) throw error; this.storageProblem(error); }
       let saved = this.cleanupPending ? null : this.readRoom();
       restoring = Boolean(saved);
+      if (this.persistentStored && build.settings.lifetime !== 'persistent') throw new Error('This room holds a lasting world. Keep room.lifetime persistent; its save is retained.');
       let boot = { epoch: 0, count: 0 };
       try { boot = this.durable?.boots() ?? boot; } catch (error) { if (saved) throw error; this.storageProblem(error); }
       if (!Number.isSafeInteger(boot.epoch) || boot.epoch < 0 || !Number.isInteger(boot.count) || boot.count < 0) {
@@ -1402,7 +1438,8 @@ export class Table {
       const restorePause = saved?.pauseFromRestore === true && Date.now() >= saved.pausedAt + ROOM_PAUSE_MS && this.recoveredAlarmAt !== null ? null : saved?.pausedAt;
       const restoredEnd = saved ? roomEndAt({ people: 0, pausedAt: restorePause, restoredAt: Date.now(), savedAt: saved.at, alarmAt: this.recoveredAlarmAt }) : Infinity;
       const expired = Date.now() >= restoredEnd;
-      if (saved && (saved.stateHash !== build.stateHash || boot.count >= 2 || expired)) {
+      if (saved && persistent && saved.stateHash !== build.stateHash) throw new Error('This lasting world needs its previous state schema. Restore the compatible build; the saved world has been retained.');
+      if (saved && !persistent && (saved.stateHash !== build.stateHash || boot.count >= 2 || expired)) {
         const why = saved.stateHash !== build.stateHash ? 'state-changed' : boot.count >= 2 ? 'restore loop' : 'nobody-returned';
         const tokens = new Set((saved.net.seats ?? []).map((s) => s[1]));
         this.finishRoom(why);
@@ -1412,15 +1449,16 @@ export class Table {
         this.room = room; saved = null; restoring = false; boot = { epoch: 0, count: 0 };
       }
       this.roomSave = saved;
+      this.accountTokens = saved?.accountTokens ?? {};
       if (saved) {
         // The seat map and the world came from one transaction. No unrelated net write can take a body from its token.
         room.seats.clear(); room.state.clear(); room.stateBytes = 0;
         room.restore({ ...saved.net, savedAt: Date.now(), durable: true });
-        this.pausedAt = restoredEnd - ROOM_PAUSE_MS;
+        this.pausedAt = persistent ? Date.now() : restoredEnd - ROOM_PAUSE_MS;
         this.pauseFromRestore = saved.pauseFromRestore = saved.pausedAt === null || saved.pauseFromRestore === true;
         saved.pausedAt = this.pausedAt;
         // A failed pause write must never be mistaken for an invalid host save.
-        try { this.durable.write(saved); } catch (error) { pauseWriteFailed = true; this.storageProblem(error); }
+        try { this.durable.write(saved); } catch (error) { if (persistent) throw error; pauseWriteFailed = true; this.storageProblem(error); }
       }
       const epoch = saved ? Math.max(saved.host.core.epoch, boot.epoch) + 1 : undefined;
       if (saved) this.durable.boot({ epoch, count: boot.count });
@@ -1429,7 +1467,11 @@ export class Table {
       this.hostRt = startHost(this.game, {
         ...(saved ? { restore: new TextEncoder().encode((saved.hostText ?? JSON.stringify(saved.host))), restoreEpoch: epoch, startDelayMs: boot.count === 1 ? restoreDelay(`${this.game}/${this.code}`) : 0 } : {}),
         record: (owner,key,value) => this.queueRoundRecord(owner,key,value),
-        store: { save: (bytes) => this.saveRoom(bytes) },
+        store: { save: (bytes, commitment) => this.saveRoom(bytes, commitment) },
+        ...(build.settings.characters ? { characterFor: (peer) => {
+          const account = room.clients.get(peer.id)?.player;
+          return account ? this.characterGrants.get(account) ?? null : null;
+        } } : {}),
         onTick: () => {
           if (!saved) return;
           ticks += 1;
@@ -1454,7 +1496,7 @@ export class Table {
       this.armRoom(roomEndAt({ people: 0, pausedAt: this.pausedAt, createdAt: this.hostCreatedAt }));
     } catch (error) {
       this.hostRt?.stop(); this.hostRt = null;
-      if (restoring) {
+      if (restoring && !this.isPersistent()) {
         this.storageProblem(error);
         room.forget(); this.clearRoom();
         this.skipSave = true;
@@ -1465,19 +1507,35 @@ export class Table {
     }
   }
 
-  saveRoom(bytes) {
+  saveRoom(bytes, commitment) {
+    if (this.persistentFailed) throw new Error('Lasting world stopped; restart from its committed save');
     const now = Date.now();
     if (now < (this.saveRetryAt ?? 0)) throw this.saveError ?? new Error('room save retry is waiting');
     try {
-      this.durable ??= roomStore(this.ctx.storage);
+      this.durable ??= roomStore(this.ctx.storage, { persistent: this.isPersistent() });
       const build = hostedBuild(this.game);
       const host = new TextDecoder().decode(bytes);
-      const saved = { v: 1, game: this.game, room: this.code, at: now, pauseFromRestore: this.hostRt?.paused === true && this.pauseFromRestore === true, pausedAt: this.hostRt?.paused ? this.pausedAt ?? now : null, stateHash: build.stateHash, buildHash: build.build, host, net: this.room.saved() };
+      const net = this.room.saved();
+      if (build.settings.characters) for (const client of this.room.clients.values()) {
+        if (client.player && client.seat !== null && client.token) this.accountTokens[client.player] = client.token;
+      }
+      if (build.settings.characters) {
+        const tokens = new Set((net.seats ?? []).map(seat => seat[1]));
+        for (const [account, token] of Object.entries(this.accountTokens)) if (!tokens.has(token)) delete this.accountTokens[account];
+      }
+      const saved = { ...(build.settings.characters ? { accountTokens: { ...this.accountTokens } } : {}), v: 1, game: this.game, room: this.code, at: now, pauseFromRestore: this.hostRt?.paused === true && this.pauseFromRestore === true, pausedAt: this.hostRt?.paused ? this.pausedAt ?? now : null, stateHash: build.stateHash, buildHash: build.build, host, net };
       const clearing = this.cleanupPending;
       if (clearing) this.durable.clear();
-      this.durable.write(saved);
+      if (this.isPersistent()) {
+        const c = compiledFor(this.game);
+        commitment ??= { force: false, seconds: c.settings.durability.movementSeconds, tickHz: c.settings.tickHz,
+          fields: { kinds: c.kinds.map(k => k.fields.flatMap(([,f],i) => f.durable ? [i] : [])), shared: c.shared.flatMap(([,f],i) => f.durable ? [i] : []) } };
+        this.durable.commit(saved, commitment);
+      } else this.durable.write(saved);
       if (clearing) { this.cleanupGeneration = (this.cleanupGeneration ?? 0) + 1; this.queueNetCleanup(false); }
-      this.roomSave = saved; this.cleanupPending = false; clearTimeout(this.cleanupRetry); this.cleanupRetry = null;
+      this.roomSave = saved;
+      if (build.settings.characters) this.ctx.waitUntil(this.flushCharacters().catch(error => this.storageProblem(error)));
+      this.cleanupPending = false; clearTimeout(this.cleanupRetry); this.cleanupRetry = null;
       this.saveFailures = 0; this.saveRetryAt = 0; this.saveError = null;
       clearTimeout(this.saveRetry); this.saveRetry = null;
       this.storageHealth = { ok: !this.pendingBoot };
@@ -1486,7 +1544,8 @@ export class Table {
       const delay = Math.min(60_000, 1000 * 2 ** Math.min(this.saveFailures ?? 0, 6));
       this.saveFailures = (this.saveFailures ?? 0) + 1; this.saveRetryAt = now + delay;
       this.storageProblem(error);
-      if (!this.saveRetry) {
+      if (this.isPersistent()) this.endHosted('storage-failed');
+      if (!this.isPersistent() && !this.saveRetry) {
         this.saveRetry = setTimeout(() => {
           this.saveRetry = null;
           if (this.hostRt) { try { this.saveRoom(this.hostRt.save()); } catch { /* saveRoom scheduled the next attempt */ } }
@@ -1507,7 +1566,9 @@ export class Table {
   readRoom(validateHost = false) {
     if (this.skipSave) { this.skipSave = false; return null; }
     try {
-      if (this.durable?.boots()?.retired === true) { this.clearRoom(); return null; }
+      const boot = this.durable?.boots();
+      this.persistentStored = boot?.persistent === true;
+      if (boot?.retired === true) { this.clearRoom(); return null; }
       const saved = this.durable?.read();
       if (!saved) return null;
       if (saved.v !== 1 || typeof saved.game !== 'string' || typeof saved.room !== 'string' ||
@@ -1529,10 +1590,11 @@ export class Table {
         probe.stop();
       } else if (!hostedGame(saved.game)) throw new Error('saved game is not in this build');
       return saved;
-    } catch (error) { this.storageProblem(error); this.clearRoom(); return null; }
+    } catch (error) { this.storageProblem(error); if (this.isPersistent()) throw error; this.clearRoom(); return null; }
   }
 
   clearRoom() {
+    if (this.isPersistent()) throw new Error('A lasting world cannot be cleared by match cleanup');
     this.cleanupGeneration = (this.cleanupGeneration ?? 0) + 1;
     this.roomSave = null; this.saved = null; this.pendingBoot = null;
     try { this.durable?.retire(); this.durable?.clear(); this.cleanupPending = false; clearTimeout(this.cleanupRetry); this.cleanupRetry = null; }
@@ -1581,6 +1643,7 @@ export class Table {
   }
 
   finishRoom(why) {
+    if (this.isPersistent()) { this.hostRt?.stop(); this.room?.failServerHost(`Lasting world paused: ${why}. Its committed save is retained.`); return; }
     this.hostRt?.stop(); this.hostRt = null;
     clearInterval(this.timer); this.timer = null;
     clearTimeout(this.saveRetry); this.saveRetry = null; this.saveRetryAt = 0;
@@ -1599,6 +1662,7 @@ export class Table {
 
   /** The room wants the alarm at `at` (ms): set it unless an earlier one is already waiting. */
   armRoom(at) {
+    if (this.isPersistent()) return;
     this.roomAlarmAt = at;
     this.alarmWrite = (this.alarmWrite ?? Promise.resolve()).then(async () => {
       const cur = await this.ctx.storage.getAlarm();
@@ -1620,6 +1684,14 @@ export class Table {
    * five): the room ends. Its players are told, their seats are freed, and the next visitor starts a fresh room.
    */
   endHosted(why) {
+    if (this.isPersistent()) {
+      this.persistentFailed = true;
+      // The host's own stop would checkpoint a healthy world; this one is refused by `persistentFailed`, and the committed save stands.
+      try { this.hostRt?.stop(); } catch { /* stopped all the same */ }
+      clearTimeout(this.saveRetry); this.saveRetry = null;
+      this.room?.failServerHost(`Lasting world paused: ${why}. Its committed save is retained.`);
+      return;
+    }
     const room = this.room;
     if (!room) return;
     this.finishRoom(why);
@@ -1661,6 +1733,7 @@ export class Table {
         const saved = this.cleanupPending ? null : this.readRoom(true);
         if (saved) {
           this.game = saved.game; this.code = saved.room;
+          if (this.isPersistent()) return;
           if (saved.stateHash !== hostedBuild(saved.game)?.stateHash) { this.finishRoom('state-changed'); return; }
           // No saved pause means people were present. The first cold wake starts the absence period.
           if (saved.pausedAt === null) {
@@ -1675,6 +1748,7 @@ export class Table {
       return;
     }
     if (!this.hostRt) return;
+    if (this.isPersistent()) { await this.flushCharacters(); return; }
     const endAt = roomEndAt({ people: this.hostRt.people, pausedAt: this.pausedAt, createdAt: this.hostCreatedAt });
     if (endAt === Infinity) { if (now >= this.roomAlarmAt - 1000) this.armRoom(now + ROOM_ALARM_MS); else this.armRoom(this.roomAlarmAt); return; }
     if (now < endAt) { this.armRoom(endAt); return; }
@@ -1963,9 +2037,83 @@ export class Table {
     try { await this.roomAlarm(); } catch (error) { this.say({ ev: 'failed', op: 'room-alarm', error: errorLine(error) }); }
   }
 
+  async flushCharacters() {
+    if (this.characterFlush) { await this.characterFlush; return; }
+    const saved = this.roomSave;
+    if (!saved) return;
+    const host = typeof saved.host === 'string' ? JSON.parse(saved.host) : saved.host;
+    const returns = (host.characters ?? []).filter(c => c.returning);
+    if (!returns.length) return;
+    this.characterFlush = (async () => {
+      for (const item of returns) {
+        await characterRequest(this.env, item.account, { op: 'return', game: this.game, holder: this.code, lease: item.lease, character: item.character });
+        this.hostRt?.characterReturned(item.account, item.lease);
+        if (this.characterGrants.get(item.account)?.lease === item.lease) this.characterGrants.delete(item.account);
+      }
+    })();
+    try { await this.characterFlush; } finally { this.characterFlush = null; }
+  }
+
+  // Network awaits may interleave another join or recall. Serialize each account
+  // within this room so a delayed acquisition cannot revive a returned lease.
+  async withCharacter(account, operation) {
+    this.characterOperations ??= new Map();
+    const previous = this.characterOperations.get(account) ?? Promise.resolve();
+    const current = previous.catch(() => {}).then(operation);
+    this.characterOperations.set(account, current);
+    try { return await current; }
+    finally { if (this.characterOperations.get(account) === current) this.characterOperations.delete(account); }
+  }
+
+  acquireCharacter(account) { return this.withCharacter(account, () => this.acquireCharacterOnce(account)); }
+
+  async acquireCharacterOnce(account) {
+    for (const c of [...this.room.clients.values()]) if (c.player === account && c.helloed) this.room.kick(c, 'character-moved', 4001);
+    await this.flushCharacters();
+    const body = { op: 'acquire', game: this.game, holder: this.code, schema: hostedBuild(this.game).stateHash };
+    let grant = await characterRequest(this.env, account, body);
+    if (grant.error === 'character-held') {
+      const old = this.env.TABLE.get(this.env.TABLE.idFromName(`${this.game}/${grant.holder}`));
+      const url = `https://room/__recall?game=${encodeURIComponent(this.game)}&room=${encodeURIComponent(grant.holder)}`;
+      const response = await old.fetch(url, { method: 'POST', body: JSON.stringify({ account }) });
+      if (!response.ok) throw new Error('Finishing your last session; its room is unavailable');
+      grant = await characterRequest(this.env, account, body);
+    }
+    if (!grant.ok) throw new Error(grant.error);
+    const held = { account, lease: grant.lease, seat: -1, character: grant.character };
+    this.characterGrants.set(account, held);
+    this.hostRt.reserveCharacter(held);
+    this.saveRoom(this.hostRt.save());
+  }
+
   async fetch(request) {
-    if (new URL(request.url).pathname === '/__multiplex') {
-      return acceptMultiplex(request, (req, socket) => this.connect(req, socket));
+    if (new URL(request.url).pathname === '/__character') {
+      const body = await request.json();
+      this.characters ??= characterStore(this.ctx.storage);
+      if (body.op === 'acquire') return json(this.characters.acquire(body.game, body.holder, body.schema));
+      if (body.op === 'return') return json(this.characters.return(body.game, body.holder, body.lease, body.character));
+      return json({ ok: false }, 400);
+    }
+    const path = new URL(request.url).pathname;
+    if (path === '/__gate') {
+      // The door asks which Gate takes the next player (worker/gate.mjs, nextGate): the lowest with room, counting
+      // players sent to a Gate in the last ten seconds who have not reached it yet.
+      const gates = Number(new URL(request.url).searchParams.get('gates')) || 1, now = Date.now(), promised = new Map();
+      for (const [index, due] of this.gatePromised) { const live = due.filter((at) => at > now); if (live.length) { this.gatePromised.set(index, live); promised.set(index, live.length); } else this.gatePromised.delete(index); }
+      const gate = nextGate(gates, this.gateHeld, promised);
+      if (!this.gatePromised.has(gate)) this.gatePromised.set(gate, []);
+      this.gatePromised.get(gate).push(now + 10_000);
+      return json({ gate });
+    }
+    if (path === '/__multiplex') {
+      this.relayed = true;
+      const index = Number(new URL(request.url).searchParams.get('gate'));
+      // One encoding of each world for every Gate link (worker/world-wire.mjs).
+      return acceptMultiplex(request, (req, socket) => this.connect(req, socket), { source: (this.worldSource ??= worldSource()), onCount: (n) => {
+        // A player arrived: a promise to that Gate is kept. The Gate's count is what the next join is placed by.
+        if (n > (this.gateHeld.get(index) ?? 0)) this.gatePromised.get(index)?.shift();
+        if (n > 0) this.gateHeld.set(index, n); else this.gateHeld.delete(index);
+      } });
     }
     return this.connect(request);
   }
@@ -1982,9 +2130,26 @@ export class Table {
       return json({ ok: true });
     }
     const room = this.roomFor(game, code, max);
+    if (url.pathname === '/__recall') {
+      const { account } = await request.json();
+      return this.withCharacter(account, async () => {
+        this.ensureHost(room, true);
+        if (!this.hostRt || this.persistentFailed || room.hostFailed) return json({ ok: false }, 503);
+        await this.flushCharacters();
+        if (!this.hostRt.characters.has(account)) {
+          const grant = await characterRequest(this.env, account, { op: 'acquire', game, holder: code, schema: hostedBuild(game).stateHash });
+          if (!grant.ok) return json({ ok: true });
+          this.hostRt.reserveCharacter({ account, lease: grant.lease, seat: -1, character: grant.character });
+        }
+        this.hostRt.releaseCharacter(account);
+        for (const c of [...room.clients.values()]) if (c.player === account) room.kick(c, 'character-moved', 4001);
+        await this.flushCharacters();
+        return json({ ok: true });
+      });
+    }
     // The back office (worker/office.mjs), from the studio's Worker only: the room as its owner sees it, and the
     // owner's signed controls, which this room verifies before it applies one (NETPLAY.md section 15).
-    if (url.pathname === '/__facts') return json({ ...room.officeFacts(), durability: this.storageHealth ?? { ok: true }, ...(this.house ? { brains: this.house.facts() } : {}) });
+    if (url.pathname === '/__facts') return json({ ...room.officeFacts(), gates: [...(this.gateMetrics?.values() ?? [])], durability: this.storageHealth ?? { ok: true }, ...(this.house ? { brains: this.house.facts() } : {}) });
     // A chat line as the room keeps it (section 19), for a report: the Worker files the room's own copy, never a reporter's.
     if (url.pathname === '/__chat') {
       const id = url.searchParams.get('id');
@@ -2044,6 +2209,12 @@ export class Table {
     const agent = decodeFacts(url.searchParams.get('ag'));
     // Kept chat (0.29.0): the room's history is back in its window before this page hears it.
     await this.hydrateHistory(room);
+    const account = holders(url.searchParams.get('via')).find(p => p.startsWith('p-'))?.slice(2) ?? null;
+    if (hostedBuild(game)?.settings.characters && url.pathname !== '/__watch') {
+      if (!account || url.searchParams.get('acct') !== '1') return new Response('Sign in to keep your character', { status: 401 });
+      try { await this.acquireCharacter(account); }
+      catch (error) { return new Response(String(error.message), { status: 409 }); }
+    }
     const [client, server] = transport ? [null, transport] : Object.values(new WebSocketPair());
     server.accept();
     const via = url.searchParams.get('via');
@@ -2075,7 +2246,9 @@ export class Table {
       ...(url.pathname === '/__watch' && url.searchParams.get('mod') === '1' ? { mod: true } : {}),
       send: (text) => { try { server.send(text); } catch { /* closed */ } },
       close: (c, r) => { try { server.close(c, r); } catch { /* closed */ } },
-      buffered: () => 0,
+      buffered: () => server.buffered?.() ?? 0,
+      ...(server.snapshotGroup ? { snapshotGroup: server.snapshotGroup, subscribe: seat => server.subscribe(seat) } : {}),
+      ...(server.snapshot ? { snapshot: (...args) => server.snapshot(...args), transportFacts: server.transportFacts } : {}),
     };
     if (url.pathname === '/__watch') {
       // Watching shells are cheap (outgoing is free) but not free: a room holds at most 256, and 24 from one address
@@ -2096,9 +2269,18 @@ export class Table {
       // seats, so it is not counted twice). One counter write per room.
       const fresh = room.seats.size === 0;
       server.addEventListener('message', (e) => {
-        h.onMessage(typeof e.data === 'string' ? e.data : '');
+        this.relayFrame = Boolean(server.snapshot);
+        try {
+        let text = typeof e.data === 'string' ? e.data : '';
+        if (hostedBuild(game)?.settings.characters && account) {
+          try { const message = JSON.parse(text); if (message.t === 'hello') { delete message.token; if (this.accountTokens[account]) message.token = this.accountTokens[account]; text = JSON.stringify(message); } } catch { /* normal parser diagnoses it */ }
+        }
+        if (Number.isFinite(e.receivedAt)) this.inputTransit.push(Math.max(0, Date.now() - e.receivedAt));
+        h.onMessage(text, this.relayFrame ? e.receivedAt : undefined);
+        if (hostedBuild(game)?.settings.characters && account) { const joined = room.clients.get(h.id); if (joined?.token) this.accountTokens[account] = joined.token; }
+        } finally { this.relayFrame = false; }
         // A newcomer: the Lobby hears of the room at once, so the owner's office (and a launch change) never misses it.
-        if (typeof e.data === 'string' && e.data.startsWith('{"t":"hello"')) this.report();
+        if (typeof e.data === 'string' && e.data.startsWith('{"t":"hello"')) this.scheduleReport();
         if (fresh && !this.openCounted && room.seats.size > 0) {
           this.openCounted = true;
           if (conn.qa) return;
@@ -2114,7 +2296,7 @@ export class Table {
         }
         // The room says the departure itself (its `leave` line: who, which seat, host or not, how many are left).
         h.onClose(via);
-        try { this.report(); } catch (error) { this.say({ ev: 'failed', op: 'report', error: errorLine(error) }); }
+        try { this.scheduleReport(); } catch (error) { this.say({ ev: 'failed', op: 'report', error: errorLine(error) }); }
       };
       server.addEventListener('close', () => left('close'));
       // A lost network arrives here, not as a close: said as what it is, with the client it was, then handled as the
@@ -2143,7 +2325,7 @@ export class Table {
       // A launch change the room applied by itself (after its round): its stored state says so too.
       if (room.officeDirty) { room.officeDirty = false; this.ctx.storage.put('office', room.officeSaved()).catch(() => {}); }
       n += 1;
-      if (n % 4 === 0) { room.tellWatchers(); this.report(); this.recordRound(); this.syncHouse(); }
+      if (n % 4 === 0) { this.publishDiagnostics(); room.tellWatchers(); this.report(); this.recordRound(); this.syncHouse(); }
       // Room chat's counts, once a minute (section 19).
       if (n % 240 === 0) this.ctx.waitUntil(this.flushChat().catch(() => {}));
       // A server-hosted room in play keeps its alarm ahead of it (re-armed every five minutes of play).
@@ -2178,6 +2360,40 @@ export class Table {
     this.ctx.waitUntil(lobby.fetch(`https://lobby/report?game=${encodeURIComponent(this.game)}`, { method: 'POST', body: JSON.stringify({ room: this.code, players: 0, people: 0, ...extra }) }).catch(() => {}));
   }
 
+  /**
+   * A big room's diagnostics leave it once a second for the object that answers readers (worker/gate.mjs,
+   * `diagnosticsFetch`): nothing per player, one post outstanding at most, never awaited by a tick or an admission.
+   * A room that every player reaches directly (one Gate's worth of seats) answers for itself and posts nothing.
+   */
+  publishDiagnostics() {
+    const transit = this.inputTransit.sort((a, b) => a - b); this.inputTransit = [];
+    if (!this.env.GATE || !this.relayed || this.diagnosticsPending || !this.room) return;
+    const facts = this.room.diagnosticFacts(), now = Date.now(), last = this.diagnosticsLast;
+    const at = (p) => transit.length ? transit[Math.min(transit.length - 1, Math.floor(transit.length * p))] : null;
+    const tick = facts.ticks?.tick ?? null;
+    this.diagnosticsLast = { now, tick };
+    this.diagnosticsPending = true;
+    const body = JSON.stringify({
+      ...facts,
+      // Ticks the rules ran per second of this object's clock since the last post.
+      tickRate: last && tick !== null && last.tick !== null && now > last.now ? Math.round((tick - last.tick) / (now - last.now) * 100000) / 100 : null,
+      // A Gate's stamp on a player's message to this object handling it, ms.
+      inputTransitMs: { n: transit.length, p50: at(0.5), p95: at(0.95), max: transit.at(-1) ?? null },
+      durability: this.storageHealth ?? { ok: true },
+    });
+    const work = diagnosticsOf(this.env, this.game, this.code).fetch('https://diagnostics/__diagnostics', { method: 'POST', body })
+      .then((r) => r.body?.cancel?.())
+      .catch((error) => { this.say({ ev: 'diagnostics-publish-failed', error: errorLine(error) }); })
+      .finally(() => { this.diagnosticsPending = false; });
+    this.ctx.waitUntil(work);
+  }
+
+  scheduleReport() {
+    if (this.reportQueued) return;
+    this.reportQueued = true;
+    queueMicrotask(() => { this.reportQueued = false; this.report(); });
+  }
+
   /** Tell the Lobby how many players this room has, when it changes. */
   report() {
     const room = this.room;

package/worker/office-page.mjs

@@ -722,6 +722,17 @@ export const OFFICE_SCRIPT = String.raw`(function () {
   function room(g, r, now) {
     var box = el('div', 'room');
     var key = g.id + '/' + r.room;
+    if (r.telemetry) {
+      if (r.telemetry.toolkit) box.appendChild(el('div', 'faint', 'Toolkit ' + r.telemetry.toolkit.version + ' · build ' + r.telemetry.toolkit.sha256));
+      var timing = r.telemetry.ticks && r.telemetry.ticks.timing;
+      var stages = timing && timing.ms || {};
+      box.appendChild(el('div', 'faint', 'Server telemetry · ' + Object.keys(stages).map(function(k) { return k + ' p95 ' + (stages[k] ? stages[k].p95.toFixed(2) + ' ms' : 'unavailable'); }).join(' · ') + ' · queued relay rows ' + (r.telemetry.transport || []).reduce(function(n, t) { return n + t.queueRows; }, 0)));
+      (r.telemetry.gates || []).forEach(function(g) {
+        var stages = g.view && g.view.ms || {};
+        var timing = ['view','encode','send'].map(function(k) { return k + ' p95 ' + (stages[k] ? stages[k].p95.toFixed(2) + ' ms' : 'unavailable'); }).join(' · ');
+        box.appendChild(el('div', 'faint', g.id + ' · ' + g.clients + ' clients · ' + timing + ' · queue ' + g.queueRows + ' reliable / ' + g.pendingViews + ' views · receipt ' + g.ackMs + ' ms'));
+      });
+    }
     var head = el('div', 'rhead');
     head.onclick = function (e) { if (e.target.closest('button,select')) return; S.open[key] = !S.open[key]; render(); };
     var round = r.round ? 'Round ' + (r.round.n || '?') + (r.round.phase === 'live' && r.round.endsAt ? ' · ' + clock(r.round.endsAt - now) + ' left' : r.round.phase === 'over' ? ' · results' : '') : 'no round yet';

package/worker/office.mjs

@@ -62,6 +62,7 @@ import { toolIdentity } from './tool-identity.mjs';
  * from an office key it is ALWAYS an ask (the AI may only propose one), and so is marking a referrer paid.
  */
 import { seatsOf } from './seats.mjs';
+import { diagnosticsOf, roomLayout } from './gate.mjs';
 import { PUBLIC_SERVER, SERVER_LIMITS, checkServer, levelName, narrows, policyOf, roomServer, rowFor, serverView, serversOf, serverPassCookie, writeServer } from './servers.mjs';
 import { BRAIN_BUDGET, aiName, brainFor, fillSpot, passById, passCreate, passList, passRevoke, think } from './agents.mjs';
 import { DEFAULT_MODEL, NEURONS_PER_M, OWNER_MODEL, vocabularyOf } from './brain.mjs';
@@ -424,6 +425,24 @@ async function roomFacts(env, game, room, max) {
   } catch { return null; }
 }
 
+/**
+ * One named room's diagnostics, for a measurement that polls it. A room big enough to run behind Gates is read from
+ * the object its room and Gates post to each second, so a poll neither waits behind the room's ticks nor costs them
+ * one; the answer carries its age. Only when that copy is missing or old is the room asked, and not for long. A
+ * small room answers for itself, as it always has.
+ */
+export async function roomDiagnostics(env, game, room, max) {
+  if (!env.GATE || roomLayout(max).gates === 1) return roomFacts(env, game, room, max);
+  let kept = null;
+  try {
+    const res = await diagnosticsOf(env, game, room).fetch(`https://diagnostics/__diagnostics?room=${enc(room)}`);
+    kept = res.ok ? await res.json() : null;
+  } catch { /* the room is asked below */ }
+  if (kept?.diagnostics?.ageMs != null && kept.diagnostics.ageMs < 5000) return kept;
+  const direct = await Promise.race([roomFacts(env, game, room, max), new Promise((done) => setTimeout(() => done(null), 1500))]);
+  return direct ? { ...direct, gates: kept?.gates?.length ? kept.gates : direct.gates, diagnostics: { cached: false, at: direct.st ?? null, ageMs: 0 } } : kept;
+}
+
 /** Hand one room one signed control; what the room says back. */
 async function roomControl(env, meta, settings, room, op, args) {
   const ctl = await signControl(env, { op, game: meta.id, room, args });
@@ -471,6 +490,7 @@ async function roomRow(env, meta, room, max) {
     round: f.round && typeof f.round === 'object' ? { n: f.round.n ?? null, phase: f.round.phase ?? null, startedAt: f.round.startedAt ?? null, endsAt: f.round.endsAt ?? null } : null,
     openedAt: office.openedAt ?? f.openedAt ?? null, closedUntil: office.closedUntil ?? null, snapHz: f.snapHz ?? 0,
     regate: office.regate ?? null,
+    telemetry: { source: 'server', toolkit: f.toolkit ?? null, ticks: f.ticks ?? null, transport: f.transport ?? [], gates: f.gates ?? [] },
     host: f.host ?? null, announce: f.announce ?? null,
     slots: slots.map((s) => ({ slot: s.slot, seat: s.seat ?? null, name: oneLine(s.name, 40), bot: Boolean(s.bot), ...(s.agent ? { agent: { role: s.agent.role ?? 'party', seat: s.agent.seat ?? null } } : {}) })),
     clients, bans: office.bans ?? [], mutes: office.mutes ?? [],
@@ -1213,6 +1233,13 @@ async function api(request, env, url, cat) {
     if (!body || typeof body !== 'object' || Array.isArray(body)) return json({ ok: false, error: 'json' }, 400);
   } else if (request.method !== 'GET') return json({ ok: false, error: 'method' }, 405);
 
+  if (path === '/_studio/api/room' && request.method === 'GET') {
+    const game = url.searchParams.get('game'), room = url.searchParams.get('room');
+    const meta = (cat.games ?? []).find(g => g.id === game);
+    if (!meta || !ROOM_ID.test(room ?? '')) return json({ ok: false, error: 'room' }, 400);
+    const facts = await roomDiagnostics(env, game, room, seatsFor(meta, await settingsOf(env)));
+    return json({ ok: Boolean(facts), facts });
+  }
   if (path === '/_studio/api/office' && request.method === 'GET') {
     try { return json({ ...(await officeView(env, cat, url.origin)), by: who }); } catch (error) {
       return json({ ok: false, error: 'no-office', message: `The office is not in this studio's D1 yet: \`npm run deploy\` applies migration 0005_studio_office.sql. (${String(error?.message ?? error).slice(0, 120)})` }, 503);