aegis-bridge 0.1.0

package/dist/ssrf.js

@@ -0,0 +1,267 @@
+/**
+ * ssrf.ts — Shared SSRF (Server-Side Request Forgery) prevention utilities.
+ *
+ * Validates URLs by checking scheme, hostname, and DNS resolution against
+ * private/internal IP ranges. Used by webhook channel and screenshot endpoint.
+ */
+import dns from 'node:dns/promises';
+import net from 'node:net';
+/**
+ * Check if an IP address (v4 or v6) is private/internal.
+ *
+ * Rejects:
+ * - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ * - Loopback: 127.0.0.0/8, ::1
+ * - Link-local: 169.254.0.0/16, fe80::/10
+ * - Current network: 0.0.0.0/8
+ * - Unspecified: ::
+ * - IPv6 unique-local: fc00::/7
+ * - IPv4-mapped IPv6: ::ffff:x.x.x.x (RFC 4291)
+ * - IPv4-compatible IPv6: ::x.x.x.x (deprecated)
+ * - CGNAT: 100.64.0.0/10 (RFC 6598)
+ * - Broadcast: 255.255.255.255
+ * - Multicast: 224.0.0.0/4 (RFC 5771)
+ * - Documentation: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737)
+ * - Benchmarking: 198.18.0.0/15 (RFC 2544)
+ */
+export function isPrivateIP(ip) {
+    // IPv4
+    if (net.isIPv4(ip)) {
+        const parts = ip.split('.').map(Number);
+        const [a, b, c] = parts;
+        // 0.0.0.0/8
+        if (a === 0)
+            return true;
+        // 10.0.0.0/8
+        if (a === 10)
+            return true;
+        // 127.0.0.0/8
+        if (a === 127)
+            return true;
+        // 169.254.0.0/16
+        if (a === 169 && b === 254)
+            return true;
+        // 172.16.0.0/12
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        // 192.168.0.0/16
+        if (a === 192 && b === 168)
+            return true;
+        // 100.64.0.0/10 (CGNAT)
+        if (a === 100 && b >= 64 && b <= 127)
+            return true;
+        // 255.255.255.255 (broadcast)
+        if (a === 255 && b === 255 && c === 255 && parts[3] === 255)
+            return true;
+        // 224.0.0.0/4 (multicast) — 224.0.0.0 to 239.255.255.255
+        if (a >= 224 && a <= 239)
+            return true;
+        // 192.0.2.0/24 (documentation, RFC 5737)
+        if (a === 192 && b === 0 && c === 2)
+            return true;
+        // 198.51.100.0/24 (documentation, RFC 5737)
+        if (a === 198 && b === 51 && c === 100)
+            return true;
+        // 203.0.113.0/24 (documentation, RFC 5737)
+        if (a === 203 && b === 0 && c === 113)
+            return true;
+        // 198.18.0.0/15 (benchmarking, RFC 2544) — 198.18.0.0 to 198.19.255.255
+        if (a === 198 && b >= 18 && b <= 19)
+            return true;
+        return false;
+    }
+    // IPv6
+    const lower = ip.toLowerCase();
+    // IPv4-mapped IPv6 (::ffff:x.x.x.x, RFC 4291 §2.5.5)
+    // Handles dotted-quad form (::ffff:127.0.0.1) and hex form (::ffff:7f00:1).
+    // Also handles IPv4-compatible IPv6 (::x.x.x.x, deprecated).
+    if (lower.startsWith('::ffff:')) {
+        const suffix = lower.slice(7);
+        // Dotted quad form: ::ffff:127.0.0.1
+        if (net.isIPv4(suffix)) {
+            return isPrivateIP(suffix);
+        }
+        // Hex form: ::ffff:7f00:1 → parse last 32 bits as IPv4
+        const hexGroups = suffix.split(':').map(h => parseInt(h, 16));
+        if (hexGroups.length === 2 && hexGroups.every(n => !isNaN(n))) {
+            const embedded = `${(hexGroups[0] >> 8) & 0xff}.${hexGroups[0] & 0xff}.${(hexGroups[1] >> 8) & 0xff}.${hexGroups[1] & 0xff}`;
+            if (net.isIPv4(embedded)) {
+                return isPrivateIP(embedded);
+            }
+        }
+    }
+    // IPv4-compatible IPv6 (::x.x.x.x, deprecated RFC 4291 §2.5.5)
+    const afterPrefix = lower.startsWith('::') && lower !== '::' && lower !== '::1' ? lower.slice(2) : null;
+    if (afterPrefix !== null && net.isIPv4(afterPrefix)) {
+        return isPrivateIP(afterPrefix);
+    }
+    // ::1 (loopback)
+    if (lower === '::1')
+        return true;
+    // :: (unspecified)
+    if (lower === '::')
+        return true;
+    // fe80::/10 (link-local)
+    if (lower.startsWith('fe8') || lower.startsWith('fe9') || lower.startsWith('fea') || lower.startsWith('feb'))
+        return true;
+    // fc00::/7 (unique-local) — includes fc and fd prefixes
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true;
+    return false;
+}
+/**
+ * Validate a URL for webhook configuration.
+ *
+ * Checks:
+ * 1. Valid URL format
+ * 2. HTTPS scheme required for external hosts
+ * 3. HTTP allowed only for localhost / 127.0.0.1
+ * 4. Rejects private/internal IP addresses (except 127.0.0.1 in dev mode)
+ * 5. Rejects *.local hostnames
+ *
+ * Returns null if valid, or an error string if invalid.
+ */
+export function validateWebhookUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch { /* malformed URL string */
+        return 'Invalid URL';
+    }
+    const hostname = parsed.hostname;
+    // Strip brackets from IPv6 URLs: [::1] → ::1
+    const bareHost = hostname.replace(/^\[|\]$/g, '');
+    // Scheme check — must be HTTPS, or HTTP only for local dev
+    const isLocalDev = bareHost === '127.0.0.1' || bareHost === '::1' || bareHost === 'localhost';
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && isLocalDev)) {
+        if (parsed.protocol === 'http:') {
+            return 'Only HTTPS URLs are allowed for external hosts';
+        }
+        return 'Only HTTPS URLs are allowed';
+    }
+    // Reject *.local hostnames (but allow literal localhost for dev)
+    if (bareHost.endsWith('.local')) {
+        return 'Localhost URLs are not allowed';
+    }
+    // Reject private/internal IPs (except 127.0.0.1/::1 which are allowed for dev over HTTP)
+    if (net.isIP(bareHost) && isPrivateIP(bareHost) && !isLocalDev) {
+        return 'Private/internal IP addresses are not allowed';
+    }
+    return null;
+}
+/** Default DNS lookup using node:dns/promises with { all: true } to resolve all addresses. */
+const defaultLookup = (hostname) => dns.lookup(hostname, { all: true });
+/**
+ * Resolve a hostname via DNS and check if the resulting IP is private/internal.
+ *
+ * For literal IP addresses, checks directly without DNS resolution.
+ * Returns a DnsCheckResult with error string if unsafe, or the resolved IP on success.
+ *
+ * The resolved IP should be used with Chromium --host-resolver-rules to pin the
+ * address and prevent DNS rebinding (TOCTOU) attacks between validation and page.goto().
+ *
+ * @param hostname - Hostname or literal IP to check
+ * @param lookupFn - Optional DNS lookup function (for testing)
+ */
+export async function resolveAndCheckIp(hostname, lookupFn = defaultLookup) {
+    // Literal IP — check directly
+    if (net.isIP(hostname)) {
+        if (isPrivateIP(hostname)) {
+            return { error: `DNS resolution points to a private/internal IP: ${hostname}`, resolvedIp: null };
+        }
+        return { error: null, resolvedIp: hostname };
+    }
+    try {
+        const results = await lookupFn(hostname);
+        if (results.length === 0) {
+            return { error: `DNS resolution returned no addresses for ${hostname}`, resolvedIp: null };
+        }
+        // Check ALL resolved addresses — reject if ANY is private/internal.
+        // An attacker can configure DNS to return both public and private IPs;
+        // the HTTP client may connect to any of them.
+        for (const result of results) {
+            if (isPrivateIP(result.address)) {
+                return { error: `DNS resolution points to a private/internal IP: ${result.address}`, resolvedIp: null };
+            }
+        }
+        // All addresses safe — return first for TOCTOU-safe pinning via --host-resolver-rules.
+        return { error: null, resolvedIp: results[0].address };
+    }
+    catch { /* DNS lookup failed — treat as unsafe */
+        return { error: `DNS resolution failed for ${hostname}`, resolvedIp: null };
+    }
+}
+/**
+ * Build Chromium --host-resolver-rules argument to pin a hostname to a specific IP.
+ *
+ * This prevents DNS rebinding (TOCTOU) attacks between SSRF validation and page.goto()
+ * by ensuring Chromium resolves the hostname to the same IP that was validated.
+ *
+ * @param hostname - The original hostname from the URL
+ * @param resolvedIp - The IP address that was validated as safe
+ * @returns The --host-resolver-rules argument string
+ */
+export function buildHostResolverRule(hostname, resolvedIp) {
+    return `MAP ${hostname} ${resolvedIp}`;
+}
+/**
+ * Build a connection URL where the hostname is replaced by the resolved IP address.
+ *
+ * This prevents DNS rebinding (TOCTOU) attacks in HTTP clients (like Node fetch)
+ * by ensuring the connection goes to the validated IP, not a re-resolved address.
+ * The original hostname is returned separately so callers can set the Host header.
+ *
+ * For IPv6 addresses, wraps the IP in brackets per RFC 2732.
+ *
+ * @param originalUrl - The original URL (e.g. "https://example.com/path")
+ * @param resolvedIp - The validated IP address to connect to
+ * @returns Object with the connection URL and the original hostname for Host header
+ */
+export function buildConnectionUrl(originalUrl, resolvedIp) {
+    const parsed = new URL(originalUrl);
+    const originalHost = parsed.host; // includes port if non-default
+    // IPv6 literals need brackets in URLs
+    const ipForUrl = parsed.hostname.startsWith('[') || resolvedIp.includes(':')
+        ? `[${resolvedIp}]`
+        : resolvedIp;
+    parsed.hostname = ipForUrl;
+    return { connectionUrl: parsed.toString(), hostHeader: originalHost };
+}
+/**
+ * Validate a URL for the screenshot endpoint to prevent SSRF attacks.
+ *
+ * Checks:
+ * 1. Valid URL format
+ * 2. http: or https: scheme only
+ * 3. Rejects private/internal IP addresses (literal)
+ * 4. Rejects localhost / *.local hostnames
+ *
+ * For full DNS-resolution protection, call resolveAndCheckIp() separately.
+ *
+ * Returns null if valid, or an error string if invalid.
+ */
+export function validateScreenshotUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch { /* malformed URL string */
+        return 'Invalid URL';
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return 'Only http and https URLs are allowed';
+    }
+    const hostname = parsed.hostname;
+    // Strip brackets from IPv6 URLs: [::1] → ::1
+    const bareHost = hostname.replace(/^\[|\]$/g, '');
+    // Reject localhost / *.local hostnames
+    if (bareHost === 'localhost' || bareHost.endsWith('.local')) {
+        return 'Localhost URLs are not allowed';
+    }
+    // Reject private/internal IPs
+    if (net.isIP(bareHost) && isPrivateIP(bareHost)) {
+        return 'Private/internal IP addresses are not allowed';
+    }
+    return null;
+}

package/dist/startup.d.ts

@@ -0,0 +1,6 @@
+import Fastify from 'fastify';
+export declare function writePidFile(stateDir: string): string;
+export declare function removePidFile(pidFilePath: string): void;
+/** Read parent PID with cross-platform fallback. */
+export declare function readPpid(pid: number): Promise<number>;
+export declare function listenWithRetry(app: ReturnType<typeof Fastify>, port: number, host: string, stateDir: string, maxRetries?: number): Promise<void>;

package/dist/startup.js

@@ -0,0 +1,162 @@
+import fs from 'node:fs/promises';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { findPidOnPort, readParentPid } from './process-utils.js';
+export function writePidFile(stateDir) {
+    try {
+        const pidFilePath = path.join(stateDir, 'aegis.pid');
+        writeFileSync(pidFilePath, String(process.pid));
+        return pidFilePath;
+    }
+    catch {
+        return '';
+    }
+}
+export function removePidFile(pidFilePath) {
+    try {
+        if (pidFilePath)
+            unlinkSync(pidFilePath);
+    }
+    catch {
+        // non-critical
+    }
+}
+async function readPidFile(stateDir) {
+    try {
+        const p = path.join(stateDir, 'aegis.pid');
+        const content = (await fs.readFile(p, 'utf-8')).trim();
+        const pid = parseInt(content, 10);
+        return Number.isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+function pidExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read parent PID with cross-platform fallback. */
+export async function readPpid(pid) {
+    const parent = await readParentPid(pid);
+    if (parent === null) {
+        throw new Error(`no parent PID available for process ${pid}`);
+    }
+    return parent;
+}
+async function isAncestorPid(pid) {
+    try {
+        let current = process.ppid;
+        for (let depth = 0; depth < 10 && current > 1; depth++) {
+            if (current === pid)
+                return true;
+            try {
+                current = await readPpid(current);
+            }
+            catch {
+                break;
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+async function waitForPortRelease(port, maxWaitMs = 5000) {
+    const net = await import('node:net');
+    const start = Date.now();
+    let delay = 200;
+    while (Date.now() - start < maxWaitMs) {
+        try {
+            await new Promise((resolve, reject) => {
+                const sock = net.createServer();
+                sock.once('error', reject);
+                sock.listen(port, '127.0.0.1', () => {
+                    sock.close();
+                    reject(new Error('port free'));
+                });
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.message === 'port free')
+                return;
+        }
+        await new Promise(resolve => setTimeout(resolve, delay));
+        delay = Math.min(delay * 1.5, 1000);
+    }
+}
+async function killStalePortHolder(port, stateDir) {
+    await new Promise(resolve => setTimeout(resolve, 100 + Math.random() * 400));
+    try {
+        const pids = await findPidOnPort(port);
+        if (pids.length === 0)
+            return false;
+        let killed = false;
+        for (const pid of pids) {
+            if (pid === process.pid)
+                continue;
+            if (await isAncestorPid(pid)) {
+                console.warn(`EADDRINUSE recovery: skipping ancestor PID ${pid} on port ${port}`);
+                continue;
+            }
+            const pidFilePid = await readPidFile(stateDir);
+            if (pidFilePid !== null && pid === pidFilePid && pid !== process.pid) {
+                console.warn(`EADDRINUSE recovery: skipping peer Aegis PID ${pid} (PID file match) on port ${port}`);
+                continue;
+            }
+            if (!pidExists(pid))
+                continue;
+            console.warn(`EADDRINUSE recovery: killing stale process PID ${pid} on port ${port}`);
+            try {
+                process.kill(pid, 'SIGTERM');
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                if (!pidExists(pid)) {
+                    killed = true;
+                    continue;
+                }
+            }
+            catch {
+                // process may have exited between checks
+            }
+            try {
+                process.kill(pid, 'SIGKILL');
+                killed = true;
+            }
+            catch {
+                // already dead
+            }
+        }
+        if (killed) {
+            await waitForPortRelease(port);
+        }
+        return killed;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listenWithRetry(app, port, host, stateDir, maxRetries = 1) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            await app.listen({ port, host });
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof Error && 'code' in err && err.code === 'EADDRINUSE') || attempt >= maxRetries) {
+                throw err;
+            }
+            console.error(`EADDRINUSE on port ${port} - attempting recovery (attempt ${attempt + 1}/${maxRetries})`);
+            const killed = await killStalePortHolder(port, stateDir);
+            if (!killed) {
+                console.error(`EADDRINUSE recovery failed: no stale process found on port ${port}`);
+                throw err;
+            }
+        }
+    }
+}

package/dist/suppress.d.ts

@@ -0,0 +1,33 @@
+/**
+ * suppress.ts — Explicit suppression predicate for expected runtime races.
+ *
+ * Issue #882: Replaces silent empty catches with a documented, testable
+ * suppression contract. Suppressible errors (expected races, killed sessions,
+ * missing tmux panes) are forwarded as rate-limited diagnostics events.
+ * Non-suppressible errors are surfaced at warn level.
+ */
+/** Contexts where suppressible races may occur. */
+export type SuppressContext = 'monitor.checkSession' | 'monitor.checkDeadSessions.killSession' | 'monitor.checkStopSignals.parseEntry' | 'session.cleanup' | 'tmux.capturePane' | string;
+/** Exported for tests — clears all rate-limit counters. */
+export declare function _resetSuppressRateLimit(): void;
+/**
+ * Returns true if the error is an expected transient race that
+ * should be swallowed without surfacing a warning.
+ *
+ * Categories of suppressible errors:
+ * - Session killed while in-flight (SESSION_NOT_FOUND-class messages)
+ * - File not found (ENOENT) — session JSONL removed after kill
+ * - Tmux pane/window gone — dead-session race
+ * - SyntaxError from truncated JSONL reads during rotation
+ */
+export declare function isSuppressible(error: unknown, _context: SuppressContext): boolean;
+/**
+ * Handle a caught error using the explicit suppression policy.
+ *
+ * - Suppressible errors: console.debug with rate limiting (max 10/min per context).
+ * - Non-suppressible errors: console.warn — always visible.
+ *
+ * Does NOT rethrow. Call isSuppressible() directly if you need rethrow control.
+ */
+export declare function suppressedCatch(error: unknown, context: SuppressContext): void;
+export declare function _errorMessage(error: unknown): string;

package/dist/suppress.js

@@ -0,0 +1,79 @@
+/**
+ * suppress.ts — Explicit suppression predicate for expected runtime races.
+ *
+ * Issue #882: Replaces silent empty catches with a documented, testable
+ * suppression contract. Suppressible errors (expected races, killed sessions,
+ * missing tmux panes) are forwarded as rate-limited diagnostics events.
+ * Non-suppressible errors are surfaced at warn level.
+ */
+/** Rate-limit state: max N suppressed debug events per context per minute. */
+const suppressRateLimit = new Map();
+/** Exported for tests — clears all rate-limit counters. */
+export function _resetSuppressRateLimit() {
+    suppressRateLimit.clear();
+}
+const SUPPRESS_MAX_PER_MINUTE = 10;
+/**
+ * Returns true if the error is an expected transient race that
+ * should be swallowed without surfacing a warning.
+ *
+ * Categories of suppressible errors:
+ * - Session killed while in-flight (SESSION_NOT_FOUND-class messages)
+ * - File not found (ENOENT) — session JSONL removed after kill
+ * - Tmux pane/window gone — dead-session race
+ * - SyntaxError from truncated JSONL reads during rotation
+ */
+export function isSuppressible(error, _context) {
+    if (error instanceof SyntaxError)
+        return true;
+    if (error instanceof Error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return true;
+        const msg = error.message.toLowerCase();
+        if (msg.includes('session not found'))
+            return true;
+        if (msg.includes('no session with id'))
+            return true;
+        if (msg.includes('no such window'))
+            return true;
+        if (msg.includes('no such pane'))
+            return true;
+        if (msg.includes('no such session'))
+            return true;
+        if (msg.includes("can't find window"))
+            return true;
+        if (msg.includes('window already dead'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Handle a caught error using the explicit suppression policy.
+ *
+ * - Suppressible errors: console.debug with rate limiting (max 10/min per context).
+ * - Non-suppressible errors: console.warn — always visible.
+ *
+ * Does NOT rethrow. Call isSuppressible() directly if you need rethrow control.
+ */
+export function suppressedCatch(error, context) {
+    if (isSuppressible(error, context)) {
+        const now = Date.now();
+        const state = suppressRateLimit.get(context);
+        if (!state || now >= state.resetAt) {
+            suppressRateLimit.set(context, { count: 1, resetAt: now + 60_000 });
+            console.debug(`[suppress] ${context}: ${_errorMessage(error)}`);
+        }
+        else if (state.count < SUPPRESS_MAX_PER_MINUTE) {
+            state.count++;
+            console.debug(`[suppress] ${context}: ${_errorMessage(error)}`);
+        }
+        // rate limit exceeded for this window — drop silently
+    }
+    else {
+        console.warn(`[unexpected] ${context}: ${_errorMessage(error)}`, error);
+    }
+}
+export function _errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/swarm-monitor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * swarm-monitor.ts — Monitors Claude Code swarm sockets for teammate sessions.
+ *
+ * Issue #81: Agent Swarm Awareness.
+ *
+ * When CC spawns teammates/subagents, it creates them in tmux with:
+ *   - Socket: -L claude-swarm-{pid} (isolated from main session)
+ *   - Window naming: teammate-{name}
+ *   - Env vars: CLAUDE_PARENT_SESSION_ID, --agent-id, --agent-name
+ *
+ * This module discovers those swarm sockets, lists their windows,
+ * cross-references with parent sessions, and tracks teammate status.
+ */
+import type { SessionManager, SessionInfo } from './session.js';
+/** Information about a single teammate window in a swarm socket. */
+export interface TeammateInfo {
+    /** Window ID (e.g. "@0") */
+    windowId: string;
+    /** Window name (e.g. "teammate-explore-agent") */
+    windowName: string;
+    /** Working directory of the teammate */
+    cwd: string;
+    /** Current process running in the pane */
+    paneCommand: string;
+    /** Whether the teammate process is alive (claude/node running) */
+    alive: boolean;
+    /** Inferred status from pane command */
+    status: 'running' | 'idle' | 'dead';
+}
+/** A detected swarm (parent + its teammates). */
+export interface SwarmInfo {
+    /** Socket name (e.g. "claude-swarm-12345") */
+    socketName: string;
+    /** PID extracted from socket name */
+    pid: number;
+    /** The parent Aegis session, if found */
+    parentSession: SessionInfo | null;
+    /** Detected teammate windows */
+    teammates: TeammateInfo[];
+    /** Aggregated swarm status */
+    aggregatedStatus: 'all_idle' | 'some_working' | 'all_dead' | 'no_teammates';
+    /** When this swarm was last scanned */
+    lastScannedAt: number;
+}
+/** Result of scanning all swarm sockets. */
+export interface SwarmScanResult {
+    swarms: SwarmInfo[];
+    totalSockets: number;
+    totalTeammates: number;
+    scannedAt: number;
+}
+export interface SwarmMonitorConfig {
+    /** How often to scan for swarm sockets (default: 10s) */
+    scanIntervalMs: number;
+    /** Glob pattern for swarm socket directories */
+    socketGlobPattern: string;
+}
+export declare const DEFAULT_SWARM_CONFIG: SwarmMonitorConfig;
+/** Events emitted by SwarmMonitor when teammate state changes. */
+export type SwarmEvent = {
+    type: 'teammate_spawned';
+    swarm: SwarmInfo;
+    teammate: TeammateInfo;
+} | {
+    type: 'teammate_finished';
+    swarm: SwarmInfo;
+    teammate: TeammateInfo;
+};
+/** Callback for swarm events. */
+export type SwarmEventHandler = (event: SwarmEvent) => void;
+export declare class SwarmMonitor {
+    private sessions;
+    private config;
+    private running;
+    private lastResult;
+    private timer;
+    private eventHandlers;
+    private windowsDisabledLogged;
+    constructor(sessions: SessionManager, config?: SwarmMonitorConfig);
+    /** Register an event handler for teammate lifecycle events. */
+    onEvent(handler: SwarmEventHandler): void;
+    private emitEvent;
+    private isWindowsPlatform;
+    private logWindowsDisabled;
+    /** Start the periodic scan loop. */
+    start(): void;
+    /** Stop the periodic scan loop. */
+    stop(): void;
+    /** Get the most recent scan result. */
+    getLastResult(): SwarmScanResult | null;
+    /** Run a single scan and return the result. */
+    scan(): Promise<SwarmScanResult>;
+    /** Compare current scan result against previous to detect teammate changes. */
+    private detectChanges;
+    /** Snapshot of teammates from previous scan for diffing. */
+    private previousTeammates;
+    /** Cached /tmp listing to avoid redundant I/O on every scan. */
+    private cachedSocketNames;
+    private cachedSocketAt;
+    private static readonly SOCKET_CACHE_TTL_MS;
+    /** Discover swarm socket directories in /tmp. */
+    private discoverSwarmSockets;
+    /** Inspect a single swarm socket and return swarm info. */
+    inspectSwarmSocket(socketName: string): Promise<SwarmInfo>;
+    /** Extract PID from socket name "claude-swarm-{pid}". */
+    private extractPid;
+    /** List all windows in a swarm socket. */
+    private listSwarmWindows;
+    /** Find the parent Aegis session for a swarm by matching the CC process PID. */
+    private findParentSession;
+    /** Compute aggregated status for a swarm. */
+    private computeAggregatedStatus;
+    /** Find a specific swarm by parent session ID. */
+    findSwarmByParentSessionId(sessionId: string): SwarmInfo | null;
+    /** Find all swarms associated with any active session. */
+    findActiveSwarms(): SwarmInfo[];
+}