@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -6,10 +6,12 @@ import {
   callBrowserAutomationBroker,
   captureBrowserAutomationRegion,
   type BrowserAutomationBrokerAction,
+  type BrowserAutomationSemanticTargetProof,
   type BrowserAutomationTrustedInput,
+  type BrowserAutomationTrustedInputRequest,
 } from './browser-automation-service';
 import { AssistantPluginError } from './errors';
-import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from './browser-session-types';
+import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from '../../../packages/protocols/browser/index';
 
 const RECORD_SEPARATOR = String.fromCharCode(30);
 const DEFAULT_NATIVE_TIMEOUT_MS = 5_000;
@@ -64,6 +66,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 +123,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());
@@ -134,8 +138,12 @@ const defaultRuntimeHooks: MacOsBrowserRuntimeHooks = {
     try {
       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;
     }
   },
 };
@@ -227,6 +235,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 +253,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,7 +335,7 @@ async function captureBrowserAutomation(
 }
 
 async function sendBrowserTrustedInput(
-  request: Extract<BrowserAutomationBrokerAction, { action: 'trusted_input' }>,
+  request: BrowserAutomationTrustedInputRequest,
   timeoutMs: number,
 ): Promise<void> {
   if (runtimeHooks.trustedInput) {
@@ -267,7 +351,7 @@ async function sendBrowserTrustedInput(
       || /\bBROWSER_AUTOMATION_ACTION_UNSUPPORTED\b/.test(message)) {
       throw new AssistantPluginError(
         'PLUGIN_BROWSER_TRUSTED_INPUT_UNAVAILABLE',
-        'Installed Forge Desktop Operator does not support native browser trusted input. Keep the exact tab explicitly foregrounded and use a separately grounded Desktop Operator interaction, or upgrade the stable Desktop Operator provider.',
+        'The configured Computer input provider does not support native browser trusted input. Keep the exact tab explicitly foregrounded and use a separately grounded Computer interaction, or upgrade the configured provider.',
         { retryable: false, details: { browserProduct: request.product, requiredProviderAction: 'trusted_input' } },
       );
     }
@@ -333,6 +417,15 @@ export function getMacOsBrowserAttachObservation(): MacOsBrowserAttachObservatio
     : undefined;
 }
 
+function recordSuccessfulMacOsBrowserAttachment(attachment: MacOsBrowserAttachment): void {
+  lastAttachObservation = {
+    checkedAt: new Date().toISOString(),
+    ready: true,
+    selectedProduct: attachment.metadata.product,
+    attempts: attachment.attempts.map((attempt) => ({ ...attempt })),
+  };
+}
+
 const BROWSERS: Record<MacOsBrowserProduct, MacOsBrowserDefinition> = {
   chrome: {
     product: 'chrome',
@@ -396,6 +489,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
@@ -408,10 +503,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
@@ -449,14 +545,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',
@@ -498,27 +603,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 error "FORGE_NO_BROWSER_WINDOW"
-set targetWindow to front window
-set originalActiveIndex to active tab index of targetWindow
-set targetTab to make new tab at end of tabs of targetWindow with properties {URL:targetUrl}
+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 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 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}
+  -- 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 active tab index of targetWindow to originalActiveIndex
 set separator to ASCII character 30
 return ((id of targetWindow) as text) & separator & (targetTabId as text)
 `)}
@@ -674,18 +830,14 @@ export async function discoverMacOsBrowserAttachment(
   }
   const selectedAttempt = attempts.find((entry) => entry.product === selected.metadata.product);
   if (selectedAttempt) selectedAttempt.status = 'selected';
-  lastAttachObservation = {
-    checkedAt: new Date().toISOString(),
-    ready: true,
-    selectedProduct: selected.metadata.product,
-    attempts: attempts.map((attempt) => ({ ...attempt })),
+  const attachment: MacOsBrowserAttachment = {
+    metadata: selected.metadata,
+    attempts,
   };
+  recordSuccessfulMacOsBrowserAttachment(attachment);
   return {
     attempts,
-    attachment: {
-      metadata: selected.metadata,
-      attempts,
-    },
+    attachment,
   };
 }
 
@@ -794,7 +946,11 @@ 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}`, {
+      // Keep the broker's bounded timeout/serialization identity visible to
+      // the sole Supervisor retry policy. Flattening both to the generic
+      // operation error makes a blocked tab hot-loop against the global lane.
+      const brokerFailure = /\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: true,
         details: { browserProduct: this.browser.product, bundleId: this.browser.bundleId },
       });
@@ -1113,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.');
@@ -1181,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;
@@ -1190,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> {
@@ -1230,10 +1462,13 @@ export class MacOsAppleEventsPage {
 
   private async setChecked(selector: string, checked: boolean): Promise<void> {
     await this.evaluate(selectorSource(selector, `
-      if (!('checked' in element)) throw new Error('Element is not checkable.');
-      element.checked = ${checked};
-      element.dispatchEvent(new Event('input', { bubbles: true }));
-      element.dispatchEvent(new Event('change', { bubbles: true }));
+      if (!('checked' in element) || typeof element.click !== 'function') {
+        throw new Error('Element is not checkable.');
+      }
+      if (element.checked !== ${checked}) element.click();
+      if (element.checked !== ${checked}) {
+        throw new Error('Requested checked state did not persist.');
+      }
       return true;
     `));
   }
@@ -1341,7 +1576,7 @@ async function resolveCurrentMacOsBrowserTabRef(
 ): Promise<MacOsBrowserTabRef> {
   // Existing unit-level AppleScript hooks historically model one exact script at a time.
   // Preserve that narrow test seam unless a live inventory hook is explicitly supplied;
-  // production always resolves through the stable Desktop Operator broker inventory.
+  // production always resolves through the configured Computer provider inventory.
   const inventory = runtimeHooks.tabInventory
     ? await runtimeHooks.tabInventory(product, timeoutMs)
     : runtimeHooks.runAppleScript
@@ -1375,18 +1610,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(
@@ -1394,11 +1669,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,
   ));
@@ -1464,6 +1752,41 @@ export async function createMacOsBrowserOwnedPage(
   return page;
 }
 
+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, preferredWindowId),
+    [url],
+    timeoutMs,
+  );
+  const ref = creationEvidence.ref;
+  const attachment: MacOsBrowserAttachment = {
+    attempts: attempts.map((attempt) => ({ ...attempt })),
+    metadata: {
+      product,
+      appName: browser.appName,
+      bundleId: browser.bundleId,
+      frontmost: false,
+      url,
+      title: '',
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      windowId: ref.windowId,
+      tabId: ref.tabId,
+      active: false,
+    },
+  };
+  const page = new MacOsAppleEventsPage(attachment, timeoutMs, ref, creationEvidence);
+  rememberMacOsBrowserPageHandle(product, ref, page);
+  return { page, attachment };
+}
+
 export async function reattachMacOsBrowserOwnedPage(
   product: MacOsBrowserProduct,
   ref: MacOsBrowserTabRef,
@@ -1488,6 +1811,7 @@ export async function reattachMacOsBrowserOwnedPage(
     : ref;
   const page = new MacOsAppleEventsPage(attachment, timeoutMs, resolvedRef);
   rememberMacOsBrowserPageHandle(product, resolvedRef, page);
+  recordSuccessfulMacOsBrowserAttachment(attachment);
   return { page, attachment };
 }
 
@@ -1496,12 +1820,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,
     );