@geometra/mcp 1.63.2 → 1.65.0

package/dist/session.js

@@ -1,8 +1,9 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
 import { resolveStealthMode, spawnGeometraProxy, startEmbeddedGeometraProxy, } from './proxy-spawn.js';
 import { completeSessionLifecycle, failSessionLifecycle, heartbeatSessionLifecycle, initializeSessionLifecycle, recordSessionSnapshot, } from './session-state.js';
+import { REDACTED_STATE_URL, sanitizeUrlToOrigin } from './state-privacy.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
@@ -20,12 +21,22 @@ const activeSessions = new Map();
 let defaultSessionId = null;
 const MAX_ACTIVE_SESSIONS = 5;
 function generateSessionId() { return `s_${randomUUID()}`; }
+class SessionCapacityError extends Error {
+    constructor(active, pending) {
+        super(`Geometra MCP already has ${active} active sessions and ${pending} pending connection(s) ` +
+            `(limit ${MAX_ACTIVE_SESSIONS}). Disconnect an explicit session before connecting another; ` +
+            'active owners are never evicted implicitly.');
+        this.name = 'SessionCapacityError';
+    }
+}
+const pendingSessionOwnership = new Set();
 let reusableProxies = [];
 const REUSABLE_PROXY_POOL_LIMIT = 6;
 /** Close idle reusable proxies after 5 minutes of inactivity. */
 const REUSABLE_PROXY_IDLE_TTL_MS = 5 * 60 * 1000;
 let idleProxyTimer = null;
 const trackedReusableProxyChildren = new WeakSet();
+const embeddedProxyClosePromises = new WeakMap();
 const ACTION_UPDATE_TIMEOUT_MS = 2000;
 const LISTBOX_UPDATE_TIMEOUT_MS = 4500;
 const FILL_BATCH_BASE_TIMEOUT_MS = 2500;
@@ -37,12 +48,418 @@ const FILL_BATCH_TOGGLE_FIELD_TIMEOUT_MS = 225;
 const FILL_BATCH_FILE_FIELD_TIMEOUT_MS = 5000;
 const FILL_BATCH_MAX_TIMEOUT_MS = 60_000;
 const SESSION_RECONNECT_TIMEOUT_MS = 5_000;
-let nextRequestSequence = 0;
+const GEOMETRY_PROTOCOL_VERSION = 1;
+const PROXY_ACTION_PROTOCOL_VERSION = 2;
+const MAX_AMBIGUOUS_OPERATIONS_PER_SESSION = 64;
+const MAX_AMBIGUOUS_WIRE_BYTES_PER_SESSION = 1024 * 1024;
+const MUTATING_PROXY_ACTION_TYPES = new Set([
+    'event',
+    'key',
+    'typeText',
+    'resize',
+    'navigate',
+    'composition',
+    'file',
+    'setFieldText',
+    'setFieldChoice',
+    'fillFields',
+    'fillOtp',
+    'listboxPick',
+    'selectOption',
+    'setChecked',
+    'wheel',
+    'pdfGenerate',
+]);
+class GeometraWireError extends Error {
+    code;
+    requestId;
+    actionId;
+    constructor(message, code, requestId, actionId) {
+        super(message);
+        this.name = 'GeometraWireError';
+        this.code = code;
+        this.requestId = requestId;
+        this.actionId = actionId;
+    }
+}
+const SAFE_NON_EXECUTION_WIRE_CODES = new Set([
+    'ACTION_EXPIRED',
+    'REQUEST_ID_CONFLICT',
+    'REQUEST_LEDGER_CAPACITY',
+]);
+function wireErrorFromMessage(msg, actionId) {
+    return new GeometraWireError(typeof msg.message === 'string' ? msg.message : 'Geometra server error', typeof msg.code === 'string' ? msg.code : undefined, typeof msg.requestId === 'string' ? msg.requestId : undefined, actionId);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function optionalFiniteProtocolVersion(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid Geometra server message: ${field} must be a finite number when present`);
+    }
+    return value;
+}
+function validatePatchMessage(patches) {
+    if (!Array.isArray(patches)) {
+        throw new Error('Invalid Geometra server patch: patches must be an array');
+    }
+    for (const patch of patches) {
+        if (!isRecord(patch) || !Array.isArray(patch.path) || !patch.path.every(segment => typeof segment === 'number' && Number.isInteger(segment) && segment >= 0)) {
+            throw new Error('Invalid Geometra server patch: every patch needs a non-negative integer path');
+        }
+        for (const key of ['x', 'y', 'width', 'height']) {
+            const value = patch[key];
+            if (value === undefined)
+                continue;
+            if (typeof value !== 'number' || !Number.isFinite(value) || ((key === 'width' || key === 'height') && value < 0)) {
+                throw new Error(`Invalid Geometra server patch: ${key} must be a finite${key === 'width' || key === 'height' ? ' non-negative' : ''} number`);
+            }
+        }
+    }
+}
+function parseInboundServerMessage(data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(String(data));
+    }
+    catch {
+        throw new Error('Invalid Geometra server message: expected valid JSON');
+    }
+    if (!isRecord(parsed) || typeof parsed.type !== 'string') {
+        throw new Error('Invalid Geometra server message: expected an object with a string type');
+    }
+    const geometryVersion = optionalFiniteProtocolVersion(parsed.geometryProtocolVersion, 'geometryProtocolVersion');
+    const proxyActionVersion = optionalFiniteProtocolVersion(parsed.proxyActionProtocolVersion, 'proxyActionProtocolVersion');
+    const legacyVersion = optionalFiniteProtocolVersion(parsed.protocolVersion, 'protocolVersion');
+    if (geometryVersion !== undefined && geometryVersion > GEOMETRY_PROTOCOL_VERSION) {
+        throw new Error(`Server geometry protocol ${geometryVersion} is newer than MCP geometry protocol ${GEOMETRY_PROTOCOL_VERSION}`);
+    }
+    if (proxyActionVersion !== undefined && proxyActionVersion > PROXY_ACTION_PROTOCOL_VERSION) {
+        throw new Error(`Server proxy-action protocol ${proxyActionVersion} is newer than MCP proxy-action protocol ${PROXY_ACTION_PROTOCOL_VERSION}`);
+    }
+    if (geometryVersion === undefined && proxyActionVersion === undefined && legacyVersion !== undefined && legacyVersion > PROXY_ACTION_PROTOCOL_VERSION) {
+        throw new Error(`Server protocol ${legacyVersion} is newer than MCP's supported geometry/proxy protocols`);
+    }
+    if (parsed.type === 'frame') {
+        if (!isRecord(parsed.layout) || !isRecord(parsed.tree)) {
+            throw new Error('Invalid Geometra server frame: layout and tree must be objects');
+        }
+        for (const key of ['x', 'y', 'width', 'height']) {
+            const value = parsed.layout[key];
+            if (typeof value !== 'number' || !Number.isFinite(value) || ((key === 'width' || key === 'height') && value < 0)) {
+                throw new Error(`Invalid Geometra server frame: layout.${key} is invalid`);
+            }
+        }
+        if (!Array.isArray(parsed.layout.children)) {
+            throw new Error('Invalid Geometra server frame: layout.children must be an array');
+        }
+    }
+    else if (parsed.type === 'patch') {
+        validatePatchMessage(parsed.patches);
+    }
+    else if (parsed.type === 'error' && typeof parsed.message !== 'string') {
+        throw new Error('Invalid Geometra server error: message must be a string');
+    }
+    else if (parsed.type === 'ack' && parsed.requestId !== undefined && typeof parsed.requestId !== 'string') {
+        throw new Error('Invalid Geometra server ack: requestId must be a string when present');
+    }
+    return parsed;
+}
+function updatePeerProtocol(session, msg) {
+    const geometryVersion = typeof msg.geometryProtocolVersion === 'number'
+        ? msg.geometryProtocolVersion
+        : undefined;
+    const proxyActionVersion = typeof msg.proxyActionProtocolVersion === 'number'
+        ? msg.proxyActionProtocolVersion
+        : undefined;
+    const legacyVersion = typeof msg.protocolVersion === 'number' ? msg.protocolVersion : undefined;
+    const capabilities = isRecord(msg.protocolCapabilities) ? msg.protocolCapabilities : undefined;
+    const transport = capabilities?.transport;
+    if (geometryVersion !== undefined || proxyActionVersion !== undefined || capabilities) {
+        session.peerAdvertisedSplitProtocol = true;
+    }
+    session.peerGeometryProtocolVersion = geometryVersion ?? (legacyVersion === PROXY_ACTION_PROTOCOL_VERSION ? GEOMETRY_PROTOCOL_VERSION : legacyVersion) ?? session.peerGeometryProtocolVersion ?? GEOMETRY_PROTOCOL_VERSION;
+    session.peerProxyActionProtocolVersion = proxyActionVersion ?? (legacyVersion === PROXY_ACTION_PROTOCOL_VERSION ? legacyVersion : session.peerProxyActionProtocolVersion);
+    if (transport === 'native' || transport === 'proxy') {
+        session.peerTransport = transport;
+    }
+    else if (proxyActionVersion !== undefined || legacyVersion === PROXY_ACTION_PROTOCOL_VERSION) {
+        session.peerTransport = 'proxy';
+    }
+    if (capabilities) {
+        session.peerProtocolCapabilities = {
+            authenticatedController: typeof capabilities.authenticatedController === 'boolean' ? capabilities.authenticatedController : undefined,
+            requestScopedAcks: typeof capabilities.requestScopedAcks === 'boolean' ? capabilities.requestScopedAcks : undefined,
+            actionDeadlines: typeof capabilities.actionDeadlines === 'boolean' ? capabilities.actionDeadlines : undefined,
+            idempotentRequestIds: typeof capabilities.idempotentRequestIds === 'boolean' ? capabilities.idempotentRequestIds : undefined,
+            atomicTypeText: typeof capabilities.atomicTypeText === 'boolean' ? capabilities.atomicTypeText : undefined,
+            proxyActions: typeof capabilities.proxyActions === 'boolean' ? capabilities.proxyActions : undefined,
+            exactFieldIdentity: typeof capabilities.exactFieldIdentity === 'boolean' ? capabilities.exactFieldIdentity : undefined,
+            verifiedFileUploads: typeof capabilities.verifiedFileUploads === 'boolean' ? capabilities.verifiedFileUploads : undefined,
+            binaryFraming: typeof capabilities.binaryFraming === 'boolean' ? capabilities.binaryFraming : undefined,
+        };
+    }
+}
+function outboundProtocolMetadata(session) {
+    const geometryVersion = Math.min(session.peerGeometryProtocolVersion ?? GEOMETRY_PROTOCOL_VERSION, GEOMETRY_PROTOCOL_VERSION);
+    const proxyActionVersion = session.peerProxyActionProtocolVersion === undefined
+        ? undefined
+        : Math.min(session.peerProxyActionProtocolVersion, PROXY_ACTION_PROTOCOL_VERSION);
+    if (session.peerAdvertisedSplitProtocol) {
+        return {
+            protocolVersion: proxyActionVersion ?? geometryVersion,
+            geometryProtocolVersion: geometryVersion,
+            ...(proxyActionVersion !== undefined ? { proxyActionProtocolVersion: proxyActionVersion } : {}),
+        };
+    }
+    return { protocolVersion: proxyActionVersion ?? geometryVersion };
+}
+function canonicalActionJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalActionJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${canonicalActionJson(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function actionFingerprint(value) {
+    return createHash('sha256').update(canonicalActionJson(value)).digest('hex');
+}
+function isMutatingProxyAction(message) {
+    return typeof message.type === 'string' && MUTATING_PROXY_ACTION_TYPES.has(message.type);
+}
+function actionTimeoutFor(session, message, timeoutMs) {
+    if (session.peerTransport !== 'proxy' ||
+        session.peerProtocolCapabilities?.actionDeadlines !== true ||
+        !isMutatingProxyAction(message)) {
+        return undefined;
+    }
+    return timeoutMs;
+}
+function ambiguousOperationFor(session, fingerprint) {
+    return session.ambiguousOperations?.get(fingerprint) ?? session.inFlightMutations?.get(fingerprint);
+}
+function assertCanStartMutatingOperation(session, fingerprint) {
+    const operations = session.ambiguousOperations;
+    const trackedCount = (operations?.size ?? 0) + (session.inFlightMutations?.size ?? 0);
+    if (operations?.has(fingerprint) || session.inFlightMutations?.has(fingerprint) || trackedCount < MAX_AMBIGUOUS_OPERATIONS_PER_SESSION)
+        return;
+    throw new Error(`Session ${session.id} has ${trackedCount} unresolved action outcomes. ` +
+        'Inspect or reconnect the session before sending another mutation; Geometra refused to risk a duplicate action.');
+}
+function rememberAmbiguousOperation(session, operation) {
+    if (session.inFlightMutations?.get(operation.fingerprint) === operation) {
+        session.inFlightMutations.delete(operation.fingerprint);
+    }
+    const operations = session.ambiguousOperations ?? new Map();
+    session.ambiguousOperations = operations;
+    if (!operations.has(operation.fingerprint)) {
+        const retainedWireBytes = Array.from(operations.values()).reduce((total, candidate) => total + retainedOperationBytes(candidate), 0);
+        const operationWireBytes = retainedOperationBytes(operation);
+        if (retainedWireBytes + operationWireBytes > MAX_AMBIGUOUS_WIRE_BYTES_PER_SESSION) {
+            // Retain the hash and identities so the action remains blocked, but do
+            // not retain potentially sensitive field values merely for ergonomics.
+            operation.wireMessages = [];
+            operation.idempotent = false;
+        }
+    }
+    operations.set(operation.fingerprint, operation);
+}
+const OMITTED_TERMINAL_RESULT = {
+    retained: false,
+    reason: 'Terminal action result exceeded the 1 MiB per-session ambiguity retention cap.',
+};
+function retainedCompletionBytes(operation) {
+    if (operation.completion?.kind !== 'result' || operation.completion.value.result === undefined)
+        return 0;
+    try {
+        return Buffer.byteLength(JSON.stringify(operation.completion.value.result));
+    }
+    catch {
+        return 0;
+    }
+}
+function retainedOperationBytes(operation) {
+    return operation.wireMessages.reduce((sum, wire) => sum + Buffer.byteLength(wire), 0) +
+        retainedCompletionBytes(operation);
+}
+function boundedTerminalResult(session, operation, result) {
+    if (!operation.permanentTombstone || result === undefined)
+        return result;
+    let resultBytes;
+    try {
+        resultBytes = Buffer.byteLength(JSON.stringify(result));
+    }
+    catch {
+        return OMITTED_TERMINAL_RESULT;
+    }
+    const otherOperations = new Set([
+        ...Array.from(session.ambiguousOperations?.values() ?? []),
+        ...Array.from(session.inFlightMutations?.values() ?? []),
+    ]);
+    otherOperations.delete(operation);
+    const retainedBytes = Array.from(otherOperations).reduce((total, candidate) => total + retainedOperationBytes(candidate), 0);
+    if (retainedBytes + resultBytes <= MAX_AMBIGUOUS_WIRE_BYTES_PER_SESSION)
+        return result;
+    const markerBytes = Buffer.byteLength(JSON.stringify(OMITTED_TERMINAL_RESULT));
+    return retainedBytes + markerBytes <= MAX_AMBIGUOUS_WIRE_BYTES_PER_SESSION
+        ? OMITTED_TERMINAL_RESULT
+        : undefined;
+}
+function retainTerminalResult(session, operation, value) {
+    operation.wireMessages = [];
+    const result = boundedTerminalResult(session, operation, value.result);
+    operation.completion = {
+        kind: 'result',
+        value: {
+            ...value,
+            ...(result !== undefined ? { result } : {}),
+        },
+    };
+}
+function retainTerminalError(operation, error) {
+    operation.wireMessages = [];
+    operation.completion = { kind: 'error', error };
+}
+function trackInFlightMutation(session, operation) {
+    if (!operation.mutating)
+        return;
+    const retainedWireBytes = [
+        ...Array.from(session.ambiguousOperations?.values() ?? []),
+        ...Array.from(session.inFlightMutations?.values() ?? []),
+    ].reduce((total, candidate) => total + retainedOperationBytes(candidate), 0);
+    const operationWireBytes = retainedOperationBytes(operation);
+    if (retainedWireBytes + operationWireBytes > MAX_AMBIGUOUS_WIRE_BYTES_PER_SESSION) {
+        throw new Error('In-flight action replay data would exceed the 1 MiB per-session safety cap; Geometra refused to send the mutation.');
+    }
+    const operations = session.inFlightMutations ?? new Map();
+    session.inFlightMutations = operations;
+    operations.set(operation.fingerprint, operation);
+}
+function forgetAmbiguousOperation(session, operation) {
+    if (session.ambiguousOperations?.get(operation.fingerprint) === operation) {
+        session.ambiguousOperations.delete(operation.fingerprint);
+    }
+    if (session.inFlightMutations?.get(operation.fingerprint) === operation) {
+        session.inFlightMutations.delete(operation.fingerprint);
+    }
+}
+function stickyAmbiguousError(operation, error) {
+    const marker = `Outcome is ambiguous for actionId ${operation.actionId} (requestId ${operation.requestId})`;
+    if (error instanceof GeometraWireError &&
+        error.requestId === operation.requestId &&
+        error.actionId === operation.actionId &&
+        error.message.includes(marker)) {
+        return error;
+    }
+    const sourceMessage = error instanceof Error ? error.message : String(error);
+    return new GeometraWireError(`${sourceMessage} ${marker}; do not retry blindly.`, error instanceof GeometraWireError
+        ? error.code ?? 'ACTION_OUTCOME_AMBIGUOUS'
+        : 'ACTION_OUTCOME_AMBIGUOUS', operation.requestId, operation.actionId);
+}
+function cacheLateAmbiguousOutcome(session, msg) {
+    const requestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
+    if (!requestId)
+        return;
+    const tracked = [
+        ...Array.from(session.ambiguousOperations?.values() ?? []),
+        ...Array.from(session.inFlightMutations?.values() ?? []),
+    ];
+    const operation = tracked.find(candidate => candidate.requestIds.includes(requestId));
+    if (!operation || operation.completion)
+        return;
+    if (msg.type === 'error') {
+        if (msg.code === 'DUPLICATE_REQUEST')
+            return;
+        const error = wireErrorFromMessage(msg, operation.actionId);
+        if (typeof msg.code === 'string' &&
+            SAFE_NON_EXECUTION_WIRE_CODES.has(msg.code) &&
+            operation.requestIds.length === 1) {
+            retainTerminalError(operation, error);
+        }
+        else {
+            // A logical action may have many phases. Once any phase fails, a later
+            // final-phase ACK cannot prove that the whole action completed.
+            operation.wireMessages = [];
+            operation.stickyError = stickyAmbiguousError(operation, error);
+        }
+        return;
+    }
+    if (msg.type === 'ack') {
+        if (requestId !== operation.requestId)
+            return;
+        if (operation.stickyError)
+            return;
+        // Navigation and similar operations require a fresh post-action frame.
+        // A late ACK cannot establish that evidence on its own.
+        if (operation.requireUpdateOnAck)
+            return;
+        const peerProtocolVersion = typeof msg.proxyActionProtocolVersion === 'number'
+            ? msg.proxyActionProtocolVersion
+            : typeof msg.protocolVersion === 'number'
+                ? msg.protocolVersion
+                : session.peerProxyActionProtocolVersion;
+        if (operation.requiredProtocolVersion !== undefined && (peerProtocolVersion === undefined || peerProtocolVersion < operation.requiredProtocolVersion)) {
+            operation.wireMessages = [];
+            operation.stickyError = stickyAmbiguousError(operation, new Error(`Proxy protocol ${peerProtocolVersion ?? 'unknown'} cannot guarantee exact field identity; ` +
+                `protocol ${operation.requiredProtocolVersion}+ is required. Update and reconnect the Geometra proxy.`));
+            return;
+        }
+        retainTerminalResult(session, operation, {
+            status: 'acknowledged',
+            timeoutMs: operation.timeoutMs,
+            requestId: operation.requestId,
+            actionId: operation.actionId,
+            ...(msg.result !== undefined ? { result: msg.result } : {}),
+        });
+        return;
+    }
+}
 function invalidateSessionCaches(session) {
     session.cachedA11y = null;
     session.cachedA11yRevision = -1;
     session.cachedFormSchemas?.clear();
 }
+function invalidateSessionUiState(session) {
+    session.hasFreshFrame = false;
+    session.layout = null;
+    session.tree = null;
+    invalidateSessionCaches(session);
+}
+function applyInboundSessionMessage(session, data) {
+    const msg = parseInboundServerMessage(data);
+    updatePeerProtocol(session, msg);
+    if (msg.type === 'frame') {
+        session.layout = msg.layout;
+        session.tree = msg.tree;
+        session.hasFreshFrame = true;
+        session.updateRevision++;
+        invalidateSessionCaches(session);
+    }
+    else if (msg.type === 'patch' && session.hasFreshFrame === true && session.layout) {
+        applyPatches(session.layout, msg.patches);
+        session.updateRevision++;
+        invalidateSessionCaches(session);
+    }
+    cacheLateAmbiguousOutcome(session, msg);
+    return msg;
+}
+function assertAuthenticatedProxyHandshake(session) {
+    const expectedAuthenticatedProxy = session.transportAuthToken !== undefined;
+    const advertisedProxy = session.peerTransport === 'proxy';
+    if (!expectedAuthenticatedProxy && !advertisedProxy)
+        return;
+    if (session.peerTransport !== 'proxy' ||
+        session.peerProtocolCapabilities?.authenticatedController !== true) {
+        throw new Error('Geometra proxy did not attest authenticated controller support. Rebuild or update @geometra/proxy; unauthenticated proxy transports are refused.');
+    }
+}
 function sameReusableProxyEntry(entry, proxy) {
     return ('child' in proxy && !!entry.child && entry.child === proxy.child)
         || ('runtime' in proxy && !!entry.runtime && entry.runtime === proxy.runtime);
@@ -61,6 +478,8 @@ function reusableProxyEntryIsActive(entry) {
 }
 function clearReusableProxiesIfExited() {
     reusableProxies = reusableProxies.filter(entry => {
+        if (entry.closed)
+            return false;
         if (entry.child) {
             return !entry.child.killed && entry.child.exitCode === null && entry.child.signalCode === null;
         }
@@ -75,7 +494,27 @@ function updateReusableProxySnapshotState(entry, session) {
         entry.snapshotReady = true;
     }
 }
+function closeEmbeddedProxyRuntime(runtime) {
+    const existing = embeddedProxyClosePromises.get(runtime);
+    if (existing)
+        return existing;
+    let settle;
+    const closing = new Promise(resolve => { settle = resolve; });
+    // Publish the promise before invoking user/runtime code so even a
+    // re-entrant cleanup observes the same close operation.
+    embeddedProxyClosePromises.set(runtime, closing);
+    try {
+        void runtime.close().then(settle, settle);
+    }
+    catch {
+        settle();
+    }
+    return closing;
+}
 function closeReusableProxy(entry) {
+    if (entry.closed)
+        return;
+    entry.closed = true;
     reusableProxies = reusableProxies.filter(candidate => candidate !== entry);
     if (entry.child) {
         try {
@@ -87,24 +526,15 @@ function closeReusableProxy(entry) {
         ensureIdleProxyTimer();
         return;
     }
-    void entry.runtime?.close().catch(() => { });
+    if (entry.runtime)
+        void closeEmbeddedProxyRuntime(entry.runtime);
     ensureIdleProxyTimer();
 }
 function closeReusableProxies() {
     clearReusableProxiesIfExited();
     const proxies = [...reusableProxies];
-    reusableProxies = [];
     for (const entry of proxies) {
-        if (entry.child) {
-            try {
-                entry.child.kill('SIGTERM');
-            }
-            catch {
-                /* ignore */
-            }
-            continue;
-        }
-        void entry.runtime?.close().catch(() => { });
+        closeReusableProxy(entry);
     }
 }
 function evictIdleReusableProxies() {
@@ -142,11 +572,13 @@ function enforceReusableProxyPoolLimit() {
 function setReusableProxy(proxy, wsUrl, opts) {
     clearReusableProxiesIfExited();
     const now = Date.now();
+    const authToken = 'child' in proxy ? proxy.authToken : proxy.runtime.authToken;
     const proxyKey = proxyKeyFor(opts.proxy);
     const stealth = resolveStealthMode(opts.stealth);
     const existing = reusableProxies.find(entry => sameReusableProxyEntry(entry, proxy));
     if (existing) {
         existing.wsUrl = wsUrl;
+        existing.authToken = authToken;
         existing.headless = opts.headless !== false;
         existing.stealth = stealth;
         existing.slowMo = opts.slowMo ?? 0;
@@ -163,6 +595,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         const entry = {
             child,
             wsUrl,
+            authToken,
             headless: opts.headless !== false,
             stealth,
             slowMo: opts.slowMo ?? 0,
@@ -190,6 +623,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
     reusableProxies.push({
         runtime: proxy.runtime,
         wsUrl,
+        authToken,
         headless: opts.headless !== false,
         stealth,
         slowMo: opts.slowMo ?? 0,
@@ -235,23 +669,15 @@ function promoteDefaultSession() {
     }
     defaultSessionId = null;
 }
-/**
- * Clear `defaultSessionId` if it currently points at the given session id.
- * Used after tagging a fresh session as isolated — `connect()` set the
- * default pointer before the isolation flag was applied, and we need to
- * retract that assignment so this session is only addressable by its
- * explicit id.
- */
-function retractDefaultIfPointsTo(sessionId) {
-    if (defaultSessionId === sessionId) {
-        promoteDefaultSession();
-    }
-}
 function shutdownSession(id, opts) {
     const prev = activeSessions.get(id);
     if (!prev)
         return;
-    const forceCloseProxy = prev.isolated === true;
+    const hasUnsettledMutation = Boolean(prev.inFlightMutations?.size || prev.ambiguousOperations?.size);
+    prev.disposed = true;
+    prev.ambiguousOperations?.clear();
+    prev.inFlightMutations?.clear();
+    const forceCloseProxy = prev.isolated === true || hasUnsettledMutation;
     safeCompleteSessionLifecycle(prev, opts?.reason ?? 'disconnect', {
         closeProxy: opts?.closeProxy ?? false,
         forceCloseProxy,
@@ -260,7 +686,8 @@ function shutdownSession(id, opts) {
     if (defaultSessionId === id)
         promoteDefaultSession();
     stopSessionHeartbeat(prev);
-    releaseSessionResources(prev, { closeProxy: opts?.closeProxy ?? false });
+    releaseSessionResources(prev, { closeProxy: (opts?.closeProxy ?? false) || hasUnsettledMutation });
+    invalidateSessionUiState(prev);
 }
 function releaseSessionResources(session, opts) {
     try {
@@ -311,19 +738,65 @@ function releaseSessionResources(session, opts) {
             closeReusableProxy(entry);
             return;
         }
-        void session.proxyRuntime.close().catch(() => { });
+        void closeEmbeddedProxyRuntime(session.proxyRuntime);
+    }
+}
+/**
+ * Reserve one ownership slot before any asynchronous transport or browser
+ * startup. Passing the same lease is idempotent, which lets an embedded
+ * connection hand its reservation through to `connect()` and safely
+ * reacquire it before a child-process fallback.
+ */
+function reserveSessionOwnership(existing) {
+    if (existing?.reserved && pendingSessionOwnership.has(existing))
+        return existing;
+    pruneDisconnectedSessions();
+    if (activeSessions.size + pendingSessionOwnership.size >= MAX_ACTIVE_SESSIONS) {
+        throw new SessionCapacityError(activeSessions.size, pendingSessionOwnership.size);
     }
+    const lease = existing ?? { id: randomUUID(), reserved: false, connectAttemptActive: false };
+    lease.reserved = true;
+    pendingSessionOwnership.add(lease);
+    return lease;
+}
+function beginSessionOwnershipAttempt(existing) {
+    const lease = reserveSessionOwnership(existing);
+    if (lease.connectAttemptActive) {
+        throw new Error(`Session ownership lease ${lease.id} is already assigned to a pending connection attempt`);
+    }
+    lease.connectAttemptActive = true;
+    return lease;
 }
-/** Evict the oldest session when at capacity. */
-function evictOldestSession() {
-    if (activeSessions.size < MAX_ACTIVE_SESSIONS)
+function releaseSessionOwnership(lease) {
+    if (!lease.reserved)
         return;
-    const oldestId = activeSessions.keys().next().value;
-    shutdownSession(oldestId, { closeProxy: false, reason: 'evicted' });
+    pendingSessionOwnership.delete(lease);
+    lease.reserved = false;
+    lease.connectAttemptActive = false;
+}
+function claimSessionOwnership(lease, session) {
+    if (!lease.reserved || !pendingSessionOwnership.has(lease)) {
+        throw new Error(`Session ownership lease ${lease.id} was not reserved when connection completed`);
+    }
+    // The transition is synchronous: no other connect can observe a moment
+    // where both the pending reservation and active owner are absent.
+    pendingSessionOwnership.delete(lease);
+    lease.reserved = false;
+    lease.connectAttemptActive = false;
+    activeSessions.set(session.id, session);
 }
 function formatUnknownError(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * Durable lifecycle records only need enough URL context to identify the
+ * remote origin. Paths, query strings, fragments, and credentials can carry
+ * application data or bearer capabilities, so call sites must not forward
+ * them to the persistence layer.
+ */
+function lifecycleUrlOrigin(rawUrl) {
+    return sanitizeUrlToOrigin(rawUrl) ?? REDACTED_STATE_URL;
+}
 function rejectOnRuntimeReadyFailure(runtime) {
     return new Promise((_, reject) => {
         runtime.ready.catch(reject);
@@ -423,11 +896,8 @@ function reusableProxyMatchesOptions(entry, options) {
 function findExactReusableProxy(options) {
     clearReusableProxiesIfExited();
     return reusableProxies
-        .filter(entry => reusableProxyMatchesOptions(entry, options))
-        .sort((a, b) => {
-        const activeBonus = reusableProxyEntryIsActive(b) ? 1 : reusableProxyEntryIsActive(a) ? -1 : 0;
-        return activeBonus || b.lastUsedAt - a.lastUsedAt;
-    })[0];
+        .filter(entry => !reusableProxyEntryIsActive(entry) && reusableProxyMatchesOptions(entry, options))
+        .sort((a, b) => b.lastUsedAt - a.lastUsedAt)[0];
 }
 function findReusableProxy(options) {
     clearReusableProxiesIfExited();
@@ -438,7 +908,8 @@ function findReusableProxy(options) {
     const desiredHeight = options.height ?? 720;
     const desiredProxyKey = proxyKeyFor(options.proxy);
     return reusableProxies
-        .filter(entry => entry.headless === desiredHeadless
+        .filter(entry => !reusableProxyEntryIsActive(entry)
+        && entry.headless === desiredHeadless
         && entry.stealth === desiredStealth
         && entry.slowMo === desiredSlowMo
         // Proxy partition is hard: a session with a caller-provided proxy MUST
@@ -452,8 +923,6 @@ function findReusableProxy(options) {
                 value += 100;
             if (entry.width === desiredWidth && entry.height === desiredHeight)
                 value += 10;
-            if (reusableProxyEntryIsActive(entry))
-                value += 5;
             return value;
         };
         return score(b) - score(a) || b.lastUsedAt - a.lastUsedAt;
@@ -492,7 +961,7 @@ export async function prewarmProxy(options) {
             await runtime.ready;
         }
         catch (err) {
-            await runtime.close().catch(() => { });
+            await closeEmbeddedProxyRuntime(runtime);
             throw err;
         }
         setReusableProxy({ runtime }, wsUrl, {
@@ -521,7 +990,7 @@ export async function prewarmProxy(options) {
         embeddedFailure = err;
     }
     try {
-        const { child, wsUrl } = await spawnGeometraProxy({
+        const { child, wsUrl, authToken } = await spawnGeometraProxy({
             pageUrl: options.pageUrl,
             port: options.port ?? 0,
             headless: options.headless,
@@ -531,7 +1000,7 @@ export async function prewarmProxy(options) {
             stealth: options.stealth,
             proxy: options.proxy,
         });
-        setReusableProxy({ child }, wsUrl, {
+        setReusableProxy({ child, authToken }, wsUrl, {
             headless: options.headless,
             slowMo: options.slowMo,
             stealth: options.stealth,
@@ -561,17 +1030,15 @@ async function attachToReusableProxy(proxy, options) {
     const desiredWidth = options.width ?? proxy.width;
     const desiredHeight = options.height ?? proxy.height;
     const needsSnapshotKickoff = options.awaitInitialFrame !== false && !proxy.snapshotReady;
-    let reusedExistingSession = null;
-    for (const s of activeSessions.values()) {
-        if ((proxy.child && s.proxyChild === proxy.child) || (proxy.runtime && s.proxyRuntime === proxy.runtime)) {
-            reusedExistingSession = s;
-            break;
-        }
+    if (reusableProxyEntryIsActive(proxy)) {
+        throw new Error('Reusable proxy already has an active session owner');
     }
-    const session = reusedExistingSession ?? await connect(proxy.wsUrl, {
+    const session = await connect(proxy.wsUrl, {
         skipInitialResize: true,
         closePreviousProxy: false,
         awaitInitialFrame: needsSnapshotKickoff ? false : options.awaitInitialFrame,
+        authToken: proxy.authToken,
+        isolated: false,
     });
     if (!session) {
         throw new Error('Failed to attach to reusable proxy session');
@@ -580,166 +1047,103 @@ async function attachToReusableProxy(proxy, options) {
     session.proxyRuntime = proxy.runtime;
     session.proxyReusable = true;
     touchReusableProxy(proxy);
-    let resizeKickoffMs;
-    if (needsSnapshotKickoff || desiredWidth !== proxy.width || desiredHeight !== proxy.height) {
-        const resizeStartedAt = performance.now();
-        const resizeWait = await sendResizeAndWaitForUpdate(session, desiredWidth, desiredHeight, 5_000);
-        resizeKickoffMs = performance.now() - resizeStartedAt;
-        if (needsSnapshotKickoff && resizeWait.status === 'timed_out' && (!session.tree || !session.layout)) {
-            throw new Error('Timed out waiting for initial proxy snapshot after resize kickoff');
-        }
-        proxy.width = desiredWidth;
-        proxy.height = desiredHeight;
+    try {
+        let resizeKickoffMs;
+        if (needsSnapshotKickoff || desiredWidth !== proxy.width || desiredHeight !== proxy.height) {
+            const resizeStartedAt = performance.now();
+            const resizeWait = await sendResizeAndWaitForUpdate(session, desiredWidth, desiredHeight, 5_000);
+            resizeKickoffMs = performance.now() - resizeStartedAt;
+            if (needsSnapshotKickoff && resizeWait.status === 'timed_out' && (!session.tree || !session.layout)) {
+                throw new Error('Timed out waiting for initial proxy snapshot after resize kickoff');
+            }
+            proxy.width = desiredWidth;
+            proxy.height = desiredHeight;
+            updateReusableProxySnapshotState(proxy, session);
+        }
+        const currentUrl = session.cachedA11y?.meta?.pageUrl ?? proxy.pageUrl;
+        let navigateMs;
+        if (currentUrl !== options.pageUrl) {
+            const navigateStartedAt = performance.now();
+            await sendNavigate(session, options.pageUrl, 15_000);
+            navigateMs = performance.now() - navigateStartedAt;
+            proxy.pageUrl = options.pageUrl;
+            updateReusableProxySnapshotState(proxy, session);
+        }
+        const baseConnectTrace = session.connectTrace;
+        session.connectTrace = {
+            mode: 'reused-proxy',
+            reused: true,
+            awaitInitialFrame: options.awaitInitialFrame !== false,
+            connectMs: baseConnectTrace?.totalMs ?? 0,
+            wsOpenMs: baseConnectTrace?.wsOpenMs,
+            firstFrameMs: baseConnectTrace?.firstFrameMs,
+            resolvedWithoutInitialFrame: baseConnectTrace?.resolvedWithoutInitialFrame,
+            snapshotKickoff: needsSnapshotKickoff,
+            resizeKickoffMs,
+            navigateMs,
+            totalMs: performance.now() - startedAt,
+        };
         updateReusableProxySnapshotState(proxy, session);
+        safeRecordSessionSnapshot(session, 'session.proxy_attached', {
+            transportMode: 'reused-proxy',
+            targetPageOrigin: lifecycleUrlOrigin(options.pageUrl),
+            reusedExistingSession: false,
+        });
+        return session;
     }
-    const currentUrl = session.cachedA11y?.meta?.pageUrl ?? proxy.pageUrl;
-    let navigateMs;
-    if (currentUrl !== options.pageUrl) {
-        const navigateStartedAt = performance.now();
-        await sendNavigate(session, options.pageUrl, 15_000);
-        navigateMs = performance.now() - navigateStartedAt;
-        proxy.pageUrl = options.pageUrl;
-        updateReusableProxySnapshotState(proxy, session);
+    catch (err) {
+        // The provisional WebSocket session must not remain an active owner when
+        // resize/navigation fails. Release only the session here; the caller owns
+        // eviction of the stale warm proxy entry.
+        shutdownSession(session.id, { closeProxy: false, reason: 'proxy_attach_failed' });
+        throw err;
     }
-    const baseConnectTrace = !reusedExistingSession ? session.connectTrace : undefined;
-    session.connectTrace = {
-        mode: 'reused-proxy',
-        reused: true,
-        awaitInitialFrame: options.awaitInitialFrame !== false,
-        connectMs: baseConnectTrace?.totalMs ?? 0,
-        wsOpenMs: baseConnectTrace?.wsOpenMs,
-        firstFrameMs: baseConnectTrace?.firstFrameMs,
-        resolvedWithoutInitialFrame: baseConnectTrace?.resolvedWithoutInitialFrame,
-        snapshotKickoff: needsSnapshotKickoff,
-        resizeKickoffMs,
-        navigateMs,
-        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) {
+async function startFreshProxySession(options, initialOwnershipLease) {
     const startedAt = performance.now();
     const eagerInitialExtract = options.eagerInitialExtract !== undefined
         ? options.eagerInitialExtract
         : options.awaitInitialFrame !== false
             ? undefined
             : false;
+    let ownershipLease = reserveSessionOwnership(initialOwnershipLease);
     let pendingEmbeddedRuntime;
+    let pendingEmbeddedConnect;
+    let attachedEmbeddedSession;
     try {
-        const proxyStartStartedAt = performance.now();
-        const { runtime, wsUrl } = await startEmbeddedGeometraProxy({
-            pageUrl: options.pageUrl,
-            port: options.port ?? 0,
-            headless: options.headless,
-            width: options.width,
-            height: options.height,
-            slowMo: options.slowMo,
-            stealth: options.stealth,
-            eagerInitialExtract,
-            proxy: options.proxy,
-        });
-        pendingEmbeddedRuntime = runtime;
-        const proxyStartMs = performance.now() - proxyStartStartedAt;
-        const session = await Promise.race([
-            connect(wsUrl, {
-                skipInitialResize: true,
-                closePreviousProxy: false,
-                awaitInitialFrame: options.awaitInitialFrame,
-            }),
-            rejectOnRuntimeReadyFailure(runtime),
-        ]);
-        // Connect succeeded — the session now owns the runtime, so the
-        // catch-block cleanup below must not also close it.
-        pendingEmbeddedRuntime = undefined;
-        session.proxyRuntime = runtime;
-        session.proxyReusable = !options.isolated;
-        if (options.isolated) {
-            session.isolated = true;
-            // connect() already set defaultSessionId to this session. Retract
-            // that assignment so the isolated session is only addressable by its
-            // explicit id — the implicit-default fallback is the contamination
-            // vector we're fixing, and an isolated session must never be the
-            // implicit target of a tool call that omits sessionId.
-            retractDefaultIfPointsTo(session.id);
-        }
-        else {
-            setReusableProxy({ runtime }, wsUrl, {
+        try {
+            const proxyStartStartedAt = performance.now();
+            const { runtime, wsUrl } = await startEmbeddedGeometraProxy({
+                pageUrl: options.pageUrl,
+                port: options.port ?? 0,
                 headless: options.headless,
-                slowMo: options.slowMo,
-                stealth: options.stealth,
                 width: options.width,
                 height: options.height,
-                pageUrl: options.pageUrl,
-                snapshotReady: Boolean(session.tree && session.layout),
+                slowMo: options.slowMo,
+                stealth: options.stealth,
+                eagerInitialExtract,
                 proxy: options.proxy,
             });
-        }
-        const baseConnectTrace = session.connectTrace;
-        session.connectTrace = {
-            mode: 'fresh-proxy',
-            reused: false,
-            awaitInitialFrame: options.awaitInitialFrame !== false,
-            proxyStartMode: 'embedded',
-            proxyStartMs,
-            connectMs: baseConnectTrace?.totalMs,
-            wsOpenMs: baseConnectTrace?.wsOpenMs,
-            firstFrameMs: baseConnectTrace?.firstFrameMs,
-            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) {
-        // If startEmbeddedGeometraProxy() returned but the subsequent connect()
-        // threw (e.g. WebSocket failure, first-frame timeout), the runtime
-        // still owns a launched Chromium that nobody is going to clean up.
-        // Without this, that Chromium leaks for the lifetime of the MCP server
-        // every time we fall through to the child-process fallback path.
-        if (pendingEmbeddedRuntime) {
-            const leaked = pendingEmbeddedRuntime;
-            void leaked.close().catch(() => { });
-        }
-        const proxyStartStartedAt = performance.now();
-        const { child, wsUrl } = await spawnGeometraProxy({
-            pageUrl: options.pageUrl,
-            port: options.port ?? 0,
-            headless: options.headless,
-            width: options.width,
-            height: options.height,
-            slowMo: options.slowMo,
-            stealth: options.stealth,
-            eagerInitialExtract,
-            proxy: options.proxy,
-        });
-        const proxyStartMs = performance.now() - proxyStartStartedAt;
-        try {
-            const session = await connect(wsUrl, {
+            pendingEmbeddedRuntime = runtime;
+            const proxyStartMs = performance.now() - proxyStartStartedAt;
+            pendingEmbeddedConnect = connectWithOwnership(wsUrl, {
                 skipInitialResize: true,
                 closePreviousProxy: false,
                 awaitInitialFrame: options.awaitInitialFrame,
+                authToken: runtime.authToken,
+                isolated: options.isolated === true,
+                ownershipLease,
             });
-            session.proxyChild = child;
+            const session = await Promise.race([
+                pendingEmbeddedConnect,
+                rejectOnRuntimeReadyFailure(runtime),
+            ]);
+            pendingEmbeddedConnect = undefined;
+            attachedEmbeddedSession = session;
+            session.proxyRuntime = runtime;
             session.proxyReusable = !options.isolated;
-            if (options.isolated) {
-                session.isolated = true;
-                // See the embedded-runtime path above — an isolated session must
-                // not be the implicit default. Retract the pointer set by connect().
-                retractDefaultIfPointsTo(session.id);
-            }
-            else {
-                setReusableProxy({ child }, wsUrl, {
+            if (!options.isolated) {
+                setReusableProxy({ runtime }, wsUrl, {
                     headless: options.headless,
                     slowMo: options.slowMo,
                     stealth: options.stealth,
@@ -755,7 +1159,7 @@ async function startFreshProxySession(options) {
                 mode: 'fresh-proxy',
                 reused: false,
                 awaitInitialFrame: options.awaitInitialFrame !== false,
-                proxyStartMode: 'child',
+                proxyStartMode: 'embedded',
                 proxyStartMs,
                 connectMs: baseConnectTrace?.totalMs,
                 wsOpenMs: baseConnectTrace?.wsOpenMs,
@@ -765,39 +1169,155 @@ async function startFreshProxySession(options) {
             };
             safeRecordSessionSnapshot(session, 'session.proxy_attached', {
                 transportMode: 'fresh-proxy',
-                proxyStartMode: 'child',
-                requestedPageUrl: options.pageUrl,
+                proxyStartMode: 'embedded',
+                requestedPageOrigin: lifecycleUrlOrigin(options.pageUrl),
                 isolated: options.isolated === true,
             });
             return session;
         }
-        catch (fallbackError) {
+        catch (embeddedFailure) {
+            // `runtime.ready` can reject before the parallel WebSocket connect
+            // settles. Close the runtime and await that losing connect before this
+            // lease is eligible for child fallback; one reservation can never back
+            // two simultaneous attempts.
+            if (attachedEmbeddedSession) {
+                shutdownSession(attachedEmbeddedSession.id, { closeProxy: true, reason: 'embedded_proxy_start_failed' });
+            }
+            if (pendingEmbeddedRuntime) {
+                await closeEmbeddedProxyRuntime(pendingEmbeddedRuntime);
+            }
+            if (pendingEmbeddedConnect) {
+                const orphanedSession = await pendingEmbeddedConnect.catch(() => undefined);
+                pendingEmbeddedConnect = undefined;
+                if (orphanedSession) {
+                    orphanedSession.proxyRuntime = pendingEmbeddedRuntime;
+                    orphanedSession.proxyReusable = false;
+                    shutdownSession(orphanedSession.id, { closeProxy: true, reason: 'embedded_proxy_ready_failed' });
+                }
+            }
+            ownershipLease = reserveSessionOwnership(ownershipLease);
+            let pendingChild;
+            let attachedChildSession;
             try {
-                child.kill('SIGTERM');
+                const proxyStartStartedAt = performance.now();
+                const { child, wsUrl, authToken } = await spawnGeometraProxy({
+                    pageUrl: options.pageUrl,
+                    port: options.port ?? 0,
+                    headless: options.headless,
+                    width: options.width,
+                    height: options.height,
+                    slowMo: options.slowMo,
+                    stealth: options.stealth,
+                    eagerInitialExtract,
+                    proxy: options.proxy,
+                });
+                pendingChild = child;
+                const proxyStartMs = performance.now() - proxyStartStartedAt;
+                const session = await connectWithOwnership(wsUrl, {
+                    skipInitialResize: true,
+                    closePreviousProxy: false,
+                    awaitInitialFrame: options.awaitInitialFrame,
+                    authToken,
+                    isolated: options.isolated === true,
+                    ownershipLease,
+                });
+                attachedChildSession = session;
+                session.proxyChild = child;
+                session.proxyReusable = !options.isolated;
+                if (!options.isolated) {
+                    setReusableProxy({ child, authToken }, wsUrl, {
+                        headless: options.headless,
+                        slowMo: options.slowMo,
+                        stealth: options.stealth,
+                        width: options.width,
+                        height: options.height,
+                        pageUrl: options.pageUrl,
+                        snapshotReady: Boolean(session.tree && session.layout),
+                        proxy: options.proxy,
+                    });
+                }
+                const baseConnectTrace = session.connectTrace;
+                session.connectTrace = {
+                    mode: 'fresh-proxy',
+                    reused: false,
+                    awaitInitialFrame: options.awaitInitialFrame !== false,
+                    proxyStartMode: 'child',
+                    proxyStartMs,
+                    connectMs: baseConnectTrace?.totalMs,
+                    wsOpenMs: baseConnectTrace?.wsOpenMs,
+                    firstFrameMs: baseConnectTrace?.firstFrameMs,
+                    resolvedWithoutInitialFrame: baseConnectTrace?.resolvedWithoutInitialFrame,
+                    totalMs: performance.now() - startedAt,
+                };
+                safeRecordSessionSnapshot(session, 'session.proxy_attached', {
+                    transportMode: 'fresh-proxy',
+                    proxyStartMode: 'child',
+                    requestedPageOrigin: lifecycleUrlOrigin(options.pageUrl),
+                    isolated: options.isolated === true,
+                });
+                return session;
             }
-            catch {
-                /* ignore */
+            catch (fallbackError) {
+                if (attachedChildSession) {
+                    shutdownSession(attachedChildSession.id, { closeProxy: true, reason: 'child_proxy_start_failed' });
+                }
+                else if (pendingChild) {
+                    try {
+                        pendingChild.kill('SIGTERM');
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                if (fallbackError instanceof SessionCapacityError)
+                    throw fallbackError;
+                throw new Error(`Failed to start embedded browser session: ${formatUnknownError(embeddedFailure)}\n` +
+                    `Child-process proxy fallback also failed: ${formatUnknownError(fallbackError)}`, { cause: fallbackError });
             }
-            throw fallbackError instanceof Error ? fallbackError : e;
         }
     }
+    finally {
+        releaseSessionOwnership(ownershipLease);
+    }
 }
 /**
  * Connect to a running Geometra server. Waits for the first frame so that
  * layout/tree state is available immediately after connection.
  */
 export function connect(url, opts) {
+    return connectWithOwnership(url, opts);
+}
+function connectWithOwnership(url, opts) {
     return new Promise((resolve, reject) => {
         const startedAt = performance.now();
         clearReusableProxiesIfExited();
-        evictOldestSession();
-        const ws = new WebSocket(url);
+        let ownershipLease;
+        try {
+            ownershipLease = beginSessionOwnershipAttempt(opts?.ownershipLease);
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        let ws;
+        try {
+            ws = new WebSocket(url, opts?.authToken
+                ? { headers: { Authorization: `Bearer ${opts.authToken}` } }
+                : undefined);
+        }
+        catch (err) {
+            releaseSessionOwnership(ownershipLease);
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
         const session = {
             id: generateSessionId(),
             ws,
             layout: null,
             tree: null,
             url,
+            ...(opts?.authToken ? { transportAuthToken: opts.authToken } : {}),
+            isolated: opts?.isolated === true,
             updateRevision: 0,
             connectTrace: {
                 mode: 'direct-ws',
@@ -808,6 +1328,8 @@ export function connect(url, opts) {
             cachedA11y: null,
             cachedA11yRevision: -1,
             cachedFormSchemas: new Map(),
+            hasFreshFrame: false,
+            disposed: false,
             heartbeatInterval: null,
             heartbeatLastMessageAt: Date.now(),
             heartbeatPendingPongBy: null,
@@ -822,6 +1344,7 @@ export function connect(url, opts) {
             catch {
                 /* ignore */
             }
+            releaseSessionOwnership(ownershipLease);
             reject(new Error(`Failed to initialize durable session state for ${url}: ${formatUnknownError(err)}`));
             return;
         }
@@ -832,7 +1355,7 @@ export function connect(url, opts) {
         const timeout = setTimeout(() => {
             if (!resolved) {
                 safeFailSessionLifecycle(session, 'connect_timeout', {
-                    transportUrl: url,
+                    transportOrigin: lifecycleUrlOrigin(url),
                     timeoutMs: 10_000,
                 });
                 resolved = true;
@@ -842,6 +1365,7 @@ export function connect(url, opts) {
                 catch {
                     /* ignore */
                 }
+                releaseSessionOwnership(ownershipLease);
                 reject(new Error(`Connection to ${url} timed out after 10s`));
             }
         }, 10_000);
@@ -854,22 +1378,24 @@ export function connect(url, opts) {
             if (!opts?.skipInitialResize) {
                 const width = opts?.width ?? 1024;
                 const height = opts?.height ?? 768;
-                ws.send(JSON.stringify({ type: 'resize', width, height }));
-            }
-            if (opts?.awaitInitialFrame === false && !resolved) {
-                resolved = true;
-                clearTimeout(timeout);
-                if (session.connectTrace) {
-                    session.connectTrace.resolvedWithoutInitialFrame = true;
-                    session.connectTrace.totalMs = performance.now() - startedAt;
+                // Start with the shared GEOM v1 envelope. The first frame explicitly
+                // advertises whether this is a native server or a proxy-action peer.
+                // Legacy proxy v1/v2 endpoints both accept this compatibility hello.
+                try {
+                    ws.send(JSON.stringify({ type: 'resize', width, height, protocolVersion: GEOMETRY_PROTOCOL_VERSION }));
+                }
+                catch (err) {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    clearTimeout(timeout);
+                    releaseSessionOwnership(ownershipLease);
+                    try {
+                        ws.close();
+                    }
+                    catch { /* ignore */ }
+                    reject(new Error(`Failed to initialize connection to ${url}: ${formatUnknownError(err)}`));
                 }
-                activeSessions.set(session.id, session);
-                defaultSessionId = session.id;
-                startSessionHeartbeat(session);
-                safeRecordSessionSnapshot(session, 'session.open', {
-                    awaitInitialFrame: false,
-                });
-                resolve(session);
             }
         });
         ws.on('message', (data) => {
@@ -877,25 +1403,42 @@ export function connect(url, opts) {
             if (session.ws !== ws)
                 return;
             try {
-                const msg = JSON.parse(String(data));
+                const msg = applyInboundSessionMessage(session, data);
+                if (msg.type === 'hello' || msg.type === 'frame') {
+                    assertAuthenticatedProxyHandshake(session);
+                }
+                if (msg.type === 'hello' && opts?.awaitInitialFrame === false && !resolved) {
+                    clearTimeout(timeout);
+                    if (session.connectTrace) {
+                        session.connectTrace.resolvedWithoutInitialFrame = true;
+                        session.connectTrace.totalMs = performance.now() - startedAt;
+                    }
+                    claimSessionOwnership(ownershipLease, session);
+                    resolved = true;
+                    if (!session.isolated)
+                        defaultSessionId = session.id;
+                    startSessionHeartbeat(session);
+                    safeRecordSessionSnapshot(session, 'session.open', {
+                        awaitInitialFrame: false,
+                        authenticatedProxyHandshake: true,
+                    });
+                    resolve(session);
+                }
                 if (msg.type === 'frame') {
-                    session.layout = msg.layout;
-                    session.tree = msg.tree;
-                    session.updateRevision++;
-                    invalidateSessionCaches(session);
                     const connectTrace = session.connectTrace;
                     const firstFrame = connectTrace?.firstFrameMs === undefined;
                     if (connectTrace && connectTrace.firstFrameMs === undefined) {
                         connectTrace.firstFrameMs = performance.now() - startedAt;
                     }
                     if (!resolved) {
-                        resolved = true;
                         clearTimeout(timeout);
                         if (session.connectTrace) {
                             session.connectTrace.totalMs = performance.now() - startedAt;
                         }
-                        activeSessions.set(session.id, session);
-                        defaultSessionId = session.id;
+                        claimSessionOwnership(ownershipLease, session);
+                        resolved = true;
+                        if (!session.isolated)
+                            defaultSessionId = session.id;
                         startSessionHeartbeat(session);
                         safeRecordSessionSnapshot(session, 'session.connected');
                         resolve(session);
@@ -906,34 +1449,62 @@ export function connect(url, opts) {
                         });
                     }
                 }
-                else if (msg.type === 'patch' && session.layout) {
-                    applyPatches(session.layout, msg.patches);
-                    session.updateRevision++;
-                    invalidateSessionCaches(session);
+                else if (msg.type === 'error' && !resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    try {
+                        ws.close();
+                    }
+                    catch { /* ignore */ }
+                    releaseSessionOwnership(ownershipLease);
+                    reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
+                }
+            }
+            catch (err) {
+                rememberReusableProxyPageUrl(session);
+                try {
+                    ws.close(1002, 'Invalid protocol message');
+                }
+                catch { /* ignore */ }
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    releaseSessionOwnership(ownershipLease);
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+                else {
+                    invalidateSessionUiState(session);
                 }
             }
-            catch { /* ignore malformed messages */ }
         });
         ws.on('error', (err) => {
+            if (session.ws === ws) {
+                rememberReusableProxyPageUrl(session);
+                invalidateSessionUiState(session);
+            }
             if (!resolved) {
                 safeFailSessionLifecycle(session, 'websocket_error', {
-                    transportUrl: url,
-                    message: err.message,
+                    transportOrigin: lifecycleUrlOrigin(url),
+                    errorCode: err.code ?? 'websocket_error',
                 });
                 resolved = true;
                 clearTimeout(timeout);
+                releaseSessionOwnership(ownershipLease);
                 reject(new Error(`WebSocket error connecting to ${url}: ${err.message}`));
             }
         });
         ws.on('close', () => {
             if (session.ws !== ws)
                 return;
+            rememberReusableProxyPageUrl(session);
+            invalidateSessionUiState(session);
             if (!resolved) {
                 safeFailSessionLifecycle(session, 'websocket_closed_before_ready', {
-                    transportUrl: url,
+                    transportOrigin: lifecycleUrlOrigin(url),
                 });
                 resolved = true;
                 clearTimeout(timeout);
+                releaseSessionOwnership(ownershipLease);
                 reject(new Error(`Connection to ${url} closed before first frame`));
                 return;
             }
@@ -951,20 +1522,22 @@ export function connect(url, opts) {
  */
 export async function connectThroughProxy(options) {
     clearReusableProxiesIfExited();
+    const isolated = options.isolated !== false;
+    const normalizedOptions = { ...options, isolated };
     // Isolated sessions skip the pool entirely. They always get their own
     // brand-new Chromium and never reuse a proxy from a prior call. The
     // tag flows down so startFreshProxySession knows to keep this proxy out
     // of the pool on success and so shutdownSession knows to force-close it.
-    if (options.isolated) {
-        return await startFreshProxySession({ ...options, isolated: true });
+    if (isolated) {
+        const ownershipLease = reserveSessionOwnership();
+        return await startFreshProxySession(normalizedOptions, ownershipLease);
     }
     let reuseFailure;
     // Loop because if a candidate is currently being attached by another
-    // concurrent connectThroughProxy call we wait for it, then re-pick. The
-    // second pick may now find the same entry already bound to an active
-    // session — attachToReusableProxy's reusedExistingSession branch then
-    // returns that session instead of opening a second WebSocket. Bounded
-    // by the pool size to defend against pathological churn.
+    // concurrent connectThroughProxy call we wait for it, then re-pick. Active
+    // entries are never eligible: the second caller either claims another idle
+    // warm browser or starts a fresh one. Bounded by the pool size to defend
+    // against pathological churn.
     for (let attempt = 0; attempt < REUSABLE_PROXY_POOL_LIMIT + 1; attempt++) {
         const reusableProxy = findReusableProxy(options);
         if (!reusableProxy)
@@ -979,10 +1552,16 @@ export async function connectThroughProxy(options) {
         let releaseLock = () => { };
         reusableProxy.attachLock = new Promise(resolve => { releaseLock = resolve; });
         try {
+            if (reusableProxyEntryIsActive(reusableProxy))
+                continue;
             return await attachToReusableProxy(reusableProxy, options);
         }
         catch (err) {
+            if (err instanceof SessionCapacityError)
+                throw err;
             reuseFailure = err;
+            if (reusableProxyEntryIsActive(reusableProxy))
+                continue;
             closeReusableProxy(reusableProxy);
             break;
         }
@@ -992,9 +1571,12 @@ export async function connectThroughProxy(options) {
         }
     }
     try {
-        return await startFreshProxySession(options);
+        const ownershipLease = reserveSessionOwnership();
+        return await startFreshProxySession(normalizedOptions, ownershipLease);
     }
     catch (e) {
+        if (e instanceof SessionCapacityError)
+            throw e;
         if (reuseFailure) {
             throw new Error(`Failed to recover reusable browser session after it became stale: ${formatUnknownError(reuseFailure)}\nFresh proxy start also failed: ${formatUnknownError(e)}`, { cause: e });
         }
@@ -1011,13 +1593,22 @@ export function getSession(id) {
 export function pruneDisconnectedSessions() {
     const removedIds = [];
     for (const [id, session] of activeSessions.entries()) {
-        if (session.ws.readyState === WebSocket.OPEN || session.reconnectInFlight || reconnectUrlForSession(session))
+        if (session.ws.readyState === WebSocket.OPEN)
+            continue;
+        rememberReusableProxyPageUrl(session);
+        invalidateSessionUiState(session);
+        if (session.reconnectInFlight || reconnectUrlForSession(session))
             continue;
         removedIds.push(id);
+        session.disposed = true;
+        session.ambiguousOperations?.clear();
+        session.inFlightMutations?.clear();
         activeSessions.delete(id);
         if (defaultSessionId === id) {
             promoteDefaultSession();
         }
+        stopSessionHeartbeat(session);
+        releaseSessionResources(session, { closeProxy: true });
     }
     return removedIds;
 }
@@ -1058,13 +1649,28 @@ export function getDefaultSessionId() {
 }
 export function disconnect(opts) {
     if (opts?.sessionId) {
-        shutdownSession(opts.sessionId, { closeProxy: opts?.closeProxy ?? false, reason: 'disconnect' });
+        if (!activeSessions.has(opts.sessionId))
+            return;
+        shutdownSession(opts.sessionId, { closeProxy: opts.closeProxy ?? false, reason: 'disconnect' });
+        return;
     }
-    else if (defaultSessionId) {
-        shutdownSession(defaultSessionId, { closeProxy: opts?.closeProxy ?? false, reason: 'disconnect' });
+    const resolved = resolveSession();
+    if (resolved.kind === 'none')
+        return;
+    if (resolved.kind === 'ambiguous') {
+        throw new Error(`Cannot disconnect without an explicit sessionId while session routing is ambiguous. ` +
+            `Active sessions: ${resolved.activeIds.join(', ')}.`);
     }
-    if (opts?.closeProxy)
-        closeReusableProxies();
+    if (resolved.kind === 'not_found')
+        return;
+    shutdownSession(resolved.session.id, { closeProxy: opts?.closeProxy ?? false, reason: 'disconnect' });
+}
+/** Process/test teardown only. User-facing disconnects are always owner-scoped. */
+export function shutdownAllSessionsAndProxies() {
+    for (const id of [...activeSessions.keys()]) {
+        shutdownSession(id, { closeProxy: true, reason: 'process_shutdown' });
+    }
+    closeReusableProxies();
 }
 function estimateFillBatchTimeout(fields) {
     let total = FILL_BATCH_BASE_TIMEOUT_MS;
@@ -1100,7 +1706,13 @@ function estimateFillBatchTimeout(fields) {
 }
 export function waitForUiCondition(session, predicate, timeoutMs) {
     return new Promise((resolve) => {
+        const transport = session.ws;
         const check = () => {
+            if (session.ws !== transport) {
+                cleanup();
+                resolve(false);
+                return;
+            }
             let matched;
             try {
                 matched = predicate();
@@ -1126,11 +1738,11 @@ export function waitForUiCondition(session, predicate, timeoutMs) {
         };
         function cleanup() {
             clearTimeout(timeout);
-            session.ws.off('message', onMessage);
-            session.ws.off('close', onClose);
+            transport.off('message', onMessage);
+            transport.off('close', onClose);
         }
-        session.ws.on('message', onMessage);
-        session.ws.on('close', onClose);
+        transport.on('message', onMessage);
+        transport.on('close', onClose);
         check();
     });
 }
@@ -1147,9 +1759,19 @@ function reconnectUrlForSession(session) {
     }
     return null;
 }
-async function openWebSocket(url, timeoutMs = SESSION_RECONNECT_TIMEOUT_MS) {
+async function openWebSocket(url, session, timeoutMs = SESSION_RECONNECT_TIMEOUT_MS, viewport) {
     return await new Promise((resolve, reject) => {
-        const ws = new WebSocket(url);
+        const ws = new WebSocket(url, session.transportAuthToken
+            ? { headers: { Authorization: `Bearer ${session.transportAuthToken}` } }
+            : undefined);
+        // Every transport replacement must negotiate from fresh evidence. Keeping
+        // the prior socket's capability flags would let a different process take
+        // over the endpoint and inherit an authenticated-proxy attestation.
+        session.peerTransport = undefined;
+        session.peerGeometryProtocolVersion = undefined;
+        session.peerProxyActionProtocolVersion = undefined;
+        session.peerAdvertisedSplitProtocol = undefined;
+        session.peerProtocolCapabilities = undefined;
         const timeout = setTimeout(() => {
             cleanup();
             try {
@@ -1158,23 +1780,61 @@ async function openWebSocket(url, timeoutMs = SESSION_RECONNECT_TIMEOUT_MS) {
             catch {
                 /* ignore */
             }
-            reject(new Error(`Reconnect to ${url} timed out after ${timeoutMs}ms`));
+            reject(new Error(`Reconnect handshake to ${url} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
         const onOpen = () => {
-            cleanup();
-            resolve(ws);
+            const width = viewport?.width ?? 1024;
+            const height = viewport?.height ?? 768;
+            // Current proxies attest immediately with `hello`. This compatibility
+            // resize prompts native/legacy peers that only emit a frame after input.
+            ws.send(JSON.stringify({
+                type: 'resize',
+                width,
+                height,
+                protocolVersion: GEOMETRY_PROTOCOL_VERSION,
+            }));
         };
         const onError = (err) => {
             cleanup();
             reject(new Error(`WebSocket reconnect failed for ${url}: ${err.message}`));
         };
+        const onClose = () => {
+            cleanup();
+            reject(new Error(`WebSocket reconnect to ${url} closed before capability handshake`));
+        };
+        const onMessage = (data) => {
+            try {
+                const msg = parseInboundServerMessage(data);
+                updatePeerProtocol(session, msg);
+                if (msg.type === 'error') {
+                    throw new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error');
+                }
+                if (msg.type !== 'hello' && msg.type !== 'frame')
+                    return;
+                assertAuthenticatedProxyHandshake(session);
+                cleanup();
+                resolve({ ws, handshakeMessage: data });
+            }
+            catch (err) {
+                cleanup();
+                try {
+                    ws.close(1002, 'Invalid capability handshake');
+                }
+                catch { /* ignore */ }
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        };
         function cleanup() {
             clearTimeout(timeout);
             ws.off('open', onOpen);
             ws.off('error', onError);
+            ws.off('close', onClose);
+            ws.off('message', onMessage);
         }
         ws.on('open', onOpen);
         ws.on('error', onError);
+        ws.on('close', onClose);
+        ws.on('message', onMessage);
     });
 }
 function bindReconnectedSocket(session, ws) {
@@ -1183,29 +1843,31 @@ function bindReconnectedSocket(session, ws) {
         if (session.ws !== ws)
             return;
         try {
-            const msg = JSON.parse(String(data));
-            if (msg.type === 'frame') {
-                session.layout = msg.layout;
-                session.tree = msg.tree;
-                session.updateRevision++;
-                invalidateSessionCaches(session);
-            }
-            else if (msg.type === 'patch' && session.layout) {
-                applyPatches(session.layout, msg.patches);
-                session.updateRevision++;
-                invalidateSessionCaches(session);
-            }
+            applyInboundSessionMessage(session, data);
         }
         catch {
-            /* ignore malformed messages */
+            rememberReusableProxyPageUrl(session);
+            invalidateSessionUiState(session);
+            try {
+                ws.close(1002, 'Invalid protocol message');
+            }
+            catch { /* ignore */ }
         }
     });
     ws.on('pong', () => {
         noteSessionSocketActivity(session, ws);
     });
+    ws.on('error', () => {
+        if (session.ws !== ws)
+            return;
+        rememberReusableProxyPageUrl(session);
+        invalidateSessionUiState(session);
+    });
     ws.on('close', () => {
         if (session.ws !== ws)
             return;
+        rememberReusableProxyPageUrl(session);
+        invalidateSessionUiState(session);
         if (activeSessions.get(session.id) === session && !session.lifecycleFinalized) {
             safeRecordSessionSnapshot(session, 'session.transport_closed', {
                 reconnectable: reconnectUrlForSession(session) !== null,
@@ -1213,7 +1875,13 @@ function bindReconnectedSocket(session, ws) {
         }
     });
 }
-async function ensureSessionConnected(session) {
+function sessionIsDisposedOrUnowned(session) {
+    return session.disposed === true || activeSessions.get(session.id) !== session;
+}
+export async function ensureSessionConnected(session) {
+    if (sessionIsDisposedOrUnowned(session)) {
+        throw new Error(`Session ${session.id} is disconnected or no longer owns its transport`);
+    }
     if (session.ws.readyState === WebSocket.OPEN)
         return;
     if (session.reconnectInFlight) {
@@ -1221,15 +1889,31 @@ async function ensureSessionConnected(session) {
         if (!recovered) {
             throw new Error('Not connected');
         }
+        if (sessionIsDisposedOrUnowned(session)) {
+            throw new Error(`Session ${session.id} was disconnected while reconnecting`);
+        }
         return;
     }
     const targetUrl = reconnectUrlForSession(session);
     if (!targetUrl) {
         throw new Error('Not connected');
     }
+    const reconnectViewport = {
+        width: typeof session.layout?.width === 'number' ? session.layout.width : 1024,
+        height: typeof session.layout?.height === 'number' ? session.layout.height : 768,
+    };
+    rememberReusableProxyPageUrl(session);
+    invalidateSessionUiState(session);
     const reconnectPromise = (async () => {
         try {
-            const nextWs = await openWebSocket(targetUrl);
+            const { ws: nextWs, handshakeMessage } = await openWebSocket(targetUrl, session, SESSION_RECONNECT_TIMEOUT_MS, reconnectViewport);
+            if (sessionIsDisposedOrUnowned(session)) {
+                try {
+                    nextWs.close();
+                }
+                catch { /* ignore */ }
+                throw new Error(`Session ${session.id} was disconnected while reconnecting`);
+            }
             try {
                 session.ws.close();
             }
@@ -1239,28 +1923,33 @@ async function ensureSessionConnected(session) {
             session.ws = nextWs;
             noteSessionSocketActivity(session, nextWs);
             bindReconnectedSocket(session, nextWs);
+            applyInboundSessionMessage(session, handshakeMessage);
             activeSessions.set(session.id, session);
             if (!session.isolated) {
                 defaultSessionId = session.id;
             }
             startSessionHeartbeat(session);
             safeRecordSessionSnapshot(session, 'session.reconnected', {
-                targetUrl,
+                targetOrigin: lifecycleUrlOrigin(targetUrl),
             });
             return true;
         }
         catch (err) {
             safeFailSessionLifecycle(session, 'reconnect_failed', {
-                targetUrl,
-                message: formatUnknownError(err),
+                targetOrigin: lifecycleUrlOrigin(targetUrl),
+                errorName: err instanceof Error ? err.name : 'Error',
             });
             if (activeSessions.get(session.id) === session) {
                 activeSessions.delete(session.id);
                 if (defaultSessionId === session.id)
                     promoteDefaultSession();
             }
+            session.disposed = true;
+            session.ambiguousOperations?.clear();
+            session.inFlightMutations?.clear();
             stopSessionHeartbeat(session);
             releaseSessionResources(session, { closeProxy: true });
+            invalidateSessionUiState(session);
             throw err;
         }
     })();
@@ -1275,12 +1964,16 @@ async function ensureSessionConnected(session) {
     if (!recovered) {
         throw new Error('Not connected');
     }
+    if (sessionIsDisposedOrUnowned(session)) {
+        throw new Error(`Session ${session.id} was disconnected while reconnecting`);
+    }
 }
 async function sendResizeAndWaitForUpdate(session, width, height, timeoutMs = 5_000) {
-    await ensureSessionConnected(session);
-    const startRevision = session.updateRevision;
-    session.ws.send(JSON.stringify({ type: 'resize', width, height }));
-    return await waitForNextUpdate(session, timeoutMs, undefined, startRevision);
+    return await sendAndWaitForUpdate(session, {
+        type: 'resize',
+        width,
+        height,
+    }, timeoutMs);
 }
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
@@ -1299,10 +1992,30 @@ export function sendClick(session, x, y, timeoutMs) {
 export function sendType(session, text, timeoutMs) {
     return (async () => {
         await ensureSessionConnected(session);
-        // Send each character as keydown + keyup
+        const waitTimeoutMs = timeoutMs ?? ACTION_UPDATE_TIMEOUT_MS;
+        if (session.peerTransport === 'proxy' && session.peerProtocolCapabilities?.atomicTypeText === true) {
+            if (text.length > 65_536) {
+                throw new Error('geometra_type text exceeds the proxy atomic typing limit of 65,536 characters');
+            }
+            return await sendAndWaitForUpdate(session, { type: 'typeText', text }, waitTimeoutMs);
+        }
+        const fingerprint = actionFingerprint({ type: 'typeSequence', text });
+        const existing = ambiguousOperationFor(session, fingerprint);
+        if (existing) {
+            return await sendPreparedActionOperation(session, existing, waitTimeoutMs, undefined, true);
+        }
+        assertCanStartMutatingOperation(session, fingerprint);
+        const actionId = randomUUID();
+        const actionTimeoutMs = actionTimeoutFor(session, { type: 'key' }, waitTimeoutMs);
+        const keyEvents = [];
+        // Give every key phase its own identity. Waiting on the final key-up is
+        // sufficient because the proxy processes its action queue in wire order;
+        // a scoped acknowledgement for that phase therefore confirms that every
+        // earlier phase in this type sequence has also finished.
         for (const char of text) {
             const keyEvent = {
                 type: 'key',
+                ...outboundProtocolMetadata(session),
                 eventType: 'onKeyDown',
                 key: char,
                 code: `Key${char.toUpperCase()}`,
@@ -1311,11 +2024,41 @@ export function sendType(session, text, timeoutMs) {
                 metaKey: false,
                 altKey: false,
             };
-            session.ws.send(JSON.stringify(keyEvent));
-            session.ws.send(JSON.stringify({ ...keyEvent, eventType: 'onKeyUp' }));
+            keyEvents.push({
+                ...keyEvent,
+                ...(actionTimeoutMs !== undefined ? { actionTimeoutMs } : {}),
+                requestId: randomUUID(),
+            });
+            keyEvents.push({
+                ...keyEvent,
+                eventType: 'onKeyUp',
+                ...(actionTimeoutMs !== undefined ? { actionTimeoutMs } : {}),
+                requestId: randomUUID(),
+            });
+        }
+        if (keyEvents.length === 0) {
+            return {
+                status: 'acknowledged',
+                timeoutMs: waitTimeoutMs,
+                requestId: randomUUID(),
+                actionId,
+            };
         }
-        // Wait briefly for server to process and send update
-        return await waitForNextUpdate(session, timeoutMs);
+        const finalRequestId = keyEvents[keyEvents.length - 1].requestId;
+        const operation = {
+            fingerprint,
+            actionId,
+            requestId: finalRequestId,
+            requestIds: keyEvents.map(keyEvent => keyEvent.requestId),
+            wireMessages: keyEvents.map(keyEvent => JSON.stringify(keyEvent)),
+            ...(actionTimeoutMs !== undefined ? { actionTimeoutMs } : {}),
+            timeoutMs: waitTimeoutMs,
+            idempotent: session.peerTransport === 'proxy' &&
+                session.peerProtocolCapabilities?.idempotentRequestIds === true,
+            mutating: true,
+        };
+        trackInFlightMutation(session, operation);
+        return await sendPreparedActionOperation(session, operation, waitTimeoutMs);
     })();
 }
 /**
@@ -1335,7 +2078,9 @@ export function sendKey(session, key, modifiers, timeoutMs) {
 }
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
- * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
+ * Optional `x`,`y` click opens a file chooser. Callers must provide an explicit
+ * coordinate or semantic target; MCP never intentionally requests a global
+ * first-file-input fallback.
  */
 export function sendFileUpload(session, paths, opts, timeoutMs) {
     const payload = { type: 'file', paths };
@@ -1345,6 +2090,10 @@ export function sendFileUpload(session, paths, opts, timeoutMs) {
     }
     if (opts?.fieldLabel)
         payload.fieldLabel = opts.fieldLabel;
+    if (opts?.fieldId)
+        payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     if (opts?.exact !== undefined)
         payload.exact = opts.exact;
     if (opts?.strategy)
@@ -1353,6 +2102,10 @@ export function sendFileUpload(session, paths, opts, timeoutMs) {
         payload.dropX = opts.drop.x;
         payload.dropY = opts.drop.y;
     }
+    if (opts?.contextText !== undefined)
+        payload.contextText = opts.contextText;
+    if (opts?.sectionText !== undefined)
+        payload.sectionText = opts.sectionText;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Set a labeled text-like field (`input`, `textarea`, contenteditable, ARIA textbox) semantically. */
@@ -1366,6 +2119,8 @@ export function sendFieldText(session, fieldLabel, value, opts, timeoutMs) {
         payload.exact = opts.exact;
     if (opts?.fieldId)
         payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     if (opts?.typingDelayMs !== undefined)
         payload.typingDelayMs = opts.typingDelayMs;
     if (opts?.imeFriendly !== undefined)
@@ -1387,6 +2142,10 @@ export function sendFieldChoice(session, fieldLabel, value, opts, timeoutMs = LI
         payload.choiceType = opts.choiceType;
     if (opts?.fieldId)
         payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
+    if (opts?.optionIndex !== undefined)
+        payload.optionIndex = opts.optionIndex;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Fill several semantic form fields in one proxy-side batch. */
@@ -1417,14 +2176,14 @@ export function sendListboxPick(session, label, opts, timeoutMs = LISTBOX_UPDATE
     const payload = { type: 'listboxPick', label };
     if (opts?.exact !== undefined)
         payload.exact = opts.exact;
-    if (opts?.open) {
-        payload.openX = opts.open.x;
-        payload.openY = opts.open.y;
-    }
     if (opts?.fieldLabel)
         payload.fieldLabel = opts.fieldLabel;
     if (opts?.query)
         payload.query = opts.query;
+    if (opts?.fieldId)
+        payload.fieldId = opts.fieldId;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
@@ -1445,6 +2204,12 @@ export function sendSetChecked(session, label, opts, timeoutMs) {
         payload.exact = opts.exact;
     if (opts?.controlType)
         payload.controlType = opts.controlType;
+    if (opts?.fieldKey)
+        payload.fieldKey = opts.fieldKey;
+    if (opts?.contextText)
+        payload.contextText = opts.contextText;
+    if (opts?.sectionText)
+        payload.sectionText = opts.sectionText;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
@@ -1480,9 +2245,8 @@ export function sendNavigate(session, url, timeoutMs = 15_000) {
             url,
         }, timeoutMs, { requireUpdateOnAck: true });
         safeRecordSessionSnapshot(session, 'session.navigate', {
-            requestedUrl: url,
+            requestedOrigin: lifecycleUrlOrigin(url),
             status: result.status,
-            result: result.result ?? null,
         });
         return result;
     })();
@@ -1537,6 +2301,11 @@ const FORM_FIELD_ROLES = new Set([
     'checkbox',
     'radio',
 ]);
+function isFormFieldNode(node) {
+    if (node.meta?.coordinateOnly === true)
+        return false;
+    return FORM_FIELD_ROLES.has(node.role) || node.meta?.fileInput === true;
+}
 const ACTION_ROLES = new Set([
     'button',
     'link',
@@ -2154,6 +2923,8 @@ function schemaOptionLabel(node) {
     return sanitizeFieldName(node.name, 80) ?? sanitizeInlineName(node.name, 80);
 }
 function isGroupedChoiceControl(node) {
+    if (node.meta?.coordinateOnly === true)
+        return false;
     return node.role === 'radio' || node.role === 'checkbox' || (node.role === 'button' && node.focusable);
 }
 function groupedChoiceForNode(root, formNode, seed) {
@@ -2219,10 +2990,36 @@ function buildFieldFormat(node) {
         format.pattern = m.inputPattern;
     if (m.inputType)
         format.inputType = m.inputType;
+    else if (m.fileInput)
+        format.inputType = 'file';
     if (m.autocomplete)
         format.autocomplete = m.autocomplete;
+    if (m.accept)
+        format.accept = m.accept;
+    if (m.multiple)
+        format.multiple = true;
     return Object.keys(format).length > 0 ? format : undefined;
 }
+function nativeSchemaOptions(node, fieldIdentity) {
+    const options = node.meta?.options;
+    if (!options)
+        return undefined;
+    return options.map(option => ({
+        id: `${fieldIdentity}:option:${option.index}`,
+        value: option.value,
+        label: option.label,
+        index: option.index,
+        ...(option.disabled ? { disabled: true } : {}),
+        ...(option.selected ? { selected: true } : {}),
+    }));
+}
+function uniqueSchemaFieldKey(root, node) {
+    const fieldKey = node.meta?.controlKey;
+    if (!fieldKey)
+        return undefined;
+    const matches = collectDescendants(root, candidate => candidate.meta?.controlKey === fieldKey);
+    return matches.length === 1 ? fieldKey : undefined;
+}
 function simpleSchemaField(root, node) {
     const context = nodeContextForNode(root, node);
     const label = fieldLabel(node) ?? sanitizeInlineName(node.name, 80) ?? context?.prompt;
@@ -2251,15 +3048,51 @@ function simpleSchemaField(root, node) {
                 ? 'select'
                 : 'listbox'
         : undefined;
+    const fieldKey = uniqueSchemaFieldKey(root, node);
+    const id = fieldKey ?? formFieldIdForPath(node.path);
     const format = buildFieldFormat(node);
+    const optionDetails = classifiedChoiceType === 'select' ? nativeSchemaOptions(node, id) : undefined;
+    const enabledOptions = optionDetails
+        ? dedupeStrings(optionDetails.filter(option => !option.disabled).map(option => option.label), 64)
+        : undefined;
     return {
-        id: formFieldIdForPath(node.path),
+        id,
+        ...(fieldKey ? { fieldKey } : {}),
         kind: classifiedRole === 'combobox' ? 'choice' : 'text',
         label,
         ...(classifiedChoiceType ? { choiceType: classifiedChoiceType } : {}),
         ...(node.state?.required ? { required: true } : {}),
         ...(node.state?.invalid ? { invalid: true } : {}),
         ...compactSchemaValue(node.value, 72),
+        ...(optionDetails ? { optionCount: optionDetails.length, optionDetails } : {}),
+        ...(enabledOptions && enabledOptions.length > 0 ? { options: enabledOptions } : {}),
+        ...(enabledOptions && computeOptionAliases(enabledOptions) ? { aliases: computeOptionAliases(enabledOptions) } : {}),
+        ...(format ? { format } : {}),
+        ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
+    };
+}
+function fileSchemaField(root, node) {
+    const context = nodeContextForNode(root, node);
+    // Hidden dropzone inputs are commonly missing an accessible name even when
+    // they retain an authored `name`/`id`. Keep them in the schema so required
+    // upload fields cannot disappear; the authored identity remains the exact
+    // action target and the generated fallback is display-only when no such
+    // identity exists.
+    const label = fieldLabel(node)
+        ?? sanitizeInlineName(node.name, 80)
+        ?? sanitizeInlineName(node.meta?.controlName, 80)
+        ?? sanitizeInlineName(node.meta?.controlId, 80)
+        ?? context?.prompt
+        ?? 'Unlabeled file upload';
+    const fieldKey = uniqueSchemaFieldKey(root, node);
+    const format = buildFieldFormat(node);
+    return {
+        id: fieldKey ?? formFieldIdForPath(node.path),
+        ...(fieldKey ? { fieldKey } : {}),
+        kind: 'file',
+        label,
+        ...(node.state?.required ? { required: true } : {}),
+        ...(node.state?.invalid ? { invalid: true } : {}),
         ...(format ? { format } : {}),
         ...(compactSchemaContext(context, label) ? { context: compactSchemaContext(context, label) } : {}),
     };
@@ -2304,8 +3137,10 @@ function toggleSchemaField(root, node) {
         return null;
     const context = nodeContextForNode(root, node);
     const controlType = node.role === 'radio' ? 'radio' : 'checkbox';
+    const fieldKey = uniqueSchemaFieldKey(root, node);
     return {
-        id: formFieldIdForPath(node.path),
+        id: fieldKey ?? formFieldIdForPath(node.path),
+        ...(fieldKey ? { fieldKey } : {}),
         kind: 'toggle',
         label,
         controlType,
@@ -2330,7 +3165,10 @@ function detectFormSections(formNode, fields) {
         return [];
     const fieldIdToPath = new Map();
     for (const field of fields) {
-        const parsed = parseFormFieldId(field.id);
+        const authoredMatches = field.fieldKey
+            ? collectDescendants(formNode, node => node.meta?.controlKey === field.fieldKey)
+            : [];
+        const parsed = authoredMatches.length === 1 ? authoredMatches[0].path : parseFormFieldId(field.id);
         if (parsed)
             fieldIdToPath.set(field.id, parsed);
     }
@@ -2351,17 +3189,25 @@ function detectFormSections(formNode, fields) {
     return sections;
 }
 function buildFormSchemaForNode(root, formNode, options) {
-    const candidates = sortByBounds(collectDescendants(formNode, candidate => candidate.role === 'textbox' ||
+    const candidates = sortByBounds(collectDescendants(formNode, candidate => candidate.meta?.coordinateOnly !== true && (candidate.role === 'textbox' ||
         candidate.role === 'combobox' ||
         candidate.role === 'checkbox' ||
         candidate.role === 'radio' ||
-        (candidate.role === 'button' && candidate.focusable)));
+        candidate.meta?.fileInput === true ||
+        (candidate.role === 'button' && candidate.focusable))));
     const consumed = new Set();
     const fields = [];
     for (const candidate of candidates) {
         const candidateKey = pathKey(candidate.path);
         if (consumed.has(candidateKey))
             continue;
+        if (candidate.meta?.fileInput === true) {
+            const field = fileSchemaField(root, candidate);
+            if (field)
+                fields.push(field);
+            consumed.add(candidateKey);
+            continue;
+        }
         if (candidate.role === 'textbox' || candidate.role === 'combobox') {
             const field = simpleSchemaField(root, candidate);
             if (field)
@@ -2428,6 +3274,7 @@ function presentFormSchemaFields(fields, options) {
             next.booleanChoice = true;
         if (!includeOptions) {
             delete next.options;
+            delete next.optionDetails;
             delete next.aliases;
         }
         if (includeContext === 'none') {
@@ -2655,7 +3502,7 @@ export function buildPageModel(root, options) {
             landmarks.push(toLandmarkModel(node));
         }
         if (node.role === 'form') {
-            const fields = collectDescendants(node, candidate => FORM_FIELD_ROLES.has(candidate.role));
+            const fields = collectDescendants(node, isFormFieldNode);
             const actions = collectDescendants(node, candidate => ACTION_ROLES.has(candidate.role) && candidate.focusable);
             const name = sectionDisplayName(node, 'form');
             forms.push({
@@ -2668,7 +3515,7 @@ export function buildPageModel(root, options) {
             });
         }
         if (DIALOG_ROLES.has(node.role)) {
-            const fields = collectDescendants(node, candidate => FORM_FIELD_ROLES.has(candidate.role));
+            const fields = collectDescendants(node, isFormFieldNode);
             const actions = collectDescendants(node, candidate => ACTION_ROLES.has(candidate.role) && candidate.focusable);
             const name = sectionDisplayName(node, 'dialog');
             dialogs.push({
@@ -2742,8 +3589,11 @@ export function buildFormSchemas(root, options) {
         ...(root.role === 'form' ? [root] : []),
         ...collectDescendants(root, candidate => candidate.role === 'form'),
     ];
-    // Infer forms from group/region containers with 2+ form fields (e.g. Ashby-style UIs without <form>)
-    const inferredForms = collectDescendants(root, candidate => {
+    // Infer forms from group/region containers with 2+ form fields (e.g.
+    // Ashby-style UIs without <form>). A standalone upload is also a complete
+    // form surface when it is required or has a unique authored identity;
+    // otherwise common one-field upload widgets disappear from the schema.
+    const inferredCandidates = collectDescendants(root, candidate => {
         if (candidate.role !== 'group' && candidate.role !== 'region')
             return false;
         // Skip descendants of explicit forms
@@ -2753,14 +3603,173 @@ export function buildFormSchemas(root, options) {
                 return false;
             }
         }
-        const fields = collectDescendants(candidate, child => FORM_FIELD_ROLES.has(child.role));
-        return fields.length >= 2;
+        const fields = collectDescendants(candidate, isFormFieldNode);
+        if (fields.length >= 2)
+            return true;
+        if (fields.length !== 1 || fields[0]?.meta?.fileInput !== true)
+            return false;
+        const file = fields[0];
+        return file.state?.required === true || uniqueSchemaFieldKey(root, file) !== undefined;
     });
+    // Nested layout groups often describe the same inferred form surface. Keep
+    // one stable container for an identical field set so callers do not receive
+    // duplicate formIds and then fail with an artificial ambiguous-form error.
+    // Explicit native forms are intentionally untouched.
+    const inferredByFieldSet = new Map();
+    for (const candidate of inferredCandidates) {
+        const fieldSet = collectDescendants(candidate, isFormFieldNode)
+            .map(field => pathKey(field.path))
+            .sort()
+            .join('|');
+        const current = inferredByFieldSet.get(fieldSet);
+        if (!current) {
+            inferredByFieldSet.set(fieldSet, candidate);
+            continue;
+        }
+        const currentNamed = Boolean(sanitizeContainerName(current.name, 80));
+        const candidateNamed = Boolean(sanitizeContainerName(candidate.name, 80));
+        const candidateIsPreferred = candidateNamed !== currentNamed
+            ? candidateNamed
+            : candidate.path.length > current.path.length || (candidate.path.length === current.path.length && pathKey(candidate.path) < pathKey(current.path));
+        if (candidateIsPreferred)
+            inferredByFieldSet.set(fieldSet, candidate);
+    }
+    const inferredForms = [...inferredByFieldSet.values()];
     const forms = sortByBounds([...explicitForms, ...inferredForms]);
     return forms
         .filter(form => !options?.formId || sectionIdForPath('form', form.path) === options.formId)
         .map(form => buildFormSchemaForNode(root, form, options));
 }
+export function buildFormGraphs(root, options) {
+    const pageUrl = typeof root.meta?.pageUrl === 'string' && root.meta.pageUrl.length > 0 ? root.meta.pageUrl : undefined;
+    return buildFormSchemas(root, {
+        ...options,
+        includeOptions: true,
+    }).map(schema => formSchemaToFormGraph(schema, pageUrl));
+}
+export function formSchemaToFormGraph(schema, pageUrl) {
+    const sourceId = 'geometra-page';
+    const formSlug = slugPathSegment(schema.name ?? schema.formId);
+    const pathCounts = new Map();
+    return {
+        formgraph: '0.1',
+        id: `geometra:${schema.formId}`,
+        title: schema.name ?? `Geometra form ${schema.formId}`,
+        description: 'FormGraph-compatible projection of a Geometra form schema.',
+        sources: [
+            {
+                id: sourceId,
+                kind: 'html',
+                title: schema.name ?? 'Geometra-discovered web form',
+                ...(pageUrl ? { url: pageUrl } : {}),
+            },
+        ],
+        fields: schema.fields.map(field => formSchemaFieldToFormGraphField(field, {
+            formSlug,
+            sourceId,
+            pathCounts,
+        })),
+        evidence: [],
+        dependencies: [],
+        review: {
+            autoSubmitAllowed: false,
+            requiredBeforeSubmit: true,
+        },
+        metadata: {
+            producer: 'geometra',
+            geometra: {
+                formId: schema.formId,
+                fieldCount: schema.fieldCount,
+                requiredCount: schema.requiredCount,
+                invalidCount: schema.invalidCount,
+                ...(schema.sections ? { sections: schema.sections } : {}),
+            },
+        },
+    };
+}
+function formSchemaFieldToFormGraphField(field, opts) {
+    const basePath = `web.forms.${opts.formSlug}.${slugPathSegment(field.label || field.id)}`;
+    const path = uniquePath(basePath, opts.pathCounts);
+    const aliases = fieldAliases(field);
+    const options = field.optionDetails
+        ?.filter(option => !option.disabled)
+        .map(option => ({ value: option.value, label: option.label }))
+        ?? field.options?.map(option => ({ value: option, label: option }));
+    const inputType = field.format?.inputType?.toLowerCase();
+    const metadata = {
+        geometra: {
+            fieldId: field.id,
+            ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+            kind: field.kind,
+            ...(field.choiceType ? { choiceType: field.choiceType } : {}),
+            ...(field.controlType ? { controlType: field.controlType } : {}),
+            ...(field.booleanChoice ? { booleanChoice: true } : {}),
+            ...(field.invalid ? { invalid: true } : {}),
+            ...(field.format ? { format: field.format } : {}),
+            ...(field.context ? { context: field.context } : {}),
+            ...(field.optionDetails ? { optionDetails: field.optionDetails } : {}),
+        },
+    };
+    return {
+        id: field.fieldKey ?? field.id,
+        path,
+        label: field.label,
+        kind: formGraphFieldKind(field),
+        ...(field.required ? { required: true } : {}),
+        ...(field.invalid ? { reviewRequired: true } : {}),
+        ...(aliases.length > 0 ? { aliases } : {}),
+        ...(options && options.length > 0 ? { options } : {}),
+        ...(field.format?.pattern ? { constraints: { pattern: field.format.pattern } } : {}),
+        sourceAnchors: [
+            {
+                sourceId: opts.sourceId,
+                kind: 'html',
+                fieldName: field.fieldKey ?? field.id,
+                pointer: `geometra:${field.fieldKey ?? field.id}`,
+            },
+        ],
+        ...(inputType ? { metadata: { ...metadata, inputType } } : { metadata }),
+    };
+}
+function formGraphFieldKind(field) {
+    if (field.kind === 'toggle' || field.booleanChoice)
+        return 'boolean';
+    if (field.kind === 'choice' || field.kind === 'multi_choice')
+        return 'enum';
+    const inputType = field.format?.inputType?.toLowerCase();
+    if (inputType === 'email')
+        return 'email';
+    if (inputType === 'tel' || inputType === 'phone')
+        return 'phone';
+    if (inputType === 'date')
+        return 'date';
+    if (inputType === 'number')
+        return 'number';
+    if (field.valueLength !== undefined && field.valueLength > 120)
+        return 'textarea';
+    return 'text';
+}
+function fieldAliases(field) {
+    const values = new Set();
+    if (field.format?.placeholder)
+        values.add(field.format.placeholder);
+    if (field.context?.prompt && normalizeUiText(field.context.prompt) !== normalizeUiText(field.label)) {
+        values.add(field.context.prompt);
+    }
+    return [...values].filter(value => value.trim().length > 0);
+}
+function uniquePath(basePath, seen) {
+    const count = seen.get(basePath) ?? 0;
+    seen.set(basePath, count + 1);
+    return count === 0 ? basePath : `${basePath}.${count + 1}`;
+}
+function slugPathSegment(value) {
+    const normalized = normalizeUiText(value)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return normalized || 'field';
+}
 /**
  * Required-field snapshot for automation: every required field in a form, including
  * offscreen entries, annotated with visibility and scroll hints so agents do not
@@ -2779,7 +3788,10 @@ export function buildFormRequiredSnapshot(root, options) {
         const formNode = parsedForm ? findNodeByPath(root, parsedForm.path) : null;
         const fields = schema.fields
             .map(field => {
-            const fieldPath = parseFormFieldId(field.id);
+            const authoredMatches = field.fieldKey && formNode
+                ? collectDescendants(formNode, node => node.meta?.controlKey === field.fieldKey)
+                : [];
+            const fieldPath = authoredMatches.length === 1 ? authoredMatches[0].path : parseFormFieldId(field.id);
             const target = fieldPath ? findNodeByPath(root, fieldPath) ?? formNode : formNode;
             if (!target)
                 return null;
@@ -2846,7 +3858,7 @@ export function expandPageSection(root, id, options) {
     const maxTextPreview = options?.maxTextPreview ?? 6;
     const includeBounds = options?.includeBounds ?? false;
     const headingsAll = sortByBounds(collectDescendants(node, candidate => candidate.role === 'heading' && !!sanitizeInlineName(candidate.name, 80)));
-    const fieldsAll = sortByBounds(collectDescendants(node, candidate => FORM_FIELD_ROLES.has(candidate.role)));
+    const fieldsAll = sortByBounds(collectDescendants(node, isFormFieldNode));
     const actionsAll = sortByBounds(collectDescendants(node, candidate => ACTION_ROLES.has(candidate.role) && candidate.focusable));
     const nestedListsAll = sortByBounds(collectDescendants(node, candidate => candidate.role === 'list' && pathKey(candidate.path) !== pathKey(node.path)));
     const itemsAll = actualKind === 'list'
@@ -3183,6 +4195,32 @@ function normalizeCheckedState(value) {
         return false;
     return undefined;
 }
+function normalizeSemanticOptions(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const options = [];
+    const seenIndices = new Set();
+    for (const entry of value.slice(0, 500)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        if (typeof record.value !== 'string' || typeof record.label !== 'string')
+            continue;
+        if (typeof record.index !== 'number' || !Number.isInteger(record.index) || record.index < 0)
+            continue;
+        if (seenIndices.has(record.index))
+            continue;
+        seenIndices.add(record.index);
+        options.push({
+            value: record.value,
+            label: record.label,
+            disabled: record.disabled === true,
+            selected: record.selected === true,
+            index: record.index,
+        });
+    }
+    return options;
+}
 function normalizeA11yRoleHint(value) {
     if (typeof value !== 'string')
         return undefined;
@@ -3239,6 +4277,15 @@ function walkNode(element, layout, path) {
         meta.scrollY = semantic.scrollY;
     if (typeof semantic?.tag === 'string' && semantic.tag.trim().length > 0)
         meta.controlTag = semantic.tag;
+    if (typeof semantic?.controlKey === 'string' && semantic.controlKey.trim().length > 0)
+        meta.controlKey = semantic.controlKey.trim();
+    if (typeof semantic?.controlId === 'string' && semantic.controlId.trim().length > 0)
+        meta.controlId = semantic.controlId.trim();
+    if (typeof semantic?.controlName === 'string' && semantic.controlName.trim().length > 0)
+        meta.controlName = semantic.controlName.trim();
+    const semanticOptions = normalizeSemanticOptions(semantic?.options);
+    if (semanticOptions)
+        meta.options = semanticOptions;
     if (typeof semantic?.placeholder === 'string')
         meta.placeholder = semantic.placeholder;
     if (typeof semantic?.inputPattern === 'string')
@@ -3247,6 +4294,14 @@ function walkNode(element, layout, path) {
         meta.inputType = semantic.inputType;
     if (typeof semantic?.autocomplete === 'string')
         meta.autocomplete = semantic.autocomplete;
+    if (semantic?.fileInput === true)
+        meta.fileInput = true;
+    if (typeof semantic?.accept === 'string' && semantic.accept.trim().length > 0)
+        meta.accept = semantic.accept.trim();
+    if (semantic?.multiple === true)
+        meta.multiple = true;
+    if (semantic?.coordinateOnly === true)
+        meta.coordinateOnly = true;
     if (semantic?.isAutocompleteCombobox === true)
         meta.isAutocompleteCombobox = true;
     const children = [];
@@ -3350,24 +4405,186 @@ function applyPatches(layout, patches) {
 }
 async function sendAndWaitForUpdate(session, message, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, opts) {
     await ensureSessionConnected(session);
-    const requestId = `req-${++nextRequestSequence}`;
+    const includesFileMutation = message.type === 'file' || (message.type === 'fillFields' &&
+        Array.isArray(message.fields) &&
+        message.fields.some(field => typeof field === 'object' && field !== null && field.kind === 'file'));
+    if (includesFileMutation && session.peerProtocolCapabilities?.verifiedFileUploads !== true) {
+        throw new Error('file_upload_capability_required: This peer does not advertise verified file uploads. Update @geometra/proxy to v1.65.0 or newer and reconnect. No file mutation was sent.');
+    }
+    const fingerprint = actionFingerprint(message);
+    const existing = ambiguousOperationFor(session, fingerprint);
+    if (existing) {
+        return await sendPreparedActionOperation(session, existing, timeoutMs, opts, true);
+    }
+    if (isMutatingProxyAction(message))
+        assertCanStartMutatingOperation(session, fingerprint);
+    const requiresExactFieldIdentity = typeof message.fieldKey === 'string' || (message.type === 'fillFields' &&
+        Array.isArray(message.fields) &&
+        message.fields.some(field => typeof field === 'object' && field !== null && typeof field.fieldKey === 'string'));
+    if (requiresExactFieldIdentity && session.peerProxyActionProtocolVersion !== undefined && (session.peerProxyActionProtocolVersion < PROXY_ACTION_PROTOCOL_VERSION ||
+        session.peerProtocolCapabilities?.exactFieldIdentity === false)) {
+        throw new Error(`Proxy protocol ${session.peerProxyActionProtocolVersion} cannot guarantee exact field identity; protocol ${PROXY_ACTION_PROTOCOL_VERSION}+ is required. Update and reconnect the Geometra proxy.`);
+    }
+    const actionId = randomUUID();
+    const requestId = randomUUID();
+    const actionTimeoutMs = actionTimeoutFor(session, message, timeoutMs);
+    const wireMessage = {
+        ...message,
+        ...(actionTimeoutMs !== undefined ? { actionTimeoutMs } : {}),
+        requestId,
+        ...outboundProtocolMetadata(session),
+    };
+    const operation = {
+        fingerprint,
+        actionId,
+        requestId,
+        requestIds: [requestId],
+        wireMessages: [JSON.stringify(wireMessage)],
+        ...(actionTimeoutMs !== undefined ? { actionTimeoutMs } : {}),
+        timeoutMs,
+        idempotent: session.peerTransport === 'proxy' &&
+            session.peerProtocolCapabilities?.idempotentRequestIds === true,
+        mutating: isMutatingProxyAction(message),
+        ...(opts?.requireUpdateOnAck ? { requireUpdateOnAck: true } : {}),
+        ...(requiresExactFieldIdentity ? { requiredProtocolVersion: PROXY_ACTION_PROTOCOL_VERSION } :
+            opts?.requiredProtocolVersion !== undefined ? { requiredProtocolVersion: opts.requiredProtocolVersion } : {}),
+    };
+    trackInFlightMutation(session, operation);
+    return await sendPreparedActionOperation(session, operation, timeoutMs, {
+        ...opts,
+        ...(requiresExactFieldIdentity ? { requiredProtocolVersion: PROXY_ACTION_PROTOCOL_VERSION } : {}),
+    });
+}
+async function sendPreparedActionOperation(session, operation, timeoutMs, opts, retry = false) {
+    if (operation.stickyError)
+        throw operation.stickyError;
+    if (operation.completion) {
+        if (operation.completion.kind === 'error') {
+            // Completion errors are restricted to proven non-execution. Deliver
+            // that correlated evidence once, then allow a genuinely fresh intent.
+            forgetAmbiguousOperation(session, operation);
+            throw operation.completion.error;
+        }
+        if (!operation.permanentTombstone)
+            forgetAmbiguousOperation(session, operation);
+        return operation.completion.value;
+    }
+    if (operation.permanentTombstone) {
+        // At least one indistinguishable caller already observed an unconfirmed
+        // outcome. Never replay this fingerprint within the same session.
+        return {
+            status: 'timed_out',
+            timeoutMs: operation.timeoutMs,
+            requestId: operation.requestId,
+            actionId: operation.actionId,
+        };
+    }
+    if (retry && (!operation.idempotent ||
+        session.peerTransport !== 'proxy' ||
+        session.peerProtocolCapabilities?.idempotentRequestIds !== true)) {
+        // An older/native peer cannot guarantee that replaying an identical wire
+        // message is safe. The second indistinguishable caller therefore makes
+        // this identity a permanent session tombstone even before the first
+        // caller settles.
+        operation.permanentTombstone = true;
+        rememberAmbiguousOperation(session, operation);
+        return {
+            status: 'timed_out',
+            timeoutMs: operation.timeoutMs,
+            requestId: operation.requestId,
+            actionId: operation.actionId,
+        };
+    }
     const startRevision = session.updateRevision;
-    session.ws.send(JSON.stringify({ ...message, requestId }));
-    return await waitForNextUpdate(session, timeoutMs, requestId, startRevision, opts);
+    try {
+        const result = await waitForNextUpdate(session, timeoutMs, operation, startRevision, {
+            ...(operation.requireUpdateOnAck ? { requireUpdateOnAck: true } : {}),
+            ...(operation.requiredProtocolVersion !== undefined
+                ? { requiredProtocolVersion: operation.requiredProtocolVersion }
+                : {}),
+        }, operation.idempotent, (transport) => {
+            for (const wireMessage of operation.wireMessages)
+                transport.send(wireMessage);
+        });
+        if (result.status === 'timed_out') {
+            operation.permanentTombstone = true;
+            rememberAmbiguousOperation(session, operation);
+            return result;
+        }
+        retainTerminalResult(session, operation, result);
+        if (!operation.permanentTombstone)
+            forgetAmbiguousOperation(session, operation);
+        return result;
+    }
+    catch (err) {
+        const safelyDidNotExecute = err instanceof GeometraWireError &&
+            err.code !== undefined &&
+            SAFE_NON_EXECUTION_WIRE_CODES.has(err.code) &&
+            operation.requestIds.length === 1;
+        if (safelyDidNotExecute) {
+            const terminalError = err instanceof Error ? err : new Error(String(err));
+            retainTerminalError(operation, terminalError);
+            // This caller received correlated proof that the mutation never began.
+            // That delivery consumes the tombstone, even if another waiter had
+            // previously timed out.
+            forgetAmbiguousOperation(session, operation);
+            throw terminalError;
+        }
+        if (operation.mutating) {
+            // A transport/handler/extraction error can arrive after a browser-side
+            // mutation. Preserve the exact identity so a later call cannot create
+            // a fresh mutation merely because the first response was an error.
+            rememberAmbiguousOperation(session, operation);
+            const ambiguousError = stickyAmbiguousError(operation, err);
+            operation.wireMessages = [];
+            operation.stickyError = ambiguousError;
+            throw ambiguousError;
+        }
+        else {
+            forgetAmbiguousOperation(session, operation);
+        }
+        throw err;
+    }
 }
-function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, requestId, startRevision = session.updateRevision, opts) {
+function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, operation, startRevision = session.updateRevision, opts, ignoreDuplicateRequestError = false, sendAfterSubscribe) {
     return new Promise((resolve, reject) => {
+        const transport = session.ws;
+        const { requestId, actionId } = operation;
+        const operationRequestIds = new Set(operation.requestIds);
         let ackSeen = false;
         let ackResult;
-        const ackPayload = () => (ackSeen && ackResult !== undefined ? { result: ackResult } : {});
+        const ackPayload = () => ({
+            requestId,
+            actionId,
+            ...(ackSeen && ackResult !== undefined ? { result: ackResult } : {}),
+        });
         const onMessage = (data) => {
+            if (session.ws !== transport)
+                return;
             try {
-                const msg = JSON.parse(String(data));
+                const msg = parseInboundServerMessage(data);
+                updatePeerProtocol(session, msg);
                 const messageRequestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
                 if (requestId) {
-                    if (msg.type === 'error' && (messageRequestId === requestId || messageRequestId === undefined)) {
+                    const requiresScopedAck = session.peerProtocolCapabilities?.requestScopedAcks === true;
+                    if (ignoreDuplicateRequestError &&
+                        msg.type === 'error' &&
+                        messageRequestId !== undefined &&
+                        operationRequestIds.has(messageRequestId) &&
+                        msg.code === 'DUPLICATE_REQUEST') {
+                        // The proxy has guaranteed that this replay did not mutate. Keep
+                        // waiting for the original action's late correlated terminal ACK.
+                        return;
+                    }
+                    if (operation.stickyError) {
                         cleanup();
-                        reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
+                        reject(operation.stickyError);
+                        return;
+                    }
+                    if (msg.type === 'error' && ((messageRequestId !== undefined && operationRequestIds.has(messageRequestId)) ||
+                        (!requiresScopedAck && messageRequestId === undefined))) {
+                        cleanup();
+                        reject(wireErrorFromMessage(msg, actionId));
                         return;
                     }
                     if ((msg.type === 'frame' || (msg.type === 'patch' && session.layout)) && ackSeen && session.updateRevision > startRevision) {
@@ -3380,6 +4597,20 @@ function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, reques
                         return;
                     }
                     if (msg.type === 'ack' && messageRequestId === requestId) {
+                        const peerProtocolVersion = typeof msg.proxyActionProtocolVersion === 'number'
+                            ? msg.proxyActionProtocolVersion
+                            : typeof msg.protocolVersion === 'number'
+                                ? msg.protocolVersion
+                                : session.peerProxyActionProtocolVersion;
+                        if (opts?.requiredProtocolVersion !== undefined && (peerProtocolVersion === undefined || peerProtocolVersion < opts.requiredProtocolVersion)) {
+                            cleanup();
+                            const protocolError = stickyAmbiguousError(operation, new Error(`Proxy protocol ${peerProtocolVersion ?? 'unknown'} cannot guarantee exact field identity; protocol ${opts.requiredProtocolVersion}+ is required. Update and reconnect the Geometra proxy.`));
+                            operation.stickyError = protocolError;
+                            if (operation.mutating)
+                                rememberAmbiguousOperation(session, operation);
+                            reject(protocolError);
+                            return;
+                        }
                         ackSeen = true;
                         ackResult = msg.result;
                         if (!opts?.requireUpdateOnAck || session.updateRevision > startRevision) {
@@ -3395,45 +4626,95 @@ function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, reques
                 }
                 if (msg.type === 'error') {
                     cleanup();
-                    reject(new Error(typeof msg.message === 'string' ? msg.message : 'Geometra server error'));
+                    reject(wireErrorFromMessage(msg, actionId));
                     return;
                 }
                 if (msg.type === 'frame') {
                     cleanup();
-                    resolve({ status: 'updated', timeoutMs });
+                    resolve({ status: 'updated', timeoutMs, ...ackPayload() });
                 }
                 else if (msg.type === 'patch' && session.layout) {
                     cleanup();
-                    resolve({ status: 'updated', timeoutMs });
+                    resolve({ status: 'updated', timeoutMs, ...ackPayload() });
                 }
                 else if (msg.type === 'ack') {
                     cleanup();
                     resolve({
                         status: 'acknowledged',
                         timeoutMs,
+                        requestId,
+                        actionId,
                         ...(msg.result !== undefined ? { result: msg.result } : {}),
                     });
                 }
             }
-            catch { /* ignore */ }
+            catch (err) {
+                cleanup();
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
         };
         // Expose timeout explicitly so action handlers can tell the user the result is ambiguous.
         const timeout = setTimeout(() => {
             cleanup();
-            if (requestId && session.updateRevision > startRevision) {
+            if (session.ws !== transport) {
+                if (operation.mutating)
+                    rememberAmbiguousOperation(session, operation);
+                resolve({ status: 'timed_out', timeoutMs, requestId, actionId });
+                return;
+            }
+            const requiresScopedAck = session.peerProtocolCapabilities?.requestScopedAcks === true;
+            if (requestId && !requiresScopedAck && session.updateRevision > startRevision) {
                 resolve({ status: 'updated', timeoutMs, ...ackPayload() });
                 return;
             }
-            if (requestId && ackSeen) {
+            if (requestId && ackSeen && (!opts?.requireUpdateOnAck || session.updateRevision > startRevision)) {
                 resolve({ status: 'acknowledged', timeoutMs, ...ackPayload() });
                 return;
             }
-            resolve({ status: 'timed_out', timeoutMs });
+            if (operation.mutating)
+                rememberAmbiguousOperation(session, operation);
+            resolve({ status: 'timed_out', timeoutMs, requestId, actionId });
         }, timeoutMs);
+        const onClose = () => {
+            cleanup();
+            if (operation.mutating)
+                rememberAmbiguousOperation(session, operation);
+            reject(new GeometraWireError('Action transport closed before a correlated terminal response arrived', 'TRANSPORT_CLOSED', requestId, actionId));
+        };
+        const onError = (error) => {
+            cleanup();
+            if (operation.mutating)
+                rememberAmbiguousOperation(session, operation);
+            reject(new GeometraWireError(`Action transport failed before a correlated terminal response arrived: ${error.message}`, 'TRANSPORT_ERROR', requestId, actionId));
+        };
         function cleanup() {
             clearTimeout(timeout);
-            session.ws.off('message', onMessage);
+            transport.off('message', onMessage);
+            transport.off('close', onClose);
+            transport.off('error', onError);
+        }
+        transport.on('message', onMessage);
+        transport.on('close', onClose);
+        transport.on('error', onError);
+        if (operation.completion) {
+            cleanup();
+            if (operation.completion.kind === 'error')
+                reject(operation.completion.error);
+            else
+                resolve(operation.completion.value);
+            return;
+        }
+        if (sendAfterSubscribe) {
+            try {
+                if (session.ws !== transport || transport.readyState !== WebSocket.OPEN) {
+                    throw new Error('Action transport changed before the request could be sent');
+                }
+                sendAfterSubscribe(transport);
+            }
+            catch (err) {
+                cleanup();
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
         }
-        session.ws.on('message', onMessage);
     });
 }