@geometra/mcp 1.64.0 → 1.65.1

package/dist/server.js

@@ -3,7 +3,9 @@ import { performance } from 'node:perf_hooks';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
-import { connect, connectThroughProxy, disconnect, pruneDisconnectedSessions, resolveSession, listSessions, getDefaultSessionId, prewarmProxy, sendClick, sendFillFields, sendFillOtp, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, formSchemaToFormGraph, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, parseSectionId, findNodeByPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { REDACTED_STATE_URL, sanitizeUrlToOrigin } from './state-privacy.js';
+import { SERVER_IMPLEMENTATION } from './version.js';
+import { connect, connectThroughProxy, ensureSessionConnected, disconnect, pruneDisconnectedSessions, resolveSession, listSessions, getDefaultSessionId, prewarmProxy, sendClick, sendFillFields, sendFillOtp, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, formSchemaToFormGraph, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, parseSectionId, findNodeByPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -188,7 +190,7 @@ const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic fil
     '(common for “Parsing…”, “Parsing your resume”, or similar). Passing only present/timeoutMs is not enough without a filter.';
 /** Strict input so unknown keys (e.g. textGone) fail parse; empty-filter checks happen in handlers / waitForSemanticCondition. */
 const sessionIdSchemaField = {
-    sessionId: z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.'),
+    sessionId: z.string().optional().describe('Session identifier returned by geometra_connect or an auto-connected tool. Omit only when exactly one non-isolated session is active.'),
 };
 const geometraQueryInputSchema = z.object({
     ...nodeFilterShape(),
@@ -285,6 +287,79 @@ function capBatchActionTimeouts(action, capMs) {
 const nonEmptyFieldIdSchema = z.string().trim().min(1, 'fieldId must not be empty');
 const nonEmptyFieldLabelSchema = z.string().trim().min(1, 'fieldLabel must not be empty');
 const nonEmptyToggleLabelSchema = z.string().trim().min(1, 'toggle label must not be empty');
+function incompleteCoordinatePairError(input, first, second) {
+    const hasFirst = input[first] !== undefined;
+    const hasSecond = input[second] !== undefined;
+    return hasFirst === hasSecond
+        ? undefined
+        : `${first} and ${second} must be provided together`;
+}
+function fileUploadContractError(input) {
+    const clickPairError = incompleteCoordinatePairError(input, 'x', 'y');
+    if (clickPairError)
+        return clickPairError;
+    const dropPairError = incompleteCoordinatePairError(input, 'dropX', 'dropY');
+    if (dropPairError)
+        return dropPairError;
+    const hasClick = input.x !== undefined && input.y !== undefined;
+    const hasDrop = input.dropX !== undefined && input.dropY !== undefined;
+    const hasFieldLabel = typeof input.fieldLabel === 'string' && input.fieldLabel.trim().length > 0;
+    const hasSemanticConstraint = hasFieldLabel || input.contextText !== undefined || input.sectionText !== undefined || input.exact !== undefined;
+    const strategy = input.strategy ?? 'auto';
+    if ((input.contextText !== undefined || input.sectionText !== undefined || input.exact !== undefined) && !hasFieldLabel) {
+        return 'contextText, sectionText, and exact require fieldLabel';
+    }
+    if (strategy === 'chooser') {
+        if (!hasClick)
+            return 'chooser strategy requires x and y';
+        if (hasDrop || hasSemanticConstraint)
+            return 'chooser strategy accepts only an x,y target; semantic and drop targets cannot be combined';
+        return undefined;
+    }
+    if (strategy === 'drop') {
+        if (!hasDrop)
+            return 'drop strategy requires dropX and dropY';
+        if (hasClick || hasSemanticConstraint)
+            return 'drop strategy accepts only a dropX,dropY target; chooser and semantic targets cannot be combined';
+        return undefined;
+    }
+    if (strategy === 'hidden') {
+        if (!hasFieldLabel)
+            return 'hidden strategy requires fieldLabel to prevent a global first-input fallback';
+        if (hasClick || hasDrop)
+            return 'hidden strategy does not accept chooser or drop coordinates';
+        return undefined;
+    }
+    if (hasDrop)
+        return 'dropX and dropY require strategy="drop"';
+    if (hasClick && hasFieldLabel)
+        return 'auto strategy requires exactly one target: either x,y or fieldLabel';
+    if (!hasClick && !hasFieldLabel)
+        return 'upload_files requires an explicit target: fieldLabel, x and y, or strategy="drop" with dropX and dropY';
+    return undefined;
+}
+function listboxPickContractError(input) {
+    if (typeof input.fieldLabel !== 'string' || input.fieldLabel.trim().length === 0) {
+        return 'pick_listbox_option requires fieldLabel so the committed field can be confirmed';
+    }
+    return undefined;
+}
+function selectOptionContractError(input) {
+    const coordinateError = incompleteCoordinatePairError(input, 'x', 'y');
+    if (coordinateError)
+        return coordinateError;
+    if (input.x === undefined || input.y === undefined)
+        return 'select_option requires x and y';
+    const selectorCount = Number(input.value !== undefined) + Number(input.label !== undefined) + Number(input.index !== undefined);
+    if (selectorCount === 0)
+        return 'select_option requires at least one of value, label, or index';
+    return undefined;
+}
+function addActionContractIssue(ctx, message) {
+    if (!message)
+        return;
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+}
 const fillFieldSchema = z.union([
     z.object({
         kind: z.literal('text'),
@@ -417,7 +492,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }).strict(),
     z.object({
         type: z.literal('type'),
-        text: z.string(),
+        text: z.string().max(65_536),
         timeoutMs: timeoutMsInput,
     }).strict(),
     z.object({
@@ -431,25 +506,25 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }).strict(),
     z.object({
         type: z.literal('upload_files'),
-        paths: z.array(z.string()).min(1),
+        paths: z.array(z.string().trim().min(1)).min(1),
         x: z.number().optional(),
         y: z.number().optional(),
-        fieldLabel: z.string().optional(),
+        fieldLabel: z.string().trim().min(1).optional(),
         exact: z.boolean().optional(),
         strategy: z.enum(['auto', 'chooser', 'hidden', 'drop']).optional(),
         dropX: z.number().optional(),
         dropY: z.number().optional(),
+        contextText: z.string().trim().min(1).optional(),
+        sectionText: z.string().trim().min(1).optional(),
         timeoutMs: timeoutMsInput,
     }).strict(),
     z.object({
         type: z.literal('pick_listbox_option'),
-        label: z.string(),
+        label: z.string().trim().min(1),
         exact: z.boolean().optional(),
-        openX: z.number().optional(),
-        openY: z.number().optional(),
         fieldId: z.string().trim().min(1).optional(),
         fieldKey: z.string().trim().min(1).optional(),
-        fieldLabel: z.string().optional(),
+        fieldLabel: z.string().trim().min(1),
         query: z.string().optional(),
         timeoutMs: timeoutMsInput,
     }).strict(),
@@ -458,7 +533,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
         x: z.number(),
         y: z.number(),
         value: z.string().optional(),
-        label: z.string().optional(),
+        label: z.string().trim().min(1).optional(),
         index: z.number().int().min(0).optional(),
         timeoutMs: timeoutMsInput,
     }).strict(),
@@ -512,10 +587,20 @@ const batchActionSchema = z.discriminatedUnion('type', [
         maxTextPreview: z.number().int().min(0).max(20).optional(),
         includeBounds: z.boolean().optional(),
     }).strict(),
-]);
+]).superRefine((action, ctx) => {
+    if (action.type === 'upload_files') {
+        addActionContractIssue(ctx, fileUploadContractError(action));
+    }
+    else if (action.type === 'pick_listbox_option') {
+        addActionContractIssue(ctx, listboxPickContractError(action));
+    }
+    else if (action.type === 'select_option') {
+        addActionContractIssue(ctx, selectOptionContractError(action));
+    }
+});
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.26' }, { capabilities: { tools: {} } });
-    const sessionIdInput = z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.');
+    const server = new McpServer(SERVER_IMPLEMENTATION, { capabilities: { tools: {} } });
+    const sessionIdInput = z.string().optional().describe('Session identifier returned by geometra_connect or an auto-connected tool. Omit only when exactly one non-isolated session is active.');
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -525,11 +610,16 @@ Use \`url\` (ws://…) only when a Geometra/native server or an already-running
 
 Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth: true\` (or set \`GEOMETRA_STEALTH=1\`) to opt into CloakBrowser's Chromium for authorized testing instead of stock Playwright Chromium. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.
 
-**Parallelism:** by default, geometra MCP pools and reuses Chromium instances across sessions for speed. That pooling is safe for read-only exploration, but it shares localStorage / cookies / page state across whichever sessions land on the same proxy — which means **two parallel form-submission flows can contaminate each other** (one job's email/autocomplete state leaks into another, or worse, two agents end up driving the same browser tab). For parallel apply / form submission, pass \`isolated: true\`. Each isolated session gets its own brand-new Chromium that is destroyed on disconnect, never enters the pool, and is guaranteed independent of every other session. The cost is ~1–2s of extra startup vs the ~50ms reusable-proxy attach.`, {
+**Session isolation:** browser sessions started from \`pageUrl\` (or an HTTP(S) \`url\`) are isolated by default: each gets a fresh Chromium that is destroyed on disconnect. Pass \`isolated: false\` explicitly only when you intentionally want sequential warm-browser reuse, including shared cookies, localStorage, and page state. Direct \`ws://\` connections attach to an externally managed endpoint and cannot create browser isolation.`, {
         url: z
             .string()
             .optional()
             .describe('WebSocket URL when a server is already running (e.g. ws://127.0.0.1:3200 or ws://localhost:3100). If you pass http(s) here by mistake, MCP will treat it as a page URL and start geometra-proxy.'),
+        authToken: z
+            .string()
+            .min(32)
+            .optional()
+            .describe('Bearer capability for an already-running authenticated geometra-proxy. Kept private and never returned in session metadata. Not needed when pageUrl starts the proxy automatically.'),
         pageUrl: z
             .string()
             .url()
@@ -560,8 +650,7 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
         isolated: z
             .boolean()
             .optional()
-            .default(false)
-            .describe('When true, bypass the reusable proxy pool and spawn a brand-new Chromium for this session that is destroyed on disconnect. Required for safe parallel form submission — without this, two parallel sessions can land on the same pooled proxy and contaminate each other. Default false (use the pool for speed).'),
+            .describe('For pageUrl/HTTP(S) browser connects, omission uses a fresh Chromium that is destroyed on disconnect. Pass false explicitly to opt into sequential warm-browser reuse and shared browser state. Direct ws:// endpoints are externally managed.'),
         proxy: z
             .object({
             server: z
@@ -610,6 +699,9 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
         if (!browser.ok)
             return err(browser.error);
         const target = normalized.value;
+        if (target.kind === 'ws' && input.isolated === true) {
+            return err('isolated:true is unsupported for direct ws:// endpoints because MCP does not own that browser/runtime. Use pageUrl/HTTP(S) url for an isolated browser, or omit isolated for the externally managed endpoint.');
+        }
         const formSchema = {
             formId: input.formId,
             maxFields: input.maxFields,
@@ -639,7 +731,7 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
                     height: input.height,
                     slowMo: input.slowMo,
                     ...(browser.stealth !== undefined && { stealth: browser.stealth }),
-                    isolated: input.isolated,
+                    isolated: input.isolated !== false,
                     proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
                     eagerInitialExtract: deferInlinePageModel ? true : undefined,
@@ -671,6 +763,7 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
                 width: input.width,
                 height: input.height,
                 awaitInitialFrame: deferInlinePageModel ? false : undefined,
+                authToken: input.authToken,
             });
             if (input.returnForms) {
                 await stabilizeInlineFormSchemas(session, formSchema);
@@ -702,7 +795,7 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
     // ── prepare browser ──────────────────────────────────────────
     server.tool('geometra_prepare_browser', `Pre-launch and pre-navigate a reusable geometra-proxy browser for a normal web page without creating an active MCP session.
 
-Use this when you can prepare ahead of the user-facing task so the next \`geometra_connect\` or one-call \`geometra_run_actions\` on the same \`pageUrl\` / viewport / headless settings skips the cold browser launch.`, {
+Use this when you can prepare ahead of the user-facing task so the next \`geometra_connect\` or one-call \`geometra_run_actions\` on the same \`pageUrl\` / viewport / headless settings skips the cold browser launch. The consuming call must pass \`isolated: false\` explicitly; isolated browser connects intentionally ignore the warm pool.`, {
         pageUrl: z
             .string()
             .url()
@@ -1005,7 +1098,7 @@ Captures the current URL, then polls until the URL changes and a stable UI tree
     });
     server.tool('geometra_fill_fields', `Fill several labeled form fields in one MCP call. This is the preferred high-level primitive for long forms.
 
-Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / comboboxes / radio-style questions addressed by field label + answer, \`"toggle"\` for individually labeled checkboxes or radios, and \`"file"\` for labeled uploads. When \`fieldId\` from \`geometra_form_schema\` is present, MCP can resolve the current label server-side so you do not need to duplicate \`fieldLabel\` / \`label\` for text, choice, and toggle fields.`, {
+Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / comboboxes / radio-style questions addressed by field label + answer, \`"toggle"\` for individually labeled checkboxes or radios, and \`"file"\` for labeled uploads. When \`fieldId\` from \`geometra_form_schema\` is present, MCP can resolve the current label server-side so you do not need to duplicate \`fieldLabel\` / \`label\` for text, choice, toggle, or file fields.`, {
         fields: z.array(fillFieldSchema).min(1).max(80).describe('Ordered field operations to apply. Use fieldId from geometra_form_schema to omit duplicate fieldLabel/label on schema-backed fields.'),
         stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing field (default true)'),
         failOnInvalid: z
@@ -1053,12 +1146,21 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
                 fallbackFromBatch = { attempted: true, used: true, reason: 'batched-unavailable', attempts: 2 };
             }
             catch (e) {
+                const ambiguity = ambiguousOutcomeDetails(e);
+                if (ambiguity) {
+                    return err(JSON.stringify({
+                        completed: false,
+                        execution: 'batched',
+                        ...ambiguousOutcomePayload(ambiguity),
+                    }, null, detail === 'verbose' ? 2 : undefined));
+                }
                 const message = e instanceof Error ? e.message : String(e);
                 return err(message);
             }
         }
         const steps = [];
         let stoppedAt;
+        let ambiguousAt;
         for (let index = 0; index < resolvedFields.fields.length; index++) {
             const field = resolvedFields.fields[index];
             try {
@@ -1074,9 +1176,10 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
                     : { index, kind: field.kind, ok: true, ...result.compact });
             }
             catch (e) {
-                const message = e instanceof Error ? e.message : String(e);
+                let handledError = e;
+                let message = e instanceof Error ? e.message : String(e);
                 // Retry once for transient selection failures
-                if (message.includes('selection_not_confirmed') || message.includes('still invalid after fill')) {
+                if (!ambiguousOutcomeDetails(e) && (message.includes('selection_not_confirmed') || message.includes('still invalid after fill'))) {
                     try {
                         const retryResult = await executeFillField(session, field, detail);
                         steps.push(detail === 'verbose'
@@ -1084,12 +1187,25 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
                             : { index, kind: field.kind, ok: true, ...retryResult.compact, retried: true });
                         continue;
                     }
-                    catch { /* fall through to error handling */ }
+                    catch (retryError) {
+                        handledError = retryError;
+                        message = retryError instanceof Error ? retryError.message : String(retryError);
+                    }
                 }
+                const ambiguity = ambiguousOutcomeDetails(handledError);
                 const suggestion = isResolvedFillFieldInput(field) ? suggestRecovery(field, message) : undefined;
-                steps.push({ index, kind: field.kind, ok: false, error: message, ...(suggestion ? { suggestion } : {}) });
-                if (stopOnError) {
+                steps.push({
+                    index,
+                    kind: field.kind,
+                    ok: false,
+                    error: message,
+                    ...(ambiguity ? ambiguousOutcomePayload(ambiguity) : {}),
+                    ...(suggestion ? { suggestion } : {}),
+                });
+                if (ambiguity || stopOnError) {
                     stoppedAt = index;
+                    if (ambiguity)
+                        ambiguousAt = index;
                     break;
                 }
             }
@@ -1106,6 +1222,13 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
             errorCount,
             ...(includeSteps ? { steps } : {}),
             ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(ambiguousAt !== undefined ? {
+                ambiguous: true,
+                ambiguousAt,
+                resumeBlocked: true,
+                resumeFromIndex: ambiguousAt,
+                resumeInstruction: 'Inspect the current UI before resuming; do not skip the ambiguous field.',
+            } : {}),
             ...(fallbackFromBatch ? { fallback: fallbackFromBatch } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
@@ -1159,8 +1282,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         isolated: z
             .boolean()
             .optional()
-            .default(false)
-            .describe('When auto-connecting via pageUrl/url, request an isolated proxy (own brand-new Chromium, destroyed on disconnect). Required for safe parallel form submission. See geometra_connect for details. Ignored when reusing an existing sessionId — set isolated on the original geometra_connect for that case.'),
+            .describe('When auto-connecting via pageUrl/HTTP(S) url, use a fresh isolated Chromium by default. Pass false explicitly for sequential warm reuse. Ignored when using an existing sessionId.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
     }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
@@ -1239,10 +1361,43 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         let fallbackFromBatch;
         if (!includeSteps) {
             let usedBatch = false;
+            let batchReadbackSnapshot;
             try {
                 const startRevision = session.updateRevision;
                 const wait = await sendFillFields(session, toProxyFillFields(planned.fields));
+                assertActionWaitConfirmed('Batched form fill', wait);
                 const ackResult = parseProxyFillAckResult(wait.result);
+                const batchIncludesFile = planned.fields.some(field => field.kind === 'file');
+                if (batchIncludesFile) {
+                    // Legacy proxies do not return a structured fillFields result.
+                    // Because a file chooser may already have mutated, replaying the
+                    // batch or falling back sequentially would be unsafe. Current
+                    // proxies only emit this result after attachFiles confirms the
+                    // exact input retained the requested files.
+                    if (!ackResult) {
+                        throw new AmbiguousActionOutcomeError('Batched file fill', wait, 'Batched file fill was acknowledged without structured proxy confirmation; the upload may already have happened. Do not retry blindly.');
+                    }
+                    await waitForDeferredBatchUpdate(session, startRevision, wait);
+                    const verification = verifyFills ? verifyFormFills(session, planned.planned) : undefined;
+                    const payload = {
+                        ...connection,
+                        completed: true,
+                        execution: 'batched',
+                        finalSource: 'proxy',
+                        formId: schema.formId,
+                        requestedValueCount: entryCount,
+                        fieldCount: planned.fields.length,
+                        successCount: planned.fields.length,
+                        errorCount: 0,
+                        ...(verification ? { verification } : {}),
+                        final: ackResult,
+                    };
+                    recordWorkflowFill(session, schema.formId, schema.name, valuesById, valuesByLabel, ackResult.invalidCount, planned.fields.length);
+                    if (failOnInvalid && ackResult.invalidCount > 0) {
+                        return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                    }
+                    return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                }
                 if (ackResult && ackResult.invalidCount === 0) {
                     usedBatch = true;
                     if (!verifyFills) {
@@ -1262,10 +1417,29 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                     }
                 }
                 await waitForDeferredBatchUpdate(session, startRevision, wait);
-                await waitForBatchFieldReadback(session, planned.fields);
-                usedBatch = true;
+                batchReadbackSnapshot = await waitForBatchFieldReadback(session, planned.fields);
+                if (!batchReadbackSnapshot) {
+                    if (!sessionA11y(session)) {
+                        throw new AmbiguousActionOutcomeError('Batched form fill', wait, 'Batched form fill was sent, but its read-back evidence became unavailable before confirmation. The fields may already have changed. Do not retry blindly.');
+                    }
+                    usedBatch = false;
+                    fallbackFromBatch = { attempted: true, used: true, reason: 'batched-invalid-readback', attempts: 2 };
+                }
+                else {
+                    usedBatch = true;
+                }
             }
             catch (e) {
+                const ambiguity = ambiguousOutcomeDetails(e);
+                if (ambiguity) {
+                    return err(JSON.stringify({
+                        ...connection,
+                        completed: false,
+                        execution: 'batched',
+                        formId: schema.formId,
+                        ...ambiguousOutcomePayload(ambiguity),
+                    }, null, detail === 'verbose' ? 2 : undefined));
+                }
                 if (!canFallbackToSequentialFill(e)) {
                     const message = e instanceof Error ? e.message : String(e);
                     return err(message);
@@ -1273,7 +1447,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                 fallbackFromBatch = { attempted: true, used: true, reason: 'batched-threw', attempts: 2 };
             }
             if (usedBatch) {
-                const after = sessionA11y(session);
+                const after = batchReadbackSnapshot;
                 const signals = after
                     ? scopeSessionSignalsToForm(after, targetFormPath ? formNodeAtPath(after, targetFormPath) : undefined, targetFormPath !== undefined)
                     : undefined;
@@ -1284,12 +1458,14 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                 }
             }
             if (usedBatch) {
-                const after = sessionA11y(session);
+                const after = batchReadbackSnapshot;
                 const signals = after
                     ? scopeSessionSignalsToForm(after, targetFormPath ? formNodeAtPath(after, targetFormPath) : undefined, targetFormPath !== undefined)
                     : undefined;
                 const invalidRemaining = signals?.invalidFields.length ?? 0;
-                const verification = verifyFills ? verifyFormFills(session, planned.planned) : undefined;
+                const verification = verifyFills
+                    ? verifyFormFills(session, planned.planned, batchReadbackSnapshot)
+                    : undefined;
                 const payload = {
                     ...connection,
                     completed: true,
@@ -1315,6 +1491,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         }
         const steps = [];
         let stoppedAt;
+        let ambiguousAt;
         const startIndex = resumeFromIndex ?? 0;
         for (let index = startIndex; index < planned.fields.length; index++) {
             const field = planned.fields[index];
@@ -1329,10 +1506,21 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
+                const ambiguity = ambiguousOutcomeDetails(e);
                 const suggestion = suggestRecovery(field, message);
-                steps.push({ index, kind: field.kind, ok: false, ...(confidence !== undefined ? { confidence, matchMethod } : {}), error: message, ...(suggestion ? { suggestion } : {}) });
-                if (stopOnError) {
+                steps.push({
+                    index,
+                    kind: field.kind,
+                    ok: false,
+                    ...(confidence !== undefined ? { confidence, matchMethod } : {}),
+                    error: message,
+                    ...(ambiguity ? ambiguousOutcomePayload(ambiguity) : {}),
+                    ...(suggestion ? { suggestion } : {}),
+                });
+                if (ambiguity || stopOnError) {
                     stoppedAt = index;
+                    if (ambiguity)
+                        ambiguousAt = index;
                     break;
                 }
             }
@@ -1360,7 +1548,16 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                 : undefined,
             ...(startIndex > 0 ? { resumedFromIndex: startIndex } : {}),
             ...(includeSteps ? { steps } : {}),
-            ...(stoppedAt !== undefined ? { stoppedAt, resumeFromIndex: stoppedAt + 1 } : {}),
+            ...(stoppedAt !== undefined ? {
+                stoppedAt,
+                resumeFromIndex: ambiguousAt ?? (stoppedAt + 1),
+            } : {}),
+            ...(ambiguousAt !== undefined ? {
+                ambiguous: true,
+                ambiguousAt,
+                resumeBlocked: true,
+                resumeInstruction: 'Inspect the current UI before resuming; do not skip the ambiguous field.',
+            } : {}),
             ...(fallbackFromBatch ? { fallback: fallbackFromBatch } : {}),
             ...(verification ? { verification } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
@@ -1392,7 +1589,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
 
 Pass \`valuesById\` or \`valuesByLabel\` to populate fields, \`submit\` to target the submit button (default: semantic \`{ role: 'button', name: 'Submit' }\`), and \`waitFor\` to block on the post-submit state (success banner, navigation, submit button gone, etc.). Navigation is detected automatically and surfaced as \`navigated: true\` with \`afterUrl\`.
 
-Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: true\` for safe parallel submissions.`, {
+Pass \`pageUrl\`/\`url\` to auto-connect in the same call. These browser connects are isolated by default; pass \`isolated: false\` only for intentional sequential warm reuse.`, {
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before submitting.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before submitting. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
@@ -1402,7 +1599,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         stealth: stealthInput(),
         browserMode: browserModeInput(),
-        isolated: z.boolean().optional().default(false).describe('When auto-connecting via pageUrl/url, request an isolated proxy. Required for safe parallel form submission.'),
+        isolated: z.boolean().optional().describe('When auto-connecting via pageUrl/HTTP(S) url, use a fresh isolated Chromium by default. Pass false explicitly for sequential warm reuse.'),
         formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
         valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
         valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
@@ -1428,22 +1625,30 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         const session = resolved.session;
         const connection = autoConnectionPayload(resolved);
         let targetFormId = formId;
+        let targetFormIdentity;
         let fillSummary;
         let fillFallback;
-        const pausedPayload = (phase, resumeHint, extra) => ({
-            ...connection,
-            completed: false,
-            outcome: 'unconfirmed',
-            paused: true,
-            phase,
-            pauseReason: 'soft-timeout',
-            softTimeoutMs: effectiveSoftTimeoutMs,
-            elapsedMs: Number((performance.now() - toolStartedAt).toFixed(1)),
-            ...(resumeHint ? { resumeHint } : {}),
-            ...(fillSummary ? { fill: fillSummary } : {}),
-            ...(fillFallback ? { fill_fallback: fillFallback } : {}),
-            ...(extra ?? {}),
-        });
+        const pausedPayload = (phase, resumeHint, extra) => {
+            const resumesSubmitForm = resumeHint?.tool === 'geometra_submit_form';
+            const scopedResumeHint = {
+                ...(resumeHint ?? {}),
+                ...(resumesSubmitForm && targetFormId ? { formId: targetFormId } : {}),
+            };
+            return {
+                ...connection,
+                completed: false,
+                outcome: 'unconfirmed',
+                paused: true,
+                phase,
+                pauseReason: 'soft-timeout',
+                softTimeoutMs: effectiveSoftTimeoutMs,
+                elapsedMs: Number((performance.now() - toolStartedAt).toFixed(1)),
+                ...(Object.keys(scopedResumeHint).length > 0 ? { resumeHint: scopedResumeHint } : {}),
+                ...(fillSummary ? { fill: fillSummary } : {}),
+                ...(fillFallback ? { fill_fallback: fillFallback } : {}),
+                ...(extra ?? {}),
+            };
+        };
         if (!session.tree || !session.layout) {
             await waitForUiCondition(session, () => Boolean(session.tree && session.layout), capTimeoutMs(2_000, timeoutCapFromDeadline(deadlineAt), 2_000));
         }
@@ -1466,6 +1671,17 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                 return err(resolution.error);
             const schema = resolution.schema;
             targetFormId = schema.formId;
+            const initialFormPath = parseSectionId(schema.formId);
+            const initialFormNode = initialFormPath?.kind === 'form'
+                ? formScopeNodeAtPath(entryA11y, initialFormPath.path)
+                : undefined;
+            if (!initialFormNode) {
+                return err(`Target form ${schema.formId} does not resolve to a maintainable form scope before fill`);
+            }
+            const capturedIdentity = captureFormScopeIdentity(initialFormNode, schema);
+            if (!capturedIdentity.ok)
+                return err(capturedIdentity.error);
+            targetFormIdentity = capturedIdentity.identity;
             const planned = planFormFill(schema, { valuesById, valuesByLabel }, schemas);
             if (!planned.ok)
                 return err(planned.error);
@@ -1473,6 +1689,28 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             try {
                 const startRevision = session.updateRevision;
                 const wait = await sendFillFields(session, toProxyFillFields(planned.fields), capTimeoutMs(undefined, timeoutCapFromDeadline(deadlineAt), HOST_SAFE_TOOL_TIMEOUT_MS));
+                if (wait.status === 'timed_out') {
+                    fillSummary = {
+                        formId: schema.formId,
+                        execution: 'batched',
+                        fieldCount: planned.fields.length,
+                        ...waitStatusPayload(wait),
+                        ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
+                    };
+                    const guidance = ambiguousActionGuidance(wait);
+                    return ok(JSON.stringify(pausedPayload('fill', {
+                        tool: 'geometra_submit_form',
+                        retrySameCall: false,
+                        inspectCurrentUiFirst: true,
+                        skipFill: false,
+                        actionId: wait.actionId,
+                        requestId: wait.requestId,
+                    }, {
+                        pauseReason: 'action-outcome-ambiguous',
+                        retrySafety: 'inspect-first',
+                        guidance,
+                    }), null, detail === 'verbose' ? 2 : undefined));
+                }
                 const ack = parseProxyFillAckResult(wait.result);
                 await waitForDeferredBatchUpdate(session, startRevision, wait);
                 fillSummary = {
@@ -1484,15 +1722,20 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                     ...(ack?.invalidFields ? { invalidFields: ack.invalidFields } : {}),
                     ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
                 };
-                if (wait.status === 'timed_out') {
-                    return ok(JSON.stringify(pausedPayload('fill', {
-                        tool: 'geometra_submit_form',
-                        retrySameCall: true,
-                        skipFill: false,
-                    }), null, detail === 'verbose' ? 2 : undefined));
-                }
             }
             catch (e) {
+                const ambiguity = ambiguousOutcomeDetails(e);
+                if (ambiguity) {
+                    return err(JSON.stringify({
+                        ...connection,
+                        completed: false,
+                        paused: true,
+                        phase: 'fill',
+                        pauseReason: 'action-outcome-ambiguous',
+                        ...ambiguousOutcomePayload(ambiguity),
+                        submit: { attempted: false, reason: 'Fill outcome must be inspected before submission.' },
+                    }, null, detail === 'verbose' ? 2 : undefined));
+                }
                 if (!canFallbackToSequentialFill(e)) {
                     const message = e instanceof Error ? e.message : String(e);
                     return err(`Failed to fill form before submit: ${message}`);
@@ -1503,6 +1746,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             if (!usedBatch) {
                 let successCount = 0;
                 let firstErr;
+                let firstAmbiguity;
                 for (const field of planned.fields) {
                     if (!hasSoftBudget(deadlineAt)) {
                         fillSummary = {
@@ -1524,6 +1768,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                     }
                     catch (e) {
                         firstErr = e instanceof Error ? e.message : String(e);
+                        firstAmbiguity = ambiguousOutcomeDetails(e);
                         break;
                     }
                 }
@@ -1536,6 +1781,18 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                     ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
                 };
                 if (firstErr !== undefined) {
+                    if (firstAmbiguity) {
+                        return err(JSON.stringify({
+                            ...connection,
+                            completed: false,
+                            paused: true,
+                            phase: 'fill',
+                            pauseReason: 'action-outcome-ambiguous',
+                            fill: fillSummary,
+                            ...ambiguousOutcomePayload(firstAmbiguity),
+                            submit: { attempted: false, reason: 'Fill outcome must be inspected before submission.' },
+                        }, null, detail === 'verbose' ? 2 : undefined));
+                    }
                     return err(JSON.stringify({
                         ...connection,
                         completed: false,
@@ -1560,29 +1817,85 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             return ok(JSON.stringify(pausedPayload('submit', submitResumeHint), null, detail === 'verbose' ? 2 : undefined));
         }
         const submitFilter = submit ?? { role: 'button', name: 'Submit' };
+        const submitTargetFailurePayload = (error, fallback) => ({
+            ...connection,
+            completed: false,
+            outcome: 'unconfirmed',
+            ...(fillSummary ? { fill: fillSummary } : {}),
+            ...(fillFallback ? { fill_fallback: fillFallback } : {}),
+            submit: { ok: false, error: `Submit target not found: ${error}` },
+            ...(fallback ? { submit_fallback: fallback } : {}),
+        });
+        let submitFormNode;
+        let submitFormPath;
+        let formScope;
+        if (targetFormId) {
+            const currentA11y = sessionA11y(session);
+            const parsedForm = parseSectionId(targetFormId);
+            const currentSchema = currentA11y
+                ? getSessionFormSchemas(session, { includeOptions: false, includeContext: 'auto' })
+                    .find(schema => schema.formId === targetFormId)
+                : undefined;
+            const currentForm = currentA11y && parsedForm?.kind === 'form'
+                ? formScopeNodeAtPath(currentA11y, parsedForm.path)
+                : undefined;
+            if (!currentA11y || parsedForm?.kind !== 'form' || !currentSchema || !currentForm) {
+                return err(JSON.stringify(submitTargetFailurePayload(`Target form ${targetFormId} has an invalid or stale form path`), null, detail === 'verbose' ? 2 : undefined));
+            }
+            if (!targetFormIdentity) {
+                const capturedIdentity = captureFormScopeIdentity(currentForm, currentSchema);
+                if (!capturedIdentity.ok) {
+                    return err(JSON.stringify(submitTargetFailurePayload(capturedIdentity.error), null, detail === 'verbose' ? 2 : undefined));
+                }
+                targetFormIdentity = capturedIdentity.identity;
+            }
+            submitFormPath = [...parsedForm.path];
+            formScope = { formId: targetFormId, path: submitFormPath, identity: targetFormIdentity };
+            const scoped = currentFormScope(session, currentA11y, formScope);
+            if (!scoped.ok) {
+                return err(JSON.stringify(submitTargetFailurePayload(scoped.error), null, detail === 'verbose' ? 2 : undefined));
+            }
+            submitFormNode = scoped.node;
+        }
         const resolvedClick = await resolveClickLocationWithFallback(session, {
             filter: submitFilter,
             index: submitIndex,
             fullyVisible: true,
+            formScope,
             revealTimeoutMs: capTimeoutMs(2_500, timeoutCapFromDeadline(deadlineAt), 2_500),
         });
         if (!resolvedClick.ok) {
-            const payload = {
-                ...connection,
-                completed: false,
-                outcome: 'unconfirmed',
-                ...(fillSummary ? { fill: fillSummary } : {}),
-                ...(fillFallback ? { fill_fallback: fillFallback } : {}),
-                submit: { ok: false, error: `Submit target not found: ${resolvedClick.error}` },
-                ...(resolvedClick.fallback ? { submit_fallback: resolvedClick.fallback } : {}),
-            };
+            const payload = submitTargetFailurePayload(resolvedClick.error, resolvedClick.fallback);
             return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
         }
         const preSubmitA11y = sessionA11y(session);
-        const submitFormNode = preSubmitA11y
-            ? resolveSubmitFormNode(preSubmitA11y, targetFormId, resolvedClick.value.target?.path)
-            : undefined;
-        const submitFormPath = submitFormNode?.path;
+        let submitPoint = { x: resolvedClick.value.x, y: resolvedClick.value.y };
+        if (formScope) {
+            if (!preSubmitA11y) {
+                return err(JSON.stringify(submitTargetFailurePayload(`Target form ${formScope.formId} cannot be revalidated because the current UI tree is unavailable`), null, detail === 'verbose' ? 2 : undefined));
+            }
+            const scoped = currentFormScope(session, preSubmitA11y, formScope);
+            const targetPath = resolvedClick.value.target?.path;
+            const currentTarget = targetPath ? findNodeByPath(preSubmitA11y, targetPath) : undefined;
+            const targetContext = currentTarget ? nodeContextForNode(preSubmitA11y, currentTarget) : undefined;
+            if (!scoped.ok ||
+                !currentTarget ||
+                !targetPath ||
+                !pathIsStrictDescendant(targetPath, formScope.path) ||
+                !nodeMatchesFilter(currentTarget, submitFilter, targetContext)) {
+                return err(JSON.stringify(submitTargetFailurePayload(`Target form ${formScope.formId} or its selected submit control became stale before click`), null, detail === 'verbose' ? 2 : undefined));
+            }
+            const currentCenter = currentVisibleClickCenter(preSubmitA11y, currentTarget);
+            if (!currentCenter) {
+                return err(JSON.stringify(submitTargetFailurePayload(`Target form ${formScope.formId} submit control is no longer visible at a usable click point`), null, detail === 'verbose' ? 2 : undefined));
+            }
+            submitPoint = currentCenter;
+            submitFormNode = scoped.node;
+        }
+        else if (preSubmitA11y) {
+            submitFormNode = resolveSubmitFormNode(preSubmitA11y, undefined, resolvedClick.value.target?.path);
+            submitFormPath = submitFormNode?.path;
+        }
         const preSubmitSignals = preSubmitA11y
             ? scopeSessionSignalsToForm(preSubmitA11y, submitFormNode)
             : undefined;
@@ -1630,18 +1943,38 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         const beforeWaitEvidence = waitFor && beforeSubmit
             ? captureWaitEvidence(beforeSubmit, waitFilter)
             : undefined;
-        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, capTimeoutMs(submitTimeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000));
+        const clickWait = await sendClick(session, submitPoint.x, submitPoint.y, capTimeoutMs(submitTimeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000));
+        if (clickWait.status === 'timed_out') {
+            const guidance = ambiguousActionGuidance(clickWait);
+            return ok(JSON.stringify(pausedPayload('submit', {
+                ...submitResumeHint,
+                retrySameCall: false,
+                inspectCurrentUiFirst: true,
+                actionId: clickWait.actionId,
+                requestId: clickWait.requestId,
+            }, {
+                pauseReason: 'action-outcome-ambiguous',
+                retrySafety: 'inspect-first',
+                guidance,
+                submit: {
+                    at: submitPoint,
+                    ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
+                    ...waitStatusPayload(clickWait),
+                },
+            }), null, detail === 'verbose' ? 2 : undefined));
+        }
         let waitResult;
         let waitError;
         if (waitFor) {
             if (!hasSoftBudget(deadlineAt)) {
                 return ok(JSON.stringify(pausedPayload('wait_for', {
                     tool: 'geometra_wait_for',
-                    filter: compactFilterPayload(waitFilter),
+                    ...compactFilterPayload(waitFilter),
                     present: waitFor.present ?? true,
+                    ...(waitFor.timeoutMs !== undefined ? { timeoutMs: waitFor.timeoutMs } : {}),
                 }, {
                     submit: {
-                        at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                        at: submitPoint,
                         ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
                         ...waitStatusPayload(clickWait),
                     },
@@ -1661,7 +1994,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         }
         const after = sessionA11y(session);
         const signals = after
-            ? scopeSessionSignalsToForm(after, submitFormPath ? formNodeAtPath(after, submitFormPath) : undefined, submitFormPath !== undefined)
+            ? scopeSessionSignalsToForm(after, submitFormPath ? formScopeNodeAtPath(after, submitFormPath) : undefined, submitFormPath !== undefined)
             : undefined;
         const clickResult = clickWait.result && typeof clickWait.result === 'object'
             ? clickWait.result
@@ -1681,11 +2014,11 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         const waitEvidenceFresh = waitResult
             ? waitConditionHasFreshEvidence(beforeWaitEvidence, after, waitResult)
             : false;
-        const execution = clickWait.status === 'timed_out' ? 'unconfirmed' : 'completed';
+        const execution = 'completed';
         const invalidCount = signals?.invalidFields.length ?? 0;
         const outcome = invalidCount > 0
             ? 'validation_failed'
-            : execution === 'unconfirmed' || Boolean(waitError)
+            : waitError
                 ? 'unconfirmed'
                 : waitFor
                     ? waitEvidenceFresh
@@ -1712,7 +2045,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             outcome,
             ...(fillSummary ? { fill: fillSummary } : {}),
             submit: {
-                at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                at: submitPoint,
                 ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target), revealSteps: resolvedClick.value.revealAttempts ?? 0 } : {}),
                 ...waitStatusPayload(clickWait),
             },
@@ -1755,8 +2088,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         isolated: z
             .boolean()
             .optional()
-            .default(false)
-            .describe('When auto-connecting via pageUrl/url, request an isolated proxy. See geometra_connect for details.'),
+            .describe('When auto-connecting via pageUrl/HTTP(S) url, use a fresh isolated Chromium by default. Pass false explicitly for sequential warm reuse.'),
         actions: z.array(batchActionSchema).min(1).max(80).describe('Ordered high-level action steps to run sequentially'),
         resumeFromIndex: z
             .number()
@@ -1806,6 +2138,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const steps = [];
         let stoppedAt;
         let pausedAt;
+        let ambiguousAt;
         const batchStartedAt = performance.now();
         // Collect transparent-fallback signals from each step so run_actions
         // surfaces them at top level regardless of `includeSteps` — otherwise
@@ -1878,6 +2211,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
+                const ambiguity = ambiguousOutcomeDetails(e);
                 const elapsedMs = Number((performance.now() - startedAt).toFixed(1));
                 const cumulativeMs = Number((performance.now() - batchStartedAt).toFixed(1));
                 steps.push({
@@ -1888,7 +2222,15 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
                     cumulativeMs,
                     ...(uiTreeWaitMs > 0 ? { uiTreeWaitMs: Number(uiTreeWaitMs.toFixed(1)) } : {}),
                     error: message,
+                    ...(ambiguity ? ambiguousOutcomePayload(ambiguity) : {}),
                 });
+                if (ambiguity) {
+                    // Continuing would silently skip a mutation that may still land.
+                    // Stop regardless of stopOnError and pin any resume to this step.
+                    ambiguousAt = index;
+                    stoppedAt = index;
+                    break;
+                }
                 if (stopOnError) {
                     stoppedAt = index;
                     break;
@@ -1902,6 +2244,15 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const completed = errorCount === 0 && stoppedAt === undefined && pausedAt === undefined && startIndex + steps.length >= actions.length;
         const resumePayload = {
             ...(startIndex > 0 ? { resumedFromIndex: startIndex } : {}),
+            ...(ambiguousAt !== undefined
+                ? {
+                    ambiguous: true,
+                    ambiguousAt,
+                    resumeBlocked: true,
+                    resumeFromIndex: ambiguousAt,
+                    resumeInstruction: 'Do not skip this ambiguous step. Inspect the current UI; an identical retry will reuse its action identity when deduplication is supported.',
+                }
+                : {}),
             ...(pausedAt !== undefined
                 ? {
                     paused: true,
@@ -1999,8 +2350,7 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         isolated: z
             .boolean()
             .optional()
-            .default(false)
-            .describe('When auto-connecting via pageUrl/url, request an isolated proxy. See geometra_connect for details.'),
+            .describe('When auto-connecting via pageUrl/HTTP(S) url, use a fresh isolated Chromium by default. Pass false explicitly for sequential warm reuse.'),
         formId: z.string().optional().describe('Optional form id from geometra_page_model. If omitted, returns every form schema on the page.'),
         maxFields: z.number().int().min(1).max(120).optional().default(80).describe('Cap returned fields per form'),
         onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields'),
@@ -2264,7 +2614,14 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
         };
         if (wait.status === 'timed_out') {
-            return err(detailText(lines.filter(Boolean).join('\n'), { completed: false, outcome: 'unconfirmed', ...compact }, detail));
+            const guidance = ambiguousActionGuidance(wait);
+            return err(detailText([...lines.filter(Boolean), guidance].join('\n'), {
+                completed: false,
+                outcome: 'unconfirmed',
+                retrySafety: 'inspect-first',
+                guidance,
+                ...compact,
+            }, detail));
         }
         return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
     });
@@ -2272,7 +2629,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
     server.tool('geometra_type', `Type text into the currently focused element. First click a textbox/input with geometra_click to focus it, then use this to type.
 
 Each character is sent as a key event through the geometry protocol. Returns a compact semantic delta when possible, otherwise a short current-UI overview.`, {
-        text: z.string().describe('Text to type into the focused element'),
+        text: z.string().max(65_536).describe('Text to type into the focused element (maximum 65,536 characters)'),
         timeoutMs: z
             .number()
             .int()
@@ -2365,32 +2722,40 @@ Detection is fully generic (no site branding). It refuses to run if the detected
         }
     });
     // ── upload files (proxy) ───────────────────────────────────────
-    server.tool('geometra_upload_files', `Attach local files to a file input. Requires \`@geometra/proxy\` (paths exist on the proxy host).
+    server.registerTool('geometra_upload_files', {
+        description: `Attach local files to a file input. Requires \`@geometra/proxy\` (paths exist on the proxy host).
 
-Strategies: **auto** (default) tries chooser click if x,y given, else a labeled file input when \`fieldLabel\` is provided, else hidden \`input[type=file]\`, else first visible file input. **hidden** targets hidden inputs directly. **drop** needs dropX,dropY for drag-target zones. **chooser** requires x,y.`, {
-        paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine, e.g. /Users/you/resume.pdf'),
-        x: z.number().optional().describe('Click X to trigger native file chooser'),
-        y: z.number().optional().describe('Click Y to trigger native file chooser'),
-        fieldLabel: z.string().optional().describe('Prefer a specific labeled file field (for example "Resume" or "Cover letter")'),
-        exact: z.boolean().optional().describe('Exact match when using fieldLabel'),
-        strategy: z
-            .enum(['auto', 'chooser', 'hidden', 'drop'])
-            .optional()
-            .describe('Upload strategy (default auto)'),
-        dropX: z.number().optional().describe('Drop target X (viewport) for strategy drop'),
-        dropY: z.number().optional().describe('Drop target Y (viewport) for strategy drop'),
-        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated file inputs'),
-        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated file inputs'),
-        timeoutMs: z
-            .number()
-            .int()
-            .min(50)
-            .max(60_000)
-            .optional()
-            .describe('Optional action wait timeout (resume parsing / SPA upload flows often need longer than a normal click)'),
-        detail: detailInput(),
-        sessionId: sessionIdInput,
-    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+Every upload must name one explicit target. **auto** (default) accepts either a complete x,y chooser target or a labeled field. **hidden** requires fieldLabel. **chooser** requires x,y. **drop** requires dropX,dropY. Geometra rejects incomplete, conflicting, and global-first-input targets.`,
+        inputSchema: z.object({
+            paths: z.array(z.string().trim().min(1)).min(1).describe('Absolute paths on the proxy machine, e.g. /Users/you/resume.pdf'),
+            x: z.number().optional().describe('Click X to trigger native file chooser; must be paired with y'),
+            y: z.number().optional().describe('Click Y to trigger native file chooser; must be paired with x'),
+            fieldLabel: z.string().trim().min(1).optional().describe('Specific labeled file field (for example "Resume" or "Cover letter")'),
+            exact: z.boolean().optional().describe('Exact match when using fieldLabel'),
+            strategy: z
+                .enum(['auto', 'chooser', 'hidden', 'drop'])
+                .optional()
+                .describe('Upload strategy (default auto)'),
+            dropX: z.number().optional().describe('Drop target X (viewport) for strategy drop; must be paired with dropY'),
+            dropY: z.number().optional().describe('Drop target Y (viewport) for strategy drop; must be paired with dropX'),
+            contextText: z.string().trim().min(1).optional().describe('Ancestor / prompt text to disambiguate repeated file inputs; requires fieldLabel'),
+            sectionText: z.string().trim().min(1).optional().describe('Containing section text to disambiguate repeated file inputs; requires fieldLabel'),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(50)
+                .max(60_000)
+                .optional()
+                .describe('Optional action wait timeout (resume parsing / SPA upload flows often need longer than a normal click)'),
+            detail: detailInput(),
+            sessionId: sessionIdInput,
+        }).strict().superRefine((input, ctx) => {
+            addActionContractIssue(ctx, fileUploadContractError(input));
+        }),
+    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, contextText, sectionText, timeoutMs, detail, sessionId }) => {
+        const contractError = fileUploadContractError({ x, y, fieldLabel, exact, strategy, dropX, dropY, contextText, sectionText });
+        if (contractError)
+            return err(contractError);
         const sessionResult = resolveToolSession(sessionId);
         if ('error' in sessionResult)
             return sessionResult.error;
@@ -2403,12 +2768,16 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
                 exact,
                 strategy,
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
+                contextText,
+                sectionText,
             }, timeoutMs ?? 8_000);
             const summary = postActionSummary(session, before, wait, detail);
             return actionWaitResponse(wait, `Uploaded ${paths.length} file(s).\n${summary}`, {
                 fileCount: paths.length,
                 ...(fieldLabel ? { fieldLabel } : {}),
                 ...(strategy ? { strategy } : {}),
+                ...(contextText ? { contextText } : {}),
+                ...(sectionText ? { sectionText } : {}),
                 ...waitStatusPayload(wait),
                 ...(fieldLabel ? { readback: fieldStatePayload(session, fieldLabel) } : {}),
             }, detail);
@@ -2417,41 +2786,41 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
             return err(e.message);
         }
     });
-    server.tool('geometra_pick_listbox_option', `Pick an option from a custom dropdown / listbox / searchable combobox (Headless UI, React Select, Radix, Ashby-style custom selects, etc.). Requires \`@geometra/proxy\`.
+    server.registerTool('geometra_pick_listbox_option', {
+        description: `Pick an option from a custom dropdown / listbox / searchable combobox (Headless UI, React Select, Radix, Ashby-style custom selects, etc.). Requires \`@geometra/proxy\`.
 
-Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying on coordinates. If the opened control is editable, MCP types \`query\` (or the option label by default) before selecting. Uses fuzzy-ish substring/alias matching unless exact=true, prefers the popup nearest the opened field, can fall back to keyboard navigation for searchable comboboxes, and returns capped \`visibleOptions\` in failure payloads so agents can retry with a real label.`, {
-        label: z.string().describe('Accessible name of the option (visible text or aria-label)'),
-        exact: z.boolean().optional().describe('Exact name match'),
-        openX: z.number().optional().describe('Click to open dropdown'),
-        openY: z.number().optional().describe('Click to open dropdown'),
-        fieldId: z.string().trim().min(1).optional().describe('Stable field id from geometra_form_schema'),
-        fieldKey: z.string().trim().min(1).optional().describe('Authored field key from geometra_form_schema for exact resolution'),
-        fieldLabel: z.string().optional().describe('Field label of the dropdown/combobox to open semantically (e.g. "Location")'),
-        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated dropdowns with the same label'),
-        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated dropdowns'),
-        query: z.string().optional().describe('Optional text to type into a searchable combobox before selecting'),
-        timeoutMs: z
-            .number()
-            .int()
-            .min(50)
-            .max(60_000)
-            .optional()
-            .describe('Optional action wait timeout for slow dropdowns / remote search results'),
-        detail: detailInput(),
-        sessionId: sessionIdInput,
-    }, async ({ label, exact, openX, openY, fieldId, fieldKey, fieldLabel, contextText, sectionText, query, timeoutMs, detail, sessionId }) => {
+fieldLabel is required so Geometra can confirm which control committed the selection. fieldId/fieldKey are supplemental exact identity and are only meaningful alongside fieldLabel. Coordinate-only opening is intentionally unsupported because it cannot provide field readback. If the opened control is editable, MCP types query (or the option label by default) before selecting.`,
+        inputSchema: z.object({
+            label: z.string().trim().min(1).describe('Accessible name of the option (visible text or aria-label)'),
+            exact: z.boolean().optional().describe('Exact name match'),
+            fieldId: z.string().trim().min(1).optional().describe('Stable field id from geometra_form_schema; used with fieldLabel'),
+            fieldKey: z.string().trim().min(1).optional().describe('Authored field key from geometra_form_schema for exact resolution; used with fieldLabel'),
+            fieldLabel: z.string().trim().min(1).describe('Field label of the dropdown/combobox to open and verify (e.g. "Location")'),
+            query: z.string().optional().describe('Optional text to type into a searchable combobox before selecting'),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(50)
+                .max(60_000)
+                .optional()
+                .describe('Optional action wait timeout for slow dropdowns / remote search results'),
+            detail: detailInput(),
+            sessionId: sessionIdInput,
+        }).strict().superRefine((input, ctx) => {
+            addActionContractIssue(ctx, listboxPickContractError(input));
+        }),
+    }, async ({ label, exact, fieldId, fieldKey, fieldLabel, query, timeoutMs, detail, sessionId }) => {
+        const contractError = listboxPickContractError({ fieldId, fieldKey, fieldLabel });
+        if (contractError)
+            return err(contractError);
         const sessionResult = resolveToolSession(sessionId);
         if ('error' in sessionResult)
             return sessionResult.error;
         const session = sessionResult.session;
         const before = sessionA11y(session);
-        if (contextText || sectionText) {
-            return err('contextText/sectionText are not supported for listbox resolution; pass fieldKey from geometra_form_schema instead.');
-        }
         try {
             const wait = await sendListboxPick(session, label, {
                 exact,
-                open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
                 fieldId,
                 fieldKey,
                 fieldLabel,
@@ -2478,33 +2847,36 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
         }
     });
     // ── select option (proxy, native <select>) ─────────────────────
-    server.tool('geometra_select_option', `Set a native HTML \`<select>\` after clicking its center (x,y from geometra_query). Requires \`@geometra/proxy\`.
+    server.registerTool('geometra_select_option', {
+        description: `Set a native HTML \`<select>\` after clicking its center (x,y from geometra_query). Requires \`@geometra/proxy\`.
 
-Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbox_option\` for custom dropdowns / searchable comboboxes.`, {
-        x: z.number().describe('X coordinate (e.g. center of the select from geometra_query)'),
-        y: z.number().describe('Y coordinate'),
-        value: z.string().optional().describe('Option value= attribute'),
-        label: z.string().optional().describe('Visible option label (substring match)'),
-        index: z.number().int().min(0).optional().describe('Zero-based option index'),
-        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated selects'),
-        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated selects'),
-        timeoutMs: z
-            .number()
-            .int()
-            .min(50)
-            .max(60_000)
-            .optional()
-            .describe('Optional action wait timeout'),
-        detail: detailInput(),
-        sessionId: sessionIdInput,
-    }, async ({ x, y, value, label, index, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+Provide one or more of value, label, and index. Every supplied selector is conjunctive identity and must describe the same enabled option. Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbox_option\` for custom dropdowns / searchable comboboxes.`,
+        inputSchema: z.object({
+            x: z.number().describe('X coordinate (e.g. center of the select from geometra_query)'),
+            y: z.number().describe('Y coordinate'),
+            value: z.string().optional().describe('Exact option value= attribute'),
+            label: z.string().trim().min(1).optional().describe('Exact normalized visible option label'),
+            index: z.number().int().min(0).optional().describe('Zero-based option index'),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(50)
+                .max(60_000)
+                .optional()
+                .describe('Optional action wait timeout'),
+            detail: detailInput(),
+            sessionId: sessionIdInput,
+        }).strict().superRefine((input, ctx) => {
+            addActionContractIssue(ctx, selectOptionContractError(input));
+        }),
+    }, async ({ x, y, value, label, index, timeoutMs, detail, sessionId }) => {
+        const contractError = selectOptionContractError({ x, y, value, label, index });
+        if (contractError)
+            return err(contractError);
         const sessionResult = resolveToolSession(sessionId);
         if ('error' in sessionResult)
             return sessionResult.error;
         const session = sessionResult.session;
-        if (value === undefined && label === undefined && index === undefined) {
-            return err('Provide at least one of value, label, or index');
-        }
         const before = sessionA11y(session);
         try {
             const wait = await sendSelectOption(session, x, y, { value, label, index }, timeoutMs);
@@ -2747,7 +3119,7 @@ For a token-efficient semantic view, use geometra_snapshot (default compact). Fo
         return ok(JSON.stringify(session.layout, null, 2));
     });
     // ── workflow state ───────────────────────────────────────────
-    server.tool('geometra_workflow_state', `Get the accumulated workflow state across page navigations. Shows which pages/forms have been filled, what values were submitted, and the fill status per page.
+    server.tool('geometra_workflow_state', `Get the accumulated workflow state across page navigations. Shows which pages/forms and field identities have been filled, with the fill status per page. Submitted values and local file paths are never stored or returned; every recorded field is represented by a redaction marker.
 
 Use this after navigating to a new page in a multi-step flow (e.g. job applications) to understand what has been completed so far. Pass \`clear: true\` to reset the workflow state.`, {
         clear: z.boolean().optional().default(false).describe('Reset the workflow state'),
@@ -2764,6 +3136,8 @@ Use this after navigating to a new page in a multi-step flow (e.g. job applicati
         if (!session.workflowState || session.workflowState.pages.length === 0) {
             return ok(JSON.stringify({
                 pageCount: 0,
+                valuesRedacted: true,
+                redactionNotice: 'Submitted values and local file paths are not stored.',
                 message: 'No workflow state recorded yet. Fill a form with geometra_fill_form to start tracking.',
             }));
         }
@@ -2775,13 +3149,18 @@ Use this after navigating to a new page in a multi-step flow (e.g. job applicati
             totalFieldsFilled: totalFields,
             totalInvalidRemaining: totalInvalid,
             elapsedMs: Date.now() - state.startedAt,
+            valuesRedacted: true,
+            redactionNotice: 'Submitted values and local file paths are not stored; filledFields lists identities and filledValues contains redaction markers only.',
             pages: state.pages.map(p => ({
                 pageUrl: p.pageUrl,
                 ...(p.formId ? { formId: p.formId } : {}),
                 ...(p.formName ? { formName: p.formName } : {}),
                 fieldCount: p.fieldCount,
                 invalidCount: p.invalidCount,
+                filledFields: p.filledFields,
+                // Preserve the established response key without retaining values.
                 filledValues: p.filledValues,
+                valuesRedacted: true,
             })),
         }));
     });
@@ -2850,12 +3229,19 @@ Returns \`{ pdf, pageUrl }\` where \`pdf\` is the base64-encoded PDF bytes.`, {
             return err(`PDF generation failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
-    server.tool('geometra_disconnect', `Disconnect from the Geometra server. Proxy-backed sessions keep compatible browsers alive by default so the next geometra_connect can reuse them quickly; pass closeBrowser=true to fully tear down the warm proxy/browser pool.`, {
-        closeBrowser: z.boolean().optional().default(false).describe('Fully close the spawned proxy/browser instead of keeping it warm for reuse'),
+    server.tool('geometra_disconnect', 'Disconnect one explicitly resolved Geometra session. Isolated browser sessions are always destroyed. A session created with isolated: false may return its browser to the warm pool; pass closeBrowser: true to destroy that session\'s browser only. This tool never closes another session\'s browser.', {
+        closeBrowser: z.boolean().optional().default(false).describe("Destroy this session's spawned proxy/browser instead of returning an explicitly reusable browser to the warm pool"),
         sessionId: sessionIdInput,
     }, async ({ closeBrowser, sessionId }) => {
-        disconnect({ closeProxy: closeBrowser, sessionId });
-        return ok(closeBrowser ? 'Disconnected and closed browser.' : 'Disconnected.');
+        const resolved = resolveToolSession(sessionId);
+        if ('error' in resolved)
+            return resolved.error;
+        const target = resolved.session;
+        disconnect({ closeProxy: closeBrowser, sessionId: target.id });
+        const browserClosed = closeBrowser || target.isolated === true;
+        return ok(browserClosed
+            ? `Disconnected session ${target.id} and closed its browser.`
+            : `Disconnected session ${target.id}; its explicitly reusable browser remains warm.`);
     });
     server.tool('geometra_list_sessions', 'List all active Geometra sessions with their IDs and URLs. Use this to discover available sessions when operating on multiple pages in parallel.', {}, async () => {
         const sessions = listSessions();
@@ -2886,8 +3272,17 @@ function connectPayload(session, opts) {
         ...(opts.detail === 'verbose' && a11y ? { currentUi: sessionOverviewFromA11y(a11y) } : {}),
     };
 }
+function sessionHasFreshUi(session) {
+    // `ws` is required on real Sessions. The absence allowance keeps legacy
+    // in-process test doubles compatible while production always verifies the
+    // transport is OPEN, closing the CLOSING -> close-event stale-read window.
+    const transportOpen = !session.ws || session.ws.readyState === session.ws.OPEN;
+    return transportOpen
+        && session.hasFreshFrame !== false
+        && Boolean(session.tree && session.layout);
+}
 function sessionA11y(session) {
-    if (!session.tree || !session.layout)
+    if (!sessionHasFreshUi(session))
         return null;
     if (session.cachedA11yRevision === session.updateRevision) {
         return session.cachedA11y ?? null;
@@ -2898,9 +3293,17 @@ function sessionA11y(session) {
     return a11y;
 }
 async function ensureSessionUiTree(session, timeoutMs = 4_000) {
-    if (session.tree && session.layout)
+    if (sessionHasFreshUi(session))
         return true;
-    return await waitForUiCondition(session, () => Boolean(session.tree && session.layout), timeoutMs);
+    try {
+        await ensureSessionConnected(session);
+    }
+    catch {
+        return false;
+    }
+    if (sessionHasFreshUi(session))
+        return true;
+    return await waitForUiCondition(session, () => sessionHasFreshUi(session), timeoutMs);
 }
 async function sessionA11yWhenReady(session, timeoutMs = 4_000) {
     const ready = await ensureSessionUiTree(session, timeoutMs);
@@ -3058,7 +3461,7 @@ function connectResponsePayload(session, opts) {
 function deferredPageModelConnectPayload(session, options) {
     return {
         deferred: true,
-        ready: Boolean(session.tree && session.layout),
+        ready: sessionHasFreshUi(session),
         tool: 'geometra_page_model',
         options: {
             maxPrimaryActions: options?.maxPrimaryActions ?? 6,
@@ -3101,6 +3504,12 @@ async function ensureToolSession(target, missingConnectionMessage = 'Not connect
     if (!normalized.ok)
         return { ok: false, error: normalized.error };
     const resolvedTarget = normalized.value;
+    if (resolvedTarget.kind === 'ws' && target.isolated === true) {
+        return {
+            ok: false,
+            error: 'isolated:true is unsupported for direct ws:// endpoints because MCP does not own that browser/runtime. Use pageUrl/HTTP(S) url for an isolated browser, or omit isolated for the externally managed endpoint.',
+        };
+    }
     try {
         if (resolvedTarget.kind === 'proxy') {
             const session = await connectThroughProxy({
@@ -3112,7 +3521,7 @@ async function ensureToolSession(target, missingConnectionMessage = 'Not connect
                 slowMo: target.slowMo,
                 ...(target.stealth !== undefined && { stealth: target.stealth }),
                 awaitInitialFrame: target.awaitInitialFrame,
-                isolated: target.isolated,
+                isolated: target.isolated !== false,
             });
             return {
                 ok: true,
@@ -3145,6 +3554,7 @@ function autoConnectionPayload(target) {
         return {};
     return {
         autoConnected: true,
+        sessionId: target.session.id,
         ...(target.transport ? { transport: target.transport } : {}),
         ...(target.requestedPageUrl ? { pageUrl: target.requestedPageUrl } : {}),
         ...(target.requestedWsUrl ? { requestedWsUrl: target.requestedWsUrl } : {}),
@@ -3168,8 +3578,8 @@ function postActionSummary(session, before, wait, detail = 'minimal') {
     }
     if (wait?.status === 'timed_out') {
         notes.push(detail === 'verbose'
-            ? `No frame or patch arrived within ${wait.timeoutMs}ms after the action. The action may still have succeeded if it did not change geometry or semantics.`
-            : `No update arrived within ${wait.timeoutMs}ms; the action may still have succeeded.`);
+            ? `No correlated terminal response arrived within ${wait.timeoutMs}ms. The action may still be running or may already have succeeded. ${ambiguousActionGuidance(wait)}`
+            : `No correlated response arrived within ${wait.timeoutMs}ms; the action may still have succeeded. Do not retry blindly.`);
     }
     if (!after)
         return [...notes, 'No UI update received'].filter(Boolean).join('\n');
@@ -3203,10 +3613,100 @@ function summarizeCompactContext(context) {
     }
     return parts.length > 0 ? `Context: ${parts.join(' | ')}` : '';
 }
+function pathIsStrictDescendant(path, ancestorPath) {
+    return path.length > ancestorPath.length && ancestorPath.every((segment, index) => path[index] === segment);
+}
 function formNodeAtPath(root, path) {
     const node = findNodeByPath(root, path);
     return node?.role === 'form' ? node : undefined;
 }
+function formScopeNodeAtPath(root, path) {
+    const node = findNodeByPath(root, path);
+    return node && (node.role === 'form' || node.role === 'group' || node.role === 'region')
+        ? node
+        : undefined;
+}
+function formScopeFieldAnchor(field) {
+    if (field.fieldKey)
+        return `key:${field.fieldKey}`;
+    return [
+        'field',
+        field.kind,
+        normalizeLookupKey(field.label),
+        field.controlType ?? '',
+        field.choiceType ?? '',
+        field.booleanChoice ? 'boolean' : '',
+    ].join(':');
+}
+function captureFormScopeIdentity(node, schema) {
+    const fieldAnchors = schema.fields.map(formScopeFieldAnchor).sort();
+    const name = normalizeLookupKey(node.name || schema.name || '');
+    if (fieldAnchors.length === 0 && !name) {
+        return {
+            ok: false,
+            error: `Target form ${schema.formId} has no stable semantic or field identity; refusing to submit without a maintainable form scope`,
+        };
+    }
+    return {
+        ok: true,
+        identity: {
+            role: node.role,
+            name,
+            fieldAnchors,
+        },
+    };
+}
+function containsFormFieldAnchors(current, expected) {
+    const counts = new Map();
+    for (const anchor of current)
+        counts.set(anchor, (counts.get(anchor) ?? 0) + 1);
+    for (const anchor of expected) {
+        const count = counts.get(anchor) ?? 0;
+        if (count === 0)
+            return false;
+        counts.set(anchor, count - 1);
+    }
+    return true;
+}
+function currentFormScope(session, root, scope) {
+    const node = formScopeNodeAtPath(root, scope.path);
+    const schema = getSessionFormSchemas(session, {
+        includeOptions: false,
+        includeContext: 'auto',
+    }).find(candidate => candidate.formId === scope.formId);
+    if (!node || !schema) {
+        return { ok: false, error: `Target form ${scope.formId} is stale or no longer resolves to a form in the current UI` };
+    }
+    const currentName = normalizeLookupKey(node.name || schema.name || '');
+    const currentAnchors = schema.fields.map(formScopeFieldAnchor).sort();
+    if (node.role !== scope.identity.role ||
+        currentName !== scope.identity.name ||
+        !containsFormFieldAnchors(currentAnchors, scope.identity.fieldAnchors)) {
+        return {
+            ok: false,
+            error: `Target form ${scope.formId} was replaced at the same path; its semantic/schema identity no longer matches`,
+        };
+    }
+    return { ok: true, node, schema };
+}
+function currentVisibleClickCenter(root, target) {
+    const { x, y, width, height } = target.bounds;
+    const viewport = root.bounds;
+    if (![x, y, width, height, viewport.x, viewport.y, viewport.width, viewport.height].every(Number.isFinite))
+        return undefined;
+    if (width <= 0 || height <= 0 || viewport.width <= 0 || viewport.height <= 0)
+        return undefined;
+    const visibleLeft = Math.max(x, viewport.x);
+    const visibleTop = Math.max(y, viewport.y);
+    const visibleRight = Math.min(x + width, viewport.x + viewport.width);
+    const visibleBottom = Math.min(y + height, viewport.y + viewport.height);
+    if (visibleRight <= visibleLeft || visibleBottom <= visibleTop)
+        return undefined;
+    return {
+        x: visibleLeft + (visibleRight - visibleLeft) / 2,
+        y: visibleTop + (visibleBottom - visibleTop) / 2,
+    };
+}
 function resolveSubmitFormNode(root, formId, submitPath) {
     const parsedForm = formId ? parseSectionId(formId) : null;
     if (parsedForm?.kind === 'form') {
@@ -3422,7 +3922,11 @@ function fieldStatePayload(session, fieldLabel, fieldKey) {
 function waitStatusPayload(wait) {
     if (!wait)
         return {};
-    const payload = { wait: wait.status };
+    const payload = {
+        wait: wait.status,
+        requestId: wait.requestId,
+        actionId: wait.actionId,
+    };
     // Surface navigation info from proxy click handlers so callers can tell
     // when a click triggered a full-page nav (form submit → thank-you page).
     // Without this, the proxy session may die on the next request and the
@@ -3555,9 +4059,19 @@ async function revealSemanticTarget(session, options) {
         const a11y = sessionA11y(session);
         if (!a11y)
             return { ok: false, error: 'No UI tree available to reveal from' };
-        const matches = sortA11yNodes(findNodes(a11y, options.filter));
+        if (options.formScope) {
+            const scoped = currentFormScope(session, a11y, options.formScope);
+            if (!scoped.ok) {
+                return { ok: false, error: scoped.error, staleFormScope: true };
+            }
+        }
+        // Match against the page root first so prompt/section/item context from
+        // ancestors outside the form remains available, then constrain the
+        // actionable candidates to descendants of the selected current form.
+        const matches = sortA11yNodes(findNodes(a11y, options.filter).filter(node => !options.formScope || pathIsStrictDescendant(node.path, options.formScope.path)));
         if (matches.length === 0) {
-            return { ok: false, error: `No elements found matching ${JSON.stringify(options.filter)}` };
+            const scopeSuffix = options.formScope ? ` within form ${options.formScope.formId}` : '';
+            return { ok: false, error: `No elements found matching ${JSON.stringify(options.filter)}${scopeSuffix}` };
         }
         if (options.index >= matches.length) {
             return {
@@ -3626,6 +4140,7 @@ async function resolveClickLocation(session, options) {
         filter: options.filter,
         index: options.index ?? 0,
         fullyVisible: options.fullyVisible ?? true,
+        formScope: options.formScope,
         maxSteps: options.maxRevealSteps,
         timeoutMs: options.revealTimeoutMs ?? 2_500,
     });
@@ -3645,6 +4160,8 @@ async function resolveClickLocationWithFallback(session, options) {
     const first = await resolveClickLocation(session, options);
     if (first.ok)
         return first;
+    if (first.staleFormScope)
+        return first;
     // Fallback only applies to semantic resolves. Explicit coordinates never enter
     // the reveal path, so there is nothing to retry.
     const hasExplicitCoordinates = options.x !== undefined || options.y !== undefined;
@@ -3667,6 +4184,8 @@ async function resolveClickLocationWithFallback(session, options) {
                 fallback: { attempted: true, used: true, reason: 'revision-retry', attempts },
             };
         }
+        if (retry.staleFormScope)
+            return retry;
     }
     if (options.fullyVisible !== false) {
         attempts += 1;
@@ -3683,6 +4202,8 @@ async function resolveClickLocationWithFallback(session, options) {
                 fallback: { attempted: true, used: true, reason: 'relaxed-visibility', attempts },
             };
         }
+        if (relaxed.staleFormScope)
+            return relaxed;
     }
     // All fallback phases tried and none recovered. Carry the trace of what we
     // tried so operators see the attempted-but-failed signal alongside the
@@ -3729,11 +4250,19 @@ function compactFormattedNode(node) {
 function detailText(summary, compact, detail) {
     return detail === 'terse' ? JSON.stringify(compact) : summary;
 }
+function ambiguousActionGuidance(wait) {
+    return `Outcome is ambiguous for actionId ${wait.actionId} (requestId ${wait.requestId}). ` +
+        'Do not retry blindly or skip this step; inspect the current UI first. ' +
+        'An identical retry reuses the same action identity when the proxy supports deduplication.';
+}
 function actionWaitResponse(wait, summary, compact, detail) {
     if (wait.status === 'timed_out') {
-        return err(detailText(summary, {
+        const guidance = ambiguousActionGuidance(wait);
+        return err(detailText(`${summary}\n${guidance}`, {
             completed: false,
             outcome: 'unconfirmed',
+            retrySafety: 'inspect-first',
+            guidance,
             ...compact,
         }, detail));
     }
@@ -3908,6 +4437,25 @@ function pad2(n) {
     return n < 10 ? `0${n}` : String(n);
 }
 function plannedFillInputsForField(field, value) {
+    if (field.kind === 'file') {
+        if (!Array.isArray(value)) {
+            return { error: `Field "${field.label}" expects a non-empty string array of proxy-host file paths` };
+        }
+        const paths = value.map(path => path.trim()).filter(Boolean);
+        if (paths.length === 0 || paths.length !== value.length) {
+            return { error: `Field "${field.label}" expects a non-empty string array of proxy-host file paths` };
+        }
+        if (field.format?.multiple !== true && paths.length > 1) {
+            return { error: `Field "${field.label}" accepts only one file` };
+        }
+        return [{
+                kind: 'file',
+                fieldId: field.id,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+                fieldLabel: field.label,
+                paths,
+            }];
+    }
     if (field.kind === 'text') {
         if (typeof value !== 'string')
             return { error: `Field "${field.label}" expects a string value` };
@@ -4045,13 +4593,12 @@ function isResolvedFillFieldInput(field) {
 }
 function resolveFillFieldInputs(session, fields) {
     const unresolved = fields.filter(field => !isResolvedFillFieldInput(field));
+    const requiresSchemaLookup = fields.some(field => typeof field.fieldId === 'string');
     const a11y = sessionA11y(session);
-    if (unresolved.length === 0 && !a11y) {
+    if (unresolved.length === 0 && !requiresSchemaLookup && !a11y) {
         return { ok: true, fields: fields };
     }
     if (!a11y) {
-        if (unresolved.length === 0)
-            return { ok: true, fields: fields };
         return { ok: false, error: 'No UI tree available to resolve fieldId entries from geometra_form_schema' };
     }
     const schemas = buildFormSchemas(a11y, { includeOptions: true, includeContext: 'always' });
@@ -4068,10 +4615,16 @@ function resolveFillFieldInputs(session, fields) {
                 return { ok: false, error: `Unknown form field id ${field.fieldId}. Refresh geometra_form_schema and try again.` };
             }
             if (schemaField) {
-                const expectedKind = field.kind === 'file' ? 'file' : field.kind;
-                if (field.kind !== 'file' && schemaField.kind !== expectedKind) {
+                if (schemaField.kind !== field.kind) {
                     return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not ${field.kind}.` };
                 }
+                const suppliedLabel = field.kind === 'toggle' ? field.label : field.fieldLabel;
+                if (normalizeLookupKey(suppliedLabel) !== normalizeLookupKey(schemaField.label)) {
+                    return {
+                        ok: false,
+                        error: `Field id ${field.fieldId} now resolves to "${schemaField.label}", not "${suppliedLabel}". Refresh geometra_form_schema; Geometra refused to downgrade the stale id to a label-only mutation.`,
+                    };
+                }
             }
             const suppliedLabel = field.kind === 'toggle' ? field.label : field.fieldLabel;
             const distinctLabelMatches = new Map();
@@ -4179,14 +4732,20 @@ function resolveFillFieldInputs(session, fields) {
             });
             continue;
         }
-        return {
-            ok: false,
-            error: `File field id ${field.fieldId} still needs fieldLabel. geometra_form_schema does not reliably expose proxy file inputs yet.`,
-        };
+        if (schemaField.kind !== 'file') {
+            return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not file.` };
+        }
+        resolved.push({
+            ...field,
+            ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
+            fieldLabel: schemaField.label,
+        });
     }
     return { ok: true, fields: resolved };
 }
 function canFallbackToSequentialFill(error) {
+    if (ambiguousOutcomeDetails(error))
+        return false;
     const message = error instanceof Error ? error.message : String(error);
     try {
         const parsed = JSON.parse(message);
@@ -4236,10 +4795,20 @@ async function tryBatchedResolvedFields(session, fields, detail) {
     try {
         const startRevision = session.updateRevision;
         const wait = await sendFillFields(session, toProxyFillFields(fields));
-        if (wait.status === 'timed_out')
-            return { ok: false };
+        assertActionWaitConfirmed('Batched field fill', wait);
         const ackResult = parseProxyFillAckResult(wait.result);
         batchAckResult = ackResult;
+        if (fields.some(field => field.kind === 'file')) {
+            if (!ackResult) {
+                throw new AmbiguousActionOutcomeError('Batched file fill', wait, 'Batched file fill was acknowledged without structured proxy confirmation; the upload may already have happened. Do not retry blindly.');
+            }
+            return {
+                ok: true,
+                finalSource: 'proxy',
+                final: ackResult,
+                invalidRemaining: ackResult.invalidCount,
+            };
+        }
         if (ackResult && ackResult.invalidCount === 0) {
             return {
                 ok: true,
@@ -4249,27 +4818,31 @@ async function tryBatchedResolvedFields(session, fields, detail) {
             };
         }
         await waitForDeferredBatchUpdate(session, startRevision, wait);
-        await waitForBatchFieldReadback(session, fields);
+        const readbackSnapshot = await waitForBatchFieldReadback(session, fields);
+        if (!readbackSnapshot) {
+            if (!sessionA11y(session)) {
+                throw new AmbiguousActionOutcomeError('Batched field fill', wait, 'Batched field fill was sent, but its read-back evidence became unavailable before confirmation. The fields may already have changed. Do not retry blindly.');
+            }
+            return { ok: false };
+        }
+        const signals = collectSessionSignals(readbackSnapshot);
+        const invalidRemaining = signals.invalidFields.length;
+        if ((!batchAckResult || batchAckResult.invalidCount > 0) && invalidRemaining > 0) {
+            return { ok: false };
+        }
+        return {
+            ok: true,
+            finalSource: 'session',
+            final: sessionSignalsPayload(signals, detail),
+            invalidRemaining,
+            readbackSnapshot,
+        };
     }
     catch (e) {
         if (canFallbackToSequentialFill(e))
             return { ok: false };
         throw e;
     }
-    const after = sessionA11y(session);
-    if (!after)
-        return { ok: false };
-    const signals = collectSessionSignals(after);
-    const invalidRemaining = signals.invalidFields.length;
-    if ((!batchAckResult || batchAckResult.invalidCount > 0) && invalidRemaining > 0) {
-        return { ok: false };
-    }
-    return {
-        ok: true,
-        finalSource: 'session',
-        final: sessionSignalsPayload(signals, detail),
-        invalidRemaining,
-    };
 }
 async function waitForDeferredBatchUpdate(session, startRevision, wait) {
     if (wait.status !== 'acknowledged' || session.updateRevision > startRevision)
@@ -4277,12 +4850,17 @@ async function waitForDeferredBatchUpdate(session, startRevision, wait) {
     await waitForUiCondition(session, () => session.updateRevision > startRevision, 750);
 }
 async function waitForBatchFieldReadback(session, fields) {
+    let matchingSnapshot;
     await waitForUiCondition(session, () => {
         const a11y = sessionA11y(session);
         if (!a11y)
             return false;
-        return fields.every(field => batchFieldReadbackMatches(a11y, field));
+        if (!fields.every(field => batchFieldReadbackMatches(a11y, field)))
+            return false;
+        matchingSnapshot = a11y;
+        return true;
     }, 1500);
+    return matchingSnapshot;
 }
 function batchFieldReadbackMatches(a11y, field) {
     switch (field.kind) {
@@ -4337,9 +4915,50 @@ function canDeferInitialFrameForRunActions(actions) {
 function assertBatchActionConfirmed(actionType, wait) {
     assertActionWaitConfirmed(`${actionType} action`, wait);
 }
+class AmbiguousActionOutcomeError extends Error {
+    wait;
+    constructor(actionName, wait, message) {
+        super(message ?? `${actionName} timed out after ${wait.timeoutMs}ms; its outcome is unconfirmed. ${ambiguousActionGuidance(wait)}`);
+        this.name = 'AmbiguousActionOutcomeError';
+        this.wait = wait;
+    }
+}
+function ambiguousOutcomeDetails(error) {
+    if (error instanceof AmbiguousActionOutcomeError) {
+        return {
+            wait: error.wait,
+            requestId: error.wait.requestId,
+            actionId: error.wait.actionId,
+        };
+    }
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidate = error;
+    const code = typeof candidate.code === 'string' ? candidate.code : undefined;
+    const requestId = typeof candidate.requestId === 'string' ? candidate.requestId : undefined;
+    const actionId = typeof candidate.actionId === 'string' ? candidate.actionId : undefined;
+    const message = typeof candidate.message === 'string' ? candidate.message : '';
+    if (code !== 'ACTION_OUTCOME_AMBIGUOUS' &&
+        !(requestId && actionId && message.includes('Outcome is ambiguous')))
+        return undefined;
+    return { ...(requestId ? { requestId } : {}), ...(actionId ? { actionId } : {}), ...(code ? { code } : {}) };
+}
+function ambiguousOutcomePayload(details) {
+    return {
+        outcome: 'unconfirmed',
+        retrySafety: 'inspect-first',
+        ...(details.wait ? waitStatusPayload(details.wait) : {}),
+        ...(!details.wait && details.requestId ? { requestId: details.requestId } : {}),
+        ...(!details.wait && details.actionId ? { actionId: details.actionId } : {}),
+        ...(details.code ? { code: details.code } : {}),
+        guidance: details.actionId && details.requestId
+            ? `Outcome is ambiguous for actionId ${details.actionId} (requestId ${details.requestId}). Do not retry blindly or skip this step; inspect the current UI first.`
+            : 'The action outcome is ambiguous. Do not retry blindly or skip this step; inspect the current UI first.',
+    };
+}
 function assertActionWaitConfirmed(actionName, wait) {
     if (wait.status === 'timed_out') {
-        throw new Error(`${actionName} timed out after ${wait.timeoutMs}ms; its outcome is unconfirmed.`);
+        throw new AmbiguousActionOutcomeError(actionName, wait);
     }
 }
 async function executeBatchAction(session, action, detail, includeSteps) {
@@ -4457,6 +5076,9 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             };
         }
         case 'upload_files': {
+            const contractError = fileUploadContractError(action);
+            if (contractError)
+                throw new Error(contractError);
             const before = sessionA11y(session);
             const wait = await sendFileUpload(session, action.paths, {
                 click: action.x !== undefined && action.y !== undefined ? { x: action.x, y: action.y } : undefined,
@@ -4464,6 +5086,8 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 exact: action.exact,
                 strategy: action.strategy,
                 drop: action.dropX !== undefined && action.dropY !== undefined ? { x: action.dropX, y: action.dropY } : undefined,
+                contextText: action.contextText,
+                sectionText: action.sectionText,
             }, action.timeoutMs ?? 8_000);
             assertBatchActionConfirmed(action.type, wait);
             return {
@@ -4472,16 +5096,20 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     fileCount: action.paths.length,
                     ...(action.fieldLabel ? { fieldLabel: action.fieldLabel } : {}),
                     ...(action.strategy ? { strategy: action.strategy } : {}),
+                    ...(action.contextText ? { contextText: action.contextText } : {}),
+                    ...(action.sectionText ? { sectionText: action.sectionText } : {}),
                     ...waitStatusPayload(wait),
                     ...(action.fieldLabel ? { readback: fieldStatePayload(session, action.fieldLabel) } : {}),
                 },
             };
         }
         case 'pick_listbox_option': {
+            const contractError = listboxPickContractError(action);
+            if (contractError)
+                throw new Error(contractError);
             const before = sessionA11y(session);
             const wait = await sendListboxPick(session, action.label, {
                 exact: action.exact,
-                open: action.openX !== undefined && action.openY !== undefined ? { x: action.openX, y: action.openY } : undefined,
                 fieldId: action.fieldId,
                 fieldKey: action.fieldKey,
                 fieldLabel: action.fieldLabel,
@@ -4505,9 +5133,9 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             };
         }
         case 'select_option': {
-            if (action.value === undefined && action.label === undefined && action.index === undefined) {
-                throw new Error('select_option step requires at least one of value, label, or index');
-            }
+            const contractError = selectOptionContractError(action);
+            if (contractError)
+                throw new Error(contractError);
             const before = sessionA11y(session);
             const wait = await sendSelectOption(session, action.x, action.y, {
                 value: action.value,
@@ -4647,13 +5275,13 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             if (!resolvedFields.ok)
                 throw new Error(resolvedFields.error);
             const verifyFillsFn = action.verifyFills
-                ? () => verifyFormFills(session, resolvedFields.fields.map(field => ({ field, confidence: 1.0, matchMethod: 'label-exact' })))
+                ? (readbackSnapshot) => verifyFormFills(session, resolvedFields.fields.map(field => ({ field, confidence: 1.0, matchMethod: 'label-exact' })), readbackSnapshot)
                 : undefined;
             let fallbackFromBatch;
             if (!includeSteps) {
                 const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
                 if (batched.ok) {
-                    const verification = verifyFillsFn?.();
+                    const verification = verifyFillsFn?.(batched.readbackSnapshot);
                     return {
                         summary: `Filled ${resolvedFields.fields.length} field(s) in one proxy batch.`,
                         compact: {
@@ -4736,7 +5364,7 @@ function suggestRecovery(field, error) {
         }
     }
     if (lowerError.includes('timeout')) {
-        return `Action timed out. The page may still be loading. Try geometra_wait_for with a loading indicator, then retry.`;
+        return 'Action timed out and may still complete. Do not retry blindly; inspect the current UI or wait for a loading indicator before repeating the identical action.';
     }
     return undefined;
 }
@@ -4816,8 +5444,8 @@ export function valuesEquivalent(expected, actual) {
     const aNorm = actual.replace(/\s+/g, ' ').trim().toLowerCase();
     return eNorm === aNorm;
 }
-function verifyFormFills(session, planned) {
-    const a11y = sessionA11y(session);
+function verifyFormFills(session, planned, readbackSnapshot) {
+    const a11y = readbackSnapshot ?? sessionA11y(session);
     if (!a11y)
         return { verified: 0, mismatches: [] };
     const mismatches = [];
@@ -4980,27 +5608,29 @@ function recordWorkflowFill(session, formId, formName, valuesById, valuesByLabel
     if (!session.workflowState) {
         session.workflowState = { pages: [], startedAt: Date.now() };
     }
-    const filledValues = {};
-    for (const [k, v] of Object.entries(valuesById ?? {})) {
-        if (typeof v === 'string' || typeof v === 'boolean')
-            filledValues[k] = v;
-    }
-    for (const [k, v] of Object.entries(valuesByLabel ?? {})) {
-        if (typeof v === 'string' || typeof v === 'boolean')
-            filledValues[k] = v;
-    }
+    const fieldIdentities = new Set([
+        ...Object.keys(valuesById ?? {}),
+        ...Object.keys(valuesByLabel ?? {}),
+    ]);
+    const filledFields = Array.from(fieldIdentities).sort();
+    const filledValues = Object.fromEntries(filledFields.map(identity => [identity, '[REDACTED]']));
     const a11y = sessionA11y(session);
-    const pageUrl = a11y?.meta?.pageUrl ?? session.url;
+    const pageUrl = workflowUrlOrigin(a11y?.meta?.pageUrl ?? session.url);
     session.workflowState.pages.push({
         pageUrl,
         formId,
         formName,
         filledValues,
+        filledFields,
+        valuesRedacted: true,
         filledAt: Date.now(),
         fieldCount,
         invalidCount,
     });
 }
+function workflowUrlOrigin(rawUrl) {
+    return sanitizeUrlToOrigin(rawUrl) ?? REDACTED_STATE_URL;
+}
 async function captureScreenshotBase64(session) {
     try {
         const wait = await sendScreenshot(session);