@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/daemon-client.test.js

@@ -0,0 +1,411 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, setDaemonCommandTimeoutSeconds, } from './daemon-client.js';
+import * as daemonLifecycle from './daemon-lifecycle.js';
+describe('daemon-client', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        if (typeof setDaemonCommandTimeoutSeconds === 'function') {
+            setDaemonCommandTimeoutSeconds(null);
+        }
+        vi.restoreAllMocks();
+        vi.unstubAllEnvs();
+    });
+    it('fetchDaemonStatus sends the shared status request and returns parsed data', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            runtimeVersion: '1.2.3',
+            pending: 0,
+            memoryMB: 32,
+            port: 19825,
+        };
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(fetchDaemonStatus()).resolves.toEqual(status);
+        expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/status$/), expect.objectContaining({
+            headers: expect.objectContaining({ 'X-Webcmd': '1' }),
+        }));
+    });
+    it('fetchDaemonStatus returns null on network failure', async () => {
+        vi.mocked(fetch).mockRejectedValue(new Error('ECONNREFUSED'));
+        await expect(fetchDaemonStatus()).resolves.toBeNull();
+    });
+    it('requestDaemonShutdown POSTs to the shared shutdown endpoint', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({ ok: true });
+        await expect(requestDaemonShutdown()).resolves.toBe(true);
+        expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/shutdown$/), expect.objectContaining({
+            method: 'POST',
+            headers: expect.objectContaining({ 'X-Webcmd': '1' }),
+        }));
+    });
+    it('getDaemonHealth returns stopped when daemon is not reachable', async () => {
+        vi.mocked(fetch).mockRejectedValue(new Error('ECONNREFUSED'));
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'stopped', status: null });
+    });
+    it('getDaemonHealth returns no-runtime when daemon is running but runtime disconnected', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            runtimeConnected: false,
+            runtimeName: 'fake',
+            pending: 0,
+            memoryMB: 16,
+            port: 19825,
+        };
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'no-runtime', status });
+    });
+    it('getDaemonHealth returns ready when daemon and runtime are both connected', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            runtimeVersion: '1.2.3',
+            pending: 0,
+            memoryMB: 32,
+            port: 19825,
+        };
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'ready', status });
+    });
+    it('getDaemonHealth returns profile-required when multiple profiles are connected without a selection', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            runtimeConnected: false,
+            runtimeName: 'fake',
+            profileRequired: true,
+            profiles: [
+                { contextId: 'work', runtimeConnected: true, pending: 0 },
+                { contextId: 'personal', runtimeConnected: true, pending: 0 },
+            ],
+            pending: 0,
+            memoryMB: 32,
+            port: 19825,
+        };
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'profile-required', status });
+    });
+    it('fetchDaemonStatus includes contextId in the status query', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                ok: true,
+                pid: 1,
+                uptime: 0,
+                runtimeConnected: true,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 1,
+                port: 19825,
+            }),
+        });
+        await fetchDaemonStatus({ contextId: 'work' });
+        expect(vi.mocked(fetch).mock.calls[0][0]).toMatch(/\/status\?contextId=work$/);
+    });
+    it('rejects WEBCMD_DAEMON_PORT so CLI and extension cannot split bridge ports', async () => {
+        vi.resetModules();
+        vi.stubEnv('WEBCMD_DAEMON_PORT', '19999');
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                ok: true,
+                pid: 1,
+                uptime: 0,
+                runtimeConnected: true,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 1,
+                port: 19825,
+            }),
+        });
+        const freshClient = await import('./daemon-client.js');
+        await expect(freshClient.fetchDaemonStatus()).rejects.toThrow('WEBCMD_DAEMON_PORT is no longer supported');
+        expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+    });
+    it('sendCommand includes the current pid in generated command ids', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await expect(sendCommand('exec', { code: '1 + 1' })).resolves.toBe('ok');
+        await expect(sendCommand('exec', { code: '2 + 2' })).resolves.toBe('ok');
+        const ids = vi.mocked(fetch).mock.calls.map(([, init]) => {
+            const body = JSON.parse(String(init?.body));
+            return body.id;
+        });
+        expect(ids).toHaveLength(2);
+        expect(ids[0]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[0]).not.toBe(ids[1]);
+    });
+    it('sendCommand forwards WEBCMD_PROFILE as command contextId', async () => {
+        vi.stubEnv('WEBCMD_PROFILE', 'work');
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1 + 1' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body.contextId).toBe('work');
+    });
+    it('sendCommand uses explicit windowMode before WEBCMD_WINDOW env fallback', async () => {
+        vi.stubEnv('WEBCMD_WINDOW', 'foreground');
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1 + 1', windowMode: 'background' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body.windowMode).toBe('background');
+    });
+    it('sendCommand treats duplicate pending ids from an old daemon as unknown instead of minting a new id', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: false,
+            status: 409,
+            json: () => Promise.resolve({ ok: false, error: 'Duplicate command id already pending; retry' }),
+        });
+        await expect(sendCommand('exec', { code: '6 * 7' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('sendCommand does not retry command_result_unknown even when the message looks transient', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: () => Promise.resolve({
+                id: 'server',
+                ok: false,
+                errorCode: 'command_result_unknown',
+                error: 'Extension disconnected after command timeout',
+                errorHint: 'Inspect state before retrying.',
+            }),
+        });
+        await expect(sendCommand('exec', { code: 'window.__mutate = true' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+            hint: 'Inspect state before retrying.',
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('sendCommand runs full bridge ensure on a pre-dispatch failure, then resends with the same id', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_321);
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
+            health: {
+                state: 'ready',
+                status: {
+                    ok: true,
+                    pid: 1,
+                    uptime: 1,
+                    runtimeConnected: true,
+                    runtimeName: 'fake',
+                    pending: 0,
+                    memoryMB: 0,
+                    port: 19825,
+                },
+            },
+            spawnedProcess: null,
+        });
+        const fetchMock = vi.mocked(fetch);
+        fetchMock
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 503,
+            json: () => Promise.resolve({
+                ok: false,
+                errorCode: 'extension_not_connected',
+                error: 'Extension not connected.',
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 7 }),
+        });
+        await expect(sendCommand('exec', { code: '1 + 6', contextId: 'work' })).resolves.toBe(7);
+        expect(ensureSpy).toHaveBeenCalledWith(expect.objectContaining({ contextId: 'work', verbose: false }));
+        const ids = fetchMock.mock.calls.map(([, init]) => JSON.parse(String(init?.body)).id);
+        expect(ids).toHaveLength(2);
+        expect(ids[0]).toBe(ids[1]);
+    });
+    it('sendCommand runs full bridge ensure on a pre-connect TypeError before resending', async () => {
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
+            health: {
+                state: 'ready',
+                status: {
+                    ok: true,
+                    pid: 1,
+                    uptime: 1,
+                    runtimeConnected: true,
+                    runtimeName: 'fake',
+                    pending: 0,
+                    memoryMB: 0,
+                    port: 19825,
+                },
+            },
+            spawnedProcess: null,
+        });
+        const refused = new TypeError('fetch failed');
+        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:19825'), { code: 'ECONNREFUSED' });
+        const fetchMock = vi.mocked(fetch);
+        fetchMock
+            .mockRejectedValueOnce(refused)
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await expect(sendCommand('exec', { code: 'document.title' })).resolves.toBe('ok');
+        expect(ensureSpy).toHaveBeenCalledWith(expect.objectContaining({ verbose: false }));
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+    it('sendCommand does not resend a post-connect TypeError because the command may have been dispatched', async () => {
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
+            health: {
+                state: 'ready',
+                status: {
+                    ok: true,
+                    pid: 1,
+                    uptime: 1,
+                    runtimeConnected: true,
+                    runtimeName: 'fake',
+                    pending: 0,
+                    memoryMB: 0,
+                    port: 19825,
+                },
+            },
+            spawnedProcess: null,
+        });
+        const reset = new TypeError('fetch failed');
+        reset.cause = Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' });
+        vi.mocked(fetch).mockRejectedValueOnce(reset);
+        await expect(sendCommand('navigate', { url: 'https://example.com' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+        });
+        expect(ensureSpy).toHaveBeenCalledTimes(1);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('sendCommand does NOT wait when the bridge reports profile_required', async () => {
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady');
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: false,
+            status: 409,
+            json: () => Promise.resolve({
+                ok: false,
+                errorCode: 'profile_required',
+                error: 'Multiple browser runtime profiles are connected; choose one with --profile.',
+                errorHint: 'Run webcmd profile list, then webcmd profile use <name>.',
+            }),
+        });
+        await expect(sendCommand('exec', { code: '1' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'profile_required',
+        });
+        expect(ensureSpy).not.toHaveBeenCalled();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('sendCommand surfaces an AbortError as command_result_unknown without ensure or resend', async () => {
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady');
+        const abortErr = new Error('The operation was aborted');
+        abortErr.name = 'AbortError';
+        vi.mocked(fetch).mockRejectedValueOnce(abortErr);
+        await expect(sendCommand('exec', { code: 'window.__mutate = true' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+        });
+        expect(ensureSpy).not.toHaveBeenCalled();
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('sendCommand plumbs the default command timeout and absolute deadline into the request body', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 1 }),
+        });
+        await expect(sendCommand('exec', { code: '1' })).resolves.toBe(1);
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(120);
+        expect(body.deadlineAt).toBe(1_763_000_120_000);
+    });
+    it('sendCommand extends the daemon deadline past a runtime-side timeoutMs', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: { downloaded: true } }),
+        });
+        await sendCommand('wait-download', { timeoutMs: 240_000 });
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(255);
+    });
+    it('setDaemonCommandTimeoutSeconds raises the transport deadline for a user timeout', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 1 }),
+        });
+        setDaemonCommandTimeoutSeconds(300);
+        await sendCommand('exec', { code: '1' });
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(300);
+    });
+    it('client HTTP abort fires only after the daemon timeout margin', async () => {
+        vi.useFakeTimers();
+        try {
+            const fetchMock = vi.mocked(fetch);
+            let aborted = false;
+            fetchMock.mockImplementationOnce((_url, init) => new Promise((_, reject) => {
+                init?.signal?.addEventListener('abort', () => {
+                    aborted = true;
+                    reject(Object.assign(new Error('This operation was aborted'), { name: 'AbortError' }));
+                });
+            }));
+            const pending = sendCommand('exec', { code: '1' }).catch((err) => err);
+            await vi.advanceTimersByTimeAsync(120_000 + 9_999);
+            expect(aborted).toBe(false);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(aborted).toBe(true);
+            await expect(pending).resolves.toMatchObject({
+                name: 'BrowserCommandError',
+                code: 'command_result_unknown',
+            });
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/dist/src/browser/daemon-lifecycle.d.ts

@@ -0,0 +1,37 @@
+import { type ChildProcess } from 'node:child_process';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { requestDaemonShutdown, type DaemonHealth, type DaemonStatus } from './daemon-transport.js';
+export interface DaemonLaunchSpec {
+    binary: string;
+    args: string[];
+    scriptPath: string;
+}
+export interface DaemonRestartResult {
+    previousStatus: DaemonStatus | null;
+    status: DaemonStatus | null;
+    stopped: boolean;
+    spawned: boolean;
+}
+export interface EnsureBrowserBridgeReadyResult {
+    health: DaemonHealth;
+    spawnedProcess: ChildProcess | null;
+}
+export declare function resolveDaemonLaunchSpec(): DaemonLaunchSpec;
+export declare function spawnDaemonProcess(): ChildProcess;
+export declare function waitForDaemonStop(timeoutMs: number): Promise<boolean>;
+export declare function waitForDaemonStatus(timeoutMs: number): Promise<DaemonStatus | null>;
+export declare const daemonLifecycleHooks: {
+    requestDaemonShutdown: typeof requestDaemonShutdown;
+    spawnDaemonProcess: typeof spawnDaemonProcess;
+    waitForDaemonStop: typeof waitForDaemonStop;
+};
+export declare function restartDaemon(opts?: {
+    stopTimeoutMs?: number;
+    startTimeoutMs?: number;
+}): Promise<DaemonRestartResult>;
+export declare function ensureBrowserBridgeReady(opts?: {
+    timeoutSeconds?: number;
+    contextId?: string;
+    verbose?: boolean;
+}): Promise<EnsureBrowserBridgeReadyResult>;
+export { DEFAULT_DAEMON_PORT };

package/dist/src/browser/daemon-lifecycle.js

@@ -0,0 +1,147 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { BrowserConnectError } from '../errors.js';
+import { PKG_VERSION } from '../version.js';
+import { waitForBridgeReady } from './bridge-readiness.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown } from './daemon-transport.js';
+export function resolveDaemonLaunchSpec() {
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const parentDir = path.resolve(__dirname, '..');
+    const daemonTs = path.join(parentDir, 'daemon.ts');
+    const daemonJs = path.join(parentDir, 'daemon.js');
+    const isTs = fs.existsSync(daemonTs);
+    const scriptPath = isTs ? daemonTs : daemonJs;
+    return {
+        binary: process.execPath,
+        args: isTs ? ['--import', 'tsx/esm', scriptPath] : [scriptPath],
+        scriptPath,
+    };
+}
+export function spawnDaemonProcess() {
+    const launch = resolveDaemonLaunchSpec();
+    const proc = spawn(launch.binary, launch.args, {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    proc.unref();
+    return proc;
+}
+export async function waitForDaemonStop(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(200);
+        const h = await getDaemonHealth();
+        if (h.state === 'stopped')
+            return true;
+    }
+    return false;
+}
+export async function waitForDaemonStatus(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const status = await fetchDaemonStatus({ timeout: Math.min(1000, Math.max(100, deadline - Date.now())) });
+        if (status)
+            return status;
+        await sleep(200);
+    }
+    return null;
+}
+export const daemonLifecycleHooks = {
+    requestDaemonShutdown,
+    spawnDaemonProcess,
+    waitForDaemonStop,
+};
+export async function restartDaemon(opts = {}) {
+    const previousStatus = await fetchDaemonStatus();
+    let stopped = previousStatus === null;
+    if (previousStatus) {
+        const shutdownAccepted = await requestDaemonShutdown();
+        stopped = shutdownAccepted && await waitForDaemonStop(opts.stopTimeoutMs ?? 3000);
+        if (!stopped) {
+            return { previousStatus, status: previousStatus, stopped: false, spawned: false };
+        }
+    }
+    spawnDaemonProcess();
+    const status = await waitForDaemonStatus(opts.startTimeoutMs ?? 5000);
+    return { previousStatus, status, stopped, spawned: true };
+}
+export async function ensureBrowserBridgeReady(opts = {}) {
+    const timeoutSeconds = opts.timeoutSeconds && opts.timeoutSeconds > 0 ? opts.timeoutSeconds : 10;
+    const timeoutMs = timeoutSeconds * 1000;
+    const verbose = opts.verbose ?? true;
+    const contextId = opts.contextId;
+    const health = await getDaemonHealth({ contextId });
+    const daemonVersion = health.status?.daemonVersion;
+    const isStale = !!health.status && (!daemonVersion || daemonVersion !== PKG_VERSION);
+    let staleDaemonReplaced = false;
+    let spawnedProcess = null;
+    if (isStale) {
+        const reason = daemonVersion
+            ? `v${daemonVersion} ≠ v${PKG_VERSION}`
+            : `pre-version daemon, CLI is v${PKG_VERSION}`;
+        if (verbose && (process.env.WEBCMD_VERBOSE || process.stderr.isTTY)) {
+            process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
+        }
+        const shutdownAccepted = await daemonLifecycleHooks.requestDaemonShutdown();
+        let portReleased = shutdownAccepted && await daemonLifecycleHooks.waitForDaemonStop(3000);
+        if (!portReleased) {
+            const stalePid = health.status?.pid;
+            if (typeof stalePid === 'number' && Number.isInteger(stalePid) && stalePid > 0) {
+                try {
+                    process.kill(stalePid, 'SIGKILL');
+                }
+                catch {
+                    // EPERM / ESRCH are both resolved by polling the fixed daemon port.
+                }
+                portReleased = await daemonLifecycleHooks.waitForDaemonStop(2000);
+            }
+        }
+        if (!portReleased) {
+            throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down (graceful + SIGKILL both failed).\n` +
+                '  Run manually: webcmd daemon stop', 'daemon-not-running');
+        }
+        staleDaemonReplaced = true;
+    }
+    if (!staleDaemonReplaced && health.state === 'ready') {
+        return { health, spawnedProcess };
+    }
+    if (!staleDaemonReplaced && health.state === 'profile-required') {
+        throw browserConnectErrorFromHealth(health, contextId);
+    }
+    if (staleDaemonReplaced || health.state === 'stopped') {
+        if (verbose && (process.env.WEBCMD_VERBOSE || process.stderr.isTTY)) {
+            process.stderr.write('⏳ Starting daemon...\n');
+        }
+        spawnedProcess = daemonLifecycleHooks.spawnDaemonProcess();
+    }
+    else if (verbose && (process.env.WEBCMD_VERBOSE || process.stderr.isTTY)) {
+        process.stderr.write('⏳ Waiting for Cloak runtime to connect...\n');
+        process.stderr.write('   Make sure Chrome or Chromium is open and Cloak is enabled.\n');
+    }
+    const finalHealth = await waitForBridgeReady(getDaemonHealth, { timeoutMs, contextId });
+    if (finalHealth.state === 'ready')
+        return { health: finalHealth, spawnedProcess };
+    throw browserConnectErrorFromHealth(finalHealth, contextId);
+}
+function browserConnectErrorFromHealth(health, contextId) {
+    if (health.state === 'profile-required') {
+        return new BrowserConnectError('Multiple browser profiles are connected', 'Select one with --profile <name>, WEBCMD_PROFILE=<name>, or webcmd profile use <name>.\n' +
+            'Run webcmd profile list to see connected profiles.', 'profile-required');
+    }
+    if (health.state === 'profile-disconnected') {
+        const label = contextId ?? health.status.contextId ?? 'unknown';
+        return new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure Cloak is enabled, or choose another profile with webcmd profile use <name>.', 'profile-disconnected');
+    }
+    if (health.state === 'no-runtime') {
+        return new BrowserConnectError('Browser runtime is not ready', 'Run `webcmd daemon restart`. If CloakBrowser is downloading its browser binary, wait for it to finish and retry.', 'runtime-not-ready');
+    }
+    return new BrowserConnectError('Failed to start webcmd daemon', `Try running manually:\n  node ${resolveDaemonLaunchSpec().scriptPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export { DEFAULT_DAEMON_PORT };

package/dist/src/browser/daemon-transport.d.ts

@@ -0,0 +1,54 @@
+export interface DaemonStatus {
+    ok: boolean;
+    pid: number;
+    uptime: number;
+    daemonVersion?: string;
+    runtimeConnected: boolean;
+    runtimeName: string;
+    runtimeVersion?: string;
+    contextId?: string;
+    profileRequired?: boolean;
+    profileDisconnected?: boolean;
+    profiles?: BrowserProfileStatus[];
+    pending: number;
+    commandResultUnknown?: number;
+    memoryMB: number;
+    port: number;
+}
+export interface BrowserProfileStatus {
+    contextId: string;
+    runtimeConnected: boolean;
+    runtimeVersion?: string;
+    pending: number;
+    lastSeenAt?: number;
+}
+export type DaemonHealth = {
+    state: 'stopped';
+    status: null;
+} | {
+    state: 'no-runtime';
+    status: DaemonStatus;
+} | {
+    state: 'profile-required';
+    status: DaemonStatus;
+} | {
+    state: 'profile-disconnected';
+    status: DaemonStatus;
+} | {
+    state: 'ready';
+    status: DaemonStatus;
+};
+export declare function requestDaemon(pathname: string, init?: RequestInit & {
+    timeout?: number;
+}): Promise<Response>;
+export declare function fetchDaemonStatus(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonStatus | null>;
+export declare function getDaemonHealth(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonHealth>;
+export declare function requestDaemonShutdown(opts?: {
+    timeout?: number;
+}): Promise<boolean>;