typescript-server-benchmark-stuck-games

Answer

Root cause. BenchmarkRunner.launchGame called GameEngine.startGame(), which is a stub: it assigns roles to players and flips state to IN_PROGRESS, but never starts a loop (no day/night turns, no voting, no win-condition evaluation). The terminal event WINNER_DETERMINED is therefore never published and GameRun.status stays RUNNING forever — the benchmark hangs and the run can never complete. Two independent bugs compound it:

1. Wrong engine path. The engine that actually plays the game is the legacy one, exposed via LegacyGameAdapter.startGame.
2. Wrong terminal event. The legacy engine never emits WINNER_DETERMINED. Per MAF-GAP-005 it remaps the terminal STATE_CHANGE to GAME_ENDED. So even after switching engines, a listener on WINNER_DETERMINED alone would still never see completion. The fix must subscribe to both event types.

Fix 1 — BenchmarkRunner.launchGame branches to the legacy engine with a deterministic role split:

// src/benchmark/BenchmarkRunner.ts
import { EventBus } from '../events/EventBus';
import { GameEvent } from '../events/GameEvent';
import { LegacyGameAdapter } from '../legacy/LegacyGameAdapter';
import { Role, BenchmarkConfig, GameRun, GameRunStatus } from './types';

/**
 * Deterministic role split used by every benchmark launch so that runs are
 * reproducible across invocations:
 *   MAFIA / SHERIFF -> modelA (mafia side)
 *   TOWN / DOCTOR   -> modelB (town side)
 */
const ROLE_SIDE: Record<Role, 'A' | 'B'> = {
  MAFIA: 'A',
  SHERIFF: 'A',
  TOWN: 'B',
  DOCTOR: 'B',
};

export class BenchmarkRunner {
  constructor(
    private readonly legacyGameAdapter: LegacyGameAdapter,
    private readonly eventBus: EventBus,
  ) {}

  async launchGame(config: BenchmarkConfig): Promise<GameRun> {
    const run = this.createRun(config);

    // Branch to the legacy engine — the ONLY path that actually plays the game
    // to a terminal state. GameEngine.startGame() is a stub (roles only) and
    // would leave the run RUNNING forever.
    const game = await this.legacyGameAdapter.startGame({
      modelA: config.modelA,
      modelB: config.modelB,
      players: config.players.map((player, index) => ({
        id: player.id,
        role: this.assignRole(index, config.players.length),
      })),
    });

    run.bindGame(game.id);
    this.subscribeToTerminalEvents(run);
    return run;
  }

  /** Deterministic round-robin over the fixed role order: MAFIA, SHERIFF, TOWN, DOCTOR. */
  private assignRole(index: number, playerCount: number): Role {
    const ordered: Role[] = ['MAFIA', 'SHERIFF', 'TOWN', 'DOCTOR'];
    return ordered[index % ordered.length];
  }

  private sideFor(role: Role): 'A' | 'B' {
    return ROLE_SIDE[role];
  }

  /**
   * Subscribes to BOTH terminal events. The modern engine documents
   * WINNER_DETERMINED, but the legacy engine — the one actually used here —
   * never emits it: it remaps the terminal STATE_CHANGE to GAME_ENDED
   * (MAF-GAP-005). Listening to only one type would resurrect the stuck-run
   * bug. completion() is idempotent so a double fire is harmless.
   */
  private subscribeToTerminalEvents(run: GameRun): void {
    const finish = (payload: { gameId: string; winner: string }) => {
      if (payload.gameId !== run.gameId) return;
      this.completeRun(run, payload);
    };

    this.eventBus.on(GameEvent.WINNER_DETERMINED, finish);
    this.eventBus.on(GameEvent.GAME_ENDED, finish);

    // Safety net: never allow a run to hang forever.
    const timeout = setTimeout(() => finish({ gameId: run.gameId, winner: 'TIMEOUT' }), run.maxDurationMs);
    run.onTerminated(() => clearTimeout(timeout));
  }

  private completeRun(run: GameRun, payload: { gameId: string; winner: string }): void {
    if (run.status !== GameRunStatus.RUNNING) return; // idempotent
    run.status = GameRunStatus.COMPLETED;
    run.winner = payload.winner;
    run.completedAt = new Date();
    this.eventBus.off(GameEvent.WINNER_DETERMINED, ...); // detach listeners (cleanup)
    this.eventBus.off(GameEvent.GAME_ENDED, ...);
  }
}

Fix 2 — wire the already-implemented repository methods into the routes. getStatus / getProgress / listRuns / cancel already exist on the runner/store; they were simply never mounted:

// src/routes/benchmark.ts
import { Router } from 'express';
import { BenchmarkRunner } from '../benchmark/BenchmarkRunner';

export function benchmarkRouter(runner: BenchmarkRunner): Router {
  const router = Router();

  router.post('/api/v1/benchmark', async (req, res, next) => {
    try {
      const run = await runner.launchGame(req.body);
      res.status(202).json({ id: run.id, status: run.status });
    } catch (err) {
      next(err);
    }
  });

  router.get('/api/v1/benchmark/runs', (_req, res) => {
    res.json({ runs: runner.listRuns() });
  });

  router.get('/api/v1/benchmark/:id', (req, res) => {
    const run = runner.getStatus(req.params.id);
    if (!run) {
      return res.status(404).json({ error: `run ${req.params.id} not found` });
    }
    res.json({ ...run, progress: runner.getProgress(req.params.id) });
  });

  router.post('/api/v1/benchmark/:id/cancel', (req, res) => {
    const cancelled = runner.cancel(req.params.id);
    if (!cancelled) {
      return res.status(404).json({ error: 'run not found or already finished' });
    }
    res.json({ id: req.params.id, status: 'CANCELLED' });
  });

  return router;
}

cancel is the escape hatch for any run that is legitimately still playing (long games, slow models), so no client ever has to wait on a truly stuck run:

// BenchmarkRunner.cancel
cancel(runId: string): boolean {
  const run = this.runs.get(runId);
  if (!run || run.status !== GameRunStatus.RUNNING) return false;
  run.status = GameRunStatus.CANCELLED;
  this.eventBus.emit(GameEvent.GAME_CANCELLED, { gameId: run.gameId, reason: 'client_cancel' });
  return true;
}