@geometra/mcp 1.57.0 → 1.58.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/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

@@ -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';

package/dist/session.js

@@ -1,11 +1,12 @@
+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';
 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. */
@@ -229,11 +230,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 +253,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,11 +298,93 @@ 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) &&
@@ -477,6 +569,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) {
@@ -542,6 +639,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) {
@@ -603,6 +706,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 +751,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 +808,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 +827,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 +839,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 +859,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 +871,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 +954,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 +1001,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 +1122,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 +1143,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 +1171,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 +1417,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.58.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"
   },