@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,6 +1,9 @@
 import { createHash, randomUUID } from 'crypto';
+import { spawn, spawnSync } from 'child_process';
 import { createRequire } from 'module';
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'fs';
+import { createServer as createNetServer } from 'net';
+import { existsSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 import type {
   AssistantPluginActionExecutionInput,
@@ -10,6 +13,8 @@ import type {
   AssistantPluginManifest,
 } from './types';
 import { AssistantPluginError, toAssistantPluginError } from './errors';
+import { listCanonicalGrants } from '../../../packages/kernel/identity/api/index';
+import { resolveRepoPreferredControllerHome } from '../../cli/repositories/controller-home';
 import { readRepositoryPluginConfig, writeRepositoryPluginConfig, type RepositoryPluginConfigContext } from './config-store';
 import {
   browserActions,
@@ -107,12 +112,12 @@ type WaitForSelectorState = 'attached' | 'detached' | 'visible' | 'hidden';
 type BrowserChannel = 'chromium' | 'chrome' | 'chrome-beta' | 'chrome-dev' | 'chrome-canary';
 type BrowserNativeAttachMode = 'auto' | 'disabled';
 
-const CURRENT_BROWSER_CONFIG_SCHEMA_VERSION = 2 as const;
+const CURRENT_BROWSER_CONFIG_SCHEMA_VERSION = 3 as const;
 const DEFAULT_USER_BROWSER_CHANNEL: BrowserChannel = 'chrome';
-const DEFAULT_USER_NATIVE_BROWSER_CANDIDATES: MacOsBrowserProduct[] = ['chrome'];
+const DEFAULT_USER_NATIVE_BROWSER_CANDIDATES: MacOsBrowserProduct[] = ['chrome', 'vivaldi'];
 
 interface BrowserPluginConfig {
-  schemaVersion: 2;
+  schemaVersion: 3;
   enabled: boolean;
   provider: 'playwright';
   browserMode?: BrowserMode;
@@ -131,7 +136,7 @@ interface BrowserPluginConfig {
 }
 
 type PersistedBrowserPluginConfig = Partial<Omit<BrowserPluginConfig, 'schemaVersion'>> & {
-  schemaVersion?: 1 | 2;
+  schemaVersion?: 1 | 2 | 3;
 };
 
 type BrowserSessionInventory = {
@@ -175,15 +180,109 @@ interface BrowserProfileSelection {
   selectedProfilePath: string;
 }
 
+type BrowserExtensionTargetLike = { url(): string };
+type BrowserCdpSessionLike = {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  detach?(): Promise<void>;
+};
+
+function connectNativeBrowserCdp(endpoint: string, timeoutMs: number): Promise<BrowserCdpSessionLike> {
+  const boundedTimeoutMs = Math.max(250, Math.min(timeoutMs, 30_000));
+  return new Promise<BrowserCdpSessionLike>((resolveSession, rejectSession) => {
+    const socket = new WebSocket(endpoint);
+    const pending = new Map<number, {
+      resolve(value: unknown): void;
+      reject(error: Error): void;
+      timer: ReturnType<typeof setTimeout>;
+    }>();
+    let nextId = 1;
+    let connectSettled = false;
+
+    const failPending = (error: Error) => {
+      for (const request of pending.values()) {
+        clearTimeout(request.timer);
+        request.reject(error);
+      }
+      pending.clear();
+    };
+    const failConnect = (error: Error) => {
+      if (connectSettled) return;
+      connectSettled = true;
+      clearTimeout(connectTimer);
+      rejectSession(error);
+    };
+    const connectTimer = setTimeout(() => {
+      failConnect(new Error(`Browser CDP WebSocket did not open within ${boundedTimeoutMs}ms.`));
+      try { socket.close(); } catch { /* best-effort bounded cleanup */ }
+    }, boundedTimeoutMs);
+
+    socket.onopen = () => {
+      if (connectSettled) return;
+      connectSettled = true;
+      clearTimeout(connectTimer);
+      resolveSession({
+        send: (method, params) => new Promise<unknown>((resolveResult, rejectResult) => {
+          const id = nextId++;
+          const timer = setTimeout(() => {
+            pending.delete(id);
+            rejectResult(new Error(`Browser CDP method ${method} timed out after ${boundedTimeoutMs}ms.`));
+          }, boundedTimeoutMs);
+          pending.set(id, { resolve: resolveResult, reject: rejectResult, timer });
+          try {
+            socket.send(JSON.stringify({ id, method, ...(params ? { params } : {}) }));
+          } catch (error) {
+            clearTimeout(timer);
+            pending.delete(id);
+            rejectResult(error instanceof Error ? error : new Error(String(error)));
+          }
+        }),
+        detach: async () => {
+          failPending(new Error('Browser CDP session detached.'));
+          try { socket.close(); } catch { /* best-effort bounded cleanup */ }
+        },
+      });
+    };
+    socket.onmessage = (event) => {
+      if (typeof event.data !== 'string') return;
+      let message: { id?: unknown; result?: unknown; error?: { message?: unknown } };
+      try { message = JSON.parse(event.data) as typeof message; }
+      catch { return; }
+      if (!Number.isInteger(message.id)) return;
+      const request = pending.get(Number(message.id));
+      if (!request) return;
+      pending.delete(Number(message.id));
+      clearTimeout(request.timer);
+      if (message.error) {
+        request.reject(new Error(typeof message.error.message === 'string' ? message.error.message : 'Browser CDP command failed.'));
+      } else {
+        request.resolve(message.result);
+      }
+    };
+    socket.onerror = () => {
+      const error = new Error('Browser CDP WebSocket transport failed.');
+      failConnect(error);
+      failPending(error);
+    };
+    socket.onclose = () => {
+      const error = new Error('Browser CDP WebSocket transport closed.');
+      failConnect(error);
+      failPending(error);
+    };
+  });
+}
 type BrowserContextLike = {
   pages(): PageLike[];
   newPage(): Promise<PageLike>;
   close(): Promise<void>;
+  browser?(): BrowserLike | null;
+  serviceWorkers?(): BrowserExtensionTargetLike[];
+  backgroundPages?(): BrowserExtensionTargetLike[];
 };
 
 type BrowserLike = {
   contexts(): BrowserContextLike[];
   newContext?(): Promise<BrowserContextLike>;
+  newBrowserCDPSession?(): Promise<BrowserCdpSessionLike>;
   close?(): Promise<void>;
   disconnect?(): Promise<void> | void;
 };
@@ -257,10 +356,56 @@ interface BrowserPluginRuntimeHooks {
   loadPlaywright(repoRoot?: string): PlaywrightRuntime;
   fetchJson(url: string, timeoutMs: number): Promise<unknown>;
   activateNativeBrowserApplication(input: AssistantPluginActionExecutionInput, product: MacOsBrowserProduct): Promise<void>;
+  /** Bounded process inventory used only to reclaim Forge-owned browser profiles. */
+  listProcesses(): Array<{ pid: number; command: string }>;
+  /** Signal one process; returns false when it already exited. */
+  signalProcess(pid: number, signal: NodeJS.Signals): boolean;
+  /** Launch one browser process without claiming its lifecycle through Playwright. */
+  launchProcess(executable: string, args: string[]): { pid?: number };
+  /** Allocate one currently-free loopback TCP port for an immediately following browser launch. */
+  allocateLoopbackPort(): Promise<number>;
+  /** Open one bounded browser-level CDP session without a Playwright browser/context adapter. */
+  connectBrowserCdp(endpoint: string, timeoutMs: number): Promise<BrowserCdpSessionLike>;
 }
 
 const defaultRuntimeHooks: BrowserPluginRuntimeHooks = {
   now: () => new Date().toISOString(),
+  listProcesses: () => {
+    const result = spawnSync('ps', ['-eo', 'pid=,command='], { encoding: 'utf8', timeout: 10_000, maxBuffer: 8 * 1024 * 1024 });
+    if (result.status !== 0 || typeof result.stdout !== 'string') return [];
+    const entries: Array<{ pid: number; command: string }> = [];
+    for (const line of result.stdout.split('\n')) {
+      const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+      if (!match?.[1] || !match[2]) continue;
+      entries.push({ pid: Number(match[1]), command: match[2] });
+    }
+    return entries;
+  },
+  signalProcess: (pid, signal) => {
+    try { process.kill(pid, signal); return true; }
+    catch (error) { return (error as NodeJS.ErrnoException).code !== 'ESRCH'; }
+  },
+  launchProcess: (executable, args) => {
+    const child = spawn(executable, args, { stdio: 'ignore', detached: true });
+    child.once('error', () => undefined);
+    child.unref();
+    return { pid: child.pid };
+  },
+  allocateLoopbackPort: () => new Promise<number>((resolvePort, rejectPort) => {
+    const server = createNetServer();
+    server.unref();
+    server.once('error', rejectPort);
+    server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address ? address.port : 0;
+      server.close((error) => {
+        if (error) return rejectPort(error);
+        if (!Number.isInteger(port) || port <= 0 || port > 65_535) return rejectPort(new Error('BROWSER_LOOPBACK_PORT_ALLOCATION_FAILED'));
+        resolvePort(port);
+      });
+    });
+  }),
+  connectBrowserCdp: connectNativeBrowserCdp,
   moduleAvailable: (name: string, repoRoot?: string) => {
     const anchors = [repoRoot ? join(repoRoot, 'package.json') : undefined, import.meta.url]
       .filter((value): value is string => Boolean(value));
@@ -313,6 +458,7 @@ interface ManagedBrowserContextState {
 }
 
 const managedBrowserContexts = new Map<string, Promise<ManagedBrowserContextState>>();
+const managedExtensionPaths = new Map<string, Set<string>>();
 
 export function setBrowserPluginRuntimeHooksForTest(hooks: Partial<BrowserPluginRuntimeHooks>): void {
   runtimeHooks = { ...defaultRuntimeHooks, ...hooks };
@@ -323,6 +469,7 @@ export function resetBrowserPluginRuntimeHooksForTest(): void {
   runtimeHooks = { ...defaultRuntimeHooks };
   runtimeHooksCustomized = false;
   managedBrowserContexts.clear();
+  managedExtensionPaths.clear();
 }
 
 function now(): string {
@@ -426,42 +573,46 @@ function resolveProfileSelection(repoRoot: string, profileDir: string, profileDi
 
 function normalizeConfig(raw: PersistedBrowserPluginConfig): BrowserPluginConfig {
   const normalizedProfileDir = stringValue(raw.profileDir);
+  const normalizedExecutablePath = stringValue(raw.executablePath);
+  const normalizedBrowserChannel = browserChannel(raw.browserChannel);
   return {
     schemaVersion: CURRENT_BROWSER_CONFIG_SCHEMA_VERSION,
     enabled: raw.enabled === true,
     provider: 'playwright',
-    browserMode: browserMode(raw.browserMode) ?? 'attach_preferred',
+    browserMode: browserMode(raw.browserMode) ?? 'managed_persistent',
     profileMode: browserProfileMode(raw.profileMode) ?? (normalizedProfileDir ? 'custom' : 'repo_local'),
     profileDir: normalizedProfileDir,
     profileDirectory: stringValue(raw.profileDirectory),
-    browserChannel: browserChannel(raw.browserChannel) ?? DEFAULT_USER_BROWSER_CHANNEL,
-    executablePath: stringValue(raw.executablePath),
+    browserChannel: normalizedBrowserChannel ?? (normalizedExecutablePath ? undefined : DEFAULT_USER_BROWSER_CHANNEL),
+    executablePath: normalizedExecutablePath,
     cdpEndpoint: stringValue(raw.cdpEndpoint),
     cdpEndpointCandidates: stringList(raw.cdpEndpointCandidates)?.slice(0, MAX_BROWSER_CDP_ENDPOINT_CANDIDATES),
     cdpDiscoveryTimeoutMs: typeof raw.cdpDiscoveryTimeoutMs === 'number'
       ? Math.min(positiveNumber(raw.cdpDiscoveryTimeoutMs, DEFAULT_CDP_DISCOVERY_TIMEOUT_MS), MAX_CDP_DISCOVERY_TIMEOUT_MS)
       : undefined,
     cdpAttachFallback: browserCdpAttachFallback(raw.cdpAttachFallback) ?? 'fail_closed',
-    nativeAttachMode: browserNativeAttachMode(raw.nativeAttachMode) ?? 'auto',
+    nativeAttachMode: browserNativeAttachMode(raw.nativeAttachMode) ?? 'disabled',
     nativeBrowserCandidates: browserProductList(raw.nativeBrowserCandidates) ?? [...DEFAULT_USER_NATIVE_BROWSER_CANDIDATES],
     defaultTimeoutMs: typeof raw.defaultTimeoutMs === 'number' ? positiveNumber(raw.defaultTimeoutMs, DEFAULT_TIMEOUT_MS) : undefined,
   };
 }
 
 function migrateLegacyRepositoryConfig(raw: PersistedBrowserPluginConfig): PersistedBrowserPluginConfig {
-  if (raw.schemaVersion !== 1) return raw;
+  if (raw.schemaVersion === CURRENT_BROWSER_CONFIG_SCHEMA_VERSION) return raw;
+  const configuredCdp = Boolean(
+    stringValue(raw.cdpEndpoint)
+    || (stringList(raw.cdpEndpointCandidates)?.length ?? 0) > 0,
+  );
+  const legacyMode = browserMode(raw.browserMode) ?? 'attach_preferred';
   return {
+    ...raw,
     schemaVersion: CURRENT_BROWSER_CONFIG_SCHEMA_VERSION,
-    enabled: raw.enabled,
-    provider: 'playwright',
-    browserMode: 'attach_preferred',
-    profileMode: 'repo_local',
-    browserChannel: DEFAULT_USER_BROWSER_CHANNEL,
-    cdpAttachFallback: 'fail_closed',
-    nativeAttachMode: 'auto',
-    nativeBrowserCandidates: [...DEFAULT_USER_NATIVE_BROWSER_CANDIDATES],
-    defaultTimeoutMs: raw.defaultTimeoutMs,
-    cdpDiscoveryTimeoutMs: raw.cdpDiscoveryTimeoutMs,
+    // v1/v2 defaulted to attach_preferred + native auto and silently made
+    // Apple Events JavaScript a global Browser dependency whenever no CDP endpoint
+    // was configured. Preserve explicit CDP attachment, but retire native attach
+    // from migrated defaults; it remains available only when explicitly selected.
+    browserMode: legacyMode === 'attach_preferred' && !configuredCdp ? 'managed_persistent' : legacyMode,
+    nativeAttachMode: 'disabled',
   };
 }
 
@@ -490,7 +641,13 @@ async function resolveBrowserPluginAuthorizationContextInternal(
   input: AssistantPluginActionExecutionInput,
 ): Promise<AssistantPluginAuthorizationContext | undefined> {
   const action = browserActions().find((entry) => entry.actionId === input.actionId);
-  if (!action || action.confirmation !== 'authorization' || !action.scopes.includes('browser.interact')) return undefined;
+  // Browser session/profile mutations also need an exact reusable target. In
+  // particular, create_session is the bootstrap action for a scheduled
+  // Controller round and intentionally carries browser.read + browser.profile
+  // rather than browser.interact. Restricting authorization resolution to
+  // browser.interact made the first interactive session usable only for that
+  // call and left the Scheduler without a durable browser-session grant.
+  if (!action || action.confirmation !== 'authorization' || !action.scopes.includes('browser.profile')) return undefined;
 
   const persistedConfig = loadConfig(input.repoRoot, input);
   const sessionId = stringValue(input.args.session_id);
@@ -499,7 +656,24 @@ async function resolveBrowserPluginAuthorizationContextInternal(
   const session = findBrowserSession(input.repoRoot, sessionId);
   const config = effectiveBrowserActionConfig(persistedConfig, input.args, session);
   const connection = session?.browser;
-  if (!session || !connection || connection.activeMode === 'isolated') return undefined;
+  if (!session || !connection || connection.activeMode === 'isolated') {
+    // create_session precedes its durable session record. Recover only the
+    // exact browser-origin target already named by this Work's grant refs.
+    if (input.actionId !== 'create_session') return undefined;
+    let origin: string;
+    try { origin = new URL(stringValue(input.args.url) ?? '').origin.toLowerCase(); } catch { return undefined; }
+    const refs = new Set((input.authorizationGrantRefs ?? []).map((ref) => ref.trim()).filter(Boolean));
+    const target = listCanonicalGrants(input.controllerHome).find((grant) => (
+      refs.has(grant.grantId)
+      && grant.target?.kind === 'browser-origin'
+      && grant.target.id.endsWith(`@${origin}`)
+      && grant.scopes?.includes('browser.profile')
+    ))?.target;
+    return target ? {
+      target: { kind: target.kind, id: target.id, identityFingerprint: target.identityFingerprint },
+      expiresInMinutes: 30 * 24 * 60,
+    } : undefined;
+  }
 
   let origin: string;
   try {
@@ -1056,7 +1230,7 @@ interface BrowserOpenHandle {
 
 interface PageDiagnostics {
   consoleErrors: Array<{ type: string; text: string }>;
-  failedRequests: Array<{ url: string; status?: number; failure?: string }>;
+  failedRequests: Array<{ url: string; method?: string; status?: number; failure?: string }>;
   navigation?: { url: string; status?: number };
 }
 
@@ -1074,18 +1248,21 @@ function attachDiagnostics(page: PageLike): PageDiagnostics {
       }
     });
     page.on('requestfailed', (request) => {
-      const entry = request as { url?: () => string; failure?: () => { errorText?: string } | null };
+      const entry = request as { url?: () => string; method?: () => string; failure?: () => { errorText?: string } | null };
       diagnostics.failedRequests.push({
         url: typeof entry.url === 'function' ? entry.url() : '',
+        method: typeof entry.method === 'function' ? entry.method() : undefined,
         failure: typeof entry.failure === 'function' ? entry.failure()?.errorText : undefined,
       });
     });
     page.on('response', (response) => {
-      const entry = response as { url?: () => string; status?: () => number; ok?: () => boolean };
+      const entry = response as { url?: () => string; status?: () => number; ok?: () => boolean; request?: () => { method?: () => string } };
       const status = typeof entry.status === 'function' ? entry.status() : undefined;
       if (typeof status === 'number' && status >= 400) {
+        const request = typeof entry.request === 'function' ? entry.request() : undefined;
         diagnostics.failedRequests.push({
           url: typeof entry.url === 'function' ? entry.url() : '',
+          method: typeof request?.method === 'function' ? request.method() : undefined,
           status,
         });
       }
@@ -1544,14 +1721,71 @@ async function discoverCdpEndpoint(endpoint: string, timeoutMs: number): Promise
   };
 }
 
+async function waitForCdpEndpoint(endpoint: string, timeoutMs: number): Promise<CdpAttachAttempt> {
+  const deadline = Date.now() + Math.max(250, timeoutMs);
+  let lastError: unknown;
+  while (Date.now() < deadline) {
+    try {
+      return await discoverCdpEndpoint(endpoint, Math.max(100, Math.min(500, deadline - Date.now())));
+    } catch (error) {
+      lastError = error;
+      await delay(50);
+    }
+  }
+  throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Vivaldi did not expose the allocated loopback CDP endpoint after launch.', {
+    retryable: true,
+    details: { endpoint, error: lastError instanceof Error ? lastError.message : String(lastError ?? 'unknown') },
+  });
+}
+
+async function browserCdpExtensionTarget(session: BrowserCdpSessionLike, extensionId: string): Promise<string | undefined> {
+  const response = await session.send('Target.getTargets') as { targetInfos?: Array<{ url?: unknown }> };
+  const prefix = `chrome-extension://${extensionId}/`;
+  return (response.targetInfos ?? [])
+    .map((target) => typeof target.url === 'string' ? target.url : '')
+    .find((url) => url.startsWith(prefix));
+}
+
+async function waitForBrowserCdpExtensionTarget(session: BrowserCdpSessionLike, extensionId: string, timeoutMs: number): Promise<string> {
+  const deadline = Date.now() + Math.min(Math.max(timeoutMs, 250), 10_000);
+  while (Date.now() <= deadline) {
+    const target = await browserCdpExtensionTarget(session, extensionId);
+    if (target) return target;
+    await delay(100);
+  }
+  throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_POSTCONDITION_FAILED', 'Browser-level CDP did not expose an exact runtime target for the requested extension id.', {
+    retryable: true,
+    details: { extensionId },
+  });
+}
+
 function launchOptionsForRepo(repoRoot: string, config: BrowserPluginConfig, profile: BrowserProfileSelection): Record<string, unknown> {
+  const extensionPaths = [...(managedExtensionPaths.get(managedContextKey(profile)) ?? [])].sort();
+  const args = [
+    ...(profile.profileDirectory ? [`--profile-directory=${profile.profileDirectory}`] : []),
+    ...(extensionPaths.length > 0 ? ['--enable-unsafe-extension-debugging'] : []),
+  ];
+  const customProfileDefaultArgsToPreserve = [
+    '--disable-extensions',
+    '--disable-component-extensions-with-background-pages',
+    '--disable-default-apps',
+    '--disable-sync',
+    '--use-mock-keychain',
+    '--password-store=basic',
+  ];
+  const ignoreDefaultArgs = config.profileMode === 'custom'
+    ? customProfileDefaultArgsToPreserve
+    : extensionPaths.length > 0
+      ? ['--disable-extensions']
+      : [];
   return {
     headless: false,
     acceptDownloads: true,
     viewport: { width: 1280, height: 900 },
     ...(config.executablePath ? { executablePath: resolveConfiguredPath(repoRoot, config.executablePath) } : {}),
-    ...(!config.executablePath && config.browserChannel && config.browserChannel !== 'chromium' ? { channel: config.browserChannel } : {}),
-    ...(profile.profileDirectory ? { args: [`--profile-directory=${profile.profileDirectory}`] } : {}),
+    ...(!config.executablePath && extensionPaths.length === 0 && config.browserChannel && config.browserChannel !== 'chromium' ? { channel: config.browserChannel } : {}),
+    ...(ignoreDefaultArgs.length > 0 ? { ignoreDefaultArgs } : {}),
+    ...(args.length > 0 ? { args } : {}),
   };
 }
 
@@ -1571,8 +1805,87 @@ async function evictManagedContext(key: string): Promise<void> {
   }
 }
 
+/**
+ * Forge-owned isolated/handoff browser profiles are per-session and cannot be
+ * shared, so a browser still running on one of those profiles while no managed
+ * context in this Runtime incarnation owns it is an orphan: the session that
+ * launched it is gone. Left alone it stays visible as a logged-out browser the
+ * user never opened and keeps a stale profile locked.
+ *
+ * Reclamation is mechanical and bounded: only processes whose own command line
+ * names a Forge-owned profile path are considered, browser child processes
+ * (`--type=`) are ignored so the main process is signalled once, and a profile
+ * with a live managed context is never touched.
+ */
+export function reclaimOrphanedIsolatedBrowserProfiles(input: { profileRoots: readonly string[]; graceMs?: number }): { terminated: number; details: string[] } {
+  const roots = input.profileRoots.map((root) => resolve(root)).filter(Boolean);
+  if (roots.length === 0) return { terminated: 0, details: [] };
+  const owned = (profileDir: string): boolean => {
+    const normalized = resolve(profileDir);
+    const isForgeProfile = /\/browser\/profiles\/(?:isolated|handoff)\//.test(normalized);
+    if (!isForgeProfile) return false;
+    return roots.some((root) => normalized === root || normalized.startsWith(`${root}${sep}`));
+  };
+  const liveOwners = new Set([...managedBrowserContexts.keys()].map((key) => resolve(key)));
+  const graceMs = Math.max(0, Math.min(30_000, input.graceMs ?? 2_000));
+  const targets: Array<{ pid: number; profileDir: string }> = [];
+  for (const entry of runtimeHooks.listProcesses()) {
+    if (entry.command.includes('--type=')) continue;
+    const match = /--user-data-dir=(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(entry.command);
+    const profileDir = match?.[1] ?? match?.[2] ?? match?.[3];
+    if (!profileDir || !owned(profileDir)) continue;
+    if (liveOwners.has(resolve(profileDir))) continue;
+    targets.push({ pid: entry.pid, profileDir: resolve(profileDir) });
+  }
+  const details: string[] = [];
+  let terminated = 0;
+  for (const target of targets) {
+    runtimeHooks.signalProcess(target.pid, 'SIGTERM');
+    details.push(`SIGTERM ${target.pid} ${target.profileDir}`);
+    terminated += 1;
+  }
+  if (graceMs > 0 && targets.length > 0) {
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline) {
+      const remaining = new Set(targets
+        .filter((target) => runtimeHooks.listProcesses().some((entry) => entry.pid === target.pid && !entry.command.includes('--type=')))
+        .map((target) => target.pid));
+      if (remaining.size === 0) break;
+      sleepSyncMs(50);
+    }
+    for (const target of targets) {
+      const alive = runtimeHooks.listProcesses().some((entry) => entry.pid === target.pid && !entry.command.includes('--type='));
+      if (!alive) continue;
+      runtimeHooks.signalProcess(target.pid, 'SIGKILL');
+      details.push(`SIGKILL ${target.pid} ${target.profileDir}`);
+    }
+  }
+  return { terminated, details };
+}
+
+function sleepSyncMs(ms: number): void {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, Math.min(1_000, ms))); }
+  catch { /* best-effort bounded wait */ }
+}
+
+export function browserProfileRootsForRuntime(input: { controllerHome: string; repoRoots?: readonly string[] }): string[] {
+  const roots = new Set<string>();
+  const home = input.controllerHome.trim();
+  if (home) roots.add(join(resolve(home), 'repositories'));
+  for (const repoRoot of input.repoRoots ?? []) {
+    const trimmed = repoRoot.trim();
+    if (trimmed) roots.add(join(resolve(trimmed), '.forge'));
+  }
+  return [...roots];
+}
+
 async function closeManagedContextsForRepo(repoRoot: string, options: { strict?: boolean } = {}): Promise<void> {
   const canonicalRoot = resolve(repoRoot);
+  // Explicit session cleanup must also retire a browser whose session record is
+  // gone; otherwise the profile stays locked by a process nothing owns.
+  reclaimOrphanedIsolatedBrowserProfiles({
+    profileRoots: browserProfileRootsForRuntime({ controllerHome: resolveRepoPreferredControllerHome(canonicalRoot), repoRoots: [canonicalRoot] }),
+  });
   for (const [key, pending] of [...managedBrowserContexts.entries()]) {
     let state: ManagedBrowserContextState;
     try {
@@ -1884,6 +2197,342 @@ async function openManagedContext(
   };
 }
 
+const FORGE_NATIVE_MESSAGING_DECLARATION = 'forge-native-messaging-host.json';
+interface ManagedNativeMessagingHost {
+  name: string;
+  manifest: string;
+}
+interface BrowserExtensionInfo {
+  id: string;
+  name?: string;
+  version?: string;
+  path: string;
+  enabled: boolean;
+}
+
+function pathWithin(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
+function unpackedExtensionPath(input: AssistantPluginActionExecutionInput): { path: string; expectedId?: string; nativeHost?: ManagedNativeMessagingHost } {
+  const requested = requiredString(input.args.extension_path, 'extension_path');
+  if (!isAbsolute(requested)) throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'extension_path must be absolute.', { retryable: false });
+  if (!existsSync(requested) || !statSync(requested).isDirectory()) {
+    throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'extension_path must reference an existing directory.', { retryable: false });
+  }
+  const realPath = realpathSync(requested);
+  const trustedRoots = [realpathSync(input.repoRoot)];
+  const controllerBrowserRoot = join(resolve(input.controllerHome), 'supervisor', 'browser-adapter');
+  if (existsSync(controllerBrowserRoot)) trustedRoots.push(realpathSync(controllerBrowserRoot));
+  if (!trustedRoots.some((root) => pathWithin(root, realPath))) {
+    throw new AssistantPluginError('PLUGIN_POLICY_BLOCKED', 'Unpacked extensions must resolve inside the repository or Controller-owned browser-adapter root.', { retryable: false });
+  }
+  const manifestPath = join(realPath, 'manifest.json');
+  if (!existsSync(manifestPath) || !statSync(manifestPath).isFile() || !pathWithin(realPath, realpathSync(manifestPath))) {
+    throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Unpacked extension requires a regular manifest.json inside the extension directory.', { retryable: false });
+  }
+  let manifest: { key?: unknown };
+  try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { key?: unknown }; }
+  catch { throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Unpacked extension manifest.json must contain valid JSON.', { retryable: false }); }
+  let expectedId: string | undefined;
+  if (typeof manifest.key === 'string' && /^[A-Za-z0-9+/]+={0,2}$/.test(manifest.key.trim())) {
+    const bytes = Buffer.from(manifest.key.trim(), 'base64');
+    if (bytes.length > 0) expectedId = createHash('sha256').update(bytes).digest('hex').slice(0, 32)
+      .replace(/[0-9a-f]/g, (nibble) => String.fromCharCode(97 + Number.parseInt(nibble, 16)));
+  }
+  const declarationPath = join(realPath, FORGE_NATIVE_MESSAGING_DECLARATION);
+  let nativeHost: ManagedNativeMessagingHost | undefined;
+  if (existsSync(declarationPath)) {
+    if (!expectedId || !statSync(declarationPath).isFile() || !pathWithin(realPath, realpathSync(declarationPath))) {
+      throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Managed native messaging declaration requires a regular file and stable extension manifest key.', { retryable: false });
+    }
+    let declaration: { name?: unknown; description?: unknown; path?: unknown; type?: unknown; allowed_origins?: unknown };
+    try { declaration = JSON.parse(readFileSync(declarationPath, 'utf8')) as typeof declaration; }
+    catch { throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'forge-native-messaging-host.json must contain valid JSON.', { retryable: false }); }
+    const name = typeof declaration.name === 'string' ? declaration.name.trim() : '';
+    const hostPath = typeof declaration.path === 'string' ? declaration.path.trim() : '';
+    const expectedOrigin = `chrome-extension://${expectedId}/`;
+    if (!/^[a-z0-9_]+(?:\.[a-z0-9_]+)*$/.test(name)
+      || declaration.type !== 'stdio'
+      || !isAbsolute(hostPath)
+      || !Array.isArray(declaration.allowed_origins)
+      || declaration.allowed_origins.length !== 1
+      || declaration.allowed_origins[0] !== expectedOrigin) {
+      throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Managed native messaging declaration must bind one valid host name, stdio transport, absolute executable, and the exact stable extension origin.', { retryable: false });
+    }
+    if (!existsSync(hostPath) || !statSync(hostPath).isFile()) {
+      throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Managed native messaging host executable must exist as a regular file.', { retryable: false });
+    }
+    const realHostPath = realpathSync(hostPath);
+    if (!trustedRoots.some((root) => pathWithin(root, realHostPath))) {
+      throw new AssistantPluginError('PLUGIN_POLICY_BLOCKED', 'Managed native messaging host executable must resolve inside an already trusted extension, repository, or Controller browser-adapter root.', { retryable: false });
+    }
+    if (process.platform !== 'win32' && (statSync(realHostPath).mode & 0o111) === 0) {
+      throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Managed native messaging host must be executable.', { retryable: false });
+    }
+    nativeHost = {
+      name,
+      manifest: `${JSON.stringify({
+        name,
+        description: typeof declaration.description === 'string' ? declaration.description.slice(0, 512) : '',
+        path: realHostPath,
+        type: 'stdio',
+        allowed_origins: [expectedOrigin],
+      }, null, 2)}\n`,
+    };
+  }
+  return { path: realPath, expectedId, nativeHost };
+}
+
+function projectManagedNativeMessagingHost(profileDir: string, host: ManagedNativeMessagingHost | undefined): boolean {
+  if (!host) return false;
+  const root = join(profileDir, 'NativeMessagingHosts');
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const target = join(root, `${host.name}.json`);
+  if (existsSync(target) && readFileSync(target, 'utf8') === host.manifest) return false;
+  const temporary = `${target}.${randomUUID().slice(0, 12)}.tmp`;
+  writeFileSync(temporary, host.manifest, { mode: 0o600 });
+  renameSync(temporary, target);
+  return true;
+}
+
+function extensionTargets(context: BrowserContextLike): string[] {
+  return [...(context.serviceWorkers?.() ?? []), ...(context.backgroundPages?.() ?? [])].map((target) => target.url());
+}
+
+async function waitForManagedExtension(context: BrowserContextLike, extensionId: string, timeoutMs: number): Promise<string> {
+  const prefix = `chrome-extension://${extensionId}/`;
+  const deadline = Date.now() + Math.min(Math.max(timeoutMs, 250), 10_000);
+  while (Date.now() <= deadline) {
+    const url = extensionTargets(context).find((candidate) => candidate.startsWith(prefix));
+    if (url) return url;
+    await delay(100);
+  }
+  throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_POSTCONDITION_FAILED', 'Managed browser did not expose an exact runtime target for the requested extension id.', { retryable: true, details: { extensionId } });
+}
+
+async function browserLevelCdp(
+  repoRoot: string,
+  config: BrowserPluginConfig,
+): Promise<{ browser: BrowserLike; session: BrowserCdpSessionLike; endpoint: string } | undefined> {
+  if (cdpEndpoints(config).length === 0 || !runtimeHooks.moduleAvailable('playwright', repoRoot)) return undefined;
+  const runtime = runtimeHooks.loadPlaywright(repoRoot);
+  const connectOverCDP = runtime.chromium.connectOverCDP;
+  if (typeof connectOverCDP !== 'function') return undefined;
+  for (const endpoint of cdpEndpoints(config)) {
+    try {
+      const discovered = await discoverCdpEndpoint(endpoint, cdpDiscoveryTimeout(config));
+      const browser = await connectOverCDP.call(runtime.chromium, discovered.discoveredEndpoint ?? endpoint);
+      if (typeof browser.newBrowserCDPSession !== 'function') {
+        if (browser.disconnect) await Promise.resolve(browser.disconnect()).catch(() => undefined);
+        else if (browser.close) await browser.close().catch(() => undefined);
+        continue;
+      }
+      const session = await browser.newBrowserCDPSession();
+      return { browser, session, endpoint: discovered.discoveredEndpoint ?? endpoint };
+    } catch { /* Pre-dispatch endpoint discovery/attach failure; try the next configured endpoint. */ }
+  }
+  return undefined;
+}
+
+async function closeBrowserLevelCdp(handle: { browser: BrowserLike; session: BrowserCdpSessionLike }): Promise<void> {
+  await handle.session.detach?.().catch(() => undefined);
+  if (handle.browser.disconnect) await Promise.resolve(handle.browser.disconnect()).catch(() => undefined);
+  else if (handle.browser.close) await handle.browser.close().catch(() => undefined);
+}
+
+async function cdpExtensionList(repoRoot: string, config: BrowserPluginConfig): Promise<{ provider: string; endpoint: string; extensions: BrowserExtensionInfo[] } | undefined> {
+  const handle = await browserLevelCdp(repoRoot, config);
+  if (!handle) return undefined;
+  try {
+    const result = await handle.session.send('Extensions.getExtensions') as { extensions?: BrowserExtensionInfo[] };
+    return { provider: 'playwright-cdp', endpoint: handle.endpoint, extensions: Array.isArray(result.extensions) ? result.extensions : [] };
+  } finally { await closeBrowserLevelCdp(handle); }
+}
+
+async function loadAndVerifyUnpackedExtension(
+  session: BrowserCdpSessionLike,
+  extensionPath: string,
+  expectedId: string | undefined,
+  enableInIncognito: boolean,
+): Promise<BrowserExtensionInfo> {
+  const loaded = await session.send('Extensions.loadUnpacked', {
+    path: extensionPath,
+    ...(enableInIncognito ? { enableInIncognito: true } : {}),
+  }) as { id?: string };
+  const id = typeof loaded.id === 'string' && loaded.id.trim() ? loaded.id.trim() : undefined;
+  if (!id) throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_POSTCONDITION_FAILED', 'Browser did not return an extension id after loadUnpacked.', { retryable: true });
+  if (expectedId && id !== expectedId) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_POSTCONDITION_FAILED', 'Browser returned an unpacked extension id that does not match the manifest-derived stable id.', {
+      retryable: false,
+      details: { extensionId: id, expectedExtensionId: expectedId },
+    });
+  }
+  const listed = await session.send('Extensions.getExtensions') as { extensions?: BrowserExtensionInfo[] };
+  const exact = (listed.extensions ?? []).find((entry) => {
+    if (entry.id !== id || entry.enabled !== true) return false;
+    try { return realpathSync(entry.path) === extensionPath; } catch { return false; }
+  });
+  if (!exact) throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_POSTCONDITION_FAILED', 'Browser did not verify the exact enabled unpacked extension id/path after loadUnpacked.', { retryable: true, details: { extensionId: id } });
+  return exact;
+}
+
+function customVivaldiExtensionInstall(config: BrowserPluginConfig, repoRoot: string): { executable: string } | undefined {
+  if (config.profileMode !== 'custom' || !config.executablePath) return undefined;
+  const executable = resolveConfiguredPath(repoRoot, config.executablePath);
+  return basename(executable).toLowerCase() === 'vivaldi' ? { executable } : undefined;
+}
+
+function processUsesUserDataDir(command: string, profileDir: string): boolean {
+  const expected = resolve(profileDir);
+  const forms = [
+    `--user-data-dir=${expected}`,
+    `--user-data-dir="${expected}"`,
+    `--user-data-dir='${expected}'`,
+  ];
+  return forms.some((form) => {
+    const index = command.indexOf(form);
+    if (index < 0) return false;
+    const next = command[index + form.length];
+    return next === undefined || /\s/.test(next);
+  });
+}
+
+function exactCustomVivaldiProfileOwner(
+  executable: string,
+  profile: BrowserProfileSelection,
+): { pid: number; command: string } | undefined {
+  let lockTarget: string;
+  try { lockTarget = readlinkSync(join(profile.profileDir, 'SingletonLock')); }
+  catch { return undefined; }
+  const pidText = /(?:^|-)(\d+)$/.exec(lockTarget.trim())?.[1];
+  const pid = pidText ? Number(pidText) : 0;
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  const process = runtimeHooks.listProcesses().find((entry) => entry.pid === pid && !entry.command.includes('--type='));
+  if (!process || !process.command.includes(executable)) return undefined;
+  const hasExplicitProfileDir = process.command.includes('--user-data-dir=');
+  if (hasExplicitProfileDir) {
+    if (!processUsesUserDataDir(process.command, profile.profileDir)) return undefined;
+  } else {
+    const defaultVivaldiProfileDir = resolve(join(homedir(), 'Library', 'Application Support', 'Vivaldi'));
+    if (resolve(profile.profileDir) !== defaultVivaldiProfileDir) return undefined;
+  }
+  return process;
+}
+
+async function gracefullyRestartExactCustomVivaldiOwner(
+  executable: string,
+  profile: BrowserProfileSelection,
+  timeoutMs: number,
+): Promise<{ restarted: boolean; pid?: number }> {
+  const owner = exactCustomVivaldiProfileOwner(executable, profile);
+  if (!owner) return { restarted: false };
+  runtimeHooks.signalProcess(owner.pid, 'SIGTERM');
+  const deadline = Date.now() + Math.max(500, Math.min(timeoutMs, 10_000));
+  while (Date.now() < deadline) {
+    const alive = runtimeHooks.listProcesses().some((entry) => entry.pid === owner.pid && !entry.command.includes('--type='));
+    if (!alive) return { restarted: true, pid: owner.pid };
+    await delay(50);
+  }
+  throw new AssistantPluginError('PLUGIN_BROWSER_PROFILE_IN_USE', 'The exact Vivaldi custom-profile owner did not exit after a bounded graceful restart request.', {
+    retryable: true,
+    details: { pid: owner.pid, profileDir: profile.profileDir },
+  });
+}
+
+async function installExtensionThroughCustomVivaldiCdpPort(
+  input: AssistantPluginActionExecutionInput,
+  config: BrowserPluginConfig,
+  profile: BrowserProfileSelection,
+  extensionPath: string,
+  expectedId: string,
+): Promise<Record<string, unknown>> {
+  const vivaldi = customVivaldiExtensionInstall(config, input.repoRoot);
+  if (!vivaldi) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Custom Vivaldi unpacked-extension install requires the configured Vivaldi executable.', { retryable: true });
+  }
+  const timeoutMs = positiveNumber(input.args.timeout_ms, config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+  await gracefullyRestartExactCustomVivaldiOwner(vivaldi.executable, profile, timeoutMs);
+  const port = await runtimeHooks.allocateLoopbackPort();
+  const endpoint = `http://127.0.0.1:${port}`;
+  const args = [
+    `--user-data-dir=${profile.profileDir}`,
+    ...(profile.profileDirectory ? [`--profile-directory=${profile.profileDirectory}`] : []),
+    '--remote-debugging-address=127.0.0.1',
+    `--remote-debugging-port=${port}`,
+    '--enable-unsafe-extension-debugging',
+    '--no-first-run',
+    '--no-default-browser-check',
+  ];
+  const launched = runtimeHooks.launchProcess(vivaldi.executable, args);
+  const pid = launched.pid;
+  if (!pid || !Number.isInteger(pid) || pid <= 0) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Vivaldi launcher did not return a process identity for bounded cleanup.', { retryable: true });
+  }
+  let session: BrowserCdpSessionLike | undefined;
+  let keepBrowser = false;
+  try {
+    const discovered = await waitForCdpEndpoint(endpoint, timeoutMs);
+    const browserEndpoint = discovered.discoveredEndpoint ?? endpoint;
+    session = await runtimeHooks.connectBrowserCdp(browserEndpoint, Math.max(1_000, Math.min(timeoutMs, 30_000)));
+    const listed = await session.send('Extensions.getExtensions') as { extensions?: BrowserExtensionInfo[] };
+    let verifiedExtension = (listed.extensions ?? []).find((entry) => {
+      if (entry.id !== expectedId || entry.enabled !== true) return false;
+      try { return realpathSync(entry.path) === extensionPath; } catch { return false; }
+    });
+    let runtimeTarget = await browserCdpExtensionTarget(session, expectedId);
+    if (!verifiedExtension || !runtimeTarget) {
+      verifiedExtension = await loadAndVerifyUnpackedExtension(session, extensionPath, expectedId, input.args.enable_in_incognito === true);
+      if (!runtimeTarget) runtimeTarget = await waitForBrowserCdpExtensionTarget(session, expectedId, timeoutMs);
+    }
+    keepBrowser = true;
+    return {
+      provider: 'native-cdp-vivaldi-custom',
+      endpoint,
+      extension: { ...verifiedExtension, runtimeTarget },
+      verified: true,
+    };
+  } finally {
+    await session?.detach?.().catch(() => undefined);
+    if (!keepBrowser) runtimeHooks.signalProcess(pid, 'SIGTERM');
+  }
+}
+
+async function managedCdpInstallExtension(
+  input: AssistantPluginActionExecutionInput,
+  context: BrowserContextLike,
+  extensionPath: string,
+  expectedId: string,
+  runtimeTargetPresent: boolean,
+): Promise<BrowserExtensionInfo> {
+  const browser = context.browser?.();
+  if (!browser || typeof browser.newBrowserCDPSession !== 'function') {
+    throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Managed unpacked-extension install requires browser-level CDP on the launched Chromium context.', { retryable: true });
+  }
+  const session = await browser.newBrowserCDPSession();
+  try {
+    const listed = await session.send('Extensions.getExtensions') as { extensions?: BrowserExtensionInfo[] };
+    const exact = (listed.extensions ?? []).find((entry) => {
+      if (entry.id !== expectedId || entry.enabled !== true) return false;
+      try { return realpathSync(entry.path) === extensionPath; } catch { return false; }
+    });
+    if (exact && runtimeTargetPresent) return exact;
+    return await loadAndVerifyUnpackedExtension(session, extensionPath, expectedId, input.args.enable_in_incognito === true);
+  } finally {
+    await session.detach?.().catch(() => undefined);
+  }
+}
+
+async function cdpInstallExtension(input: AssistantPluginActionExecutionInput, config: BrowserPluginConfig, extensionPath: string, expectedId?: string): Promise<Record<string, unknown> | undefined> {
+  const handle = await browserLevelCdp(input.repoRoot, config);
+  if (!handle) return undefined;
+  try {
+    const exact = await loadAndVerifyUnpackedExtension(handle.session, extensionPath, expectedId, input.args.enable_in_incognito === true);
+    return { provider: 'playwright-cdp', endpoint: handle.endpoint, extension: exact, verified: true };
+  } finally { await closeBrowserLevelCdp(handle); }
+}
+
 async function openAttachedContext(
   runtime: PlaywrightRuntime,
   repoRoot: string,
@@ -2112,6 +2761,7 @@ async function openNativeAttachedContext(
         zeroWindowAttempt.product,
         target.url,
         discovered.attempts,
+        undefined,
         timeout,
       );
       page = created.page as unknown as PageLike;
@@ -2816,11 +3466,15 @@ const EXTRACTION_SCRIPTS = {
   })()`,
 };
 
+function selectorUnavailableInTime(errorMessage: string): boolean {
+  return /timeout|timed out|waiting for selector|selector.*not found|not found.*selector/i.test(errorMessage);
+}
+
 function selectorRepairHint(selector: string, errorMessage: string): string {
   if (/strict mode violation|resolved to \d+ elements/i.test(errorMessage)) {
     return `Selector "${selector}" matched multiple elements. Prefer a unique #id, [data-testid], or more specific path.`;
   }
-  if (/Timeout|waiting for selector|not found/i.test(errorMessage)) {
+  if (selectorUnavailableInTime(errorMessage)) {
     return `Selector "${selector}" was not found in time. Use snapshot_interactive or query_all to discover stable selectors, then retry.`;
   }
   return `Check selector "${selector}" against the current page structure.`;
@@ -3232,7 +3886,7 @@ export function buildBrowserPluginManifest(previousRevision = 0, previousUpdated
     pluginId: BROWSER_PLUGIN_ID,
     provider: 'local-browser',
     displayName: 'Controller Browser Plugin',
-    pluginVersion: '1.1.0',
+    pluginVersion: '1.2.0',
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
@@ -3364,7 +4018,7 @@ async function executeBrowserPluginActionInternal(
           profileMode: nextProfileMode,
           profileDir: nextProfileMode === 'repo_local' ? undefined : nextProfileDir,
           profileDirectory: nextProfileMode === 'repo_local' ? undefined : nextProfileDirectory,
-          browserChannel: nextBrowserChannel ?? 'chromium',
+          browserChannel: nextBrowserChannel ?? (nextExecutablePath ? undefined : 'chromium'),
           executablePath: nextExecutablePath,
           cdpEndpoint: nextCdpEndpoint,
           cdpEndpointCandidates: nextCdpEndpointCandidates,
@@ -3385,6 +4039,71 @@ async function executeBrowserPluginActionInternal(
         await closeManagedContextsForRepo(input.repoRoot);
         return { config, health: health(config, input.repoRoot) };
       }
+      case 'list_unpacked_extensions': {
+        if (current.browserMode === 'attach_preferred') {
+          const cdp = await cdpExtensionList(input.repoRoot, current);
+          if (cdp) return { ...cdp, verified: true };
+          if (current.cdpAttachFallback !== 'managed_persistent') {
+            throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Unpacked-extension control requires a configured browser-level CDP endpoint; refusing to restart or mutate the user-owned native browser.', { retryable: true });
+          }
+        }
+        if (current.browserMode !== 'managed_persistent' && current.cdpAttachFallback !== 'managed_persistent') {
+          throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Selected Browser mode does not provide unpacked-extension control.', { retryable: false });
+        }
+        const profile = selectedProfile(current, input.repoRoot, 'managed_persistent');
+        const pending = managedBrowserContexts.get(managedContextKey(profile));
+        if (!pending) return { provider: 'playwright-persistent-context', extensions: [], verified: true };
+        const state = await pending;
+        const urls = extensionTargets(state.context);
+        const extensions = [...(managedExtensionPaths.get(managedContextKey(profile)) ?? [])].map((path) => {
+          const { expectedId } = unpackedExtensionPath({ ...input, args: { ...input.args, extension_path: path } });
+          const enabled = Boolean(expectedId && urls.some((url) => url.startsWith(`chrome-extension://${expectedId}/`)));
+          return { id: expectedId, path, enabled };
+        });
+        return { provider: 'playwright-persistent-context', extensions, verified: true };
+      }
+      case 'install_unpacked_extension': {
+        const extension = unpackedExtensionPath(input);
+        if (current.browserMode === 'attach_preferred') {
+          const cdp = await cdpInstallExtension(input, current, extension.path, extension.expectedId);
+          if (cdp) return cdp;
+          if (current.cdpAttachFallback !== 'managed_persistent') {
+            throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', 'Unpacked-extension install requires a configured browser-level CDP endpoint; refusing to restart or mutate the user-owned native browser.', { retryable: true });
+          }
+        }
+        if ((current.browserMode !== 'managed_persistent' && current.cdpAttachFallback !== 'managed_persistent') || !extension.expectedId) {
+          throw new AssistantPluginError('PLUGIN_BROWSER_EXTENSION_CONTROL_UNAVAILABLE', extension.expectedId
+            ? 'Selected Browser mode does not provide managed unpacked-extension control.'
+            : 'Managed unpacked-extension verification requires a stable manifest key.', { retryable: false });
+        }
+        const profile = selectedProfile(current, input.repoRoot, 'managed_persistent');
+        const nativeHostChanged = projectManagedNativeMessagingHost(profile.profileDir, extension.nativeHost);
+        if (customVivaldiExtensionInstall(current, input.repoRoot)) {
+          return await installExtensionThroughCustomVivaldiCdpPort(input, current, profile, extension.path, extension.expectedId);
+        }
+        if (!runtimeHooks.moduleAvailable('playwright', input.repoRoot)) {
+          throw new AssistantPluginError('PLUGIN_BROWSER_DEPENDENCY_UNAVAILABLE', 'Managed unpacked-extension install requires Playwright.', { retryable: false });
+        }
+        const runtime = runtimeHooks.loadPlaywright(input.repoRoot);
+        const key = managedContextKey(profile);
+        const paths = managedExtensionPaths.get(key) ?? new Set<string>();
+        const changed = !paths.has(extension.path);
+        paths.add(extension.path);
+        managedExtensionPaths.set(key, paths);
+        if (changed || nativeHostChanged) await evictManagedContext(key);
+        const state = await managedContextState(runtime, input.repoRoot, current, profile);
+        const prefix = `chrome-extension://${extension.expectedId}/`;
+        let runtimeTarget = extensionTargets(state.context).find((candidate) => candidate.startsWith(prefix));
+        const verifiedExtension = await managedCdpInstallExtension(input, state.context, extension.path, extension.expectedId, Boolean(runtimeTarget));
+        if (!runtimeTarget) {
+          runtimeTarget = await waitForManagedExtension(state.context, extension.expectedId, positiveNumber(input.args.timeout_ms, current.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS));
+        }
+        return {
+          provider: 'playwright-persistent-context',
+          extension: { ...verifiedExtension, runtimeTarget },
+          verified: true,
+        };
+      }
       case 'list_sessions': {
         const inventory = await inspectSavedSessions(input.repoRoot, current);
         const requestedLimit = Math.max(1, Math.min(Math.trunc(positiveNumber(input.args.limit, DEFAULT_BROWSER_SESSION_LIST_LIMIT)), MAX_BROWSER_SESSION_LIST_LIMIT));
@@ -4245,10 +4964,14 @@ async function executeBrowserPluginActionInternal(
           });
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          throw new AssistantPluginError('PLUGIN_ACTION_FAILED', message, {
-            retryable: true,
-            details: { selector, repairHint: selectorRepairHint(selector, message) },
-          });
+          throw new AssistantPluginError(
+            selectorUnavailableInTime(message) ? 'PLUGIN_BROWSER_SELECTOR_UNAVAILABLE' : 'PLUGIN_ACTION_FAILED',
+            message,
+            {
+              retryable: true,
+              details: { selector, repairHint: selectorRepairHint(selector, message) },
+            },
+          );
         }
       }
       case 'type':