@myclaw163/clawclaw-cli 0.6.54

package/src/lib/workspace-argv.ts

@@ -0,0 +1,44 @@
+import { resolve, win32 } from 'path';
+import { CLAWCLAW_WORKSPACE_DIR } from './init-command.js';
+
+const WORKSPACE_DIR_OPTION = '--workspace-dir';
+export { CLAWCLAW_WORKSPACE_DIR };
+
+function isPresent(value: string | undefined): value is string {
+  return typeof value === 'string' && value.trim() !== '' && !value.startsWith('-');
+}
+
+export function extractWorkspaceDirArgv(argv: readonly string[]): string | undefined {
+  for (let i = 0; i < argv.length; i += 1) {
+    const current = argv[i];
+    if (current === WORKSPACE_DIR_OPTION) {
+      const next = argv[i + 1];
+      return isPresent(next) ? next : undefined;
+    }
+
+    if (current.startsWith(`${WORKSPACE_DIR_OPTION}=`)) {
+      const value = current.slice(WORKSPACE_DIR_OPTION.length + 1);
+      return isPresent(value) ? value : undefined;
+    }
+  }
+
+  return undefined;
+}
+
+export function applyWorkspaceArgv(
+  argv: readonly string[],
+  env: NodeJS.ProcessEnv,
+  cwd: string = process.cwd(),
+): string | undefined {
+  const workspaceDir = extractWorkspaceDirArgv(argv);
+  if (!workspaceDir) {
+    return undefined;
+  }
+
+  const useWin32Path = /^[A-Za-z]:[\\/]/.test(cwd) || /^[A-Za-z]:[\\/]/.test(workspaceDir);
+  const resolvedWorkspaceDir = useWin32Path
+    ? win32.resolve(cwd, workspaceDir)
+    : resolve(cwd, workspaceDir);
+  env[CLAWCLAW_WORKSPACE_DIR] = resolvedWorkspaceDir;
+  return resolvedWorkspaceDir;
+}

package/src/perception/player-history-store.test.ts

@@ -0,0 +1,87 @@
+import { existsSync, mkdtempSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { PlayerHistoryStore, playerHistoryPathForSession } from './player-history-store.js';
+
+describe('PlayerHistoryStore', () => {
+  it('derives sidecar path from the session jsonl path', () => {
+    expect(playerHistoryPathForSession('/tmp/game.jsonl')).toBe('/tmp/game.player-history.json');
+    expect(playerHistoryPathForSession('/tmp/game')).toBe('/tmp/game.player-history.json');
+  });
+
+  it('records player_spotted by tick, fills empty frames, and merges same tick players', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'player-history-'));
+    const store = new PlayerHistoryStore(join(dir, 'session.player-history.json'));
+    store.reset(Date.parse('2026-05-21T00:00:00.000Z'));
+
+    expect(store.recordPlayerSpotted({
+      type: 'player_spotted',
+      tick: 10,
+      spotted_name: '砂锅猎手',
+      spotted_room: '动力监控室',
+      spotted_x: 1,
+      spotted_y: 2,
+    }, Date.parse('2026-05-21T00:00:01.000Z'))).toBe(true);
+    store.recordPlayerSpotted({
+      type: 'player_spotted',
+      tick: 13,
+      spotted_name: '洋流王子',
+      spotted_room: 'hallway',
+      spotted_x: 3,
+      spotted_y: 4,
+    }, Date.parse('2026-05-21T00:00:02.000Z'));
+    store.recordPlayerSpotted({
+      type: 'player_spotted',
+      tick: 13,
+      spotted_name: '测试-浮沉-0bc9',
+      spotted_room: 'hallway',
+      spotted_x: 5,
+      spotted_y: 6,
+    }, Date.parse('2026-05-21T00:00:02.000Z'));
+
+    const data = store.read()!;
+    expect(data.visible_frames.map((frame) => frame.tick)).toEqual([10, 11, 12, 13]);
+    expect(data.visible_frames[1].players).toEqual({});
+    expect(data.visible_frames[2].players).toEqual({});
+    expect(new Set(Object.keys(data.visible_frames[3].players))).toEqual(new Set(['测试-浮沉-0bc9', '洋流王子']));
+    expect(data.last_history_tick).toBe(13);
+  });
+
+  it('does not backfill a missing old tick after later ticks have been processed', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'player-history-'));
+    const store = new PlayerHistoryStore(join(dir, 'session.player-history.json'));
+    store.reset();
+    store.recordPlayerSpotted({ type: 'player_spotted', tick: 10, spotted_name: 'A', spotted_x: 1, spotted_y: 1 });
+    store.recordPlayerSpotted({ type: 'player_spotted', tick: 13, spotted_name: 'B', spotted_x: 2, spotted_y: 2 });
+    expect(store.recordPlayerSpotted({ type: 'player_spotted', tick: 9, spotted_name: 'C', spotted_x: 3, spotted_y: 3 })).toBe(false);
+    expect(store.read()!.visible_frames.some((frame) => frame.tick === 9)).toBe(false);
+  });
+
+  it('caches seats and lobster task locations from map data', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'player-history-'));
+    const store = new PlayerHistoryStore(join(dir, 'session.player-history.json'));
+    store.reset();
+    store.updateMapCache({
+      all_players: [{ name: 'A', seat: 1 }, { name: 'B', seat: 2 }],
+      all_task_locations: [
+        { name: '修线', room: '电力', x: 10, y: 20, faction: 'lobster' },
+        { name: '破坏', room: '制氧', x: 30, y: 40, faction: 'crab' },
+      ],
+    });
+    const data = store.read()!;
+    expect(data.seats).toEqual({ A: 1, B: 2 });
+    expect(data.lobster_tasks).toEqual([{ name: '修线', room: '电力', x: 10, y: 20 }]);
+  });
+
+  it('deletes the sidecar when requested', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'player-history-'));
+    const path = join(dir, 'session.player-history.json');
+    const store = new PlayerHistoryStore(path);
+    store.reset();
+    expect(existsSync(path)).toBe(true);
+    expect(JSON.parse(readFileSync(path, 'utf8')).visible_frames).toEqual([]);
+    store.delete();
+    expect(existsSync(path)).toBe(false);
+  });
+});

package/src/perception/player-history-store.ts

@@ -0,0 +1,194 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+
+export interface FramePlayer {
+  x: number;
+  y: number;
+  room?: string | null;
+}
+
+export interface VisibleFrame {
+  tick: number;
+  time: string;
+  players: Record<string, FramePlayer>;
+}
+
+export interface LobsterTaskPoint {
+  name: string;
+  room?: string | null;
+  x: number;
+  y: number;
+}
+
+export interface PlayerHistoryData {
+  time: string;
+  visible_frames: VisibleFrame[];
+  seats: Record<string, number>;
+  lobster_tasks: LobsterTaskPoint[];
+  last_raw_frame: null;
+  last_history_tick: number | null;
+}
+
+const TICK_MS = 100;
+
+function nowIso(nowMs = Date.now()): string {
+  return new Date(nowMs).toISOString();
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function frameTimeFromPrevious(data: PlayerHistoryData, tick: number, nowMs: number): string {
+  const lastTick = data.last_history_tick;
+  if (lastTick == null || tick <= lastTick) return nowIso(nowMs);
+  const lastFrame = data.visible_frames.find((frame) => frame.tick === lastTick);
+  const lastMs = lastFrame ? Date.parse(lastFrame.time) : NaN;
+  const baseMs = Number.isFinite(lastMs) ? lastMs : nowMs - (tick - lastTick) * TICK_MS;
+  return nowIso(baseMs + (tick - lastTick) * TICK_MS);
+}
+
+function createEmptyData(nowMs = Date.now()): PlayerHistoryData {
+  return {
+    time: nowIso(nowMs),
+    visible_frames: [],
+    seats: {},
+    lobster_tasks: [],
+    last_raw_frame: null,
+    last_history_tick: null,
+  };
+}
+
+function normalizeData(raw: Partial<PlayerHistoryData> | null, nowMs = Date.now()): PlayerHistoryData {
+  return {
+    time: typeof raw?.time === 'string' ? raw.time : nowIso(nowMs),
+    visible_frames: Array.isArray(raw?.visible_frames) ? raw.visible_frames : [],
+    seats: raw?.seats && typeof raw.seats === 'object' ? raw.seats : {},
+    lobster_tasks: Array.isArray(raw?.lobster_tasks) ? raw.lobster_tasks : [],
+    last_raw_frame: null,
+    last_history_tick: isFiniteNumber(raw?.last_history_tick) ? raw.last_history_tick : null,
+  };
+}
+
+function ensureFrame(data: PlayerHistoryData, tick: number, time: string): VisibleFrame {
+  let frame = data.visible_frames.find((candidate) => candidate.tick === tick);
+  if (!frame) {
+    frame = { tick, time, players: {} };
+    data.visible_frames.push(frame);
+    data.visible_frames.sort((a, b) => a.tick - b.tick);
+  }
+  return frame;
+}
+
+export function playerHistoryPathForSession(sessionPath: string): string {
+  return sessionPath.endsWith('.jsonl')
+    ? `${sessionPath.slice(0, -'.jsonl'.length)}.player-history.json`
+    : `${sessionPath}.player-history.json`;
+}
+
+export class PlayerHistoryStore {
+  constructor(private filePath: string) {}
+
+  get path(): string {
+    return this.filePath;
+  }
+
+  static forSession(sessionPath: string): PlayerHistoryStore {
+    return new PlayerHistoryStore(playerHistoryPathForSession(sessionPath));
+  }
+
+  read(): PlayerHistoryData | null {
+    if (!existsSync(this.filePath)) return null;
+    try {
+      return normalizeData(JSON.parse(readFileSync(this.filePath, 'utf8')));
+    } catch {
+      return null;
+    }
+  }
+
+  reset(nowMs = Date.now()): PlayerHistoryData {
+    const data = createEmptyData(nowMs);
+    this.write(data);
+    return data;
+  }
+
+  delete(): void {
+    try { unlinkSync(this.filePath); } catch {}
+  }
+
+  updateMapCache(mapData: any, nowMs = Date.now()): void {
+    if (!mapData || typeof mapData !== 'object') return;
+    const data = this.read() ?? createEmptyData(nowMs);
+    const seats: Record<string, number> = {};
+    for (const player of Array.isArray(mapData.all_players) ? mapData.all_players : []) {
+      if (typeof player?.name !== 'string' || !isFiniteNumber(player.seat)) continue;
+      seats[player.name] = player.seat;
+    }
+    const lobsterTasks: LobsterTaskPoint[] = [];
+    for (const task of Array.isArray(mapData.all_task_locations) ? mapData.all_task_locations : []) {
+      if (task?.faction !== 'lobster') continue;
+      if (typeof task.name !== 'string' || !isFiniteNumber(task.x) || !isFiniteNumber(task.y)) continue;
+      lobsterTasks.push({
+        name: task.name,
+        room: typeof task.room === 'string' ? task.room : null,
+        x: task.x,
+        y: task.y,
+      });
+    }
+    data.seats = seats;
+    data.lobster_tasks = lobsterTasks;
+    data.time = nowIso(nowMs);
+    this.write(data);
+  }
+
+  recordPlayerSpotted(event: Record<string, any>, nowMs = Date.now()): boolean {
+    if (event.type !== 'player_spotted') return false;
+    const tick = event.tick;
+    const name = event.spotted_name;
+    const x = event.spotted_x;
+    const y = event.spotted_y;
+    if (!isFiniteNumber(tick) || !Number.isInteger(tick)) return false;
+    if (typeof name !== 'string' || name.length === 0) return false;
+    if (!isFiniteNumber(x) || !isFiniteNumber(y)) return false;
+
+    const data = this.read() ?? createEmptyData(nowMs);
+    let frame: VisibleFrame | undefined;
+    const lastTick = data.last_history_tick;
+
+    if (lastTick == null) {
+      frame = ensureFrame(data, tick, nowIso(nowMs));
+      data.last_history_tick = tick;
+    } else if (tick > lastTick) {
+      const lastFrame = data.visible_frames.find((candidate) => candidate.tick === lastTick);
+      const lastMs = lastFrame ? Date.parse(lastFrame.time) : NaN;
+      const baseMs = Number.isFinite(lastMs) ? lastMs : nowMs - (tick - lastTick) * TICK_MS;
+      for (let emptyTick = lastTick + 1; emptyTick < tick; emptyTick++) {
+        ensureFrame(data, emptyTick, nowIso(baseMs + (emptyTick - lastTick) * TICK_MS));
+      }
+      frame = ensureFrame(data, tick, nowIso(baseMs + (tick - lastTick) * TICK_MS));
+      data.last_history_tick = tick;
+    } else {
+      frame = data.visible_frames.find((candidate) => candidate.tick === tick);
+      if (!frame && tick === lastTick) frame = ensureFrame(data, tick, frameTimeFromPrevious(data, tick, nowMs));
+      if (!frame) return false;
+    }
+
+    frame.players[name] = {
+      x,
+      y,
+      room: typeof event.spotted_room === 'string'
+        ? event.spotted_room
+        : typeof event.room === 'string'
+          ? event.room
+          : null,
+    };
+    data.time = nowIso(nowMs);
+    this.write(data);
+    return true;
+  }
+
+  private write(data: PlayerHistoryData): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+  }
+}

package/src/pipeline/event-store.ts

@@ -0,0 +1,124 @@
+import { appendFileSync, readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { dirname, join, basename } from 'path';
+import { AuthStore } from '../lib/auth.js';
+import { getProfileGamesDir } from '../lib/init-command.js';
+
+interface GameSessionFile {
+  path: string;
+  sessionId: string;
+  mtimeMs: number;
+}
+
+export function extractNewEvents(source: any): Record<string, any>[] {
+  const candidates = [
+    source,
+    source?.new_events,
+    source?.data?.new_events,
+    source?.result?.new_events,
+    source?.result?.data?.new_events,
+  ];
+
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate.filter((evt) => evt && typeof evt === 'object');
+    }
+  }
+
+  return [];
+}
+
+export class EventStore {
+  constructor(private filePath: string) {}
+
+  get path(): string {
+    return this.filePath;
+  }
+
+  static forActiveAccount(): EventStore {
+    return EventStore.forLatestGame();
+  }
+
+  static forLatestGame(): EventStore {
+    const store = new AuthStore();
+    const profile = store.getActive();
+    if (!profile) throw new Error('Not logged in.');
+
+    const latest = EventStore.latestSessionFile(getProfileGamesDir(profile));
+    if (!latest) {
+      throw new Error('No game events found. Join a game first.');
+    }
+
+    return new EventStore(latest.path);
+  }
+
+  /** Returns the path to the latest session jsonl, or null if none exists. */
+  static latestSessionPath(): string | null {
+    const store = new AuthStore();
+    const profile = store.getActive();
+    if (!profile) return null;
+    return EventStore.latestSessionFile(getProfileGamesDir(profile))?.path ?? null;
+  }
+
+  static createSessionForActiveAccount(sessionId = EventStore.createSessionId()): EventStore {
+    const store = new AuthStore();
+    const profile = store.getActive();
+    if (!profile) throw new Error('Not logged in.');
+
+    const dir = getProfileGamesDir(profile);
+    mkdirSync(dir, { recursive: true });
+    const filePath = join(dir, `${sessionId}.jsonl`);
+    if (!existsSync(filePath)) writeFileSync(filePath, '');
+    return new EventStore(filePath);
+  }
+
+  append(event: Record<string, any>): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    const line = JSON.stringify(event) + '\n';
+    appendFileSync(this.filePath, line);
+  }
+
+  appendNewEvents(events: any): void {
+    const extracted = extractNewEvents(events);
+    if (extracted.length === 0) return;
+    for (const evt of extracted) {
+      this.append(evt);
+    }
+  }
+
+  tail(n: number): Record<string, any>[] {
+    if (!existsSync(this.filePath)) return [];
+    const lines = readFileSync(this.filePath, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-n).map(l => JSON.parse(l));
+  }
+
+  all(): Record<string, any>[] {
+    if (!existsSync(this.filePath)) return [];
+    const content = readFileSync(this.filePath, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(l => JSON.parse(l));
+  }
+
+  clear(): void {
+    writeFileSync(this.filePath, '');
+  }
+
+  private static createSessionId(): string {
+    const id = new Date().toISOString();
+    return process.platform === 'win32' ? id.replace(/:/g, '_') : id;
+  }
+
+  private static latestSessionFile(dir: string): GameSessionFile | null {
+    if (!existsSync(dir)) return null;
+
+    const files = readdirSync(dir)
+      .filter(name => name.endsWith('.jsonl') && !name.endsWith('.raw-ws.jsonl') && !name.startsWith('index.'))
+      .map(name => {
+        const path = join(dir, name);
+        const stat = statSync(path);
+        return { path, sessionId: basename(name, '.jsonl'), mtimeMs: stat.mtimeMs };
+      })
+      .sort((a, b) => b.sessionId.localeCompare(a.sessionId) || b.mtimeMs - a.mtimeMs);
+
+    return files[0] ?? null;
+  }
+}

package/src/pipeline/pipeline.ts

@@ -0,0 +1,35 @@
+import { GameClient } from '../lib/game-client.js';
+import { EventStore } from './event-store.js';
+
+interface PipelineAction {
+  action: Record<string, any>;
+  needsWait: boolean;
+}
+
+export async function runPipeline(actions: PipelineAction[], initialWaitMs?: number): Promise<void> {
+  const client = GameClient.fromAuth();
+  const store = EventStore.forActiveAccount();
+
+  if (initialWaitMs && initialWaitMs > 0) {
+    await new Promise(r => setTimeout(r, initialWaitMs));
+  }
+
+  for (const item of actions) {
+    const result = await client.submitAction(item.action as any);
+    store.appendNewEvents(result);
+    const durationSecs = result?.data?.duration_secs ?? result?.duration_secs ?? 0;
+
+    if (item.needsWait && durationSecs > 0) {
+      await new Promise(r => setTimeout(r, (durationSecs + 0.5) * 1000));
+      try {
+        const state = await client.getGameState();
+        if (state) store.appendNewEvents(state.new_events);
+      } catch {}
+      store.append({ type: 'pipeline', action: item.action, status: 'done' });
+    } else {
+      store.append({ type: 'pipeline', action: item.action, result });
+    }
+  }
+
+  store.append({ type: 'pipeline_done', count: actions.length });
+}

package/src/runtime/auto-upgrade.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('../commands/upgrade.js', () => ({
+  runDefaultUpgrade: vi.fn(),
+}));
+
+import { runDefaultUpgrade } from '../commands/upgrade.js';
+import { runAutoUpgradeOnLoad, shouldSkipAutoUpgrade } from './auto-upgrade.js';
+
+describe('runAutoUpgradeOnLoad', () => {
+  const prev = process.env.CLAWCLAW_SKIP_AUTO_UPGRADE;
+
+  beforeEach(() => {
+    vi.mocked(runDefaultUpgrade).mockReset();
+    delete process.env.CLAWCLAW_SKIP_AUTO_UPGRADE;
+  });
+
+  afterEach(() => {
+    if (prev === undefined) delete process.env.CLAWCLAW_SKIP_AUTO_UPGRADE;
+    else process.env.CLAWCLAW_SKIP_AUTO_UPGRADE = prev;
+  });
+
+  it('skips when CLAWCLAW_SKIP_AUTO_UPGRADE=1', () => {
+    process.env.CLAWCLAW_SKIP_AUTO_UPGRADE = '1';
+    runAutoUpgradeOnLoad({ packageVersion: '0.5.25' });
+    expect(runDefaultUpgrade).not.toHaveBeenCalled();
+  });
+
+  it('skips prerelease/test package versions', () => {
+    runAutoUpgradeOnLoad({ packageVersion: '0.5.25-test' });
+    expect(runDefaultUpgrade).not.toHaveBeenCalled();
+  });
+
+  it('runs default upgrade when not skipped', () => {
+    vi.mocked(runDefaultUpgrade).mockReturnValue({ version: '0.4.8' });
+    runAutoUpgradeOnLoad({ packageVersion: '0.5.25' });
+    expect(runDefaultUpgrade).toHaveBeenCalledOnce();
+  });
+
+  it('does not write upgrade progress to stdout', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.mocked(runDefaultUpgrade).mockReturnValue({ version: '0.4.8' });
+    try {
+      runAutoUpgradeOnLoad({ packageVersion: '0.5.25' });
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it('notifies on upgrade success and failure', () => {
+    const notify = vi.fn();
+    vi.mocked(runDefaultUpgrade).mockReturnValueOnce({ version: '0.4.8' });
+    runAutoUpgradeOnLoad({ packageVersion: '0.5.25', notify });
+    expect(notify).toHaveBeenCalledWith('[clawclaw-cli] auto-upgrade installed 0.4.8');
+
+    vi.mocked(runDefaultUpgrade).mockReturnValueOnce({ error: 'npm install failed: EACCES' });
+    runAutoUpgradeOnLoad({ packageVersion: '0.5.25', notify });
+    expect(notify).toHaveBeenCalledWith('[clawclaw-cli] auto-upgrade failed: npm install failed: EACCES');
+  });
+
+  it('treats prerelease versions as skip-worthy', () => {
+    expect(shouldSkipAutoUpgrade('0.5.25-test')).toBe(true);
+    expect(shouldSkipAutoUpgrade('0.5.25')).toBe(false);
+  });
+});

package/src/runtime/auto-upgrade.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from 'fs';
+import { runDefaultUpgrade } from '../commands/upgrade.js';
+
+function readPackageVersion(): string | null {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    return typeof pkg?.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+export function shouldSkipAutoUpgrade(packageVersion = readPackageVersion()): boolean {
+  if (process.env.CLAWCLAW_SKIP_AUTO_UPGRADE === '1') return true;
+  return Boolean(packageVersion?.includes('-'));
+}
+
+/** Run during `ccl load`, before game start and event streaming begin. */
+export function runAutoUpgradeOnLoad(options?: { packageVersion?: string; notify?: (message: string) => void }): void {
+  if (shouldSkipAutoUpgrade(options?.packageVersion)) return;
+
+  const result = runDefaultUpgrade();
+  if (result.error) {
+    const msg = result.version ? `${result.version} (${result.error})` : result.error;
+    options?.notify?.(`[clawclaw-cli] auto-upgrade failed: ${msg}`);
+    return;
+  }
+  if (result.version) {
+    options?.notify?.(`[clawclaw-cli] auto-upgrade installed ${result.version}`);
+  }
+}

package/src/runtime/daemon.ts

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, openSync, readFileSync } from 'fs';
+import { resolve, dirname, delimiter } from 'path';
+import { spawn, execSync } from 'child_process';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { getProfileStateDir, getProfileLogsDir } from '../lib/init-command.js';
+import { AuthStore } from '../lib/auth.js';
+import { RuntimeLogger } from './runtime-logger.js';
+
+const log = new RuntimeLogger();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function isPidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function getRunningDaemonPid(stateDir: string): number | null {
+  const runtimePath = join(stateDir, 'runtime.json');
+  if (!existsSync(runtimePath)) return null;
+  try {
+    const info = JSON.parse(readFileSync(runtimePath, 'utf8'));
+    if (typeof info?.pid === 'number' && isPidAlive(info.pid)) return info.pid;
+  } catch {}
+  return null;
+}
+
+export async function waitDaemonExit(stateDir: string, timeoutMs = 15000): Promise<void> {
+  const runtimePath = join(stateDir, 'runtime.json');
+  let pid: number | undefined;
+  try {
+    if (existsSync(runtimePath)) {
+      const info = JSON.parse(readFileSync(runtimePath, 'utf8'));
+      if (typeof info?.pid === 'number') pid = info.pid;
+    }
+  } catch {}
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const fileGone = !existsSync(runtimePath);
+    const procGone = pid === undefined ? true : !isPidAlive(pid);
+    if (fileGone && procGone) return;
+    await new Promise(r => setTimeout(r, 200));
+  }
+  throw new Error(
+    `Daemon did not exit within ${timeoutMs}ms (pid=${pid ?? 'unknown'}).`,
+  );
+}
+
+export function spawnDaemon(): { pid: number; logFile: string } {
+  const store = new AuthStore();
+  const active = store.getActive();
+  if (!active) throw new Error('Not logged in.');
+
+  const stateDir = getProfileStateDir(active);
+  mkdirSync(stateDir, { recursive: true });
+
+  const existingPid = getRunningDaemonPid(stateDir);
+  if (existingPid) {
+    throw new Error(`Daemon already running (pid=${existingPid}). Stop it first.`);
+  }
+
+  const logsDir = getProfileLogsDir(active);
+  mkdirSync(logsDir, { recursive: true });
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logFile = join(logsDir, `daemon-${timestamp}.log`);
+  const logFd = openSync(logFile, 'a');
+
+  const fwd = (p: string) => p.replace(/\\/g, '/');
+  const binEntry = fwd(resolve(__dirname, '..', '..', 'bin', 'clawclaw-cli.mjs'));
+  if (!existsSync(binEntry)) throw new Error('clawclaw-cli bin entry not found');
+
+  let npmGlobalModules = '';
+  try { npmGlobalModules = execSync('npm root -g', { encoding: 'utf8', windowsHide: true }).trim(); } catch {}
+
+  const existingNodePath = process.env.NODE_PATH ?? '';
+  const nodePath = [npmGlobalModules, existingNodePath].filter(Boolean).join(delimiter);
+  const isWin = process.platform === 'win32';
+
+  const child = spawn(process.execPath, [binEntry, '_daemon'], {
+    detached: true,
+    stdio: isWin ? ['ignore', 'ignore', 'ignore'] : ['ignore', logFd, logFd],
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      NODE_PATH: nodePath,
+      ...(isWin ? { CLAWCLAW_LOG_FILE: logFile } : {}),
+    },
+    windowsHide: true,
+  });
+
+  child.on('error', (err) => {
+    log.error('DAEMON_SPAWN', `failed to start daemon`, err);
+  });
+
+  child.unref();
+  return { pid: child.pid!, logFile };
+}