@myclaw163/clawclaw-cli 0.6.71 → 0.6.74

package/src/lib/load-context.test.ts

@@ -1,52 +1,52 @@
-import { describe, expect, it, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import { AuthStore, type AuthData } from './auth.js';
-import { CLAWCLAW_WORKSPACE_DIR } from './init-command.js';
-import { loadContext } from './load-context.js';
-
-describe('loadContext', () => {
-  let dir: string;
-  let authFile: string;
-  let prevWorkspace: string | undefined;
-
-  beforeEach(() => {
-    prevWorkspace = process.env[CLAWCLAW_WORKSPACE_DIR];
-    dir = mkdtempSync(join(tmpdir(), 'clawclaw-load-'));
-    process.env[CLAWCLAW_WORKSPACE_DIR] = dir;
-    authFile = join(dir, '.auth.json');
-    const auth: AuthData = {
-      activeProfile: 'lobster-1',
-      profiles: {
-        'lobster-1': {
-          agentName: 'lobster-1',
-          apiKey: 'claw_test_key_12345678',
-          serverUrl: 'https://example.com',
-        },
-      },
-    };
-    writeFileSync(authFile, JSON.stringify(auth));
-    const accountDir = join(dir, 'accounts', 'claw_test_key_12345678');
-    mkdirSync(accountDir, { recursive: true });
-    writeFileSync(join(accountDir, 'persona.md'), 'voice');
-    writeFileSync(join(accountDir, 'memory.md'), 'notes');
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-    if (prevWorkspace === undefined) delete process.env[CLAWCLAW_WORKSPACE_DIR];
-    else process.env[CLAWCLAW_WORKSPACE_DIR] = prevWorkspace;
-  });
-
-  it('returns persona and memory snapshots for the active account', () => {
-    const store = new AuthStore(authFile);
-    const snapshot = loadContext(store);
-    expect(snapshot.persona.content).toBe('voice');
-    expect(snapshot.persona.exists).toBe(true);
-    expect(snapshot.memory.content).toBe('notes');
-    expect(snapshot.memory.exists).toBe(true);
-    expect(snapshot.persona.path).toContain('persona.md');
-    expect(snapshot.memory.path).toContain('memory.md');
-  });
-});
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { AuthStore, type AuthData } from './auth.js';
+import { CLAWCLAW_WORKSPACE_DIR } from './init-command.js';
+import { loadContext } from './load-context.js';
+
+describe('loadContext', () => {
+  let dir: string;
+  let authFile: string;
+  let prevWorkspace: string | undefined;
+
+  beforeEach(() => {
+    prevWorkspace = process.env[CLAWCLAW_WORKSPACE_DIR];
+    dir = mkdtempSync(join(tmpdir(), 'clawclaw-load-'));
+    process.env[CLAWCLAW_WORKSPACE_DIR] = dir;
+    authFile = join(dir, '.auth.json');
+    const auth: AuthData = {
+      activeProfile: 'lobster-1',
+      profiles: {
+        'lobster-1': {
+          agentName: 'lobster-1',
+          apiKey: 'claw_test_key_12345678',
+          serverUrl: 'https://example.com',
+        },
+      },
+    };
+    writeFileSync(authFile, JSON.stringify(auth));
+    const accountDir = join(dir, 'accounts', 'claw_test_key_12345678');
+    mkdirSync(accountDir, { recursive: true });
+    writeFileSync(join(accountDir, 'persona.md'), 'voice');
+    writeFileSync(join(accountDir, 'memory.md'), 'notes');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    if (prevWorkspace === undefined) delete process.env[CLAWCLAW_WORKSPACE_DIR];
+    else process.env[CLAWCLAW_WORKSPACE_DIR] = prevWorkspace;
+  });
+
+  it('returns persona and memory snapshots for the active account', () => {
+    const store = new AuthStore(authFile);
+    const snapshot = loadContext(store);
+    expect(snapshot.persona.content).toBe('voice');
+    expect(snapshot.persona.exists).toBe(true);
+    expect(snapshot.memory.content).toBe('notes');
+    expect(snapshot.memory.exists).toBe(true);
+    expect(snapshot.persona.path).toContain('persona.md');
+    expect(snapshot.memory.path).toContain('memory.md');
+  });
+});

package/src/lib/load-context.ts

@@ -1,52 +1,52 @@
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { AuthStore } from './auth.js';
-import { getProfileMemoryFile } from './init-command.js';
-import {
-  getActivePersonaFile,
-  readPersonaFile,
-} from './persona.js';
-
-export interface LoadedFileSnapshot {
-  path: string;
-  exists: boolean;
-  content: string;
-}
-
-export interface LoadContextSnapshot {
-  persona: LoadedFileSnapshot;
-  memory: LoadedFileSnapshot;
-}
-
-function ensureMemoryFile(path: string): void {
-  if (!existsSync(path)) writeFileSync(path, '');
-}
-
-export function loadPersonaSnapshot(authStore = new AuthStore()): LoadedFileSnapshot {
-  const path = getActivePersonaFile(authStore);
-  const exists = existsSync(path);
-  return {
-    path,
-    exists,
-    content: readPersonaFile(path),
-  };
-}
-
-export function loadMemorySnapshot(authStore = new AuthStore()): LoadedFileSnapshot {
-  const profile = authStore.getActive();
-  if (!profile) throw new Error('Not logged in.');
-  const path = getProfileMemoryFile(profile);
-  ensureMemoryFile(path);
-  const exists = existsSync(path);
-  return {
-    path,
-    exists,
-    content: exists ? readFileSync(path, 'utf8') : '',
-  };
-}
-
-export function loadContext(authStore = new AuthStore()): LoadContextSnapshot {
-  return {
-    persona: loadPersonaSnapshot(authStore),
-    memory: loadMemorySnapshot(authStore),
-  };
-}
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { AuthStore } from './auth.js';
+import { getProfileMemoryFile } from './init-command.js';
+import {
+  getActivePersonaFile,
+  readPersonaFile,
+} from './persona.js';
+
+export interface LoadedFileSnapshot {
+  path: string;
+  exists: boolean;
+  content: string;
+}
+
+export interface LoadContextSnapshot {
+  persona: LoadedFileSnapshot;
+  memory: LoadedFileSnapshot;
+}
+
+function ensureMemoryFile(path: string): void {
+  if (!existsSync(path)) writeFileSync(path, '');
+}
+
+export function loadPersonaSnapshot(authStore = new AuthStore()): LoadedFileSnapshot {
+  const path = getActivePersonaFile(authStore);
+  const exists = existsSync(path);
+  return {
+    path,
+    exists,
+    content: readPersonaFile(path),
+  };
+}
+
+export function loadMemorySnapshot(authStore = new AuthStore()): LoadedFileSnapshot {
+  const profile = authStore.getActive();
+  if (!profile) throw new Error('Not logged in.');
+  const path = getProfileMemoryFile(profile);
+  ensureMemoryFile(path);
+  const exists = existsSync(path);
+  return {
+    path,
+    exists,
+    content: exists ? readFileSync(path, 'utf8') : '',
+  };
+}
+
+export function loadContext(authStore = new AuthStore()): LoadContextSnapshot {
+  return {
+    persona: loadPersonaSnapshot(authStore),
+    memory: loadMemorySnapshot(authStore),
+  };
+}

package/src/lib/match-state.test.ts

@@ -1,134 +1,134 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { mkdtempSync, existsSync, readFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import {
-  startMatch,
-  endMatch,
-  readMatchState,
-  markWaitingEmitted,
-  shouldEmitWaiting,
-  getWaitedSecs,
-  hasMatchTimedOut,
-  DEFAULT_WAITING_HEARTBEAT_MS,
-  DEFAULT_MATCH_TIMEOUT_MS,
-} from './match-state.js';
-
-function tmpDir(): string {
-  return mkdtempSync(join(tmpdir(), 'match-state-'));
-}
-
-describe('match-state — startMatch / readMatchState / endMatch', () => {
-  it('startMatch persists started_at with last_waiting_emit=0', () => {
-    const dir = tmpDir();
-    const now = 1_700_000_000_000;
-    const state = startMatch(dir, now);
-    expect(state).toEqual({ started_at: now, last_waiting_emit: 0 });
-    expect(readMatchState(dir)).toEqual(state);
-  });
-
-  it('startMatch overwrites an existing state (new queue session)', () => {
-    const dir = tmpDir();
-    startMatch(dir, 1_000_000);
-    markWaitingEmitted(dir, 1_500_000);
-    const fresh = startMatch(dir, 2_000_000);
-    expect(fresh).toEqual({ started_at: 2_000_000, last_waiting_emit: 0 });
-    expect(readMatchState(dir)).toEqual(fresh);
-  });
-
-  it('readMatchState returns null when no state file exists', () => {
-    expect(readMatchState(tmpDir())).toBeNull();
-  });
-
-  it('readMatchState returns null on corrupt JSON (does not throw)', () => {
-    const dir = tmpDir();
-    // Simulate a half-written file from a previous crash.
-    const fs = require('fs');
-    fs.writeFileSync(join(dir, 'match-state.json'), '{"started_at": 1');
-    expect(readMatchState(dir)).toBeNull();
-  });
-
-  it('endMatch removes the file; idempotent on missing', () => {
-    const dir = tmpDir();
-    startMatch(dir, 1_000_000);
-    expect(existsSync(join(dir, 'match-state.json'))).toBe(true);
-    endMatch(dir);
-    expect(existsSync(join(dir, 'match-state.json'))).toBe(false);
-    expect(() => endMatch(dir)).not.toThrow();
-  });
-});
-
-describe('match-state — atomic write', () => {
-  it('does not leave a .tmp sibling after a successful write', () => {
-    const dir = tmpDir();
-    startMatch(dir, 1_000_000);
-    markWaitingEmitted(dir, 1_100_000);
-    expect(existsSync(join(dir, 'match-state.json.tmp'))).toBe(false);
-  });
-});
-
-describe('match-state — shouldEmitWaiting', () => {
-  it('returns true when last_waiting_emit is 0 (sentinel: never emitted)', () => {
-    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
-    expect(shouldEmitWaiting(state, 1_000_001)).toBe(true);
-  });
-
-  it('returns true when the elapsed since last emit reaches the heartbeat', () => {
-    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
-    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS)).toBe(true);
-  });
-
-  it('returns false when below the heartbeat interval', () => {
-    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
-    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS - 1)).toBe(false);
-  });
-
-  it('honors a custom heartbeatMs', () => {
-    const state = { started_at: 0, last_waiting_emit: 1_000 };
-    expect(shouldEmitWaiting(state, 2_000, 1_000)).toBe(true);  // elapsed 1000ms == hb
-    expect(shouldEmitWaiting(state, 2_500, 1_000)).toBe(true);  // elapsed 1500ms > hb
-    expect(shouldEmitWaiting(state, 1_999, 1_000)).toBe(false); // elapsed 999ms < hb
-    expect(shouldEmitWaiting(state, 5_000, 5_000)).toBe(false); // elapsed 4000ms < hb 5000
-  });
-});
-
-describe('match-state — markWaitingEmitted', () => {
-  it('updates last_waiting_emit while preserving started_at', () => {
-    const dir = tmpDir();
-    startMatch(dir, 1_000_000);
-    markWaitingEmitted(dir, 1_200_000);
-    expect(readMatchState(dir)).toEqual({ started_at: 1_000_000, last_waiting_emit: 1_200_000 });
-  });
-
-  it('no-ops when state file is missing', () => {
-    const dir = tmpDir();
-    expect(() => markWaitingEmitted(dir, 1_000_000)).not.toThrow();
-    expect(readMatchState(dir)).toBeNull();
-  });
-});
-
-describe('match-state — getWaitedSecs / hasMatchTimedOut', () => {
-  it('getWaitedSecs returns floor of seconds since started_at', () => {
-    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
-    expect(getWaitedSecs(state, 1_000_999)).toBe(0);
-    expect(getWaitedSecs(state, 1_001_000)).toBe(1);
-    expect(getWaitedSecs(state, 1_120_500)).toBe(120);
-  });
-
-  it('getWaitedSecs clamps to 0 if clock skews backwards', () => {
-    const state = { started_at: 2_000_000, last_waiting_emit: 0 };
-    expect(getWaitedSecs(state, 1_000_000)).toBe(0);
-  });
-
-  it('hasMatchTimedOut flips at the default 10-minute threshold', () => {
-    const state = { started_at: 0, last_waiting_emit: 0 };
-    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS - 1)).toBe(false);
-    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS)).toBe(true);
-  });
-
-  it('honors a custom timeoutMs', () => {
-    const state = { started_at: 0, last_waiting_emit: 0 };
-    expect(hasMatchTimedOut(state, 999, 1_000)).toBe(false);
-    expect(hasMatchTimedOut(state, 1_000, 1_000)).toBe(true);
-  });
-});
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, existsSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  startMatch,
+  endMatch,
+  readMatchState,
+  markWaitingEmitted,
+  shouldEmitWaiting,
+  getWaitedSecs,
+  hasMatchTimedOut,
+  DEFAULT_WAITING_HEARTBEAT_MS,
+  DEFAULT_MATCH_TIMEOUT_MS,
+} from './match-state.js';
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), 'match-state-'));
+}
+
+describe('match-state — startMatch / readMatchState / endMatch', () => {
+  it('startMatch persists started_at with last_waiting_emit=0', () => {
+    const dir = tmpDir();
+    const now = 1_700_000_000_000;
+    const state = startMatch(dir, now);
+    expect(state).toEqual({ started_at: now, last_waiting_emit: 0 });
+    expect(readMatchState(dir)).toEqual(state);
+  });
+
+  it('startMatch overwrites an existing state (new queue session)', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_500_000);
+    const fresh = startMatch(dir, 2_000_000);
+    expect(fresh).toEqual({ started_at: 2_000_000, last_waiting_emit: 0 });
+    expect(readMatchState(dir)).toEqual(fresh);
+  });
+
+  it('readMatchState returns null when no state file exists', () => {
+    expect(readMatchState(tmpDir())).toBeNull();
+  });
+
+  it('readMatchState returns null on corrupt JSON (does not throw)', () => {
+    const dir = tmpDir();
+    // Simulate a half-written file from a previous crash.
+    const fs = require('fs');
+    fs.writeFileSync(join(dir, 'match-state.json'), '{"started_at": 1');
+    expect(readMatchState(dir)).toBeNull();
+  });
+
+  it('endMatch removes the file; idempotent on missing', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    expect(existsSync(join(dir, 'match-state.json'))).toBe(true);
+    endMatch(dir);
+    expect(existsSync(join(dir, 'match-state.json'))).toBe(false);
+    expect(() => endMatch(dir)).not.toThrow();
+  });
+});
+
+describe('match-state — atomic write', () => {
+  it('does not leave a .tmp sibling after a successful write', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_100_000);
+    expect(existsSync(join(dir, 'match-state.json.tmp'))).toBe(false);
+  });
+});
+
+describe('match-state — shouldEmitWaiting', () => {
+  it('returns true when last_waiting_emit is 0 (sentinel: never emitted)', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
+    expect(shouldEmitWaiting(state, 1_000_001)).toBe(true);
+  });
+
+  it('returns true when the elapsed since last emit reaches the heartbeat', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
+    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS)).toBe(true);
+  });
+
+  it('returns false when below the heartbeat interval', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 1_000_000 };
+    expect(shouldEmitWaiting(state, 1_000_000 + DEFAULT_WAITING_HEARTBEAT_MS - 1)).toBe(false);
+  });
+
+  it('honors a custom heartbeatMs', () => {
+    const state = { started_at: 0, last_waiting_emit: 1_000 };
+    expect(shouldEmitWaiting(state, 2_000, 1_000)).toBe(true);  // elapsed 1000ms == hb
+    expect(shouldEmitWaiting(state, 2_500, 1_000)).toBe(true);  // elapsed 1500ms > hb
+    expect(shouldEmitWaiting(state, 1_999, 1_000)).toBe(false); // elapsed 999ms < hb
+    expect(shouldEmitWaiting(state, 5_000, 5_000)).toBe(false); // elapsed 4000ms < hb 5000
+  });
+});
+
+describe('match-state — markWaitingEmitted', () => {
+  it('updates last_waiting_emit while preserving started_at', () => {
+    const dir = tmpDir();
+    startMatch(dir, 1_000_000);
+    markWaitingEmitted(dir, 1_200_000);
+    expect(readMatchState(dir)).toEqual({ started_at: 1_000_000, last_waiting_emit: 1_200_000 });
+  });
+
+  it('no-ops when state file is missing', () => {
+    const dir = tmpDir();
+    expect(() => markWaitingEmitted(dir, 1_000_000)).not.toThrow();
+    expect(readMatchState(dir)).toBeNull();
+  });
+});
+
+describe('match-state — getWaitedSecs / hasMatchTimedOut', () => {
+  it('getWaitedSecs returns floor of seconds since started_at', () => {
+    const state = { started_at: 1_000_000, last_waiting_emit: 0 };
+    expect(getWaitedSecs(state, 1_000_999)).toBe(0);
+    expect(getWaitedSecs(state, 1_001_000)).toBe(1);
+    expect(getWaitedSecs(state, 1_120_500)).toBe(120);
+  });
+
+  it('getWaitedSecs clamps to 0 if clock skews backwards', () => {
+    const state = { started_at: 2_000_000, last_waiting_emit: 0 };
+    expect(getWaitedSecs(state, 1_000_000)).toBe(0);
+  });
+
+  it('hasMatchTimedOut flips at the default 10-minute threshold', () => {
+    const state = { started_at: 0, last_waiting_emit: 0 };
+    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS - 1)).toBe(false);
+    expect(hasMatchTimedOut(state, DEFAULT_MATCH_TIMEOUT_MS)).toBe(true);
+  });
+
+  it('honors a custom timeoutMs', () => {
+    const state = { started_at: 0, last_waiting_emit: 0 };
+    expect(hasMatchTimedOut(state, 999, 1_000)).toBe(false);
+    expect(hasMatchTimedOut(state, 1_000, 1_000)).toBe(true);
+  });
+});

package/src/lib/match-state.ts

@@ -1,94 +1,94 @@
-/**
- * match-state — 记录单次匹配等待的进度,用于 `ccl game queue` 跨进程协调
- * `match_waiting` / `match_timeout` 合成事件的发射节奏。
- *
- * 每次 `ccl game queue` 是一个新进程,跨进程的"上次心跳时间"必须落盘。
- * 持久化在 `${profileStateDir}/match-state.json`,生命周期:
- *   - `ccl game join`           → startMatch() 创建
- *   - `ccl game queue` 匹配成功 → endMatch() 删除
- *   - `ccl game queue` 心跳到点 → markWaitingEmitted() 更新 last_waiting_emit
- *   - 用户主动 leave/quit      → endMatch() 删除
- */
-
-import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'fs';
-import { join } from 'path';
-
-export interface MatchState {
-  started_at: number;       // ms epoch — 进入队列的时刻
-  last_waiting_emit: number; // ms epoch — 最近一次 emit match_waiting 的时刻 (0 = 从未)
-}
-
-/** 默认匹配等待心跳间隔:5 分钟 */
-export const DEFAULT_WAITING_HEARTBEAT_MS = 300_000;
-
-/** 默认匹配总超时阈值:600 秒 (10 分钟) */
-export const DEFAULT_MATCH_TIMEOUT_MS = 600_000;
-
-function statePath(stateDir: string): string {
-  return join(stateDir, 'match-state.json');
-}
-
-/**
- * 原子写: 先写到 .tmp 再 rename。
- * rename 在 NTFS / ext4 / APFS 上都是原子操作,避免半写文件被 JSON.parse 时
- * 误判为"无匹配进行中"而把累计等待计数重置。
- */
-function atomicWriteJSON(path: string, value: unknown): void {
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, JSON.stringify(value));
-  renameSync(tmp, path);
-}
-
-export function readMatchState(stateDir: string): MatchState | null {
-  const p = statePath(stateDir);
-  if (!existsSync(p)) return null;
-  try {
-    return JSON.parse(readFileSync(p, 'utf8')) as MatchState;
-  } catch {
-    return null;
-  }
-}
-
-/** 开始一轮新匹配。即使旧 state 残留也覆盖。 */
-export function startMatch(stateDir: string, now: number = Date.now()): MatchState {
-  const state: MatchState = { started_at: now, last_waiting_emit: 0 };
-  atomicWriteJSON(statePath(stateDir), state);
-  return state;
-}
-
-/** 匹配成功或被取消时清理。幂等。 */
-export function endMatch(stateDir: string): void {
-  const p = statePath(stateDir);
-  if (!existsSync(p)) return;
-  try { unlinkSync(p); } catch {}
-}
-
-export function markWaitingEmitted(stateDir: string, now: number = Date.now()): void {
-  const cur = readMatchState(stateDir);
-  if (!cur) return;
-  const next: MatchState = { ...cur, last_waiting_emit: now };
-  atomicWriteJSON(statePath(stateDir), next);
-}
-
-/** 距离上次 emit match_waiting 是否够久 (或从未 emit)。 */
-export function shouldEmitWaiting(
-  state: MatchState,
-  now: number = Date.now(),
-  heartbeatMs: number = DEFAULT_WAITING_HEARTBEAT_MS,
-): boolean {
-  if (state.last_waiting_emit === 0) return true;
-  return now - state.last_waiting_emit >= heartbeatMs;
-}
-
-export function getWaitedSecs(state: MatchState, now: number = Date.now()): number {
-  return Math.max(0, Math.floor((now - state.started_at) / 1000));
-}
-
-/** 累计等待是否已到总超时阈值。 */
-export function hasMatchTimedOut(
-  state: MatchState,
-  now: number = Date.now(),
-  timeoutMs: number = DEFAULT_MATCH_TIMEOUT_MS,
-): boolean {
-  return now - state.started_at >= timeoutMs;
-}
+/**
+ * match-state — 记录单次匹配等待的进度,用于 `ccl game queue` 跨进程协调
+ * `match_waiting` / `match_timeout` 合成事件的发射节奏。
+ *
+ * 每次 `ccl game queue` 是一个新进程,跨进程的"上次心跳时间"必须落盘。
+ * 持久化在 `${profileStateDir}/match-state.json`,生命周期:
+ *   - `ccl game join`           → startMatch() 创建
+ *   - `ccl game queue` 匹配成功 → endMatch() 删除
+ *   - `ccl game queue` 心跳到点 → markWaitingEmitted() 更新 last_waiting_emit
+ *   - 用户主动 leave/quit      → endMatch() 删除
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'fs';
+import { join } from 'path';
+
+export interface MatchState {
+  started_at: number;       // ms epoch — 进入队列的时刻
+  last_waiting_emit: number; // ms epoch — 最近一次 emit match_waiting 的时刻 (0 = 从未)
+}
+
+/** 默认匹配等待心跳间隔:5 分钟 */
+export const DEFAULT_WAITING_HEARTBEAT_MS = 300_000;
+
+/** 默认匹配总超时阈值:600 秒 (10 分钟) */
+export const DEFAULT_MATCH_TIMEOUT_MS = 600_000;
+
+function statePath(stateDir: string): string {
+  return join(stateDir, 'match-state.json');
+}
+
+/**
+ * 原子写: 先写到 .tmp 再 rename。
+ * rename 在 NTFS / ext4 / APFS 上都是原子操作,避免半写文件被 JSON.parse 时
+ * 误判为"无匹配进行中"而把累计等待计数重置。
+ */
+function atomicWriteJSON(path: string, value: unknown): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value));
+  renameSync(tmp, path);
+}
+
+export function readMatchState(stateDir: string): MatchState | null {
+  const p = statePath(stateDir);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8')) as MatchState;
+  } catch {
+    return null;
+  }
+}
+
+/** 开始一轮新匹配。即使旧 state 残留也覆盖。 */
+export function startMatch(stateDir: string, now: number = Date.now()): MatchState {
+  const state: MatchState = { started_at: now, last_waiting_emit: 0 };
+  atomicWriteJSON(statePath(stateDir), state);
+  return state;
+}
+
+/** 匹配成功或被取消时清理。幂等。 */
+export function endMatch(stateDir: string): void {
+  const p = statePath(stateDir);
+  if (!existsSync(p)) return;
+  try { unlinkSync(p); } catch {}
+}
+
+export function markWaitingEmitted(stateDir: string, now: number = Date.now()): void {
+  const cur = readMatchState(stateDir);
+  if (!cur) return;
+  const next: MatchState = { ...cur, last_waiting_emit: now };
+  atomicWriteJSON(statePath(stateDir), next);
+}
+
+/** 距离上次 emit match_waiting 是否够久 (或从未 emit)。 */
+export function shouldEmitWaiting(
+  state: MatchState,
+  now: number = Date.now(),
+  heartbeatMs: number = DEFAULT_WAITING_HEARTBEAT_MS,
+): boolean {
+  if (state.last_waiting_emit === 0) return true;
+  return now - state.last_waiting_emit >= heartbeatMs;
+}
+
+export function getWaitedSecs(state: MatchState, now: number = Date.now()): number {
+  return Math.max(0, Math.floor((now - state.started_at) / 1000));
+}
+
+/** 累计等待是否已到总超时阈值。 */
+export function hasMatchTimedOut(
+  state: MatchState,
+  now: number = Date.now(),
+  timeoutMs: number = DEFAULT_MATCH_TIMEOUT_MS,
+): boolean {
+  return now - state.started_at >= timeoutMs;
+}