@moretea-labs/forge 1.8.1 → 1.8.2

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

@@ -1,5 +1,5 @@
 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 {
@@ -16,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;
 
@@ -136,6 +137,8 @@ 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 (error) {
@@ -222,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 });
@@ -338,6 +342,7 @@ async function sendBrowserTrustedInput(
   request: BrowserAutomationTrustedInputRequest,
   timeoutMs: number,
 ): Promise<void> {
+  await assertMacOsBrowserApplicationRunning(request.product, timeoutMs);
   if (runtimeHooks.trustedInput) {
     await runtimeHooks.trustedInput(request, timeoutMs);
     return;
@@ -647,13 +652,15 @@ if preferredWindowId is not "" then
     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
+  -- 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}
   -- Restore the previously active tab by identity, never by a stale position:
@@ -946,12 +953,25 @@ export class MacOsAppleEventsPage {
       return await runBrowserAutomationText(effectiveRequest, effectiveScript, args, timeoutMs);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      // 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];
+      // 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: true,
+        retryable: !nonRetryable && !outcomeUnknown,
+        effectOutcome: outcomeUnknown ? 'outcome_unknown' : 'failed',
         details: { browserProduct: this.browser.product, bundleId: this.browser.bundleId },
       });
     }
@@ -980,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;
@@ -1119,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'
@@ -1135,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);
     }
   }
 
@@ -1581,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);

package/src/runtime/plugins/browser-manifest-surface.ts

@@ -616,13 +616,14 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'attach_local_file',
       title: 'Attach local file(s)',
-      description: 'Set one or more allowed local files on input[type=file] after authorization. file_path remains backward-compatible; file_paths supports multiple selection. Never auto-opens executables.',
+      description: 'Attach allowed local files to input[type=file]. Paths are repository-relative by default; optional target_key makes them relative to an existing caller-owned local-system read grant (e.g. Downloads). Does not drive a macOS Open Panel or submit the upload form.',
       readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
       argumentsSchema: interactSchema({
         selector: { type: 'string' },
         file_path: { type: 'string' },
         file_paths: { type: 'array', minItems: 1, maxItems: 32, items: { type: 'string' } },
+        target_key: { type: 'string' },
       }, ['selector']),
     },
     {

package/src/runtime/plugins/browser-registration.ts

@@ -1,5 +1,6 @@
 import {
   buildBrowserPluginManifest,
+  normalizeLegacyBrowserConfig,
   executeBrowserPluginAction,
   resolveBrowserPluginAuthorizationContext,
 } from './browser-adapter';
@@ -24,6 +25,7 @@ export const browserPluginAdapter: AssistantPluginAdapter = {
   scope: 'controller_with_repository_overlay',
   exposure: 'internal',
   buildManifest: buildBrowserPluginManifest,
+  normalizeLegacyConfig: normalizeLegacyBrowserConfig,
   executeAction: executeBrowserPluginAction,
   resolveAuthorizationContext: resolveBrowserPluginAuthorizationContext,
   shouldRefreshManifestAfterAction(actionId) {

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

@@ -11,7 +11,6 @@ import {
 import {
   BrowserProviderRegistry,
   BrowserProviderSelectionError,
-  BrowserProviderUnavailableBeforeActionError,
   type BrowserRuntimeProvider,
 } from '../../../packages/plugin-runtime/browser/provider-registry';
 
@@ -197,42 +196,34 @@ export async function executeBrowserRuntimeAction(options: {
   input: AssistantPluginActionExecutionInput;
   providers: readonly BrowserRuntimeProvider<AssistantPluginActionExecutionInput, Record<string, unknown>>[];
 }): Promise<Record<string, unknown>> {
+  if (options.providers.length !== 1) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_PROVIDER_CARDINALITY_INVALID',
+      'One Browser action must bind exactly one provider before dispatch.', { retryable: false });
+  }
   const registry = registryFor(options.runtimeKey);
-  for (const provider of options.providers) registry.register(provider);
-
+  registry.register(options.providers[0]!);
   const policy = browserRuntimeActionPolicy(options.input.actionId);
-  const excluded = new Set<string>();
-  while (true) {
-    let selection;
-    try {
-      selection = await registry.select({
-        input: options.input,
-        requiredCapabilities: policy.requiredCapabilities,
-        foreground: policy.foreground,
-        excludedProviderIds: excluded,
-      });
-    } catch (error) {
-      if (error instanceof BrowserProviderSelectionError) {
-        throw new AssistantPluginError(error.code, error.message, { retryable: error.retryable });
-      }
-      throw error;
-    }
-    const transaction = transactionFor(options.input, selection.provider.providerId, policy);
-    const validationErrors = validateBrowserTransaction(transaction);
-    if (validationErrors.length > 0) {
-      throw new AssistantPluginError('PLUGIN_BROWSER_TRANSACTION_INVALID', validationErrors[0]!, {
-        retryable: false,
-        details: { transactionId: transaction.transactionId, errors: validationErrors },
-      });
-    }
-
-    try {
-      return await selection.provider.execute(options.input);
-    } catch (error) {
-      if (!(error instanceof BrowserProviderUnavailableBeforeActionError)) throw error;
-      excluded.add(selection.provider.providerId);
-      // This is provider reselection, not action replay: the typed error proves the rejected provider
-      // never attempted the action. Unknown outcomes from non-idempotent actions always propagate.
+  let selection;
+  try {
+    selection = await registry.select({
+      input: options.input,
+      requiredCapabilities: policy.requiredCapabilities,
+      foreground: policy.foreground,
+    });
+  } catch (error) {
+    if (error instanceof BrowserProviderSelectionError) {
+      throw new AssistantPluginError(error.code, error.message, { retryable: error.retryable });
     }
+    throw error;
+  }
+  const transaction = transactionFor(options.input, selection.provider.providerId, policy);
+  const validationErrors = validateBrowserTransaction(transaction);
+  if (validationErrors.length > 0) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_TRANSACTION_INVALID', validationErrors[0]!, {
+      retryable: false,
+      details: { transactionId: transaction.transactionId, errors: validationErrors },
+    });
   }
+  // Provider failures are returned to the caller. Never silently switch target/provider.
+  return await selection.provider.execute(options.input);
 }

package/src/runtime/plugins/computer-chatgpt-browser-adapter-installer.ts

@@ -112,8 +112,17 @@ function projectExtension(source: string, destination: string): void {
       assertRegularFile(sourcePath, 'WORKFLOW_SUPERVISOR_EXTENSION_SOURCE_INVALID');
       writeFileSync(join(staging, file), readFileSync(sourcePath), { mode: 0o600 });
     }
-    rmSync(destination, { recursive: true, force: true });
-    renameSync(staging, destination);
+    // Preserve the previous projection until the staged replacement is ready.
+    const backup = destination + '.backup-' + randomUUID().slice(0, 12);
+    const hadDestination = existsSync(destination);
+    if (hadDestination) renameSync(destination, backup);
+    try {
+      renameSync(staging, destination);
+    } catch (error) {
+      if (hadDestination) renameSync(backup, destination);
+      throw error;
+    }
+    if (hadDestination) rmSync(backup, { recursive: true, force: true });
   } catch (error) {
     rmSync(staging, { recursive: true, force: true });
     throw error;

package/src/runtime/plugins/computer-registration.ts

@@ -31,6 +31,8 @@ import {
 import { desktopOperatorActions } from './desktop-operator-registration';
 import { getExternalPluginAdapter } from './external-adapter';
 import { AssistantPluginError } from './errors';
+import { executeIosPhysicalDeviceAction, iosPhysicalDeviceActions, iosPhysicalDeviceCapabilities, iosPhysicalDeviceStatus, isIosPhysicalDeviceAction, resolveIosPhysicalDeviceAuthorizationContext } from './ios-physical-device';
+import { remoteXpcHidCachedStatus } from './ios/remote-xpc-hid';
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
@@ -445,14 +447,37 @@ function buildComputerManifest(
   repoRoot?: string,
   context?: AssistantPluginBuildContext,
 ): AssistantPluginManifest {
-  const browser = buildBrowserPluginManifest(previousRevision, previousUpdatedAt, repoRoot, context);
+  const browser = buildBrowserPluginManifest(previousRevision, previousUpdatedAt, repoRoot, context, true);
+  const scriptedBrowserActions = new Set([
+    'configure', 'install_unpacked_extension', 'list_unpacked_extensions', 'clear_session', 'reconcile_sessions',
+  ]);
+  const browserActions = browser.actions.filter((action) => !scriptedBrowserActions.has(action.actionId));
+  const browserCapabilities = browser.capabilities.map((capability) => ({
+    ...capability,
+    actions: capability.actions.filter((action) => !scriptedBrowserActions.has(action)),
+    ...(capability.capabilityId === 'browser-interaction'
+      ? { description: 'Interact with existing Chrome or Vivaldi through native Computer; scripted Playwright is a separate explicit capability.' }
+      : {}),
+    ...(capability.capabilityId === 'browser-session'
+      ? { description: 'Discover, bind and reuse tabs of the user’s existing browser.' }
+      : {}),
+    ...(capability.capabilityId === 'browser-human-handoff'
+      ? { description: 'Present the exact existing native browser tab for manual interaction.' }
+      : {}),
+  })).filter((capability) => capability.actions.length > 0);
   const desktop = desktopProviderManifest(context);
   const platform = currentComputerPlatform();
   const desktopSupported = platform === 'darwin';
   const browserReady = browser.enabled && browser.health.ready;
   const desktopReady = desktopSupported && desktop?.enabled === true && desktop.health.ready;
+  const physicalRepository = desktopSupported && context?.controllerScoped === false;
+  const physicalReady = physicalRepository && iosPhysicalDeviceStatus().coreDeviceReady;
+  // Passive manifest reads must never launch Python: input readiness is
+  // published only after an explicit HID action verified the exact toolchain.
+  const hidStatus = physicalReady && context ? remoteXpcHidCachedStatus(context.controllerHome) : undefined;
+  const physicalInputReady = physicalReady && hidStatus?.available === true;
   const ready = browserReady && desktopReady;
-  const partial = browserReady || desktopReady;
+  const partial = browserReady || desktopReady || physicalReady;
   const checkedAt = new Date().toISOString();
   return {
     ...browser,
@@ -464,11 +489,14 @@ function buildComputerManifest(
       strategy: 'derived',
       duplicateStateAllowed: false,
       sourceOfTruth: [
-        ...browser.authority.sourceOfTruth,
+        // Computer browser is built in and never reads a project's independent
+        // Browser-script configuration to decide activation or routing.
         'controllerHome:sqlite/computer_interaction_target',
+        'controller-home:repository browser artifacts',
+        'controller-home:repository ios-device interactions and Controller-global UDID lock',
       ],
     },
-    enabled: browser.enabled || desktop?.enabled === true,
+    enabled: browser.enabled || desktop?.enabled === true || physicalReady,
     lifecycle: {
       state: ready ? 'enabled' : partial ? 'degraded' : 'error',
       reason: ready
@@ -488,6 +516,7 @@ function buildComputerManifest(
       ],
       warnings: [
         ...browser.health.warnings,
+        ...(physicalReady && !physicalInputReady ? [`Physical iPhone observation is ready, but RemoteXPC HID input requires Controller-owned pymobiledevice3 ${String(hidStatus?.toolchainVersion ?? 'toolchain')}.`] : []),
         ...(desktopSupported
           ? (desktopReady ? [] : ['Native Computer capability diagnostics are available through the internal platform provider.'])
           : [`Native Desktop Computer capabilities are unsupported on ${platform}.`]),
@@ -496,11 +525,24 @@ function buildComputerManifest(
         partial: !ready && partial,
         browser: { ready: browserReady, state: browser.health.state },
         desktop: { supported: desktopSupported, ready: desktopReady, state: desktop?.health.state ?? (desktopSupported ? 'not_installed' : 'unsupported') },
+        iphone: {
+          supported: desktopSupported, ready: physicalInputReady,
+          observationReady: physicalReady, inputReady: physicalInputReady,
+          toolchainVersion: hidStatus?.toolchainVersion,
+          provider: 'coredevice',
+        },
       },
     },
-    permissions: [...browser.permissions, ...desktopProductPermissions(desktopReady)],
-    capabilities: [...browser.capabilities, ...desktopProductCapabilities()],
-    actions: [...browser.actions, ...desktopProductActions()],
+    permissions: [...browser.permissions.filter((permission) => permission.scope !== 'browser.extensions').map((permission) =>
+      permission.scope === 'browser.profile'
+        ? { ...permission, description: 'Bind and persist exact existing native browser tab identities.' }
+        : permission), ...desktopProductPermissions(desktopReady),
+      ...(physicalRepository ? [
+        { scope: 'ios.discover' as const, mode: 'read' as const, description: 'Discover paired physical iPhones through CoreDevice.', granted: physicalReady, required: false },
+        { scope: 'ios.device' as const, mode: 'write' as const, description: 'Use one exact iPhone through the existing CoreDevice/RemoteXPC owner.', granted: physicalReady, required: false },
+      ] : [])],
+    capabilities: [...browserCapabilities, ...desktopProductCapabilities(), ...(physicalRepository ? iosPhysicalDeviceCapabilities() : [])],
+    actions: [...browserActions, ...desktopProductActions(), ...(physicalRepository ? iosPhysicalDeviceActions() : [])],
     updatedAt: previousUpdatedAt ?? checkedAt,
   };
 }
@@ -1003,19 +1045,44 @@ async function resolveDesktopAuthorizationContext(input: AssistantPluginActionEx
   return provider.resolveAuthorizationContext?.(providerInput(input, input.actionId, input.args));
 }
 
+// Computer's browser subdomain always targets the user's real browser.
+// The independent Browser plugin retains explicit Playwright scripting modes,
+// but Computer must neither select nor silently fall back to those providers.
+function computerNativeBrowserInput(input: AssistantPluginActionExecutionInput): AssistantPluginActionExecutionInput {
+  if (['configure', 'install_unpacked_extension', 'list_unpacked_extensions', 'clear_session', 'reconcile_sessions'].includes(input.actionId)) {
+    throw new AssistantPluginError('PLUGIN_COMPUTER_BROWSER_SCRIPT_ACTION_SEPARATE',
+      'Browser profile configuration and script-managed extensions belong to the independent Browser plugin.', { retryable: false });
+  }
+  if ((input.args.browser_mode !== undefined && input.args.browser_mode !== 'attach_preferred')
+    || (input.args.cdp_attach_fallback !== undefined && input.args.cdp_attach_fallback !== 'fail_closed')
+    || (input.args.native_attach_mode !== undefined && input.args.native_attach_mode !== 'auto')) {
+    throw new AssistantPluginError('PLUGIN_COMPUTER_BROWSER_SCRIPT_MODE_SEPARATE',
+      'Computer only operates the native browser; use the independent Browser plugin for scripted or isolated profiles.',
+      { retryable: false });
+  }
+  return { ...input, args: { ...input.args,
+    browser_mode: 'attach_preferred',
+    cdp_attach_fallback: 'fail_closed',
+    native_attach_mode: 'auto',
+    __forge_computer_native_only: true,
+  } };
+}
+
 export const computerPluginAdapter: AssistantPluginAdapter = {
   pluginId: 'computer',
   scope: 'controller_with_repository_overlay',
   buildManifest: buildComputerManifest,
   async resolveAuthorizationContext(input) {
+    if (isIosPhysicalDeviceAction(input.actionId)) return resolveIosPhysicalDeviceAuthorizationContext(input);
     if (!isDesktopProductAction(input.actionId)) {
-      return resolveBrowserPluginAuthorizationContext({ ...input, pluginId: 'browser' });
+      return resolveBrowserPluginAuthorizationContext(computerNativeBrowserInput(input));
     }
     return resolveDesktopAuthorizationContext(input);
   },
   async executeAction(input) {
+    if (isIosPhysicalDeviceAction(input.actionId)) return executeIosPhysicalDeviceAction(input);
     if (!isDesktopProductAction(input.actionId)) {
-      return executeBrowserPluginAction({ ...input, pluginId: 'browser' });
+      return executeBrowserPluginAction(computerNativeBrowserInput(input));
     }
     if (input.actionId === COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION) {
       return executeProtectedConsoleUnlockPreparation({ confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);