@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/plugins/capability-authorization-grants.ts

@@ -1,5 +1,13 @@
+import {
+  findActiveCanonicalGrant,
+  listCanonicalGrants,
+  reconcileCanonicalGrants,
+  recordCanonicalGrant,
+  revokeCanonicalGrant,
+  type Grant,
+} from '../../../packages/kernel/identity/api/index';
 import { randomUUID } from 'crypto';
-import { existsSync, mkdirSync } from 'fs';
+import { existsSync, renameSync } from 'fs';
 import { join } from 'path';
 import { controllerSystemRoot } from '../../cli/repositories/controller-home';
 import { ControllerLockContentionError, withControllerLock } from '../../cli/repositories/locks';
@@ -31,7 +39,7 @@ export interface PluginCapabilityAuthorizationGrant {
   schemaVersion: 1;
   grantId: string;
   ownerScope: string;
-  repoId: string;
+  repoId?: string;
   pluginId: string;
   capabilityId: string;
   target: AssistantPluginAuthorizationTarget;
@@ -51,7 +59,7 @@ interface PluginCapabilityAuthorizationGrantStore {
 
 export interface PluginCapabilityAuthorizationQuery {
   ownerScope: string;
-  repoId: string;
+  repoId?: string;
   pluginId: string;
   capabilityId: string;
   target: AssistantPluginAuthorizationTarget;
@@ -73,12 +81,19 @@ export interface RevokePluginCapabilityAuthorizationInput {
   now?: Date;
 }
 
-const RISK_RANK: Record<AssistantPluginActionRisk, number> = {
-  readonly: 0,
-  workspace_write: 1,
-  remote_write: 2,
-  destructive: 3,
-};
+export interface ReconcilePluginCapabilityAuthorizationsInput {
+  retiredOwnerScopes?: readonly string[];
+  now?: Date;
+}
+
+export interface ReconcilePluginCapabilityAuthorizationsResult {
+  removedRetiredOwner: number;
+  removedRevoked: number;
+  removedExpired: number;
+  removedTotal: number;
+  remaining: number;
+  changed: boolean;
+}
 
 const GENERIC_PLUGIN_AUTHORIZATION_ACTORS = new Set(['', 'anonymous', 'plugin_action_execute']);
 
@@ -156,7 +171,10 @@ function validatePersistedGrant(value: unknown, index: number): PluginCapability
     schemaVersion: 1,
     grantId: string('grantId'),
     ownerScope: string('ownerScope'),
-    repoId: string('repoId'),
+    // Pre-canonical plugin grants could omit repoId for controller/account targets.
+    // Normalize that omission once during the one-way migration; authorization
+    // against the canonical Grant store is exact after this point.
+    repoId: typeof record.repoId === 'string' && record.repoId.trim() ? record.repoId.trim() : 'controller:global',
     pluginId: string('pluginId'),
     capabilityId: string('capabilityId'),
     target: normalizeTarget({
@@ -180,6 +198,41 @@ export function pluginCapabilityAuthorizationGrantStorePath(controllerHome: stri
   return join(controllerSystemRoot(controllerHome), 'plugin-capability-authorizations', 'grants.json');
 }
 
+function legacyPluginGrantMigrationMarkerPath(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'plugin-capability-authorizations', 'migration.json');
+}
+
+/**
+ * Durable proof that this Controller Home already ran the one-way migration, so
+ * authorization reads stop consulting the legacy file at all.
+ */
+interface LegacyPluginGrantMigrationMarker {
+  schemaVersion: 1;
+  migratedAt: string;
+  legacyGrantCount: number;
+  canonicalGrantCount: number;
+}
+
+function readLegacyPluginGrantMigrationMarker(controllerHome: string): LegacyPluginGrantMigrationMarker | undefined {
+  const path = legacyPluginGrantMigrationMarkerPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const raw = readJsonFile<Record<string, unknown>>(path);
+    if (raw?.schemaVersion !== 1
+      || typeof raw.migratedAt !== 'string'
+      || typeof raw.legacyGrantCount !== 'number'
+      || typeof raw.canonicalGrantCount !== 'number') {
+      throw new Error('migration marker schema is invalid');
+    }
+    return raw as unknown as LegacyPluginGrantMigrationMarker;
+  } catch (error) {
+    throw new PluginCapabilityAuthorizationGrantError(
+      'PLUGIN_CAPABILITY_GRANT_STORE_CORRUPT',
+      `Plugin capability authorization migration marker is corrupt: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
 function loadStore(controllerHome: string): PluginCapabilityAuthorizationGrantStore {
   const path = pluginCapabilityAuthorizationGrantStorePath(controllerHome);
   if (!existsSync(path)) return { schemaVersion: 1, grants: [] };
@@ -197,21 +250,123 @@ function loadStore(controllerHome: string): PluginCapabilityAuthorizationGrantSt
   }
 }
 
-function saveStore(controllerHome: string, store: PluginCapabilityAuthorizationGrantStore): void {
-  const path = pluginCapabilityAuthorizationGrantStorePath(controllerHome);
-  mkdirSync(join(controllerSystemRoot(controllerHome), 'plugin-capability-authorizations'), { recursive: true });
-  writeJsonAtomic(path, store);
+function pluginMetadataFromCanonicalGrant(grant: Grant): { pluginId: string; capabilityId: string } | undefined {
+  const constraints = grant.constraints;
+  if (!constraints || constraints.kind !== 'plugin_capability_authorization') return undefined;
+  const pluginId = typeof constraints.pluginId === 'string' ? constraints.pluginId.trim() : '';
+  const capabilityId = typeof constraints.capabilityId === 'string' ? constraints.capabilityId.trim() : '';
+  return pluginId && capabilityId ? { pluginId, capabilityId } : undefined;
+}
+
+function pluginGrantFromCanonical(
+  grant: Grant,
+  fallback?: { pluginId: string; capabilityId: string; repoId?: string; target?: AssistantPluginAuthorizationTarget },
+): PluginCapabilityAuthorizationGrant | undefined {
+  const metadata = pluginMetadataFromCanonicalGrant(grant)
+    ?? (fallback ? { pluginId: fallback.pluginId, capabilityId: fallback.capabilityId } : undefined);
+  if (!metadata || !grant.target) return undefined;
+  if (grant.riskCeiling === 'destructive') return undefined;
+  const ownerScope = grant.ownerScope?.trim() || grant.principalId.trim();
+  if (!ownerScope) return undefined;
+  const target: AssistantPluginAuthorizationTarget = {
+    kind: grant.target.kind,
+    id: grant.target.id,
+    ...(grant.target.identityFingerprint ? { identityFingerprint: grant.target.identityFingerprint } : fallback?.target?.identityFingerprint ? { identityFingerprint: fallback.target.identityFingerprint } : {}),
+  };
+  return {
+    schemaVersion: 1,
+    grantId: grant.grantId,
+    ownerScope,
+    repoId: grant.target.repoId ?? fallback?.repoId ?? 'controller:global',
+    pluginId: metadata.pluginId,
+    capabilityId: metadata.capabilityId,
+    target,
+    scopes: [...(grant.scopes ?? [])],
+    riskCeiling: grant.riskCeiling ?? 'readonly',
+    createdAt: grant.createdAt,
+    updatedAt: grant.updatedAt,
+    expiresAt: grant.expiresAt,
+    ...(grant.revokedAt ? { revokedAt: grant.revokedAt } : {}),
+    ...(grant.revokedReason ? { revokedReason: grant.revokedReason } : {}),
+  };
 }
 
-function targetMatches(left: AssistantPluginAuthorizationTarget, right: AssistantPluginAuthorizationTarget): boolean {
-  return left.kind === right.kind
-    && left.id === right.id
-    && (left.identityFingerprint ?? '') === (right.identityFingerprint ?? '');
+function recordCanonicalPluginGrant(
+  controllerHome: string,
+  grant: PluginCapabilityAuthorizationGrant,
+  now?: Date,
+): PluginCapabilityAuthorizationGrant {
+  const expiresInMinutes = Math.max(1, Math.ceil((Date.parse(grant.expiresAt) - (now ?? new Date()).getTime()) / 60_000));
+  const canonical = recordCanonicalGrant(controllerHome, {
+    grantId: grant.grantId,
+    principalId: grant.ownerScope,
+    ownerScope: grant.ownerScope,
+    capabilities: [`${grant.pluginId}:${grant.capabilityId}`, grant.capabilityId],
+    target: {
+      kind: grant.target.kind,
+      id: grant.target.id,
+      repoId: grant.repoId,
+      ...(grant.target.identityFingerprint ? { identityFingerprint: grant.target.identityFingerprint } : {}),
+    },
+    scopes: grant.scopes,
+    riskCeiling: grant.riskCeiling,
+    constraints: { kind: 'plugin_capability_authorization', pluginId: grant.pluginId, capabilityId: grant.capabilityId },
+    expiresInMinutes,
+    now,
+  });
+  return pluginGrantFromCanonical(canonical, grant)!;
 }
 
-function scopesContain(granted: readonly string[], requested: readonly string[]): boolean {
-  const available = new Set(granted);
-  return requested.every((scope) => available.has(scope));
+/**
+ * One-way migration input. The legacy plugin grant file is read-only history:
+ * every still-authorizable legacy grant is copied into the canonical Grant
+ * authority exactly once, and this module never writes the legacy file again.
+ * A corrupt migration input still fails closed so un-migrated grants cannot be
+ * silently dropped.
+ *
+ * Removal trigger: once a released Runtime baseline has shipped with the
+ * `migration.json` marker (so every install has migrated at least once), delete
+ * this migration, `loadStore`/`validatePersistedGrant`, the legacy path getter
+ * and the PLUGIN_CAPABILITY_GRANT_STORE_CORRUPT error code in the same slice.
+ * The archived `grants.json.migrated-*` file is recoverable history, not input.
+ */
+function migrateLegacyPluginCapabilityGrants(controllerHome: string, at = new Date()): void {
+  if (readLegacyPluginGrantMigrationMarker(controllerHome)) return;
+  const legacyGrants = loadStore(controllerHome).grants;
+  const canonicalById = new Map(listCanonicalGrants(controllerHome).map((grant) => [grant.grantId, grant]));
+  const atMs = at.getTime();
+  for (const grant of legacyGrants) {
+    if (grant.revokedAt) continue;
+    if (Date.parse(grant.expiresAt) <= atMs) continue;
+    const existing = canonicalById.get(grant.grantId);
+    if (existing) {
+      // A canonical row written before plugin metadata existed cannot be projected
+      // back into a plugin grant. Repair it in place instead of leaving a live grant
+      // that neither list nor by-id resolution can see.
+      if (existing.revokedAt || pluginMetadataFromCanonicalGrant(existing)) continue;
+      recordCanonicalPluginGrant(controllerHome, grant, new Date(grant.createdAt));
+      continue;
+    }
+    recordCanonicalPluginGrant(controllerHome, grant, new Date(grant.createdAt));
+    canonicalById.set(grant.grantId, { grantId: grant.grantId } as Grant);
+  }
+  // The migration is complete for this Controller Home: prove it durably, then
+  // move the legacy file aside so no authorization read can ever depend on it
+  // again. The archive is recoverable; a failed rename leaves an inert file.
+  writeJsonAtomic(legacyPluginGrantMigrationMarkerPath(controllerHome), {
+    schemaVersion: 1,
+    migratedAt: at.toISOString(),
+    legacyGrantCount: legacyGrants.length,
+    canonicalGrantCount: listCanonicalGrants(controllerHome).length,
+  } satisfies LegacyPluginGrantMigrationMarker);
+  const legacyPath = pluginCapabilityAuthorizationGrantStorePath(controllerHome);
+  if (existsSync(legacyPath)) {
+    try {
+      renameSync(legacyPath, `${legacyPath}.migrated-${at.getTime()}`);
+    } catch {
+      // Inert history; the marker already prevents any further legacy read.
+    }
+  }
 }
 
 export function findActivePluginCapabilityAuthorization(
@@ -220,22 +375,21 @@ export function findActivePluginCapabilityAuthorization(
 ): PluginCapabilityAuthorizationGrant | undefined {
   if (query.risk === 'destructive') return undefined;
   const ownerScope = required(query.ownerScope, 'ownerScope');
-  const repoId = required(query.repoId, 'repoId');
+  const repoId = (query.repoId?.trim()) || 'controller:global';
   const pluginId = required(query.pluginId, 'pluginId');
   const capabilityId = required(query.capabilityId, 'capabilityId');
   const target = normalizeTarget(query.target);
   const scopes = normalizeScopes(query.scopes);
-  const atMs = (query.at ?? new Date()).getTime();
-  return loadStore(controllerHome).grants
-    .filter((grant) => !grant.revokedAt && Date.parse(grant.expiresAt) > atMs)
-    .filter((grant) => grant.ownerScope === ownerScope
-      && grant.repoId === repoId
-      && grant.pluginId === pluginId
-      && grant.capabilityId === capabilityId
-      && targetMatches(grant.target, target)
-      && scopesContain(grant.scopes, scopes)
-      && RISK_RANK[grant.riskCeiling] >= RISK_RANK[query.risk])
-    .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0];
+  migrateLegacyPluginCapabilityGrants(controllerHome, query.at ?? new Date());
+  const canonical = findActiveCanonicalGrant(controllerHome, {
+    ownerScope,
+    capability: `${pluginId}:${capabilityId}`,
+    target: { kind: target.kind, id: target.id, repoId, ...(target.identityFingerprint ? { identityFingerprint: target.identityFingerprint } : {}) },
+    scopes,
+    risk: query.risk,
+    at: query.at,
+  });
+  return canonical ? pluginGrantFromCanonical(canonical, { pluginId, capabilityId, repoId, target }) : undefined;
 }
 
 /**
@@ -250,9 +404,12 @@ export function findActivePluginCapabilityAuthorizationById(
 ): PluginCapabilityAuthorizationGrant | undefined {
   const normalizedGrantId = required(grantId, 'grantId');
   const atMs = at.getTime();
-  const grant = loadStore(controllerHome).grants.find((entry) => entry.grantId === normalizedGrantId);
-  if (!grant || grant.revokedAt || Date.parse(grant.expiresAt) <= atMs) return undefined;
-  return structuredClone(grant);
+  migrateLegacyPluginCapabilityGrants(controllerHome, at);
+  const canonical = listCanonicalGrants(controllerHome).find((entry) => entry.grantId === normalizedGrantId);
+  if (canonical && !canonical.revokedAt && Date.parse(canonical.expiresAt) > atMs) {
+    return pluginGrantFromCanonical(canonical);
+  }
+  return undefined;
 }
 
 export function recordPluginCapabilityAuthorization(
@@ -267,7 +424,7 @@ export function recordPluginCapabilityAuthorization(
   }
   const now = input.now ?? new Date();
   const ownerScope = required(input.ownerScope, 'ownerScope');
-  const repoId = required(input.repoId, 'repoId');
+  const repoId = (input.repoId?.trim()) || 'controller:global';
   const pluginId = required(input.pluginId, 'pluginId');
   const capabilityId = required(input.capabilityId, 'capabilityId');
   const target = normalizeTarget(input.target);
@@ -278,6 +435,7 @@ export function recordPluginCapabilityAuthorization(
   }
   const expiresInMinutes = Math.min(Math.max(1, Math.trunc(rawMinutes)), MAX_PLUGIN_CAPABILITY_GRANT_MINUTES);
   const timestamp = now.toISOString();
+  migrateLegacyPluginCapabilityGrants(controllerHome, now);
   const grant: PluginCapabilityAuthorizationGrant = {
     schemaVersion: 1,
     grantId: `plugin-grant-${randomUUID()}`,
@@ -298,16 +456,19 @@ export function recordPluginCapabilityAuthorization(
       { scope: 'global', resource: 'plugin-capability-authorization-grants' },
       `plugin-capability-grant:${ownerScope}`,
       () => {
-        const store = loadStore(controllerHome);
-        store.grants = store.grants.filter((entry) => !(entry.ownerScope === ownerScope
-          && entry.repoId === repoId
-          && entry.pluginId === pluginId
-          && entry.capabilityId === capabilityId
-          && entry.target.kind === target.kind
-          && entry.target.id === target.id));
-        store.grants.push(grant);
-        saveStore(controllerHome, store);
-        return grant;
+        const canonicalGrant = recordCanonicalGrant(controllerHome, {
+          grantId: grant.grantId,
+          principalId: grant.ownerScope,
+          ownerScope: grant.ownerScope,
+          capabilities: [`${grant.pluginId}:${grant.capabilityId}`, grant.capabilityId],
+          target: { kind: grant.target.kind, id: grant.target.id, repoId: grant.repoId, ...(grant.target.identityFingerprint ? { identityFingerprint: grant.target.identityFingerprint } : {}) },
+          scopes: grant.scopes,
+          riskCeiling: grant.riskCeiling,
+          constraints: { kind: 'plugin_capability_authorization', pluginId: grant.pluginId, capabilityId: grant.capabilityId },
+          expiresInMinutes,
+          now,
+        });
+        return pluginGrantFromCanonical(canonicalGrant, grant)!;
       },
       5_000,
     );
@@ -333,22 +494,56 @@ export function revokePluginCapabilityAuthorization(
       { scope: 'global', resource: 'plugin-capability-authorization-grants' },
       `plugin-capability-revoke:${ownerScope}`,
       () => {
-        const store = loadStore(controllerHome);
-        const index = store.grants.findIndex((grant) => grant.grantId === grantId);
-        if (index < 0) throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_NOT_FOUND', `Grant ${grantId} was not found.`);
-        const current = store.grants[index]!;
+        const current = findActivePluginCapabilityAuthorizationById(controllerHome, grantId, now);
+        if (!current) throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_NOT_FOUND', `Grant ${grantId} was not found.`);
         if (current.ownerScope !== ownerScope) {
           throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_OWNER_MISMATCH', `Grant ${grantId} belongs to another owner scope.`);
         }
-        const revoked: PluginCapabilityAuthorizationGrant = {
-          ...current,
-          updatedAt: now.toISOString(),
-          revokedAt: now.toISOString(),
-          revokedReason: reason,
+        const canonical = revokeCanonicalGrant(controllerHome, { grantId, ownerScope, reason, now });
+        return pluginGrantFromCanonical(canonical, current)!;
+      },
+      5_000,
+    );
+  } catch (error) {
+    if (error instanceof ControllerLockContentionError) {
+      throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_STORE_BUSY', error.message);
+    }
+    throw error;
+  }
+}
+
+export function reconcilePluginCapabilityAuthorizations(
+  controllerHome: string,
+  input: ReconcilePluginCapabilityAuthorizationsInput = {},
+): ReconcilePluginCapabilityAuthorizationsResult {
+  const retiredOwnerScopes = new Set(
+    (input.retiredOwnerScopes ?? [])
+      .map((ownerScope) => required(ownerScope, 'retiredOwnerScopes[]')),
+  );
+  const nowMs = (input.now ?? new Date()).getTime();
+  try {
+    return withControllerLock(
+      controllerHome,
+      { scope: 'global', resource: 'plugin-capability-authorization-grants' },
+      'plugin-capability-reconcile',
+      () => {
+        void nowMs;
+        migrateLegacyPluginCapabilityGrants(controllerHome, input.now ?? new Date());
+        const canonical = reconcileCanonicalGrants(controllerHome, {
+          retiredOwnerScopes: [...retiredOwnerScopes],
+          now: input.now,
+        });
+        const grants = listCanonicalGrants(controllerHome)
+          .map((grant) => pluginGrantFromCanonical(grant))
+          .filter((grant): grant is PluginCapabilityAuthorizationGrant => Boolean(grant));
+        return {
+          removedRetiredOwner: canonical.removedRetiredOwner,
+          removedRevoked: canonical.removedRevoked,
+          removedExpired: canonical.removedExpired,
+          removedTotal: canonical.removedTotal,
+          remaining: grants.length,
+          changed: canonical.changed,
         };
-        store.grants[index] = revoked;
-        saveStore(controllerHome, store);
-        return revoked;
       },
       5_000,
     );
@@ -364,8 +559,9 @@ export function listPluginCapabilityAuthorizations(
   controllerHome: string,
   ownerScope?: string,
 ): PluginCapabilityAuthorizationGrant[] {
+  migrateLegacyPluginCapabilityGrants(controllerHome);
   const normalizedOwner = ownerScope?.trim();
-  return loadStore(controllerHome).grants
-    .filter((grant) => !normalizedOwner || grant.ownerScope === normalizedOwner)
-    .map((grant) => structuredClone(grant));
+  return listCanonicalGrants(controllerHome, normalizedOwner ? { ownerScope: normalizedOwner } : undefined)
+    .map((grant) => pluginGrantFromCanonical(grant))
+    .filter((grant): grant is PluginCapabilityAuthorizationGrant => Boolean(grant));
 }

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

@@ -0,0 +1,219 @@
+import { createHash, randomUUID } from 'crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { loadRuntimeReleaseManifest } from '../root/release-manifest';
+import { readRuntimeReleaseAuthority } from '../root/release-store';
+import { ensureBrowserStateInControllerHome } from './browser-session-store';
+import { renderWorkflowSupervisorNativeManifest } from '../../../supervisor/native-messaging/manifest';
+import { WORKFLOW_SUPERVISOR_NATIVE_HOST_NAME } from '../../../supervisor/native-messaging/host';
+
+const EXTENSION_FILES = ['manifest.json', 'background.js', 'content.js', 'core.js'] as const;
+const FORGE_NATIVE_MESSAGING_DECLARATION = 'forge-native-messaging-host.json';
+
+export interface WorkflowSupervisorBrowserInstallation {
+  browser: 'chrome' | 'chrome-for-testing' | 'chromium' | 'vivaldi' | 'forge-managed';
+  nativeMessagingRoot: string;
+}
+interface ActiveBrowserAdapterRelease {
+  releaseId: string;
+  extensionSourcePath: string;
+  nativeHostSourcePath: string;
+  nativeHostArtifactIdentity: string;
+}
+export interface WorkflowSupervisorBrowserAdapterDependencies {
+  homeDir?: string;
+  browserInstallations?: readonly WorkflowSupervisorBrowserInstallation[];
+  activeRelease?: (controllerHome: string) => ActiveBrowserAdapterRelease;
+  repository?: { repoId: string; repoRoot: string };
+}
+export interface WorkflowSupervisorBrowserAdapterStatus {
+  state: 'ready' | 'not_installed' | 'projection_stale' | 'runtime_release_incomplete';
+  extensionPath: string;
+  extensionId?: string;
+  nativeHostPath: string;
+  activeReleaseId?: string;
+  nativeManifestPaths: string[];
+  projectionCurrent: boolean;
+  detail: string;
+}
+
+function sha256(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+export function workflowSupervisorExtensionIdFromManifestKey(value: string): string {
+  const key = value.trim();
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(key)) throw new Error('WORKFLOW_SUPERVISOR_EXTENSION_KEY_INVALID');
+  const bytes = Buffer.from(key, 'base64');
+  if (bytes.length < 64 || bytes.toString('base64').replace(/=+$/,'') !== key.replace(/=+$/,'')) {
+    throw new Error('WORKFLOW_SUPERVISOR_EXTENSION_KEY_INVALID');
+  }
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 32)
+    .replace(/[0-9a-f]/g, (nibble) => String.fromCharCode(97 + Number.parseInt(nibble, 16)));
+}
+function extensionId(path: string): string {
+  const manifest = JSON.parse(readFileSync(join(path, 'manifest.json'), 'utf8')) as { key?: unknown };
+  if (typeof manifest.key !== 'string') throw new Error('WORKFLOW_SUPERVISOR_EXTENSION_KEY_REQUIRED');
+  return workflowSupervisorExtensionIdFromManifestKey(manifest.key);
+}
+function controllerPaths(controllerHome: string) {
+  const root = join(resolveControllerHome(controllerHome), 'supervisor', 'browser-adapter');
+  return {
+    extensionPath: join(root, 'chrome-extension'),
+    nativeHostPath: join(root, 'forge-workflow-supervisor-native-host'),
+  };
+}
+function defaultBrowserInstallations(
+  controllerHome: string,
+  homeDir = process.env.HOME ?? homedir(),
+  repository?: { repoId: string; repoRoot: string },
+): WorkflowSupervisorBrowserInstallation[] {
+  const installations: WorkflowSupervisorBrowserInstallation[] = [
+    { browser: 'chrome', nativeMessagingRoot: join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome', 'NativeMessagingHosts') },
+    { browser: 'chrome-for-testing', nativeMessagingRoot: join(homeDir, 'Library', 'Application Support', 'Google', 'ChromeForTesting', 'NativeMessagingHosts') },
+    { browser: 'chromium', nativeMessagingRoot: join(homeDir, 'Library', 'Application Support', 'Chromium', 'NativeMessagingHosts') },
+    { browser: 'vivaldi', nativeMessagingRoot: join(homeDir, 'Library', 'Application Support', 'Vivaldi', 'NativeMessagingHosts') },
+  ];
+  if (repository) {
+    const browserStateRoot = ensureBrowserStateInControllerHome(controllerHome, repository.repoId, repository.repoRoot);
+    installations.push({ browser: 'forge-managed', nativeMessagingRoot: join(browserStateRoot, 'profiles', 'default', 'NativeMessagingHosts') });
+  }
+  return installations;
+}
+function activeBrowserAdapterRelease(controllerHome: string): ActiveBrowserAdapterRelease {
+  const home = resolveControllerHome(controllerHome);
+  const authority = readRuntimeReleaseAuthority(home);
+  if (!authority) throw new Error('WORKFLOW_SUPERVISOR_BROWSER_RUNTIME_RELEASE_MISSING');
+  const manifest = loadRuntimeReleaseManifest(authority.active.manifestPath, home);
+  if (!manifest.packageRoot || !manifest.workflowSupervisorNativeHostEntrypoint || !manifest.workflowSupervisorNativeHostArtifactIdentity) {
+    throw new Error('WORKFLOW_SUPERVISOR_BROWSER_RUNTIME_RELEASE_INCOMPLETE');
+  }
+  const releaseRoot = dirname(authority.active.manifestPath);
+  return {
+    releaseId: authority.active.releaseId,
+    extensionSourcePath: join(releaseRoot, manifest.packageRoot, 'adapters', 'computer', 'chrome-extension'),
+    nativeHostSourcePath: join(releaseRoot, manifest.workflowSupervisorNativeHostEntrypoint),
+    nativeHostArtifactIdentity: manifest.workflowSupervisorNativeHostArtifactIdentity,
+  };
+}
+function assertRegularFile(path: string, code: string): void {
+  if (!existsSync(path)) throw new Error(code + ': ' + path);
+  const status = lstatSync(path);
+  if (status.isSymbolicLink() || !status.isFile()) throw new Error(code + ': ' + path);
+}
+function projectExtension(source: string, destination: string): void {
+  const staging = destination + '.staging-' + randomUUID().slice(0, 12);
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true, mode: 0o700 });
+  try {
+    for (const file of EXTENSION_FILES) {
+      const sourcePath = join(source, file);
+      assertRegularFile(sourcePath, 'WORKFLOW_SUPERVISOR_EXTENSION_SOURCE_INVALID');
+      writeFileSync(join(staging, file), readFileSync(sourcePath), { mode: 0o600 });
+    }
+    rmSync(destination, { recursive: true, force: true });
+    renameSync(staging, destination);
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+function projectNativeHost(source: string, expectedIdentity: string, destination: string): void {
+  assertRegularFile(source, 'WORKFLOW_SUPERVISOR_NATIVE_HOST_SOURCE_INVALID');
+  if ('sha256:' + sha256(source) !== expectedIdentity) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_HOST_IDENTITY_MISMATCH');
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = destination + '.' + randomUUID().slice(0, 12) + '.tmp';
+  writeFileSync(temporary, readFileSync(source), { mode: 0o700 });
+  chmodSync(temporary, 0o700);
+  renameSync(temporary, destination);
+}
+function extensionProjectionCurrent(source: string, destination: string): boolean {
+  return EXTENSION_FILES.every((file) => {
+    const sourcePath = join(source, file), destinationPath = join(destination, file);
+    return existsSync(sourcePath) && existsSync(destinationPath) && sha256(sourcePath) === sha256(destinationPath);
+  });
+}
+function nativeManifestPath(installation: WorkflowSupervisorBrowserInstallation): string {
+  return join(installation.nativeMessagingRoot, WORKFLOW_SUPERVISOR_NATIVE_HOST_NAME + '.json');
+}
+function nativeManifestReady(path: string, nativeHostPath: string, exactExtensionId: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    const manifest = JSON.parse(readFileSync(path, 'utf8')) as { path?: unknown; allowed_origins?: unknown };
+    return manifest.path === nativeHostPath
+      && JSON.stringify(manifest.allowed_origins) === JSON.stringify(['chrome-extension://' + exactExtensionId + '/']);
+  } catch { return false; }
+}
+function inspectWithRelease(
+  controllerHome: string,
+  release: ActiveBrowserAdapterRelease,
+  dependencies: WorkflowSupervisorBrowserAdapterDependencies,
+): WorkflowSupervisorBrowserAdapterStatus {
+  const paths = controllerPaths(controllerHome);
+  const exactExtensionId = extensionId(release.extensionSourcePath);
+  const hostCurrent = existsSync(paths.nativeHostPath) && 'sha256:' + sha256(paths.nativeHostPath) === release.nativeHostArtifactIdentity;
+  const extensionCurrent = existsSync(paths.extensionPath)
+    && extensionProjectionCurrent(release.extensionSourcePath, paths.extensionPath)
+    && nativeManifestReady(join(paths.extensionPath, FORGE_NATIVE_MESSAGING_DECLARATION), paths.nativeHostPath, exactExtensionId);
+  const installations = dependencies.browserInstallations ?? defaultBrowserInstallations(controllerHome, dependencies.homeDir, dependencies.repository);
+  const nativeManifestPaths = installations.map(nativeManifestPath);
+  const manifestsCurrent = nativeManifestPaths.every((path) => nativeManifestReady(path, paths.nativeHostPath, exactExtensionId));
+  const projectionCurrent = hostCurrent && extensionCurrent && manifestsCurrent;
+  return {
+    state: projectionCurrent ? 'ready' : (existsSync(paths.extensionPath) || existsSync(paths.nativeHostPath) ? 'projection_stale' : 'not_installed'),
+    extensionPath: paths.extensionPath,
+    extensionId: exactExtensionId,
+    nativeHostPath: paths.nativeHostPath,
+    activeReleaseId: release.releaseId,
+    nativeManifestPaths,
+    projectionCurrent,
+    detail: projectionCurrent
+      ? 'Workflow Supervisor browser adapter is projected from the active Runtime release and Native Messaging is registered for the package-derived extension id. Live browser connectivity is proven separately by Supervisor browser_discovery.'
+      : 'Controller browser-adapter projection does not match the active Runtime release.',
+  };
+}
+export function inspectWorkflowSupervisorBrowserAdapter(
+  controllerHome: string,
+  dependencies: WorkflowSupervisorBrowserAdapterDependencies = {},
+): WorkflowSupervisorBrowserAdapterStatus {
+  const paths = controllerPaths(controllerHome);
+  try {
+    return inspectWithRelease(controllerHome, (dependencies.activeRelease ?? activeBrowserAdapterRelease)(controllerHome), dependencies);
+  } catch (error) {
+    return {
+      state: 'runtime_release_incomplete',
+      extensionPath: paths.extensionPath,
+      nativeHostPath: paths.nativeHostPath,
+      nativeManifestPaths: [],
+      projectionCurrent: false,
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+export function installWorkflowSupervisorBrowserAdapter(
+  controllerHome: string,
+  dependencies: WorkflowSupervisorBrowserAdapterDependencies = {},
+): WorkflowSupervisorBrowserAdapterStatus {
+  const release = (dependencies.activeRelease ?? activeBrowserAdapterRelease)(controllerHome);
+  const paths = controllerPaths(controllerHome);
+  const exactExtensionId = extensionId(release.extensionSourcePath);
+  projectExtension(release.extensionSourcePath, paths.extensionPath);
+  projectNativeHost(release.nativeHostSourcePath, release.nativeHostArtifactIdentity, paths.nativeHostPath);
+  writeFileSync(
+    join(paths.extensionPath, FORGE_NATIVE_MESSAGING_DECLARATION),
+    renderWorkflowSupervisorNativeManifest({ executablePath: paths.nativeHostPath, extensionId: exactExtensionId }),
+    { mode: 0o600 },
+  );
+  for (const installation of dependencies.browserInstallations ?? defaultBrowserInstallations(controllerHome, dependencies.homeDir, dependencies.repository)) {
+    const path = nativeManifestPath(installation);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = path + '.' + randomUUID().slice(0, 12) + '.tmp';
+    writeFileSync(temporary, renderWorkflowSupervisorNativeManifest({
+      executablePath: paths.nativeHostPath,
+      extensionId: exactExtensionId,
+    }), { mode: 0o600 });
+    renameSync(temporary, path);
+  }
+  return inspectWithRelease(controllerHome, release, dependencies);
+}