@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,224 +1,50 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { createHash } from 'crypto';
-import { readdirSync, readFileSync } from 'fs';
-import { join, resolve } from 'path';
+/** @deprecated Compatibility facade. Durable Browser interaction identity belongs to Computer SurfaceTarget authority. */
+import type {
+  BrowserSessionAuthorityPage,
+  BrowserSessionAuthoritySession,
+  BrowserSessionLegacyCutoverRepository,
+  BrowserSessionLegacyCutoverReport,
+  BrowserSessionTombstoneCleanupReport,
+} from '../../../packages/plugin-runtime/browser/session-authority';
 import {
-  listControlPlaneRecords,
-  readControlPlaneRecord,
-  readControlPlaneRecordWithinTransaction,
-  withControlPlaneTransaction,
-  writeControlPlaneRecordWithinTransaction,
-} from '../control-plane/persistence/sqlite-store';
-
-const SESSION_NAMESPACE = 'browser_session';
-const SESSION_SCOPE = 'controller';
-const IMPORT_NAMESPACE = 'browser_session_legacy_import';
-const MAX_AUTHORITY_RECORDS = 5_000;
-export const DEFAULT_BROWSER_SESSION_LIST_LIMIT = 50;
-export const MAX_BROWSER_SESSION_LIST_LIMIT = 200;
-
-export interface BrowserSessionAuthorityContext {
-  controllerHome: string;
-  repoId: string;
-}
-
-export interface BrowserSessionAuthoritySession {
-  schemaVersion: 1;
-  sessionId: string;
-  url: string;
-  title?: string;
-  createdAt: string;
-  updatedAt: string;
-  browser?: {
-    provider?: string;
-    browserProduct?: string;
-    tab?: {
-      windowId?: string;
-      tabId?: string;
-      ownership?: string;
-    };
-  };
-}
-
-interface BrowserSessionAuthorityEntry<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
-  schemaVersion: 1;
-  status: 'active' | 'tombstoned';
-  session: T;
-  aliases: string[];
-  repositoryIds: string[];
-  nativeIdentity?: string;
-  tombstonedAt?: string;
-  importedFromLegacy?: boolean;
-}
-
-interface LegacyImportMarker {
-  schemaVersion: 1;
-  repoId: string;
-  repoRootFingerprint: string;
-  importedAt: string;
-  importedRecordCount: number;
-}
-
-export interface BrowserSessionAuthorityPage<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
-  sessions: T[];
-  limit: number;
-  totalCount: number;
-  nextCursor?: string;
-}
-
-const authorityContextStorage = new AsyncLocalStorage<BrowserSessionAuthorityContext>();
-
-export function withBrowserSessionAuthorityContext<T>(
-  context: BrowserSessionAuthorityContext,
-  operation: () => T,
-): T {
-  return authorityContextStorage.run(context, operation);
-}
-
-export function currentBrowserSessionAuthorityContext(): BrowserSessionAuthorityContext | undefined {
-  return authorityContextStorage.getStore();
-}
-
-function digest(value: string): string {
-  return createHash('sha256').update(value).digest('hex');
-}
-
-function nativeIdentity(session: BrowserSessionAuthoritySession): string | undefined {
-  const browser = session.browser;
-  const tab = browser?.tab;
-  if (browser?.provider !== 'macos-apple-events' || !browser.browserProduct || !tab?.windowId || !tab.tabId) return undefined;
-  return `${browser.provider}:${browser.browserProduct}:${tab.windowId}:${tab.tabId}`;
-}
-
-function recordKey(repoId: string, session: BrowserSessionAuthoritySession): string {
-  const native = nativeIdentity(session);
-  return native ? `native-${digest(native).slice(0, 40)}` : `session-${digest(`${repoId}:${session.sessionId}`).slice(0, 40)}`;
-}
-
-function importMarkerKey(repoRoot: string): string {
-  return digest(resolve(repoRoot)).slice(0, 40);
-}
-
-function unique(values: string[]): string[] {
-  return [...new Set(values.filter(Boolean))].sort();
-}
-
-function parseLegacySession(path: string): BrowserSessionAuthoritySession {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(path, 'utf8'));
-  } catch (error) {
-    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: expected object`);
-  }
-  const session = parsed as Partial<BrowserSessionAuthoritySession>;
-  if (session.schemaVersion !== 1 || typeof session.sessionId !== 'string' || typeof session.url !== 'string'
-    || typeof session.createdAt !== 'string' || typeof session.updatedAt !== 'string') {
-    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: required session fields are missing`);
-  }
-  return session as BrowserSessionAuthoritySession;
-}
-
-function legacySessions(repoRoot: string): BrowserSessionAuthoritySession[] {
-  const root = join(repoRoot, '.forge', 'browser', 'sessions');
-  let names: string[];
-  try {
-    names = readdirSync(root);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return [];
-    throw error;
-  }
-  return names.filter((name) => name.endsWith('.json')).sort().map((name) => parseLegacySession(join(root, name)));
-}
-
-function mergeEntry<T extends BrowserSessionAuthoritySession>(
-  existing: BrowserSessionAuthorityEntry<T> | undefined,
-  repoId: string,
-  session: T,
-  options: { importedFromLegacy?: boolean } = {},
-): BrowserSessionAuthorityEntry<T> {
-  const canonicalSessionId = existing?.session.sessionId ?? session.sessionId;
-  const canonicalCreatedAt = existing?.session.createdAt ?? session.createdAt;
-  const normalizedSession = {
-    ...session,
-    sessionId: canonicalSessionId,
-    createdAt: canonicalCreatedAt,
-  } as T;
-  return {
-    schemaVersion: 1,
-    status: 'active',
-    session: normalizedSession,
-    aliases: unique([...(existing?.aliases ?? []), existing?.session.sessionId ?? '', session.sessionId, canonicalSessionId]),
-    repositoryIds: unique([...(existing?.repositoryIds ?? []), repoId]),
-    nativeIdentity: nativeIdentity(session) ?? existing?.nativeIdentity,
-    importedFromLegacy: options.importedFromLegacy === true || existing?.importedFromLegacy === true,
-  };
+  DEFAULT_BROWSER_SESSION_LIST_LIMIT,
+  MAX_BROWSER_SESSION_LIST_LIMIT,
+} from '../../../packages/plugin-runtime/browser/session-authority';
+import {
+  currentRuntimeBrowserSessionExecutionContext,
+  withRuntimeBrowserSessionExecutionContext,
+} from '../root/browser-session-composition';
+import {
+  ensureBrowserSessionsMigratedToComputer,
+  findBrowserSession as findComputerBackedBrowserSession,
+  listSavedBrowserSessions,
+  removeBrowserSession,
+  saveBrowserSession as saveComputerBackedBrowserSession,
+} from './browser-session-store';
+
+export {
+  DEFAULT_BROWSER_SESSION_LIST_LIMIT,
+  MAX_BROWSER_SESSION_LIST_LIMIT,
+  type BrowserSessionAuthorityContext,
+  type BrowserSessionExecutionContext,
+  type BrowserSessionAuthorityPage,
+  type BrowserSessionAuthoritySession,
+  type BrowserSessionLegacyCutoverRepository,
+  type BrowserSessionLegacyCutoverReport,
+  type BrowserSessionTombstoneCleanupReport,
+} from '../../../packages/plugin-runtime/browser/session-authority';
+
+export {
+  currentRuntimeBrowserSessionExecutionContext as currentBrowserSessionAuthorityContext,
+  withRuntimeBrowserSessionExecutionContext as withBrowserSessionAuthorityContext,
+} from '../root/browser-session-composition';
+
+function withContext<T>(controllerHome: string, repoId: string, operation: () => T): T {
+  return withRuntimeBrowserSessionExecutionContext({ controllerHome, repoId }, operation);
 }
 
 export function ensureLegacyBrowserSessionsImported(controllerHome: string, repoId: string, repoRoot: string): number {
-  const markerKey = importMarkerKey(repoRoot);
-  if (readControlPlaneRecord<LegacyImportMarker>(controllerHome, IMPORT_NAMESPACE, repoId, markerKey)) return 0;
-  const sessions = legacySessions(repoRoot);
-  return withControlPlaneTransaction(controllerHome, (database) => {
-    const marker = readControlPlaneRecordWithinTransaction<LegacyImportMarker>(database, IMPORT_NAMESPACE, repoId, markerKey);
-    if (marker) return 0;
-    let imported = 0;
-    for (const session of sessions) {
-      const key = recordKey(repoId, session);
-      const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
-      const next = mergeEntry(current?.value, repoId, session, { importedFromLegacy: true });
-      writeControlPlaneRecordWithinTransaction(database, {
-        namespace: SESSION_NAMESPACE,
-        scope: SESSION_SCOPE,
-        key,
-        schemaVersion: 1,
-        value: next,
-        expectedRevision: current?.revision ?? null,
-        action: current ? 'legacy_merge' : 'legacy_import',
-      });
-      imported += 1;
-    }
-    writeControlPlaneRecordWithinTransaction(database, {
-      namespace: IMPORT_NAMESPACE,
-      scope: repoId,
-      key: markerKey,
-      schemaVersion: 1,
-      value: {
-        schemaVersion: 1,
-        repoId,
-        repoRootFingerprint: markerKey,
-        importedAt: new Date().toISOString(),
-        importedRecordCount: imported,
-      } satisfies LegacyImportMarker,
-      expectedRevision: null,
-      action: 'legacy_import_complete',
-    });
-    return imported;
-  });
-}
-
-function authorityEntries(controllerHome: string): BrowserSessionAuthorityEntry[] {
-  return listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
-    namespace: SESSION_NAMESPACE,
-    scope: SESSION_SCOPE,
-    limit: MAX_AUTHORITY_RECORDS,
-  }).map((record) => record.value);
-}
-
-function visibleToRepository(entry: BrowserSessionAuthorityEntry, repoId: string): boolean {
-  return Boolean(entry.nativeIdentity) || entry.repositoryIds.includes(repoId);
-}
-
-function activeEntries(controllerHome: string, repoId: string, repoRoot: string): BrowserSessionAuthorityEntry[] {
-  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
-  return authorityEntries(controllerHome)
-    .filter((entry) => entry.status === 'active' && visibleToRepository(entry, repoId))
-    .sort((left, right) => {
-      const updated = right.session.updatedAt.localeCompare(left.session.updatedAt);
-      return updated !== 0 ? updated : left.session.sessionId.localeCompare(right.session.sessionId);
-    });
+  return withContext(controllerHome, repoId, () => ensureBrowserSessionsMigratedToComputer(repoRoot));
 }
 
 export function saveBrowserSession<T extends BrowserSessionAuthoritySession>(
@@ -227,22 +53,7 @@ export function saveBrowserSession<T extends BrowserSessionAuthoritySession>(
   repoRoot: string,
   session: T,
 ): T {
-  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
-  const key = recordKey(repoId, session);
-  return withControlPlaneTransaction(controllerHome, (database) => {
-    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry<T>>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
-    const next = mergeEntry(current?.value, repoId, session);
-    const written = writeControlPlaneRecordWithinTransaction(database, {
-      namespace: SESSION_NAMESPACE,
-      scope: SESSION_SCOPE,
-      key,
-      schemaVersion: 1,
-      value: next,
-      expectedRevision: current?.revision ?? null,
-      action: current ? 'save' : 'create',
-    });
-    return written.value.session;
-  });
+  return withContext(controllerHome, repoId, () => saveComputerBackedBrowserSession(repoRoot, session as never) as unknown as T);
 }
 
 export function findBrowserSession<T extends BrowserSessionAuthoritySession>(
@@ -251,8 +62,7 @@ export function findBrowserSession<T extends BrowserSessionAuthoritySession>(
   repoRoot: string,
   sessionId: string,
 ): T | undefined {
-  return activeEntries(controllerHome, repoId, repoRoot)
-    .find((entry) => entry.session.sessionId === sessionId || entry.aliases.includes(sessionId))?.session as T | undefined;
+  return withContext(controllerHome, repoId, () => findComputerBackedBrowserSession(repoRoot, sessionId) as unknown as T | undefined);
 }
 
 export function listBrowserSessions<T extends BrowserSessionAuthoritySession>(
@@ -261,29 +71,30 @@ export function listBrowserSessions<T extends BrowserSessionAuthoritySession>(
   repoRoot: string,
   options: { limit?: number; cursor?: string } = {},
 ): BrowserSessionAuthorityPage<T> {
-  const entries = activeEntries(controllerHome, repoId, repoRoot);
-  const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? DEFAULT_BROWSER_SESSION_LIST_LIMIT), MAX_BROWSER_SESSION_LIST_LIMIT));
-  let offset = 0;
-  if (options.cursor) {
-    try {
-      const parsed = JSON.parse(Buffer.from(options.cursor, 'base64url').toString('utf8')) as { offset?: unknown };
-      if (!Number.isInteger(parsed.offset) || Number(parsed.offset) < 0) throw new Error('invalid offset');
-      offset = Number(parsed.offset);
-    } catch {
-      throw new Error('PLUGIN_BROWSER_SESSION_CURSOR_INVALID: cursor is invalid or expired');
+  return withContext(controllerHome, repoId, () => {
+    const sessions = listSavedBrowserSessions(repoRoot) as unknown as T[];
+    const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? DEFAULT_BROWSER_SESSION_LIST_LIMIT), MAX_BROWSER_SESSION_LIST_LIMIT));
+    let offset = 0;
+    if (options.cursor) {
+      try {
+        const parsed = JSON.parse(Buffer.from(options.cursor, 'base64url').toString('utf8')) as { offset?: unknown };
+        if (!Number.isInteger(parsed.offset) || Number(parsed.offset) < 0) throw new Error('invalid offset');
+        offset = Number(parsed.offset);
+      } catch {
+        throw new Error('PLUGIN_BROWSER_SESSION_CURSOR_INVALID: cursor is invalid or expired');
+      }
     }
-  }
-  const page = entries.slice(offset, offset + limit);
-  const nextOffset = offset + page.length;
-  const nextCursor = nextOffset < entries.length
-    ? Buffer.from(JSON.stringify({ offset: nextOffset }), 'utf8').toString('base64url')
-    : undefined;
-  return {
-    sessions: page.map((entry) => entry.session as T),
-    limit,
-    totalCount: entries.length,
-    nextCursor,
-  };
+    const page = sessions.slice(offset, offset + limit);
+    const nextOffset = offset + page.length;
+    return {
+      sessions: page,
+      limit,
+      totalCount: sessions.length,
+      nextCursor: nextOffset < sessions.length
+        ? Buffer.from(JSON.stringify({ offset: nextOffset }), 'utf8').toString('base64url')
+        : undefined,
+    };
+  });
 }
 
 export function listAllBrowserSessionsForRepository<T extends BrowserSessionAuthoritySession>(
@@ -291,42 +102,41 @@ export function listAllBrowserSessionsForRepository<T extends BrowserSessionAuth
   repoId: string,
   repoRoot: string,
 ): T[] {
-  return activeEntries(controllerHome, repoId, repoRoot).map((entry) => entry.session as T);
+  return withContext(controllerHome, repoId, () => listSavedBrowserSessions(repoRoot) as unknown as T[]);
 }
 
-export function tombstoneBrowserSession(
-  controllerHome: string,
-  repoId: string,
-  repoRoot: string,
-  sessionId: string,
-): boolean {
-  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
-  const record = listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
-    namespace: SESSION_NAMESPACE,
-    scope: SESSION_SCOPE,
-    limit: MAX_AUTHORITY_RECORDS,
-  }).find((candidate) => {
-    const entry = candidate.value;
-    return entry.status === 'active' && visibleToRepository(entry, repoId)
-      && (entry.session.sessionId === sessionId || entry.aliases.includes(sessionId));
-  });
-  if (!record) return false;
-  return withControlPlaneTransaction(controllerHome, (database) => {
-    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, record.key);
-    if (!current || current.value.status !== 'active') return false;
-    writeControlPlaneRecordWithinTransaction(database, {
-      namespace: SESSION_NAMESPACE,
-      scope: SESSION_SCOPE,
-      key: record.key,
-      schemaVersion: 1,
-      value: {
-        ...current.value,
-        status: 'tombstoned',
-        tombstonedAt: new Date().toISOString(),
-      },
-      expectedRevision: current.revision,
-      action: 'tombstone',
-    });
+export function tombstoneBrowserSession(controllerHome: string, repoId: string, repoRoot: string, sessionId: string): boolean {
+  return withContext(controllerHome, repoId, () => {
+    const existing = findComputerBackedBrowserSession(repoRoot, sessionId);
+    if (!existing) return false;
+    removeBrowserSession(repoRoot, sessionId);
     return true;
   });
 }
+
+/** Browser-owned legacy cutover authority is retired; Computer migration markers own cutover state. */
+export function closeLegacyBrowserSessionImportCutover(
+  _controllerHome: string,
+  repositories: readonly BrowserSessionLegacyCutoverRepository[],
+): BrowserSessionLegacyCutoverReport {
+  return { closed: true, alreadyClosed: true, repositoryCount: repositories.length, migratedRecordCount: 0 };
+}
+
+/** Browser-owned tombstone retention is retired; Computer target retention is authoritative. */
+export function cleanupBrowserSessionTombstones(
+  _controllerHome: string,
+  _options?: { nowMs?: number; ttlMs?: number; maxTombstones?: number; maxRemovals?: number },
+): BrowserSessionTombstoneCleanupReport {
+  return {
+    policyVersion: 'browser-session-tombstone-retention-v1',
+    cutoverClosed: true,
+    inspected: 0,
+    eligible: 0,
+    removed: 0,
+    retained: 0,
+    blockers: [],
+    budgetExhausted: false,
+  };
+}
+
+void currentRuntimeBrowserSessionExecutionContext;

package/src/runtime/plugins/browser-session-legacy-migration.ts

@@ -0,0 +1,203 @@
+import { createHash } from 'crypto';
+import { readdirSync, readFileSync, rmSync } from 'fs';
+import { join, resolve } from 'path';
+import type { BrowserSessionState } from '../../../packages/protocols/browser/index';
+import {
+  listAllControlPlaneRecords,
+  readControlPlaneRecord,
+} from '../control-plane/persistence/sqlite-store';
+import { AssistantPluginError } from './errors';
+
+const LEGACY_SESSION_NAMESPACE = 'browser_session';
+const LEGACY_SESSION_SCOPE = 'controller';
+const LEGACY_IMPORT_NAMESPACE = 'browser_session_legacy_import';
+const LEGACY_IMPORT_CUTOVER_SCOPE = 'controller';
+const LEGACY_IMPORT_CUTOVER_KEY = 'v2-browser-session-import-cutover';
+
+export interface LegacyBrowserSessionMigrationEntry {
+  schemaVersion: 1;
+  status: 'active' | 'tombstoned';
+  session: BrowserSessionState;
+  aliases: string[];
+  repositoryIds: string[];
+  nativeIdentity?: string;
+  tombstonedAt?: string;
+  importedFromLegacy?: boolean;
+}
+
+function digest40(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 40);
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
+}
+
+function nativeIdentity(session: BrowserSessionState): string | undefined {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || !browser.browserProduct || !tab?.windowId || !tab.tabId) return undefined;
+  return `${browser.provider}:${browser.browserProduct}:${tab.windowId}:${tab.tabId}`;
+}
+
+function corruptSession(source: string, message: string, field?: string): never {
+  throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_CORRUPT', message, {
+    retryable: false,
+    details: { source, ...(field ? { field } : {}) },
+  });
+}
+
+function legacyNativeBrowserId(value: unknown, source: string, field: 'windowId' | 'tabId'): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') {
+    const normalized = value.trim();
+    if (normalized) return normalized;
+  }
+  // Before the Browser runtime-contract extraction, macOS native ids were
+  // persisted as integers. Accept only that exact retired representation.
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value);
+  return corruptSession(source, 'Legacy Browser native tab identity is malformed; migration stopped fail-closed.', `browser.tab.${field}`);
+}
+
+function assertSession(value: unknown, source: string): BrowserSessionState {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return corruptSession(source, 'Legacy Browser session metadata is malformed; migration stopped fail-closed.');
+  }
+  const session = structuredClone(value) as Record<string, unknown>;
+  if (session.schemaVersion !== 1 || typeof session.sessionId !== 'string' || typeof session.url !== 'string'
+    || typeof session.createdAt !== 'string' || typeof session.updatedAt !== 'string') {
+    return corruptSession(source, 'Legacy Browser session metadata is missing required fields; migration stopped fail-closed.');
+  }
+  const browser = session.browser;
+  if (browser !== undefined) {
+    if (!browser || typeof browser !== 'object' || Array.isArray(browser)) {
+      return corruptSession(source, 'Legacy Browser connection metadata is malformed; migration stopped fail-closed.', 'browser');
+    }
+    const browserRecord = browser as Record<string, unknown>;
+    const tab = browserRecord.tab;
+    if (tab !== undefined) {
+      if (!tab || typeof tab !== 'object' || Array.isArray(tab)) {
+        return corruptSession(source, 'Legacy Browser tab metadata is malformed; migration stopped fail-closed.', 'browser.tab');
+      }
+      const tabRecord = tab as Record<string, unknown>;
+      const windowId = legacyNativeBrowserId(tabRecord.windowId, source, 'windowId');
+      const tabId = legacyNativeBrowserId(tabRecord.tabId, source, 'tabId');
+      if (windowId === undefined) delete tabRecord.windowId; else tabRecord.windowId = windowId;
+      if (tabId === undefined) delete tabRecord.tabId; else tabRecord.tabId = tabId;
+    }
+  }
+  return session as unknown as BrowserSessionState;
+}
+
+function assertEntry(value: unknown): LegacyBrowserSessionMigrationEntry {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('LEGACY_BROWSER_SESSION_ENTRY_INVALID');
+  const entry = value as Partial<LegacyBrowserSessionMigrationEntry>;
+  if (entry.schemaVersion !== 1 || (entry.status !== 'active' && entry.status !== 'tombstoned')
+    || !Array.isArray(entry.aliases) || !Array.isArray(entry.repositoryIds)) throw new Error('LEGACY_BROWSER_SESSION_ENTRY_INVALID');
+  return {
+    ...(entry as LegacyBrowserSessionMigrationEntry),
+    session: assertSession(entry.session, 'controller-home:sqlite/browser_session'),
+    aliases: unique(entry.aliases),
+    repositoryIds: unique(entry.repositoryIds),
+  };
+}
+
+function legacySessionDirectories(controllerHome: string, repoId: string, repoRoot: string): string[] {
+  return [...new Set([
+    join(repoRoot, '.forge', 'browser', 'sessions'),
+    join(controllerHome, 'repositories', repoId, 'browser', 'sessions'),
+  ].map((path) => resolve(path)))];
+}
+
+function readJsonSessions(controllerHome: string, repoId: string, repoRoot: string): BrowserSessionState[] {
+  const sessions: BrowserSessionState[] = [];
+  for (const root of legacySessionDirectories(controllerHome, repoId, repoRoot)) {
+    let names: string[];
+    try { names = readdirSync(root); } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') continue;
+      throw error;
+    }
+    for (const name of names.filter((entry) => entry.endsWith('.json')).sort()) {
+      let parsed: unknown;
+      try { parsed = JSON.parse(readFileSync(join(root, name), 'utf8')); } catch (error) {
+        throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_CORRUPT', 'Legacy Browser session JSON is malformed; migration stopped fail-closed.', {
+          retryable: false,
+          details: { fileName: name, cause: error instanceof Error ? error.message : String(error) },
+        });
+      }
+      sessions.push(assertSession(parsed, name));
+    }
+  }
+  return sessions;
+}
+
+function legacyJsonImportAllowed(controllerHome: string, repoId: string, repoRoot: string): boolean {
+  const globalCutover = readControlPlaneRecord<{ status?: string }>(
+    controllerHome,
+    LEGACY_IMPORT_NAMESPACE,
+    LEGACY_IMPORT_CUTOVER_SCOPE,
+    LEGACY_IMPORT_CUTOVER_KEY,
+  );
+  if (globalCutover?.value.status === 'closed') return false;
+  const markerKey = digest40(resolve(repoRoot));
+  return !readControlPlaneRecord(controllerHome, LEGACY_IMPORT_NAMESPACE, repoId, markerKey);
+}
+
+function mergeLegacyJson(entries: LegacyBrowserSessionMigrationEntry[], repoId: string, session: BrowserSessionState): void {
+  const native = nativeIdentity(session);
+  const index = entries.findIndex((entry) => native
+    ? entry.nativeIdentity === native
+    : !entry.nativeIdentity && entry.repositoryIds.includes(repoId)
+      && (entry.session.sessionId === session.sessionId || entry.aliases.includes(session.sessionId)));
+  const current = index >= 0 ? entries[index] : undefined;
+  if (current?.status === 'tombstoned') return;
+  if (current) {
+    entries[index] = {
+      ...current,
+      status: 'active',
+      session: { ...session, sessionId: current.session.sessionId, createdAt: current.session.createdAt },
+      aliases: unique([...current.aliases, current.session.sessionId, session.sessionId]),
+      repositoryIds: unique([...current.repositoryIds, repoId]),
+      nativeIdentity: native ?? current.nativeIdentity,
+      importedFromLegacy: true,
+    };
+    return;
+  }
+  entries.push({
+    schemaVersion: 1,
+    status: 'active',
+    session,
+    aliases: [session.sessionId],
+    repositoryIds: [repoId],
+    ...(native ? { nativeIdentity: native } : {}),
+    importedFromLegacy: true,
+  });
+}
+
+/** Read-only compatibility reader. It can consume retired Browser state but cannot mutate that authority. */
+export function readLegacyBrowserSessionMigrationEntries(input: {
+  controllerHome: string;
+  repoId: string;
+  repoRoot: string;
+}): LegacyBrowserSessionMigrationEntry[] {
+  const entries = listAllControlPlaneRecords<LegacyBrowserSessionMigrationEntry>(input.controllerHome, {
+    namespace: LEGACY_SESSION_NAMESPACE,
+    scope: LEGACY_SESSION_SCOPE,
+  }).map((record) => assertEntry(record.value));
+  if (legacyJsonImportAllowed(input.controllerHome, input.repoId, input.repoRoot)) {
+    for (const session of readJsonSessions(input.controllerHome, input.repoId, input.repoRoot)) mergeLegacyJson(entries, input.repoId, session);
+  }
+  return entries;
+}
+
+/** Repo-local/controller-home JSON is import-only. Removal after Computer migration is best-effort and idempotent. */
+export function cleanupLegacyBrowserSessionJson(controllerHome: string, repoId: string, repoRoot: string): void {
+  for (const root of legacySessionDirectories(controllerHome, repoId, repoRoot)) {
+    let names: string[];
+    try { names = readdirSync(root); } catch { continue; }
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      try { rmSync(join(root, name), { force: true }); } catch { /* retry on a later Browser access */ }
+    }
+  }
+}