@moretea-labs/forge 1.8.0 → 1.8.2

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 {

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));
 }