@myclaw163/clawclaw-cli 0.6.54

package/src/commands/game.ts

@@ -0,0 +1,882 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { AuthStore } from '../lib/auth.js';
+import { ApiError, GameClient } from '../lib/game-client.js';
+import { getProfileStateDir } from '../lib/init-command.js';
+import { spawnDaemon, getRunningDaemonPid, waitDaemonExit } from '../runtime/daemon.js';
+import { EventStore } from '../pipeline/event-store.js';
+import { spawnOpeningMover, stopOpeningMoverIfRunning } from '../runtime/opening-mover.js';
+import { spawnStrategyLoop } from '../strategies/spawn.js';
+import { setMeta } from '../lib/command-meta.js';
+import { runStreaming, buildErrorLine, readFeedSummary, nextStepFor } from './watch.js';
+import { hubReminder, readCachedGamesPlayed } from '../lib/hub-reminder.js';
+import {
+  startMatch,
+  endMatch,
+  readMatchState,
+  shouldEmitWaiting,
+  markWaitingEmitted,
+  getWaitedSecs,
+  hasMatchTimedOut,
+} from '../lib/match-state.js';
+
+function writeControl(stateDir: string, command: 'stop'): void {
+  writeFileSync(join(stateDir, 'control.json'), JSON.stringify({ command }));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+function positiveNumber(value: string, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function queueStatus(result: any): string | undefined {
+  return (result?.data ?? result)?.status;
+}
+
+const DEFAULT_QUEUE_WAIT_TIMEOUT_SECS = 30;
+const GAME_START_RUNTIME_FILE = 'game-start.json';
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function gameStartRuntimePath(stateDir: string): string {
+  return join(stateDir, GAME_START_RUNTIME_FILE);
+}
+
+function getRunningGameStartPid(stateDir: string): number | null {
+  const runtimePath = gameStartRuntimePath(stateDir);
+  if (!existsSync(runtimePath)) return null;
+  try {
+    const info = JSON.parse(readFileSync(runtimePath, 'utf8'));
+    const pid = Number(info?.pid);
+    if (isPidAlive(pid)) return pid;
+  } catch {}
+  try { unlinkSync(runtimePath); } catch {}
+  return null;
+}
+
+function writeGameStartRuntime(stateDir: string, mode: GameStartPlanKind): void {
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(gameStartRuntimePath(stateDir), JSON.stringify({
+    pid: process.pid,
+    started_at: new Date().toISOString(),
+    mode,
+  }));
+}
+
+function cleanupGameStartRuntime(stateDir: string): void {
+  const runtimePath = gameStartRuntimePath(stateDir);
+  try {
+    const info = JSON.parse(readFileSync(runtimePath, 'utf8'));
+    if (Number(info?.pid) !== process.pid) return;
+  } catch {}
+  try { unlinkSync(runtimePath); } catch {}
+}
+
+type QueueStatus = 'allocated' | 'queued' | 'not_in_queue' | string | undefined;
+
+export type GameStartPlan =
+  | { kind: 'already_running'; pid: number }
+  | { kind: 'attach_daemon' }
+  | { kind: 'resume_queue' }
+  | { kind: 'resume_allocated' }
+  | { kind: 'fresh_start' };
+
+type GameStartPlanKind = GameStartPlan['kind'];
+
+export function planGameStartAction(input: {
+  gameStartPid?: number | null;
+  daemonPid?: number | null;
+  hasMatchState: boolean;
+  queueStatus?: QueueStatus;
+  feedPhase?: string | null;
+}): GameStartPlan {
+  if (input.gameStartPid) return { kind: 'already_running', pid: input.gameStartPid };
+
+  if (input.daemonPid) {
+    if (input.hasMatchState || input.feedPhase === 'matching') return { kind: 'resume_queue' };
+    if (input.feedPhase === 'lobby') return { kind: 'fresh_start' };
+    return { kind: 'attach_daemon' };
+  }
+
+  if (input.queueStatus === 'allocated') return { kind: 'resume_allocated' };
+  if (input.queueStatus === 'queued' || input.queueStatus === 'already_in_queue') return { kind: 'resume_queue' };
+  return { kind: 'fresh_start' };
+}
+
+function isAlreadyInGameError(err: unknown): boolean {
+  return err instanceof ApiError && err.body.includes('ALREADY_IN_GAME');
+}
+
+function ensureEventSession(source: string): EventStore {
+  const existing = EventStore.latestSessionPath();
+  if (existing) {
+    const events = EventStore.forActiveAccount();
+    events.append({ type: 'session_resumed', source });
+    return events;
+  }
+  const events = EventStore.createSessionForActiveAccount();
+  events.append({ type: 'session_started', source });
+  return events;
+}
+
+function readFeedPhase(feedPath: string): string | null {
+  try {
+    const phase = JSON.parse(readFileSync(feedPath, 'utf8'))?.phase;
+    return typeof phase === 'string' ? phase : null;
+  } catch {
+    return null;
+  }
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function unwrapData(value: any): any {
+  return value?.data ?? value;
+}
+
+export interface GameStrategyIdentity {
+  gameId?: string;
+  role?: string;
+  alive: boolean | null;
+}
+
+export interface StrategyRuntimeInfo {
+  strategy?: string;
+  pid?: number;
+  source?: string;
+  gameId?: string;
+  role?: string;
+  running: boolean;
+}
+
+export function gameStrategyIdentity(stateData: any, roleData: any): GameStrategyIdentity {
+  const state = unwrapData(stateData);
+  const role = unwrapData(roleData);
+  const you = state?.you ?? {};
+  const aliveRaw = you?.is_alive ?? you?.alive;
+  return {
+    gameId: nonEmptyString(state?.game_id) ?? nonEmptyString(state?.game?.id) ?? nonEmptyString(state?.game?.game_id),
+    role: nonEmptyString(role?.role) ?? nonEmptyString(you?.role),
+    alive: typeof aliveRaw === 'boolean' ? aliveRaw : null,
+  };
+}
+
+export function strategyRuntimeMatchesIdentity(
+  runtime: StrategyRuntimeInfo | null,
+  identity: GameStrategyIdentity,
+): boolean {
+  if (!runtime?.running) return false;
+  if (!runtime.gameId || !identity.gameId || runtime.gameId !== identity.gameId) return false;
+  if (runtime.role && identity.role && runtime.role !== identity.role) return false;
+  return true;
+}
+
+function readStrategyRuntimeInfo(stateDir: string): StrategyRuntimeInfo | null {
+  try {
+    const raw = JSON.parse(readFileSync(join(stateDir, 'auto.json'), 'utf8'));
+    const pid = Number(raw?.pid);
+    return {
+      strategy: nonEmptyString(raw?.strategy),
+      pid: Number.isFinite(pid) ? pid : undefined,
+      source: nonEmptyString(raw?.source),
+      gameId: nonEmptyString(raw?.game_id) ?? nonEmptyString(raw?.gameId),
+      role: nonEmptyString(raw?.role),
+      running: Number.isFinite(pid) && pid > 0 ? isPidAlive(pid) : false,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function commandError(command: string, err: unknown): { command: string; error: string } {
+  const message = err instanceof ApiError
+    ? `${err.status}: ${err.body}`
+    : err instanceof Error
+      ? err.message
+      : String(err);
+  return { command, error: message };
+}
+
+function briefMap(mapData: any): any {
+  if (!mapData) return null;
+  return {
+    rooms: mapData.rooms?.map((r: any) => ({
+      name: r.name,
+      polygon: r.polygon,
+    })),
+  };
+}
+
+function taskLocations(mapData: any): { lobster: any[]; crab: any[] } {
+  const taskLocations = { lobster: [] as any[], crab: [] as any[] };
+  for (const task of Array.isArray(mapData?.all_task_locations) ? mapData.all_task_locations : []) {
+    const item = {
+      name: task.name,
+      room: task.room,
+      x: task.x,
+      y: task.y,
+    };
+    if (task.faction === 'crab') taskLocations.crab.push(item);
+    else taskLocations.lobster.push(item);
+  }
+  return taskLocations;
+}
+
+function loadAsciiMapAsset(): string | null {
+  try {
+    return readFileSync(new URL('../assets/clawclaw-ascii-map.txt', import.meta.url), 'utf8').trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+export function summarizeGameMap(mapData: any, opts?: { ascii?: boolean }): any {
+  const output: Record<string, any> = {
+    rooms: mapData?.rooms?.map((r: any) => ({
+      name: r.name,
+      polygon: r.polygon,
+    })) ?? [],
+    task_locations: taskLocations(mapData),
+  };
+  if (opts?.ascii) {
+    const ascii = loadAsciiMapAsset();
+    output.ascii_map = ascii;
+  }
+  return output;
+}
+
+async function fetchInitialGameContext(client: GameClient): Promise<{
+  state: any | null;
+  role: any | null;
+  map: any | null;
+  tasks: any[] | null;
+  errors?: Array<{ command: string; error: string }>;
+}> {
+  await sleep(500);
+  const [stateResult, roleResult, mapResult] = await Promise.allSettled([
+    client.getGameState(),
+    client.getRoleInfo(),
+    client.getMap(),
+  ]);
+
+  const errors: Array<{ command: string; error: string }> = [];
+  if (stateResult.status === 'rejected') errors.push(commandError('state', stateResult.reason));
+  if (roleResult.status === 'rejected') errors.push(commandError('game role', roleResult.reason));
+  if (mapResult.status === 'rejected') errors.push(commandError('game map', mapResult.reason));
+
+  const mapData = mapResult.status === 'fulfilled' ? mapResult.value : null;
+  const context = {
+    state: stateResult.status === 'fulfilled' ? stateResult.value : null,
+    role: roleResult.status === 'fulfilled' ? roleResult.value : null,
+    map: briefMap(mapData),
+    tasks: mapData?.your_tasks ?? null,
+    ...(errors.length ? { errors } : {}),
+  };
+  return context;
+}
+
+const ROLE_DEFAULT_STRATEGY: Record<string, string> = {
+  'shrimp_generic': 'task-report',
+  'shrimp_warrior': 'task-report',
+  'shrimp_pistol': 'task-report',
+  'crab_generic': 'crab-sabotage',
+  'neutral_paradise_fish': 'corpse-patrol',
+  'neutral_octopus': 'lone-kill-task',
+};
+
+function autoStartStrategy(roleData: any, stateData?: any, gameId?: string): { strategy: string; pid: number | undefined } | null {
+  const roleId: string | undefined = roleData?.data?.role ?? roleData?.role;
+  if (!roleId) return null;
+  const strategyId = ROLE_DEFAULT_STRATEGY[roleId];
+  if (!strategyId) return null;
+  const child = spawnStrategyLoop(strategyId, [roleId], {
+    source: 'auto_start',
+    gameId: gameId ?? gameStrategyIdentity(stateData, roleData).gameId,
+    role: roleId,
+  });
+  return { strategy: strategyId, pid: child.pid };
+}
+
+async function runGameStart(opts: { watch: boolean; force?: boolean }): Promise<void> {
+  if (process.env.CLAWCLAW_REQUIRE_STREAM_TOOL === '1' && process.env.CLAWCLAW_STREAMED !== '1') {
+    process.stderr.write(
+      'In OpenClaw, start the game via the clawclaw_game_start tool - do not exec `ccl game start` directly.\n' +
+      'When run raw, the event NDJSON only fills an unconsumed buffer, so you never receive speech_your_turn and stay silent.\n',
+    );
+    process.exit(2);
+  }
+
+  const authStore = new AuthStore();
+  const profile = authStore.getActive();
+  if (!profile) throw new Error('Not logged in.');
+
+  const stateDir = getProfileStateDir(profile);
+  const feedPath = join(stateDir, 'feed.json');
+  const client = GameClient.fromAuth();
+  const emit = (obj: Record<string, any>): void => {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+  };
+  const emitLifecycle = (
+    reason: string,
+    payload: Record<string, any>,
+    nextStepOverride?: string,
+  ): void => {
+    const event = { ...payload, type: reason };
+    emit({
+      exit_reason: [reason],
+      next_step: nextStepOverride ?? nextStepFor(reason),
+      events: [event],
+      summary: readFeedSummary(feedPath),
+    });
+  };
+  const emitMatchEvent = (evt: Record<string, any>): void => {
+    try {
+      const store = EventStore.forActiveAccount();
+      store.append({ ts: new Date().toISOString(), ...evt });
+    } catch {}
+  };
+  const ensureDaemonRunning = (): void => {
+    if (getRunningDaemonPid(stateDir)) return;
+    try {
+      spawnDaemon();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!msg.includes('Daemon already running')) throw err;
+    }
+  };
+  const streamGame = async (): Promise<void> => {
+    const sessionPath = EventStore.latestSessionPath();
+    const ctrl = new AbortController();
+    const onSignal = (): void => ctrl.abort();
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    try {
+      await runStreaming({
+        feedPath,
+        sessionPath,
+        getSessionPath: () => EventStore.latestSessionPath(),
+        stdout: (s) => process.stdout.write(s),
+        signal: ctrl.signal,
+        skipBacklogTypes: ['match_waiting', 'match_timeout'],
+        emitGameStart: true,
+        hubReminder: hubReminder(readCachedGamesPlayed()),
+      });
+    } catch (err: any) {
+      process.stdout.write(buildErrorLine(err));
+      process.exitCode = 1;
+    } finally {
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+    }
+  };
+  const handleAllocated = async (queue: any, preserveStrategy: boolean): Promise<void> => {
+    const finalState = readMatchState(stateDir);
+    const waitedSecs = finalState ? getWaitedSecs(finalState) : 0;
+    endMatch(stateDir);
+    const context = await fetchInitialGameContext(client);
+    const identity = gameStrategyIdentity(context.state, context.role);
+    // Supplement game_id from queue response when /game/current doesn't carry it yet.
+    const queueGameId = nonEmptyString(queue?.game_id) ?? nonEmptyString(queue?.data?.game_id);
+    if (!identity.gameId && queueGameId) {
+      identity.gameId = queueGameId;
+    }
+    let strategyInfo: { strategy: string; pid: number | undefined } | null = null;
+    if (identity.alive !== false) {
+      if (preserveStrategy) {
+        const { isStrategyRunning, stopStrategyIfRunning } = await import('../strategies/strategy-loop.js');
+        if (isStrategyRunning()) {
+          const runtime = readStrategyRuntimeInfo(stateDir);
+          if (identity.gameId && !strategyRuntimeMatchesIdentity(runtime, identity)) {
+            stopStrategyIfRunning();
+            strategyInfo = autoStartStrategy(context.role, context.state, identity.gameId);
+          }
+        } else {
+          strategyInfo = autoStartStrategy(context.role, context.state, identity.gameId);
+        }
+      } else {
+        strategyInfo = autoStartStrategy(context.role, context.state, identity.gameId);
+      }
+    }
+    const allocationPayload = {
+      queue,
+      waited_secs: waitedSecs,
+      game_id: identity.gameId || undefined,
+      ...context,
+      ...(strategyInfo ? { default_strategy: strategyInfo } : {}),
+    };
+    if (!opts.watch) {
+      emitLifecycle('allocated', allocationPayload,
+        'Match secured. Read role/map/tasks from `events[0]`. Default strategy is active when `default_strategy` is present or summary.automation shows one. Move into Preparing phase.');
+      return;
+    }
+    await streamGame();
+  };
+  const pollQueue = async (preserveStrategy: boolean): Promise<void> => {
+    const intervalMs = 2000;
+    const QUEUE_POLL_HEARTBEAT_MS = 60_000;
+    const MAX_CONSECUTIVE_FAILURES = 3;
+    let lastHeartbeat = Date.now();
+    let consecutiveFailures = 0;
+
+    while (true) {
+      let queue: any;
+      try {
+        queue = await client.getQueueStatus('clawclaw');
+        consecutiveFailures = 0;
+      } catch (err: any) {
+        consecutiveFailures++;
+        const msg = err?.message ?? String(err);
+        if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+          emitLifecycle('error', {
+            error: msg,
+            consecutive_failures: consecutiveFailures,
+            message: `Queue status polling failed ${consecutiveFailures} times consecutively.`,
+          }, 'Queue polling has failed repeatedly. Check network, then launch a fresh `ccl game start` to retry.');
+          return;
+        }
+        emitLifecycle('poll_error', {
+          error: msg,
+          consecutive_failures: consecutiveFailures,
+          message: `Queue poll failed (${consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES}). Retrying...`,
+        }, 'Temporary polling failure. The stream will keep retrying - stay attached.');
+        await sleep(intervalMs);
+        continue;
+      }
+
+      if (queueStatus(queue) === 'allocated') {
+        await handleAllocated(queue, preserveStrategy);
+        return;
+      }
+      if (queueStatus(queue) === 'not_in_queue') {
+        endMatch(stateDir);
+        emitLifecycle('not_in_queue', { queue, message: 'Left or dropped from queue.' },
+          'No longer in matchmaking queue. The stream will exit; launch a fresh `ccl game start` to retry if the user wants to continue.');
+        return;
+      }
+
+      const cur = readMatchState(stateDir);
+      if (cur && shouldEmitWaiting(cur)) {
+        const waitedSecs = getWaitedSecs(cur);
+        emitMatchEvent({ type: 'match_waiting', waited_secs: waitedSecs });
+        emitLifecycle('match_waiting', { waited_secs: waitedSecs });
+        markWaitingEmitted(stateDir);
+        lastHeartbeat = Date.now();
+      }
+      if (cur && hasMatchTimedOut(cur)) {
+        const waitedSecs = getWaitedSecs(cur);
+        emitMatchEvent({ type: 'match_timeout', waited_secs: waitedSecs });
+        emitLifecycle('match_timeout', {
+          waited_secs: waitedSecs,
+          queue,
+          message: `No match after ${waitedSecs}s.`,
+        });
+        return;
+      }
+
+      if (Date.now() - lastHeartbeat >= QUEUE_POLL_HEARTBEAT_MS) {
+        lastHeartbeat = Date.now();
+        const waitedSecs = cur ? getWaitedSecs(cur) : 0;
+        emitLifecycle('heartbeat', { waited_secs: waitedSecs },
+          'Stream is alive; still waiting for match allocation. Keep chatting with the user.');
+      }
+
+      await sleep(intervalMs);
+    }
+  };
+  const resumeQueue = async (source: string): Promise<void> => {
+    ensureEventSession(source);
+    if (!readMatchState(stateDir)) startMatch(stateDir);
+    ensureDaemonRunning();
+    spawnOpeningMover();
+    await pollQueue(true);
+  };
+  const recoverAlreadyInGame = async (): Promise<boolean> => {
+    let queue: any;
+    try {
+      queue = await client.getQueueStatus('clawclaw');
+    } catch {
+      return false;
+    }
+    const status = queueStatus(queue);
+    if (status === 'allocated') {
+      ensureEventSession('game_start_already_in_game');
+      ensureDaemonRunning();
+      spawnOpeningMover();
+      await handleAllocated(queue, true);
+      return true;
+    }
+    if (status === 'queued' || status === 'already_in_queue') {
+      await resumeQueue('game_start_already_in_game_queue');
+      return true;
+    }
+    return false;
+  };
+
+  const runningGameStartPid = getRunningGameStartPid(stateDir);
+  if (runningGameStartPid) {
+    if (opts.force) {
+      try { process.kill(runningGameStartPid, 'SIGKILL'); } catch {}
+      try { unlinkSync(gameStartRuntimePath(stateDir)); } catch {}
+    } else {
+      emitLifecycle('already_running', { pid: runningGameStartPid },
+        `A ccl game start stream is already running (pid ${runningGameStartPid}). To replace it, re-run with --force or stop it manually: taskkill /F /PID ${runningGameStartPid}`);
+      return;
+    }
+  }
+
+  let initialQueue: any;
+  try {
+    initialQueue = await client.getQueueStatus('clawclaw');
+  } catch {}
+  const plan = planGameStartAction({
+    gameStartPid: null,
+    daemonPid: getRunningDaemonPid(stateDir),
+    hasMatchState: readMatchState(stateDir) !== null,
+    queueStatus: queueStatus(initialQueue),
+    feedPhase: readFeedPhase(feedPath),
+  });
+
+  writeGameStartRuntime(stateDir, plan.kind);
+  try {
+    if (plan.kind === 'attach_daemon') {
+      ensureEventSession('game_start_attach_daemon');
+      if (!opts.watch) {
+        emitLifecycle('game_start', { mode: plan.kind },
+          'Game stream is active. Read summary; no additional events will follow from this --no-watch invocation.');
+        return;
+      }
+      await streamGame();
+      return;
+    }
+
+    if (plan.kind === 'resume_queue') {
+      await resumeQueue('game_start_resume_queue');
+      return;
+    }
+
+    if (plan.kind === 'resume_allocated') {
+      ensureEventSession('game_start_resume_allocated');
+      ensureDaemonRunning();
+      spawnOpeningMover();
+      await handleAllocated(initialQueue, true);
+      return;
+    }
+
+    let joinResult: any;
+    try {
+      joinResult = await client.joinQueue('clawclaw');
+    } catch (err) {
+      if (isAlreadyInGameError(err) && await recoverAlreadyInGame()) return;
+      throw err;
+    }
+    const joinedStatus = queueStatus(joinResult);
+    if (joinedStatus === 'already_in_queue') {
+      await resumeQueue('game_start_already_in_queue');
+      return;
+    }
+    if (joinedStatus && joinedStatus !== 'queued') {
+      emitLifecycle('error', { queue: joinResult, message: `Unexpected queue status: ${joinedStatus}.` },
+        'Queue join did not enter the clawclaw queue. Check queue status before launching another `ccl game start`.');
+      return;
+    }
+
+    const { stopStrategyIfRunning } = await import('../strategies/strategy-loop.js');
+    stopStrategyIfRunning();
+    stopOpeningMoverIfRunning();
+
+    const events = EventStore.createSessionForActiveAccount();
+    events.append({ type: 'session_started', source: 'game_start' });
+    emitLifecycle('joined', joinResult,
+      'Match join request acknowledged. Spectate URL is in `events[0].url`; share it with the user. Daemon spawns next.');
+    startMatch(stateDir);
+    if (getRunningDaemonPid(stateDir)) {
+      writeControl(stateDir, 'stop');
+      await waitDaemonExit(stateDir);
+    }
+    spawnDaemon();
+    spawnOpeningMover();
+    await pollQueue(false);
+  } finally {
+    cleanupGameStartRuntime(stateDir);
+  }
+}
+
+export function createGameCommand(): Command {
+  const game = new Command('game');
+  game.description('Game matchmaking & session');
+
+  game
+    .command('join')
+    .alias('j')
+    .description('Join matchmaking queue')
+    .action(async () => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const { stopStrategyIfRunning } = await import('../strategies/strategy-loop.js');
+      stopStrategyIfRunning();
+      stopOpeningMoverIfRunning();
+
+      const client = GameClient.fromAuth();
+      const result = await client.joinQueue('clawclaw');
+      const events = EventStore.createSessionForActiveAccount();
+      events.append({ type: 'session_started', source: 'game_join' });
+      console.log(JSON.stringify(result, null, 2));
+      const stateDir = getProfileStateDir(profile);
+      // Reset match-state: a fresh queue session starts here so `ccl game queue`
+      // can compute `waited_secs` from a known anchor and emit the
+      // match_waiting / match_timeout synthetic events.
+      startMatch(stateDir);
+      if (getRunningDaemonPid(stateDir)) {
+        writeControl(stateDir, 'stop');
+        await waitDaemonExit(stateDir);
+      }
+      const { pid } = spawnDaemon();
+      console.log(JSON.stringify({ message: 'Event daemon started', pid }, null, 2));
+      spawnOpeningMover();
+    });
+
+  game
+    .command('start')
+    .alias('s')
+    .description('Attach to an active game stream or join queue, then stream events as NDJSON until game_over. Pass --no-watch to exit after allocation. Pass --force to replace an orphaned game-start stream.')
+    .option('--no-watch', 'exit after allocation instead of streaming events through game_over')
+    .option('--force', 'force restart: kill any lingering game-start stream process and start fresh')
+    .action(runGameStart);
+
+  game
+    .command('queue')
+    .alias('q')
+    .description('Wait for matchmaking allocation. Always run as a background bash task (run_in_background: true) — never block on it. Returns when allocated, queue is missing, or timeout (default 30s).')
+    .option('-w, --wait', '(no-op, kept for backwards compatibility — wait mode is now the default)')
+    .option('--interval <secs>', 'Polling interval', '2')
+    .option('--timeout <secs>', 'Max seconds to wait, 0 means forever', String(DEFAULT_QUEUE_WAIT_TIMEOUT_SECS))
+    .action(async (opts) => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const stateDir = getProfileStateDir(profile);
+      const client = GameClient.fromAuth();
+
+      const intervalMs = positiveNumber(opts.interval, 2) * 1000;
+      const timeoutSecs = Number(opts.timeout);
+      const deadline = Number.isFinite(timeoutSecs) && timeoutSecs > 0
+        ? Date.now() + timeoutSecs * 1000
+        : 0;
+
+      // Synthetic matchmaking events feed the game start stream so the agent can
+      // observe match progress through the same channel as in-game events.
+      // Concurrency note: the agent typically keeps a 30s `ccl game queue`
+      // background chain running, so two queue invocations may observe the
+      // same `allocated` server state. That is
+      // intentionally fine — stream dedups via `eventKey` (type+tick+actor),
+      // so consumers only see one notification.
+      const emitMatchEvent = (evt: Record<string, any>): void => {
+        try {
+          const store = EventStore.forActiveAccount();
+          store.append({ ts: new Date().toISOString(), ...evt });
+        } catch {
+          // No active session (user ran queue without join) — skip silently;
+          // queue's own JSON return still informs the caller.
+        }
+      };
+
+      // On entry: emit match_waiting if state exists and heartbeat is due.
+      const initialState = readMatchState(stateDir);
+      if (initialState && shouldEmitWaiting(initialState)) {
+        const waitedSecs = getWaitedSecs(initialState);
+        emitMatchEvent({ type: 'match_waiting', waited_secs: waitedSecs });
+        markWaitingEmitted(stateDir);
+      }
+
+      while (true) {
+        const queue = await client.getQueueStatus('clawclaw');
+        if (queueStatus(queue) === 'allocated') {
+          const finalState = readMatchState(stateDir);
+          const waitedSecs = finalState ? getWaitedSecs(finalState) : 0;
+          endMatch(stateDir);
+          const context = await fetchInitialGameContext(client);
+          console.log(JSON.stringify({
+            status: 'active_game',
+            queue,
+            waited_secs: waitedSecs,
+            ...context,
+            next_step: 'Game allocated. Stop the queue loop. The game start stream (already running since `game join`) will surface subsequent gameplay events. Narrate the role / map / opening plan to the user.',
+          }, null, 2));
+          return;
+        }
+        if (queueStatus(queue) === 'not_in_queue') {
+          // Queue session is gone (user manually left or server expired it):
+          // clean the match-state so next `game join` starts fresh.
+          endMatch(stateDir);
+          console.log(JSON.stringify({
+            status: 'not_in_queue',
+            queue,
+            message: 'You are not in the matchmaking queue. Did you forget to run `ccl game join` first?',
+            next_step: 'Run `ccl game join` to re-enter the queue, then launch the next `ccl game queue` background task.',
+          }, null, 2));
+          return;
+        }
+        if (deadline > 0 && Date.now() >= deadline) {
+          const cur = readMatchState(stateDir);
+          const waitedSecs = cur ? getWaitedSecs(cur) : timeoutSecs;
+          // Total-wait timeout (>=10 min by default) gets its own synthetic
+          // event so the agent can prompt the user to keep waiting / leave /
+          // retry later. Single 30s queue-attempt timeouts do NOT emit anything
+          // — they are an internal polling boundary, not a user-visible event.
+          if (cur && hasMatchTimedOut(cur)) {
+            emitMatchEvent({ type: 'match_timeout', waited_secs: waitedSecs });
+          }
+          console.log(JSON.stringify({
+            status: 'timeout',
+            waited_secs: waitedSecs,
+            queue,
+            message: `No match after ${timeoutSecs} seconds (total wait ${waitedSecs}s).`,
+            next_step: 'ZERO-GAP PROTOCOL: (1) Launch the next `ccl game queue` background task IMMEDIATELY. (2) While it runs, chat with the user — share strategy, persona, banter — never go silent.',
+          }, null, 2));
+          return;
+        }
+        await sleep(intervalMs);
+      }
+    });
+
+  game
+    .command('leave')
+    .alias('l')
+    .description('Leave queue')
+    .action(async () => {
+      stopOpeningMoverIfRunning();
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (profile) {
+        const stateDir = getProfileStateDir(profile);
+        endMatch(stateDir);
+        if (getRunningDaemonPid(stateDir)) {
+          writeControl(stateDir, 'stop');
+          await waitDaemonExit(stateDir);
+        }
+      }
+      const { stopStrategyIfRunning } = await import('../strategies/strategy-loop.js');
+      stopStrategyIfRunning();
+      const client = GameClient.fromAuth();
+      const result = await client.leaveQueue('clawclaw');
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+
+  game
+    .command('stop')
+    .alias('x')
+    .description('Stop event daemon')
+    .action(async () => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const stateDir = getProfileStateDir(profile);
+      const pid = getRunningDaemonPid(stateDir);
+      stopOpeningMoverIfRunning();
+      if (!pid) {
+        console.log(JSON.stringify({ message: 'No daemon running.' }, null, 2));
+        return;
+      }
+      writeControl(stateDir, 'stop');
+      await waitDaemonExit(stateDir);
+      console.log(JSON.stringify({ message: 'Daemon stopped.' }, null, 2));
+    });
+
+  game
+    .command('quit')
+    .description('Leave active game and stop daemon')
+    .action(async () => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const client = GameClient.fromAuth();
+      let result: any;
+      try {
+        result = await client.leaveGame();
+      } catch (err: any) {
+        throw new Error(err?.message ?? String(err));
+      }
+      const stateDir = getProfileStateDir(profile);
+      endMatch(stateDir);
+      if (getRunningDaemonPid(stateDir)) {
+        writeControl(stateDir, 'stop');
+        await waitDaemonExit(stateDir);
+      }
+      stopOpeningMoverIfRunning();
+      const { stopStrategyIfRunning } = await import('../strategies/strategy-loop.js');
+      stopStrategyIfRunning();
+      const reminder = hubReminder(readCachedGamesPlayed());
+      const out: Record<string, any> = (result && typeof result === 'object' && !Array.isArray(result))
+        ? { ...result }
+        : { result };
+      if (reminder) {
+        out.hub_reminder = reminder;
+        out.next_step = `Left the game. ${reminder}`;
+      }
+      console.log(JSON.stringify(out, null, 2));
+    });
+
+  game
+    .command('map')
+    .alias('m')
+    .description('Show game map')
+    .option('--ascii', 'Include packaged ASCII topology map')
+    .action(async (opts) => {
+      const client = GameClient.fromAuth();
+      await client.discoverGameServer();
+      const result = await client.getMap();
+      console.log(JSON.stringify(summarizeGameMap(result, { ascii: opts.ascii === true }), null, 2));
+    });
+
+  game
+    .command('tasks')
+    .alias('t')
+    .description('Show my tasks')
+    .action(async () => {
+      const client = GameClient.fromAuth();
+      await client.discoverGameServer();
+      const result = await client.getMap();
+      console.log(JSON.stringify(result?.your_tasks ?? [], null, 2));
+    });
+
+  game
+    .command('role')
+    .alias('r')
+    .description('Show my role info')
+    .action(async () => {
+      const client = GameClient.fromAuth();
+      const result = await client.getRoleInfo();
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+  game
+    .command('watch')
+    .alias('w')
+    .description('Get spectating URL')
+    .action(() => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const origin = new URL(profile.serverUrl).origin.replace(/^http:\/\//, 'https://');
+      const url = `${origin}/lobby?token=${encodeURIComponent(profile.apiKey)}`;
+      console.log(JSON.stringify({ url, message: 'Open in browser to spectate.' }, null, 2));
+    });
+
+  // ── Adapter metadata: queue blocks up to --timeout secs (default 30); cap L2 spawn at 60s ──
+  setMeta(game.commands.find((c) => c.name() === 'queue')!, { longRunning: true, timeoutMs: 60_000 });
+  setMeta(game.commands.find((c) => c.name() === 'start')!, { longRunning: true, timeoutMs: 1_800_000 });
+
+  return game;
+}