@myclaw163/clawclaw-cli 0.6.76 → 0.6.78

package/src/runtime/event-daemon.ts

@@ -1,519 +1,519 @@
-import { existsSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { GameClient } from '../lib/game-client.js';
-import { EventStore } from '../pipeline/event-store.js';
-import { getProfileStateDir } from '../lib/init-command.js';
-import { AuthStore } from '../lib/auth.js';
-import { RuntimeLogger } from './runtime-logger.js';
-import { isCclTestEnabled, rawWsLogPathForSession } from './raw-ws-log.js';
-import { PlayerHistoryStore } from '../perception/player-history-store.js';
-import type { WsCloseInfo } from './ws-client.js';
-
-const log = new RuntimeLogger();
-
-let feedSerial = 0;
-const MAX_RECENT_EVENTS = 50;
-
-function isTrue(value: string | undefined): boolean {
-  return typeof value === 'string' && value.trim().toLowerCase() === 'true';
-}
-
-function shouldWriteFeedFile(): boolean {
-  return isCclTestEnabled() || isTrue(process.env.CCL_DEBUG_RUNTIME);
-}
-
-function pushRecentEvent(recentEvents: Record<string, any>[], evt: Record<string, any>): void {
-  recentEvents.push(evt);
-  if (recentEvents.length > MAX_RECENT_EVENTS) recentEvents.shift();
-}
-
-function runtimeEventKey(evt: Record<string, any>): string {
-  const type = evt.type ?? '?';
-  const tick = evt.tick ?? 0;
-  const parts = [
-    evt.actor_name,
-    evt.spotted_name,
-    evt.killer_name,
-    evt.result_target,
-    evt.target_name,
-    evt.corpse_name,
-    evt.task_name,
-  ].filter(Boolean);
-  const discriminator = parts.length > 0 ? parts.join('|') : '';
-  return `${type}@${tick}#${discriminator}`;
-}
-
-function cleanObject<T extends Record<string, any>>(obj: T): T {
-  for (const key of Object.keys(obj)) {
-    if (obj[key] === undefined) delete obj[key];
-  }
-  return obj;
-}
-
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === 'number' && Number.isFinite(value);
-}
-
-function playersFromMap(mapData: any): Array<{ name: string; seat: number }> {
-  if (!mapData || typeof mapData !== 'object' || !Array.isArray(mapData.all_players)) return [];
-  const players: Array<{ name: string; seat: number }> = [];
-  for (const player of mapData.all_players) {
-    if (typeof player?.name !== 'string' || !isFiniteNumber(player.seat)) continue;
-    players.push({ name: player.name, seat: player.seat });
-  }
-  return players;
-}
-
-function seatMapFromPlayers(players: Array<{ name: string; seat: number }>): Record<string, number> {
-  const seats: Record<string, number> = {};
-  for (const player of players) seats[player.name] = player.seat;
-  return seats;
-}
-
-function isGameOverState(data: Record<string, any>): boolean {
-  return data.phase === 'game_over';
-}
-
-function isGameOverEvent(data: Record<string, any>): boolean {
-  return data.type === 'game_over';
-}
-
-function isUserLeftGameClose(info: WsCloseInfo): boolean {
-  const reason = (info.reason ?? '').trim().toLowerCase();
-  return (
-    (info.code === 1000 && reason === 'left game')
-    || (info.code === 4001 && reason.includes('already left the game'))
-  );
-}
-
-export function buildMeetingStateProjection(meeting: any): Record<string, any> {
-  return {
-    caller: meeting?.caller ?? null,
-    sub_phase: meeting?.sub_phase ?? null,
-    first_speaker: meeting?.first_speaker ?? null,
-    speech_order: Array.isArray(meeting?.speech_order) ? meeting.speech_order : undefined,
-    current_speaker: meeting?.current_speaker ?? null,
-    speech_skipped: Array.isArray(meeting?.speech_skipped) ? meeting.speech_skipped : undefined,
-    votes_submitted: Array.isArray(meeting?.votes_submitted) ? meeting.votes_submitted : undefined,
-    alive_players: Array.isArray(meeting?.alive_players) ? meeting.alive_players : undefined,
-  };
-}
-
-/** Build the in-memory owner snapshot consumed by Monitor and owner-control snapshot requests. */
-function buildFeed(
-  youName: string,
-  phase: string,
-  urgent: Record<string, any>,
-  meeting: any,
-  recentEvents: Record<string, any>[],
-  you?: Record<string, any>,
-  game?: Record<string, any>,
-  automation?: Record<string, any>,
-): any {
-  return {
-    ts: new Date().toISOString(),
-    serial: ++feedSerial,
-    phase,
-    you: { name: youName, ...(you ?? {}) },
-    game,
-    urgent,
-    meeting,
-    automation,
-    recent_events: recentEvents.slice(-10),
-  };
-}
-
-export type EventRuntimeStopReason = 'game_over' | 'user_left_game' | 'manual' | 'SIGINT' | 'SIGTERM' | 'error';
-
-export interface EventRuntimeStop {
-  reason: EventRuntimeStopReason;
-  error?: unknown;
-}
-
-export interface EventRuntimeOptions {
-  authStore?: AuthStore;
-  onStop?: (stop: EventRuntimeStop) => void;
-  getAutomation?: () => Record<string, any> | undefined;
-}
-
-export class EventRuntime {
-  private readonly store: AuthStore;
-  private readonly onStop?: (stop: EventRuntimeStop) => void;
-  private readonly getAutomation?: () => Record<string, any> | undefined;
-  private events: EventStore | null = null;
-  private playerHistory: PlayerHistoryStore | null = null;
-  private client: GameClient | null = null;
-  private reconnectPoll: ReturnType<typeof setInterval> | null = null;
-  private reconnecting = false;
-  private stopped = false;
-  private notifyStop = false;
-  private gameOverEmitted = false;
-  private recentEvents: Record<string, any>[] = [];
-  private seenEventKeys = new Set<string>();
-
-  private profileName = '';
-  private feedPath = '';
-  private currentPhase = 'lobby';
-  private currentMeeting: any = null;
-  private currentYou: Record<string, any> = {};
-  private currentGame: Record<string, any> = {};
-  private currentUrgent: Record<string, any> = {};
-  private currentTick: number | null = null;
-  private currentAllPlayers: Array<{ name: string; seat: number }> = [];
-  private currentSeatMap: Record<string, number> = {};
-  private mapCacheLoaded = false;
-  private mapCachePromise: Promise<void> | null = null;
-  private currentMeetingRound = 0;
-  private lastMeetingProjectionJson: string | null = null;
-  private lastSpeechYourTurnTick: number | null = null;
-  private prevCurrentSpeaker: string | null = null;
-  private latestFeed: any = null;
-
-  constructor(opts: EventRuntimeOptions = {}) {
-    this.store = opts.authStore ?? new AuthStore();
-    this.onStop = opts.onStop;
-    this.getAutomation = opts.getAutomation;
-  }
-
-  snapshot(): any | null {
-    return this.latestFeed;
-  }
-
-  refreshFeed(): void {
-    this.writeFeed();
-  }
-
-  async start(): Promise<void> {
-    const profile = this.store.getActive();
-    if (!profile) throw new Error('Not logged in.');
-
-    this.profileName = profile.agentName;
-    this.events = EventStore.forActiveAccount();
-    this.playerHistory = PlayerHistoryStore.forSession(this.events.path);
-    this.playerHistory.reset();
-
-    const stateDir = getProfileStateDir(profile);
-    const cclTest = isCclTestEnabled();
-    const rawWsLogPath = cclTest ? rawWsLogPathForSession(this.events.path) : undefined;
-    this.client = GameClient.fromAuth({ ws: true, authStore: this.store, rawWsLogPath });
-    this.feedPath = join(stateDir, 'feed.json');
-
-    if (existsSync(join(stateDir, 'match-state.json'))) {
-      this.currentPhase = 'matching';
-      const matchStart = { type: 'match_start', ts: new Date().toISOString() };
-      pushRecentEvent(this.recentEvents, matchStart);
-      this.events.append(matchStart);
-    }
-
-    this.writeFeed();
-    this.events.append({ type: 'event_runtime_started', pid: process.pid });
-    log.info('EVENT_RUNTIME', `started pid=${process.pid}`);
-
-    this.client.on('*', (data) => this.handleEvent(data));
-    this.client.onWsClose((info) => this.handleWsClose(info));
-
-    await this.ensureWsConnected();
-    this.reconnectPoll = setInterval(() => {
-      void this.ensureWsConnected();
-    }, 3000);
-  }
-
-  stop(reason: EventRuntimeStopReason = 'manual'): void {
-    this.finish({ reason }, false);
-  }
-
-  private finish(stop: EventRuntimeStop, notify: boolean): void {
-    if (this.stopped) return;
-    this.stopped = true;
-    this.notifyStop = notify;
-    if (this.reconnectPoll) clearInterval(this.reconnectPoll);
-    this.reconnectPoll = null;
-    this.client?.disconnectWs();
-    this.client = null;
-    try {
-      this.events?.append({ type: 'event_runtime_stopped', reason: stop.reason });
-    } catch {}
-    if (this.notifyStop) this.onStop?.(stop);
-  }
-
-  private requestStop(reason: EventRuntimeStopReason, error?: unknown): void {
-    this.finish({ reason, error }, true);
-  }
-
-  private async ensureWsConnected(): Promise<void> {
-    const client = this.client;
-    if (!client || this.stopped || this.reconnecting || client.wsConnected) return;
-    this.reconnecting = true;
-    try {
-      await client.discoverGameServer();
-      if (!client.wsConnected) {
-        await client.connectWs();
-      }
-      if (client.wsConnected) {
-        log.info('EVENT_RUNTIME', `ws connected, game_server=${client._gameServerUrl}`);
-      } else {
-        log.info('EVENT_RUNTIME', 'waiting for game server / event websocket...');
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.warn('EVENT_RUNTIME', `ws connection attempt failed: ${message}`);
-    } finally {
-      this.reconnecting = false;
-    }
-  }
-
-  private refreshPlayerHistoryMapCache(): void {
-    if (this.mapCacheLoaded || this.mapCachePromise || !this.client || !this.playerHistory) return;
-    this.mapCachePromise = this.client.getMap()
-      .then((mapData) => {
-        if (!mapData || typeof mapData !== 'object') return;
-        const players = playersFromMap(mapData);
-        if (players.length > 0) {
-          this.currentAllPlayers = players;
-          this.currentSeatMap = seatMapFromPlayers(players);
-          this.currentGame = cleanObject({
-            ...this.currentGame,
-            all_players: this.currentAllPlayers,
-            all_seats: this.currentSeatMap,
-          });
-          const myName = this.currentYou.name ?? this.profileName;
-          const mySeat = typeof myName === 'string' ? this.currentSeatMap[myName] : undefined;
-          if (mySeat !== undefined) {
-            this.currentYou = { ...this.currentYou, seat: this.currentYou.seat ?? mySeat };
-          }
-          this.writeFeed();
-        }
-        this.playerHistory?.updateMapCache(mapData);
-        if (players.length > 0) this.mapCacheLoaded = true;
-      })
-      .catch(() => {})
-      .finally(() => {
-        this.mapCachePromise = null;
-      });
-  }
-
-  private writeFeed(): void {
-    this.latestFeed = buildFeed(
-      this.profileName,
-      this.currentPhase,
-      this.currentUrgent,
-      this.currentMeeting,
-      this.recentEvents,
-      this.currentYou,
-      this.currentGame,
-      this.getAutomation?.(),
-    );
-    if (!shouldWriteFeedFile()) return;
-    try {
-      writeFileSync(
-        this.feedPath,
-        JSON.stringify(this.latestFeed, null, 2),
-      );
-    } catch {}
-  }
-
-  private appendGameOverFromState(state: any): void {
-    if (this.gameOverEmitted || !this.events) return;
-    const event = cleanObject({
-      type: 'game_over',
-      synthetic: true,
-      source: '_state',
-      tick: state.tick,
-      winner: state.winner,
-      winning_faction: state.winning_faction,
-      result: state.result,
-      reason: state.reason,
-    });
-    this.events.append(event);
-    pushRecentEvent(this.recentEvents, event);
-    this.gameOverEmitted = true;
-  }
-
-  private appendUserLeftGameFromWsClose(info: WsCloseInfo): void {
-    if (!this.events) return;
-    const event = cleanObject({
-      type: 'user_left_game',
-      synthetic: true,
-      source: 'ws_close',
-      close_code: info.code,
-      close_reason: info.reason,
-      already_left: info.code === 4001 ? true : undefined,
-      message: 'The user left the game from the web page. This match has ended; stop playing and do not restart unless the user asks.',
-      phase: this.currentPhase,
-      tick: this.currentTick ?? undefined,
-      player_name: this.currentYou.name ?? this.profileName,
-      ts: new Date().toISOString(),
-    });
-    this.events.append(event);
-    pushRecentEvent(this.recentEvents, event);
-  }
-
-  private handleWsClose(info: WsCloseInfo): void {
-    if (this.stopped || !isUserLeftGameClose(info)) return;
-    this.appendUserLeftGameFromWsClose(info);
-    this.currentPhase = 'user_left_game';
-    this.currentUrgent = { user_left_game: true };
-    this.writeFeed();
-    this.requestStop('user_left_game');
-  }
-
-  private handleState(data: Record<string, any>): void {
-    const s = data as any;
-    const stateSaysGameOver = isGameOverState(s);
-    if (isFiniteNumber(s.tick)) this.currentTick = s.tick;
-    this.currentPhase = s.phase ?? this.currentPhase;
-    this.currentYou = s.you ? { ...s.you } : this.currentYou;
-    const myName = this.currentYou.name ?? this.profileName;
-    const mySeat = typeof myName === 'string' ? this.currentSeatMap[myName] : undefined;
-    if (this.currentYou.seat === undefined && mySeat !== undefined) {
-      this.currentYou = { ...this.currentYou, seat: mySeat };
-    }
-    this.currentGame = cleanObject({
-      game_id: s.game_id,
-      alive_count: s.alive_count,
-      task_progress: s.task_progress,
-      all_players: this.currentAllPlayers.length > 0 ? this.currentAllPlayers : undefined,
-      all_seats: Object.keys(this.currentSeatMap).length > 0 ? this.currentSeatMap : undefined,
-    });
-    if (this.currentPhase !== 'lobby') this.refreshPlayerHistoryMapCache();
-
-    if (s.meeting) {
-      if (this.currentMeetingRound === 0) {
-        this.currentMeetingRound = 1;
-        this.prevCurrentSpeaker = null;
-      }
-      const meetingProjection = buildMeetingStateProjection(s.meeting);
-      const meetingProjectionJson = JSON.stringify(meetingProjection);
-      if (meetingProjectionJson !== this.lastMeetingProjectionJson) {
-        this.events?.append({
-          type: 'meeting_state',
-          synthetic: true,
-          tick: s.tick,
-          round: this.currentMeetingRound,
-          ...meetingProjection,
-        });
-        this.lastMeetingProjectionJson = meetingProjectionJson;
-      }
-      this.currentMeeting = {
-        caller: s.meeting.caller,
-        sub_phase: s.meeting.sub_phase,
-        current_speaker: s.meeting.current_speaker,
-        is_my_turn: s.meeting.current_speaker === (s.you?.name ?? this.currentYou.name),
-        alive_players: s.meeting.alive_players,
-        speech_order: s.meeting.speech_order,
-      };
-      const myName = s.you?.name ?? this.currentYou.name;
-      const newSpeaker = s.meeting.current_speaker;
-      if (
-        typeof newSpeaker === 'string' &&
-        newSpeaker === myName &&
-        newSpeaker !== this.prevCurrentSpeaker &&
-        (s.tick == null || s.tick !== this.lastSpeechYourTurnTick)
-      ) {
-        const event = {
-          type: 'speech_your_turn',
-          synthetic: true,
-          tick: s.tick,
-          actor_name: myName,
-        };
-        this.events?.append(event);
-        pushRecentEvent(this.recentEvents, event);
-        this.lastSpeechYourTurnTick = s.tick;
-      }
-      this.prevCurrentSpeaker = typeof newSpeaker === 'string' ? newSpeaker : this.prevCurrentSpeaker;
-      if (s.meeting.sub_phase === 'vote') {
-        this.currentMeeting.votes_submitted = s.meeting.votes_submitted;
-      }
-    } else if (this.currentPhase !== 'meeting') {
-      this.currentMeeting = null;
-    }
-
-    const corpses: any[] = s.corpses ?? [];
-    let corpseNearby: any = null;
-    if (corpses.length > 0 && s.you?.x != null && s.you?.y != null) {
-      let bestDist = Infinity;
-      for (const c of corpses) {
-        if (c.x == null || c.y == null) continue;
-        const d = Math.sqrt((c.x - s.you.x) ** 2 + (c.y - s.you.y) ** 2);
-        if (d < bestDist) {
-          bestDist = d;
-          corpseNearby = { name: c.name, x: c.x, y: c.y, distance: Math.round(d) };
-        }
-      }
-    }
-
-    this.currentUrgent = {
-      meeting_started: this.currentPhase === 'meeting',
-      emergency_active: false,
-      corpse_nearby: corpseNearby,
-      game_over: this.currentPhase === 'game_over',
-    };
-
-    if (stateSaysGameOver || this.currentPhase === 'game_over') {
-      this.appendGameOverFromState(s);
-    }
-    this.writeFeed();
-    if (stateSaysGameOver || this.currentPhase === 'game_over') {
-      this.requestStop('game_over');
-    }
-  }
-
-  private handleEvent(data: Record<string, any>): void {
-    if (this.stopped) return;
-    try {
-      const eventSaysGameOver = isGameOverEvent(data);
-      if (data.type === 'speech_your_turn' && data.tick != null) {
-        this.lastSpeechYourTurnTick = data.tick;
-      }
-
-      if (data.type === '_state') {
-        this.handleState(data);
-        return;
-      }
-
-      if (isFiniteNumber(data.tick)) this.currentTick = data.tick;
-      const key = runtimeEventKey(data);
-      if (this.seenEventKeys.has(key)) return;
-      this.seenEventKeys.add(key);
-
-      this.events?.append(data);
-      pushRecentEvent(this.recentEvents, data);
-      if (data.type === 'player_spotted') {
-        this.refreshPlayerHistoryMapCache();
-        this.playerHistory?.recordPlayerSpotted(data);
-      }
-      if (data.type === 'role_assigned' || data.type === 'game_started' || data.type === 'crab_teammates') {
-        this.refreshPlayerHistoryMapCache();
-      }
-
-      if (data.type === 'meeting_start' || data.type === 'meeting_started') {
-        this.currentMeetingRound += 1;
-        this.lastMeetingProjectionJson = null;
-        this.prevCurrentSpeaker = null;
-        this.currentPhase = 'meeting';
-        this.currentMeeting = { sub_phase: 'speech' };
-      } else if (data.type === 'meeting_ended' || data.type === 'meeting_result_pending') {
-        this.currentPhase = 'wandering';
-        this.currentMeeting = null;
-      } else if (eventSaysGameOver) {
-        this.currentPhase = 'game_over';
-        this.currentMeeting = null;
-        this.gameOverEmitted = true;
-      } else if (data.type === 'game_started') {
-        this.currentPhase = 'wandering';
-      }
-
-      this.currentUrgent = {
-        meeting_started: this.currentPhase === 'meeting',
-        game_over: this.currentPhase === 'game_over',
-      };
-      this.writeFeed();
-
-      if (eventSaysGameOver) {
-        this.requestStop('game_over');
-      }
-    } catch (err) {
-      this.requestStop('error', err);
-    }
-  }
-}
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { GameClient } from '../lib/game-client.js';
+import { EventStore } from '../pipeline/event-store.js';
+import { getProfileStateDir } from '../lib/init-command.js';
+import { AuthStore } from '../lib/auth.js';
+import { RuntimeLogger } from './runtime-logger.js';
+import { isCclTestEnabled, rawWsLogPathForSession } from './raw-ws-log.js';
+import { PlayerHistoryStore } from '../perception/player-history-store.js';
+import type { WsCloseInfo } from './ws-client.js';
+
+const log = new RuntimeLogger();
+
+let feedSerial = 0;
+const MAX_RECENT_EVENTS = 50;
+
+function isTrue(value: string | undefined): boolean {
+  return typeof value === 'string' && value.trim().toLowerCase() === 'true';
+}
+
+function shouldWriteFeedFile(): boolean {
+  return isCclTestEnabled() || isTrue(process.env.CCL_DEBUG_RUNTIME);
+}
+
+function pushRecentEvent(recentEvents: Record<string, any>[], evt: Record<string, any>): void {
+  recentEvents.push(evt);
+  if (recentEvents.length > MAX_RECENT_EVENTS) recentEvents.shift();
+}
+
+function runtimeEventKey(evt: Record<string, any>): string {
+  const type = evt.type ?? '?';
+  const tick = evt.tick ?? 0;
+  const parts = [
+    evt.actor_name,
+    evt.spotted_name,
+    evt.killer_name,
+    evt.result_target,
+    evt.target_name,
+    evt.corpse_name,
+    evt.task_name,
+  ].filter(Boolean);
+  const discriminator = parts.length > 0 ? parts.join('|') : '';
+  return `${type}@${tick}#${discriminator}`;
+}
+
+function cleanObject<T extends Record<string, any>>(obj: T): T {
+  for (const key of Object.keys(obj)) {
+    if (obj[key] === undefined) delete obj[key];
+  }
+  return obj;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function playersFromMap(mapData: any): Array<{ name: string; seat: number }> {
+  if (!mapData || typeof mapData !== 'object' || !Array.isArray(mapData.all_players)) return [];
+  const players: Array<{ name: string; seat: number }> = [];
+  for (const player of mapData.all_players) {
+    if (typeof player?.name !== 'string' || !isFiniteNumber(player.seat)) continue;
+    players.push({ name: player.name, seat: player.seat });
+  }
+  return players;
+}
+
+function seatMapFromPlayers(players: Array<{ name: string; seat: number }>): Record<string, number> {
+  const seats: Record<string, number> = {};
+  for (const player of players) seats[player.name] = player.seat;
+  return seats;
+}
+
+function isGameOverState(data: Record<string, any>): boolean {
+  return data.phase === 'game_over';
+}
+
+function isGameOverEvent(data: Record<string, any>): boolean {
+  return data.type === 'game_over';
+}
+
+function isUserLeftGameClose(info: WsCloseInfo): boolean {
+  const reason = (info.reason ?? '').trim().toLowerCase();
+  return (
+    (info.code === 1000 && reason === 'left game')
+    || (info.code === 4001 && reason.includes('already left the game'))
+  );
+}
+
+export function buildMeetingStateProjection(meeting: any): Record<string, any> {
+  return {
+    caller: meeting?.caller ?? null,
+    sub_phase: meeting?.sub_phase ?? null,
+    first_speaker: meeting?.first_speaker ?? null,
+    speech_order: Array.isArray(meeting?.speech_order) ? meeting.speech_order : undefined,
+    current_speaker: meeting?.current_speaker ?? null,
+    speech_skipped: Array.isArray(meeting?.speech_skipped) ? meeting.speech_skipped : undefined,
+    votes_submitted: Array.isArray(meeting?.votes_submitted) ? meeting.votes_submitted : undefined,
+    alive_players: Array.isArray(meeting?.alive_players) ? meeting.alive_players : undefined,
+  };
+}
+
+/** Build the in-memory owner snapshot consumed by Monitor and owner-control snapshot requests. */
+function buildFeed(
+  youName: string,
+  phase: string,
+  urgent: Record<string, any>,
+  meeting: any,
+  recentEvents: Record<string, any>[],
+  you?: Record<string, any>,
+  game?: Record<string, any>,
+  automation?: Record<string, any>,
+): any {
+  return {
+    ts: new Date().toISOString(),
+    serial: ++feedSerial,
+    phase,
+    you: { name: youName, ...(you ?? {}) },
+    game,
+    urgent,
+    meeting,
+    automation,
+    recent_events: recentEvents.slice(-10),
+  };
+}
+
+export type EventRuntimeStopReason = 'game_over' | 'user_left_game' | 'manual' | 'SIGINT' | 'SIGTERM' | 'error';
+
+export interface EventRuntimeStop {
+  reason: EventRuntimeStopReason;
+  error?: unknown;
+}
+
+export interface EventRuntimeOptions {
+  authStore?: AuthStore;
+  onStop?: (stop: EventRuntimeStop) => void;
+  getAutomation?: () => Record<string, any> | undefined;
+}
+
+export class EventRuntime {
+  private readonly store: AuthStore;
+  private readonly onStop?: (stop: EventRuntimeStop) => void;
+  private readonly getAutomation?: () => Record<string, any> | undefined;
+  private events: EventStore | null = null;
+  private playerHistory: PlayerHistoryStore | null = null;
+  private client: GameClient | null = null;
+  private reconnectPoll: ReturnType<typeof setInterval> | null = null;
+  private reconnecting = false;
+  private stopped = false;
+  private notifyStop = false;
+  private gameOverEmitted = false;
+  private recentEvents: Record<string, any>[] = [];
+  private seenEventKeys = new Set<string>();
+
+  private profileName = '';
+  private feedPath = '';
+  private currentPhase = 'lobby';
+  private currentMeeting: any = null;
+  private currentYou: Record<string, any> = {};
+  private currentGame: Record<string, any> = {};
+  private currentUrgent: Record<string, any> = {};
+  private currentTick: number | null = null;
+  private currentAllPlayers: Array<{ name: string; seat: number }> = [];
+  private currentSeatMap: Record<string, number> = {};
+  private mapCacheLoaded = false;
+  private mapCachePromise: Promise<void> | null = null;
+  private currentMeetingRound = 0;
+  private lastMeetingProjectionJson: string | null = null;
+  private lastSpeechYourTurnTick: number | null = null;
+  private prevCurrentSpeaker: string | null = null;
+  private latestFeed: any = null;
+
+  constructor(opts: EventRuntimeOptions = {}) {
+    this.store = opts.authStore ?? new AuthStore();
+    this.onStop = opts.onStop;
+    this.getAutomation = opts.getAutomation;
+  }
+
+  snapshot(): any | null {
+    return this.latestFeed;
+  }
+
+  refreshFeed(): void {
+    this.writeFeed();
+  }
+
+  async start(): Promise<void> {
+    const profile = this.store.getActive();
+    if (!profile) throw new Error('Not logged in.');
+
+    this.profileName = profile.agentName;
+    this.events = EventStore.forActiveAccount();
+    this.playerHistory = PlayerHistoryStore.forSession(this.events.path);
+    this.playerHistory.reset();
+
+    const stateDir = getProfileStateDir(profile);
+    const cclTest = isCclTestEnabled();
+    const rawWsLogPath = cclTest ? rawWsLogPathForSession(this.events.path) : undefined;
+    this.client = GameClient.fromAuth({ ws: true, authStore: this.store, rawWsLogPath });
+    this.feedPath = join(stateDir, 'feed.json');
+
+    if (existsSync(join(stateDir, 'match-state.json'))) {
+      this.currentPhase = 'matching';
+      const matchStart = { type: 'match_start', ts: new Date().toISOString() };
+      pushRecentEvent(this.recentEvents, matchStart);
+      this.events.append(matchStart);
+    }
+
+    this.writeFeed();
+    this.events.append({ type: 'event_runtime_started', pid: process.pid });
+    log.info('EVENT_RUNTIME', `started pid=${process.pid}`);
+
+    this.client.on('*', (data) => this.handleEvent(data));
+    this.client.onWsClose((info) => this.handleWsClose(info));
+
+    await this.ensureWsConnected();
+    this.reconnectPoll = setInterval(() => {
+      void this.ensureWsConnected();
+    }, 3000);
+  }
+
+  stop(reason: EventRuntimeStopReason = 'manual'): void {
+    this.finish({ reason }, false);
+  }
+
+  private finish(stop: EventRuntimeStop, notify: boolean): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.notifyStop = notify;
+    if (this.reconnectPoll) clearInterval(this.reconnectPoll);
+    this.reconnectPoll = null;
+    this.client?.disconnectWs();
+    this.client = null;
+    try {
+      this.events?.append({ type: 'event_runtime_stopped', reason: stop.reason });
+    } catch {}
+    if (this.notifyStop) this.onStop?.(stop);
+  }
+
+  private requestStop(reason: EventRuntimeStopReason, error?: unknown): void {
+    this.finish({ reason, error }, true);
+  }
+
+  private async ensureWsConnected(): Promise<void> {
+    const client = this.client;
+    if (!client || this.stopped || this.reconnecting || client.wsConnected) return;
+    this.reconnecting = true;
+    try {
+      await client.discoverGameServer();
+      if (!client.wsConnected) {
+        await client.connectWs();
+      }
+      if (client.wsConnected) {
+        log.info('EVENT_RUNTIME', `ws connected, game_server=${client._gameServerUrl}`);
+      } else {
+        log.info('EVENT_RUNTIME', 'waiting for game server / event websocket...');
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn('EVENT_RUNTIME', `ws connection attempt failed: ${message}`);
+    } finally {
+      this.reconnecting = false;
+    }
+  }
+
+  private refreshPlayerHistoryMapCache(): void {
+    if (this.mapCacheLoaded || this.mapCachePromise || !this.client || !this.playerHistory) return;
+    this.mapCachePromise = this.client.getMap()
+      .then((mapData) => {
+        if (!mapData || typeof mapData !== 'object') return;
+        const players = playersFromMap(mapData);
+        if (players.length > 0) {
+          this.currentAllPlayers = players;
+          this.currentSeatMap = seatMapFromPlayers(players);
+          this.currentGame = cleanObject({
+            ...this.currentGame,
+            all_players: this.currentAllPlayers,
+            all_seats: this.currentSeatMap,
+          });
+          const myName = this.currentYou.name ?? this.profileName;
+          const mySeat = typeof myName === 'string' ? this.currentSeatMap[myName] : undefined;
+          if (mySeat !== undefined) {
+            this.currentYou = { ...this.currentYou, seat: this.currentYou.seat ?? mySeat };
+          }
+          this.writeFeed();
+        }
+        this.playerHistory?.updateMapCache(mapData);
+        if (players.length > 0) this.mapCacheLoaded = true;
+      })
+      .catch(() => {})
+      .finally(() => {
+        this.mapCachePromise = null;
+      });
+  }
+
+  private writeFeed(): void {
+    this.latestFeed = buildFeed(
+      this.profileName,
+      this.currentPhase,
+      this.currentUrgent,
+      this.currentMeeting,
+      this.recentEvents,
+      this.currentYou,
+      this.currentGame,
+      this.getAutomation?.(),
+    );
+    if (!shouldWriteFeedFile()) return;
+    try {
+      writeFileSync(
+        this.feedPath,
+        JSON.stringify(this.latestFeed, null, 2),
+      );
+    } catch {}
+  }
+
+  private appendGameOverFromState(state: any): void {
+    if (this.gameOverEmitted || !this.events) return;
+    const event = cleanObject({
+      type: 'game_over',
+      synthetic: true,
+      source: '_state',
+      tick: state.tick,
+      winner: state.winner,
+      winning_faction: state.winning_faction,
+      result: state.result,
+      reason: state.reason,
+    });
+    this.events.append(event);
+    pushRecentEvent(this.recentEvents, event);
+    this.gameOverEmitted = true;
+  }
+
+  private appendUserLeftGameFromWsClose(info: WsCloseInfo): void {
+    if (!this.events) return;
+    const event = cleanObject({
+      type: 'user_left_game',
+      synthetic: true,
+      source: 'ws_close',
+      close_code: info.code,
+      close_reason: info.reason,
+      already_left: info.code === 4001 ? true : undefined,
+      message: 'The user left the game from the web page. This match has ended; stop playing and do not restart unless the user asks.',
+      phase: this.currentPhase,
+      tick: this.currentTick ?? undefined,
+      player_name: this.currentYou.name ?? this.profileName,
+      ts: new Date().toISOString(),
+    });
+    this.events.append(event);
+    pushRecentEvent(this.recentEvents, event);
+  }
+
+  private handleWsClose(info: WsCloseInfo): void {
+    if (this.stopped || !isUserLeftGameClose(info)) return;
+    this.appendUserLeftGameFromWsClose(info);
+    this.currentPhase = 'user_left_game';
+    this.currentUrgent = { user_left_game: true };
+    this.writeFeed();
+    this.requestStop('user_left_game');
+  }
+
+  private handleState(data: Record<string, any>): void {
+    const s = data as any;
+    const stateSaysGameOver = isGameOverState(s);
+    if (isFiniteNumber(s.tick)) this.currentTick = s.tick;
+    this.currentPhase = s.phase ?? this.currentPhase;
+    this.currentYou = s.you ? { ...s.you } : this.currentYou;
+    const myName = this.currentYou.name ?? this.profileName;
+    const mySeat = typeof myName === 'string' ? this.currentSeatMap[myName] : undefined;
+    if (this.currentYou.seat === undefined && mySeat !== undefined) {
+      this.currentYou = { ...this.currentYou, seat: mySeat };
+    }
+    this.currentGame = cleanObject({
+      game_id: s.game_id,
+      alive_count: s.alive_count,
+      task_progress: s.task_progress,
+      all_players: this.currentAllPlayers.length > 0 ? this.currentAllPlayers : undefined,
+      all_seats: Object.keys(this.currentSeatMap).length > 0 ? this.currentSeatMap : undefined,
+    });
+    if (this.currentPhase !== 'lobby') this.refreshPlayerHistoryMapCache();
+
+    if (s.meeting) {
+      if (this.currentMeetingRound === 0) {
+        this.currentMeetingRound = 1;
+        this.prevCurrentSpeaker = null;
+      }
+      const meetingProjection = buildMeetingStateProjection(s.meeting);
+      const meetingProjectionJson = JSON.stringify(meetingProjection);
+      if (meetingProjectionJson !== this.lastMeetingProjectionJson) {
+        this.events?.append({
+          type: 'meeting_state',
+          synthetic: true,
+          tick: s.tick,
+          round: this.currentMeetingRound,
+          ...meetingProjection,
+        });
+        this.lastMeetingProjectionJson = meetingProjectionJson;
+      }
+      this.currentMeeting = {
+        caller: s.meeting.caller,
+        sub_phase: s.meeting.sub_phase,
+        current_speaker: s.meeting.current_speaker,
+        is_my_turn: s.meeting.current_speaker === (s.you?.name ?? this.currentYou.name),
+        alive_players: s.meeting.alive_players,
+        speech_order: s.meeting.speech_order,
+      };
+      const myName = s.you?.name ?? this.currentYou.name;
+      const newSpeaker = s.meeting.current_speaker;
+      if (
+        typeof newSpeaker === 'string' &&
+        newSpeaker === myName &&
+        newSpeaker !== this.prevCurrentSpeaker &&
+        (s.tick == null || s.tick !== this.lastSpeechYourTurnTick)
+      ) {
+        const event = {
+          type: 'speech_your_turn',
+          synthetic: true,
+          tick: s.tick,
+          actor_name: myName,
+        };
+        this.events?.append(event);
+        pushRecentEvent(this.recentEvents, event);
+        this.lastSpeechYourTurnTick = s.tick;
+      }
+      this.prevCurrentSpeaker = typeof newSpeaker === 'string' ? newSpeaker : this.prevCurrentSpeaker;
+      if (s.meeting.sub_phase === 'vote') {
+        this.currentMeeting.votes_submitted = s.meeting.votes_submitted;
+      }
+    } else if (this.currentPhase !== 'meeting') {
+      this.currentMeeting = null;
+    }
+
+    const corpses: any[] = s.corpses ?? [];
+    let corpseNearby: any = null;
+    if (corpses.length > 0 && s.you?.x != null && s.you?.y != null) {
+      let bestDist = Infinity;
+      for (const c of corpses) {
+        if (c.x == null || c.y == null) continue;
+        const d = Math.sqrt((c.x - s.you.x) ** 2 + (c.y - s.you.y) ** 2);
+        if (d < bestDist) {
+          bestDist = d;
+          corpseNearby = { name: c.name, x: c.x, y: c.y, distance: Math.round(d) };
+        }
+      }
+    }
+
+    this.currentUrgent = {
+      meeting_started: this.currentPhase === 'meeting',
+      emergency_active: false,
+      corpse_nearby: corpseNearby,
+      game_over: this.currentPhase === 'game_over',
+    };
+
+    if (stateSaysGameOver || this.currentPhase === 'game_over') {
+      this.appendGameOverFromState(s);
+    }
+    this.writeFeed();
+    if (stateSaysGameOver || this.currentPhase === 'game_over') {
+      this.requestStop('game_over');
+    }
+  }
+
+  private handleEvent(data: Record<string, any>): void {
+    if (this.stopped) return;
+    try {
+      const eventSaysGameOver = isGameOverEvent(data);
+      if (data.type === 'speech_your_turn' && data.tick != null) {
+        this.lastSpeechYourTurnTick = data.tick;
+      }
+
+      if (data.type === '_state') {
+        this.handleState(data);
+        return;
+      }
+
+      if (isFiniteNumber(data.tick)) this.currentTick = data.tick;
+      const key = runtimeEventKey(data);
+      if (this.seenEventKeys.has(key)) return;
+      this.seenEventKeys.add(key);
+
+      this.events?.append(data);
+      pushRecentEvent(this.recentEvents, data);
+      if (data.type === 'player_spotted') {
+        this.refreshPlayerHistoryMapCache();
+        this.playerHistory?.recordPlayerSpotted(data);
+      }
+      if (data.type === 'role_assigned' || data.type === 'game_started' || data.type === 'crab_teammates') {
+        this.refreshPlayerHistoryMapCache();
+      }
+
+      if (data.type === 'meeting_start' || data.type === 'meeting_started') {
+        this.currentMeetingRound += 1;
+        this.lastMeetingProjectionJson = null;
+        this.prevCurrentSpeaker = null;
+        this.currentPhase = 'meeting';
+        this.currentMeeting = { sub_phase: 'speech' };
+      } else if (data.type === 'meeting_ended' || data.type === 'meeting_result_pending') {
+        this.currentPhase = 'wandering';
+        this.currentMeeting = null;
+      } else if (eventSaysGameOver) {
+        this.currentPhase = 'game_over';
+        this.currentMeeting = null;
+        this.gameOverEmitted = true;
+      } else if (data.type === 'game_started') {
+        this.currentPhase = 'wandering';
+      }
+
+      this.currentUrgent = {
+        meeting_started: this.currentPhase === 'meeting',
+        game_over: this.currentPhase === 'game_over',
+      };
+      this.writeFeed();
+
+      if (eventSaysGameOver) {
+        this.requestStop('game_over');
+      }
+    } catch (err) {
+      this.requestStop('error', err);
+    }
+  }
+}