@phnx-labs/agents-cli 1.18.3 → 1.18.5

package/dist/lib/browser/ipc.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getHelpersDir } from '../state.js';
 import { startDaemon } from '../daemon.js';
+import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
 export function getSocketPath() {
     return path.join(getHelpersDir(), SOCKET_NAME);
@@ -63,6 +64,9 @@ export class BrowserIPCServer {
     }
     async handleRequest(request) {
         switch (request.action) {
+            case 'version': {
+                return { ok: true, version: getCliVersion() };
+            }
             case 'start': {
                 if (!request.profile) {
                     return { ok: false, error: 'Profile required' };
@@ -70,6 +74,7 @@ export class BrowserIPCServer {
                 const result = await this.service.start(request.profile, {
                     taskName: request.taskName,
                     url: request.url,
+                    endpointName: request.endpoint,
                 });
                 return {
                     ok: true,
@@ -78,13 +83,6 @@ export class BrowserIPCServer {
                     windowTargetId: result.windowId,
                 };
             }
-            case 'launch-profile': {
-                if (!request.profile) {
-                    return { ok: false, error: 'Profile required' };
-                }
-                const result = await this.service.launchProfile(request.profile);
-                return { ok: true, port: result.port, pid: result.pid };
-            }
             case 'done': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
@@ -153,12 +151,38 @@ export class BrowserIPCServer {
                 const result = await this.service.evaluate(request.task, request.tabId, request.expr);
                 return { ok: true, result };
             }
+            case 'record-start': {
+                if (!request.task)
+                    return { ok: false, error: 'Task required' };
+                try {
+                    const r = await this.service.recordStart(request.task, request.tabId, {
+                        fps: request.fps,
+                        duration: request.duration,
+                        maxMb: request.maxMb,
+                    });
+                    return { ok: true, path: r.path, fps: r.fps, durationCapSec: r.durationCapSec, maxMb: r.maxMb };
+                }
+                catch (err) {
+                    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+            case 'record-stop': {
+                if (!request.task)
+                    return { ok: false, error: 'Task required' };
+                try {
+                    const r = await this.service.recordStop(request.task);
+                    return { ok: true, path: r.path, bytes: r.bytes, durationMs: r.durationMs, stopReason: r.reason };
+                }
+                catch (err) {
+                    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
             case 'screenshot': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
                 }
-                const resultPath = await this.service.screenshot(request.task, request.tabId, request.path);
-                return { ok: true, path: resultPath };
+                const shot = await this.service.screenshot(request.task, request.tabId, request.path, request.quality);
+                return { ok: true, path: shot.path, bytes: shot.bytes, width: shot.width, height: shot.height };
             }
             case 'refs': {
                 if (!request.task) {
@@ -296,6 +320,21 @@ export class BrowserIPCServer {
                 const downloadPath = await this.service.waitForDownload(request.task, request.timeout);
                 return { ok: true, downloadPath };
             }
+            case 'getAppLogs': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const appLogs = await this.service.getAppLogs(request.task, {
+                    lines: request.lines,
+                    level: request.appLevel,
+                    filter: request.filter,
+                    message: request.message,
+                    source: request.source,
+                    since: request.since,
+                    until: request.until,
+                });
+                return { ok: true, appLogs };
+            }
             case 'upload': {
                 if (!request.task || !request.files || request.files.length === 0) {
                     return { ok: false, error: 'Task and at least one file required' };
@@ -314,7 +353,43 @@ export class BrowserIPCServer {
         }
     }
 }
+let versionCheckedThisProcess = false;
+/**
+ * Check the daemon's version against ours and warn loudly when they
+ * differ. Fires at most once per CLI process — successive calls in the
+ * same `agents browser ...` invocation are cheap. The whole reason this
+ * code exists: a launchd-managed registry daemon kept serving stale code
+ * to a dev-build CLI for an entire session and nothing surfaced it.
+ */
+async function maybeWarnVersionMismatch() {
+    if (versionCheckedThisProcess)
+        return;
+    versionCheckedThisProcess = true;
+    try {
+        const resp = await sendRawIPCRequest({ action: 'version' });
+        const daemon = resp.version;
+        const client = getCliVersion();
+        if (!daemon || daemon === 'unknown' || daemon === client)
+            return;
+        process.stderr.write(`\nwarning: browser daemon is on ${daemon} but this CLI is on ${client}.\n` +
+            `         Run \`agents daemon restart\` to load the current code.\n\n`);
+    }
+    catch {
+        // daemon might be an older build that doesn't speak 'version' — that's
+        // itself a hint, but a noisy one. Stay silent on this path.
+    }
+}
 export async function sendIPCRequest(request) {
+    const result = await sendRawIPCRequest(request);
+    // Run the version check after the user's request returns — keeps the
+    // critical path zero-overhead and ensures `start` doesn't get blocked
+    // on a daemon-restart warning that the user hasn't read yet.
+    if (request.action !== 'version') {
+        maybeWarnVersionMismatch().catch(() => { });
+    }
+    return result;
+}
+async function sendRawIPCRequest(request) {
     const socketPath = getSocketPath();
     if (!fs.existsSync(socketPath)) {
         await fs.promises.mkdir(path.dirname(socketPath), { recursive: true });

package/dist/lib/browser/profiles.d.ts

@@ -5,15 +5,81 @@ export declare function getProfileRuntimeDir(name: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**
- * Find a port in 9222–9399 that is not already claimed by another profile
- * and is not currently in use by any OS process.
+ * Compute the LOCAL port a profile will occupy at runtime:
+ *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
+ *   - `ssh://host?port=N` → N (the SSH tunnel binds local N → remote N now)
+ *   - `ws[s]://`, `http[s]://` → undefined (we don't claim a local port)
+ *
+ * This is what callers should compare to detect collisions; the (host,
+ * port) tuple is no longer enough because SSH profiles do compete with
+ * cdp:// profiles for local ports under the new tunnel scheme.
+ */
+export declare function effectiveLocalPort(profile: BrowserProfile): number | undefined;
+/**
+ * Find a port in 9222–9399 that is not already claimed by ANY existing
+ * profile (cdp:// or ssh://) and is not in use by any OS process. The
+ * SSH change to bind locally on `?port=N` means we no longer get to
+ * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
 export declare function createProfile(profile: BrowserProfile): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
 export declare function deleteProfile(name: string): Promise<void>;
 /**
- * Extract the port intended by the profile's first endpoint.
+ * Resolve a profile's endpoint presets into a normalized map regardless of
+ * whether the YAML uses the legacy `string[]` shape or the new map shape.
+ * The legacy entries get auto-named `endpoint-0`, `endpoint-1`, ... .
+ */
+export declare function getEndpointPresets(profile: BrowserProfile): Record<string, import('./types.js').EndpointPreset>;
+/**
+ * Pick the endpoint preset to use. Order:
+ *   1. Explicit name passed in (errors if unknown)
+ *   2. `profile.defaultEndpoint` if set
+ *   3. First entry (preserves legacy string[] behavior)
+ *
+ * Returns the resolved name + the preset (with per-endpoint overrides
+ * already applied to binary / targetFilter), so callers don't have to
+ * remember the precedence rules.
+ */
+export declare function resolveEndpoint(profile: BrowserProfile, endpointName?: string): {
+    name: string;
+    target: string;
+    binary?: string;
+    targetFilter?: string;
+};
+/**
+ * Extract the (host, port) pair intended by the profile's default endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Ports are scoped by host: a `cdp://127.0.0.1:9222` profile (local Chrome on
+ * this machine) and an `ssh://mac-mini:9222` profile (Comet on mac-mini)
+ * point at different physical ports — the host disambiguates them.
+ *
+ * Accepts both `scheme://host:port` and `scheme://host?port=N` shapes (the
+ * latter is the documented form in `types.ts` for `ssh://`). Without this,
+ * `ssh://mac-mini?port=18805` would silently fall back to 9222 and every
+ * `?port=`-style SSH profile would collide on creation.
+ */
+export declare function extractConfiguredEndpoint(profile: BrowserProfile): {
+    host: string;
+    port: number;
+} | undefined;
+/**
+ * Shared endpoint parser used by both the collision-detection code path and
+ * the connection drivers. Returning a single normalized `(host, port)` here
+ * keeps `extractConfiguredEndpoint` and the SSH driver from drifting on URL
+ * conventions (which is how `?port=N` ended up being silently ignored).
+ */
+export declare function parseEndpointUrl(endpoint: string): {
+    host: string;
+    port: number;
+} | undefined;
+/**
+ * Extract the port intended by the profile's default endpoint.
  * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Note: this loses the host dimension — for collision detection use
+ * `extractConfiguredEndpoint` instead, which returns the (host, port) pair.
  */
 export declare function extractConfiguredPort(profile: BrowserProfile): number | undefined;
+export declare function isLocalHost(host: string): boolean;

package/dist/lib/browser/profiles.js

@@ -17,9 +17,12 @@ function configToProfile(name, config) {
         electron: config.electron,
         targetFilter: config.targetFilter,
         endpoints: config.endpoints,
+        defaultEndpoint: config.defaultEndpoint,
         chrome: config.chrome,
         secrets: config.secrets,
         viewport: config.viewport,
+        logDir: config.logDir,
+        logHost: config.logHost,
     };
 }
 function profileToConfig(profile) {
@@ -35,12 +38,18 @@ function profileToConfig(profile) {
         config.electron = profile.electron;
     if (profile.targetFilter)
         config.targetFilter = profile.targetFilter;
+    if (profile.defaultEndpoint)
+        config.defaultEndpoint = profile.defaultEndpoint;
     if (profile.chrome)
         config.chrome = profile.chrome;
     if (profile.secrets)
         config.secrets = profile.secrets;
     if (profile.viewport)
         config.viewport = profile.viewport;
+    if (profile.logDir)
+        config.logDir = profile.logDir;
+    if (profile.logHost)
+        config.logHost = profile.logHost;
     return config;
 }
 export async function listProfiles() {
@@ -57,14 +66,45 @@ export async function getProfile(name) {
     return configToProfile(name, config);
 }
 /**
- * Find a port in 9222–9399 that is not already claimed by another profile
- * and is not currently in use by any OS process.
+ * Compute the LOCAL port a profile will occupy at runtime:
+ *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
+ *   - `ssh://host?port=N` → N (the SSH tunnel binds local N → remote N now)
+ *   - `ws[s]://`, `http[s]://` → undefined (we don't claim a local port)
+ *
+ * This is what callers should compare to detect collisions; the (host,
+ * port) tuple is no longer enough because SSH profiles do compete with
+ * cdp:// profiles for local ports under the new tunnel scheme.
+ */
+export function effectiveLocalPort(profile) {
+    const presets = getEndpointPresets(profile);
+    const firstName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
+        ? profile.defaultEndpoint
+        : Object.keys(presets)[0];
+    if (!firstName)
+        return undefined;
+    const target = presets[firstName].target;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'cdp:' && url.protocol !== 'ssh:')
+        return undefined;
+    return parseEndpointUrl(target)?.port;
+}
+/**
+ * Find a port in 9222–9399 that is not already claimed by ANY existing
+ * profile (cdp:// or ssh://) and is not in use by any OS process. The
+ * SSH change to bind locally on `?port=N` means we no longer get to
+ * skip remote profiles in this scan.
  */
 export async function findFreeProfilePort() {
     const profiles = await listProfiles();
     const usedByProfile = new Set();
     for (const p of profiles) {
-        const port = extractConfiguredPort(p);
+        const port = effectiveLocalPort(p);
         if (port !== undefined)
             usedByProfile.add(port);
     }
@@ -87,15 +127,20 @@ export async function createProfile(profile) {
     if (meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
-    // Check for port collision with existing profiles
-    const newPort = extractConfiguredPort(profile);
-    if (newPort !== undefined && meta.browser) {
+    // Collision check. Every CDP/SSH profile ends up listening on (or
+    // tunneling to) the same LOCAL port number as the one configured in the
+    // endpoint URL — SSH profiles now reuse `?port=N` locally so we no
+    // longer need to scope by host. Two profiles that would need the same
+    // local port can't both run at the same time.
+    const newLocal = effectiveLocalPort(profile);
+    if (newLocal !== undefined && meta.browser) {
         for (const [existingName, existingConfig] of Object.entries(meta.browser)) {
             const existingProfile = configToProfile(existingName, existingConfig);
-            const existingPort = extractConfiguredPort(existingProfile);
-            if (existingPort === newPort) {
-                throw new Error(`Port ${newPort} is already used by profile "${existingName}". ` +
-                    `Each profile must own a unique port. Use a different port or omit --endpoint to auto-assign.`);
+            const existingLocal = effectiveLocalPort(existingProfile);
+            if (existingLocal === newLocal) {
+                throw new Error(`Local port ${newLocal} is already used by profile "${existingName}". ` +
+                    `Each profile must own a unique local port (SSH tunnels now bind ` +
+                    `to their configured port locally too). Pick a different port.`);
             }
         }
     }
@@ -125,13 +170,87 @@ export async function deleteProfile(name) {
     writeMeta(meta);
 }
 /**
- * Extract the port intended by the profile's first endpoint.
+ * Resolve a profile's endpoint presets into a normalized map regardless of
+ * whether the YAML uses the legacy `string[]` shape or the new map shape.
+ * The legacy entries get auto-named `endpoint-0`, `endpoint-1`, ... .
+ */
+export function getEndpointPresets(profile) {
+    if (Array.isArray(profile.endpoints)) {
+        const out = {};
+        profile.endpoints.forEach((target, i) => {
+            out[`endpoint-${i}`] = { target };
+        });
+        return out;
+    }
+    return profile.endpoints;
+}
+/**
+ * Pick the endpoint preset to use. Order:
+ *   1. Explicit name passed in (errors if unknown)
+ *   2. `profile.defaultEndpoint` if set
+ *   3. First entry (preserves legacy string[] behavior)
+ *
+ * Returns the resolved name + the preset (with per-endpoint overrides
+ * already applied to binary / targetFilter), so callers don't have to
+ * remember the precedence rules.
+ */
+export function resolveEndpoint(profile, endpointName) {
+    const presets = getEndpointPresets(profile);
+    const names = Object.keys(presets);
+    if (names.length === 0) {
+        throw new Error(`Profile "${profile.name}" has no endpoints configured`);
+    }
+    let chosenName;
+    if (endpointName) {
+        if (!presets[endpointName]) {
+            throw new Error(`Endpoint "${endpointName}" not found on profile "${profile.name}". ` +
+                `Available: ${names.join(', ')}`);
+        }
+        chosenName = endpointName;
+    }
+    else if (profile.defaultEndpoint && presets[profile.defaultEndpoint]) {
+        chosenName = profile.defaultEndpoint;
+    }
+    else {
+        chosenName = names[0];
+    }
+    const preset = presets[chosenName];
+    return {
+        name: chosenName,
+        target: preset.target,
+        binary: preset.binary ?? profile.binary,
+        targetFilter: preset.targetFilter ?? profile.targetFilter,
+    };
+}
+/**
+ * Extract the (host, port) pair intended by the profile's default endpoint.
  * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Ports are scoped by host: a `cdp://127.0.0.1:9222` profile (local Chrome on
+ * this machine) and an `ssh://mac-mini:9222` profile (Comet on mac-mini)
+ * point at different physical ports — the host disambiguates them.
+ *
+ * Accepts both `scheme://host:port` and `scheme://host?port=N` shapes (the
+ * latter is the documented form in `types.ts` for `ssh://`). Without this,
+ * `ssh://mac-mini?port=18805` would silently fall back to 9222 and every
+ * `?port=`-style SSH profile would collide on creation.
  */
-export function extractConfiguredPort(profile) {
-    const endpoint = profile.endpoints[0];
-    if (!endpoint)
+export function extractConfiguredEndpoint(profile) {
+    const presets = getEndpointPresets(profile);
+    const firstName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
+        ? profile.defaultEndpoint
+        : Object.keys(presets)[0];
+    if (!firstName)
         return undefined;
+    return parseEndpointUrl(presets[firstName].target);
+}
+/**
+ * Shared endpoint parser used by both the collision-detection code path and
+ * the connection drivers. Returning a single normalized `(host, port)` here
+ * keeps `extractConfiguredEndpoint` and the SSH driver from drifting on URL
+ * conventions (which is how `?port=N` ended up being silently ignored).
+ */
+export function parseEndpointUrl(endpoint) {
     let url;
     try {
         url = new URL(endpoint);
@@ -139,11 +258,56 @@ export function extractConfiguredPort(profile) {
     catch {
         return undefined;
     }
-    if (url.port)
-        return parseInt(url.port, 10);
-    if (url.protocol === 'cdp:')
-        return 9222;
-    if (url.protocol === 'ssh:')
-        return 9222;
+    const host = normalizeHost(url.hostname, url.protocol);
+    if (!host)
+        return undefined;
+    const port = extractPortFromUrl(url);
+    if (port !== undefined)
+        return { host, port };
+    // SSH endpoints tunnel to a remote port AND bind that same port locally,
+    // so they do "own" a local port — the host-scoped collision check used
+    // to disagree, but we want the local-port-scoped semantics now.
+    if (url.protocol === 'cdp:' || url.protocol === 'ssh:')
+        return { host, port: 9222 };
     return undefined;
 }
+function extractPortFromUrl(url) {
+    if (url.port) {
+        const n = parseInt(url.port, 10);
+        if (Number.isFinite(n))
+            return n;
+    }
+    // `scheme://host?port=N` — the form documented for SSH endpoints in
+    // `types.ts`. WHATWG URL parsing surfaces it via searchParams only.
+    const qp = url.searchParams.get('port');
+    if (qp) {
+        const n = parseInt(qp, 10);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+/**
+ * Extract the port intended by the profile's default endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Note: this loses the host dimension — for collision detection use
+ * `extractConfiguredEndpoint` instead, which returns the (host, port) pair.
+ */
+export function extractConfiguredPort(profile) {
+    return extractConfiguredEndpoint(profile)?.port;
+}
+function normalizeHost(hostname, protocol) {
+    if (!hostname) {
+        // cdp:// and ssh:// without an explicit host imply localhost.
+        if (protocol === 'cdp:' || protocol === 'ssh:')
+            return '127.0.0.1';
+        return undefined;
+    }
+    if (hostname === 'localhost')
+        return '127.0.0.1';
+    return hostname;
+}
+export function isLocalHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}

package/dist/lib/browser/runtime-state.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Per-profile runtime files we persist under
+ * `~/.agents/.cache/browser/<composite>/`:
+ *
+ *  - `pid`     — child process ID we spawned (or 0 if attached to an
+ *                already-running browser)
+ *  - `port`    — CDP port we ended up speaking on
+ *  - `command` — basename of the executable so we can defend against pid
+ *                reuse (`process.kill(pid, 0)` only proves *some* process
+ *                with that id exists; if the OS recycled it for an
+ *                unrelated daemon, we'd happily attach to garbage)
+ *  - `meta.json` — richer record: which daemon spawned us, when, the
+ *                user-data-dir we wrote into, optional tunnel PID. This
+ *                is the file the orphan reaper reads on daemon startup.
+ *  - `tasks.json` — open task state (managed elsewhere by service.ts)
+ *
+ * The one-value-per-file fields are kept for backward compat with older
+ * builds; `meta.json` is additive and consulted preferentially.
+ */
+export interface ProfileRuntime {
+    pid: number;
+    port: number;
+    command?: string;
+    /** Full path of the user-data-dir we passed to --user-data-dir, used by the reaper to confirm. */
+    userDataDir?: string;
+    /** PID of the daemon that spawned this. When the daemon dies, the next one reaps. */
+    daemonPid?: number;
+    /** Wall-clock time of spawn — useful for diagnostics and TTL-based cleanup. */
+    spawnedAt?: number;
+    /** What kind of process: 'browser' (Chrome-family), 'electron' (Notion etc.), or 'tunnel' (ssh -L). */
+    kind?: 'browser' | 'electron' | 'tunnel';
+    /** Local ssh -L PID, if this profile is SSH-backed. Distinct from `pid` (which is the remote browser, normally 0). */
+    tunnelPid?: number;
+}
+/**
+ * Save the runtime record atomically. We write the legacy one-value-per-
+ * file fields plus a JSON meta blob so future code can read either.
+ * The cache directory may not exist yet (first launch); we create it.
+ */
+export declare function writeProfileRuntime(profileName: string, runtime: ProfileRuntime): void;
+/** Read just the JSON meta record. Returns null when absent or malformed. */
+export declare function readProfileRuntimeMeta(profileName: string): ProfileRuntime | null;
+/**
+ * Read the runtime triple. Returns null when the files are missing OR when
+ * the recorded pid no longer points at the same process we launched —
+ * stale data is auto-cleaned to keep the next caller from acting on it.
+ */
+export declare function readProfileRuntime(profileName: string): ProfileRuntime | null;
+/** Remove the pid/port/command/meta files. Leaves chrome-data + tasks.json intact. */
+export declare function clearProfileRuntime(profileName: string): void;
+/**
+ * Recursively remove the whole profile cache (chrome-data, tasks.json,
+ * everything). Used by `profiles delete` so an old profile name doesn't
+ * leak its history into a freshly-recreated one.
+ */
+export declare function removeProfileCache(profileName: string): void;
+/**
+ * Find every cache directory belonging to a given profile. The composite
+ * naming (`<name>@<endpoint>`) means a single agents-cli profile can have
+ * multiple runtime dirs side by side; this finds them all plus the legacy
+ * non-composite dir from older builds.
+ */
+export declare function listProfileCacheDirs(profileName: string): string[];
+/**
+ * `process.kill(pid, 0)` answers "is a process with this id alive?" — but
+ * pid reuse is real on long-uptime machines, and a stale cache pointing
+ * at a since-reassigned pid would happily call the imposter ours.
+ *
+ * Strategy: if we recorded the executable basename when we launched, ask
+ * `ps` what command the live pid is running and compare. No command on
+ * record means we fall back to the existence check (older cache entries
+ * or `pid:0` for "attached to an externally-launched browser").
+ */
+export declare function isProcessAlive(pid: number, expectedCommand?: string): boolean;
+/**
+ * Snapshot of one tracked profile, suitable for `agents browser ps` output.
+ * Combines the on-disk meta record with live-process probes so callers can
+ * tell at a glance which entries are alive, stale, or have outright leaked.
+ */
+export interface ProfileSnapshot {
+    /** Composite name as the cache dir is keyed: `<profile>` or `<profile>@<endpoint>`. */
+    name: string;
+    /** Absolute path of the cache dir. */
+    dir: string;
+    meta: ProfileRuntime | null;
+    /** Live-process probe: does the recorded pid still exist + match command? */
+    pidAlive: boolean;
+    /** Live-process probe for the tunnel pid (SSH profiles). */
+    tunnelAlive: boolean;
+    /** True iff the daemon that started this is still alive. False == orphaned. */
+    daemonAlive: boolean;
+    /** Number of tasks recorded in tasks.json (open browser tabs). */
+    taskCount: number;
+}
+/**
+ * Read every profile cache directory and produce a structured snapshot.
+ * Works without the daemon — `agents browser ps` uses this to render a
+ * complete state view even when the IPC server is down. The caller can
+ * post-process to detect conflicts (e.g. two profiles with the same port,
+ * or a port someone else is listening on).
+ */
+export declare function listAllProfileSnapshots(): ProfileSnapshot[];
+/**
+ * Reap browser + tunnel processes spawned by daemons that no longer exist.
+ * Call once on daemon startup. The idea: every process we spawn records
+ * its daemonPid in meta.json. If that daemon is dead (crashed, SIGKILL),
+ * its children were left rootless — kill them now so they don't hijack
+ * the next session's local ports.
+ *
+ * We're conservative: a record with no daemonPid (older builds) is left
+ * alone — we'd rather leak than wrongly kill a user-owned process that
+ * happens to share metadata.
+ */
+export declare function reapOrphanedProcesses(): {
+    reaped: number;
+    details: string[];
+};