@geometra/mcp 1.63.2 → 1.65.0

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, 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(),
@@ -282,11 +284,87 @@ function capBatchActionTimeouts(action, capMs) {
             return action;
     }
 }
+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'),
-        fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        fieldLabel: z.string().describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
+        fieldId: nonEmptyFieldIdSchema.optional().describe('Optional stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
         value: z.string().describe('Text value to set'),
         exact: z.boolean().optional().describe('Exact label match'),
         typingDelayMs: z
@@ -301,11 +379,11 @@ const fillFieldSchema = z.union([
             .optional()
             .describe('Use composition-friendly events for IME-heavy controlled fields.'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('text'),
-        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
-        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
+        fieldId: nonEmptyFieldIdSchema.describe('Stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         value: z.string().describe('Text value to set'),
         exact: z.boolean().optional().describe('Exact label match'),
         typingDelayMs: z
@@ -320,12 +398,13 @@ const fillFieldSchema = z.union([
             .optional()
             .describe('Use composition-friendly events for IME-heavy controlled fields.'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('choice'),
-        fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        fieldLabel: z.string().describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
+        fieldId: nonEmptyFieldIdSchema.optional().describe('Optional stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
         value: z.string().describe('Desired option value / answer label'),
+        optionIndex: z.number().int().min(0).optional().describe('Exact native <select> option index from optionDetails'),
         query: z.string().optional().describe('Optional search text for searchable comboboxes'),
         choiceType: z
             .enum(['select', 'group', 'listbox'])
@@ -333,12 +412,13 @@ const fillFieldSchema = z.union([
             .describe('Optional choice subtype hint. Use `group` for repeated radio/button answers, `select` for native selects, and `listbox` for searchable dropdowns.'),
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('choice'),
-        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
-        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
+        fieldId: nonEmptyFieldIdSchema.describe('Stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         value: z.string().describe('Desired option value / answer label'),
+        optionIndex: z.number().int().min(0).optional().describe('Exact native <select> option index from optionDetails'),
         query: z.string().optional().describe('Optional search text for searchable comboboxes'),
         choiceType: z
             .enum(['select', 'group', 'listbox'])
@@ -346,42 +426,51 @@ const fillFieldSchema = z.union([
             .describe('Optional choice subtype hint. Use `group` for repeated radio/button answers, `select` for native selects, and `listbox` for searchable dropdowns.'),
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('toggle'),
-        fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        label: z.string().describe('Visible checkbox/radio label to set. Optional to duplicate when fieldId is present.'),
+        fieldId: nonEmptyFieldIdSchema.optional().describe('Optional stable field id from geometra_form_schema'),
+        label: nonEmptyToggleLabelSchema.describe('Visible checkbox/radio label to set. Optional to duplicate when fieldId is present.'),
         checked: z.boolean().optional().default(true).describe('Desired checked state (default true)'),
         exact: z.boolean().optional().describe('Exact label match'),
         controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('toggle'),
-        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
-        label: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
+        fieldId: nonEmptyFieldIdSchema.describe('Stable field id from geometra_form_schema'),
+        label: nonEmptyToggleLabelSchema.optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         checked: z.boolean().optional().default(true).describe('Desired checked state (default true)'),
         exact: z.boolean().optional().describe('Exact label match'),
         controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('file'),
-        fieldId: z.string().optional().describe('Optional stable field id from geometra_form_schema'),
-        fieldLabel: z.string().describe('Visible file-field label / accessible name'),
+        fieldId: nonEmptyFieldIdSchema.optional().describe('Optional stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.describe('Visible file-field label / accessible name'),
         paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine'),
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
     z.object({
         kind: z.literal('file'),
-        fieldId: z.string().describe('Stable field id from geometra_form_schema'),
-        fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label when file fields are exposed by geometra_form_schema'),
+        fieldId: nonEmptyFieldIdSchema.describe('Stable field id from geometra_form_schema'),
+        fieldLabel: nonEmptyFieldLabelSchema.optional().describe('Optional when fieldId is present; MCP resolves the current label when file fields are exposed by geometra_form_schema'),
         paths: z.array(z.string()).min(1).describe('Absolute paths on the proxy machine'),
         exact: z.boolean().optional().describe('Exact label match'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
-    }),
+    }).strict(),
 ]);
+function toProxyFillFields(fields) {
+    return fields.map(field => {
+        const proxyField = { ...field };
+        delete proxyField.timeoutMs;
+        if (proxyField.kind === 'choice')
+            delete proxyField.expectedReadback;
+        return proxyField;
+    });
+}
 const formValueSchema = z.union([
     z.string(),
     z.boolean(),
@@ -398,14 +487,14 @@ const batchActionSchema = z.discriminatedUnion('type', [
         fullyVisible: z.boolean().optional().describe('When clicking by semantic target, require full visibility before clicking (default true)'),
         maxRevealSteps: z.number().int().min(1).max(48).optional().describe('Maximum reveal attempts before clicking a semantic target. When omitted, Geometra auto-scales from scroll distance for tall forms.'),
         revealTimeoutMs: timeoutMsInput.describe('Per-scroll wait timeout while revealing a semantic target'),
-        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the click'),
+        waitFor: z.object(waitConditionShape()).strict().optional().describe('Optional semantic condition to wait for after the click'),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('type'),
-        text: z.string(),
+        text: z.string().max(65_536),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('key'),
         key: z.string(),
@@ -414,46 +503,51 @@ const batchActionSchema = z.discriminatedUnion('type', [
         meta: z.boolean().optional(),
         alt: z.boolean().optional(),
         timeoutMs: timeoutMsInput,
-    }),
+    }).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(),
-        fieldLabel: z.string().optional(),
+        fieldId: z.string().trim().min(1).optional(),
+        fieldKey: z.string().trim().min(1).optional(),
+        fieldLabel: z.string().trim().min(1),
         query: z.string().optional(),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('select_option'),
         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(),
     z.object({
         type: z.literal('set_checked'),
-        label: z.string(),
+        label: z.string().trim().min(1, 'set_checked label must not be empty'),
         checked: z.boolean().optional(),
         exact: z.boolean().optional(),
         controlType: z.enum(['checkbox', 'radio']).optional(),
+        fieldKey: z.string().trim().min(1).optional(),
+        contextText: z.string().trim().min(1).optional(),
+        sectionText: z.string().trim().min(1).optional(),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('wheel'),
         deltaY: z.number(),
@@ -461,13 +555,13 @@ const batchActionSchema = z.discriminatedUnion('type', [
         x: z.number().optional(),
         y: z.number().optional(),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('wait_for'),
         ...nodeFilterShape(),
         present: z.boolean().optional(),
         timeoutMs: timeoutMsInput,
-    }),
+    }).strict(),
     z.object({
         type: z.literal('fill_fields'),
         fields: z.array(fillFieldSchema).min(1).max(80),
@@ -475,7 +569,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
             .boolean()
             .optional()
             .describe('After filling, read each text/choice field back and flag mismatches (e.g. autocomplete rejected input, format transformed). Adds a `verification` entry to the step.'),
-    }),
+    }).strict(),
     z.object({
         type: z.literal('expand_section'),
         id: z.string().describe('Stable section id from geometra_page_model (e.g. fm:1.0, ls:2.1).'),
@@ -492,11 +586,21 @@ const batchActionSchema = z.discriminatedUnion('type', [
         itemOffset: z.number().int().min(0).optional(),
         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.
 
@@ -506,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()
@@ -541,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
@@ -576,6 +684,7 @@ Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth
         onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields when returnForms=true'),
         onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields when returnForms=true'),
         includeOptions: z.boolean().optional().default(false).describe('Include explicit choice option labels in returned form schemas'),
+        includeFormGraph: z.boolean().optional().default(false).describe('Also include FormGraph 0.1-compatible graphs in returned form schemas. Use for paperwork/application workflows that need field paths, review gates, and source anchors.'),
         includeContext: formSchemaContextInput(),
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         schemaFormat: formSchemaFormatInput(),
@@ -590,12 +699,16 @@ 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,
             onlyRequiredFields: input.onlyRequiredFields,
             onlyInvalidFields: input.onlyInvalidFields,
             includeOptions: input.includeOptions,
+            includeFormGraph: input.includeFormGraph,
             includeContext: input.includeContext,
             sinceSchemaId: input.sinceSchemaId,
             format: input.schemaFormat,
@@ -618,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,
@@ -650,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);
@@ -681,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()
@@ -984,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
@@ -1032,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 {
@@ -1053,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'
@@ -1063,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;
                 }
             }
@@ -1079,12 +1216,19 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
         const payload = {
-            completed: stoppedAt === undefined && steps.length === resolvedFields.fields.length,
+            completed: errorCount === 0 && stoppedAt === undefined && steps.length === resolvedFields.fields.length,
             fieldCount: resolvedFields.fields.length,
             successCount,
             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) } : {}),
         };
@@ -1138,17 +1282,13 @@ 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 }) => {
         const browser = resolveBrowserStealth({ stealth, browserMode });
         if (!browser.ok)
             return err(browser.error);
-        const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
-            ? directLabelBatchFields(valuesByLabel)
-            : null;
         const resolved = await ensureToolSession({
             sessionId,
             url,
@@ -1160,7 +1300,6 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             slowMo,
             stealth: browser.stealth,
             isolated,
-            awaitInitialFrame: directFields ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_fill_form.');
         if (!resolved.ok)
             return err(resolved.error);
@@ -1170,50 +1309,6 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         if (entryCount === 0) {
             return err('Provide at least one value in valuesById or valuesByLabel');
         }
-        if (directFields) {
-            try {
-                const startRevision = session.updateRevision;
-                const wait = await sendFillFields(session, directFields);
-                const ackResult = parseProxyFillAckResult(wait.result);
-                if (ackResult && ackResult.invalidCount === 0) {
-                    recordWorkflowFill(session, undefined, undefined, valuesById, valuesByLabel, 0, directFields.length);
-                    return ok(JSON.stringify({
-                        ...connection,
-                        completed: true,
-                        execution: 'batched-direct',
-                        finalSource: 'proxy',
-                        requestedValueCount: entryCount,
-                        fieldCount: directFields.length,
-                        successCount: directFields.length,
-                        errorCount: 0,
-                        final: ackResult,
-                    }, null, detail === 'verbose' ? 2 : undefined));
-                }
-                await waitForDeferredBatchUpdate(session, startRevision, wait);
-                const afterDirect = sessionA11y(session);
-                const directSignals = afterDirect ? collectSessionSignals(afterDirect) : undefined;
-                if (directSignals && directSignals.invalidFields.length === 0) {
-                    recordWorkflowFill(session, undefined, undefined, valuesById, valuesByLabel, 0, directFields.length);
-                    return ok(JSON.stringify({
-                        ...connection,
-                        completed: true,
-                        execution: 'batched-direct',
-                        finalSource: 'session',
-                        requestedValueCount: entryCount,
-                        fieldCount: directFields.length,
-                        successCount: directFields.length,
-                        errorCount: 0,
-                        final: sessionSignalsPayload(directSignals, detail),
-                    }, null, detail === 'verbose' ? 2 : undefined));
-                }
-            }
-            catch (e) {
-                if (!canFallbackToSequentialFill(e)) {
-                    const message = e instanceof Error ? e.message : String(e);
-                    return err(message);
-                }
-            }
-        }
         if (!session.tree || !session.layout) {
             await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
         }
@@ -1231,7 +1326,8 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         if (!resolution.ok)
             return err(resolution.error);
         const schema = resolution.schema;
-        const planned = planFormFill(schema, { valuesById, valuesByLabel });
+        const targetFormPath = parseSectionId(schema.formId)?.path;
+        const planned = planFormFill(schema, { valuesById, valuesByLabel }, schemas);
         if (!planned.ok)
             return err(planned.error);
         let skippedCount = 0;
@@ -1265,14 +1361,24 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         let fallbackFromBatch;
         if (!includeSteps) {
             let usedBatch = false;
-            let batchAckResult;
+            let batchReadbackSnapshot;
             try {
                 const startRevision = session.updateRevision;
-                const wait = await sendFillFields(session, planned.fields);
+                const wait = await sendFillFields(session, toProxyFillFields(planned.fields));
+                assertActionWaitConfirmed('Batched form fill', wait);
                 const ackResult = parseProxyFillAckResult(wait.result);
-                batchAckResult = ackResult;
-                if (ackResult && ackResult.invalidCount === 0) {
-                    usedBatch = true;
+                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,
@@ -1283,15 +1389,57 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                         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) {
+                        const payload = {
+                            ...connection,
+                            completed: true,
+                            execution: 'batched',
+                            finalSource: 'proxy',
+                            formId: schema.formId,
+                            requestedValueCount: entryCount,
+                            fieldCount: planned.fields.length,
+                            successCount: planned.fields.length,
+                            errorCount: 0,
+                            final: ackResult,
+                        };
+                        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                    }
+                }
                 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);
@@ -1299,18 +1447,25 @@ 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 signals = after ? collectSessionSignals(after) : undefined;
+                const after = batchReadbackSnapshot;
+                const signals = after
+                    ? scopeSessionSignalsToForm(after, targetFormPath ? formNodeAtPath(after, targetFormPath) : undefined, targetFormPath !== undefined)
+                    : undefined;
                 const invalidRemaining = signals?.invalidFields.length ?? 0;
-                if ((!batchAckResult || batchAckResult.invalidCount > 0) && invalidRemaining > 0) {
+                if (invalidRemaining > 0) {
                     usedBatch = false;
                     fallbackFromBatch = { attempted: true, used: true, reason: 'batched-invalid-readback', attempts: 2 };
                 }
             }
             if (usedBatch) {
-                const after = sessionA11y(session);
-                const signals = after ? collectSessionSignals(after) : undefined;
+                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, batchReadbackSnapshot)
+                    : undefined;
                 const payload = {
                     ...connection,
                     completed: true,
@@ -1324,6 +1479,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                     minConfidence: planned.planned.length > 0
                         ? Number(Math.min(...planned.planned.map(p => p.confidence)).toFixed(2))
                         : undefined,
+                    ...(verification ? { verification } : {}),
                     ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
                 };
                 recordWorkflowFill(session, schema.formId, schema.name, valuesById, valuesByLabel, invalidRemaining, planned.fields.length);
@@ -1335,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];
@@ -1349,23 +1506,36 @@ 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;
                 }
             }
         }
         const after = sessionA11y(session);
-        const signals = after ? collectSessionSignals(after) : undefined;
+        const signals = after
+            ? scopeSessionSignalsToForm(after, targetFormPath ? formNodeAtPath(after, targetFormPath) : undefined, targetFormPath !== undefined)
+            : undefined;
         const invalidRemaining = signals?.invalidFields.length ?? 0;
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
         const verification = verifyFills ? verifyFormFills(session, planned.planned) : undefined;
         const payload = {
             ...connection,
-            completed: stoppedAt === undefined && (startIndex + steps.length) === planned.fields.length,
+            completed: errorCount === 0 && stoppedAt === undefined && (startIndex + steps.length) === planned.fields.length,
             execution: 'sequential',
             formId: schema.formId,
             requestedValueCount: entryCount,
@@ -1378,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) } : {}),
@@ -1410,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).'),
@@ -1420,17 +1599,17 @@ 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'),
-        submit: z.object(nodeFilterShape()).optional().describe('Semantic target for the submit button. Defaults to {role: "button", name: "Submit"}.'),
+        submit: z.object(nodeFilterShape()).strict().optional().describe('Semantic target for the submit button. Defaults to {role: "button", name: "Submit"}.'),
         submitIndex: z.number().int().min(0).optional().default(0).describe('Which matching submit target to click after sorting top-to-bottom (default 0)'),
         submitTimeoutMs: z.number().int().min(50).max(60_000).optional().default(15_000).describe('Action wait timeout for the submit click (default 15000ms). Increase for slow backends.'),
-        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the submit click (success banner, navigation, submit gone, etc.)'),
+        waitFor: z.object(waitConditionShape()).strict().optional().describe('Optional semantic condition to wait for after the submit click (success banner, submit gone, etc.)'),
         skipFill: z.boolean().optional().default(false).describe('Skip the fill phase and go straight to submit+wait. Use when values have already been filled by a previous call.'),
         softTimeoutMs: softTimeoutMsInput(),
-        failOnInvalid: z.boolean().optional().default(false).describe('Return an error if invalid fields remain after the submit wait resolves.'),
+        failOnInvalid: z.boolean().optional().default(false).describe('Control whether a validation_failed outcome is returned as an MCP error. Outcome facts are always reported.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
     }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
@@ -1445,28 +1624,37 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             return err(resolved.error);
         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,
-            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));
         }
         const entryA11y = sessionA11y(session);
         if (!entryA11y)
             return err('No UI tree available for form submission');
-        const entryUrl = entryA11y.meta?.pageUrl;
         if (!hasSoftBudget(deadlineAt)) {
             return ok(JSON.stringify(pausedPayload('before-fill', { retrySameCall: true }), null, detail === 'verbose' ? 2 : undefined));
         }
@@ -1482,13 +1670,47 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             if (!resolution.ok)
                 return err(resolution.error);
             const schema = resolution.schema;
-            const planned = planFormFill(schema, { valuesById, valuesByLabel });
+            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);
             let usedBatch = true;
             try {
                 const startRevision = session.updateRevision;
-                const wait = await sendFillFields(session, planned.fields.map(field => capFillFieldTimeout(field, timeoutCapFromDeadline(deadlineAt))), capTimeoutMs(undefined, timeoutCapFromDeadline(deadlineAt), HOST_SAFE_TOOL_TIMEOUT_MS));
+                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 = {
@@ -1497,19 +1719,23 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                     fieldCount: planned.fields.length,
                     ...waitStatusPayload(wait),
                     ...(ack ? { invalidCount: ack.invalidCount, alertCount: ack.alertCount } : {}),
+                    ...(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',
-                        skipFill: true,
-                        submit: submit ?? { role: 'button', name: 'Submit' },
-                        submitIndex,
-                        ...(waitFor ? { waitFor } : {}),
-                    }), 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}`);
@@ -1520,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 = {
@@ -1531,10 +1758,8 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                         };
                         return ok(JSON.stringify(pausedPayload('fill', {
                             tool: 'geometra_submit_form',
-                            skipFill: true,
-                            submit: submit ?? { role: 'button', name: 'Submit' },
-                            submitIndex,
-                            ...(waitFor ? { waitFor } : {}),
+                            retrySameCall: true,
+                            skipFill: false,
                         }), null, detail === 'verbose' ? 2 : undefined));
                     }
                     try {
@@ -1543,19 +1768,42 @@ 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;
                     }
                 }
-                if (firstErr !== undefined && successCount === 0) {
-                    return err(`Failed to fill form before submit (sequential fallback): ${firstErr}`);
-                }
                 fillSummary = {
                     formId: schema.formId,
                     execution: 'sequential',
                     fieldCount: planned.fields.length,
                     successCount,
+                    ...(firstErr !== undefined ? { error: firstErr } : {}),
                     ...(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,
+                        execution: 'unconfirmed',
+                        outcome: 'unconfirmed',
+                        phase: 'fill',
+                        fill: fillSummary,
+                        ...(fillFallback ? { fill_fallback: fillFallback } : {}),
+                        submit: { attempted: false, reason: 'Fill phase did not complete successfully.' },
+                    }, null, detail === 'verbose' ? 2 : undefined));
+                }
             }
         }
         const submitResumeHint = {
@@ -1569,110 +1817,217 @@ 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 = submitTargetFailurePayload(resolvedClick.error, resolvedClick.fallback);
+            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        }
+        const preSubmitA11y = sessionA11y(session);
+        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;
+        if (preSubmitSignals && preSubmitSignals.invalidFields.length > 0) {
             const payload = {
                 ...connection,
                 completed: false,
+                execution: 'not_started',
+                outcome: 'validation_failed',
                 ...(fillSummary ? { fill: fillSummary } : {}),
                 ...(fillFallback ? { fill_fallback: fillFallback } : {}),
-                submit: { ok: false, error: `Submit target not found: ${resolvedClick.error}` },
-                ...(resolvedClick.fallback ? { submit_fallback: resolvedClick.fallback } : {}),
+                submit: {
+                    attempted: false,
+                    reason: 'Invalid fields remain in the target form before submit; the submit control was not clicked.',
+                },
+                final: sessionSignalsPayload(preSubmitSignals, detail),
             };
-            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+            const serialized = JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined);
+            return failOnInvalid ? err(serialized) : ok(serialized);
         }
         if (!hasSoftBudget(deadlineAt)) {
             return ok(JSON.stringify(pausedPayload('submit', submitResumeHint), null, detail === 'verbose' ? 2 : undefined));
         }
         const beforeSubmit = sessionA11y(session);
-        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, capTimeoutMs(submitTimeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000));
+        const beforeClickUrl = beforeSubmit?.meta?.pageUrl;
+        const waitFilter = {
+            id: waitFor?.id,
+            role: waitFor?.role,
+            name: waitFor?.name,
+            text: waitFor?.text,
+            contextText: waitFor?.contextText,
+            promptText: waitFor?.promptText,
+            sectionText: waitFor?.sectionText,
+            itemText: waitFor?.itemText,
+            value: waitFor?.value,
+            checked: waitFor?.checked,
+            disabled: waitFor?.disabled,
+            focused: waitFor?.focused,
+            selected: waitFor?.selected,
+            expanded: waitFor?.expanded,
+            invalid: waitFor?.invalid,
+            required: waitFor?.required,
+            busy: waitFor?.busy,
+        };
+        const beforeWaitEvidence = waitFor && beforeSubmit
+            ? captureWaitEvidence(beforeSubmit, waitFilter)
+            : undefined;
+        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({
-                        id: waitFor.id,
-                        role: waitFor.role,
-                        name: waitFor.name,
-                        text: waitFor.text,
-                        contextText: waitFor.contextText,
-                        promptText: waitFor.promptText,
-                        sectionText: waitFor.sectionText,
-                        itemText: waitFor.itemText,
-                        value: waitFor.value,
-                        checked: waitFor.checked,
-                        disabled: waitFor.disabled,
-                        focused: waitFor.focused,
-                        selected: waitFor.selected,
-                        expanded: waitFor.expanded,
-                        invalid: waitFor.invalid,
-                        required: waitFor.required,
-                        busy: waitFor.busy,
-                    }),
+                    ...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),
                     },
                 }), null, detail === 'verbose' ? 2 : undefined));
             }
             const postWait = await waitForSemanticCondition(session, {
-                filter: {
-                    id: waitFor.id,
-                    role: waitFor.role,
-                    name: waitFor.name,
-                    text: waitFor.text,
-                    contextText: waitFor.contextText,
-                    promptText: waitFor.promptText,
-                    sectionText: waitFor.sectionText,
-                    itemText: waitFor.itemText,
-                    value: waitFor.value,
-                    checked: waitFor.checked,
-                    disabled: waitFor.disabled,
-                    focused: waitFor.focused,
-                    selected: waitFor.selected,
-                    expanded: waitFor.expanded,
-                    invalid: waitFor.invalid,
-                    required: waitFor.required,
-                    busy: waitFor.busy,
-                },
+                filter: waitFilter,
                 present: waitFor.present ?? true,
                 timeoutMs: capTimeoutMs(waitFor.timeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000),
             });
             if (!postWait.ok) {
-                const preErrFallbacks = [];
-                if (fillFallback)
-                    preErrFallbacks.push({ phase: 'fill', ...fillFallback });
-                if (resolvedClick.fallback)
-                    preErrFallbacks.push({ phase: 'submit', ...resolvedClick.fallback });
-                const payload = {
-                    ...connection,
-                    completed: false,
-                    ...(fillSummary ? { fill: fillSummary } : {}),
-                    submit: {
-                        at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
-                        ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
-                        ...waitStatusPayload(clickWait),
-                    },
-                    ...(preErrFallbacks.length > 0 ? { fallbacks: preErrFallbacks } : {}),
-                    waitFor: { ok: false, error: postWait.error },
-                };
-                return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+                waitError = postWait.error;
+            }
+            else {
+                waitResult = postWait.value;
             }
-            waitResult = postWait.value;
         }
         const after = sessionA11y(session);
-        const signals = after ? collectSessionSignals(after) : undefined;
-        const afterUrl = after?.meta?.pageUrl;
-        const navigated = Boolean(afterUrl && entryUrl && afterUrl !== entryUrl);
+        const signals = after
+            ? scopeSessionSignalsToForm(after, submitFormPath ? formScopeNodeAtPath(after, submitFormPath) : undefined, submitFormPath !== undefined)
+            : undefined;
+        const clickResult = clickWait.result && typeof clickWait.result === 'object'
+            ? clickWait.result
+            : undefined;
+        const clickAfterUrl = typeof clickResult?.pageUrl === 'string' ? clickResult.pageUrl : undefined;
+        const clickBeforeUrl = typeof clickResult?.urlBefore === 'string' ? clickResult.urlBefore : beforeClickUrl;
+        const observedAfterUrl = after?.meta?.pageUrl;
+        const navigatedByClick = Boolean(clickResult?.navigated === true &&
+            clickAfterUrl &&
+            clickBeforeUrl &&
+            clickAfterUrl !== clickBeforeUrl);
+        const navigatedByTree = Boolean(observedAfterUrl && beforeClickUrl && observedAfterUrl !== beforeClickUrl);
+        const navigated = navigatedByClick || navigatedByTree;
+        const afterUrl = navigatedByClick && clickAfterUrl
+            ? clickAfterUrl
+            : observedAfterUrl ?? clickAfterUrl;
+        const waitEvidenceFresh = waitResult
+            ? waitConditionHasFreshEvidence(beforeWaitEvidence, after, waitResult)
+            : false;
+        const execution = 'completed';
+        const invalidCount = signals?.invalidFields.length ?? 0;
+        const outcome = invalidCount > 0
+            ? 'validation_failed'
+            : waitError
+                ? 'unconfirmed'
+                : waitFor
+                    ? waitEvidenceFresh
+                        ? 'submitted'
+                        : 'unconfirmed'
+                    : navigated
+                        ? 'submitted'
+                        : 'unconfirmed';
+        const completed = outcome === 'submitted';
         // Aggregate all fallback usage into a single top-level `fallbacks[]`
         // array so this tool matches the shape emitted by `geometra_run_actions`
         // and can be aggregated the same way by operators.
@@ -1685,16 +2040,22 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         }
         const payload = {
             ...connection,
-            completed: true,
+            completed,
+            execution,
+            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),
             },
-            ...(waitResult ? { waitFor: waitConditionCompact(waitResult) } : {}),
+            ...(waitResult
+                ? { waitFor: { ...waitConditionCompact(waitResult), fresh: waitEvidenceFresh } }
+                : waitError
+                    ? { waitFor: { ok: false, error: waitError } }
+                    : {}),
             ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
-            ...(navigated ? { navigated: true, afterUrl } : {}),
+            ...(navigated ? { navigated: true, ...(afterUrl ? { afterUrl } : {}) } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
         // Pull in page model hints on navigation to mirror fill_form behavior.
@@ -1705,15 +2066,12 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             if (model.verification)
                 payload.verification = model.verification;
         }
-        if (failOnInvalid && signals && signals.invalidFields.length > 0) {
-            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
-        }
-        // Swallow the unused `beforeSubmit` binding; it anchors that the a11y tree was
-        // captured pre-click and keeps the pattern consistent with other tools that
-        // diff before/after for summaries (we rely on the waitFor / final signals
-        // for the actual comparison here).
-        void beforeSubmit;
-        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        const serialized = JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined);
+        if (waitError)
+            return err(serialized);
+        if (failOnInvalid && outcome === 'validation_failed')
+            return err(serialized);
+        return ok(serialized);
     });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
@@ -1730,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()
@@ -1781,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
@@ -1853,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({
@@ -1863,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;
@@ -1874,9 +2241,18 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
         const elapsedMs = Number((performance.now() - toolStartedAt).toFixed(1));
-        const completed = stoppedAt === undefined && pausedAt === undefined && startIndex + steps.length >= actions.length;
+        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,
@@ -1892,6 +2268,8 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             ? {
                 ...connection,
                 completed,
+                successCount,
+                errorCount,
                 ...resumePayload,
                 ...(stoppedAt !== undefined ? { stoppedAt } : {}),
                 ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
@@ -1972,18 +2350,18 @@ 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'),
         onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields'),
         includeOptions: z.boolean().optional().default(false).describe('Include explicit choice option labels'),
+        includeFormGraph: z.boolean().optional().default(false).describe('Also include FormGraph 0.1-compatible graphs for the returned forms'),
         includeContext: formSchemaContextInput(),
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         format: formSchemaFormatInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeFormGraph, includeContext, sinceSchemaId, format, sessionId }) => {
         const browser = resolveBrowserStealth({ stealth, browserMode });
         if (!browser.ok)
             return err(browser.error);
@@ -2000,6 +2378,7 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
             onlyRequiredFields,
             onlyInvalidFields,
             includeOptions,
+            includeFormGraph,
             includeContext,
             sinceSchemaId,
             format,
@@ -2132,7 +2511,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             .optional()
             .default(2_500)
             .describe('Per-scroll wait timeout while revealing a semantic target (default 2500ms)'),
-        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the click'),
+        waitFor: z.object(waitConditionShape()).strict().optional().describe('Optional semantic condition to wait for after the click'),
         timeoutMs: z
             .number()
             .int()
@@ -2177,6 +2556,29 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
         });
         if (!resolved.ok)
             return err(clickFallbackErrorMessage(resolved));
+        const waitFilter = waitFor ? {
+            id: waitFor.id,
+            role: waitFor.role,
+            name: waitFor.name,
+            text: waitFor.text,
+            contextText: waitFor.contextText,
+            promptText: waitFor.promptText,
+            sectionText: waitFor.sectionText,
+            itemText: waitFor.itemText,
+            value: waitFor.value,
+            checked: waitFor.checked,
+            disabled: waitFor.disabled,
+            focused: waitFor.focused,
+            selected: waitFor.selected,
+            expanded: waitFor.expanded,
+            invalid: waitFor.invalid,
+            required: waitFor.required,
+            busy: waitFor.busy,
+        } : undefined;
+        const waitEvidenceRoot = sessionA11y(session) ?? before;
+        const beforeWaitEvidence = waitFilter && waitEvidenceRoot
+            ? captureWaitEvidence(waitEvidenceRoot, waitFilter)
+            : undefined;
         const wait = await sendClick(session, resolved.value.x, resolved.value.y, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
         const clickLine = !resolved.value.target
@@ -2185,37 +2587,23 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
         const lines = [clickLine, summary];
         if (waitFor) {
             const postWait = await waitForSemanticCondition(session, {
-                filter: {
-                    id: waitFor.id,
-                    role: waitFor.role,
-                    name: waitFor.name,
-                    text: waitFor.text,
-                    contextText: waitFor.contextText,
-                    promptText: waitFor.promptText,
-                    sectionText: waitFor.sectionText,
-                    itemText: waitFor.itemText,
-                    value: waitFor.value,
-                    checked: waitFor.checked,
-                    disabled: waitFor.disabled,
-                    focused: waitFor.focused,
-                    selected: waitFor.selected,
-                    expanded: waitFor.expanded,
-                    invalid: waitFor.invalid,
-                    required: waitFor.required,
-                    busy: waitFor.busy,
-                },
+                filter: waitFilter,
                 present: waitFor.present ?? true,
                 timeoutMs: waitFor.timeoutMs ?? 10_000,
             });
             if (!postWait.ok)
                 return err([...lines, postWait.error].join('\n'));
+            const fresh = waitConditionHasFreshEvidence(beforeWaitEvidence, sessionA11y(session), postWait.value);
+            if (!fresh) {
+                return err([...lines, 'Post-click condition matched only pre-existing evidence; the click outcome is unconfirmed.'].join('\n'));
+            }
             lines.push(`Post-click ${waitConditionSuccessLine(postWait.value)}`);
             const compact = {
                 at: { x: resolved.value.x, y: resolved.value.y },
                 ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                 ...waitStatusPayload(wait),
                 ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
-                postWait: waitConditionCompact(postWait.value),
+                postWait: { ...waitConditionCompact(postWait.value), fresh: true },
             };
             return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
         }
@@ -2225,13 +2613,23 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             ...waitStatusPayload(wait),
             ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
         };
+        if (wait.status === 'timed_out') {
+            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));
     });
     // ── type ─────────────────────────────────────────────────────
     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()
@@ -2249,10 +2647,10 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         const before = sessionA11y(session);
         const wait = await sendType(session, text, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
-        return ok(detailText(`Typed "${text}".\n${summary}`, {
+        return actionWaitResponse(wait, `Typed "${text}".\n${summary}`, {
             ...compactTextValue(text),
             ...waitStatusPayload(wait),
-        }, detail));
+        }, detail);
     });
     // ── key ──────────────────────────────────────────────────────
     server.tool('geometra_key', `Send a special key press (Enter, Tab, Escape, ArrowDown, etc.) to the Geometra UI. Useful for form submission, focus navigation, and keyboard shortcuts.`, {
@@ -2278,10 +2676,10 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         const before = sessionA11y(session);
         const wait = await sendKey(session, key, { shift, ctrl, meta, alt }, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
-        return ok(detailText(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`, {
+        return actionWaitResponse(wait, `Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`, {
             key: formatKeyCombo(key, { shift, ctrl, meta, alt }),
             ...waitStatusPayload(wait),
-        }, detail));
+        }, detail);
     });
     // ── fill OTP / verification-code box group ─────────────────────
     server.tool('geometra_fill_otp', `Fill a multi-cell OTP / verification-code input group (e.g. Greenhouse's 8-box security code, generic 6-digit 2FA widgets, Auth0 / Clerk per-char inputs). Auto-detects a row of sibling <input maxlength="1"> elements at adjacent x-coordinates and types each character through a real keyboard event cycle so React's per-cell onKeyDown handler can auto-advance focus.
@@ -2311,45 +2709,53 @@ Detection is fully generic (no site branding). It refuses to run if the detected
             const wait = await sendFillOtp(session, value, { fieldLabel, perCharDelayMs }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
             const result = wait.result;
-            return ok(detailText(`Filled OTP code (${value.length} chars).\n${summary}`, {
+            return actionWaitResponse(wait, `Filled OTP code (${value.length} chars).\n${summary}`, {
                 ...compactTextValue(value),
                 ...(fieldLabel ? { fieldLabel } : {}),
                 ...(result?.cellCount !== undefined ? { cellCount: result.cellCount } : {}),
                 ...(result?.filledCount !== undefined ? { filledCount: result.filledCount } : {}),
                 ...waitStatusPayload(wait),
-            }, detail));
+            }, detail);
         }
         catch (e) {
             return err(e.message);
         }
     });
     // ── 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;
@@ -2362,41 +2768,51 @@ 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 ok(detailText(`Uploaded ${paths.length} file(s).\n${summary}`, {
+            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));
+            }, detail);
         }
         catch (e) {
             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'),
-        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, fieldLabel, contextText: _contextText, sectionText: _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;
@@ -2405,105 +2821,125 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
         try {
             const wait = await sendListboxPick(session, label, {
                 exact,
-                open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
+                fieldId,
+                fieldKey,
                 fieldLabel,
                 query,
             }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            const fieldSummary = fieldLabel ? summarizeFieldLabelState(session, fieldLabel) : undefined;
+            const fieldSummary = fieldLabel ? summarizeFieldLabelState(session, fieldLabel, fieldKey) : undefined;
             const summaryText = [
                 `Picked listbox option "${label}".`,
                 fieldSummary,
                 summary,
             ].filter(Boolean).join('\n');
-            return ok(detailText(summaryText, {
+            return actionWaitResponse(wait, summaryText, {
                 label,
+                ...(fieldId ? { fieldId } : {}),
+                ...(fieldKey ? { fieldKey } : {}),
                 ...(fieldLabel ? { fieldLabel } : {}),
                 ...waitStatusPayload(wait),
-                ...(fieldLabel ? { readback: fieldStatePayload(session, fieldLabel) } : {}),
-            }, detail));
+                ...(fieldLabel ? { readback: fieldStatePayload(session, fieldLabel, fieldKey) } : {}),
+            }, detail);
         }
         catch (e) {
             return err(e.message);
         }
     });
     // ── 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);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(detailText(`Selected option.\n${summary}`, {
+            return actionWaitResponse(wait, `Selected option.\n${summary}`, {
                 at: { x, y },
                 ...(value !== undefined ? { value } : {}),
                 ...(label !== undefined ? { label } : {}),
                 ...(index !== undefined ? { index } : {}),
                 ...waitStatusPayload(wait),
-            }, detail));
+            }, detail);
         }
         catch (e) {
             return err(e.message);
         }
     });
-    server.tool('geometra_set_checked', `Set a checkbox or radio by label. Requires \`@geometra/proxy\`.
+    server.registerTool('geometra_set_checked', {
+        description: `Set a checkbox or radio by label. Requires \`@geometra/proxy\`.
 
-Prefer this over raw coordinate clicks for custom forms that keep the real input visually hidden (common on Ashby, Greenhouse custom widgets, and design-system checkboxes/radios). Uses substring label matching unless exact=true.`, {
-        label: z.string().describe('Accessible label or visible option text to match'),
-        checked: z.boolean().optional().default(true).describe('Desired checked state (radios only support true)'),
-        exact: z.boolean().optional().describe('Exact label match'),
-        controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
-        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated checkboxes/radios'),
-        sectionText: z.string().optional().describe('Containing section text to disambiguate repeated checkboxes/radios'),
-        timeoutMs: z
-            .number()
-            .int()
-            .min(50)
-            .max(60_000)
-            .optional()
-            .describe('Optional action wait timeout'),
-        detail: detailInput(),
-        sessionId: sessionIdInput,
-    }, async ({ label, checked, exact, controlType, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+Prefer this over raw coordinate clicks for custom forms that keep the real input visually hidden (common on Ashby, Greenhouse custom widgets, and design-system checkboxes/radios). Uses substring label matching unless exact=true. Unknown parameter names are rejected.`,
+        inputSchema: z.object({
+            label: z.string().trim().min(1, 'label must not be empty').describe('Accessible label or visible option text to match'),
+            checked: z.boolean().optional().default(true).describe('Desired checked state (radios only support true)'),
+            exact: z.boolean().optional().describe('Exact label match'),
+            controlType: z.enum(['checkbox', 'radio']).optional().describe('Limit matching to checkbox or radio'),
+            fieldKey: z.string().trim().min(1).optional().describe('Authored field key from geometra_form_schema for exact resolution'),
+            contextText: z.string().trim().min(1).optional().describe('Ancestor / prompt text to disambiguate repeated checkboxes/radios'),
+            sectionText: z.string().trim().min(1).optional().describe('Containing section text to disambiguate repeated checkboxes/radios'),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(50)
+                .max(60_000)
+                .optional()
+                .describe('Optional action wait timeout'),
+            detail: detailInput(),
+            sessionId: sessionIdInput,
+        }).strict(),
+    }, async ({ label, checked, exact, controlType, fieldKey, contextText, sectionText, timeoutMs, detail, sessionId }) => {
         const sessionResult = resolveToolSession(sessionId);
         if ('error' in sessionResult)
             return sessionResult.error;
         const session = sessionResult.session;
         const before = sessionA11y(session);
         try {
-            const wait = await sendSetChecked(session, label, { checked, exact, controlType }, timeoutMs);
+            const wait = await sendSetChecked(session, label, {
+                checked,
+                exact,
+                controlType,
+                ...(fieldKey ? { fieldKey } : {}),
+                contextText,
+                sectionText,
+            }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(detailText(`Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`, {
+            return actionWaitResponse(wait, `Set ${controlType ?? 'checkbox/radio'} "${label}" to ${String(checked ?? true)}.\n${summary}`, {
                 label,
                 checked: checked ?? true,
                 ...(controlType ? { controlType } : {}),
+                ...(fieldKey ? { fieldKey } : {}),
+                ...(contextText ? { contextText } : {}),
+                ...(sectionText ? { sectionText } : {}),
                 ...waitStatusPayload(wait),
-            }, detail));
+            }, detail);
         }
         catch (e) {
             return err(e.message);
@@ -2533,12 +2969,12 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
         try {
             const wait = await sendWheel(session, deltaY, { deltaX, x, y }, timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
-            return ok(detailText(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`, {
+            return actionWaitResponse(wait, `Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`, {
                 deltaY,
                 ...(deltaX !== undefined ? { deltaX } : {}),
                 ...(x !== undefined && y !== undefined ? { at: { x, y } } : {}),
                 ...waitStatusPayload(wait),
-            }, detail));
+            }, detail);
         }
         catch (e) {
             return err(e.message);
@@ -2683,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'),
@@ -2700,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.',
             }));
         }
@@ -2711,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,
             })),
         }));
     });
@@ -2786,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();
@@ -2822,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;
@@ -2834,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;
+    try {
+        await ensureSessionConnected(session);
+    }
+    catch {
+        return false;
+    }
+    if (sessionHasFreshUi(session))
         return true;
-    return await waitForUiCondition(session, () => Boolean(session.tree && session.layout), timeoutMs);
+    return await waitForUiCondition(session, () => sessionHasFreshUi(session), timeoutMs);
 }
 async function sessionA11yWhenReady(session, timeoutMs = 4_000) {
     const ready = await ensureSessionUiTree(session, timeoutMs);
@@ -2883,6 +3350,7 @@ function packedFormSchemas(forms) {
         ic: form.invalidCount,
         f: form.fields.map(field => ({
             i: field.id,
+            ...(field.fieldKey ? { fk: field.fieldKey } : {}),
             k: field.kind,
             l: field.label,
             ...(field.required ? { r: 1 } : {}),
@@ -2891,6 +3359,8 @@ function packedFormSchemas(forms) {
             ...(field.booleanChoice ? { b: 1 } : {}),
             ...(field.controlType ? { t: field.controlType } : {}),
             ...(field.optionCount !== undefined ? { oc: field.optionCount } : {}),
+            ...(field.options ? { o: field.options } : {}),
+            ...(field.optionDetails ? { od: field.optionDetails } : {}),
             ...(field.value ? { v: field.value } : {}),
             ...(field.valueLength !== undefined ? { vl: field.valueLength } : {}),
             ...(field.checked !== undefined ? { c: field.checked ? 1 : 0 } : {}),
@@ -2904,7 +3374,10 @@ function packedFormSchemas(forms) {
 }
 function formSchemaResponsePayload(session, opts) {
     const forms = getSessionFormSchemas(session, opts);
-    const schemaJson = JSON.stringify(forms);
+    const graphForms = opts.includeFormGraph && !opts.includeOptions
+        ? getSessionFormSchemas(session, { ...opts, includeOptions: true })
+        : forms;
+    const schemaJson = JSON.stringify(forms) + (opts.includeFormGraph ? '|formgraph' : '');
     const schemaId = `fs:${shortHash(schemaJson)}`;
     if (opts.sinceSchemaId && opts.sinceSchemaId === schemaId) {
         return {
@@ -2914,12 +3387,14 @@ function formSchemaResponsePayload(session, opts) {
             format: opts.format ?? 'compact',
         };
     }
+    const pageUrl = sessionA11y(session)?.meta?.pageUrl;
     return {
         schemaId,
         changed: true,
         formCount: forms.length,
         format: opts.format ?? 'compact',
         forms: (opts.format ?? 'compact') === 'packed' ? packedFormSchemas(forms) : forms,
+        ...(opts.includeFormGraph ? { formGraphs: graphForms.map(form => formSchemaToFormGraph(form, pageUrl)) } : {}),
     };
 }
 function totalReturnedSchemaFields(forms) {
@@ -2986,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,
@@ -3029,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({
@@ -3040,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,
@@ -3073,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 } : {}),
@@ -3096,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');
@@ -3131,6 +3613,123 @@ 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') {
+        const explicit = formNodeAtPath(root, parsedForm.path);
+        if (explicit)
+            return explicit;
+    }
+    if (!submitPath)
+        return undefined;
+    for (let length = submitPath.length; length >= 0; length--) {
+        const candidate = formNodeAtPath(root, submitPath.slice(0, length));
+        if (candidate)
+            return candidate;
+    }
+    return undefined;
+}
+function scopeSessionSignalsToForm(pageRoot, formNode, targetFormWasKnown = false) {
+    const pageSignals = collectSessionSignals(pageRoot);
+    if (formNode) {
+        return { ...pageSignals, invalidFields: collectSessionSignals(formNode).invalidFields };
+    }
+    return targetFormWasKnown ? { ...pageSignals, invalidFields: [] } : pageSignals;
+}
 function collectSessionSignals(root) {
     const signals = {
         ...(root.meta?.pageUrl ? { pageUrl: root.meta.pageUrl } : {}),
@@ -3143,6 +3742,17 @@ function collectSessionSignals(root) {
     };
     const seenAlerts = new Set();
     const seenInvalidIds = new Set();
+    const formControlRoles = new Set([
+        'textbox',
+        'combobox',
+        'checkbox',
+        'radio',
+        'spinbutton',
+        'listbox',
+        'searchbox',
+        'slider',
+        'switch',
+    ]);
     const captchaPattern = /recaptcha|g-recaptcha|hcaptcha|h-captcha|turnstile|cf-turnstile|captcha/i;
     const captchaTypes = {
         recaptcha: 'recaptcha', 'g-recaptcha': 'recaptcha',
@@ -3169,7 +3779,11 @@ function collectSessionSignals(root) {
                 signals.alerts.push(text);
             }
         }
-        if ((node.role === 'textbox' || node.role === 'combobox' || node.role === 'checkbox' || node.role === 'radio') && node.state?.invalid) {
+        const isFormControl = formControlRoles.has(node.role) ||
+            node.meta?.controlTag === 'input' ||
+            node.meta?.controlTag === 'textarea' ||
+            node.meta?.controlTag === 'select';
+        if (isFormControl && (node.state?.invalid === true || Boolean(node.validation?.error))) {
             const id = nodeIdForPath(node.path);
             if (!seenInvalidIds.has(id)) {
                 seenInvalidIds.add(id);
@@ -3274,20 +3888,26 @@ function compactTextValue(value, inlineLimit = 48) {
         ? { value: normalized }
         : { valueLength: value.length };
 }
-function fieldStatePayload(session, fieldLabel) {
+function fieldReadbackNodes(a11y, fieldLabel, roles, fieldKey) {
+    if (fieldKey) {
+        const matches = [];
+        const allowedRoles = new Set(roles);
+        const walk = (node) => {
+            if (allowedRoles.has(node.role) && node.meta?.controlKey === fieldKey)
+                matches.push(node);
+            for (const child of node.children)
+                walk(child);
+        };
+        walk(a11y);
+        return matches;
+    }
+    return roles.flatMap(role => findNodes(a11y, { name: fieldLabel, role }));
+}
+function fieldStatePayload(session, fieldLabel, fieldKey) {
     const a11y = sessionA11y(session);
     if (!a11y)
         return undefined;
-    const matches = findNodes(a11y, {
-        name: fieldLabel,
-        role: 'combobox',
-    });
-    if (matches.length === 0) {
-        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'textbox' }));
-    }
-    if (matches.length === 0) {
-        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'button' }));
-    }
+    const matches = fieldReadbackNodes(a11y, fieldLabel, ['combobox', 'textbox', 'button'], fieldKey);
     const match = matches[0];
     if (!match)
         return undefined;
@@ -3302,7 +3922,11 @@ function fieldStatePayload(session, fieldLabel) {
 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
@@ -3372,6 +3996,45 @@ function waitConditionCompact(result) {
         ...(result.present ? { matchCount: result.matchCount } : {}),
     };
 }
+function waitEvidenceNodeSnapshot(node, filter) {
+    const relevantState = {
+        ...(filter.checked !== undefined ? { checked: node.state?.checked } : {}),
+        ...(filter.disabled !== undefined ? { disabled: node.state?.disabled } : {}),
+        ...(filter.focused !== undefined ? { focused: node.state?.focused } : {}),
+        ...(filter.selected !== undefined ? { selected: node.state?.selected } : {}),
+        ...(filter.expanded !== undefined ? { expanded: node.state?.expanded } : {}),
+        ...(filter.invalid !== undefined ? { invalid: node.state?.invalid } : {}),
+        ...(filter.required !== undefined ? { required: node.state?.required } : {}),
+        ...(filter.busy !== undefined ? { busy: node.state?.busy } : {}),
+    };
+    return {
+        role: node.role,
+        name: node.name,
+        value: node.value,
+        validation: node.validation,
+        ...(Object.keys(relevantState).length > 0 ? { state: relevantState } : {}),
+    };
+}
+function captureWaitEvidence(root, filter) {
+    const matches = findNodes(root, filter);
+    return {
+        matchCount: matches.length,
+        fingerprints: new Set(matches.map(node => JSON.stringify(waitEvidenceNodeSnapshot(node, filter)))),
+    };
+}
+function waitConditionHasFreshEvidence(before, after, result) {
+    if (!before || !after)
+        return false;
+    const current = captureWaitEvidence(after, result.filter);
+    if (!result.present) {
+        return before.matchCount > 0 && current.matchCount === 0;
+    }
+    if (current.matchCount === 0)
+        return false;
+    if (before.matchCount === 0)
+        return true;
+    return [...current.fingerprints].some(fingerprint => !before.fingerprints.has(fingerprint));
+}
 function inferRevealStepBudget(target, viewport) {
     const verticalSteps = Math.ceil(Math.abs(target.scrollHint.revealDeltaY) / Math.max(1, viewport.height * 0.75));
     const horizontalSteps = Math.ceil(Math.abs(target.scrollHint.revealDeltaX) / Math.max(1, viewport.width * 0.7));
@@ -3396,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 {
@@ -3467,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,
     });
@@ -3486,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;
@@ -3508,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;
@@ -3524,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
@@ -3570,6 +4250,24 @@ 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') {
+        const guidance = ambiguousActionGuidance(wait);
+        return err(detailText(`${summary}\n${guidance}`, {
+            completed: false,
+            outcome: 'unconfirmed',
+            retrySafety: 'inspect-first',
+            guidance,
+            ...compact,
+        }, detail));
+    }
+    return ok(detailText(summary, compact, detail));
+}
 function normalizeLookupKey(value) {
     return value.replace(/\s+/g, ' ').trim().toLowerCase();
 }
@@ -3613,6 +4311,57 @@ function coerceChoiceValue(field, value) {
     const option = field.options?.find(option => normalizeLookupKey(option) === desired);
     return option ?? (value ? 'Yes' : 'No');
 }
+function resolveNativeChoiceValue(field, value) {
+    const options = field.optionDetails;
+    if (!options || options.length === 0)
+        return { ok: true, value };
+    const resolved = (option) => ({
+        ok: true,
+        value: option.value,
+        optionIndex: option.index,
+        expectedReadback: option.label,
+    });
+    const enabled = options.filter(option => !option.disabled);
+    const exactValue = enabled.filter(option => option.value === value);
+    if (exactValue.length > 0)
+        return resolved(exactValue[0]);
+    const lookup = normalizeLookupKey(value);
+    const normalizedValues = enabled.filter(option => normalizeLookupKey(option.value) === lookup);
+    if (normalizedValues.length === 1)
+        return resolved(normalizedValues[0]);
+    if (normalizedValues.length > 1) {
+        const distinct = new Set(normalizedValues.map(option => option.value));
+        if (distinct.size === 1)
+            return resolved(normalizedValues[0]);
+        return {
+            ok: false,
+            error: `Option value "${value}" is ambiguous for field "${field.label}". Use an exact option value from optionDetails.`,
+        };
+    }
+    const labelMatches = enabled.filter(option => normalizeLookupKey(option.label) === lookup);
+    if (labelMatches.length === 1)
+        return resolved(labelMatches[0]);
+    if (labelMatches.length > 1) {
+        const distinctValues = new Set(labelMatches.map(option => option.value));
+        if (distinctValues.size === 1)
+            return resolved(labelMatches[0]);
+        return {
+            ok: false,
+            error: `Option label "${value}" maps to multiple submitted values for field "${field.label}". Use an exact option value from optionDetails.`,
+        };
+    }
+    const disabledMatch = options.some(option => option.disabled && (option.value === value ||
+        normalizeLookupKey(option.value) === lookup ||
+        normalizeLookupKey(option.label) === lookup));
+    if (disabledMatch) {
+        return { ok: false, error: `Option "${value}" is disabled for field "${field.label}".` };
+    }
+    const available = enabled.slice(0, 12).map(option => `${option.label} (${option.value})`);
+    return {
+        ok: false,
+        error: `Unknown option "${value}" for field "${field.label}".${available.length > 0 ? ` Available options: ${available.join(', ')}.` : ''}`,
+    };
+}
 /**
  * Normalize a text value based on field format hints (placeholder, inputType, pattern).
  * Handles common date and phone format conversions.
@@ -3688,28 +4437,69 @@ 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` };
         const normalized = normalizeFieldValue(value, field.format);
-        return [{ kind: 'text', fieldId: field.id, fieldLabel: field.label, value: normalized }];
+        return [{
+                kind: 'text',
+                fieldId: field.id,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+                fieldLabel: field.label,
+                value: normalized,
+            }];
     }
     if (field.kind === 'choice') {
         const coerced = coerceChoiceValue(field, value);
-        if (!coerced)
+        if (coerced === null)
             return { error: `Field "${field.label}" expects a string value` };
+        const resolvedChoice = field.choiceType === 'select'
+            ? resolveNativeChoiceValue(field, coerced)
+            : { ok: true, value: coerced };
+        if (!resolvedChoice.ok)
+            return { error: resolvedChoice.error };
         return [{
                 kind: 'choice',
                 fieldId: field.id,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                 fieldLabel: field.label,
-                value: coerced,
+                value: resolvedChoice.value,
+                ...(resolvedChoice.optionIndex !== undefined ? { optionIndex: resolvedChoice.optionIndex } : {}),
+                ...(resolvedChoice.expectedReadback !== undefined ? { expectedReadback: resolvedChoice.expectedReadback } : {}),
+                ...(field.choiceType === 'select' && field.optionDetails?.length ? { exact: true } : {}),
                 ...(field.choiceType ? { choiceType: field.choiceType } : {}),
             }];
     }
     if (field.kind === 'toggle') {
         if (typeof value !== 'boolean')
             return { error: `Field "${field.label}" expects a boolean value` };
-        return [{ kind: 'toggle', fieldId: field.id, label: field.label, checked: value, controlType: field.controlType }];
+        return [{
+                kind: 'toggle',
+                fieldId: field.id,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+                label: field.label,
+                checked: value,
+                controlType: field.controlType,
+            }];
     }
     const selected = Array.isArray(value) ? value : typeof value === 'string' ? [value] : null;
     if (!selected || selected.length === 0)
@@ -3721,12 +4511,29 @@ function plannedFillInputsForField(field, value) {
     return field.options.map(option => ({
         kind: 'toggle',
         fieldId: field.id,
+        ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
         label: option,
         checked: selectedKeys.has(normalizeLookupKey(option)),
         controlType: 'checkbox',
     }));
 }
-function planFormFill(schema, opts) {
+function unkeyedSchemaFieldIsAmbiguous(field, schemas) {
+    if (field.fieldKey)
+        return false;
+    const matchingIds = new Set();
+    const label = normalizeLookupKey(field.label);
+    for (const schema of schemas) {
+        for (const candidate of schema.fields) {
+            if (normalizeLookupKey(candidate.label) === label)
+                matchingIds.add(candidate.id);
+        }
+    }
+    return matchingIds.size > 1;
+}
+function ambiguousFieldIdentityError(field) {
+    return `Field "${field.label}" has no unique authored identity and shares its label with another control. Geometra refused to guess; refresh the schema or use a contextual recovery action.`;
+}
+function planFormFill(schema, opts, pageSchemas = [schema]) {
     const fieldById = new Map(schema.fields.map(field => [field.id, field]));
     const fieldsByLabel = new Map();
     for (const field of schema.fields) {
@@ -3743,6 +4550,9 @@ function planFormFill(schema, opts) {
         const field = fieldById.get(fieldId);
         if (!field)
             return { ok: false, error: `Unknown form field id ${fieldId}. Refresh geometra_form_schema and try again.` };
+        if (unkeyedSchemaFieldIsAmbiguous(field, pageSchemas)) {
+            return { ok: false, error: ambiguousFieldIdentityError(field) };
+        }
         const next = plannedFillInputsForField(field, value);
         if ('error' in next)
             return { ok: false, error: next.error };
@@ -3758,6 +4568,9 @@ function planFormFill(schema, opts) {
             return { ok: false, error: `Label "${label}" is ambiguous in form ${schema.formId}. Use valuesById for this field.` };
         }
         const field = matches[0];
+        if (unkeyedSchemaFieldIsAmbiguous(field, pageSchemas)) {
+            return { ok: false, error: ambiguousFieldIdentityError(field) };
+        }
         if (seenFieldIds.has(field.id)) {
             return { ok: false, error: `Field "${label}" was provided in both valuesById and valuesByLabel` };
         }
@@ -3780,36 +4593,83 @@ function isResolvedFillFieldInput(field) {
 }
 function resolveFillFieldInputs(session, fields) {
     const unresolved = fields.filter(field => !isResolvedFillFieldInput(field));
-    if (unresolved.length === 0) {
+    const requiresSchemaLookup = fields.some(field => typeof field.fieldId === 'string');
+    const a11y = sessionA11y(session);
+    if (unresolved.length === 0 && !requiresSchemaLookup && !a11y) {
         return { ok: true, fields: fields };
     }
-    const a11y = sessionA11y(session);
-    if (!a11y)
+    if (!a11y) {
         return { ok: false, error: 'No UI tree available to resolve fieldId entries from geometra_form_schema' };
+    }
+    const schemas = buildFormSchemas(a11y, { includeOptions: true, includeContext: 'always' });
     const fieldById = new Map();
-    for (const schema of buildFormSchemas(a11y, { includeOptions: true, includeContext: 'always' })) {
+    for (const schema of schemas) {
         for (const field of schema.fields)
             fieldById.set(field.id, field);
     }
     const resolved = [];
     for (const field of fields) {
         if (isResolvedFillFieldInput(field)) {
-            if (field.kind === 'choice' && field.fieldId && field.choiceType === undefined) {
-                const schemaField = fieldById.get(field.fieldId);
+            const schemaField = field.fieldId ? fieldById.get(field.fieldId) : undefined;
+            if (field.fieldId && !schemaField) {
+                return { ok: false, error: `Unknown form field id ${field.fieldId}. Refresh geometra_form_schema and try again.` };
+            }
+            if (schemaField) {
+                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();
+            for (const candidate of fieldById.values()) {
+                if (normalizeLookupKey(candidate.label) === normalizeLookupKey(suppliedLabel)) {
+                    distinctLabelMatches.set(candidate.id, candidate);
+                }
+            }
+            const effectiveFieldKey = field.fieldKey ?? schemaField?.fieldKey;
+            if (!effectiveFieldKey && distinctLabelMatches.size > 1) {
+                return {
+                    ok: false,
+                    error: schemaField
+                        ? ambiguousFieldIdentityError(schemaField)
+                        : `Field label "${suppliedLabel}" is ambiguous and no exact field identity was supplied. Geometra refused to guess.`,
+                };
+            }
+            if (field.kind === 'choice' && schemaField?.kind === 'choice') {
+                const resolvedChoice = schemaField.choiceType === 'select'
+                    ? resolveNativeChoiceValue(schemaField, field.value)
+                    : { ok: true, value: field.value };
+                if (!resolvedChoice.ok)
+                    return { ok: false, error: resolvedChoice.error };
                 resolved.push({
                     ...field,
-                    ...(schemaField?.kind === 'choice' && schemaField.choiceType ? { choiceType: schemaField.choiceType } : {}),
+                    value: resolvedChoice.value,
+                    ...(resolvedChoice.optionIndex !== undefined ? { optionIndex: resolvedChoice.optionIndex } : {}),
+                    ...(resolvedChoice.expectedReadback !== undefined ? { expectedReadback: resolvedChoice.expectedReadback } : {}),
+                    ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
+                    ...(field.choiceType === undefined && schemaField.choiceType ? { choiceType: schemaField.choiceType } : {}),
+                    ...(schemaField.choiceType === 'select' && schemaField.optionDetails?.length ? { exact: true } : {}),
                 });
             }
-            else if (field.kind === 'toggle' && field.fieldId && field.controlType === undefined) {
-                const schemaField = fieldById.get(field.fieldId);
+            else if (field.kind === 'toggle' && schemaField?.kind === 'toggle') {
                 resolved.push({
                     ...field,
-                    ...(schemaField?.kind === 'toggle' && schemaField.controlType ? { controlType: schemaField.controlType } : {}),
+                    ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
+                    ...(field.controlType === undefined && schemaField.controlType ? { controlType: schemaField.controlType } : {}),
                 });
             }
             else {
-                resolved.push(field);
+                resolved.push({
+                    ...field,
+                    ...(schemaField?.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
+                });
             }
             continue;
         }
@@ -3825,21 +4685,38 @@ function resolveFillFieldInputs(session, fields) {
         if (!schemaField) {
             return { ok: false, error: `Unknown form field id ${field.fieldId}. Refresh geometra_form_schema and try again.` };
         }
+        if (unkeyedSchemaFieldIsAmbiguous(schemaField, schemas)) {
+            return { ok: false, error: ambiguousFieldIdentityError(schemaField) };
+        }
         if (field.kind === 'text') {
             if (schemaField.kind !== 'text') {
                 return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not text.` };
             }
-            resolved.push({ ...field, fieldLabel: schemaField.label });
+            resolved.push({
+                ...field,
+                ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
+                fieldLabel: schemaField.label,
+            });
             continue;
         }
         if (field.kind === 'choice') {
             if (schemaField.kind !== 'choice') {
                 return { ok: false, error: `Field id ${field.fieldId} resolves to kind "${schemaField.kind}", not choice.` };
             }
+            const resolvedChoice = schemaField.choiceType === 'select'
+                ? resolveNativeChoiceValue(schemaField, field.value)
+                : { ok: true, value: field.value };
+            if (!resolvedChoice.ok)
+                return { ok: false, error: resolvedChoice.error };
             resolved.push({
                 ...field,
+                ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
                 fieldLabel: schemaField.label,
+                value: resolvedChoice.value,
+                ...(resolvedChoice.optionIndex !== undefined ? { optionIndex: resolvedChoice.optionIndex } : {}),
+                ...(resolvedChoice.expectedReadback !== undefined ? { expectedReadback: resolvedChoice.expectedReadback } : {}),
                 ...(field.choiceType === undefined && schemaField.choiceType ? { choiceType: schemaField.choiceType } : {}),
+                ...(schemaField.choiceType === 'select' && schemaField.optionDetails?.length ? { exact: true } : {}),
             });
             continue;
         }
@@ -3849,19 +4726,26 @@ function resolveFillFieldInputs(session, fields) {
             }
             resolved.push({
                 ...field,
+                ...(schemaField.fieldKey ? { fieldKey: schemaField.fieldKey } : {}),
                 label: schemaField.label,
                 ...(field.controlType === undefined && schemaField.controlType ? { controlType: schemaField.controlType } : {}),
             });
             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);
@@ -3906,25 +4790,25 @@ function parseProxyFillAckResult(value) {
         ...(invalidFields && invalidFields.length > 0 ? { invalidFields } : {}),
     };
 }
-function directLabelBatchFields(valuesByLabel) {
-    const entries = Object.entries(valuesByLabel ?? {});
-    if (entries.length === 0)
-        return null;
-    const fields = [];
-    for (const [fieldLabel, value] of entries) {
-        if (typeof value !== 'string' && typeof value !== 'boolean')
-            return null;
-        fields.push({ kind: 'auto', fieldLabel, value });
-    }
-    return fields;
-}
 async function tryBatchedResolvedFields(session, fields, detail) {
     let batchAckResult;
     try {
         const startRevision = session.updateRevision;
-        const wait = await sendFillFields(session, fields);
+        const wait = await sendFillFields(session, toProxyFillFields(fields));
+        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,
@@ -3934,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)
@@ -3962,37 +4850,48 @@ 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) {
         case 'text': {
-            const matches = findNodes(a11y, { name: field.fieldLabel, role: 'textbox' });
+            const matches = fieldReadbackNodes(a11y, field.fieldLabel, ['textbox'], field.fieldKey);
             return matches.some(match => normalizeLookupKey(match.value ?? '') === normalizeLookupKey(field.value));
         }
         case 'choice': {
-            const directMatches = [
-                ...findNodes(a11y, { name: field.fieldLabel, role: 'combobox' }),
-                ...findNodes(a11y, { name: field.fieldLabel, role: 'textbox' }),
-                ...findNodes(a11y, { name: field.fieldLabel, role: 'button' }),
-            ];
+            const directMatches = fieldReadbackNodes(a11y, field.fieldLabel, ['combobox', 'textbox', 'button'], field.fieldKey);
             if (directMatches.length === 0)
-                return true;
-            return directMatches.some(match => normalizeLookupKey(match.value ?? '') === normalizeLookupKey(field.value));
+                return field.fieldKey === undefined;
+            if (field.optionIndex !== undefined) {
+                return directMatches.some(match => {
+                    const selected = match.meta?.options?.find(option => option.selected);
+                    return selected
+                        ? selected.index === field.optionIndex && selected.value === field.value
+                        : false;
+                });
+            }
+            const expected = [field.value, field.expectedReadback]
+                .filter((value) => value !== undefined)
+                .map(normalizeLookupKey);
+            return directMatches.some(match => expected.includes(normalizeLookupKey(match.value ?? '')));
         }
         case 'toggle':
             return true;
         case 'file': {
-            const matches = [
-                ...findNodes(a11y, { name: field.fieldLabel, role: 'textbox' }),
-                ...findNodes(a11y, { name: field.fieldLabel, role: 'button' }),
-            ];
-            return matches.length === 0 || matches.some(match => Boolean(match.value && match.value.trim()));
+            const matches = fieldReadbackNodes(a11y, field.fieldLabel, ['textbox', 'button'], field.fieldKey);
+            return field.fieldKey
+                ? matches.some(match => Boolean(match.value && match.value.trim()))
+                : matches.length === 0 || matches.some(match => Boolean(match.value && match.value.trim()));
         }
     }
 }
@@ -4013,6 +4912,55 @@ function canDeferInitialFrameForRunActions(actions) {
         return false;
     return first.type === 'fill_fields';
 }
+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 AmbiguousActionOutcomeError(actionName, wait);
+    }
+}
 async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
@@ -4046,7 +4994,31 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             });
             if (!resolved.ok)
                 throw new Error(clickFallbackErrorMessage(resolved));
+            const waitFilter = action.waitFor ? {
+                id: action.waitFor.id,
+                role: action.waitFor.role,
+                name: action.waitFor.name,
+                text: action.waitFor.text,
+                contextText: action.waitFor.contextText,
+                promptText: action.waitFor.promptText,
+                sectionText: action.waitFor.sectionText,
+                itemText: action.waitFor.itemText,
+                value: action.waitFor.value,
+                checked: action.waitFor.checked,
+                disabled: action.waitFor.disabled,
+                focused: action.waitFor.focused,
+                selected: action.waitFor.selected,
+                expanded: action.waitFor.expanded,
+                invalid: action.waitFor.invalid,
+                required: action.waitFor.required,
+                busy: action.waitFor.busy,
+            } : undefined;
+            const waitEvidenceRoot = sessionA11y(session) ?? before;
+            const beforeWaitEvidence = waitFilter && waitEvidenceRoot
+                ? captureWaitEvidence(waitEvidenceRoot, waitFilter)
+                : undefined;
             const wait = await sendClick(session, resolved.value.x, resolved.value.y, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             const targetSummary = resolved.value.target
                 ? `Clicked ${describeFormattedNode(resolved.value.target)} at (${resolved.value.x}, ${resolved.value.y}).`
                 : `Clicked at (${resolved.value.x}, ${resolved.value.y}).`;
@@ -4054,33 +5026,19 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             let postWaitCompact;
             if (action.waitFor) {
                 const postWait = await waitForSemanticCondition(session, {
-                    filter: {
-                        id: action.waitFor.id,
-                        role: action.waitFor.role,
-                        name: action.waitFor.name,
-                        text: action.waitFor.text,
-                        contextText: action.waitFor.contextText,
-                        promptText: action.waitFor.promptText,
-                        sectionText: action.waitFor.sectionText,
-                        itemText: action.waitFor.itemText,
-                        value: action.waitFor.value,
-                        checked: action.waitFor.checked,
-                        disabled: action.waitFor.disabled,
-                        focused: action.waitFor.focused,
-                        selected: action.waitFor.selected,
-                        expanded: action.waitFor.expanded,
-                        invalid: action.waitFor.invalid,
-                        required: action.waitFor.required,
-                        busy: action.waitFor.busy,
-                    },
+                    filter: waitFilter,
                     present: action.waitFor.present ?? true,
                     timeoutMs: action.waitFor.timeoutMs ?? 10_000,
                 });
                 if (!postWait.ok) {
                     throw new Error(`Post-click wait failed after ${targetSummary.toLowerCase()}\n${postWait.error}`);
                 }
+                const fresh = waitConditionHasFreshEvidence(beforeWaitEvidence, sessionA11y(session), postWait.value);
+                if (!fresh) {
+                    throw new Error(`Post-click wait matched only pre-existing evidence after ${targetSummary.toLowerCase()}; the click outcome is unconfirmed.`);
+                }
                 postWaitSummary = `Post-click ${waitConditionSuccessLine(postWait.value)}`;
-                postWaitCompact = waitConditionCompact(postWait.value);
+                postWaitCompact = { ...waitConditionCompact(postWait.value), fresh: true };
             }
             return {
                 summary: [targetSummary, postActionSummary(session, before, wait, detail), postWaitSummary].filter(Boolean).join('\n'),
@@ -4096,6 +5054,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
         case 'type': {
             const before = sessionA11y(session);
             const wait = await sendType(session, action.text, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             return {
                 summary: `Typed "${action.text}".\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
@@ -4107,6 +5066,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
         case 'key': {
             const before = sessionA11y(session);
             const wait = await sendKey(session, action.key, { shift: action.shift, ctrl: action.ctrl, meta: action.meta, alt: action.alt }, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             return {
                 summary: `Pressed ${formatKeyCombo(action.key, action)}.\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
@@ -4116,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,
@@ -4123,48 +5086,63 @@ 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 {
                 summary: `Uploaded ${action.paths.length} file(s).\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
                     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,
                 query: action.query,
             }, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             const summary = postActionSummary(session, before, wait, detail);
-            const fieldSummary = action.fieldLabel ? summarizeFieldLabelState(session, action.fieldLabel) : undefined;
+            const fieldSummary = action.fieldLabel
+                ? summarizeFieldLabelState(session, action.fieldLabel, action.fieldKey)
+                : undefined;
             return {
                 summary: [`Picked listbox option "${action.label}".`, fieldSummary, summary].filter(Boolean).join('\n'),
                 compact: {
                     label: action.label,
+                    ...(action.fieldId ? { fieldId: action.fieldId } : {}),
+                    ...(action.fieldKey ? { fieldKey: action.fieldKey } : {}),
                     ...(action.fieldLabel ? { fieldLabel: action.fieldLabel } : {}),
                     ...waitStatusPayload(wait),
-                    ...(action.fieldLabel ? { readback: fieldStatePayload(session, action.fieldLabel) } : {}),
+                    ...(action.fieldLabel ? { readback: fieldStatePayload(session, action.fieldLabel, action.fieldKey) } : {}),
                 },
             };
         }
         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,
                 label: action.label,
                 index: action.index,
             }, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             return {
                 summary: `Selected option.\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
@@ -4182,13 +5160,20 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 checked: action.checked,
                 exact: action.exact,
                 controlType: action.controlType,
+                ...(action.fieldKey ? { fieldKey: action.fieldKey } : {}),
+                contextText: action.contextText,
+                sectionText: action.sectionText,
             }, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             return {
                 summary: `Set ${action.controlType ?? 'checkbox/radio'} "${action.label}" to ${String(action.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
                     label: action.label,
                     checked: action.checked ?? true,
                     ...(action.controlType ? { controlType: action.controlType } : {}),
+                    ...(action.fieldKey ? { fieldKey: action.fieldKey } : {}),
+                    ...(action.contextText ? { contextText: action.contextText } : {}),
+                    ...(action.sectionText ? { sectionText: action.sectionText } : {}),
                     ...waitStatusPayload(wait),
                 },
             };
@@ -4200,6 +5185,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 x: action.x,
                 y: action.y,
             }, action.timeoutMs);
+            assertBatchActionConfirmed(action.type, wait);
             return {
                 summary: `Wheel delta (${action.deltaX ?? 0}, ${action.deltaY}).\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
@@ -4289,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: {
@@ -4378,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;
 }
@@ -4458,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 = [];
@@ -4468,13 +5454,27 @@ function verifyFormFills(session, planned) {
         if (p.field.kind === 'toggle' || p.field.kind === 'file')
             continue;
         const label = p.field.fieldLabel;
-        const expected = p.field.kind === 'text' ? p.field.value : p.field.value;
-        const matches = [
-            ...findNodes(a11y, { name: label, role: 'textbox' }),
-            ...findNodes(a11y, { name: label, role: 'combobox' }),
-        ];
+        const expected = p.field.kind === 'choice'
+            ? p.field.expectedReadback ?? p.field.value
+            : p.field.value;
+        const matches = fieldReadbackNodes(a11y, label, ['textbox', 'combobox'], p.field.fieldKey);
         const match = matches[0];
         const actual = match?.value?.trim();
+        if (p.field.kind === 'choice' && p.field.optionIndex !== undefined && match?.meta?.options) {
+            const selected = match.meta.options.find(option => option.selected);
+            if (selected?.index === p.field.optionIndex && selected.value === p.field.value) {
+                verified++;
+            }
+            else {
+                mismatches.push({
+                    fieldLabel: label,
+                    expected,
+                    actual: selected?.label ?? actual,
+                    ...(p.field.fieldId ? { fieldId: p.field.fieldId } : {}),
+                });
+            }
+            continue;
+        }
         if (!actual || !expected) {
             mismatches.push({ fieldLabel: label, expected, actual, ...(p.field.fieldId ? { fieldId: p.field.fieldId } : {}) });
         }
@@ -4494,10 +5494,12 @@ async function executeFillField(session, field, detail) {
             const wait = await sendFieldText(session, field.fieldLabel, field.value, {
                 exact: field.exact,
                 fieldId: field.fieldId,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                 typingDelayMs: field.typingDelayMs,
                 imeFriendly: field.imeFriendly,
             }, field.timeoutMs);
-            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            assertActionWaitConfirmed(`Text fill for "${field.fieldLabel}"`, wait);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel, field.fieldKey);
             return {
                 summary: [
                     `Filled text field "${field.fieldLabel}".`,
@@ -4506,17 +5508,26 @@ async function executeFillField(session, field, detail) {
                 ].filter(Boolean).join('\n'),
                 compact: {
                     ...(field.fieldId ? { fieldId: field.fieldId } : {}),
+                    ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                     fieldLabel: field.fieldLabel,
                     ...compactTextValue(field.value),
                     ...waitStatusPayload(wait),
-                    readback: fieldStatePayload(session, field.fieldLabel),
+                    readback: fieldStatePayload(session, field.fieldLabel, field.fieldKey),
                 },
             };
         }
         case 'choice': {
             const before = sessionA11y(session);
-            const wait = await sendFieldChoice(session, field.fieldLabel, field.value, { exact: field.exact, query: field.query, choiceType: field.choiceType, fieldId: field.fieldId }, field.timeoutMs);
-            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            const wait = await sendFieldChoice(session, field.fieldLabel, field.value, {
+                exact: field.exact,
+                query: field.query,
+                choiceType: field.choiceType,
+                fieldId: field.fieldId,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+                ...(field.optionIndex !== undefined ? { optionIndex: field.optionIndex } : {}),
+            }, field.timeoutMs);
+            assertActionWaitConfirmed(`Choice fill for "${field.fieldLabel}"`, wait);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel, field.fieldKey);
             return {
                 summary: [
                     `Set choice field "${field.fieldLabel}" to "${field.value}".`,
@@ -4525,21 +5536,31 @@ async function executeFillField(session, field, detail) {
                 ].filter(Boolean).join('\n'),
                 compact: {
                     ...(field.fieldId ? { fieldId: field.fieldId } : {}),
+                    ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                     fieldLabel: field.fieldLabel,
                     value: field.value,
+                    ...(field.optionIndex !== undefined ? { optionIndex: field.optionIndex } : {}),
                     ...(field.choiceType ? { choiceType: field.choiceType } : {}),
                     ...waitStatusPayload(wait),
-                    readback: fieldStatePayload(session, field.fieldLabel),
+                    readback: fieldStatePayload(session, field.fieldLabel, field.fieldKey),
                 },
             };
         }
         case 'toggle': {
             const before = sessionA11y(session);
-            const wait = await sendSetChecked(session, field.label, { checked: field.checked, exact: field.exact, controlType: field.controlType }, field.timeoutMs);
+            const wait = await sendSetChecked(session, field.label, {
+                checked: field.checked,
+                exact: field.exact,
+                controlType: field.controlType,
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+            }, field.timeoutMs);
+            assertActionWaitConfirmed(`Toggle fill for "${field.label}"`, wait);
             return {
                 summary: `Set ${field.controlType ?? 'checkbox/radio'} "${field.label}" to ${String(field.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`,
                 compact: {
                     label: field.label,
+                    ...(field.fieldId ? { fieldId: field.fieldId } : {}),
+                    ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                     checked: field.checked ?? true,
                     ...(field.controlType ? { controlType: field.controlType } : {}),
                     ...waitStatusPayload(wait),
@@ -4548,8 +5569,14 @@ async function executeFillField(session, field, detail) {
         }
         case 'file': {
             const before = sessionA11y(session);
-            const wait = await sendFileUpload(session, field.paths, { fieldLabel: field.fieldLabel, exact: field.exact }, field.timeoutMs ?? 8_000);
-            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
+            const wait = await sendFileUpload(session, field.paths, {
+                ...(field.fieldId ? { fieldId: field.fieldId } : {}),
+                ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
+                fieldLabel: field.fieldLabel,
+                exact: field.exact,
+            }, field.timeoutMs ?? 8_000);
+            assertActionWaitConfirmed(`File fill for "${field.fieldLabel}"`, wait);
+            const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel, field.fieldKey);
             return {
                 summary: [
                     `Uploaded ${field.paths.length} file(s) to "${field.fieldLabel}".`,
@@ -4558,9 +5585,11 @@ async function executeFillField(session, field, detail) {
                 ].filter(Boolean).join('\n'),
                 compact: {
                     fieldLabel: field.fieldLabel,
+                    ...(field.fieldId ? { fieldId: field.fieldId } : {}),
+                    ...(field.fieldKey ? { fieldKey: field.fieldKey } : {}),
                     fileCount: field.paths.length,
                     ...waitStatusPayload(wait),
-                    readback: fieldStatePayload(session, field.fieldLabel),
+                    readback: fieldStatePayload(session, field.fieldLabel, field.fieldKey),
                 },
             };
         }
@@ -4579,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);
@@ -4726,8 +5757,8 @@ export function findNodes(node, filter) {
     walk(node);
     return matches;
 }
-function summarizeFieldLabelState(session, fieldLabel) {
-    const payload = fieldStatePayload(session, fieldLabel);
+function summarizeFieldLabelState(session, fieldLabel, fieldKey) {
+    const payload = fieldStatePayload(session, fieldLabel, fieldKey);
     if (!payload)
         return undefined;
     const parts = [`Field "${fieldLabel}"`];