@geometra/mcp 1.57.0 → 1.59.0

package/dist/index.js

@@ -1,18 +1,28 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
-import { disconnect } from './session.js';
+import { disconnect, listSessions } from './session.js';
+import { shutdownSessionLifecycleRegistry } from './session-state.js';
 let cleanedUp = false;
 function cleanupActiveSession() {
     if (cleanedUp)
         return;
     cleanedUp = true;
     try {
+        for (const session of listSessions()) {
+            disconnect({ sessionId: session.id, closeProxy: false });
+        }
         disconnect({ closeProxy: true });
     }
     catch {
         /* ignore */
     }
+    try {
+        shutdownSessionLifecycleRegistry();
+    }
+    catch {
+        /* ignore */
+    }
 }
 async function main() {
     const server = createServer();

package/dist/proxy-spawn.d.ts

@@ -11,6 +11,19 @@ export declare function resolveProxyScriptPath(): string;
 export declare function resolveProxyScriptPathWith(customRequire: NodeRequire, moduleDir?: string): string;
 export declare function resolveProxyRuntimePath(): string;
 export declare function resolveProxyRuntimePathWith(customRequire: NodeRequire, moduleDir?: string): string;
+/**
+ * BYO outbound proxy for the spawned Chromium. JobForge sets this when the
+ * user configures a residential / mobile / SOCKS proxy in `profile.yml` to
+ * bypass datacenter-IP fingerprinting on apply portals (Ashby class B,
+ * Lever Mapbox geocoder, Cloudflare Bot Management, etc.). Geometra is the
+ * wire — the user supplies the proxy.
+ */
+export interface SpawnProxyConfig {
+    server: string;
+    username?: string;
+    password?: string;
+    bypass?: string;
+}
 export interface SpawnProxyParams {
     pageUrl: string;
     port: number;
@@ -19,6 +32,7 @@ export interface SpawnProxyParams {
     height?: number;
     slowMo?: number;
     eagerInitialExtract?: boolean;
+    proxy?: SpawnProxyConfig;
 }
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;

package/dist/proxy-spawn.js

@@ -139,6 +139,7 @@ export async function startEmbeddedGeometraProxy(opts) {
         headed: opts.headless !== true,
         slowMo: opts.slowMo,
         eagerInitialExtract: opts.eagerInitialExtract,
+        ...(opts.proxy && { proxy: opts.proxy }),
     });
     return { runtime, wsUrl: runtime.wsUrl };
 }
@@ -192,6 +193,15 @@ export function spawnGeometraProxy(opts) {
         args.push('--headed');
     if (opts.eagerInitialExtract === false)
         args.push('--lazy-initial-extract');
+    if (opts.proxy?.server) {
+        args.push('--proxy-server', opts.proxy.server);
+        if (opts.proxy.username !== undefined)
+            args.push('--proxy-username', opts.proxy.username);
+        if (opts.proxy.password !== undefined)
+            args.push('--proxy-password', opts.proxy.password);
+        if (opts.proxy.bypass !== undefined)
+            args.push('--proxy-bypass', opts.proxy.bypass);
+    }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, {
             stdio: ['ignore', 'pipe', 'pipe'],

package/dist/server.js

@@ -376,6 +376,20 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .optional()
             .default(false)
             .describe('When true, bypass the reusable proxy pool and spawn a brand-new Chromium for this session that is destroyed on disconnect. Required for safe parallel form submission — without this, two parallel sessions can land on the same pooled proxy and contaminate each other. Default false (use the pool for speed).'),
+        proxy: z
+            .object({
+            server: z
+                .string()
+                .describe('Proxy URL (http://host:port, https://host:port, or socks5://host:port).'),
+            username: z.string().optional().describe('Proxy auth username.'),
+            password: z.string().optional().describe('Proxy auth password.'),
+            bypass: z
+                .string()
+                .optional()
+                .describe('Comma-separated host patterns to bypass (e.g. "*.internal,localhost").'),
+        })
+            .optional()
+            .describe('BYO outbound proxy for the spawned Chromium. Routes all browser traffic through the supplied residential / mobile / SOCKS proxy — useful for apply portals (Ashby, Lever, Cloudflare-fronted ATSes) that fingerprint datacenter IPs and flag headless sessions as bots. The reusable proxy pool is partitioned by proxy identity so callers with different proxy configs never share a Chromium instance.'),
         returnForms: z
             .boolean()
             .optional()
@@ -431,6 +445,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     height: input.height,
                     slowMo: input.slowMo,
                     isolated: input.isolated,
+                    proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
                     eagerInitialExtract: deferInlinePageModel ? true : undefined,
                 });
@@ -501,9 +516,23 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) for the warmed browser.'),
-    }, async ({ pageUrl, port, headless, width, height, slowMo }) => {
+        proxy: z
+            .object({
+            server: z
+                .string()
+                .describe('Proxy URL (http://host:port, https://host:port, or socks5://host:port).'),
+            username: z.string().optional().describe('Proxy auth username.'),
+            password: z.string().optional().describe('Proxy auth password.'),
+            bypass: z
+                .string()
+                .optional()
+                .describe('Comma-separated host patterns to bypass.'),
+        })
+            .optional()
+            .describe('BYO outbound proxy for the warmed Chromium. The pool entry is partitioned by proxy identity, so a later geometra_connect with the same proxy config will reuse this warmed browser; a different proxy config (or no proxy) will not.'),
+    }, async ({ pageUrl, port, headless, width, height, slowMo, proxy }) => {
         try {
-            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo });
+            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo, proxy });
             return ok(JSON.stringify(prepared));
         }
         catch (e) {

package/dist/session-state.d.ts

@@ -0,0 +1,35 @@
+interface SessionLifecycleTarget {
+    id: string;
+    url: string;
+    isolated?: boolean;
+    proxyReusable?: boolean;
+    updateRevision: number;
+    layout: Record<string, unknown> | null;
+    tree: Record<string, unknown> | null;
+    ws: {
+        readyState: number;
+    };
+    connectTrace?: {
+        mode?: string;
+    } | null;
+    cachedA11y?: {
+        meta?: {
+            pageUrl?: string;
+        };
+    } | null;
+    lifecycleTaskId?: string;
+    lifecycleTaskKind?: string;
+    lifecycleLeaseId?: string;
+    lifecycleWorkerId?: string;
+    lifecycleFinalized?: boolean;
+}
+export declare function initializeSessionLifecycle(target: SessionLifecycleTarget, options?: {
+    pageUrl?: string;
+    transportMode?: string;
+}): void;
+export declare function heartbeatSessionLifecycle(target: SessionLifecycleTarget): void;
+export declare function recordSessionSnapshot(target: SessionLifecycleTarget, label: string, extra?: Record<string, unknown>): void;
+export declare function completeSessionLifecycle(target: SessionLifecycleTarget, reason: string, extra?: Record<string, unknown>): void;
+export declare function failSessionLifecycle(target: SessionLifecycleTarget, error: string, extra?: Record<string, unknown>): void;
+export declare function shutdownSessionLifecycleRegistry(): void;
+export {};

package/dist/session-state.js

@@ -0,0 +1,191 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { ParallelMcpOrchestrator, SqliteParallelMcpStore, } from '@razroo/parallel-mcp';
+const SESSION_NAMESPACE = 'geometra-mcp-session';
+const SESSION_TASK_KEY = 'session.live';
+const SESSION_LEASE_MS = 60_000;
+const SESSION_SWEEP_MS = 15_000;
+const SESSION_WORKER_PREFIX = `geometra-mcp:${process.pid}`;
+function resolveSessionStateFile() {
+    const raw = process.env.GEOMETRA_MCP_STATE_FILE?.trim();
+    if (raw) {
+        mkdirSync(path.dirname(raw), { recursive: true });
+        return raw;
+    }
+    const dir = path.join(homedir(), '.geometra-mcp');
+    mkdirSync(dir, { recursive: true });
+    return path.join(dir, `parallel-mcp-${process.pid}.sqlite`);
+}
+const orchestrator = new ParallelMcpOrchestrator(new SqliteParallelMcpStore({ filename: resolveSessionStateFile() }), { defaultLeaseMs: SESSION_LEASE_MS });
+const leaseSweep = setInterval(() => {
+    try {
+        orchestrator.expireLeases();
+    }
+    catch {
+        /* ignore background lease sweep failures */
+    }
+}, SESSION_SWEEP_MS);
+leaseSweep.unref();
+function extractPageUrl(target) {
+    const cached = target.cachedA11y?.meta?.pageUrl;
+    if (typeof cached === 'string' && cached.length > 0)
+        return cached;
+    const semantic = target.tree?.semantic;
+    if (semantic && typeof semantic.pageUrl === 'string' && semantic.pageUrl.length > 0)
+        return semantic.pageUrl;
+    return null;
+}
+function toJsonValue(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => toJsonValue(item));
+    }
+    if (typeof value === 'object') {
+        const object = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                continue;
+            object[key] = toJsonValue(entry);
+        }
+        return object;
+    }
+    return String(value);
+}
+function buildSessionContext(target, label, extra) {
+    return {
+        sessionId: target.id,
+        label,
+        transportUrl: target.url,
+        pageUrl: extractPageUrl(target),
+        isolated: target.isolated === true,
+        proxyReusable: target.proxyReusable === true,
+        wsReadyState: target.ws.readyState,
+        updateRevision: target.updateRevision,
+        hasLayout: target.layout !== null,
+        hasTree: target.tree !== null,
+        connectMode: target.connectTrace?.mode ?? null,
+        ...(extra ? { extra: toJsonValue(extra) } : {}),
+    };
+}
+function liveTaskIdFor(sessionId) {
+    return `${sessionId}:live`;
+}
+function liveTaskKindFor(sessionId) {
+    return `session.live:${sessionId}`;
+}
+function workerIdFor(sessionId) {
+    return `${SESSION_WORKER_PREFIX}:${sessionId}`;
+}
+export function initializeSessionLifecycle(target, options) {
+    const sessionId = target.id;
+    const taskId = liveTaskIdFor(sessionId);
+    const taskKind = liveTaskKindFor(sessionId);
+    const workerId = workerIdFor(sessionId);
+    orchestrator.createRun({
+        id: sessionId,
+        namespace: SESSION_NAMESPACE,
+        metadata: toJsonValue({
+            transportMode: options?.transportMode ?? 'direct-ws',
+            isolated: target.isolated === true,
+        }),
+        context: buildSessionContext(target, 'session.initialized', {
+            requestedPageUrl: options?.pageUrl ?? null,
+        }),
+    });
+    orchestrator.enqueueTask({
+        id: taskId,
+        runId: sessionId,
+        key: SESSION_TASK_KEY,
+        kind: taskKind,
+        input: toJsonValue({
+            transportUrl: target.url,
+            requestedPageUrl: options?.pageUrl ?? null,
+        }),
+    });
+    const claimed = orchestrator.claimNextTask({
+        workerId,
+        kinds: [taskKind],
+        leaseMs: SESSION_LEASE_MS,
+    });
+    if (!claimed || claimed.task.id !== taskId) {
+        throw new Error(`Failed to initialize durable session task for ${sessionId}`);
+    }
+    orchestrator.markTaskRunning({
+        taskId,
+        leaseId: claimed.lease.id,
+        workerId,
+    });
+    target.lifecycleTaskId = taskId;
+    target.lifecycleTaskKind = taskKind;
+    target.lifecycleLeaseId = claimed.lease.id;
+    target.lifecycleWorkerId = workerId;
+    target.lifecycleFinalized = false;
+}
+export function heartbeatSessionLifecycle(target) {
+    if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
+        return;
+    orchestrator.heartbeatLease({
+        taskId: target.lifecycleTaskId,
+        leaseId: target.lifecycleLeaseId,
+        workerId: target.lifecycleWorkerId,
+        leaseMs: SESSION_LEASE_MS,
+    });
+}
+export function recordSessionSnapshot(target, label, extra) {
+    if (!target.lifecycleTaskId)
+        return;
+    orchestrator.appendContextSnapshot({
+        runId: target.id,
+        taskId: target.lifecycleTaskId,
+        scope: 'run',
+        label,
+        payload: buildSessionContext(target, label, extra),
+    });
+}
+export function completeSessionLifecycle(target, reason, extra) {
+    if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
+        return;
+    orchestrator.completeTask({
+        taskId: target.lifecycleTaskId,
+        leaseId: target.lifecycleLeaseId,
+        workerId: target.lifecycleWorkerId,
+        output: toJsonValue({
+            reason,
+            ...(extra ? { extra } : {}),
+        }),
+        nextContext: buildSessionContext(target, 'session.completed', {
+            reason,
+            ...(extra ? { ...extra } : {}),
+        }),
+        nextContextLabel: 'session.completed',
+    });
+    target.lifecycleFinalized = true;
+}
+export function failSessionLifecycle(target, error, extra) {
+    if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
+        return;
+    recordSessionSnapshot(target, 'session.failed', {
+        error,
+        ...(extra ? { ...extra } : {}),
+    });
+    orchestrator.failTask({
+        taskId: target.lifecycleTaskId,
+        leaseId: target.lifecycleLeaseId,
+        workerId: target.lifecycleWorkerId,
+        error,
+        metadata: extra ? toJsonValue(extra) : undefined,
+    });
+    target.lifecycleFinalized = true;
+}
+export function shutdownSessionLifecycleRegistry() {
+    clearInterval(leaseSweep);
+    orchestrator.close();
+}

package/dist/session.d.ts

@@ -1,6 +1,6 @@
 import type { ChildProcess } from 'node:child_process';
 import WebSocket from 'ws';
-import { type EmbeddedProxyRuntime } from './proxy-spawn.js';
+import { type EmbeddedProxyRuntime, type SpawnProxyConfig } from './proxy-spawn.js';
 /**
  * Parsed accessibility node from the UI tree + computed layout.
  * Mirrors the shape of @geometra/core's AccessibilityNode without importing it
@@ -392,7 +392,7 @@ export interface WorkflowState {
     startedAt: number;
 }
 export interface Session {
-    /** Short stable identifier (e.g. "s1", "s2") returned by geometra_connect. */
+    /** Durable unique identifier returned by geometra_connect. */
     id: string;
     ws: WebSocket;
     layout: Record<string, unknown> | null;
@@ -421,6 +421,14 @@ export interface Session {
     }>;
     workflowState?: WorkflowState;
     reconnectInFlight?: Promise<boolean>;
+    lifecycleTaskId?: string;
+    lifecycleTaskKind?: string;
+    lifecycleLeaseId?: string;
+    lifecycleWorkerId?: string;
+    lifecycleFinalized?: boolean;
+    heartbeatInterval?: ReturnType<typeof setInterval> | null;
+    heartbeatLastMessageAt?: number;
+    heartbeatPendingPongBy?: number | null;
 }
 export interface SessionConnectTrace {
     mode: 'direct-ws' | 'fresh-proxy' | 'reused-proxy';
@@ -484,6 +492,7 @@ export declare function prewarmProxy(options: {
     width?: number;
     height?: number;
     slowMo?: number;
+    proxy?: SpawnProxyConfig;
 }): Promise<{
     prepared: true;
     reused: boolean;
@@ -527,6 +536,13 @@ export declare function connectThroughProxy(options: {
      * leak into another. Default false preserves the existing pool behavior.
      */
     isolated?: boolean;
+    /**
+     * BYO outbound proxy for the Chromium. Routes all browser traffic through
+     * the supplied residential / mobile / SOCKS proxy. The reusable pool is
+     * partitioned by proxy identity so two callers with different proxy
+     * configs never share a Chromium instance.
+     */
+    proxy?: SpawnProxyConfig;
 }): Promise<Session>;
 export declare function getSession(id?: string): Session | null;
 export declare function pruneDisconnectedSessions(): string[];

package/dist/session.js

@@ -1,11 +1,25 @@
+import { randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
 import { spawnGeometraProxy, startEmbeddedGeometraProxy } from './proxy-spawn.js';
+import { completeSessionLifecycle, failSessionLifecycle, heartbeatSessionLifecycle, initializeSessionLifecycle, recordSessionSnapshot, } from './session-state.js';
+/**
+ * Stable identity for an outbound proxy config, used as the reusable-pool
+ * partition key. Two sessions with different proxy configs MUST NOT share a
+ * pooled Chromium — otherwise the first apply's IP leaks into subsequent
+ * applies even when the caller opted into a fresh proxy. Password is
+ * excluded from the key to keep logs safe; `server + username + bypass` is
+ * enough to distinguish every realistic multi-tenant config.
+ */
+function proxyKeyFor(proxy) {
+    if (!proxy?.server)
+        return '';
+    return `${proxy.server}|${proxy.username ?? ''}|${proxy.bypass ?? ''}`;
+}
 const activeSessions = new Map();
 let defaultSessionId = null;
 const MAX_ACTIVE_SESSIONS = 5;
-let nextSessionId = 0;
-function generateSessionId() { return `s${++nextSessionId}`; }
+function generateSessionId() { return `s_${randomUUID()}`; }
 let reusableProxies = [];
 const REUSABLE_PROXY_POOL_LIMIT = 6;
 /** Close idle reusable proxies after 5 minutes of inactivity. */
@@ -128,6 +142,7 @@ function enforceReusableProxyPoolLimit() {
 function setReusableProxy(proxy, wsUrl, opts) {
     clearReusableProxiesIfExited();
     const now = Date.now();
+    const proxyKey = proxyKeyFor(opts.proxy);
     const existing = reusableProxies.find(entry => sameReusableProxyEntry(entry, proxy));
     if (existing) {
         existing.wsUrl = wsUrl;
@@ -136,6 +151,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         existing.width = opts.width ?? 1280;
         existing.height = opts.height ?? 720;
         existing.pageUrl = opts.pageUrl;
+        existing.proxyKey = proxyKey;
         existing.snapshotReady = opts.snapshotReady ?? existing.snapshotReady;
         existing.lastUsedAt = now;
         return;
@@ -150,6 +166,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
             width: opts.width ?? 1280,
             height: opts.height ?? 720,
             pageUrl: opts.pageUrl,
+            proxyKey,
             snapshotReady: opts.snapshotReady === true,
             lastUsedAt: now,
         };
@@ -175,6 +192,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         width: opts.width ?? 1280,
         height: opts.height ?? 720,
         pageUrl: opts.pageUrl,
+        proxyKey,
         snapshotReady: opts.snapshotReady === true,
         lastUsedAt: now,
     });
@@ -229,11 +247,20 @@ function shutdownSession(id, opts) {
     const prev = activeSessions.get(id);
     if (!prev)
         return;
+    const forceCloseProxy = prev.isolated === true;
+    safeCompleteSessionLifecycle(prev, opts?.reason ?? 'disconnect', {
+        closeProxy: opts?.closeProxy ?? false,
+        forceCloseProxy,
+    });
     activeSessions.delete(id);
     if (defaultSessionId === id)
         promoteDefaultSession();
+    stopSessionHeartbeat(prev);
+    releaseSessionResources(prev, { closeProxy: opts?.closeProxy ?? false });
+}
+function releaseSessionResources(session, opts) {
     try {
-        prev.ws.close();
+        session.ws.close();
     }
     catch {
         /* ignore */
@@ -243,44 +270,44 @@ function shutdownSession(id, opts) {
     // the underlying browser would defeat the entire point of the
     // isolation flag (the next non-isolated connect could attach to a
     // proxy with stale storage from this session's job).
-    const forceCloseProxy = prev.isolated === true;
-    if (prev.proxyChild) {
-        const shouldKeepProxy = !forceCloseProxy && prev.proxyReusable && opts?.closeProxy === false;
-        rememberReusableProxyPageUrl(prev);
+    const forceCloseProxy = session.isolated === true;
+    if (session.proxyChild) {
+        const shouldKeepProxy = !forceCloseProxy && session.proxyReusable && opts?.closeProxy === false;
+        rememberReusableProxyPageUrl(session);
         if (shouldKeepProxy) {
-            const entry = reusableProxyEntryForSession(prev);
+            const entry = reusableProxyEntryForSession(session);
             if (entry)
                 touchReusableProxy(entry);
             return;
         }
-        const entry = reusableProxyEntryForSession(prev);
+        const entry = reusableProxyEntryForSession(session);
         if (entry) {
             closeReusableProxy(entry);
             return;
         }
         try {
-            prev.proxyChild.kill('SIGTERM');
+            session.proxyChild.kill('SIGTERM');
         }
         catch {
             /* ignore */
         }
         return;
     }
-    if (prev.proxyRuntime) {
-        const shouldKeepProxy = !forceCloseProxy && prev.proxyReusable && opts?.closeProxy === false;
-        rememberReusableProxyPageUrl(prev);
+    if (session.proxyRuntime) {
+        const shouldKeepProxy = !forceCloseProxy && session.proxyReusable && opts?.closeProxy === false;
+        rememberReusableProxyPageUrl(session);
         if (shouldKeepProxy) {
-            const entry = reusableProxyEntryForSession(prev);
+            const entry = reusableProxyEntryForSession(session);
             if (entry)
                 touchReusableProxy(entry);
             return;
         }
-        const entry = reusableProxyEntryForSession(prev);
+        const entry = reusableProxyEntryForSession(session);
         if (entry) {
             closeReusableProxy(entry);
             return;
         }
-        void prev.proxyRuntime.close().catch(() => { });
+        void session.proxyRuntime.close().catch(() => { });
     }
 }
 /** Evict the oldest session when at capacity. */
@@ -288,17 +315,100 @@ function evictOldestSession() {
     if (activeSessions.size < MAX_ACTIVE_SESSIONS)
         return;
     const oldestId = activeSessions.keys().next().value;
-    shutdownSession(oldestId, { closeProxy: false });
+    shutdownSession(oldestId, { closeProxy: false, reason: 'evicted' });
 }
 function formatUnknownError(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function warnSessionLifecycleError(action, session, err) {
+    console.warn(`geometra-mcp: failed to ${action} for session ${session.id}: ${formatUnknownError(err)}`);
+}
+function safeRecordSessionSnapshot(session, label, extra) {
+    try {
+        recordSessionSnapshot(session, label, extra);
+    }
+    catch (err) {
+        warnSessionLifecycleError(`record snapshot "${label}"`, session, err);
+    }
+}
+function safeHeartbeatSessionLifecycle(session) {
+    try {
+        heartbeatSessionLifecycle(session);
+    }
+    catch (err) {
+        warnSessionLifecycleError('heartbeat durable state', session, err);
+    }
+}
+function safeCompleteSessionLifecycle(session, reason, extra) {
+    try {
+        completeSessionLifecycle(session, reason, extra);
+    }
+    catch (err) {
+        warnSessionLifecycleError(`complete durable state as "${reason}"`, session, err);
+    }
+}
+function safeFailSessionLifecycle(session, error, extra) {
+    try {
+        failSessionLifecycle(session, error, extra);
+    }
+    catch (err) {
+        warnSessionLifecycleError(`fail durable state as "${error}"`, session, err);
+    }
+}
+function noteSessionSocketActivity(session, ws) {
+    if (session.ws !== ws)
+        return;
+    session.heartbeatLastMessageAt = Date.now();
+    session.heartbeatPendingPongBy = null;
+}
+// Keep the durable lease alive independently from a transient socket and only
+// ping the WebSocket transport when a socket is actually open.
+function startSessionHeartbeat(session) {
+    if (session.heartbeatInterval)
+        return;
+    session.heartbeatLastMessageAt ??= Date.now();
+    session.heartbeatPendingPongBy ??= null;
+    session.heartbeatInterval = setInterval(() => {
+        safeHeartbeatSessionLifecycle(session);
+        const ws = session.ws;
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        const pendingPongBy = session.heartbeatPendingPongBy ?? null;
+        if (pendingPongBy !== null && Date.now() > pendingPongBy) {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        if (Date.now() - (session.heartbeatLastMessageAt ?? 0) > 10_000) {
+            try {
+                ws.ping();
+                session.heartbeatPendingPongBy = Date.now() + 30_000;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }, 15_000);
+    session.heartbeatInterval.unref();
+}
+function stopSessionHeartbeat(session) {
+    if (session.heartbeatInterval) {
+        clearInterval(session.heartbeatInterval);
+        session.heartbeatInterval = null;
+    }
+    session.heartbeatPendingPongBy = null;
+}
 function reusableProxyMatchesOptions(entry, options) {
     return (entry.pageUrl === options.pageUrl &&
         entry.headless === (options.headless === true) &&
         entry.slowMo === (options.slowMo ?? 0) &&
         entry.width === (options.width ?? 1280) &&
-        entry.height === (options.height ?? 720));
+        entry.height === (options.height ?? 720) &&
+        entry.proxyKey === proxyKeyFor(options.proxy));
 }
 function findExactReusableProxy(options) {
     clearReusableProxiesIfExited();
@@ -315,8 +425,14 @@ function findReusableProxy(options) {
     const desiredSlowMo = options.slowMo ?? 0;
     const desiredWidth = options.width ?? 1280;
     const desiredHeight = options.height ?? 720;
+    const desiredProxyKey = proxyKeyFor(options.proxy);
     return reusableProxies
-        .filter(entry => entry.headless === desiredHeadless && entry.slowMo === desiredSlowMo)
+        .filter(entry => entry.headless === desiredHeadless
+        && entry.slowMo === desiredSlowMo
+        // Proxy partition is hard — a session with residential proxy MUST NOT
+        // attach to a pooled direct-connection Chromium (and vice versa).
+        // Different proxy credentials also get separate pool entries.
+        && entry.proxyKey === desiredProxyKey)
         .sort((a, b) => {
         const score = (entry) => {
             let value = 0;
@@ -356,6 +472,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            proxy: options.proxy,
         });
         try {
             await runtime.ready;
@@ -371,6 +488,7 @@ export async function prewarmProxy(options) {
             height: options.height,
             pageUrl: options.pageUrl,
             snapshotReady: true,
+            proxy: options.proxy,
         });
         return {
             prepared: true,
@@ -394,6 +512,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            proxy: options.proxy,
         });
         setReusableProxy({ child }, wsUrl, {
             headless: options.headless,
@@ -401,6 +520,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
+            proxy: options.proxy,
         });
         return {
             prepared: true,
@@ -477,6 +597,11 @@ async function attachToReusableProxy(proxy, options) {
         totalMs: performance.now() - startedAt,
     };
     updateReusableProxySnapshotState(proxy, session);
+    safeRecordSessionSnapshot(session, 'session.proxy_attached', {
+        transportMode: 'reused-proxy',
+        targetPageUrl: options.pageUrl,
+        reusedExistingSession: reusedExistingSession !== null,
+    });
     return session;
 }
 async function startFreshProxySession(options) {
@@ -497,6 +622,7 @@ async function startFreshProxySession(options) {
             height: options.height,
             slowMo: options.slowMo,
             eagerInitialExtract,
+            proxy: options.proxy,
         });
         pendingEmbeddedRuntime = runtime;
         const proxyStartMs = performance.now() - proxyStartStartedAt;
@@ -527,6 +653,7 @@ async function startFreshProxySession(options) {
                 height: options.height,
                 pageUrl: options.pageUrl,
                 snapshotReady: Boolean(session.tree && session.layout),
+                proxy: options.proxy,
             });
         }
         const baseConnectTrace = session.connectTrace;
@@ -542,6 +669,12 @@ async function startFreshProxySession(options) {
             resolvedWithoutInitialFrame: baseConnectTrace?.resolvedWithoutInitialFrame,
             totalMs: performance.now() - startedAt,
         };
+        safeRecordSessionSnapshot(session, 'session.proxy_attached', {
+            transportMode: 'fresh-proxy',
+            proxyStartMode: 'embedded',
+            requestedPageUrl: options.pageUrl,
+            isolated: options.isolated === true,
+        });
         return session;
     }
     catch (e) {
@@ -564,6 +697,7 @@ async function startFreshProxySession(options) {
             height: options.height,
             slowMo: options.slowMo,
             eagerInitialExtract,
+            proxy: options.proxy,
         });
         const proxyStartMs = performance.now() - proxyStartStartedAt;
         try {
@@ -588,6 +722,7 @@ async function startFreshProxySession(options) {
                     height: options.height,
                     pageUrl: options.pageUrl,
                     snapshotReady: Boolean(session.tree && session.layout),
+                    proxy: options.proxy,
                 });
             }
             const baseConnectTrace = session.connectTrace;
@@ -603,6 +738,12 @@ async function startFreshProxySession(options) {
                 resolvedWithoutInitialFrame: baseConnectTrace?.resolvedWithoutInitialFrame,
                 totalMs: performance.now() - startedAt,
             };
+            safeRecordSessionSnapshot(session, 'session.proxy_attached', {
+                transportMode: 'fresh-proxy',
+                proxyStartMode: 'child',
+                requestedPageUrl: options.pageUrl,
+                isolated: options.isolated === true,
+            });
             return session;
         }
         catch (fallbackError) {
@@ -642,56 +783,40 @@ export function connect(url, opts) {
             cachedA11y: null,
             cachedA11yRevision: -1,
             cachedFormSchemas: new Map(),
+            heartbeatInterval: null,
+            heartbeatLastMessageAt: Date.now(),
+            heartbeatPendingPongBy: null,
         };
-        let resolved = false;
-        let lastMessageAt = Date.now();
-        let heartbeatInterval = null;
-        let pendingPongBy = null;
-        // Heartbeat: send a real WS-level ping every 15s and only tear the socket
-        // down if the peer fails to respond to two consecutive pings (i.e. ~45s of
-        // true unresponsiveness). Previous versions used a dumb idle timer that
-        // closed the socket after 30s of no inbound frames — which killed sessions
-        // during normal form-submission flows where the DOM is legitimately idle
-        // for 20-30+ seconds while the backend processes (Greenhouse submit →
-        // security-code dialog is the canonical repro). A real ping/pong cycle
-        // distinguishes a silent-but-healthy session from a dead one.
-        function startHeartbeat() {
-            if (heartbeatInterval)
-                return;
-            heartbeatInterval = setInterval(() => {
-                // If we're waiting on a pong and it's overdue, the peer is dead.
-                if (pendingPongBy !== null && Date.now() > pendingPongBy) {
-                    try {
-                        ws.close();
-                    }
-                    catch { /* ignore */ }
-                    return;
-                }
-                // Only send a new ping if we haven't heard anything for a while,
-                // to avoid spamming a chatty session.
-                if (Date.now() - lastMessageAt > 10_000) {
-                    try {
-                        ws.ping();
-                        // Allow 30s for the pong before declaring the peer dead.
-                        pendingPongBy = Date.now() + 30_000;
-                    }
-                    catch {
-                        /* if ping throws, the socket is already gone — let 'close' handle */
-                    }
-                }
-            }, 15_000);
-            heartbeatInterval.unref();
+        try {
+            initializeSessionLifecycle(session, { transportMode: 'direct-ws' });
+        }
+        catch (err) {
+            try {
+                ws.terminate();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(new Error(`Failed to initialize durable session state for ${url}: ${formatUnknownError(err)}`));
+            return;
         }
+        let resolved = false;
         ws.on('pong', () => {
-            if (session.ws !== ws)
-                return;
-            lastMessageAt = Date.now();
-            pendingPongBy = null;
+            noteSessionSocketActivity(session, ws);
         });
         const timeout = setTimeout(() => {
             if (!resolved) {
+                safeFailSessionLifecycle(session, 'connect_timeout', {
+                    transportUrl: url,
+                    timeoutMs: 10_000,
+                });
                 resolved = true;
-                ws.close();
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
                 reject(new Error(`Connection to ${url} timed out after 10s`));
             }
         }, 10_000);
@@ -715,14 +840,17 @@ export function connect(url, opts) {
                 }
                 activeSessions.set(session.id, session);
                 defaultSessionId = session.id;
-                startHeartbeat();
+                startSessionHeartbeat(session);
+                safeRecordSessionSnapshot(session, 'session.open', {
+                    awaitInitialFrame: false,
+                });
                 resolve(session);
             }
         });
         ws.on('message', (data) => {
+            noteSessionSocketActivity(session, ws);
             if (session.ws !== ws)
                 return;
-            lastMessageAt = Date.now();
             try {
                 const msg = JSON.parse(String(data));
                 if (msg.type === 'frame') {
@@ -731,6 +859,7 @@ export function connect(url, opts) {
                     session.updateRevision++;
                     invalidateSessionCaches(session);
                     const connectTrace = session.connectTrace;
+                    const firstFrame = connectTrace?.firstFrameMs === undefined;
                     if (connectTrace && connectTrace.firstFrameMs === undefined) {
                         connectTrace.firstFrameMs = performance.now() - startedAt;
                     }
@@ -742,9 +871,15 @@ export function connect(url, opts) {
                         }
                         activeSessions.set(session.id, session);
                         defaultSessionId = session.id;
-                        startHeartbeat();
+                        startSessionHeartbeat(session);
+                        safeRecordSessionSnapshot(session, 'session.connected');
                         resolve(session);
                     }
+                    else if (firstFrame) {
+                        safeRecordSessionSnapshot(session, 'session.connected', {
+                            lateInitialFrame: session.connectTrace?.resolvedWithoutInitialFrame === true,
+                        });
+                    }
                 }
                 else if (msg.type === 'patch' && session.layout) {
                     applyPatches(session.layout, msg.patches);
@@ -756,6 +891,10 @@ export function connect(url, opts) {
         });
         ws.on('error', (err) => {
             if (!resolved) {
+                safeFailSessionLifecycle(session, 'websocket_error', {
+                    transportUrl: url,
+                    message: err.message,
+                });
                 resolved = true;
                 clearTimeout(timeout);
                 reject(new Error(`WebSocket error connecting to ${url}: ${err.message}`));
@@ -764,30 +903,19 @@ export function connect(url, opts) {
         ws.on('close', () => {
             if (session.ws !== ws)
                 return;
-            if (heartbeatInterval) {
-                clearInterval(heartbeatInterval);
-                heartbeatInterval = null;
-            }
-            if (activeSessions.get(session.id) === session) {
-                activeSessions.delete(session.id);
-                if (defaultSessionId === session.id)
-                    promoteDefaultSession();
-                if (session.proxyChild && !session.proxyReusable) {
-                    try {
-                        session.proxyChild.kill('SIGTERM');
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }
-                if (session.proxyRuntime && !session.proxyReusable) {
-                    void session.proxyRuntime.close().catch(() => { });
-                }
-            }
             if (!resolved) {
+                safeFailSessionLifecycle(session, 'websocket_closed_before_ready', {
+                    transportUrl: url,
+                });
                 resolved = true;
                 clearTimeout(timeout);
                 reject(new Error(`Connection to ${url} closed before first frame`));
+                return;
+            }
+            if (activeSessions.get(session.id) === session && !session.lifecycleFinalized) {
+                safeRecordSessionSnapshot(session, 'session.transport_closed', {
+                    reconnectable: reconnectUrlForSession(session) !== null,
+                });
             }
         });
     });
@@ -858,7 +986,7 @@ export function getSession(id) {
 export function pruneDisconnectedSessions() {
     const removedIds = [];
     for (const [id, session] of activeSessions.entries()) {
-        if (session.ws.readyState === WebSocket.OPEN)
+        if (session.ws.readyState === WebSocket.OPEN || session.reconnectInFlight || reconnectUrlForSession(session))
             continue;
         removedIds.push(id);
         activeSessions.delete(id);
@@ -905,10 +1033,10 @@ export function getDefaultSessionId() {
 }
 export function disconnect(opts) {
     if (opts?.sessionId) {
-        shutdownSession(opts.sessionId, { closeProxy: opts.closeProxy ?? false });
+        shutdownSession(opts.sessionId, { closeProxy: opts?.closeProxy ?? false, reason: 'disconnect' });
     }
     else if (defaultSessionId) {
-        shutdownSession(defaultSessionId, { closeProxy: opts?.closeProxy ?? false });
+        shutdownSession(defaultSessionId, { closeProxy: opts?.closeProxy ?? false, reason: 'disconnect' });
     }
     if (opts?.closeProxy)
         closeReusableProxies();
@@ -1026,6 +1154,7 @@ async function openWebSocket(url, timeoutMs = SESSION_RECONNECT_TIMEOUT_MS) {
 }
 function bindReconnectedSocket(session, ws) {
     ws.on('message', data => {
+        noteSessionSocketActivity(session, ws);
         if (session.ws !== ws)
             return;
         try {
@@ -1046,13 +1175,16 @@ function bindReconnectedSocket(session, ws) {
             /* ignore malformed messages */
         }
     });
+    ws.on('pong', () => {
+        noteSessionSocketActivity(session, ws);
+    });
     ws.on('close', () => {
         if (session.ws !== ws)
             return;
-        if (activeSessions.get(session.id) === session) {
-            activeSessions.delete(session.id);
-            if (defaultSessionId === session.id)
-                promoteDefaultSession();
+        if (activeSessions.get(session.id) === session && !session.lifecycleFinalized) {
+            safeRecordSessionSnapshot(session, 'session.transport_closed', {
+                reconnectable: reconnectUrlForSession(session) !== null,
+            });
         }
     });
 }
@@ -1071,20 +1203,41 @@ async function ensureSessionConnected(session) {
         throw new Error('Not connected');
     }
     const reconnectPromise = (async () => {
-        const nextWs = await openWebSocket(targetUrl);
         try {
-            session.ws.close();
-        }
-        catch {
-            /* ignore */
+            const nextWs = await openWebSocket(targetUrl);
+            try {
+                session.ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            session.ws = nextWs;
+            noteSessionSocketActivity(session, nextWs);
+            bindReconnectedSocket(session, nextWs);
+            activeSessions.set(session.id, session);
+            if (!session.isolated) {
+                defaultSessionId = session.id;
+            }
+            startSessionHeartbeat(session);
+            safeRecordSessionSnapshot(session, 'session.reconnected', {
+                targetUrl,
+            });
+            return true;
         }
-        session.ws = nextWs;
-        bindReconnectedSocket(session, nextWs);
-        activeSessions.set(session.id, session);
-        if (!session.isolated) {
-            defaultSessionId = session.id;
+        catch (err) {
+            safeFailSessionLifecycle(session, 'reconnect_failed', {
+                targetUrl,
+                message: formatUnknownError(err),
+            });
+            if (activeSessions.get(session.id) === session) {
+                activeSessions.delete(session.id);
+                if (defaultSessionId === session.id)
+                    promoteDefaultSession();
+            }
+            stopSessionHeartbeat(session);
+            releaseSessionResources(session, { closeProxy: true });
+            throw err;
         }
-        return true;
     })();
     session.reconnectInFlight = reconnectPromise;
     let recovered = false;
@@ -1296,10 +1449,18 @@ export function sendPdfGenerate(session, options, timeoutMs = 30_000) {
 }
 /** Navigate the proxy page to a new URL while keeping the browser process alive. */
 export function sendNavigate(session, url, timeoutMs = 15_000) {
-    return sendAndWaitForUpdate(session, {
-        type: 'navigate',
-        url,
-    }, timeoutMs, { requireUpdateOnAck: true });
+    return (async () => {
+        const result = await sendAndWaitForUpdate(session, {
+            type: 'navigate',
+            url,
+        }, timeoutMs, { requireUpdateOnAck: true });
+        safeRecordSessionSnapshot(session, 'session.navigate', {
+            requestedUrl: url,
+            status: result.status,
+            result: result.result ?? null,
+        });
+        return result;
+    })();
 }
 /**
  * Build a flat accessibility tree from the raw UI tree + layout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
   "dependencies": {
     "@geometra/proxy": "^1.19.23",
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "@razroo/parallel-mcp": "^0.1.0",
     "ws": "^8.18.0",
     "zod": "^3.23.0"
   },