@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -33,6 +33,13 @@ export function browserPermissions(ready: boolean): AssistantPluginPermissionSco
       granted: ready,
       required: true,
     },
+    {
+      scope: 'browser.extensions',
+      mode: 'write',
+      description: 'List or load bounded unpacked extensions through the existing Browser provider control plane.',
+      granted: ready,
+      required: false,
+    },
   ];
 }
 
@@ -64,6 +71,13 @@ export function browserCapabilities(): AssistantPluginCapability[] {
         'get_console_errors', 'get_failed_requests',
       ],
     },
+    {
+      capabilityId: 'browser-extensions',
+      title: 'Browser Extensions',
+      description: 'List or load unpacked extensions from policy-bounded local directories without exposing raw CDP methods.',
+      scopes: ['browser.extensions', 'browser.profile'],
+      actions: ['list_unpacked_extensions', 'install_unpacked_extension'],
+    },
     {
       capabilityId: 'browser-interaction',
       title: 'Browser Interaction',
@@ -112,11 +126,11 @@ function interactSchema(extra: Record<string, unknown>, required: string[]): Rec
 export function browserActions(): AssistantPluginActionDescriptor[] {
   const readRemote = [
     { resource: 'remote' as const, mode: 'read' as const },
-    { resource: 'repo-state' as const, mode: 'write' as const },
+    { resource: 'provider-state' as const, mode: 'write' as const },
   ];
   const writeRemote = [
     { resource: 'remote' as const, mode: 'exclusive' as const },
-    { resource: 'repo-state' as const, mode: 'write' as const },
+    { resource: 'provider-state' as const, mode: 'write' as const },
   ];
   const descriptors: AssistantPluginActionDescriptor[] = [
     {
@@ -130,7 +144,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       cancellable: true,
       idempotent: true,
       scopes: ['browser.profile'],
-      resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: {
         type: 'object',
         properties: {
@@ -158,12 +172,31 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
         additionalProperties: false,
       },
     },
+    {
+      actionId: 'list_unpacked_extensions',
+      title: 'List unpacked browser extensions',
+      description: 'List unpacked extensions visible to the selected Browser provider. No arbitrary CDP method is accepted.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true,
+      scopes: ['browser.extensions', 'browser.profile'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({}, []),
+    },
+    {
+      actionId: 'install_unpacked_extension',
+      title: 'Install unpacked browser extension',
+      description: 'Load one policy-bounded unpacked extension directory through the selected Browser provider and verify its exact installed identity.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: false, idempotent: false,
+      scopes: ['browser.extensions', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: sessionTargetSchema({
+        extension_path: { type: 'string' },
+        enable_in_incognito: { type: 'boolean' },
+      }, ['extension_path']),
+    },
     {
       actionId: 'create_session',
       title: 'Create browser session',
       description: 'Open an HTTP(S) URL or explicitly adopt the matching frontmost native tab, then persist a reusable session id.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }, ...readRemote],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: readRemote,
       argumentsSchema: sessionTargetSchema({
         extract_text: { type: 'boolean' },
         max_chars: { type: 'number' },
@@ -178,7 +211,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'List browser sessions',
       description: 'List saved browser session metadata without secrets or cookies.',
       readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'read' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'read' }],
       argumentsSchema: {
         type: 'object',
         properties: {
@@ -193,7 +226,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Reconcile browser sessions',
       description: 'Prune only saved managed-session metadata whose exact Runtime-bound page is positively proven gone. Never removes profiles, cookies, or unverified native sessions.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
     },
     {
@@ -201,7 +234,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Close browser session',
       description: 'Remove one saved session metadata record.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: { session_id: { type: 'string' } }, required: ['session_id'], additionalProperties: false },
     },
     {
@@ -209,7 +242,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Clear all browser sessions',
       description: 'Remove all saved session metadata while keeping the profile.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
-      scopes: ['browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
     },
     {
@@ -229,7 +262,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Get browser handoff status',
       description: 'Read durable browser handoff status and reconcile a stale or crashed host.',
       readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'read' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'read' }],
       argumentsSchema: { type: 'object', properties: { interaction_id: { type: 'string' } }, required: ['interaction_id'], additionalProperties: false },
     },
     {
@@ -237,7 +270,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Resolve browser handoff',
       description: 'Resume or cancel a foreground browser handoff.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: {
         type: 'object',
         properties: {
@@ -605,7 +638,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       title: 'Close session',
       description: 'Remove saved session metadata while keeping the persistent profile.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
-      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: { session_id: { type: 'string' } }, required: ['session_id'], additionalProperties: false },
     },
   ];
@@ -618,6 +651,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
   ]);
   return descriptors.map((descriptor) => ({
     ...descriptor,
+    executionMode: 'runtime',
     foregroundEffect: foregroundRequired.has(descriptor.actionId)
       ? 'required'
       : foregroundPossible.has(descriptor.actionId)

package/src/runtime/plugins/browser-native-session-service.ts

@@ -1,9 +1,9 @@
 import { AssistantPluginError } from './errors';
 import {
-  closeMacOsBrowserOwnedTab,
+  closeResolvedMacOsBrowserOwnedTab,
   listMacOsBrowserTabs,
   macOsBrowserPageHandleStale,
-  readMacOsBrowserOwnedTabMetadata,
+  readResolvedMacOsBrowserOwnedTabMetadata,
   type MacOsBrowserProduct,
 } from './browser-macos-bridge';
 import { listSavedBrowserSessions, removeBrowserSession } from './browser-session-store';
@@ -19,12 +19,22 @@ export interface NativeOwnedSessionInspection {
   failedCleanupCount: number;
 }
 
+const MAX_NATIVE_INVENTORY_TIMEOUT_MS = 3_000;
+
+function nativeInventoryTimeoutMs(timeoutMs: number): number {
+  return Math.max(1, Math.min(timeoutMs, MAX_NATIVE_INVENTORY_TIMEOUT_MS));
+}
+
 export function nativeTabInventoryUnsupported(error: unknown): boolean {
   if (error instanceof AssistantPluginError && error.code === 'BROWSER_AUTOMATION_ACTION_UNSUPPORTED') return true;
   const message = error instanceof Error ? error.message : String(error ?? '');
   return /\bBROWSER_AUTOMATION_ACTION_UNSUPPORTED\b/.test(message);
 }
 
+function nativeBrowserApplicationNotRunning(error: unknown): boolean {
+  return error instanceof AssistantPluginError && error.code === 'PLUGIN_BROWSER_NATIVE_APP_NOT_RUNNING';
+}
+
 function isDiscardableNativeOwnedTabUrl(url: string): boolean {
   const normalized = url.trim().toLowerCase();
   return normalized === ''
@@ -35,6 +45,20 @@ function isDiscardableNativeOwnedTabUrl(url: string): boolean {
     || normalized === 'vivaldi://startpage/';
 }
 
+/**
+ * Native tab ids are only stable while the browser keeps the same tab alive.
+ * If a later inventory resolves that id to a different URL, the saved binding
+ * no longer proves ownership of that live tab. Treat the session as detached;
+ * never close the replacement tab merely because it inherited an old id.
+ */
+function nativeTabMatchesSessionUrl(session: BrowserSessionState, url: string): boolean {
+  try {
+    return new URL(session.url).toString() === new URL(url).toString();
+  } catch {
+    return session.url.trim() === url.trim();
+  }
+}
+
 /**
  * Native tab liveness/cleanup belongs to one service so the Browser adapter does
  * not reinterpret stable native identity or prune policy action-by-action.
@@ -75,13 +99,26 @@ export async function inspectNativeOwnedSessions(input: {
     let inventory = inventories.get(product);
     if (!inventory) {
       try {
-        inventory = await listMacOsBrowserTabs(product, timeoutMs);
+        inventory = await listMacOsBrowserTabs(product, nativeInventoryTimeoutMs(timeoutMs));
       } catch (error) {
         inventory = error instanceof Error ? error : new Error(String(error));
       }
       inventories.set(product, inventory);
     }
     if (inventory instanceof Error) {
+      // A plugin-owned tab cannot outlive its native browser process. This is
+      // stronger than an unavailable inventory: retire the stale transport
+      // metadata so a later continuation opens a fresh effect-scoped tab.
+      if (nativeBrowserApplicationNotRunning(inventory)) {
+        const pruned = input.pruneDead === true;
+        if (pruned) {
+          for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+          prunedCount += group.length;
+        }
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_missing', pruned });
+        deadCount += group.length;
+        continue;
+      }
       if (!nativeTabInventoryUnsupported(inventory)) {
         for (const session of group) items.set(session.sessionId, { session, liveness: 'unverified', evidence: 'native_inventory_unavailable', cleanupError: inventory.message });
         unverifiedCount += group.length;
@@ -89,9 +126,9 @@ export async function inspectNativeOwnedSessions(input: {
       }
 
       const ref = { windowId: tab.windowId!, tabId: tab.tabId! };
-      let metadata: Awaited<ReturnType<typeof readMacOsBrowserOwnedTabMetadata>>;
+      let metadata: Awaited<ReturnType<typeof readResolvedMacOsBrowserOwnedTabMetadata>>;
       try {
-        metadata = await readMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
+        metadata = await readResolvedMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
       } catch (metadataError) {
         if (macOsBrowserPageHandleStale(metadataError)) {
           const pruned = input.pruneDead === true;
@@ -113,7 +150,7 @@ export async function inspectNativeOwnedSessions(input: {
         deadCount += group.length;
         if (input.pruneDead === true) {
           try {
-            await closeMacOsBrowserOwnedTab(product, ref, timeoutMs);
+            await closeResolvedMacOsBrowserOwnedTab(product, ref, timeoutMs);
             for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
             prunedCount += group.length;
             closedInvalidCount += 1;
@@ -134,7 +171,7 @@ export async function inspectNativeOwnedSessions(input: {
     }
 
     const live = inventory.tabs.find((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId);
-    if (!live) {
+    if (!live || !nativeTabMatchesSessionUrl(canonical, live.url)) {
       const pruned = input.pruneDead === true;
       if (pruned) {
         for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
@@ -149,7 +186,11 @@ export async function inspectNativeOwnedSessions(input: {
       deadCount += group.length;
       if (input.pruneDead === true) {
         try {
-          await closeMacOsBrowserOwnedTab(product, { windowId: tab.windowId!, tabId: tab.tabId! }, timeoutMs);
+          await closeResolvedMacOsBrowserOwnedTab(
+            product,
+            { windowId: live.windowId, tabId: live.tabId },
+            timeoutMs,
+          );
           for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
           prunedCount += group.length;
           closedInvalidCount += 1;
@@ -189,20 +230,29 @@ export async function closeTrackedNativeOwnedSession(
   const ref = { windowId: tab.windowId, tabId: tab.tabId };
   let inventory: Awaited<ReturnType<typeof listMacOsBrowserTabs>> | undefined;
   try {
-    inventory = await listMacOsBrowserTabs(browser.browserProduct, timeoutMs);
+    inventory = await listMacOsBrowserTabs(browser.browserProduct, nativeInventoryTimeoutMs(timeoutMs));
   } catch (error) {
+    if (nativeBrowserApplicationNotRunning(error)) return { resourceClosed: false, resourceAlreadyMissing: true };
     if (!nativeTabInventoryUnsupported(error)) throw error;
     try {
-      await readMacOsBrowserOwnedTabMetadata(browser.browserProduct, ref, timeoutMs);
+      await readResolvedMacOsBrowserOwnedTabMetadata(browser.browserProduct, ref, timeoutMs);
     } catch (metadataError) {
       if (macOsBrowserPageHandleStale(metadataError)) return { resourceClosed: false, resourceAlreadyMissing: true };
       throw metadataError;
     }
   }
-  if (inventory && !inventory.tabs.some((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId)) {
-    return { resourceClosed: false, resourceAlreadyMissing: true };
+  if (inventory) {
+    const live = inventory.tabs.find((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId);
+    if (!live) return { resourceClosed: false, resourceAlreadyMissing: true };
+    if (!nativeTabMatchesSessionUrl(session, live.url)) return { resourceClosed: false, resourceAlreadyMissing: true };
+    await closeResolvedMacOsBrowserOwnedTab(
+      browser.browserProduct,
+      { windowId: live.windowId, tabId: live.tabId },
+      timeoutMs,
+    );
+    return { resourceClosed: true, resourceAlreadyMissing: false };
   }
-  await closeMacOsBrowserOwnedTab(browser.browserProduct, ref, timeoutMs);
+  await closeResolvedMacOsBrowserOwnedTab(browser.browserProduct, ref, timeoutMs);
   return { resourceClosed: true, resourceAlreadyMissing: false };
 }
 

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

@@ -5,6 +5,19 @@ import {
 } from './browser-adapter';
 import type { AssistantPluginAdapter } from './types';
 
+/** Browser manifests derive from config plus saved-session and active-handoff authority. */
+const BROWSER_MANIFEST_MUTATING_ACTIONS = new Set([
+  'configure',
+  'reconcile_sessions',
+  'close_session',
+  'close_page',
+  'clear_session',
+  'request_human_handoff',
+  'resolve_handoff',
+  'create_session',
+  'open_page',
+]);
+
 /** Thin first-party registration. Browser execution remains an adapter implementation detail. */
 export const browserPluginAdapter: AssistantPluginAdapter = {
   pluginId: 'browser',
@@ -13,4 +26,7 @@ export const browserPluginAdapter: AssistantPluginAdapter = {
   buildManifest: buildBrowserPluginManifest,
   executeAction: executeBrowserPluginAction,
   resolveAuthorizationContext: resolveBrowserPluginAuthorizationContext,
+  shouldRefreshManifestAfterAction(actionId) {
+    return BROWSER_MANIFEST_MUTATING_ACTIONS.has(actionId);
+  },
 };

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

@@ -56,6 +56,8 @@ const READ_ACTIONS = new Set([
   'wait_for_load_state', 'wait_for_selector', 'await_file_transfer',
 ]);
 const SCREENSHOT_ACTIONS = new Set(['screenshot']);
+const INTERNAL_RESOURCE_READ_ACTIONS = new Set(['list_unpacked_extensions']);
+const INTERNAL_RESOURCE_MUTATION_ACTIONS = new Set(['install_unpacked_extension']);
 const TRUSTED_INPUT_ACTIONS = new Set(['trusted_input', 'activate_page']);
 const DOM_INTERACTION_ACTIONS = new Set([
   'create_session', 'open_page', 'navigate', 'reload', 'go_back',
@@ -89,6 +91,12 @@ export function browserRuntimeActionPolicy(actionId: string): BrowserRuntimeActi
   if (SCREENSHOT_ACTIONS.has(actionId)) {
     return { requiredCapabilities: ['browser.screenshot', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
   }
+  if (INTERNAL_RESOURCE_READ_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.internal_resources', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (INTERNAL_RESOURCE_MUTATION_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.internal_resources', 'browser.transaction'], foreground: 'none', replaySafety: 'non_idempotent' };
+  }
   if (TRUSTED_INPUT_ACTIONS.has(actionId)) {
     return {
       requiredCapabilities: ['browser.trusted_input', 'browser.foreground', 'browser.transaction'],
@@ -125,6 +133,9 @@ function stringArgument(args: Record<string, unknown>, key: string): string | un
 }
 
 function stableTargetFor(input: AssistantPluginActionExecutionInput, providerId: string): BrowserTargetIdentity {
+  if (INTERNAL_RESOURCE_READ_ACTIONS.has(input.actionId) || INTERNAL_RESOURCE_MUTATION_ACTIONS.has(input.actionId)) {
+    return { providerId, resourceKind: 'browser_internal_resource', resourceId: 'unpacked-extensions', ownership: 'provider_owned' };
+  }
   const sessionId = stringArgument(input.args, 'session_id');
   const nativeProduct = stringArgument(input.args, 'native_browser_product');
   const nativeWindowId = stringArgument(input.args, 'native_window_id');
@@ -166,7 +177,9 @@ function transactionFor(
     foreground: policy.foreground,
     replaySafety: policy.replaySafety,
     action: {
-      kind: policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
+      kind: INTERNAL_RESOURCE_READ_ACTIONS.has(input.actionId) || INTERNAL_RESOURCE_MUTATION_ACTIONS.has(input.actionId)
+        ? 'internal_resource'
+        : policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
       operation: input.actionId,
       arguments: input.args,
     },

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

@@ -39,8 +39,8 @@ export {
   withRuntimeBrowserSessionExecutionContext as withBrowserSessionAuthorityContext,
 } from '../root/browser-session-composition';
 
-function withContext<T>(controllerHome: string, repoId: string, operation: () => T): T {
-  return withRuntimeBrowserSessionExecutionContext({ controllerHome, repoId }, operation);
+function withContext<T>(controllerHome: string, repoId: string | undefined, operation: () => T): T {
+  return withRuntimeBrowserSessionExecutionContext({ controllerHome, ...(repoId?.trim() ? { repoId: repoId.trim() } : {}) }, operation);
 }
 
 export function ensureLegacyBrowserSessionsImported(controllerHome: string, repoId: string, repoRoot: string): number {

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

@@ -1,5 +1,5 @@
-import { cpSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync } from 'fs';
-import { basename, join, resolve } from 'path';
+import { cpSync, lstatSync, mkdirSync, readlinkSync, rmSync } from 'fs';
+import { join, resolve } from 'path';
 import type {
   ComputerSurfaceProviderBinding,
   ComputerSurfaceTarget,
@@ -12,13 +12,24 @@ import {
   cleanupLegacyBrowserSessionJson,
   readLegacyBrowserSessionMigrationEntries,
 } from './browser-session-legacy-migration';
-import { writeJsonAtomic } from '../shared/json-files';
 import { AssistantPluginError } from './errors';
 
 const BROWSER_STATE_ROOT = '.forge/browser';
 const BROWSER_SESSION_COMPATIBILITY_NAMESPACE = 'browser.session.v1';
 const BROWSER_SESSION_COMPUTER_MIGRATION_ID = 'browser-session-authority-v1-to-computer-surface-v1';
 
+function requireBrowserSessionExecutionContext() {
+  const context = currentRuntimeBrowserSessionExecutionContext();
+  if (!context) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_SESSION_CONTEXT_REQUIRED',
+      'Browser session identity is owned by the Computer target authority and requires an explicit Controller execution context.',
+      { retryable: false },
+    );
+  }
+  return context;
+}
+
 function unique(values: readonly string[]): string[] {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
@@ -109,9 +120,9 @@ function surfaceInput(
  * Browser actions never read or write Browser-owned durable session state.
  */
 export function ensureBrowserSessionsMigratedToComputer(repoRoot: string): number {
-  const context = currentRuntimeBrowserSessionExecutionContext();
-  if (!context) return 0;
+  const context = requireBrowserSessionExecutionContext();
   const computer = runtimeComputerInteractionTargetAuthority();
+  if (!context.repoId) return 0;
   if (computer.compatibilityMigrationMarker(context.controllerHome, BROWSER_SESSION_COMPUTER_MIGRATION_ID, context.repoId)) {
     cleanupLegacyBrowserSessionJson(context.controllerHome, context.repoId, repoRoot);
     return 0;
@@ -146,8 +157,10 @@ export function ensureBrowserSessionsMigratedToComputer(repoRoot: string): numbe
 }
 
 /** Move legacy provider files out of the repository and retire the old path after migration. */
-export function ensureBrowserStateInControllerHome(controllerHome: string, repoId: string, repoRoot: string): string {
-  const targetRoot = join(controllerHome, 'repositories', repoId, 'browser');
+export function ensureBrowserStateInControllerHome(controllerHome: string, repoId: string | undefined, repoRoot: string): string {
+  const targetRoot = repoId
+    ? join(controllerHome, 'repositories', repoId, 'browser')
+    : join(controllerHome, 'browser');
   const compatibilityParent = join(repoRoot, '.forge');
   const compatibilityRoot = join(compatibilityParent, 'browser');
   mkdirSync(targetRoot, { recursive: true });
@@ -178,50 +191,25 @@ export function ensureBrowserStateInControllerHome(controllerHome: string, repoI
 /**
  * Browser semantic identity belongs to Computer SurfaceTarget authority. Provider
  * working state (profiles, screenshots, downloads, diagnostics) remains
- * repository-scoped under Controller Home. Repo-local session JSON exists only
- * for standalone compatibility when no Controller execution context is present.
+ * repository-scoped under Controller Home. Session identity has no standalone
+ * repository-local fallback; callers must supply Controller execution context.
  */
 export function browserStateDir(
   repoRoot: string,
   name: 'sessions' | 'screenshots' | 'profiles' | 'downloads' | 'diagnostics',
 ): string {
   const context = currentRuntimeBrowserSessionExecutionContext();
+  if (name === 'sessions') {
+    const sessionContext = context ?? requireBrowserSessionExecutionContext();
+    return join(ensureBrowserStateInControllerHome(sessionContext.controllerHome, sessionContext.repoId, repoRoot), name);
+  }
   return context
     ? join(ensureBrowserStateInControllerHome(context.controllerHome, context.repoId, repoRoot), name)
     : join(repoRoot, BROWSER_STATE_ROOT, name);
 }
 
-function sessionPath(repoRoot: string, sessionId: string): string {
-  return join(browserStateDir(repoRoot, 'sessions'), `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
-}
-
-function readLegacyBrowserSessionJson(path: string): BrowserSessionState | undefined {
-  let raw: string;
-  try {
-    raw = readFileSync(path, 'utf-8');
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined;
-    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_READ_FAILED', 'Saved browser session metadata could not be read.', {
-      retryable: true,
-      details: { fileName: basename(path), cause: error instanceof Error ? error.message : String(error) },
-    });
-  }
-  try {
-    return JSON.parse(raw) as BrowserSessionState;
-  } catch (error) {
-    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_CORRUPT', 'Saved browser session metadata is malformed; refusing to treat corrupt state as a missing session.', {
-      retryable: false,
-      details: { fileName: basename(path), cause: error instanceof Error ? error.message : String(error) },
-    });
-  }
-}
-
 export function saveBrowserSession(repoRoot: string, session: BrowserSessionState): BrowserSessionState {
-  const context = currentRuntimeBrowserSessionExecutionContext();
-  if (!context) {
-    writeJsonAtomic(sessionPath(repoRoot, session.sessionId), session);
-    return session;
-  }
+  const context = requireBrowserSessionExecutionContext();
   ensureBrowserSessionsMigratedToComputer(repoRoot);
   const computer = runtimeComputerInteractionTargetAuthority();
   const binding = surfaceProviderBinding(session);
@@ -235,7 +223,8 @@ export function saveBrowserSession(repoRoot: string, session: BrowserSessionStat
   if (!existing) {
     existing = computer.upsertSurface(context.controllerHome, surfaceInput(session, {
       aliases: [session.sessionId],
-      repositoryIds: [context.repoId],
+      repositoryIds: context.repoId ? [context.repoId] : [],
+      visibility: context.repoId ? undefined : 'controller',
       includeCompatibility: false,
       reactivate: true,
     })).target;
@@ -248,7 +237,8 @@ export function saveBrowserSession(repoRoot: string, session: BrowserSessionStat
   if (normalized.browser?.sessionResume) normalized.browser.sessionResume.sessionId = canonicalSessionId;
   const saved = computer.upsertSurface(context.controllerHome, surfaceInput(normalized, {
     aliases: [session.sessionId, canonicalSessionId],
-    repositoryIds: [context.repoId],
+    repositoryIds: context.repoId ? [context.repoId] : [],
+    visibility: context.repoId ? undefined : 'controller',
     reactivate: true,
   }));
   return browserSessionFromSurface(saved.target) ?? normalized;
@@ -256,49 +246,29 @@ export function saveBrowserSession(repoRoot: string, session: BrowserSessionStat
 
 export function findBrowserSession(repoRoot: string, sessionId?: string): BrowserSessionState | undefined {
   if (!sessionId) return undefined;
-  const context = currentRuntimeBrowserSessionExecutionContext();
-  if (!context) return readLegacyBrowserSessionJson(sessionPath(repoRoot, sessionId));
+  const context = requireBrowserSessionExecutionContext();
   ensureBrowserSessionsMigratedToComputer(repoRoot);
   const target = runtimeComputerInteractionTargetAuthority().findSurfaceByAlias(context.controllerHome, sessionId, context.repoId);
-  return target ? browserSessionFromSurface(target) : undefined;
+  if (!target || (!context.repoId && target.visibility !== 'controller')) return undefined;
+  return browserSessionFromSurface(target);
 }
 
 export function listSavedBrowserSessions(repoRoot: string): BrowserSessionState[] {
-  const context = currentRuntimeBrowserSessionExecutionContext();
-  if (context) {
-    ensureBrowserSessionsMigratedToComputer(repoRoot);
-    return runtimeComputerInteractionTargetAuthority().listAllSurfaces(context.controllerHome, { repoId: context.repoId })
-      .map(browserSessionFromSurface)
-      .filter((session): session is BrowserSessionState => Boolean(session))
-      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.sessionId.localeCompare(right.sessionId));
-  }
-  const root = browserStateDir(repoRoot, 'sessions');
-  let names: string[];
-  try {
-    names = readdirSync(root);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return [];
-    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_READ_FAILED', 'Saved browser session directory could not be read.', {
-      retryable: true,
-      details: { cause: error instanceof Error ? error.message : String(error) },
-    });
-  }
-  return names
-    .filter((name) => name.endsWith('.json'))
-    .map((name) => readLegacyBrowserSessionJson(join(root, name)))
-    .filter((session): session is BrowserSessionState => Boolean(session));
+  const context = requireBrowserSessionExecutionContext();
+  ensureBrowserSessionsMigratedToComputer(repoRoot);
+  return runtimeComputerInteractionTargetAuthority().listAllSurfaces(context.controllerHome, { repoId: context.repoId })
+    .filter((target) => Boolean(context.repoId) || target.visibility === 'controller')
+    .map(browserSessionFromSurface)
+    .filter((session): session is BrowserSessionState => Boolean(session))
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.sessionId.localeCompare(right.sessionId));
 }
 
 export function removeBrowserSession(repoRoot: string, sessionId: string): void {
-  const context = currentRuntimeBrowserSessionExecutionContext();
-  if (context) {
-    ensureBrowserSessionsMigratedToComputer(repoRoot);
-    const computer = runtimeComputerInteractionTargetAuthority();
-    const target = computer.findSurfaceByAlias(context.controllerHome, sessionId, context.repoId);
-    if (target) computer.tombstoneSurface(context.controllerHome, target.targetId);
-    return;
-  }
-  rmSync(sessionPath(repoRoot, sessionId), { force: true });
+  const context = requireBrowserSessionExecutionContext();
+  ensureBrowserSessionsMigratedToComputer(repoRoot);
+  const computer = runtimeComputerInteractionTargetAuthority();
+  const target = computer.findSurfaceByAlias(context.controllerHome, sessionId, context.repoId);
+  if (target && (context.repoId || target.visibility === 'controller')) computer.tombstoneSurface(context.controllerHome, target.targetId);
 }
 
 export function loadBrowserSession(repoRoot: string, sessionId?: string): BrowserSessionState | undefined {