@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/plugins/browser-macos-bridge.ts

@@ -1,12 +1,14 @@
 import { execFile } from 'child_process';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { basename, extname } from 'path';
 import {
   callBrowserAutomationBroker,
   captureBrowserAutomationRegion,
   type BrowserAutomationBrokerAction,
+  type BrowserAutomationSemanticTargetProof,
   type BrowserAutomationTrustedInput,
+  type BrowserAutomationTrustedInputRequest,
 } from './browser-automation-service';
 import { AssistantPluginError } from './errors';
 import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from '../../../packages/protocols/browser/index';
@@ -14,6 +16,7 @@ import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from '../../../
 const RECORD_SEPARATOR = String.fromCharCode(30);
 const DEFAULT_NATIVE_TIMEOUT_MS = 5_000;
 const MAX_NATIVE_OUTPUT_BYTES = 1_048_576;
+const MAX_NATIVE_BROWSER_FILE_ATTACH_BYTES = 16 * 1024 * 1024;
 
 export type MacOsBrowserProduct = BrowserNativeProduct;
 
@@ -64,6 +67,8 @@ export interface MacOsBrowserTabInventoryEntry {
   url: string;
   title: string;
   active: boolean;
+  /** True when this tab is active in the frontmost browser window. */
+  frontmost?: boolean;
 }
 
 export interface MacOsBrowserTabInventory {
@@ -119,7 +124,7 @@ function execFileText(file: string, args: string[], timeoutMs: number): Promise<
     }, (error, stdout, stderr) => {
       if (error) {
         const diagnostic = String(stderr || error.message).trim().slice(-2_000);
-        reject(new Error(diagnostic || error.message));
+        reject(new Error(diagnostic || error.message, { cause: error }));
         return;
       }
       resolve(String(stdout).trim());
@@ -132,10 +137,16 @@ const defaultRuntimeHooks: MacOsBrowserRuntimeHooks = {
   appExists: (path) => existsSync(path),
   processRunning: async (processName, timeoutMs) => {
     try {
+      // Process existence only: the canonical Computer provider owns exact
+      // GUI PID selection and rejects ambiguous or unverified targets.
       await execFileText('/usr/bin/pgrep', ['-x', processName], timeoutMs);
       return true;
-    } catch {
-      return false;
+    } catch (error) {
+      // pgrep's no-match exit is absence; timeout/permission/transport failure
+      // cannot prove that an application's tabs are absent.
+      const cause = error instanceof Error ? error.cause : undefined;
+      if (cause && typeof cause === 'object' && 'code' in cause && cause.code === 1) return false;
+      throw error;
     }
   },
 };
@@ -214,6 +225,7 @@ async function runCreateTabAutomation(
   testArgs: string[],
   timeoutMs: number,
 ): Promise<MacOsBrowserCreateTabEvidence> {
+  await assertMacOsBrowserApplicationRunning(request.product, timeoutMs);
   if (runtimeHooks.runAppleScript) {
     const value = await runtimeHooks.runAppleScript(testScript, testArgs, timeoutMs);
     return parseMacOsBrowserCreateTabBrokerResult({ value });
@@ -227,6 +239,12 @@ async function runBrowserAutomationText(
   testArgs: string[],
   timeoutMs: number,
 ): Promise<string> {
+  // AppleScript `tell application` starts an application that is not already
+  // running while it compiles the script. Every browser entry point therefore
+  // fails closed unless the exact browser process is already live, so routine
+  // inventory/reconcile work can never launch the user's browser or hand Forge
+  // an unauthenticated profile.
+  if ('product' in request) await assertMacOsBrowserApplicationRunning(request.product, timeoutMs);
   if (runtimeHooks.runAppleScript) return await runtimeHooks.runAppleScript(testScript, testArgs, timeoutMs);
   const result = await callBrowserAutomationBroker(request, timeoutMs);
   if (typeof result.value !== 'string') {
@@ -239,6 +257,76 @@ async function runBrowserAutomationText(
   return result.value;
 }
 
+/**
+ * Non-launching precondition for every Apple Events browser operation.
+ * Path existence is checked without scripting the application, and process
+ * liveness comes from the process table, so neither probe can start a browser.
+ */
+export async function assertMacOsBrowserApplicationRunning(
+  product: MacOsBrowserProduct,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<void> {
+  const browser = browserDefinition(product);
+  const details = { browserProduct: product, bundleId: browser.bundleId, appName: browser.appName };
+  if (runtimeHooks.platform !== 'darwin') {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_APP_UNSUPPORTED_PLATFORM',
+      `Native ${browser.appName} Apple Events are unavailable on ${runtimeHooks.platform}.`,
+      { retryable: false, details },
+    );
+  }
+  if (!browser.appPaths.some((path) => runtimeHooks.appExists(path))) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_APP_NOT_INSTALLED',
+      `${browser.appName} is not installed; Forge never installs or substitutes a browser application.`,
+      { retryable: false, details },
+    );
+  }
+  if (!(await runtimeHooks.processRunning(browser.processName, timeoutMs))) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_APP_NOT_RUNNING',
+      `${browser.appName} is not running; Forge never launches a browser application implicitly.`,
+      { retryable: true, details },
+    );
+  }
+}
+
+/**
+ * Start only the browser family already chosen by the Computer target. This
+ * is deliberately narrower than a generic browser launch: it never guesses a
+ * product, profile, or authentication identity. The caller must have a
+ * durable preferred product and must still verify the resulting ChatGPT page
+ * before any provider mutation.
+ */
+export async function ensureMacOsBrowserApplicationRunning(
+  product: MacOsBrowserProduct,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<void> {
+  const browser = browserDefinition(product);
+  if (runtimeHooks.platform !== 'darwin') throw new AssistantPluginError(
+    'PLUGIN_BROWSER_NATIVE_APP_UNSUPPORTED_PLATFORM',
+    `Native ${browser.appName} Apple Events are unavailable on ${runtimeHooks.platform}.`,
+    { retryable: false, details: { browserProduct: product } },
+  );
+  if (!browser.appPaths.some((path) => runtimeHooks.appExists(path))) throw new AssistantPluginError(
+    'PLUGIN_BROWSER_NATIVE_APP_NOT_INSTALLED',
+    `${browser.appName} is not installed.`,
+    { retryable: false, details: { browserProduct: product } },
+  );
+  if (await runtimeHooks.processRunning(browser.processName, timeoutMs)) return;
+  await execFileText('/usr/bin/open', ['-a', browser.appName], timeoutMs);
+  const deadline = Date.now() + Math.max(1_000, timeoutMs);
+  while (Date.now() < deadline) {
+    if (await runtimeHooks.processRunning(browser.processName, Math.min(1_000, timeoutMs))) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new AssistantPluginError(
+    'PLUGIN_BROWSER_NATIVE_APP_START_TIMEOUT',
+    `${browser.appName} did not become available after Forge started the remembered browser family.`,
+    { retryable: true, details: { browserProduct: product } },
+  );
+}
+
 async function captureBrowserAutomation(
   region: { x: number; y: number; width: number; height: number },
   path: string,
@@ -251,9 +339,10 @@ async function captureBrowserAutomation(
 }
 
 async function sendBrowserTrustedInput(
-  request: Extract<BrowserAutomationBrokerAction, { action: 'trusted_input' }>,
+  request: BrowserAutomationTrustedInputRequest,
   timeoutMs: number,
 ): Promise<void> {
+  await assertMacOsBrowserApplicationRunning(request.product, timeoutMs);
   if (runtimeHooks.trustedInput) {
     await runtimeHooks.trustedInput(request, timeoutMs);
     return;
@@ -405,6 +494,8 @@ set maxTabs to 256
 set returnedCount to 0
 set truncatedInventory to false
 set outputText to "false"
+set frontWindowId to ""
+if (count of windows) is greater than 0 then set frontWindowId to ((id of front window) as text)
 repeat with candidateWindow in windows
   set activeTabId to ""
   try
@@ -417,10 +508,11 @@ repeat with candidateWindow in windows
     end if
     set candidateWindowId to ((id of candidateWindow) as text)
     set candidateTabId to ((id of candidateTab) as text)
+    set candidateFrontmost to (candidateWindowId is frontWindowId)
     set candidateURL to my cleanField((URL of candidateTab as text), recordSeparator, fieldSeparator)
     set candidateTitle to my cleanField((title of candidateTab as text), recordSeparator, fieldSeparator)
     set candidateActive to (candidateTabId is activeTabId)
-    set outputText to outputText & recordSeparator & candidateWindowId & fieldSeparator & candidateTabId & fieldSeparator & (candidateActive as text) & fieldSeparator & candidateURL & fieldSeparator & candidateTitle
+    set outputText to outputText & recordSeparator & candidateWindowId & fieldSeparator & candidateTabId & fieldSeparator & (candidateActive as text) & fieldSeparator & (candidateFrontmost as text) & fieldSeparator & candidateURL & fieldSeparator & candidateTitle
     set returnedCount to returnedCount + 1
   end repeat
   if truncatedInventory then exit repeat
@@ -458,14 +550,23 @@ function parseTabInventory(product: MacOsBrowserProduct, raw: string): MacOsBrow
     const windowId = (fields[0] ?? '').trim();
     const tabId = (fields[1] ?? '').trim();
     const activeText = (fields[2] ?? '').trim().toLowerCase();
-    if (!windowId || !tabId || (activeText !== 'true' && activeText !== 'false')) {
+    const hasFrontmostField = fields.length >= 6 && ['true', 'false'].includes((fields[3] ?? '').trim().toLowerCase());
+    const frontmostText = hasFrontmostField ? (fields[3] ?? '').trim().toLowerCase() : undefined;
+    if (!windowId || !tabId || (activeText !== 'true' && activeText !== 'false') || (fields.length >= 6 && !hasFrontmostField)) {
       throw new AssistantPluginError(
         'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
         'Stable Forge macOS capability broker returned invalid browser tab inventory metadata.',
         { retryable: true },
       );
     }
-    tabs.push({ windowId, tabId, active: activeText === 'true', url: fields[3] ?? '', title: fields.slice(4).join(fieldSeparator) });
+    tabs.push({
+      windowId,
+      tabId,
+      active: activeText === 'true',
+      ...(frontmostText ? { frontmost: frontmostText === 'true' } : {}),
+      url: fields[hasFrontmostField ? 4 : 3] ?? '',
+      title: fields.slice(hasFrontmostField ? 5 : 4).join(fieldSeparator),
+    });
     if (tabs.length > 256) {
       throw new AssistantPluginError(
         'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
@@ -507,30 +608,78 @@ return (frontmost as text) & separator & (URL of targetTab as text) & separator
 function activateTargetTabScript(browser: MacOsBrowserDefinition, ref: MacOsBrowserTabRef): string {
   return browserTellScript(browser, `
 ${targetTabPreamble(ref)}
-set targetTabIndex to 1
-repeat with candidateTab in tabs of targetWindow
-  if ((id of candidateTab) as text) is ((id of targetTab) as text) then exit repeat
-  set targetTabIndex to targetTabIndex + 1
+-- Activating by position is only safe inside the same enumeration that produced
+-- the index. A tab created or closed by the provider between those two steps
+-- makes the positional write fail with -1719 ("Can't get item N of every tab"),
+-- so each attempt re-reads the tab list, bounds the index and verifies the exact
+-- tab became active before it is reported as done.
+set targetTabIdText to ((id of targetTab) as text)
+set activationConfirmed to false
+repeat 3 times
+  set targetTabIndex to 0
+  set candidateIndex to 0
+  repeat with candidateTab in tabs of targetWindow
+    set candidateIndex to candidateIndex + 1
+    if ((id of candidateTab) as text) is targetTabIdText then set targetTabIndex to candidateIndex
+  end repeat
+  if targetTabIndex is greater than 0 then
+    try
+      if targetTabIndex is less than or equal to (count of tabs of targetWindow) then
+        set active tab index of targetWindow to targetTabIndex
+        if ((id of active tab of targetWindow) as text) is targetTabIdText then set activationConfirmed to true
+      end if
+    end try
+  end if
+  if activationConfirmed then exit repeat
+  delay 0.05
 end repeat
-set active tab index of targetWindow to targetTabIndex
 set index of targetWindow to 1
 activate
 `);
 }
 
-function createOwnedTabScript(browser: MacOsBrowserDefinition): string {
+function createOwnedTabScript(browser: MacOsBrowserDefinition, preferredWindowId?: string): string {
   return `on run argv
 set targetUrl to item 1 of argv
 ${browserTellScript(browser, `
-if (count of windows) is 0 then
+set preferredWindowId to "${preferredWindowId ?? ''}"
+set targetWindow to missing value
+if preferredWindowId is not "" then
+  repeat with candidateWindow in windows
+    if ((id of candidateWindow) as text) is preferredWindowId then
+      set targetWindow to candidateWindow
+      exit repeat
+    end if
+  end repeat
+end if
+if preferredWindowId is not "" and targetWindow is missing value then error "FORGE_BROWSER_PREFERRED_WINDOW_MISSING:" & preferredWindowId
+if targetWindow is missing value and (count of windows) is greater than 0 then set targetWindow to front window
+if targetWindow is missing value then
   set targetWindow to make new window
   set targetTab to active tab of targetWindow
   set URL of targetTab to targetUrl
 else
-  set targetWindow to front window
-  set originalActiveIndex to active tab index of targetWindow
+  -- Preserve the selected background window; front-window reassignment here
+  -- previously discarded the caller's stable target and opened the wrong tab.
+  set originalActiveTabId to ((id of active tab of targetWindow) as text)
   set targetTab to make new tab at end of tabs of targetWindow with properties {URL:targetUrl}
-  set active tab index of targetWindow to originalActiveIndex
+  -- Restore the previously active tab by identity, never by a stale position:
+  -- the new tab can shift Chrome's tab order and make a pre-create index invalid.
+  repeat 3 times
+    if ((id of active tab of targetWindow) as text) is originalActiveTabId then exit repeat
+    set restoreIndex to 0
+    set candidateIndex to 0
+    repeat with candidateTab in tabs of targetWindow
+      set candidateIndex to candidateIndex + 1
+      if ((id of candidateTab) as text) is originalActiveTabId then set restoreIndex to candidateIndex
+    end repeat
+    if restoreIndex is 0 then exit repeat
+    try
+      if restoreIndex is less than or equal to (count of tabs of targetWindow) then set active tab index of targetWindow to restoreIndex
+    end try
+    if ((id of active tab of targetWindow) as text) is originalActiveTabId then exit repeat
+    delay 0.05
+  end repeat
 end if
 set targetTabId to id of targetTab
 set separator to ASCII character 30
@@ -804,8 +953,25 @@ export class MacOsAppleEventsPage {
       return await runBrowserAutomationText(effectiveRequest, effectiveScript, args, timeoutMs);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_OPERATION_FAILED', `${this.browser.appName} Apple Events operation failed: ${message}`, {
-        retryable: true,
+      // Preserve the provider's *typed* process-identity refusal. In particular,
+      // do not turn ambiguous Chrome app roots into a retryable generic error:
+      // retries must never guess another user's running browser instance.
+      const nativeCode = error instanceof AssistantPluginError ? error.code : undefined;
+      const nativeFailure = nativeCode === 'BROWSER_AUTOMATION_PROCESS_TARGET_AMBIGUOUS'
+        || nativeCode === 'BROWSER_AUTOMATION_PROCESS_IDENTITY_LOST'
+        || nativeCode === 'BROWSER_AUTOMATION_PROCESS_PROBE_UNAVAILABLE'
+        || nativeCode === 'BROWSER_AUTOMATION_NATIVE_EVENT_FAILED'
+        || nativeCode === 'BROWSER_AUTOMATION_MUTATION_OUTCOME_UNKNOWN'
+        ? nativeCode : undefined;
+      const nonRetryable = nativeFailure && nativeFailure !== 'BROWSER_AUTOMATION_PROCESS_PROBE_UNAVAILABLE';
+      // An Apple Event can mutate the page even if its callback fails.
+      // Preserve uncertainty and never retry such a mutation blindly.
+      const outcomeUnknown = nativeFailure === 'BROWSER_AUTOMATION_MUTATION_OUTCOME_UNKNOWN'
+        || (error instanceof AssistantPluginError && error.effectOutcome === 'outcome_unknown');
+      const brokerFailure = nativeFailure ?? /\b(BROWSER_AUTOMATION_TIMEOUT|BROWSER_AUTOMATION_SERIALIZATION_BUSY)\b/.exec(message)?.[1];
+      throw new AssistantPluginError(brokerFailure ?? 'PLUGIN_BROWSER_NATIVE_OPERATION_FAILED', `${this.browser.appName} Apple Events operation failed: ${message}`, {
+        retryable: !nonRetryable && !outcomeUnknown,
+        effectOutcome: outcomeUnknown ? 'outcome_unknown' : 'failed',
         details: { browserProduct: this.browser.product, bundleId: this.browser.bundleId },
       });
     }
@@ -834,8 +1000,12 @@ export class MacOsAppleEventsPage {
       if (macOsBrowserJavaScriptAutomationDisabled(error)) {
         throw new AssistantPluginError(
           'PLUGIN_BROWSER_JAVASCRIPT_PERMISSION_REQUIRED',
-          `${this.browser.appName} allows tab/window automation, but DOM actions require Settings > Privacy > Apple Events > Allow JavaScript from Apple Events.`,
-          { retryable: false, details: { browserProduct: this.browser.product, bundleId: this.browser.bundleId } },
+          `${this.browser.appName} rejected JavaScript from Apple Events for the browser instance addressed by macOS automation. This does not prove that the user's visible Chrome instance has this setting disabled. Verify the exact Chrome process/profile and View > Developer > Allow JavaScript from Apple Events before changing settings.`,
+          { retryable: false, details: {
+            browserProduct: this.browser.product, bundleId: this.browser.bundleId,
+            processIdentity: 'unverified',
+            ...(this.targetRef ? { windowId: this.targetRef.windowId, tabId: this.targetRef.tabId } : {}),
+          } },
         );
       }
       throw error;
@@ -973,15 +1143,16 @@ export class MacOsAppleEventsPage {
     if (filePaths.length === 0 || filePaths.length > 32) {
       throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Native browser file input accepts 1-32 local files.', { retryable: false });
     }
-    for (const filePath of filePaths) {
+
+    // Validate the entire batch before sending bytes or changing input.files.
+    const attachments = filePaths.map((filePath) => {
       if (!filePath || !existsSync(filePath)) {
         throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Local file does not exist.', { retryable: false });
       }
-    }
-
-    if (filePaths.length === 1) {
-      const filePath = filePaths[0];
-      const bytes = readFileSync(filePath);
+      const metadata = statSync(filePath);
+      if (!metadata.isFile()) {
+        throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Native browser can attach only regular files.', { retryable: false });
+      }
       const fileName = basename(filePath);
       const extension = extname(fileName).toLowerCase();
       const mimeType = extension === '.pdf' ? 'application/pdf'
@@ -989,123 +1160,98 @@ export class MacOsAppleEventsPage {
         : extension === '.png' ? 'image/png'
         : extension === '.jpg' || extension === '.jpeg' ? 'image/jpeg'
         : 'application/octet-stream';
-      const bufferKey = `__forgeLocalFile_${Date.now()}_${Math.random().toString(16).slice(2)}`;
-      const encoded = bytes.toString('base64');
-      const chunkChars = 192 * 1024;
-      try {
+      return { filePath, fileName, size: metadata.size, mimeType };
+    });
+    const totalBytes = attachments.reduce((sum, attachment) => sum + attachment.size, 0);
+    if (totalBytes > MAX_NATIVE_BROWSER_FILE_ATTACH_BYTES) {
+      throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_TOO_LARGE',
+        'Native browser upload is bounded to 16 MiB per batch; select a smaller batch instead of queuing unbounded Apple Events.',
+        { retryable: false, details: { totalBytes, limitBytes: MAX_NATIVE_BROWSER_FILE_ATTACH_BYTES } });
+    }
+
+    // A read-only DOM preflight must pass before staging starts. In particular,
+    // multi-file uploads cannot reset a previous file selection on preflight failure.
+    await this.evaluate(`(() => { // __forgeFileInputPreflight
+      const matches = document.querySelectorAll(${JSON.stringify(selector)});
+      if (matches.length !== 1) throw new Error('File input selector must resolve to exactly one element.');
+      const element = matches[0];
+      if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
+      if (element.disabled) throw new Error('Target file input is disabled.');
+      if (${attachments.length > 1} && !element.multiple) throw new Error('Target input does not allow multiple files.');
+      return true;
+    })()`);
+
+    const batchKey = `__forgeStagedFiles_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+    const bufferKey = `__forgeEncodedFile_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+    const expected = attachments.map(({ fileName, size }) => ({ name: fileName, size }));
+    const chunkChars = 192 * 1024;
+    try {
+      for (const attachment of attachments) {
+        // Stage one file at a time. No DOM selection or change event occurs
+        // until the complete batch has arrived and its sizes have been checked.
+        const encoded = readFileSync(attachment.filePath).toString('base64');
         await this.evaluate(`(() => { globalThis[${JSON.stringify(bufferKey)}] = ''; return true; })()`);
         for (let offset = 0; offset < encoded.length; offset += chunkChars) {
           const chunk = encoded.slice(offset, offset + chunkChars);
           await this.evaluate(`(() => { globalThis[${JSON.stringify(bufferKey)}] += ${JSON.stringify(chunk)}; return true; })()`);
         }
-        const attached = await this.evaluate<{ name?: string; size?: number }>(`(() => {
-          const element = document.querySelector(${JSON.stringify(selector)});
-          if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
-          const expectedName = ${JSON.stringify(fileName)};
-          const expectedSize = ${bytes.length};
+        const staged = await this.evaluate<{ name?: string; size?: number }>(`(() => { // __forgeFileInputStaged
           const encoded = String(globalThis[${JSON.stringify(bufferKey)}] || '');
           const binary = atob(encoded);
           const data = new Uint8Array(binary.length);
           for (let i = 0; i < binary.length; i += 1) data[i] = binary.charCodeAt(i);
-          const file = new File([data], expectedName, { type: ${JSON.stringify(mimeType)} });
-          const transfer = new DataTransfer();
-          transfer.items.add(file);
-          element.files = transfer.files;
-          element.dispatchEvent(new Event('input', { bubbles: true }));
-          element.dispatchEvent(new Event('change', { bubbles: true }));
-          const selected = element.files && element.files[0];
-          return selected ? { name: selected.name, size: selected.size, expectedName, expectedSize } : null;
+          const file = new File([data], ${JSON.stringify(attachment.fileName)}, { type: ${JSON.stringify(attachment.mimeType)} });
+          const staged = globalThis[${JSON.stringify(batchKey)}] || [];
+          staged.push(file);
+          globalThis[${JSON.stringify(batchKey)}] = staged;
+          delete globalThis[${JSON.stringify(bufferKey)}];
+          return { name: file.name, size: file.size };
         })()`);
-        if (attached?.name !== fileName || attached?.size !== bytes.length) {
-          throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED', 'Native browser did not retain the requested local file on the target input.', {
-            retryable: true,
-            details: { expectedName: fileName, expectedSize: bytes.length, actualName: attached?.name, actualSize: attached?.size },
-          });
+        if (staged?.name !== attachment.fileName || staged?.size !== attachment.size) {
+          throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED',
+            'Browser did not stage the expected local file.', { retryable: false });
         }
-      } finally {
-        await this.evaluate(`(() => { try { delete globalThis[${JSON.stringify(bufferKey)}]; } catch {} return true; })()`).catch(() => undefined);
       }
-      return;
-    }
 
-    const attachments = filePaths.map((filePath) => {
-      const bytes = readFileSync(filePath);
-      const fileName = basename(filePath);
-      const extension = extname(fileName).toLowerCase();
-      const mimeType = extension === '.pdf' ? 'application/pdf'
-        : extension === '.zip' ? 'application/zip'
-        : extension === '.png' ? 'image/png'
-        : extension === '.jpg' || extension === '.jpeg' ? 'image/jpeg'
-        : 'application/octet-stream';
-      return {
-        bytes,
-        fileName,
-        mimeType,
-        bufferKey: `__forgeLocalFile_${Date.now()}_${Math.random().toString(16).slice(2)}`,
-      };
-    });
-
-    if (attachments.length > 1) {
-      await this.evaluate(`(() => {
-        const element = document.querySelector(${JSON.stringify(selector)});
-        if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
-        if (!element.multiple) throw new Error('Target input does not allow multiple files.');
+      // One commit to input.files and one event pair, after all File objects
+      // are staged and verified. Failed transfer never partially selects files.
+      const selected = await this.evaluate<Array<{ name?: string; size?: number }>>(`(() => { // __forgeFileInputCommit
+        const matches = document.querySelectorAll(${JSON.stringify(selector)});
+        if (matches.length !== 1) throw new Error('File input selector changed during transfer.');
+        const element = matches[0];
+        if (!(element instanceof HTMLInputElement) || element.type !== 'file' || element.disabled) {
+          throw new Error('File input became unavailable during transfer.');
+        }
+        if (${attachments.length > 1} && !element.multiple) throw new Error('File input no longer supports multiple files.');
+        const staged = globalThis[${JSON.stringify(batchKey)}];
+        const expected = ${JSON.stringify(expected)};
+        if (!Array.isArray(staged) || staged.length !== expected.length ||
+            !staged.every((file, i) => file instanceof File && file.name === expected[i].name && file.size === expected[i].size)) {
+          throw new Error('Staged file batch does not match the requested selection.');
+        }
         const transfer = new DataTransfer();
+        staged.forEach((file) => transfer.items.add(file));
         element.files = transfer.files;
-        return true;
-      })()`);
-    }
-
-    const chunkChars = 192 * 1024;
-    try {
-      for (let index = 0; index < attachments.length; index += 1) {
-        const attachment = attachments[index];
-        const encoded = attachment.bytes.toString('base64');
-        await this.evaluate(`(() => { globalThis[${JSON.stringify(attachment.bufferKey)}] = ''; return true; })()`);
-        for (let offset = 0; offset < encoded.length; offset += chunkChars) {
-          const chunk = encoded.slice(offset, offset + chunkChars);
-          await this.evaluate(`(() => { globalThis[${JSON.stringify(attachment.bufferKey)}] += ${JSON.stringify(chunk)}; return true; })()`);
+        const selected = Array.from(element.files || []).map((file) => ({ name: file.name, size: file.size }));
+        if (selected.length !== expected.length ||
+            !selected.every((file, i) => file.name === expected[i].name && file.size === expected[i].size)) {
+          throw new Error('Browser did not retain the requested file selection.');
         }
-        const append = attachments.length > 1 && index > 0;
-        await this.evaluate(`(() => {
-          const element = document.querySelector(${JSON.stringify(selector)});
-          if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
-          const expectedName = ${JSON.stringify(attachment.fileName)};
-          const expectedSize = ${attachment.bytes.length};
-          const encoded = String(globalThis[${JSON.stringify(attachment.bufferKey)}] || '');
-          const binary = atob(encoded);
-          const data = new Uint8Array(binary.length);
-          for (let i = 0; i < binary.length; i += 1) data[i] = binary.charCodeAt(i);
-          const file = new File([data], expectedName, { type: ${JSON.stringify(attachment.mimeType)} });
-          const transfer = new DataTransfer();
-          if (${append ? 'true' : 'false'}) {
-            for (const existing of Array.from(element.files || [])) transfer.items.add(existing);
-          }
-          transfer.items.add(file);
-          element.files = transfer.files;
-          return Array.from(element.files || []).map((selected) => ({ name: selected.name, size: selected.size }));
-        })()`);
-      }
-
-      const selected = await this.evaluate<Array<{ name?: string; size?: number }>>(`(() => {
-        const element = document.querySelector(${JSON.stringify(selector)});
-        if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
         element.dispatchEvent(new Event('input', { bubbles: true }));
         element.dispatchEvent(new Event('change', { bubbles: true }));
-        return Array.from(element.files || []).map((file) => ({ name: file.name, size: file.size }));
+        return selected;
       })()`);
-      const expected = attachments.map((attachment) => ({ name: attachment.fileName, size: attachment.bytes.length }));
-      const matches = selected.length === expected.length && expected.every((item, index) => selected[index]?.name === item.name && selected[index]?.size === item.size);
-      if (!matches) {
-        throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED', 'Native browser did not retain the requested local files on the target input.', {
-          retryable: true,
-          details: { expected, actual: selected },
-        });
+      if (selected.length !== expected.length ||
+          !expected.every((item, index) => selected[index]?.name === item.name && selected[index]?.size === item.size)) {
+        throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED',
+          'Native browser did not retain the requested local files on the target input.', { retryable: false });
       }
     } finally {
-      for (const attachment of attachments) {
-        await this.evaluate(`(() => { try { delete globalThis[${JSON.stringify(attachment.bufferKey)}]; } catch {} return true; })()`).catch(() => undefined);
-      }
+      // Unknown effect outcomes must be reconciled by observation, never by replay.
+      await this.evaluate(`(() => {
+        try { delete globalThis[${JSON.stringify(bufferKey)}]; delete globalThis[${JSON.stringify(batchKey)}]; } catch {}
+        return true;
+      })()`).catch(() => undefined);
     }
   }
 
@@ -1123,6 +1269,57 @@ export class MacOsAppleEventsPage {
     await this.refreshMetadata();
   }
 
+  /**
+   * Supervisor-only semantic text boundary. Browser owns exact tab + DOM focus;
+   * Computer receives only a one-shot semantic target proof and remains the OS
+   * mutation transport. Generic Browser trusted text keeps its compatibility
+   * semantics and does not implicitly become ChatGPT-specific.
+   */
+  async trustedSemanticTextInput(text: string): Promise<void> {
+    if (!this.targetRef) {
+      throw new AssistantPluginError('PLUGIN_BROWSER_TRUSTED_INPUT_UNAVAILABLE', 'Semantic trusted text requires an exact saved browser tab.', { retryable: false });
+    }
+    this.targetRef = await resolveCurrentMacOsBrowserTabRef(this.browser.product, this.targetRef, this.timeoutMs);
+    const metadata = await readResolvedMacOsBrowserOwnedTabMetadata(this.browser.product, this.targetRef, this.timeoutMs);
+    if (!metadata.frontmost || metadata.active !== true) {
+      throw new AssistantPluginError(
+        'PLUGIN_BROWSER_FOREGROUND_REQUIRED',
+        'Semantic trusted text requires the exact saved browser tab to be frontmost and active.',
+        { retryable: true, details: { browserProduct: this.browser.product, windowId: this.targetRef.windowId, tabId: this.targetRef.tabId } },
+      );
+    }
+    const semanticTarget = await this.evaluate<BrowserAutomationSemanticTargetProof & { valid?: boolean }>(`(() => {
+      const element = document.activeElement;
+      if (!(element instanceof HTMLElement)) return { valid: false };
+      const tag = element.tagName.toLowerCase();
+      const inputType = element instanceof HTMLInputElement ? String(element.type || 'text').toLowerCase() : '';
+      const textInput = element instanceof HTMLTextAreaElement
+        || element.isContentEditable
+        || (element instanceof HTMLInputElement && !['button','checkbox','color','file','hidden','image','radio','range','reset','submit'].includes(inputType));
+      const accessibleName = String(element.getAttribute('aria-label') || element.getAttribute('placeholder') || element.getAttribute('title') || element.getAttribute('name') || '').trim();
+      const domRole = String(element.getAttribute('role') || (textInput ? 'textbox' : '')).trim();
+      const multiline = element instanceof HTMLTextAreaElement || element.isContentEditable || element.getAttribute('aria-multiline') === 'true';
+      return { valid: textInput && document.activeElement === element && Boolean(domRole) && Boolean(accessibleName), domRole, accessibleName, editable: true, focused: true, multiline };
+    })()`);
+    if (semanticTarget.valid !== true || semanticTarget.editable !== true || semanticTarget.focused !== true
+        || !semanticTarget.domRole || !semanticTarget.accessibleName) {
+      throw new AssistantPluginError(
+        'PLUGIN_BROWSER_TRUSTED_INPUT_SEMANTIC_TARGET_UNPROVEN',
+        'Browser could not prove one focused editable DOM target with an accessible identity before trusted text mutation.',
+        { retryable: true, details: { browserProduct: this.browser.product, windowId: this.targetRef.windowId, tabId: this.targetRef.tabId } },
+      );
+    }
+    const { valid: _valid, ...proof } = semanticTarget;
+    await sendBrowserTrustedInput({
+      action: 'trusted_input',
+      product: this.browser.product,
+      ref: this.targetRef,
+      input: { kind: 'text', text },
+      semanticTarget: proof,
+    }, this.timeoutMs);
+    await this.refreshMetadata();
+  }
+
   async screenshot(options: Record<string, unknown>): Promise<Buffer> {
     const path = typeof options.path === 'string' ? options.path : undefined;
     if (!path) throw new Error('Native browser screenshot requires an output path.');
@@ -1191,8 +1388,15 @@ export class MacOsAppleEventsPage {
         const prototype = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
         const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
         if (setter) setter.call(element, ${JSON.stringify(value)}); else element.value = ${JSON.stringify(value)};
-      } else if (element.isContentEditable) element.textContent = ${JSON.stringify(value)};
-      else throw new Error('Element does not accept text input.');
+      } else if (element.isContentEditable) {
+        element.focus();
+        const selection = window.getSelection();
+        if (!selection) throw new Error('Contenteditable selection unavailable.');
+        const range = document.createRange();
+        range.selectNodeContents(element); selection.removeAllRanges(); selection.addRange(range);
+        if (!document.execCommand('insertText', false, ${JSON.stringify(value)})) throw new Error('Contenteditable insertion rejected.');
+        return true;
+      } else throw new Error('Element does not accept text input.');
       element.dispatchEvent(new Event('input', { bubbles: true }));
       element.dispatchEvent(new Event('change', { bubbles: true }));
       return true;
@@ -1200,8 +1404,26 @@ export class MacOsAppleEventsPage {
   }
 
   async type(selector: string, text: string): Promise<void> {
-    const current = await this.evaluate<string>(selectorSource(selector, `return 'value' in element ? String(element.value || '') : String(element.textContent || '');`));
-    await this.fill(selector, `${current}${text}`);
+    await this.evaluate(selectorSource(selector, `
+      if ('value' in element) {
+        element.focus();
+        const value = String(element.value || '');
+        const prototype = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+        const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
+        if (setter) setter.call(element, value + ${JSON.stringify(text)}); else element.value = value + ${JSON.stringify(text)};
+        element.dispatchEvent(new Event('input', { bubbles: true }));
+        return true;
+      }
+      if (!element.isContentEditable) throw new Error('Element does not accept text input.');
+      element.focus();
+      const selection = window.getSelection();
+      if (!selection) throw new Error('Contenteditable selection unavailable.');
+      const range = document.createRange();
+      range.selectNodeContents(element); range.collapse(false);
+      selection.removeAllRanges(); selection.addRange(range);
+      if (!document.execCommand('insertText', false, ${JSON.stringify(text)})) throw new Error('Contenteditable insertion rejected.');
+      return true;
+    `));
   }
 
   async press(selector: string, key: string): Promise<void> {
@@ -1359,7 +1581,9 @@ async function resolveCurrentMacOsBrowserTabRef(
     ? await runtimeHooks.tabInventory(product, timeoutMs)
     : runtimeHooks.runAppleScript
       ? undefined
-      : await listMacOsBrowserTabs(product, timeoutMs);
+      // Stable identity needs the complete inventory, not UI-current flags.
+      // Input/activation checks read their exact target's foreground state.
+      : await listMacOsBrowserTabs(product, timeoutMs, { correctFrontmost: false });
   if (!inventory) return ref;
 
   const matches = inventory.tabs.filter((candidate) => candidate.tabId === ref.tabId);
@@ -1388,18 +1612,58 @@ async function resolveCurrentMacOsBrowserTabRef(
   return { windowId: match.windowId, tabId: match.tabId };
 }
 
+export interface MacOsBrowserTabInventoryOptions {
+  /**
+   * Correct stale active/frontmost bits through one extra foreground metadata
+   * read. Exact-target callers that only need stable windowId/tabId/url identity
+   * can disable this optional probe so a blocked foreground Apple Events read
+   * cannot starve the inventory itself.
+   */
+  correctFrontmost?: boolean;
+}
+
 export async function listMacOsBrowserTabs(
   product: MacOsBrowserProduct,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+  options: MacOsBrowserTabInventoryOptions = {},
 ): Promise<MacOsBrowserTabInventory> {
   const browser = browserDefinition(product);
+  // Capture the frontmost tab before reading the stable inventory when callers
+  // need corrected UI-current metadata. Exact-target identity does not depend on
+  // this optional foreground probe.
+  const inspected = options.correctFrontmost === false
+    ? undefined
+    : await inspectBrowser(product, timeoutMs);
   const raw = await runBrowserAutomationText(
     { action: 'list_tabs', product },
     listTabsScript(browser),
     [],
     timeoutMs,
   );
-  return parseTabInventory(product, raw);
+  const inventory = parseTabInventory(product, raw);
+  if (!inspected) return inventory;
+  const metadata = inspected.metadata;
+  const current = metadata?.frontmost === true && metadata.active !== false
+    ? { windowId: metadata.windowId, tabId: metadata.tabId, url: metadata.url.trim() }
+    : undefined;
+  if (!current) return inventory;
+  const hasIdentity = Boolean(current.windowId && current.tabId);
+  const currentMatches = inventory.tabs.filter(tab => (
+    hasIdentity
+      ? tab.windowId === current.windowId && tab.tabId === current.tabId
+      : Boolean(current.url) && tab.url.trim() === current.url
+  ));
+  const currentMatch = currentMatches.length === 1 ? currentMatches[0] : undefined;
+  if (!currentMatch) return inventory;
+  return {
+    ...inventory,
+    tabs: inventory.tabs.map(tab => ({
+      ...tab,
+      ...(currentMatch.windowId === tab.windowId && currentMatch.tabId === tab.tabId
+        ? { active: true, frontmost: true }
+        : { frontmost: false }),
+    })),
+  };
 }
 
 export async function readMacOsBrowserOwnedTabMetadata(
@@ -1407,11 +1671,24 @@ export async function readMacOsBrowserOwnedTabMetadata(
   ref: MacOsBrowserTabRef,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<MacOsBrowserMetadata> {
-  const browser = browserDefinition(product);
   const resolvedRef = await resolveCurrentMacOsBrowserTabRef(product, ref, timeoutMs);
+  return await readResolvedMacOsBrowserOwnedTabMetadata(product, resolvedRef, timeoutMs);
+}
+
+/**
+ * Read one exact native tab whose stable identity is already authoritative for
+ * the caller. The targeted AppleScript still fails closed when that tab id is
+ * gone, but does not perform another full browser inventory.
+ */
+export async function readResolvedMacOsBrowserOwnedTabMetadata(
+  product: MacOsBrowserProduct,
+  ref: MacOsBrowserTabRef,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<MacOsBrowserMetadata> {
+  const browser = browserDefinition(product);
   return parseMetadata(product, await runBrowserAutomationText(
-    { action: 'metadata', product, ref: resolvedRef },
-    targetMetadataScript(browser, resolvedRef),
+    { action: 'metadata', product, ref },
+    targetMetadataScript(browser, ref),
     [],
     timeoutMs,
   ));
@@ -1481,12 +1758,13 @@ export async function createMacOsBrowserOwnedPageForProduct(
   product: MacOsBrowserProduct,
   url: string,
   attempts: MacOsBrowserAttachAttempt[],
+  preferredWindowId?: string,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<{ page: MacOsAppleEventsPage; attachment: MacOsBrowserAttachment }> {
   const browser = browserDefinition(product);
   const creationEvidence = await runCreateTabAutomation(
     { action: 'create_tab', product, url },
-    createOwnedTabScript(browser),
+    createOwnedTabScript(browser, preferredWindowId),
     [url],
     timeoutMs,
   );
@@ -1544,12 +1822,28 @@ export async function closeMacOsBrowserOwnedTab(
   ref: MacOsBrowserTabRef,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<void> {
-  const browser = browserDefinition(product);
   try {
     const resolvedRef = await resolveCurrentMacOsBrowserTabRef(product, ref, timeoutMs);
+    await closeResolvedMacOsBrowserOwnedTab(product, resolvedRef, timeoutMs);
+  } finally {
+    invalidateMacOsBrowserPageHandle(product, ref);
+  }
+}
+
+/**
+ * Close one exact native tab whose stable identity was already proven by the
+ * caller's live inventory snapshot. This deliberately does not inventory again.
+ */
+export async function closeResolvedMacOsBrowserOwnedTab(
+  product: MacOsBrowserProduct,
+  ref: MacOsBrowserTabRef,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<void> {
+  const browser = browserDefinition(product);
+  try {
     await runBrowserAutomationText(
-      { action: 'close_tab', product, ref: resolvedRef },
-      closeOwnedTabScript(browser, resolvedRef),
+      { action: 'close_tab', product, ref },
+      closeOwnedTabScript(browser, ref),
       [],
       timeoutMs,
     );