@myclaw163/clawclaw-cli 0.6.64 → 0.6.66

package/src/commands/watch.ts

@@ -1,659 +1,659 @@
-import { Command } from 'commander';
-import { existsSync, readFileSync, openSync, readSync, closeSync, statSync } from 'fs';
-import { join } from 'path';
-import { AuthStore } from '../lib/auth.js';
-import { getProfileStateDir } from '../lib/init-command.js';
-import { setMeta } from '../lib/command-meta.js';
-import { EventStore, extractNewEvents, isLocalControlEvent } from '../pipeline/event-store.js';
-import { compactEventForEvents, formatEventMessage, shortStateText } from '../pipeline/event-format.js';
-import { PlayerHistoryStore } from '../perception/player-history-store.js';
-import { DEFAULT_MATCH_TIMEOUT_MS } from '../lib/match-state.js';
-import { hubReminder, readCachedGamesPlayed } from '../lib/hub-reminder.js';
-import { sendOwnerControlRequest } from '../runtime/owner-control.js';
-
-export const POLL_INTERVAL_MS = 220;
-const HEARTBEAT_INTERVAL_MS = 60_000;
-const RUNTIME_WAIT_MS = 30_000;
-
-export class WatchNotReadyError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'WatchNotReadyError';
-  }
-}
-
-/** Legacy helper for tests and explicit file-backed attaches. Owner paths use control socket snapshots. */
-export async function waitForFeed(
-  feedPath: string,
-  opts?: { signal?: AbortSignal; timeoutMs?: number; pollMs?: number },
-): Promise<boolean> {
-  const timeoutMs = opts?.timeoutMs ?? RUNTIME_WAIT_MS;
-  const pollMs = opts?.pollMs ?? POLL_INTERVAL_MS;
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (existsSync(feedPath)) return true;
-    if (opts?.signal?.aborted) return false;
-    await new Promise((r) => setTimeout(r, pollMs));
-  }
-  return existsSync(feedPath);
-}
-
-const DEFAULT_MONITOR_EVENT_PRIORITY = 50;
-
-export interface MonitorEventConfig {
-  priority: number;
-}
-
-export const MONITOR_EVENT_CONFIG: Record<string, MonitorEventConfig> = {
-  kill: { priority: 50 },
-  killed: { priority: 99 },
-  murder_witnessed: { priority: 50 },
-  warrior_shrimp_self_destruct: { priority: 50 },
-
-  task_completed: { priority: 50 },
-  task_sabotaged: { priority: 50 },
-
-  corpse_spotted: { priority: 50 },
-  octopus_time_start: { priority: 50 },
-
-  emergency_started: { priority: 50 },
-  emergency_resolved: { priority: 50 },
-
-  exile: { priority: 50 },
-  no_exile: { priority: 50 },
-
-  vote_speech_phase_ended: { priority: 50 },
-  death_speech: { priority: 50 },
-  wandering_speech: { priority: 50 },
-
-  meeting_briefing: { priority: 50 },
-  speech: { priority: 50 },
-  speech_skipped: { priority: 50 },
-  speech_your_turn: { priority: 99 },
-
-  vote_phase_start: { priority: 99 },
-  vote_cast: { priority: 50 },
-  meeting_ended: { priority: 50 },
-
-  game_over: { priority: 50 },
-  role_assigned: { priority: 50 },
-  // game_started intentionally not registered.
-
-  // #region: Matchmaking-phase synthetic events
-  match_waiting: { priority: 50 },
-  match_timeout: { priority: 50 },
-  robot_speak_rule: { priority: 50 },
-  // #endregion
-
-  // Strategy → agent real-time briefing (the automation explaining a decisive
-  // autonomous move, e.g. self-reporting its own kill). Ranked above ambient
-  // wander events so it leads the events[] list.
-  strategy_alert: { priority: 60 },
-};
-
-export const NOTABLE_EVENT_TYPES = new Set(Object.keys(MONITOR_EVENT_CONFIG));
-
-/** Events whose trigger should be delayed to allow merging with nearby events.
- *  Key = event type, Value = delay in milliseconds.
- *  During the delay window, all incoming events (both delayable and non-delayable)
- *  are buffered and emitted together when the timer expires.
- *  Only one delay runs at a time — subsequent delayable events do NOT reset the timer. */
-export const DELAYABLE_EVENT_CONFIG: Record<string, number> = {
-  kill: 2000,
-  emergency_started: 2000,
-  corpse_spotted: 2000,
-};
-
-export interface GameEvent {
-  type: string;
-  tick?: number;
-  ts?: string;
-  [key: string]: any;
-}
-
-export function eventKey(evt: GameEvent): 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 disc = parts.length > 0 ? parts.join('|') : '';
-  return `${type}@${tick}#${disc}`;
-}
-
-export interface EventClassification {
-  notable: boolean;
-}
-
-export function classifyEvent(evt: GameEvent, _youName: string | null = null): EventClassification {
-  const notable = !!(evt.type && NOTABLE_EVENT_TYPES.has(evt.type));
-  return { notable };
-}
-
-function monitorEventPriority(event: GameEvent): number {
-  return MONITOR_EVENT_CONFIG[event.type]?.priority ?? DEFAULT_MONITOR_EVENT_PRIORITY;
-}
-
-interface RouteRule {
-  reason: string;
-  match: (triggers: string[]) => boolean;
-  nextStep: string;
-}
-
-const ROUTING_RULES: RouteRule[] = [
-  { reason: 'speech_your_turn',    match: (t) => t.includes('speech_your_turn'),   nextStep: 'It is YOUR turn to speak. Submit `ccl do -s "<draft>"` immediately. Server skips you after 45s.' },
-  { reason: 'role_assigned',        match: (t) => t.includes('role_assigned'),      nextStep: 'Tell user your role, faction, win condition, and first plan.' },
-  { reason: 'vote_cast',           match: (t) => t.includes('vote_cast'),          nextStep: 'A player just cast their vote. Read events[] to track who voted. No `ccl` action needed — cast your own vote immediately when vote phase starts.' },
-  { reason: 'match_start',         match: (t) => t.includes('match_start'),        nextStep: 'Matchmaking queue entered. The game runtime is live and the stream is attached. Chat with the user while waiting for allocation.' },
-  { reason: 'match_waiting',       match: (t) => t.includes('match_waiting'),      nextStep: 'Still in queue (see `events[].waited_secs`). Keep chatting with the user; no tactical action required.' },
-  { reason: 'match_timeout',       match: (t) => t.includes('match_timeout'),      nextStep: `Cumulative wait reached ${Math.round(DEFAULT_MATCH_TIMEOUT_MS / 60_000)} min (see \`events[].waited_secs\`). The stream will exit — discuss with the user: launch a fresh \`ccl game start\` to retry, or call it a session.` },
-  { reason: 'game_over',           match: (t) => t.includes('game_over'),          nextStep: 'Game ended. The current ccl game start process is exiting automatically. Review the result with the user; start another match only if the user asks.' },
-  { reason: 'strategy_alert',      match: (t) => t.includes('strategy_alert'),     nextStep: 'Your automation just made a decisive autonomous move and is briefing you (read events[].message). Lock your story to it before you next speak or vote — e.g. if it reported a corpse that is likely your own kill, present yourself as the proactive reporter, steer suspicion onto the bystanders, and do NOT confess.' },
-];
-
-const DEFAULT_NEXT_STEP = 'React to summary fields. No relaunch needed — the stream stays attached.';
-
-function routeTriggers(triggers: string[]): { exitReason: string; nextStep: string } {
-  const rule = ROUTING_RULES.find((r) => r.match(triggers));
-  return {
-    exitReason: rule?.reason ?? triggers[0],
-    nextStep: rule?.nextStep ?? DEFAULT_NEXT_STEP,
-  };
-}
-
-export function nextStepFor(reason: string): string {
-  return routeTriggers([reason]).nextStep;
-}
-
-export function nextStepForTriggers(triggers: string[]): string {
-  return routeTriggers(triggers).nextStep;
-}
-
-export function sortEventsForMonitor(events: GameEvent[]): GameEvent[] {
-  return events
-    .map((event, index) => ({
-      event,
-      index,
-      priority: monitorEventPriority(event),
-    }))
-    .sort((a, b) => (b.priority - a.priority) || (a.index - b.index))
-    .map(({ event }) => event);
-}
-
-function readSeatMapForMonitor(sessionPath: string | null): Record<string, number> {
-  if (!sessionPath) return {};
-  try {
-    return PlayerHistoryStore.forSession(sessionPath).read()?.seats ?? {};
-  } catch {
-    return {};
-  }
-}
-
-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;
-}
-
-export function compactEventForMonitor(event: GameEvent): Record<string, any> {
-  return compactEventForEvents(event);
-}
-
-export function summarizeFeed(feed: any): any | null {
-  if (!feed || typeof feed !== 'object') return null;
-  const summary: any = {
-    phase: feed.phase,
-    you: {
-      name: feed.you?.name,
-      seat: feed.you?.seat,
-      role: feed.you?.role,
-      role_display: feed.you?.role_display,
-      faction: feed.you?.faction,
-      alive: feed.you?.alive,
-      x: feed.you?.x,
-      y: feed.you?.y,
-      currently_moving: feed.you?.currently_moving,
-      doing_task: feed.you?.doing_task,
-      kill_cooldown_secs: feed.you?.kill_cooldown_secs,
-      kills_remaining: feed.you?.kills_remaining,
-    },
-    game: feed.game,
-    urgent: feed.urgent,
-    meeting: feed.meeting,
-  };
-  if (feed.automation) summary.automation = feed.automation;
-  return summary;
-}
-
-export function readFeedSummary(feedPath: string): any | null {
-  try {
-    const feed = JSON.parse(readFileSync(feedPath, 'utf8'));
-    return summarizeFeed(feed);
-  } catch {
-    return null;
-  }
-}
-
-export function compactSummaryForMonitor(summary: any | null, triggers: string[]): any | null {
-  if (!summary || summary.phase !== 'meeting') return summary;
-  const oldMeeting = summary.meeting ?? {};
-  const oldYou = summary.you ?? {};
-  const isVotePhase = triggers.includes('vote_phase_start')
-    || (!triggers.includes('speech_your_turn') && oldMeeting.sub_phase === 'vote');
-  const meeting: Record<string, any> = {
-    caller: oldMeeting.caller,
-    sub_phase: triggers.includes('vote_phase_start') ? 'vote' : oldMeeting.sub_phase,
-    alive_players: oldMeeting.alive_players,
-  };
-  if (triggers.includes('speech_your_turn')) {
-    meeting.sub_phase = 'speech';
-    meeting.current_speaker = oldYou.name;
-    meeting.is_my_turn = true;
-  } else if (!isVotePhase) {
-    meeting.current_speaker = oldMeeting.current_speaker;
-    meeting.is_my_turn = oldMeeting.is_my_turn;
-  }
-  if (isVotePhase) {
-    meeting.votes_submitted_count = Array.isArray(oldMeeting.votes_submitted)
-      ? oldMeeting.votes_submitted.length
-      : 0;
-  }
-  return cleanObject({
-    phase: summary.phase,
-    you: cleanObject({
-      name: oldYou.name,
-      role: oldYou.role,
-      faction: oldYou.faction,
-    }),
-    game: summary.game,
-    meeting: cleanObject(meeting),
-    automation: summary.automation,
-  });
-}
-
-export interface RunStreamingOptions {
-  feedPath: string;
-  sessionPath: string | null;
-  readSummary?: () => any | null;
-  /** Optional dynamic resolver — called each poll so the stream can follow session rotation across games. */
-  getSessionPath?: () => string | null;
-  stdout: (line: string) => void;
-  signal?: AbortSignal;
-  skipFeedWait?: boolean;
-  pollIntervalMs?: number;
-  /** Emit a `heartbeat` NDJSON line after this many ms of silence so consumers don't see the stream as hung. Default 30s. Pass 0 to disable. */
-  heartbeatIntervalMs?: number;
-  /** Max ms to wait for feed.json when launching alongside `game start`. Default 30s. */
-  runtimeWaitMs?: number;
-  /**
-   * Per-event-type delay overrides for the delay buffer (see DELAYABLE_EVENT_CONFIG).
-   * Pass `{ kill: 0 }` to disable the kill delay in tests.
-   * Values from DELAYABLE_EVENT_CONFIG are used for any type not overridden here.
-   */
-  delayableEventMs?: Record<string, number>;
-  /**
-   * Event types to exclude from the initial `caught_up` backlog (useful when the
-   * caller already emitted them live before chaining into runStreaming, e.g.
-   * `ccl game start` emits `match_waiting` / `match_timeout` during its polling
-   * phase). Does NOT affect ongoing event tailing — only the one-time pre-attach
-   * backlog drain.
-   */
-  skipBacklogTypes?: string[];
-  /**
-   * Emit a first `game_start` beat even when no backlog is present. `ccl game start`
-   * uses this to tell the agent the stream is attached without carrying a huge
-   * `initial_payload`.
-   */
-  emitGameStart?: boolean;
-  /**
-   * When set, attached to the `game_over` emission (as a `hub_reminder` field
-   * and appended to `next_step`) so the agent sees the nudge in the same beat it
-   * starts the post-game debrief. Callers compute it via `hubReminder()`; pass
-   * nothing once the account has adopted a hub or custom strategy.
-   */
-  hubReminder?: string;
-}
-
-export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
-  if (!opts.skipFeedWait) {
-    const feedReady = await waitForFeed(opts.feedPath, {
-      signal: opts.signal,
-      timeoutMs: opts.runtimeWaitMs ?? RUNTIME_WAIT_MS,
-      pollMs: opts.pollIntervalMs ?? POLL_INTERVAL_MS,
-    });
-    if (!feedReady) {
-      throw new WatchNotReadyError(
-        'Game runtime not ready (no feed.json). Run `ccl game start` to start or recover the game stream.',
-      );
-    }
-  }
-  const interval = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
-  const heartbeatInterval = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
-  const resolvedDelays: Record<string, number> = { ...DELAYABLE_EVENT_CONFIG, ...(opts.delayableEventMs ?? {}) };
-  let lastEmitMs = Date.now();
-  const emit = (obj: any): void => {
-    opts.stdout(JSON.stringify(obj) + '\n');
-    lastEmitMs = Date.now();
-  };
-
-  // Initial player name from owner snapshot or legacy feed file (best-effort).
-  let youName: string | null = null;
-  try {
-    youName = opts.readSummary?.()?.you?.name
-      ?? JSON.parse(readFileSync(opts.feedPath, 'utf8'))?.you?.name
-      ?? null;
-  } catch {}
-
-  // Tail state for the .jsonl
-  const seenKeys = new Set<string>();
-  let filePos = 0;
-  let fileIno = 0;
-  let lineBuffer = '';
-  let currentSessionPath: string | null = opts.sessionPath;
-
-  if (currentSessionPath && existsSync(currentSessionPath)) {
-    filePos = 0;
-    fileIno = statSync(currentSessionPath).ino;
-  }
-
-  // Cross-game session rotation: the runtime may create a new events.jsonl when a new
-  // game starts. If the caller provided a dynamic resolver, poll it and switch
-  // tail state to the new file. Without this, the stream would silently follow the
-  // previous game's file forever and look like a huge event delay.
-  const refreshSessionPath = (): void => {
-    if (!opts.getSessionPath) return;
-    const latest = opts.getSessionPath();
-    if (!latest || latest === currentSessionPath) return;
-    currentSessionPath = latest;
-    filePos = 0;
-    lineBuffer = '';
-    try { fileIno = existsSync(latest) ? statSync(latest).ino : 0; } catch { fileIno = 0; }
-  };
-
-  const drainNewEvents = (): GameEvent[] => {
-    if (!currentSessionPath || !existsSync(currentSessionPath)) return [];
-    let stat;
-    try { stat = statSync(currentSessionPath); } catch { return []; }
-    if (stat.ino !== fileIno || stat.size < filePos) {
-      filePos = 0; fileIno = stat.ino; lineBuffer = '';
-    }
-    if (stat.size <= filePos) return [];
-    let fd: number;
-    try { fd = openSync(currentSessionPath, 'r'); } catch { return []; }
-    const buf = Buffer.alloc(stat.size - filePos);
-    readSync(fd, buf, 0, buf.length, filePos);
-    closeSync(fd);
-    filePos = stat.size;
-    lineBuffer += buf.toString('utf8');
-    const lastNl = lineBuffer.lastIndexOf('\n');
-    if (lastNl < 0) return [];
-    const chunk = lineBuffer.slice(0, lastNl);
-    lineBuffer = lineBuffer.slice(lastNl + 1);
-    const events: GameEvent[] = [];
-    for (const line of chunk.split('\n')) {
-      if (!line) continue;
-      try {
-        const evt = JSON.parse(line);
-        if (!isLocalControlEvent(evt)) events.push(evt);
-        for (const nested of extractNewEvents(evt) as GameEvent[]) {
-          if (!isLocalControlEvent(nested)) events.push(nested);
-        }
-      } catch {}
-    }
-    return events;
-  };
-
-  // Pre-attach backlog: drain once, classify, hold for first emit.
-  const backlogEvents = drainNewEvents();
-  const skipSet = new Set(opts.skipBacklogTypes ?? []);
-  const backlogNotable = backlogEvents.filter((e) => {
-    if (e.type && skipSet.has(e.type as string)) return false;
-    return classifyEvent(e, youName).notable;
-  });
-  let caughtUpEvents: GameEvent[] = backlogNotable.slice(-20);
-  for (const e of backlogEvents) seenKeys.add(eventKey(e));
-
-  const buildOut = (
-    triggers: string[],
-    _nextStep: string,
-    events: GameEvent[] = [],
-  ): any => {
-    const rawSummary = opts.readSummary?.() ?? readFeedSummary(opts.feedPath);
-    const summary = compactSummaryForMonitor(rawSummary, triggers);
-    // Server pushes `meeting_briefing` without `speech_order` (that field only lives in
-    // meeting state, which the runtime projects onto the owner snapshot).
-    // Inject it onto the briefing event here so consumers can read it from events[]
-    // directly. Guarded by caller match so a stale speech_order from a previous
-    // meeting isn't ever attached.
-    const enrichMeetingBriefing = (e: GameEvent): GameEvent => {
-      if (e.type !== 'meeting_briefing') return e;
-      if (e.speech_order) return e;
-      const so = rawSummary?.meeting?.speech_order;
-      if (!Array.isArray(so)) return e;
-      const sumCaller = rawSummary?.meeting?.caller;
-      if (sumCaller && e.caller && sumCaller !== e.caller) return e;
-      return { ...e, speech_order: so };
-    };
-    const sourceEvents = events.length > 0
-      ? sortEventsForMonitor(events).map(enrichMeetingBriefing)
-      : triggers.map((type) => ({ type }));
-    const context = {
-      summary,
-      seats: readSeatMapForMonitor(currentSessionPath),
-      maxTextLength: 90,
-    };
-    return {
-      events: sourceEvents.map((event) => event.type),
-      messages: sourceEvents.map((event) => formatEventMessage(event, context)),
-      state: shortStateText(summary),
-    };
-  };
-
-  const fireTrigger = (
-    triggers: string[],
-    triggeredEvents: GameEvent[],
-  ): void => {
-    if (triggers.length === 0) return;
-    const { nextStep } = routeTriggers(triggers);
-    const out = buildOut(triggers, nextStep, triggeredEvents.slice(-10));
-    if (opts.hubReminder && triggers.includes('game_over')) {
-      out.hub_reminder = opts.hubReminder;
-    }
-    emit(out);
-  };
-
-  // Always emit an attached first beat when there is a pre-attach backlog OR
-  // the caller explicitly requests one.
-  if (caughtUpEvents.length > 0 || opts.emitGameStart) {
-    const hasBacklog = caughtUpEvents.length > 0;
-    const nextStep = opts.emitGameStart
-      ? hasBacklog
-        ? 'Game stream attached. Read summary and caught_up.notable_events for opening events; current strategy appears in summary.automation.strategy.'
-        : 'Game stream attached. Read summary and wait for role_assigned; current strategy appears in summary.automation.strategy.'
-      : 'Catch-up complete. Read summary, then continue play.';
-    const attachedEvents = hasBacklog ? caughtUpEvents : [{ type: 'game_start' }];
-    const attachedOut = buildOut(attachedEvents.map((event) => event.type), nextStep, attachedEvents);
-    caughtUpEvents = [];
-    emit(attachedOut);
-  }
-
-  // Delay buffer: merge rapid-fire wandering-phase events into one notification
-  let delayActive = false;
-  let delayDeadline = 0;
-  const delayBuffer: { triggers: Set<string>; events: GameEvent[] } = {
-    triggers: new Set(),
-    events: [],
-  };
-
-  while (!opts.signal?.aborted) {
-    refreshSessionPath();
-
-    const triggers: string[] = [];
-    const triggeredEvents: GameEvent[] = [];
-
-    const newEvents = drainNewEvents();
-    for (const evt of newEvents) {
-      const cls = classifyEvent(evt, youName);
-      if (!cls.notable) continue;
-      const key = eventKey(evt);
-      if (seenKeys.has(key)) continue;
-      seenKeys.add(key);
-      triggeredEvents.push(evt);
-      if (evt.type && !triggers.includes(evt.type)) {
-        triggers.push(evt.type);
-      }
-    }
-
-    // ── Delay buffer: merge rapid-fire wandering-phase events ──
-    // Only active during wandering; meeting-phase events (my_turn, speech, etc.)
-    // are not in DELAYABLE_EVENT_CONFIG and won't start a delay.
-    if (delayActive) {
-      if (Date.now() < delayDeadline) {
-        // Still within delay window — buffer everything and wait
-        for (const t of triggers) delayBuffer.triggers.add(t);
-        for (const e of triggeredEvents) delayBuffer.events.push(e);
-        triggers.length = 0;
-        triggeredEvents.length = 0;
-      } else {
-        // Delay expired — flush buffer in front of current batch
-        for (const t of delayBuffer.triggers) {
-          if (!triggers.includes(t)) triggers.unshift(t);
-        }
-        triggeredEvents.unshift(...delayBuffer.events);
-        delayBuffer.triggers.clear();
-        delayBuffer.events.length = 0;
-        delayActive = false;
-      }
-    } else if (triggers.length > 0) {
-      // Check if any trigger is delayable; start a delay if so
-      let delayMs = 0;
-      for (const t of triggers) {
-        const ms = resolvedDelays[t];
-        if (ms !== undefined && ms > delayMs) delayMs = ms;
-      }
-      if (delayMs > 0) {
-        delayActive = true;
-        delayDeadline = Date.now() + delayMs;
-        for (const t of triggers) delayBuffer.triggers.add(t);
-        for (const e of triggeredEvents) delayBuffer.events.push(e);
-        triggers.length = 0;
-        triggeredEvents.length = 0;
-      }
-    }
-
-    if (triggers.length > 0) {
-      fireTrigger(triggers, triggeredEvents);
-      if (triggers.includes('game_over')) return;
-    } else if (!delayActive && heartbeatInterval > 0 && Date.now() - lastEmitMs >= heartbeatInterval) {
-      // Idle keepalive — prevents downstream adapters from interpreting a quiet
-      // wandering/transit period as a hung subprocess and killing it on their
-      // own default timeout (commonly 60s).
-      emit(buildOut(
-        ['heartbeat'],
-        'Stream is alive; no notable events. Continue waiting — no action required.',
-      ));
-    }
-
-    if (opts.signal?.aborted) break;
-    await new Promise((r) => setTimeout(r, interval));
-  }
-}
-
-export interface SnapshotOnceOptions {
-  feedPath: string;
-  stdout: (line: string) => void;
-}
-
-export function snapshotOnce(opts: SnapshotOnceOptions): void {
-  if (!existsSync(opts.feedPath)) {
-    throw new Error('ccl game runtime is not running. Start it first with `ccl game start`.');
-  }
-  const summary = readFeedSummary(opts.feedPath);
-  opts.stdout(JSON.stringify({
-    events: ['snapshot'],
-    messages: [formatEventMessage({ type: 'snapshot' })],
-    state: shortStateText(summary),
-  }) + '\n');
-}
-
-export function buildErrorLine(err: any, opts?: { notReadyNextStep?: string }): string {
-  const msg = err?.message ?? String(err);
-  const notReady = err?.name === 'WatchNotReadyError' || /not ready|feed\.json/i.test(msg);
-  const reason = notReady ? 'not_ready' : 'error';
-  const event = {
-    type: reason,
-    message: notReady
-      ? (opts?.notReadyNextStep ?? 'Game runtime not running. Run `ccl game start` to begin a new session.')
-      : msg,
-  };
-  return JSON.stringify({
-    events: [reason],
-    messages: [formatEventMessage(event)],
-    state: 'state unavailable',
-    error: msg,
-  }) + '\n';
-}
-
-export function createWatchCommand(): Command {
-  const cmd = new Command('watch')
-    .description('Stream notable game events as NDJSON. Exits on game_over. For a one-shot snapshot use `ccl peek`.')
-    .action(async () => {
-      const store = new AuthStore();
-      const profile = store.getActive();
-      if (!profile) {
-        process.stdout.write(JSON.stringify({ exit_reason: ['not_logged_in'], error: 'Not logged in' }) + '\n');
-        return;
-      }
-      const stateDir = getProfileStateDir(profile);
-      const feedPath = join(stateDir, 'feed.json');
-      const sessionPath = EventStore.latestSessionPath();
-      const ctrl = new AbortController();
-      process.on('SIGINT', () => ctrl.abort());
-      process.on('SIGTERM', () => ctrl.abort());
-      let summaryCache: any | null = null;
-      let summaryPoll: ReturnType<typeof setInterval> | null = null;
-      try {
-        const snapshot = await sendOwnerControlRequest(stateDir, 'snapshot');
-        if (!snapshot?.ok) {
-          throw new WatchNotReadyError(
-            'Game runtime not ready (no active ccl game start owner). Run `ccl game start` to start or recover the game stream.',
-          );
-        }
-        summaryCache = snapshot.summary ?? null;
-        summaryPoll = setInterval(() => {
-          void sendOwnerControlRequest(stateDir, 'snapshot')
-            .then((response) => {
-              if (response?.ok) summaryCache = response.summary ?? null;
-            })
-            .catch(() => {});
-        }, 1000);
-        await runStreaming({
-          feedPath,
-          sessionPath,
-          getSessionPath: () => EventStore.latestSessionPath(),
-          stdout: (s) => process.stdout.write(s),
-          signal: ctrl.signal,
-          skipFeedWait: true,
-          readSummary: () => summaryCache,
-          hubReminder: hubReminder(readCachedGamesPlayed()),
-        });
-      } catch (err: any) {
-        process.stdout.write(buildErrorLine(err, {
-          notReadyNextStep: 'Run `ccl game start` to start or recover the game stream.',
-        }));
-        process.exit(1);
-      } finally {
-        if (summaryPoll) clearInterval(summaryPoll);
-      }
-    });
-  // ── Adapter metadata: streaming mode blocks until game_over; cap at 30min for stuck-process safety ──
-  setMeta(cmd, { longRunning: true, timeoutMs: 1_800_000 });
-  return cmd;
-}
+import { Command } from 'commander';
+import { existsSync, readFileSync, openSync, readSync, closeSync, statSync } from 'fs';
+import { join } from 'path';
+import { AuthStore } from '../lib/auth.js';
+import { getProfileStateDir } from '../lib/init-command.js';
+import { setMeta } from '../lib/command-meta.js';
+import { EventStore, extractNewEvents, isLocalControlEvent } from '../pipeline/event-store.js';
+import { compactEventForEvents, formatEventMessage, shortStateText } from '../pipeline/event-format.js';
+import { PlayerHistoryStore } from '../perception/player-history-store.js';
+import { DEFAULT_MATCH_TIMEOUT_MS } from '../lib/match-state.js';
+import { hubReminder, readCachedGamesPlayed } from '../lib/hub-reminder.js';
+import { sendOwnerControlRequest } from '../runtime/owner-control.js';
+
+export const POLL_INTERVAL_MS = 220;
+const HEARTBEAT_INTERVAL_MS = 60_000;
+const RUNTIME_WAIT_MS = 30_000;
+
+export class WatchNotReadyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WatchNotReadyError';
+  }
+}
+
+/** Legacy helper for tests and explicit file-backed attaches. Owner paths use control socket snapshots. */
+export async function waitForFeed(
+  feedPath: string,
+  opts?: { signal?: AbortSignal; timeoutMs?: number; pollMs?: number },
+): Promise<boolean> {
+  const timeoutMs = opts?.timeoutMs ?? RUNTIME_WAIT_MS;
+  const pollMs = opts?.pollMs ?? POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(feedPath)) return true;
+    if (opts?.signal?.aborted) return false;
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return existsSync(feedPath);
+}
+
+const DEFAULT_MONITOR_EVENT_PRIORITY = 50;
+
+export interface MonitorEventConfig {
+  priority: number;
+}
+
+export const MONITOR_EVENT_CONFIG: Record<string, MonitorEventConfig> = {
+  kill: { priority: 50 },
+  killed: { priority: 99 },
+  murder_witnessed: { priority: 50 },
+  warrior_shrimp_self_destruct: { priority: 50 },
+
+  task_completed: { priority: 50 },
+  task_sabotaged: { priority: 50 },
+
+  corpse_spotted: { priority: 50 },
+  octopus_time_start: { priority: 50 },
+
+  emergency_started: { priority: 50 },
+  emergency_resolved: { priority: 50 },
+
+  exile: { priority: 50 },
+  no_exile: { priority: 50 },
+
+  vote_speech_phase_ended: { priority: 50 },
+  death_speech: { priority: 50 },
+  wandering_speech: { priority: 50 },
+
+  meeting_briefing: { priority: 50 },
+  speech: { priority: 50 },
+  speech_skipped: { priority: 50 },
+  speech_your_turn: { priority: 99 },
+
+  vote_phase_start: { priority: 99 },
+  vote_cast: { priority: 50 },
+  meeting_ended: { priority: 50 },
+
+  game_over: { priority: 50 },
+  role_assigned: { priority: 50 },
+  // game_started intentionally not registered.
+
+  // #region: Matchmaking-phase synthetic events
+  match_waiting: { priority: 50 },
+  match_timeout: { priority: 50 },
+  robot_speak_rule: { priority: 50 },
+  // #endregion
+
+  // Strategy → agent real-time briefing (the automation explaining a decisive
+  // autonomous move, e.g. self-reporting its own kill). Ranked above ambient
+  // wander events so it leads the events[] list.
+  strategy_alert: { priority: 60 },
+};
+
+export const NOTABLE_EVENT_TYPES = new Set(Object.keys(MONITOR_EVENT_CONFIG));
+
+/** Events whose trigger should be delayed to allow merging with nearby events.
+ *  Key = event type, Value = delay in milliseconds.
+ *  During the delay window, all incoming events (both delayable and non-delayable)
+ *  are buffered and emitted together when the timer expires.
+ *  Only one delay runs at a time — subsequent delayable events do NOT reset the timer. */
+export const DELAYABLE_EVENT_CONFIG: Record<string, number> = {
+  kill: 2000,
+  emergency_started: 2000,
+  corpse_spotted: 2000,
+};
+
+export interface GameEvent {
+  type: string;
+  tick?: number;
+  ts?: string;
+  [key: string]: any;
+}
+
+export function eventKey(evt: GameEvent): 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 disc = parts.length > 0 ? parts.join('|') : '';
+  return `${type}@${tick}#${disc}`;
+}
+
+export interface EventClassification {
+  notable: boolean;
+}
+
+export function classifyEvent(evt: GameEvent, _youName: string | null = null): EventClassification {
+  const notable = !!(evt.type && NOTABLE_EVENT_TYPES.has(evt.type));
+  return { notable };
+}
+
+function monitorEventPriority(event: GameEvent): number {
+  return MONITOR_EVENT_CONFIG[event.type]?.priority ?? DEFAULT_MONITOR_EVENT_PRIORITY;
+}
+
+interface RouteRule {
+  reason: string;
+  match: (triggers: string[]) => boolean;
+  nextStep: string;
+}
+
+const ROUTING_RULES: RouteRule[] = [
+  { reason: 'speech_your_turn',    match: (t) => t.includes('speech_your_turn'),   nextStep: 'It is YOUR turn to speak. Submit `ccl do -s "<draft>"` immediately. Server skips you after 45s.' },
+  { reason: 'role_assigned',        match: (t) => t.includes('role_assigned'),      nextStep: 'Tell user your role, faction, win condition, and first plan.' },
+  { reason: 'vote_cast',           match: (t) => t.includes('vote_cast'),          nextStep: 'A player just cast their vote. Read events[] to track who voted. No `ccl` action needed — cast your own vote immediately when vote phase starts.' },
+  { reason: 'match_start',         match: (t) => t.includes('match_start'),        nextStep: 'Matchmaking queue entered. The game runtime is live and the stream is attached. Chat with the user while waiting for allocation.' },
+  { reason: 'match_waiting',       match: (t) => t.includes('match_waiting'),      nextStep: 'Still in queue (see `events[].waited_secs`). Keep chatting with the user; no tactical action required.' },
+  { reason: 'match_timeout',       match: (t) => t.includes('match_timeout'),      nextStep: `Cumulative wait reached ${Math.round(DEFAULT_MATCH_TIMEOUT_MS / 60_000)} min (see \`events[].waited_secs\`). The stream will exit — discuss with the user: launch a fresh \`ccl game start\` to retry, or call it a session.` },
+  { reason: 'game_over',           match: (t) => t.includes('game_over'),          nextStep: 'Game ended. The current ccl game start process is exiting automatically. Review the result with the user; start another match only if the user asks.' },
+  { reason: 'strategy_alert',      match: (t) => t.includes('strategy_alert'),     nextStep: 'Your automation just made a decisive autonomous move and is briefing you (read events[].message). Lock your story to it before you next speak or vote — e.g. if it reported a corpse that is likely your own kill, present yourself as the proactive reporter, steer suspicion onto the bystanders, and do NOT confess.' },
+];
+
+const DEFAULT_NEXT_STEP = 'React to summary fields. No relaunch needed — the stream stays attached.';
+
+function routeTriggers(triggers: string[]): { exitReason: string; nextStep: string } {
+  const rule = ROUTING_RULES.find((r) => r.match(triggers));
+  return {
+    exitReason: rule?.reason ?? triggers[0],
+    nextStep: rule?.nextStep ?? DEFAULT_NEXT_STEP,
+  };
+}
+
+export function nextStepFor(reason: string): string {
+  return routeTriggers([reason]).nextStep;
+}
+
+export function nextStepForTriggers(triggers: string[]): string {
+  return routeTriggers(triggers).nextStep;
+}
+
+export function sortEventsForMonitor(events: GameEvent[]): GameEvent[] {
+  return events
+    .map((event, index) => ({
+      event,
+      index,
+      priority: monitorEventPriority(event),
+    }))
+    .sort((a, b) => (b.priority - a.priority) || (a.index - b.index))
+    .map(({ event }) => event);
+}
+
+function readSeatMapForMonitor(sessionPath: string | null): Record<string, number> {
+  if (!sessionPath) return {};
+  try {
+    return PlayerHistoryStore.forSession(sessionPath).read()?.seats ?? {};
+  } catch {
+    return {};
+  }
+}
+
+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;
+}
+
+export function compactEventForMonitor(event: GameEvent): Record<string, any> {
+  return compactEventForEvents(event);
+}
+
+export function summarizeFeed(feed: any): any | null {
+  if (!feed || typeof feed !== 'object') return null;
+  const summary: any = {
+    phase: feed.phase,
+    you: {
+      name: feed.you?.name,
+      seat: feed.you?.seat,
+      role: feed.you?.role,
+      role_display: feed.you?.role_display,
+      faction: feed.you?.faction,
+      alive: feed.you?.alive,
+      x: feed.you?.x,
+      y: feed.you?.y,
+      currently_moving: feed.you?.currently_moving,
+      doing_task: feed.you?.doing_task,
+      kill_cooldown_secs: feed.you?.kill_cooldown_secs,
+      kills_remaining: feed.you?.kills_remaining,
+    },
+    game: feed.game,
+    urgent: feed.urgent,
+    meeting: feed.meeting,
+  };
+  if (feed.automation) summary.automation = feed.automation;
+  return summary;
+}
+
+export function readFeedSummary(feedPath: string): any | null {
+  try {
+    const feed = JSON.parse(readFileSync(feedPath, 'utf8'));
+    return summarizeFeed(feed);
+  } catch {
+    return null;
+  }
+}
+
+export function compactSummaryForMonitor(summary: any | null, triggers: string[]): any | null {
+  if (!summary || summary.phase !== 'meeting') return summary;
+  const oldMeeting = summary.meeting ?? {};
+  const oldYou = summary.you ?? {};
+  const isVotePhase = triggers.includes('vote_phase_start')
+    || (!triggers.includes('speech_your_turn') && oldMeeting.sub_phase === 'vote');
+  const meeting: Record<string, any> = {
+    caller: oldMeeting.caller,
+    sub_phase: triggers.includes('vote_phase_start') ? 'vote' : oldMeeting.sub_phase,
+    alive_players: oldMeeting.alive_players,
+  };
+  if (triggers.includes('speech_your_turn')) {
+    meeting.sub_phase = 'speech';
+    meeting.current_speaker = oldYou.name;
+    meeting.is_my_turn = true;
+  } else if (!isVotePhase) {
+    meeting.current_speaker = oldMeeting.current_speaker;
+    meeting.is_my_turn = oldMeeting.is_my_turn;
+  }
+  if (isVotePhase) {
+    meeting.votes_submitted_count = Array.isArray(oldMeeting.votes_submitted)
+      ? oldMeeting.votes_submitted.length
+      : 0;
+  }
+  return cleanObject({
+    phase: summary.phase,
+    you: cleanObject({
+      name: oldYou.name,
+      role: oldYou.role,
+      faction: oldYou.faction,
+    }),
+    game: summary.game,
+    meeting: cleanObject(meeting),
+    automation: summary.automation,
+  });
+}
+
+export interface RunStreamingOptions {
+  feedPath: string;
+  sessionPath: string | null;
+  readSummary?: () => any | null;
+  /** Optional dynamic resolver — called each poll so the stream can follow session rotation across games. */
+  getSessionPath?: () => string | null;
+  stdout: (line: string) => void;
+  signal?: AbortSignal;
+  skipFeedWait?: boolean;
+  pollIntervalMs?: number;
+  /** Emit a `heartbeat` NDJSON line after this many ms of silence so consumers don't see the stream as hung. Default 30s. Pass 0 to disable. */
+  heartbeatIntervalMs?: number;
+  /** Max ms to wait for feed.json when launching alongside `game start`. Default 30s. */
+  runtimeWaitMs?: number;
+  /**
+   * Per-event-type delay overrides for the delay buffer (see DELAYABLE_EVENT_CONFIG).
+   * Pass `{ kill: 0 }` to disable the kill delay in tests.
+   * Values from DELAYABLE_EVENT_CONFIG are used for any type not overridden here.
+   */
+  delayableEventMs?: Record<string, number>;
+  /**
+   * Event types to exclude from the initial `caught_up` backlog (useful when the
+   * caller already emitted them live before chaining into runStreaming, e.g.
+   * `ccl game start` emits `match_waiting` / `match_timeout` during its polling
+   * phase). Does NOT affect ongoing event tailing — only the one-time pre-attach
+   * backlog drain.
+   */
+  skipBacklogTypes?: string[];
+  /**
+   * Emit a first `game_start` beat even when no backlog is present. `ccl game start`
+   * uses this to tell the agent the stream is attached without carrying a huge
+   * `initial_payload`.
+   */
+  emitGameStart?: boolean;
+  /**
+   * When set, attached to the `game_over` emission (as a `hub_reminder` field
+   * and appended to `next_step`) so the agent sees the nudge in the same beat it
+   * starts the post-game debrief. Callers compute it via `hubReminder()`; pass
+   * nothing once the account has adopted a hub or custom strategy.
+   */
+  hubReminder?: string;
+}
+
+export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
+  if (!opts.skipFeedWait) {
+    const feedReady = await waitForFeed(opts.feedPath, {
+      signal: opts.signal,
+      timeoutMs: opts.runtimeWaitMs ?? RUNTIME_WAIT_MS,
+      pollMs: opts.pollIntervalMs ?? POLL_INTERVAL_MS,
+    });
+    if (!feedReady) {
+      throw new WatchNotReadyError(
+        'Game runtime not ready (no feed.json). Run `ccl game start` to start or recover the game stream.',
+      );
+    }
+  }
+  const interval = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
+  const heartbeatInterval = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+  const resolvedDelays: Record<string, number> = { ...DELAYABLE_EVENT_CONFIG, ...(opts.delayableEventMs ?? {}) };
+  let lastEmitMs = Date.now();
+  const emit = (obj: any): void => {
+    opts.stdout(JSON.stringify(obj) + '\n');
+    lastEmitMs = Date.now();
+  };
+
+  // Initial player name from owner snapshot or legacy feed file (best-effort).
+  let youName: string | null = null;
+  try {
+    youName = opts.readSummary?.()?.you?.name
+      ?? JSON.parse(readFileSync(opts.feedPath, 'utf8'))?.you?.name
+      ?? null;
+  } catch {}
+
+  // Tail state for the .jsonl
+  const seenKeys = new Set<string>();
+  let filePos = 0;
+  let fileIno = 0;
+  let lineBuffer = '';
+  let currentSessionPath: string | null = opts.sessionPath;
+
+  if (currentSessionPath && existsSync(currentSessionPath)) {
+    filePos = 0;
+    fileIno = statSync(currentSessionPath).ino;
+  }
+
+  // Cross-game session rotation: the runtime may create a new events.jsonl when a new
+  // game starts. If the caller provided a dynamic resolver, poll it and switch
+  // tail state to the new file. Without this, the stream would silently follow the
+  // previous game's file forever and look like a huge event delay.
+  const refreshSessionPath = (): void => {
+    if (!opts.getSessionPath) return;
+    const latest = opts.getSessionPath();
+    if (!latest || latest === currentSessionPath) return;
+    currentSessionPath = latest;
+    filePos = 0;
+    lineBuffer = '';
+    try { fileIno = existsSync(latest) ? statSync(latest).ino : 0; } catch { fileIno = 0; }
+  };
+
+  const drainNewEvents = (): GameEvent[] => {
+    if (!currentSessionPath || !existsSync(currentSessionPath)) return [];
+    let stat;
+    try { stat = statSync(currentSessionPath); } catch { return []; }
+    if (stat.ino !== fileIno || stat.size < filePos) {
+      filePos = 0; fileIno = stat.ino; lineBuffer = '';
+    }
+    if (stat.size <= filePos) return [];
+    let fd: number;
+    try { fd = openSync(currentSessionPath, 'r'); } catch { return []; }
+    const buf = Buffer.alloc(stat.size - filePos);
+    readSync(fd, buf, 0, buf.length, filePos);
+    closeSync(fd);
+    filePos = stat.size;
+    lineBuffer += buf.toString('utf8');
+    const lastNl = lineBuffer.lastIndexOf('\n');
+    if (lastNl < 0) return [];
+    const chunk = lineBuffer.slice(0, lastNl);
+    lineBuffer = lineBuffer.slice(lastNl + 1);
+    const events: GameEvent[] = [];
+    for (const line of chunk.split('\n')) {
+      if (!line) continue;
+      try {
+        const evt = JSON.parse(line);
+        if (!isLocalControlEvent(evt)) events.push(evt);
+        for (const nested of extractNewEvents(evt) as GameEvent[]) {
+          if (!isLocalControlEvent(nested)) events.push(nested);
+        }
+      } catch {}
+    }
+    return events;
+  };
+
+  // Pre-attach backlog: drain once, classify, hold for first emit.
+  const backlogEvents = drainNewEvents();
+  const skipSet = new Set(opts.skipBacklogTypes ?? []);
+  const backlogNotable = backlogEvents.filter((e) => {
+    if (e.type && skipSet.has(e.type as string)) return false;
+    return classifyEvent(e, youName).notable;
+  });
+  let caughtUpEvents: GameEvent[] = backlogNotable.slice(-20);
+  for (const e of backlogEvents) seenKeys.add(eventKey(e));
+
+  const buildOut = (
+    triggers: string[],
+    _nextStep: string,
+    events: GameEvent[] = [],
+  ): any => {
+    const rawSummary = opts.readSummary?.() ?? readFeedSummary(opts.feedPath);
+    const summary = compactSummaryForMonitor(rawSummary, triggers);
+    // Server pushes `meeting_briefing` without `speech_order` (that field only lives in
+    // meeting state, which the runtime projects onto the owner snapshot).
+    // Inject it onto the briefing event here so consumers can read it from events[]
+    // directly. Guarded by caller match so a stale speech_order from a previous
+    // meeting isn't ever attached.
+    const enrichMeetingBriefing = (e: GameEvent): GameEvent => {
+      if (e.type !== 'meeting_briefing') return e;
+      if (e.speech_order) return e;
+      const so = rawSummary?.meeting?.speech_order;
+      if (!Array.isArray(so)) return e;
+      const sumCaller = rawSummary?.meeting?.caller;
+      if (sumCaller && e.caller && sumCaller !== e.caller) return e;
+      return { ...e, speech_order: so };
+    };
+    const sourceEvents = events.length > 0
+      ? sortEventsForMonitor(events).map(enrichMeetingBriefing)
+      : triggers.map((type) => ({ type }));
+    const context = {
+      summary,
+      seats: readSeatMapForMonitor(currentSessionPath),
+      maxTextLength: 90,
+    };
+    return {
+      events: sourceEvents.map((event) => event.type),
+      messages: sourceEvents.map((event) => formatEventMessage(event, context)),
+      state: shortStateText(summary),
+    };
+  };
+
+  const fireTrigger = (
+    triggers: string[],
+    triggeredEvents: GameEvent[],
+  ): void => {
+    if (triggers.length === 0) return;
+    const { nextStep } = routeTriggers(triggers);
+    const out = buildOut(triggers, nextStep, triggeredEvents.slice(-10));
+    if (opts.hubReminder && triggers.includes('game_over')) {
+      out.hub_reminder = opts.hubReminder;
+    }
+    emit(out);
+  };
+
+  // Always emit an attached first beat when there is a pre-attach backlog OR
+  // the caller explicitly requests one.
+  if (caughtUpEvents.length > 0 || opts.emitGameStart) {
+    const hasBacklog = caughtUpEvents.length > 0;
+    const nextStep = opts.emitGameStart
+      ? hasBacklog
+        ? 'Game stream attached. Read summary and caught_up.notable_events for opening events; current strategy appears in summary.automation.strategy.'
+        : 'Game stream attached. Read summary and wait for role_assigned; current strategy appears in summary.automation.strategy.'
+      : 'Catch-up complete. Read summary, then continue play.';
+    const attachedEvents = hasBacklog ? caughtUpEvents : [{ type: 'game_start' }];
+    const attachedOut = buildOut(attachedEvents.map((event) => event.type), nextStep, attachedEvents);
+    caughtUpEvents = [];
+    emit(attachedOut);
+  }
+
+  // Delay buffer: merge rapid-fire wandering-phase events into one notification
+  let delayActive = false;
+  let delayDeadline = 0;
+  const delayBuffer: { triggers: Set<string>; events: GameEvent[] } = {
+    triggers: new Set(),
+    events: [],
+  };
+
+  while (!opts.signal?.aborted) {
+    refreshSessionPath();
+
+    const triggers: string[] = [];
+    const triggeredEvents: GameEvent[] = [];
+
+    const newEvents = drainNewEvents();
+    for (const evt of newEvents) {
+      const cls = classifyEvent(evt, youName);
+      if (!cls.notable) continue;
+      const key = eventKey(evt);
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+      triggeredEvents.push(evt);
+      if (evt.type && !triggers.includes(evt.type)) {
+        triggers.push(evt.type);
+      }
+    }
+
+    // ── Delay buffer: merge rapid-fire wandering-phase events ──
+    // Only active during wandering; meeting-phase events (my_turn, speech, etc.)
+    // are not in DELAYABLE_EVENT_CONFIG and won't start a delay.
+    if (delayActive) {
+      if (Date.now() < delayDeadline) {
+        // Still within delay window — buffer everything and wait
+        for (const t of triggers) delayBuffer.triggers.add(t);
+        for (const e of triggeredEvents) delayBuffer.events.push(e);
+        triggers.length = 0;
+        triggeredEvents.length = 0;
+      } else {
+        // Delay expired — flush buffer in front of current batch
+        for (const t of delayBuffer.triggers) {
+          if (!triggers.includes(t)) triggers.unshift(t);
+        }
+        triggeredEvents.unshift(...delayBuffer.events);
+        delayBuffer.triggers.clear();
+        delayBuffer.events.length = 0;
+        delayActive = false;
+      }
+    } else if (triggers.length > 0) {
+      // Check if any trigger is delayable; start a delay if so
+      let delayMs = 0;
+      for (const t of triggers) {
+        const ms = resolvedDelays[t];
+        if (ms !== undefined && ms > delayMs) delayMs = ms;
+      }
+      if (delayMs > 0) {
+        delayActive = true;
+        delayDeadline = Date.now() + delayMs;
+        for (const t of triggers) delayBuffer.triggers.add(t);
+        for (const e of triggeredEvents) delayBuffer.events.push(e);
+        triggers.length = 0;
+        triggeredEvents.length = 0;
+      }
+    }
+
+    if (triggers.length > 0) {
+      fireTrigger(triggers, triggeredEvents);
+      if (triggers.includes('game_over')) return;
+    } else if (!delayActive && heartbeatInterval > 0 && Date.now() - lastEmitMs >= heartbeatInterval) {
+      // Idle keepalive — prevents downstream adapters from interpreting a quiet
+      // wandering/transit period as a hung subprocess and killing it on their
+      // own default timeout (commonly 60s).
+      emit(buildOut(
+        ['heartbeat'],
+        'Stream is alive; no notable events. Continue waiting — no action required.',
+      ));
+    }
+
+    if (opts.signal?.aborted) break;
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}
+
+export interface SnapshotOnceOptions {
+  feedPath: string;
+  stdout: (line: string) => void;
+}
+
+export function snapshotOnce(opts: SnapshotOnceOptions): void {
+  if (!existsSync(opts.feedPath)) {
+    throw new Error('ccl game runtime is not running. Start it first with `ccl game start`.');
+  }
+  const summary = readFeedSummary(opts.feedPath);
+  opts.stdout(JSON.stringify({
+    events: ['snapshot'],
+    messages: [formatEventMessage({ type: 'snapshot' })],
+    state: shortStateText(summary),
+  }) + '\n');
+}
+
+export function buildErrorLine(err: any, opts?: { notReadyNextStep?: string }): string {
+  const msg = err?.message ?? String(err);
+  const notReady = err?.name === 'WatchNotReadyError' || /not ready|feed\.json/i.test(msg);
+  const reason = notReady ? 'not_ready' : 'error';
+  const event = {
+    type: reason,
+    message: notReady
+      ? (opts?.notReadyNextStep ?? 'Game runtime not running. Run `ccl game start` to begin a new session.')
+      : msg,
+  };
+  return JSON.stringify({
+    events: [reason],
+    messages: [formatEventMessage(event)],
+    state: 'state unavailable',
+    error: msg,
+  }) + '\n';
+}
+
+export function createWatchCommand(): Command {
+  const cmd = new Command('watch')
+    .description('Stream notable game events as NDJSON. Exits on game_over. For a one-shot snapshot use `ccl peek`.')
+    .action(async () => {
+      const store = new AuthStore();
+      const profile = store.getActive();
+      if (!profile) {
+        process.stdout.write(JSON.stringify({ exit_reason: ['not_logged_in'], error: 'Not logged in' }) + '\n');
+        return;
+      }
+      const stateDir = getProfileStateDir(profile);
+      const feedPath = join(stateDir, 'feed.json');
+      const sessionPath = EventStore.latestSessionPath();
+      const ctrl = new AbortController();
+      process.on('SIGINT', () => ctrl.abort());
+      process.on('SIGTERM', () => ctrl.abort());
+      let summaryCache: any | null = null;
+      let summaryPoll: ReturnType<typeof setInterval> | null = null;
+      try {
+        const snapshot = await sendOwnerControlRequest(stateDir, 'snapshot');
+        if (!snapshot?.ok) {
+          throw new WatchNotReadyError(
+            'Game runtime not ready (no active ccl game start owner). Run `ccl game start` to start or recover the game stream.',
+          );
+        }
+        summaryCache = snapshot.summary ?? null;
+        summaryPoll = setInterval(() => {
+          void sendOwnerControlRequest(stateDir, 'snapshot')
+            .then((response) => {
+              if (response?.ok) summaryCache = response.summary ?? null;
+            })
+            .catch(() => {});
+        }, 1000);
+        await runStreaming({
+          feedPath,
+          sessionPath,
+          getSessionPath: () => EventStore.latestSessionPath(),
+          stdout: (s) => process.stdout.write(s),
+          signal: ctrl.signal,
+          skipFeedWait: true,
+          readSummary: () => summaryCache,
+          hubReminder: hubReminder(readCachedGamesPlayed()),
+        });
+      } catch (err: any) {
+        process.stdout.write(buildErrorLine(err, {
+          notReadyNextStep: 'Run `ccl game start` to start or recover the game stream.',
+        }));
+        process.exit(1);
+      } finally {
+        if (summaryPoll) clearInterval(summaryPoll);
+      }
+    });
+  // ── Adapter metadata: streaming mode blocks until game_over; cap at 30min for stuck-process safety ──
+  setMeta(cmd, { longRunning: true, timeoutMs: 1_800_000 });
+  return cmd;
+}