@myclaw163/clawclaw-cli 0.6.66 → 0.6.68

package/src/commands/history.ts

@@ -1,573 +1,573 @@
-import { Command } from 'commander';
-import { EventStore } from '../pipeline/event-store.js';
-import {
-  PlayerHistoryStore,
-  type FramePlayer,
-  type LobsterTaskPoint,
-  type PlayerHistoryData,
-  type VisibleFrame,
-} from '../perception/player-history-store.js';
-
-type HistoryKind = 'stay' | 'last_appear' | 'rooms_seen';
-
-const KINDS = new Set<HistoryKind>(['stay', 'last_appear', 'rooms_seen']);
-const STOP_MIN_SECS = 2;
-const TASK_DONE_RADIUS = 15;
-const DIR_MIN_MOVE = 6;
-
-interface PlayerPoint {
-  frame: VisibleFrame;
-  pos: FramePlayer;
-}
-
-function round1(value: number): number {
-  return Math.round(value * 10) / 10;
-}
-
-function dist(a: { x: number; y: number }, b: { x: number; y: number }): number {
-  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
-}
-
-function ageSecs(time: string, now: number): number {
-  const ms = Date.parse(time);
-  if (!Number.isFinite(ms)) return 0;
-  return Math.max(0, round1((now - ms) / 1000));
-}
-
-function durationSecs(start: string, end: string): number {
-  const startMs = Date.parse(start);
-  const endMs = Date.parse(end);
-  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return 0;
-  return Math.max(0, round1((endMs - startMs) / 1000));
-}
-
-function splitSelectors(values: string[]): string[] {
-  return values
-    .flatMap((value) => String(value).split(','))
-    .map((value) => value.trim())
-    .filter(Boolean);
-}
-
-function knownPlayerNames(data: PlayerHistoryData): string[] {
-  const names = new Set<string>(Object.keys(data.seats ?? {}));
-  for (const frame of data.visible_frames ?? []) {
-    for (const name of Object.keys(frame.players ?? {})) names.add(name);
-  }
-  return Array.from(names).sort((a, b) => a.localeCompare(b));
-}
-
-function resolvePlayers(data: PlayerHistoryData, selectors: string[]): { players?: string[]; error?: Record<string, any> } {
-  const names = knownPlayerNames(data);
-  if (selectors.length === 0) {
-    return { error: { code: 'missing_player_id', message: 'Provide a player id/name, list, or all.' } };
-  }
-  if (selectors.some((selector) => selector.toLowerCase() === 'all')) return { players: names };
-
-  const resolved: string[] = [];
-  for (const selector of selectors) {
-    const seatMatch = selector.match(/^seat:(\d+)$/i);
-    const seat = seatMatch ? Number(seatMatch[1]) : /^\d+$/.test(selector) ? Number(selector) : null;
-    let matches: string[] = [];
-    if (seat != null) {
-      matches = names.filter((name) => data.seats?.[name] === seat);
-    } else {
-      matches = names.filter((name) => name === selector);
-      if (matches.length === 0) matches = names.filter((name) => name.startsWith(selector));
-      if (matches.length === 0) matches = names.filter((name) => name.toLowerCase().includes(selector.toLowerCase()));
-    }
-    if (matches.length === 0) {
-      return { error: { code: 'not_found', selector, known_players: names } };
-    }
-    if (matches.length > 1) {
-      return { error: { code: 'ambiguous', selector, candidates: matches } };
-    }
-    if (!resolved.includes(matches[0])) resolved.push(matches[0]);
-  }
-  return { players: resolved };
-}
-
-function pointsForPlayer(frames: VisibleFrame[], player: string): PlayerPoint[] {
-  const points: PlayerPoint[] = [];
-  for (const frame of frames) {
-    const pos = frame.players?.[player];
-    if (pos) points.push({ frame, pos });
-  }
-  return points;
-}
-
-function continuousRuns(points: PlayerPoint[]): PlayerPoint[][] {
-  const runs: PlayerPoint[][] = [];
-  let current: PlayerPoint[] = [];
-  for (const point of points) {
-    const prev = current[current.length - 1];
-    if (!prev || point.frame.tick === prev.frame.tick + 1) {
-      current.push(point);
-    } else {
-      if (current.length > 0) runs.push(current);
-      current = [point];
-    }
-  }
-  if (current.length > 0) runs.push(current);
-  return runs;
-}
-
-function centroid(points: PlayerPoint[]): { x: number; y: number } {
-  const sum = points.reduce((acc, point) => ({ x: acc.x + point.pos.x, y: acc.y + point.pos.y }), { x: 0, y: 0 });
-  return { x: sum.x / points.length, y: sum.y / points.length };
-}
-
-function mostCommonRoom(points: PlayerPoint[]): string | undefined {
-  const counts = new Map<string, number>();
-  for (const point of points) {
-    if (!point.pos.room) continue;
-    counts.set(point.pos.room, (counts.get(point.pos.room) ?? 0) + 1);
-  }
-  return Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
-}
-
-function nearTask(tasks: LobsterTaskPoint[], point: { x: number; y: number }): string | null {
-  let best: { task: LobsterTaskPoint; distance: number } | null = null;
-  for (const task of tasks) {
-    const distance = dist(point, task);
-    if (distance > TASK_DONE_RADIUS) continue;
-    if (!best || distance < best.distance) best = { task, distance };
-  }
-  return best?.task.name ?? null;
-}
-
-function stayKey(data: PlayerHistoryData, point: PlayerPoint): string {
-  const task = nearTask(data.lobster_tasks, point.pos);
-  if (task) return `task:${task}`;
-  return `pos:${point.pos.x},${point.pos.y}`;
-}
-
-function buildStayResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
-  const stays: Record<string, any>[] = [];
-  for (const run of continuousRuns(pointsForPlayer(data.visible_frames, player))) {
-    let segment: PlayerPoint[] = [];
-    let segmentKey: string | null = null;
-    for (const point of run) {
-      const key = stayKey(data, point);
-      if (segment.length === 0 || key === segmentKey) {
-        segment.push(point);
-        segmentKey = key;
-      } else {
-        appendStay(stays, segment, data.lobster_tasks, now);
-        segment = [point];
-        segmentKey = key;
-      }
-    }
-    appendStay(stays, segment, data.lobster_tasks, now);
-  }
-  stays.sort((a, b) => a.to_ago - b.to_ago);
-  return {
-    player,
-    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
-    stays,
-  };
-}
-
-function appendStay(out: Record<string, any>[], segment: PlayerPoint[], tasks: LobsterTaskPoint[], now: number): void {
-  if (segment.length < 2) return;
-  const first = segment[0];
-  const last = segment[segment.length - 1];
-  const secs = durationSecs(first.frame.time, last.frame.time);
-  if (secs < STOP_MIN_SECS) return;
-  const center = centroid(segment);
-  const room = mostCommonRoom(segment);
-  out.push({
-    from_ago: ageSecs(first.frame.time, now),
-    to_ago: ageSecs(last.frame.time, now),
-    secs,
-    room,
-    x: round1(center.x),
-    y: round1(center.y),
-    pos: `${round1(center.x)},${round1(center.y)}`,
-    near_task: nearTask(tasks, center),
-  });
-}
-
-function direction(from: { x: number; y: number }, to: { x: number; y: number }): string {
-  const dx = to.x - from.x;
-  const dy = to.y - from.y;
-  if (Math.sqrt(dx ** 2 + dy ** 2) < DIR_MIN_MOVE) return 'stay';
-  const horizontal = Math.abs(dx) >= DIR_MIN_MOVE / 2 ? (dx > 0 ? '右' : '左') : '';
-  const vertical = Math.abs(dy) >= DIR_MIN_MOVE / 2 ? (dy > 0 ? '下' : '上') : '';
-  return `${horizontal}${vertical}` || 'stay';
-}
-
-function buildLastAppearResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
-  const runs = continuousRuns(pointsForPlayer(data.visible_frames, player));
-  const latestFrame = data.visible_frames[data.visible_frames.length - 1];
-  const lastRun = runs[runs.length - 1] ?? [];
-  const last = lastRun[lastRun.length - 1];
-  if (!last) {
-    return {
-      player,
-      ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
-      visible: false,
-      ago: null,
-    };
-  }
-
-  const previous = lastRun.length >= 2 ? lastRun[lastRun.length - 2] : last;
-  return {
-    player,
-    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
-    visible: latestFrame?.players?.[player] != null,
-    ago: ageSecs(last.frame.time, now),
-    room: last.pos.room,
-    x: round1(last.pos.x),
-    y: round1(last.pos.y),
-    dir: direction(previous.pos, last.pos),
-  };
-}
-
-function buildRoomsSeenResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
-  const rooms: Record<string, any>[] = [];
-  for (const run of continuousRuns(pointsForPlayer(data.visible_frames, player))) {
-    let currentRoom = run[0]?.pos.room ?? 'unknown';
-    let start = run[0];
-    let previous = run[0];
-    for (const point of run.slice(1)) {
-      const room = point.pos.room ?? 'unknown';
-      if (room !== currentRoom) {
-        rooms.push(roomSegment(currentRoom, start, previous, now));
-        currentRoom = room;
-        start = point;
-      }
-      previous = point;
-    }
-    if (start && previous) rooms.push(roomSegment(currentRoom, start, previous, now));
-  }
-  rooms.sort((a, b) => a.to_ago - b.to_ago);
-  return {
-    player,
-    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
-    rooms,
-  };
-}
-
-function roomSegment(room: string, start: PlayerPoint, end: PlayerPoint, now: number): Record<string, any> {
-  return {
-    room,
-    from_ago: ageSecs(start.frame.time, now),
-    to_ago: ageSecs(end.frame.time, now),
-    secs: durationSecs(start.frame.time, end.frame.time),
-  };
-}
-
-interface MeetingRecord {
-  round: number;
-  start?: Record<string, any>;
-  briefing?: Record<string, any>;
-  states: Record<string, any>[];
-  speechEvents: Record<string, any>[];
-  voteEvents: Record<string, any>[];
-  resultEvent?: Record<string, any>;
-  ended?: Record<string, any>;
-  interrupted?: boolean;
-}
-
-interface DeathInfo {
-  type: 'found_in_meeting' | 'exiled';
-  round: number;
-}
-
-function buildMeetingRecords(events: Record<string, any>[]): MeetingRecord[] {
-  const meetings: MeetingRecord[] = [];
-  let current: MeetingRecord | null = null;
-
-  const finishCurrent = (interrupted = false) => {
-    if (!current) return;
-    current.interrupted = current.interrupted || interrupted;
-    meetings.push(current);
-    current = null;
-  };
-
-  for (const event of events) {
-    if (event.type === 'meeting_start') {
-      finishCurrent(true);
-      current = {
-        round: meetings.length + 1,
-        start: event,
-        states: [],
-        speechEvents: [],
-        voteEvents: [],
-      };
-      continue;
-    }
-    if (!current) continue;
-
-    if (event.type === 'meeting_briefing') current.briefing = event;
-    if (event.type === 'meeting_state' && (event.round == null || event.round === current.round)) current.states.push(event);
-    if (event.type === 'speech' || event.type === 'speech_skipped' || event.type === 'speech_turn') current.speechEvents.push(event);
-    if (event.type === 'vote_cast') current.voteEvents.push(event);
-    if (event.type === 'exile' || event.type === 'no_exile') current.resultEvent = event;
-    if (event.type === 'meeting_ended') {
-      current.ended = event;
-      finishCurrent(false);
-      continue;
-    }
-    if (event.type === 'game_over') {
-      finishCurrent(true);
-    }
-  }
-  finishCurrent(false);
-  return meetings;
-}
-
-function latestMeetingState(record: MeetingRecord): Record<string, any> | undefined {
-  return record.states[record.states.length - 1];
-}
-
-function meetingVotes(record: MeetingRecord): Record<string, string> {
-  const resultVotes = record.resultEvent?.votes;
-  if (resultVotes && typeof resultVotes === 'object' && !Array.isArray(resultVotes)) {
-    return resultVotes as Record<string, string>;
-  }
-  const votes: Record<string, string> = {};
-  for (const vote of record.voteEvents) {
-    if (typeof vote.actor_name === 'string' && typeof vote.target === 'string') votes[vote.actor_name] = vote.target;
-  }
-  return votes;
-}
-
-function exiledPlayer(record: MeetingRecord): string | null {
-  if (record.ended?.result === 'exiled' && typeof record.ended.result_target === 'string') return record.ended.result_target;
-  if (record.resultEvent?.type === 'exile' && typeof record.resultEvent.actor_name === 'string') return record.resultEvent.actor_name;
-  return null;
-}
-
-function meetingState(record: MeetingRecord): string {
-  if (record.ended) return 'ended';
-  const subPhase = latestMeetingState(record)?.sub_phase;
-  if (typeof subPhase === 'string' && subPhase.length > 0) return subPhase;
-  if (record.interrupted) return 'interrupted_or_missing_end';
-  return 'interrupted_or_missing_end';
-}
-
-function meetingAllSeats(record: MeetingRecord): Array<{ name: string; seat: number }> {
-  const allSeats = record.briefing?.all_seats;
-  if (!Array.isArray(allSeats)) return [];
-  return allSeats
-    .filter((player: any) => typeof player?.name === 'string' && Number.isFinite(player.seat))
-    .map((player: any) => ({ name: player.name, seat: player.seat }))
-    .sort((a, b) => a.seat - b.seat);
-}
-
-function latestAlivePlayers(record: MeetingRecord): Set<string> | null {
-  for (let i = record.states.length - 1; i >= 0; i--) {
-    const alive = record.states[i].alive_players;
-    if (Array.isArray(alive)) return new Set(alive.filter((name: any) => typeof name === 'string'));
-  }
-  return null;
-}
-
-function collectSpeechOrder(record: MeetingRecord): string[] {
-  for (const state of record.states) {
-    if (Array.isArray(state.speech_order)) {
-      return state.speech_order.filter((name: any) => typeof name === 'string');
-    }
-  }
-  const order: string[] = [];
-  for (const event of record.speechEvents) {
-    const speaker = event.actor_name;
-    if (typeof speaker === 'string' && !order.includes(speaker)) order.push(speaker);
-  }
-  return order;
-}
-
-function meetingSpeeches(record: MeetingRecord): Array<{ speaker: string; text: string; skipped: boolean }> {
-  const order = collectSpeechOrder(record);
-  const texts = new Map<string, string>();
-  const skipped = new Set<string>();
-  const seen = new Set<string>();
-
-  for (const state of record.states) {
-    const stateSpeeches = state.speeches;
-    if (stateSpeeches && typeof stateSpeeches === 'object' && !Array.isArray(stateSpeeches)) {
-      for (const [speaker, text] of Object.entries(stateSpeeches)) {
-        if (typeof speaker !== 'string') continue;
-        texts.set(speaker, typeof text === 'string' ? text : '');
-        seen.add(speaker);
-      }
-    }
-    if (Array.isArray(state.speech_skipped)) {
-      for (const speaker of state.speech_skipped) {
-        if (typeof speaker !== 'string') continue;
-        skipped.add(speaker);
-        seen.add(speaker);
-      }
-    }
-  }
-
-  for (const event of record.speechEvents) {
-    const speaker = event.actor_name;
-    if (typeof speaker !== 'string') continue;
-    if (event.type === 'speech') {
-      texts.set(speaker, typeof event.text === 'string' ? event.text : '');
-      seen.add(speaker);
-    } else if (event.type === 'speech_skipped') {
-      skipped.add(speaker);
-      seen.add(speaker);
-    }
-  }
-
-  const outputOrder = [...order, ...Array.from(seen).filter((speaker) => !order.includes(speaker))];
-  return outputOrder
-    .filter((speaker) => seen.has(speaker))
-    .map((speaker) => ({
-      speaker,
-      text: texts.get(speaker) ?? '',
-      skipped: skipped.has(speaker),
-    }));
-}
-
-function applyMeetingDeaths(record: MeetingRecord, deaths: Map<string, DeathInfo>): void {
-  const alive = latestAlivePlayers(record);
-  if (alive) {
-    for (const player of meetingAllSeats(record)) {
-      if (!alive.has(player.name) && !deaths.has(player.name)) {
-        deaths.set(player.name, { type: 'found_in_meeting', round: record.round });
-      }
-    }
-  }
-  const exiled = exiledPlayer(record);
-  if (exiled) deaths.set(exiled, { type: 'exiled', round: record.round });
-}
-
-function meetingPlayers(record: MeetingRecord, deaths: Map<string, DeathInfo>): Record<string, any>[] {
-  return meetingAllSeats(record).map((player) => {
-    const death = deaths.get(player.name) ?? null;
-    return {
-      name: player.name,
-      seat: player.seat,
-      status: death ? 'dead' : 'alive',
-      death,
-    };
-  });
-}
-
-function meetingOutput(record: MeetingRecord, deaths: Map<string, DeathInfo>): Record<string, any> {
-  applyMeetingDeaths(record, deaths);
-  return {
-    round: record.round,
-    tick: record.start?.tick ?? record.briefing?.tick ?? null,
-    caller: record.start?.actor_name ?? record.briefing?.caller ?? latestMeetingState(record)?.caller ?? null,
-    corpses_found: null,
-    state: meetingState(record),
-    exiled_player: exiledPlayer(record),
-    players: meetingPlayers(record, deaths),
-    votes: meetingVotes(record),
-    speeches: meetingSpeeches(record),
-  };
-}
-
-function allMeetingOutputs(records: MeetingRecord[]): Record<string, any>[] {
-  const deaths = new Map<string, DeathInfo>();
-  return records.map((record) => meetingOutput(record, deaths));
-}
-
-function createMeetingsCommand(): Command {
-  return new Command('meetings')
-    .description('Show meeting history')
-    .argument('[round]', 'Meeting round number, starting from 1')
-    .action((roundText?: string) => {
-      const records = buildMeetingRecords(EventStore.forLatestGame().all());
-      const outputs = allMeetingOutputs(records);
-      if (roundText != null) {
-        const round = Number(roundText);
-        const record = Number.isInteger(round) && round > 0 ? outputs.find((meeting) => meeting.round === round) : null;
-        if (!record) {
-          console.log(JSON.stringify({
-            error: {
-              code: 'meeting_round_not_found',
-              round: roundText,
-              available_rounds: outputs.map((meeting) => meeting.round),
-            },
-          }, null, 2));
-          return;
-        }
-        console.log(JSON.stringify(record, null, 2));
-        return;
-      }
-      console.log(JSON.stringify({ meetings: outputs }, null, 2));
-    });
-}
-
-function createPlayerHistorySubcommand(): Command {
-  return new Command('player')
-    .description('Show derived visible-player history')
-    .argument('<kind>', 'stay | last_appear | rooms_seen')
-    .argument('[player_id...]', 'Player name/seat/list, or all')
-    .action(async (kind: string, playerArgs: string[]) => {
-      if (!KINDS.has(kind as HistoryKind)) {
-        console.log(JSON.stringify({ error: { code: 'invalid_kind', allowed: Array.from(KINDS) } }, null, 2));
-        return;
-      }
-
-      const sessionPath = EventStore.latestSessionPath();
-      if (!sessionPath) {
-        console.log(JSON.stringify({
-          kind,
-          error: { code: 'no_game_events', message: 'No game events found. Join a game first.' },
-        }, null, 2));
-        return;
-      }
-      const data = PlayerHistoryStore.forSession(sessionPath).read();
-      if (!data || !Array.isArray(data.visible_frames) || data.visible_frames.length === 0) {
-        console.log(JSON.stringify({
-          kind,
-          error: {
-            code: 'no_player_history',
-            message: 'No player_spotted history yet. Join a game and wait for the game runtime to receive player_spotted events.',
-          },
-        }, null, 2));
-        return;
-      }
-
-      const selectors = splitSelectors(playerArgs);
-      const resolved = resolvePlayers(data, selectors);
-      if (resolved.error) {
-        console.log(JSON.stringify({ kind, error: resolved.error }, null, 2));
-        return;
-      }
-
-      const now = Date.now();
-      const players = resolved.players ?? [];
-      const resultPlayers = players.map((player) => {
-        if (kind === 'stay') return buildStayResult(data, player, now);
-        if (kind === 'last_appear') return buildLastAppearResult(data, player, now);
-        return buildRoomsSeenResult(data, player, now);
-      });
-
-      console.log(JSON.stringify({
-        kind,
-        time: new Date(now).toISOString(),
-        players: resultPlayers,
-      }, null, 2));
-    });
-}
-
-export function createHistoryCommand(): Command {
-  const history = new Command('history')
-    .description('Show derived player and meeting history');
-  history.addCommand(createPlayerHistorySubcommand());
-  history.addCommand(createMeetingsCommand());
-  return history;
-}
-
-export const playerHistoryCommandInternals = {
-  direction,
-  resolvePlayers,
-  buildStayResult,
-  buildLastAppearResult,
-  buildRoomsSeenResult,
-};
-
-export const meetingHistoryCommandInternals = {
-  buildMeetingRecords,
-  allMeetingOutputs,
-  meetingSpeeches,
-};
+import { Command } from 'commander';
+import { EventStore } from '../pipeline/event-store.js';
+import {
+  PlayerHistoryStore,
+  type FramePlayer,
+  type LobsterTaskPoint,
+  type PlayerHistoryData,
+  type VisibleFrame,
+} from '../perception/player-history-store.js';
+
+type HistoryKind = 'stay' | 'last_appear' | 'rooms_seen';
+
+const KINDS = new Set<HistoryKind>(['stay', 'last_appear', 'rooms_seen']);
+const STOP_MIN_SECS = 2;
+const TASK_DONE_RADIUS = 15;
+const DIR_MIN_MOVE = 6;
+
+interface PlayerPoint {
+  frame: VisibleFrame;
+  pos: FramePlayer;
+}
+
+function round1(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+function dist(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
+}
+
+function ageSecs(time: string, now: number): number {
+  const ms = Date.parse(time);
+  if (!Number.isFinite(ms)) return 0;
+  return Math.max(0, round1((now - ms) / 1000));
+}
+
+function durationSecs(start: string, end: string): number {
+  const startMs = Date.parse(start);
+  const endMs = Date.parse(end);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return 0;
+  return Math.max(0, round1((endMs - startMs) / 1000));
+}
+
+function splitSelectors(values: string[]): string[] {
+  return values
+    .flatMap((value) => String(value).split(','))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function knownPlayerNames(data: PlayerHistoryData): string[] {
+  const names = new Set<string>(Object.keys(data.seats ?? {}));
+  for (const frame of data.visible_frames ?? []) {
+    for (const name of Object.keys(frame.players ?? {})) names.add(name);
+  }
+  return Array.from(names).sort((a, b) => a.localeCompare(b));
+}
+
+function resolvePlayers(data: PlayerHistoryData, selectors: string[]): { players?: string[]; error?: Record<string, any> } {
+  const names = knownPlayerNames(data);
+  if (selectors.length === 0) {
+    return { error: { code: 'missing_player_id', message: 'Provide a player id/name, list, or all.' } };
+  }
+  if (selectors.some((selector) => selector.toLowerCase() === 'all')) return { players: names };
+
+  const resolved: string[] = [];
+  for (const selector of selectors) {
+    const seatMatch = selector.match(/^seat:(\d+)$/i);
+    const seat = seatMatch ? Number(seatMatch[1]) : /^\d+$/.test(selector) ? Number(selector) : null;
+    let matches: string[] = [];
+    if (seat != null) {
+      matches = names.filter((name) => data.seats?.[name] === seat);
+    } else {
+      matches = names.filter((name) => name === selector);
+      if (matches.length === 0) matches = names.filter((name) => name.startsWith(selector));
+      if (matches.length === 0) matches = names.filter((name) => name.toLowerCase().includes(selector.toLowerCase()));
+    }
+    if (matches.length === 0) {
+      return { error: { code: 'not_found', selector, known_players: names } };
+    }
+    if (matches.length > 1) {
+      return { error: { code: 'ambiguous', selector, candidates: matches } };
+    }
+    if (!resolved.includes(matches[0])) resolved.push(matches[0]);
+  }
+  return { players: resolved };
+}
+
+function pointsForPlayer(frames: VisibleFrame[], player: string): PlayerPoint[] {
+  const points: PlayerPoint[] = [];
+  for (const frame of frames) {
+    const pos = frame.players?.[player];
+    if (pos) points.push({ frame, pos });
+  }
+  return points;
+}
+
+function continuousRuns(points: PlayerPoint[]): PlayerPoint[][] {
+  const runs: PlayerPoint[][] = [];
+  let current: PlayerPoint[] = [];
+  for (const point of points) {
+    const prev = current[current.length - 1];
+    if (!prev || point.frame.tick === prev.frame.tick + 1) {
+      current.push(point);
+    } else {
+      if (current.length > 0) runs.push(current);
+      current = [point];
+    }
+  }
+  if (current.length > 0) runs.push(current);
+  return runs;
+}
+
+function centroid(points: PlayerPoint[]): { x: number; y: number } {
+  const sum = points.reduce((acc, point) => ({ x: acc.x + point.pos.x, y: acc.y + point.pos.y }), { x: 0, y: 0 });
+  return { x: sum.x / points.length, y: sum.y / points.length };
+}
+
+function mostCommonRoom(points: PlayerPoint[]): string | undefined {
+  const counts = new Map<string, number>();
+  for (const point of points) {
+    if (!point.pos.room) continue;
+    counts.set(point.pos.room, (counts.get(point.pos.room) ?? 0) + 1);
+  }
+  return Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
+}
+
+function nearTask(tasks: LobsterTaskPoint[], point: { x: number; y: number }): string | null {
+  let best: { task: LobsterTaskPoint; distance: number } | null = null;
+  for (const task of tasks) {
+    const distance = dist(point, task);
+    if (distance > TASK_DONE_RADIUS) continue;
+    if (!best || distance < best.distance) best = { task, distance };
+  }
+  return best?.task.name ?? null;
+}
+
+function stayKey(data: PlayerHistoryData, point: PlayerPoint): string {
+  const task = nearTask(data.lobster_tasks, point.pos);
+  if (task) return `task:${task}`;
+  return `pos:${point.pos.x},${point.pos.y}`;
+}
+
+function buildStayResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
+  const stays: Record<string, any>[] = [];
+  for (const run of continuousRuns(pointsForPlayer(data.visible_frames, player))) {
+    let segment: PlayerPoint[] = [];
+    let segmentKey: string | null = null;
+    for (const point of run) {
+      const key = stayKey(data, point);
+      if (segment.length === 0 || key === segmentKey) {
+        segment.push(point);
+        segmentKey = key;
+      } else {
+        appendStay(stays, segment, data.lobster_tasks, now);
+        segment = [point];
+        segmentKey = key;
+      }
+    }
+    appendStay(stays, segment, data.lobster_tasks, now);
+  }
+  stays.sort((a, b) => a.to_ago - b.to_ago);
+  return {
+    player,
+    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
+    stays,
+  };
+}
+
+function appendStay(out: Record<string, any>[], segment: PlayerPoint[], tasks: LobsterTaskPoint[], now: number): void {
+  if (segment.length < 2) return;
+  const first = segment[0];
+  const last = segment[segment.length - 1];
+  const secs = durationSecs(first.frame.time, last.frame.time);
+  if (secs < STOP_MIN_SECS) return;
+  const center = centroid(segment);
+  const room = mostCommonRoom(segment);
+  out.push({
+    from_ago: ageSecs(first.frame.time, now),
+    to_ago: ageSecs(last.frame.time, now),
+    secs,
+    room,
+    x: round1(center.x),
+    y: round1(center.y),
+    pos: `${round1(center.x)},${round1(center.y)}`,
+    near_task: nearTask(tasks, center),
+  });
+}
+
+function direction(from: { x: number; y: number }, to: { x: number; y: number }): string {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  if (Math.sqrt(dx ** 2 + dy ** 2) < DIR_MIN_MOVE) return 'stay';
+  const horizontal = Math.abs(dx) >= DIR_MIN_MOVE / 2 ? (dx > 0 ? '右' : '左') : '';
+  const vertical = Math.abs(dy) >= DIR_MIN_MOVE / 2 ? (dy > 0 ? '下' : '上') : '';
+  return `${horizontal}${vertical}` || 'stay';
+}
+
+function buildLastAppearResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
+  const runs = continuousRuns(pointsForPlayer(data.visible_frames, player));
+  const latestFrame = data.visible_frames[data.visible_frames.length - 1];
+  const lastRun = runs[runs.length - 1] ?? [];
+  const last = lastRun[lastRun.length - 1];
+  if (!last) {
+    return {
+      player,
+      ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
+      visible: false,
+      ago: null,
+    };
+  }
+
+  const previous = lastRun.length >= 2 ? lastRun[lastRun.length - 2] : last;
+  return {
+    player,
+    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
+    visible: latestFrame?.players?.[player] != null,
+    ago: ageSecs(last.frame.time, now),
+    room: last.pos.room,
+    x: round1(last.pos.x),
+    y: round1(last.pos.y),
+    dir: direction(previous.pos, last.pos),
+  };
+}
+
+function buildRoomsSeenResult(data: PlayerHistoryData, player: string, now: number): Record<string, any> {
+  const rooms: Record<string, any>[] = [];
+  for (const run of continuousRuns(pointsForPlayer(data.visible_frames, player))) {
+    let currentRoom = run[0]?.pos.room ?? 'unknown';
+    let start = run[0];
+    let previous = run[0];
+    for (const point of run.slice(1)) {
+      const room = point.pos.room ?? 'unknown';
+      if (room !== currentRoom) {
+        rooms.push(roomSegment(currentRoom, start, previous, now));
+        currentRoom = room;
+        start = point;
+      }
+      previous = point;
+    }
+    if (start && previous) rooms.push(roomSegment(currentRoom, start, previous, now));
+  }
+  rooms.sort((a, b) => a.to_ago - b.to_ago);
+  return {
+    player,
+    ...(data.seats?.[player] != null ? { seat: data.seats[player] } : {}),
+    rooms,
+  };
+}
+
+function roomSegment(room: string, start: PlayerPoint, end: PlayerPoint, now: number): Record<string, any> {
+  return {
+    room,
+    from_ago: ageSecs(start.frame.time, now),
+    to_ago: ageSecs(end.frame.time, now),
+    secs: durationSecs(start.frame.time, end.frame.time),
+  };
+}
+
+interface MeetingRecord {
+  round: number;
+  start?: Record<string, any>;
+  briefing?: Record<string, any>;
+  states: Record<string, any>[];
+  speechEvents: Record<string, any>[];
+  voteEvents: Record<string, any>[];
+  resultEvent?: Record<string, any>;
+  ended?: Record<string, any>;
+  interrupted?: boolean;
+}
+
+interface DeathInfo {
+  type: 'found_in_meeting' | 'exiled';
+  round: number;
+}
+
+function buildMeetingRecords(events: Record<string, any>[]): MeetingRecord[] {
+  const meetings: MeetingRecord[] = [];
+  let current: MeetingRecord | null = null;
+
+  const finishCurrent = (interrupted = false) => {
+    if (!current) return;
+    current.interrupted = current.interrupted || interrupted;
+    meetings.push(current);
+    current = null;
+  };
+
+  for (const event of events) {
+    if (event.type === 'meeting_start') {
+      finishCurrent(true);
+      current = {
+        round: meetings.length + 1,
+        start: event,
+        states: [],
+        speechEvents: [],
+        voteEvents: [],
+      };
+      continue;
+    }
+    if (!current) continue;
+
+    if (event.type === 'meeting_briefing') current.briefing = event;
+    if (event.type === 'meeting_state' && (event.round == null || event.round === current.round)) current.states.push(event);
+    if (event.type === 'speech' || event.type === 'speech_skipped' || event.type === 'speech_turn') current.speechEvents.push(event);
+    if (event.type === 'vote_cast') current.voteEvents.push(event);
+    if (event.type === 'exile' || event.type === 'no_exile') current.resultEvent = event;
+    if (event.type === 'meeting_ended') {
+      current.ended = event;
+      finishCurrent(false);
+      continue;
+    }
+    if (event.type === 'game_over') {
+      finishCurrent(true);
+    }
+  }
+  finishCurrent(false);
+  return meetings;
+}
+
+function latestMeetingState(record: MeetingRecord): Record<string, any> | undefined {
+  return record.states[record.states.length - 1];
+}
+
+function meetingVotes(record: MeetingRecord): Record<string, string> {
+  const resultVotes = record.resultEvent?.votes;
+  if (resultVotes && typeof resultVotes === 'object' && !Array.isArray(resultVotes)) {
+    return resultVotes as Record<string, string>;
+  }
+  const votes: Record<string, string> = {};
+  for (const vote of record.voteEvents) {
+    if (typeof vote.actor_name === 'string' && typeof vote.target === 'string') votes[vote.actor_name] = vote.target;
+  }
+  return votes;
+}
+
+function exiledPlayer(record: MeetingRecord): string | null {
+  if (record.ended?.result === 'exiled' && typeof record.ended.result_target === 'string') return record.ended.result_target;
+  if (record.resultEvent?.type === 'exile' && typeof record.resultEvent.actor_name === 'string') return record.resultEvent.actor_name;
+  return null;
+}
+
+function meetingState(record: MeetingRecord): string {
+  if (record.ended) return 'ended';
+  const subPhase = latestMeetingState(record)?.sub_phase;
+  if (typeof subPhase === 'string' && subPhase.length > 0) return subPhase;
+  if (record.interrupted) return 'interrupted_or_missing_end';
+  return 'interrupted_or_missing_end';
+}
+
+function meetingAllSeats(record: MeetingRecord): Array<{ name: string; seat: number }> {
+  const allSeats = record.briefing?.all_seats;
+  if (!Array.isArray(allSeats)) return [];
+  return allSeats
+    .filter((player: any) => typeof player?.name === 'string' && Number.isFinite(player.seat))
+    .map((player: any) => ({ name: player.name, seat: player.seat }))
+    .sort((a, b) => a.seat - b.seat);
+}
+
+function latestAlivePlayers(record: MeetingRecord): Set<string> | null {
+  for (let i = record.states.length - 1; i >= 0; i--) {
+    const alive = record.states[i].alive_players;
+    if (Array.isArray(alive)) return new Set(alive.filter((name: any) => typeof name === 'string'));
+  }
+  return null;
+}
+
+function collectSpeechOrder(record: MeetingRecord): string[] {
+  for (const state of record.states) {
+    if (Array.isArray(state.speech_order)) {
+      return state.speech_order.filter((name: any) => typeof name === 'string');
+    }
+  }
+  const order: string[] = [];
+  for (const event of record.speechEvents) {
+    const speaker = event.actor_name;
+    if (typeof speaker === 'string' && !order.includes(speaker)) order.push(speaker);
+  }
+  return order;
+}
+
+function meetingSpeeches(record: MeetingRecord): Array<{ speaker: string; text: string; skipped: boolean }> {
+  const order = collectSpeechOrder(record);
+  const texts = new Map<string, string>();
+  const skipped = new Set<string>();
+  const seen = new Set<string>();
+
+  for (const state of record.states) {
+    const stateSpeeches = state.speeches;
+    if (stateSpeeches && typeof stateSpeeches === 'object' && !Array.isArray(stateSpeeches)) {
+      for (const [speaker, text] of Object.entries(stateSpeeches)) {
+        if (typeof speaker !== 'string') continue;
+        texts.set(speaker, typeof text === 'string' ? text : '');
+        seen.add(speaker);
+      }
+    }
+    if (Array.isArray(state.speech_skipped)) {
+      for (const speaker of state.speech_skipped) {
+        if (typeof speaker !== 'string') continue;
+        skipped.add(speaker);
+        seen.add(speaker);
+      }
+    }
+  }
+
+  for (const event of record.speechEvents) {
+    const speaker = event.actor_name;
+    if (typeof speaker !== 'string') continue;
+    if (event.type === 'speech') {
+      texts.set(speaker, typeof event.text === 'string' ? event.text : '');
+      seen.add(speaker);
+    } else if (event.type === 'speech_skipped') {
+      skipped.add(speaker);
+      seen.add(speaker);
+    }
+  }
+
+  const outputOrder = [...order, ...Array.from(seen).filter((speaker) => !order.includes(speaker))];
+  return outputOrder
+    .filter((speaker) => seen.has(speaker))
+    .map((speaker) => ({
+      speaker,
+      text: texts.get(speaker) ?? '',
+      skipped: skipped.has(speaker),
+    }));
+}
+
+function applyMeetingDeaths(record: MeetingRecord, deaths: Map<string, DeathInfo>): void {
+  const alive = latestAlivePlayers(record);
+  if (alive) {
+    for (const player of meetingAllSeats(record)) {
+      if (!alive.has(player.name) && !deaths.has(player.name)) {
+        deaths.set(player.name, { type: 'found_in_meeting', round: record.round });
+      }
+    }
+  }
+  const exiled = exiledPlayer(record);
+  if (exiled) deaths.set(exiled, { type: 'exiled', round: record.round });
+}
+
+function meetingPlayers(record: MeetingRecord, deaths: Map<string, DeathInfo>): Record<string, any>[] {
+  return meetingAllSeats(record).map((player) => {
+    const death = deaths.get(player.name) ?? null;
+    return {
+      name: player.name,
+      seat: player.seat,
+      status: death ? 'dead' : 'alive',
+      death,
+    };
+  });
+}
+
+function meetingOutput(record: MeetingRecord, deaths: Map<string, DeathInfo>): Record<string, any> {
+  applyMeetingDeaths(record, deaths);
+  return {
+    round: record.round,
+    tick: record.start?.tick ?? record.briefing?.tick ?? null,
+    caller: record.start?.actor_name ?? record.briefing?.caller ?? latestMeetingState(record)?.caller ?? null,
+    corpses_found: null,
+    state: meetingState(record),
+    exiled_player: exiledPlayer(record),
+    players: meetingPlayers(record, deaths),
+    votes: meetingVotes(record),
+    speeches: meetingSpeeches(record),
+  };
+}
+
+function allMeetingOutputs(records: MeetingRecord[]): Record<string, any>[] {
+  const deaths = new Map<string, DeathInfo>();
+  return records.map((record) => meetingOutput(record, deaths));
+}
+
+function createMeetingsCommand(): Command {
+  return new Command('meetings')
+    .description('Show meeting history')
+    .argument('[round]', 'Meeting round number, starting from 1')
+    .action((roundText?: string) => {
+      const records = buildMeetingRecords(EventStore.forLatestGame().all());
+      const outputs = allMeetingOutputs(records);
+      if (roundText != null) {
+        const round = Number(roundText);
+        const record = Number.isInteger(round) && round > 0 ? outputs.find((meeting) => meeting.round === round) : null;
+        if (!record) {
+          console.log(JSON.stringify({
+            error: {
+              code: 'meeting_round_not_found',
+              round: roundText,
+              available_rounds: outputs.map((meeting) => meeting.round),
+            },
+          }, null, 2));
+          return;
+        }
+        console.log(JSON.stringify(record, null, 2));
+        return;
+      }
+      console.log(JSON.stringify({ meetings: outputs }, null, 2));
+    });
+}
+
+function createPlayerHistorySubcommand(): Command {
+  return new Command('player')
+    .description('Show derived visible-player history')
+    .argument('<kind>', 'stay | last_appear | rooms_seen')
+    .argument('[player_id...]', 'Player name/seat/list, or all')
+    .action(async (kind: string, playerArgs: string[]) => {
+      if (!KINDS.has(kind as HistoryKind)) {
+        console.log(JSON.stringify({ error: { code: 'invalid_kind', allowed: Array.from(KINDS) } }, null, 2));
+        return;
+      }
+
+      const sessionPath = EventStore.latestSessionPath();
+      if (!sessionPath) {
+        console.log(JSON.stringify({
+          kind,
+          error: { code: 'no_game_events', message: 'No game events found. Join a game first.' },
+        }, null, 2));
+        return;
+      }
+      const data = PlayerHistoryStore.forSession(sessionPath).read();
+      if (!data || !Array.isArray(data.visible_frames) || data.visible_frames.length === 0) {
+        console.log(JSON.stringify({
+          kind,
+          error: {
+            code: 'no_player_history',
+            message: 'No player_spotted history yet. Join a game and wait for the game runtime to receive player_spotted events.',
+          },
+        }, null, 2));
+        return;
+      }
+
+      const selectors = splitSelectors(playerArgs);
+      const resolved = resolvePlayers(data, selectors);
+      if (resolved.error) {
+        console.log(JSON.stringify({ kind, error: resolved.error }, null, 2));
+        return;
+      }
+
+      const now = Date.now();
+      const players = resolved.players ?? [];
+      const resultPlayers = players.map((player) => {
+        if (kind === 'stay') return buildStayResult(data, player, now);
+        if (kind === 'last_appear') return buildLastAppearResult(data, player, now);
+        return buildRoomsSeenResult(data, player, now);
+      });
+
+      console.log(JSON.stringify({
+        kind,
+        time: new Date(now).toISOString(),
+        players: resultPlayers,
+      }, null, 2));
+    });
+}
+
+export function createHistoryCommand(): Command {
+  const history = new Command('history')
+    .description('Show derived player and meeting history');
+  history.addCommand(createPlayerHistorySubcommand());
+  history.addCommand(createMeetingsCommand());
+  return history;
+}
+
+export const playerHistoryCommandInternals = {
+  direction,
+  resolvePlayers,
+  buildStayResult,
+  buildLastAppearResult,
+  buildRoomsSeenResult,
+};
+
+export const meetingHistoryCommandInternals = {
+  buildMeetingRecords,
+  allMeetingOutputs,
+  meetingSpeeches,
+};