Add live game stats endpoint to the admin bot API (#4399)

## Summary

The game simulation runs **client-side**, so the server can't directly
see what's happening in a running game. This adds a way for the admin
bot to observe a live game: clients report a live stats snapshot every
~10s, the server reaches consensus on it (reusing the winner's vote
mechanism), and a new admin-bot endpoint serves it.

## How it works

1. **`LiveStatsController`** (client) emits a snapshot every **100
turns** (~10s at 100ms/turn) — only deterministic sim values, with
players sorted by clientID, so in-sync clients produce an identical
payload.
2. The snapshot is sent as a new **`live_stats`** wire message wrapping
a `LiveStats` object (`turn` + per-human-player
`tilesOwned`/`troops`/`gold`/`isAlive`/`team`).
3. **`GameServer.handleLiveStats`** tallies a per-turn **IP-weighted
majority vote** — the same consensus the winner uses — and keeps the
latest agreed snapshot.
4. **`GET /api/adminbot/game/:id/stats`** returns it, enriched with
usernames the server already holds. `liveStats` is `null` until the
first consensus.

The winner's vote tally was extracted into a small reusable
**`VoteRound`** (`src/server/VoteTally.ts`) and is now used for both
winner and live-stats consensus.

Names are deliberately **excluded** from the voted payload (they vary
per client under name anonymization, which would break exact-match
consensus); the server joins `clientID → username` instead.

## Changes

- `src/server/VoteTally.ts` *(new)* — reusable IP-weighted `VoteRound`
- `src/core/Schemas.ts` — `PlayerLiveStatsSchema`, `LiveStatsSchema`,
`ClientSendLiveStatsSchema` + unions
- `src/client/controllers/LiveStatsController.ts` *(new)* — per-100-turn
snapshot reporter
- `src/client/Transport.ts` — `SendLiveStatsEvent` + sender
- `src/client/hud/GameRenderer.ts` — register the controller
- `src/server/GameServer.ts` — refactor winner onto `VoteRound`; add
live-stats consensus + `liveStats()` accessor
- `src/server/AdminBotRoutes.ts` — `GET …/stats` endpoint

## Testing

- **Unit:** `tests/server/VoteTally.test.ts` (majority/dedup/ties),
`tests/server/LiveStats.test.ts` (consensus, disagreement, per-client
dedup, stale-turn rejection, turn advance, out-of-sync exclusion, +
endpoint 200/404/400). Full suite green (`npm test`), typecheck + lint
clean.
- **Manual e2e** against the dev server: created an admin-bot game,
joined it in a browser, force-started via `toggle_game_start_timer`, and
confirmed `GET …/stats` returned the consensus snapshot with username
enrichment and an advancing `turn`. Also verified wrong-worker → 400 and
missing-key → 401.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/server/AdminBotCreateGame.test.ts

@@ -27,6 +27,7 @@ function captureCreateHandler() {
     post(path: string, ...handlers: ((req: any, res: any) => void)[]) {
       routes[path] = handlers[handlers.length - 1];
     },
+    get() {},
   };
   const log: any = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
   registerAdminBotRoutes({ app, gm: {} as any, workerId: 0, log });

tests/server/ClientMsgRateLimiter.test.ts

@@ -57,20 +57,20 @@ describe("ClientMsgRateLimiter", () => {
   });
 
   describe("total bytes limit", () => {
-    it("kicks when cumulative bytes reach 2MB", () => {
+    it("kicks when cumulative bytes reach 5MB", () => {
       const limiter = new ClientMsgRateLimiter();
-      const chunkSize = 512 * 1024; // 512KB
-      // Send 3 chunks = 1.5MB, should be ok
-      for (let i = 0; i < 3; i++) {
+      const chunkSize = 1024 * 1024; // 1MB
+      // Send 4 chunks = 4MB, should be ok
+      for (let i = 0; i < 4; i++) {
         expect(limiter.check(CLIENT_A, "other", chunkSize)).toBe("ok");
       }
-      // 4th chunk pushes to 2MB, should kick
+      // 5th chunk pushes to 5MB, should kick
       expect(limiter.check(CLIENT_A, "other", chunkSize)).toBe("kick");
     });
 
     it("byte tracking is per client", () => {
       const limiter = new ClientMsgRateLimiter();
-      const almostFull = 2 * 1024 * 1024 - 1;
+      const almostFull = 5 * 1024 * 1024 - 1;
       expect(limiter.check(CLIENT_A, "other", almostFull)).toBe("ok");
       // CLIENT_B should still be fine
       expect(limiter.check(CLIENT_B, "other", 100)).toBe("ok");

tests/server/LiveStats.test.ts

@@ -0,0 +1,235 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { GameType } from "../../src/core/game/Game";
+import { PlayerLiveStats } from "../../src/core/Schemas";
+import { registerAdminBotRoutes } from "../../src/server/AdminBotRoutes";
+import { GameServer } from "../../src/server/GameServer";
+import { ServerEnv } from "../../src/server/ServerEnv";
+
+describe("GameServer.handleLiveStats", () => {
+  let mockLogger: any;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockLogger = {
+      child: vi.fn().mockReturnThis(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllTimers();
+  });
+
+  function makeClient(clientID: string, ip: string, username: string) {
+    return { clientID, ip, persistentID: `pid-${clientID}`, username } as any;
+  }
+
+  // A GameServer with three distinct-IP active clients wired up.
+  function gameWithClients() {
+    const game = new GameServer("test-game", mockLogger, Date.now(), {
+      gameType: GameType.Private,
+    } as any);
+    const clients = [
+      makeClient("client01", "1.1.1.1", "Alice"),
+      makeClient("client02", "2.2.2.2", "Bob"),
+      makeClient("client03", "3.3.3.3", "Carol"),
+    ];
+    (game as any).activeClients = clients;
+    const allClients = new Map<string, unknown>();
+    const disconnected = new Map<string, boolean>();
+    for (const c of clients) {
+      allClients.set(c.clientID, c);
+      disconnected.set(c.clientID, false); // all connected
+    }
+    (game as any).allClients = allClients;
+    (game as any).clientsDisconnectedStatus = disconnected;
+    return { game, clients };
+  }
+
+  const snapshot = (tilesOwned: number): PlayerLiveStats[] => [
+    {
+      clientID: "client01",
+      tilesOwned,
+      troops: 5,
+      gold: "100",
+      isAlive: true,
+      team: null,
+    },
+  ];
+
+  const report = (
+    game: GameServer,
+    client: any,
+    turn: number,
+    players: PlayerLiveStats[],
+  ) =>
+    (game as any).handleLiveStats(client, {
+      type: "live_stats",
+      stats: { turn, players },
+    });
+
+  it("reaches consensus at a strict majority and enriches usernames", () => {
+    const { game, clients } = gameWithClients();
+    const players = snapshot(10);
+
+    report(game, clients[0], 100, players);
+    // 1 of 3 IPs -> not yet.
+    expect(game.liveStats()).toBeNull();
+
+    report(game, clients[1], 100, players);
+    // 2 of 3 IPs -> consensus.
+    expect(game.liveStats()).toEqual({
+      turn: 100,
+      players: [{ ...players[0], username: "Alice", connected: true }],
+    });
+  });
+
+  it("reports server-side connection status per player", () => {
+    const { game, clients } = gameWithClients();
+    // client01 (the only player in the snapshot) has dropped.
+    (game as any).clientsDisconnectedStatus.set("client01", true);
+    const players = snapshot(10);
+    report(game, clients[0], 100, players);
+    report(game, clients[1], 100, players);
+    expect(game.liveStats()?.players[0].connected).toBe(false);
+  });
+
+  it("does not reach consensus when clients disagree", () => {
+    const { game, clients } = gameWithClients();
+    report(game, clients[0], 100, snapshot(10));
+    report(game, clients[1], 100, snapshot(20));
+    report(game, clients[2], 100, snapshot(30));
+    expect(game.liveStats()).toBeNull();
+  });
+
+  it("ignores a second vote from the same client in a turn", () => {
+    const { game, clients } = gameWithClients();
+    report(game, clients[0], 100, snapshot(10));
+    // Same client trying to back a different snapshot is ignored, so neither
+    // candidate can reach a majority from this one client.
+    report(game, clients[0], 100, snapshot(20));
+    report(game, clients[1], 100, snapshot(20));
+    expect(game.liveStats()).toBeNull();
+  });
+
+  it("ignores stats for a turn already settled", () => {
+    const { game, clients } = gameWithClients();
+    const players = snapshot(10);
+    report(game, clients[0], 100, players);
+    report(game, clients[1], 100, players);
+    expect(game.liveStats()?.turn).toBe(100);
+
+    // Late/old turns must not overwrite the latest snapshot.
+    report(game, clients[0], 50, snapshot(99));
+    report(game, clients[1], 50, snapshot(99));
+    expect(game.liveStats()?.turn).toBe(100);
+  });
+
+  it("advances to a newer turn once it reaches consensus", () => {
+    const { game, clients } = gameWithClients();
+    report(game, clients[0], 100, snapshot(10));
+    report(game, clients[1], 100, snapshot(10));
+    expect(game.liveStats()?.turn).toBe(100);
+
+    report(game, clients[0], 200, snapshot(42));
+    report(game, clients[1], 200, snapshot(42));
+    expect(game.liveStats()).toEqual({
+      turn: 200,
+      players: [{ ...snapshot(42)[0], username: "Alice", connected: true }],
+    });
+  });
+
+  it("ignores out-of-sync clients", () => {
+    const { game, clients } = gameWithClients();
+    (game as any).outOfSyncClients = new Set(["client01"]);
+    report(game, clients[0], 100, snapshot(10));
+    report(game, clients[1], 100, snapshot(10));
+    // Only client02's vote counted (1 of 3) -> no consensus.
+    expect(game.liveStats()).toBeNull();
+  });
+});
+
+function mockRes() {
+  const res: any = {
+    statusCode: 200,
+    body: undefined,
+    status(code: number) {
+      this.statusCode = code;
+      return this;
+    },
+    json(body: unknown) {
+      this.body = body;
+      return this;
+    },
+  };
+  return res;
+}
+
+// Capture the GET handler registered for the stats route, bypassing the
+// requireAdminBotKey middleware (tested separately).
+function captureStatsHandler(gm: unknown) {
+  const routes: Record<string, (req: any, res: any) => void> = {};
+  const app: any = {
+    post() {},
+    get(path: string, ...handlers: ((req: any, res: any) => void)[]) {
+      routes[path] = handlers[handlers.length - 1];
+    },
+  };
+  const log: any = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+  registerAdminBotRoutes({ app, gm: gm as any, workerId: 0, log });
+  return routes["/api/adminbot/game/:id/stats"];
+}
+
+describe("admin bot stats endpoint", () => {
+  beforeEach(() => {
+    vi.spyOn(ServerEnv, "workerIndex").mockReturnValue(0);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns the game's live stats", () => {
+    const liveStats = {
+      turn: 100,
+      players: [
+        {
+          clientID: "client01",
+          tilesOwned: 10,
+          troops: 5,
+          gold: "100",
+          isAlive: true,
+          team: null,
+          username: "Alice",
+          connected: true,
+        },
+      ],
+    };
+    const gm = { game: () => ({ liveStats: () => liveStats }) };
+    const handler = captureStatsHandler(gm);
+    const res = mockRes();
+    handler({ params: { id: "abcdABCD" } }, res);
+    expect(res.statusCode).toBe(200);
+    expect(res.body.gameID).toBe("abcdABCD");
+    expect(res.body.liveStats).toEqual(liveStats);
+  });
+
+  it("404s when the game is not found", () => {
+    const gm = { game: () => null };
+    const handler = captureStatsHandler(gm);
+    const res = mockRes();
+    handler({ params: { id: "abcdABCD" } }, res);
+    expect(res.statusCode).toBe(404);
+  });
+
+  it("400s on an invalid game id", () => {
+    const gm = { game: () => null };
+    const handler = captureStatsHandler(gm);
+    const res = mockRes();
+    handler({ params: { id: "bad" } }, res);
+    expect(res.statusCode).toBe(400);
+  });
+});

tests/server/VoteTally.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { VoteRound } from "../../src/server/VoteTally";
+
+describe("VoteRound", () => {
+  it("returns null until a candidate has a strict majority of IPs", () => {
+    const round = new VoteRound<string>();
+    round.add("a", "a", "1.1.1.1");
+    // 1 of 3 unique IPs -> no majority yet.
+    expect(round.result(3)).toBeNull();
+    round.add("a", "a", "2.2.2.2");
+    // 2 of 3 -> majority (2 * 2 >= 3).
+    expect(round.result(3)).toEqual({ value: "a", votes: 2 });
+  });
+
+  it("counts each IP once per candidate", () => {
+    const round = new VoteRound<string>();
+    expect(round.add("a", "a", "1.1.1.1")).toBe(1);
+    expect(round.add("a", "a", "1.1.1.1")).toBe(1);
+    // Still a single IP, so no majority of a 3-IP electorate.
+    expect(round.result(3)).toBeNull();
+  });
+
+  it("tallies competing candidates independently", () => {
+    const round = new VoteRound<string>();
+    round.add("a", "a", "1.1.1.1");
+    round.add("b", "b", "2.2.2.2");
+    round.add("a", "a", "3.3.3.3");
+    // 'a' has 2 of 4 IPs (2 * 2 >= 4), 'b' has 1.
+    expect(round.result(4)).toEqual({ value: "a", votes: 2 });
+  });
+
+  it("accepts with exactly half the electorate (ties pass)", () => {
+    const round = new VoteRound<string>();
+    round.add("a", "a", "1.1.1.1");
+    expect(round.result(2)).toEqual({ value: "a", votes: 1 });
+  });
+});