@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/plugins/store.ts

@@ -1,10 +1,11 @@
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { join } from 'path';
 import type { RepositoryRecord } from '../../cli/repositories/types';
-import { CONTROLLER_SCOPE_REPO_ID, controllerSystemRoot, ensureControllerHome, repositoryControllerRoot } from '../../cli/repositories/controller-home';
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { CONTROLLER_SCOPE_REPO_ID, FORGE_INSTANCE_SCOPE_KEY, controllerSystemRoot, ensureControllerHome, repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'fs';
 import type { ExecutionJob, ResourceClaimSpec } from '../execution/jobs/types';
 import { appendRuntimeEvent } from '../evidence/event-ledger';
+import { redactSensitiveText, redactSensitiveValue } from '../evidence/sensitive-output';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 import { createFirstPartyPluginAdapterMap } from './first-party-registry';
 import { reconcileFirstPartyExternalPluginRegistration, reconcileFirstPartyExternalPluginRegistrations } from './first-party-external-registration';
@@ -20,17 +21,14 @@ import {
 } from './capability-authorization-grants';
 import { markControllerContextProjectionDirty } from '../projections/controller-context';
 import { acquireExecutionLeases, releaseExactExecutionLeases } from '../resources/leases/store';
-import { classifyRepositoryCommand } from '../../cli/repositories/command-classifier';
+import { isRuntimeWriteFenceError } from '../root/write-fence';
 import {
-  acceptSubmittedWorkContract,
-  activateWorkContract,
   appendWorkEvidence,
-  failWorkContract,
   getWorkContract,
   recordWorkCompletionReceipt,
   updateWorkContract,
 } from '../../../packages/kernel/work/api/index';
-import { isTerminalWorkContractStatus, type LocalEffectCompletionReceipt, type RemoteEffectCompletionReceipt, type WorkContract, type WorkRisk } from '../control-plane/facade/types';
+import { isTerminalSemanticWorkState, type RemoteEffectCompletionReceipt, type WorkContract } from '../control-plane/facade/types';
 import type {
   AssistantPluginAdapter,
   AssistantPluginActionDescriptor,
@@ -75,65 +73,191 @@ function now(): string {
   return new Date().toISOString();
 }
 
-export function controllerPluginRepository(controllerHome: string): RepositoryRecord {
+const CONTROLLER_PLUGIN_CACHE_SCOPE = 'controller';
+const CONTROLLER_PLUGIN_GRANT_SCOPE = 'controller:global';
+const CONTROLLER_PLUGIN_SCOPE_KEY = FORGE_INSTANCE_SCOPE_KEY;
+
+interface PluginActionScopeContext {
+  kind: 'controller' | 'repository';
+  scopeKey: string;
+  grantRepoId: string;
+  root: string;
+  checkoutId?: string;
+  repository?: RepositoryRecord;
+}
+
+function repositoryPluginActionScope(repository: RepositoryRecord): PluginActionScopeContext {
+  return {
+    kind: 'repository',
+    scopeKey: repository.repoId,
+    grantRepoId: repository.repoId,
+    root: repository.canonicalRoot,
+    checkoutId: repository.activeCheckoutId,
+    repository,
+  };
+}
+
+function controllerPluginActionScope(controllerHome: string): PluginActionScopeContext {
+  return {
+    kind: 'controller',
+    scopeKey: CONTROLLER_PLUGIN_SCOPE_KEY,
+    grantRepoId: CONTROLLER_PLUGIN_GRANT_SCOPE,
+    root: controllerSystemRoot(controllerHome),
+  };
+}
+
+function pluginActionExecutionFields(scope: PluginActionScopeContext): { repoId: string; repoRoot: string } {
+  // Adapter fields are a compatibility projection. controller:global identifies
+  // the Grant/config domain; it is not a Repository Registry identity.
+  return { repoId: scope.grantRepoId, repoRoot: scope.root };
+}
+
+function controllerPluginsRoot(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'plugins');
+}
+
+function controllerManifestPath(controllerHome: string, pluginId: string): string {
+  return join(controllerPluginsRoot(controllerHome), 'manifests', `${sanitizeFileComponent(pluginId)}.json`);
+}
+
+function controllerIndexPath(controllerHome: string): string {
+  return join(controllerPluginsRoot(controllerHome), 'index.json');
+}
+
+function adapterMatchesController(adapter: AssistantPluginAdapter): boolean {
+  const scope = adapter.scope ?? 'repository';
+  return scope === 'controller' || scope === 'controller_with_repository_overlay';
+}
+
+function adapterMatchesRepository(adapter: AssistantPluginAdapter, _repository: RepositoryRecord): boolean {
+  const scope = adapter.scope ?? 'repository';
+  return scope === 'repository' || scope === 'controller_with_repository_overlay';
+}
+
+function computeControllerManifest(
+  controllerHome: string,
+  pluginId: string,
+  resolvedAdapter?: AssistantPluginAdapter,
+): AssistantPluginManifest {
+  const adapter = resolvedAdapter ?? resolvePluginAdapter(controllerHome, pluginId);
+  if (!adapter || !adapterMatchesController(adapter)) throw new Error(`PLUGIN_NOT_FOUND: ${pluginId}`);
+  const previous = readControllerStoredPluginManifest(controllerHome, pluginId);
   const root = controllerSystemRoot(controllerHome);
-  const timestamp = now();
+  const built = adapter.buildManifest(previous?.revision ?? 0, previous?.updatedAt, root, {
+    controllerHome,
+    repoId: CONTROLLER_PLUGIN_GRANT_SCOPE,
+    repoRoot: root,
+    controllerScoped: true,
+  });
+  const changed = !previous || fingerprintManifest(previous) !== fingerprintManifest(built);
   return {
-    schemaVersion: 1,
-    repoId: CONTROLLER_SCOPE_REPO_ID,
-    displayName: 'Controller local system',
-    canonicalRoot: root,
-    localRoot: root,
-    activeCheckoutId: 'controller',
-    checkouts: [],
-    defaultBranch: 'none',
-    repositoryType: 'local-git',
-    enabled: true,
-    createdAt: timestamp,
-    updatedAt: timestamp,
-    lastSeenAt: timestamp,
-    configurationPath: join(root, 'local-system', 'targets.json'),
-    stateStorageStrategy: 'controller-home',
+    ...built,
+    revision: previous ? (changed ? previous.revision + 1 : previous.revision) : 1,
+    updatedAt: changed ? now() : previous?.updatedAt ?? built.updatedAt,
   };
 }
 
-/**
- * Controller-scoped product facade. The synthetic RepositoryRecord remains an
- * internal storage/projection compatibility shape only; callers need no repo.
- */
 export function readControllerStoredPluginManifest(controllerHome: string, pluginId: string): AssistantPluginManifest | undefined {
-  return readStoredAssistantPluginManifest(controllerHome, controllerPluginRepository(controllerHome), pluginId);
+  try {
+    const canonicalPath = controllerManifestPath(controllerHome, pluginId);
+    if (existsSync(canonicalPath)) return readJsonFile<AssistantPluginManifest>(canonicalPath);
+    const legacyPath = join(legacyControllerPluginsRoot(controllerHome), 'manifests', `${sanitizeFileComponent(pluginId)}.json`);
+    return existsSync(legacyPath) ? readJsonFile<AssistantPluginManifest>(legacyPath) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function listControllerPluginIds(controllerHome: string): string[] {
+  return listPluginAdapters(controllerHome).filter(adapterMatchesController).map((adapter) => adapter.pluginId).sort();
 }
 
 export function listControllerPluginManifests(
   controllerHome: string,
   options: ListAssistantPluginManifestsOptions = {},
 ): AssistantPluginManifest[] {
-  return listAssistantPluginManifests(controllerHome, controllerPluginRepository(controllerHome), options);
+  const preferStored = options.preferStored === true && options.forceRefresh !== true;
+  const fallbackToLive = options.fallbackToLive !== false || !preferStored;
+  const cacheKey = listCacheKey(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, preferStored, fallbackToLive);
+  if (options.forceRefresh !== true) {
+    const cached = readPluginManifestCache(pluginManifestListCache, cacheKey, preferStored ? PLUGIN_MANIFEST_STORED_CACHE_TTL_MS : PLUGIN_MANIFEST_LIVE_CACHE_TTL_MS);
+    if (cached) return cached;
+  }
+  const manifests = listControllerPluginIds(controllerHome).map((pluginId) => {
+    if (preferStored) {
+      const stored = readControllerStoredPluginManifest(controllerHome, pluginId);
+      if (stored) return stored;
+      if (!fallbackToLive) return undefined;
+    }
+    return computeControllerManifest(controllerHome, pluginId);
+  }).filter((manifest): manifest is AssistantPluginManifest => Boolean(manifest)).sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+  primePluginManifestItemCache(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, manifests, preferStored);
+  return writePluginManifestCache(pluginManifestListCache, cacheKey, manifests);
+}
+
+function getControllerPluginManifestForExecution(
+  controllerHome: string,
+  pluginId: string,
+  adapter: AssistantPluginAdapter,
+): { manifest: AssistantPluginManifest; providerIdentityPrevalidated: boolean } {
+  const cacheKey = itemCacheKey(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, pluginId, false);
+  const cached = readPluginManifestCache(pluginManifestItemCache, cacheKey);
+  const wrap = (manifest: AssistantPluginManifest) => ({
+    manifest,
+    providerIdentityPrevalidated: manifest.enabled && manifest.health.probed && manifest.health.ready,
+  });
+  if (cached) return wrap(cached);
+  return wrap(writePluginManifestCache(pluginManifestItemCache, cacheKey, computeControllerManifest(controllerHome, pluginId, adapter)));
 }
 
 export function getControllerPluginManifest(controllerHome: string, pluginId: string): AssistantPluginManifest {
-  return getAssistantPluginManifest(controllerHome, controllerPluginRepository(controllerHome), pluginId);
+  const adapter = resolvePluginAdapter(controllerHome, pluginId);
+  if (!adapter || !adapterMatchesController(adapter)) throw new Error(`PLUGIN_NOT_FOUND: ${pluginId}`);
+  return getControllerPluginManifestForExecution(controllerHome, pluginId, adapter).manifest;
+}
+
+function writeControllerRegistry(controllerHome: string, manifests: AssistantPluginManifest[]): AssistantPluginRegistryIndex {
+  const index: AssistantPluginRegistryIndex = {
+    schemaVersion: 1,
+    updatedAt: now(),
+    plugins: manifests.map((manifest) => ({
+      ...pluginIndexEntry(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, manifest),
+      manifestPath: controllerManifestPath(controllerHome, manifest.pluginId),
+    })).sort((left, right) => left.pluginId.localeCompare(right.pluginId)),
+  };
+  writeJsonAtomic(controllerIndexPath(controllerHome), index);
+  return index;
 }
 
 export function syncControllerPluginRegistry(controllerHome: string) {
   reconcileFirstPartyExternalPluginRegistrations(controllerHome);
-  return syncAssistantPluginRegistry(controllerHome, controllerPluginRepository(controllerHome));
+  invalidateAssistantPluginManifestCache(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE);
+  const manifests = listControllerPluginManifests(controllerHome, { forceRefresh: true });
+  for (const manifest of manifests) writeJsonAtomic(controllerManifestPath(controllerHome, manifest.pluginId), manifest);
+  return { manifests, index: writeControllerRegistry(controllerHome, manifests) };
 }
 
 export function syncControllerPluginManifest(controllerHome: string, pluginId: string) {
   reconcileFirstPartyExternalPluginRegistration(controllerHome, pluginId);
-  return syncAssistantPluginManifest(controllerHome, controllerPluginRepository(controllerHome), pluginId);
+  invalidateAssistantPluginManifestCache(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, pluginId);
+  const manifest = computeControllerManifest(controllerHome, pluginId);
+  writeJsonAtomic(controllerManifestPath(controllerHome, pluginId), manifest);
+  cacheAssistantPluginManifest(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, manifest, false);
+  cacheAssistantPluginManifest(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, manifest, true);
+  const manifests = listControllerPluginIds(controllerHome).map((candidate) => candidate === pluginId
+    ? manifest
+    : readControllerStoredPluginManifest(controllerHome, candidate) ?? cachedManifestForRepository(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, candidate))
+    .filter((entry): entry is AssistantPluginManifest => Boolean(entry)).sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+  return { manifest, index: writeControllerRegistry(controllerHome, manifests) };
 }
 
 export function removeControllerPluginManifestProjection(controllerHome: string, pluginId: string) {
-  return removeAssistantPluginManifestProjection(controllerHome, controllerPluginRepository(controllerHome), pluginId);
-}
-
-function adapterMatchesRepository(adapter: AssistantPluginAdapter, repository: RepositoryRecord): boolean {
-  const scope = adapter.scope ?? 'repository';
-  if (scope === 'controller_with_repository_overlay') return true;
-  return repository.repoId === CONTROLLER_SCOPE_REPO_ID ? scope === 'controller' : scope === 'repository';
+  invalidateAssistantPluginManifestCache(controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, pluginId);
+  rmSync(controllerManifestPath(controllerHome, pluginId), { force: true });
+  const current = readJsonFile<AssistantPluginRegistryIndex>(controllerIndexPath(controllerHome), { schemaVersion: 1, updatedAt: now(), plugins: [] });
+  const next = { ...current, updatedAt: now(), plugins: current.plugins.filter((entry) => entry.pluginId !== pluginId) };
+  writeJsonAtomic(controllerIndexPath(controllerHome), next);
+  return next;
 }
 
 function cloneCacheValue<T>(value: T): T {
@@ -226,7 +350,13 @@ export function clearAssistantPluginManifestCacheForTest(): void {
 }
 
 function pluginsRoot(controllerHome: string, repoId: string): string {
-  return join(repositoryControllerRoot(controllerHome, repoId), 'plugins');
+  return repoId === CONTROLLER_SCOPE_REPO_ID
+    ? join(controllerSystemRoot(controllerHome), 'plugins')
+    : join(repositoryControllerRoot(controllerHome, repoId), 'plugins');
+}
+
+function legacyControllerPluginsRoot(controllerHome: string): string {
+  return join(repositoryControllerRoot(controllerHome, CONTROLLER_SCOPE_REPO_ID), 'plugins');
 }
 
 function manifestPath(controllerHome: string, repoId: string, pluginId: string): string {
@@ -271,8 +401,14 @@ function pluginIndexEntry(controllerHome: string, repoId: string, manifest: Assi
 }
 
 function readStoredManifest(controllerHome: string, repoId: string, pluginId: string): AssistantPluginManifest | undefined {
+  const canonicalPath = manifestPath(controllerHome, repoId, pluginId);
   try {
-    return readJsonFile<AssistantPluginManifest>(manifestPath(controllerHome, repoId, pluginId));
+    if (existsSync(canonicalPath)) return readJsonFile<AssistantPluginManifest>(canonicalPath);
+    if (repoId === CONTROLLER_SCOPE_REPO_ID) {
+      const legacyPath = join(legacyControllerPluginsRoot(controllerHome), 'manifests', `${sanitizeFileComponent(pluginId)}.json`);
+      if (existsSync(legacyPath)) return readJsonFile<AssistantPluginManifest>(legacyPath);
+    }
+    return undefined;
   } catch {
     return undefined;
   }
@@ -309,6 +445,20 @@ export function migrateRepositoryPluginConfigLegacyFiles(
     join(repository.canonicalRoot, '.repo-harness', 'plugins'),
   ];
   mkdirSync(targetRoot, { recursive: true });
+  // Upgrade an already-adopted v1/v2 Controller Home config in place. The
+  // adapter owns schema semantics; this store remains the sole file writer.
+  const browserTarget = repositoryPluginConfigPath({ controllerHome, repoId: repository.repoId }, 'browser');
+  const browserNormalizer = PLUGIN_ADAPTERS.get('browser')?.normalizeLegacyConfig;
+  if (!browserNormalizer) throw new Error('PLUGIN_CONFIG_MIGRATION_INVALID: browser schema owner missing');
+  if (existsSync(browserTarget)) {
+    const stat = lstatSync(browserTarget);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('PLUGIN_CONFIG_AUTHORITY_PATH_INVALID: browser config');
+    let current: unknown;
+    try { current = JSON.parse(readFileSync(browserTarget, 'utf8')); }
+    catch { throw new Error('PLUGIN_CONFIG_AUTHORITY_INVALID: browser config JSON'); }
+    const normalized = browserNormalizer(current);
+    if ((current as { schemaVersion?: unknown }).schemaVersion !== 3) writeJsonAtomic(browserTarget, normalized);
+  }
   for (const legacyRoot of legacyRoots) {
     if (!existsSync(legacyRoot)) continue;
     const stat = lstatSync(legacyRoot);
@@ -326,7 +476,16 @@ export function migrateRepositoryPluginConfigLegacyFiles(
       const sourceStat = lstatSync(source);
       if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) continue;
       const target = repositoryPluginConfigPath({ controllerHome, repoId: repository.repoId }, pluginId);
-      if (!existsSync(target)) cpSync(source, target, { force: false, errorOnExist: false });
+      if (!existsSync(target)) {
+        if (pluginId === 'browser') {
+          let parsed: unknown;
+          try { parsed = JSON.parse(readFileSync(source, 'utf8')); }
+          catch { throw new Error('PLUGIN_CONFIG_MIGRATION_INVALID: legacy browser JSON'); }
+          writeJsonAtomic(target, browserNormalizer(parsed));
+        } else {
+          cpSync(source, target, { force: false, errorOnExist: false });
+        }
+      }
       rmSync(source, { force: true });
     }
     if (readdirSync(legacyRoot).length === 0) rmSync(legacyRoot, { recursive: true, force: true });
@@ -340,7 +499,6 @@ function computeManifest(
   pluginId: string,
   resolvedAdapter?: AssistantPluginAdapter,
 ): AssistantPluginManifest {
-  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const adapter = resolvedAdapter ?? resolvePluginAdapter(controllerHome, pluginId);
   if (!adapter || !adapterMatchesRepository(adapter, repository)) throw new Error(`PLUGIN_NOT_FOUND: ${pluginId}`);
   const previous = readStoredManifest(controllerHome, repository.repoId, pluginId);
@@ -348,7 +506,7 @@ function computeManifest(
     controllerHome,
     repoId: repository.repoId,
     repoRoot: repository.canonicalRoot,
-    controllerScoped: repository.repoId === CONTROLLER_SCOPE_REPO_ID,
+    controllerScoped: false,
   });
   const changed = !previous || fingerprintManifest(previous) !== fingerprintManifest(built);
   return {
@@ -370,59 +528,76 @@ function writeRegistry(controllerHome: string, repoId: string, manifests: Assist
   return index;
 }
 
-export function claimsForAssistantPluginAction(
+function claimsForPluginActionScope(
   action: AssistantPluginActionDescriptor,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   trustedPluginId: string,
 ): ResourceClaimSpec[] {
-  const controllerScoped = repository.repoId === CONTROLLER_SCOPE_REPO_ID;
   const pluginId = trustedPluginId.trim().replace(/[^a-zA-Z0-9._-]+/g, '-');
   if (!pluginId) throw new Error('PLUGIN_ID_REQUIRED_FOR_RESOURCE_CLAIMS');
   return action.resourceClaims.map((claim) => ({
     resourceKey: claim.resource === 'remote' || claim.resource === 'provider-state'
-      // The manifest/plugin id was resolved from the trusted registration; a
-      // provider never supplies arbitrary resource-key text.
       ? `provider-state:${pluginId}`
-      : controllerScoped
+      : scope.kind === 'controller'
         ? `controller-system:${claim.resource}`
         : claim.resource === 'workspace'
-          ? `workspace:${repository.activeCheckoutId}`
+          ? `workspace:${scope.checkoutId}`
           : claim.resource === 'git-refs'
-            ? `git-refs:${repository.repoId}`
-            : `repo-state:${repository.repoId}`,
+            ? `git-refs:${scope.scopeKey}`
+            : `repo-state:${scope.scopeKey}`,
     mode: claim.mode,
   }));
 }
 
+export function claimsForAssistantPluginAction(
+  action: AssistantPluginActionDescriptor,
+  repository: RepositoryRecord,
+  trustedPluginId: string,
+): ResourceClaimSpec[] {
+  return claimsForPluginActionScope(action, repositoryPluginActionScope(repository), trustedPluginId);
+}
+
 async function withAssistantPluginResourceLeases<T>(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   action: AssistantPluginActionDescriptor,
   request: AssistantPluginActionRequest,
   operation: () => Promise<T>,
 ): Promise<T> {
-  const claims = claimsForAssistantPluginAction(action, repository, request.pluginId).map((claim) => ({
+  const claims = claimsForPluginActionScope(action, scope, request.pluginId).map((claim) => ({
     ...claim,
-    repoId: repository.repoId,
-    checkoutId: repository.activeCheckoutId,
+    repoId: scope.scopeKey,
+    ...(scope.checkoutId ? { checkoutId: scope.checkoutId } : {}),
   }));
   if (claims.length === 0) return operation();
 
-  const ownerJobId = `plugin:${request.requestId}`;
+  // requestId is the semantic idempotency key, but before its receipt/index is
+  // persisted two concurrent replays can enter this function. Give each live
+  // invocation a distinct lease owner so the later replay contends on the
+  // first invocation's declared resource instead of silently accumulating a
+  // second same-owner lease and then failing exact release with LEASE_SET_MISMATCH.
+  const ownerJobId = `plugin:${request.requestId}:${randomUUID()}`;
   const timeoutMs = Math.max(5_000, Math.min(10 * 60_000, request.timeoutMs ?? action.defaultTimeoutMs));
-  const acquisition = acquireExecutionLeases(controllerHome, repository.repoId, ownerJobId, claims, {
+  const acquisition = acquireExecutionLeases(controllerHome, scope.scopeKey, ownerJobId, claims, {
     ttlMs: timeoutMs + 60_000,
+    // This lease exists only to fence concurrent invocations of one external
+    // effect. It is not Scheduler/recovery authority, so derived projection,
+    // event-ledger, and wake side effects must never participate in the effect
+    // outcome. The lease file + fencing token remain cross-process durable for
+    // the bounded invocation and expire if its process dies.
+    visibility: 'ephemeral',
     ownerIdentity: {
-      repositoryId: repository.repoId,
-      checkoutId: repository.activeCheckoutId,
-      worktreeId: repository.activeCheckoutId,
+      repositoryId: scope.scopeKey,
+      checkoutId: scope.checkoutId ?? CONTROLLER_PLUGIN_SCOPE_KEY,
+      worktreeId: scope.checkoutId ?? CONTROLLER_PLUGIN_SCOPE_KEY,
       branch: 'workflow-plugin-action',
       principalId: request.origin.actor?.trim() || 'workflow-plugin-action',
       controllerInstanceId: process.env.FORGE_RUNTIME_INSTANCE_ID?.trim()
         || process.env.FORGE_WRITER_INSTANCE_ID?.trim()
         || process.env.FORGE_DAEMON_INSTANCE_ID?.trim()
         || `process:${process.pid}`,
-      controllerGeneration: process.env.FORGE_WRITER_GENERATION?.trim()
+      controllerGeneration: process.env.FORGE_RUNTIME_INCARNATION_GENERATION?.trim()
+        || process.env.FORGE_WRITER_GENERATION?.trim()
         || process.env.FORGE_ACTIVE_RUNTIME_REVISION?.trim()
         || 'unbound',
     },
@@ -455,13 +630,24 @@ async function withAssistantPluginResourceLeases<T>(
     retainForReconciliation = isAssistantPluginError(error) && error.effectOutcome === 'outcome_unknown';
     throw error;
   } finally {
-    if (!retainForReconciliation) releaseExactExecutionLeases(controllerHome, repository.repoId, ownerJobId, expected);
+    if (!retainForReconciliation) {
+      try {
+        releaseExactExecutionLeases(controllerHome, scope.scopeKey, ownerJobId, expected, { visibility: 'ephemeral' });
+      } catch (error) {
+        // A successful provider effect can rotate Runtime authority (for example
+        // a fenced Runtime cutover). The old sidecar must not release leases
+        // after it is fenced, but that cleanup denial must not overwrite the
+        // already-known provider result. The canonical successor Runtime can
+        // reclaim this ephemeral lease from its fenced owner immediately.
+        if (!isRuntimeWriteFenceError(error)) throw error;
+      }
+    }
   }
 }
 
-function semanticKey(repository: RepositoryRecord, pluginId: string, actionId: string, args: Record<string, unknown>): string {
+function semanticKey(scope: PluginActionScopeContext, pluginId: string, actionId: string, args: Record<string, unknown>): string {
   const digest = createHash('sha256').update(JSON.stringify(canonical(args))).digest('hex').slice(0, 20);
-  return `plugin-action:${repository.repoId}:${pluginId}:${actionId}:${digest}`;
+  return `plugin-action:${scope.scopeKey}:${pluginId}:${actionId}:${digest}`;
 }
 
 function validatePrimitive(type: string, value: unknown): boolean {
@@ -515,7 +701,18 @@ function enforceConfirmation(action: AssistantPluginActionDescriptor, request: A
   // Ordinary authorization is delegated to the host AI/tool permission model.
   // Forge keeps only the explicit strong-confirmation boundary for
   // destructive or irreversible plugin operations.
-  if (action.confirmation === 'none' || action.confirmation === 'authorization') return;
+  if (action.confirmation === 'none') return;
+  if (action.confirmation === 'authorization') {
+    if (action.requiredConfirmationText) {
+      if (request.confirmAuthorization !== true) {
+        throw new Error(`PLUGIN_CONFIRMATION_REQUIRED: ${request.pluginId}/${request.actionId} requires confirmAuthorization=true`);
+      }
+      if (request.confirmationText !== action.requiredConfirmationText) {
+        throw new Error(`PLUGIN_CONFIRMATION_TEXT_REQUIRED: provide confirmationText=${action.requiredConfirmationText}`);
+      }
+    }
+    return;
+  }
   if (action.confirmation === 'strong_confirmation') {
     if (request.confirmAuthorization !== true) {
       throw new Error(`PLUGIN_CONFIRMATION_REQUIRED: ${request.pluginId}/${request.actionId} requires confirmAuthorization=true`);
@@ -582,7 +779,7 @@ function authorizationTargetMatches(
 
 async function resolveAutomatedWriteAuthorization(input: {
   controllerHome: string;
-  repository: RepositoryRecord;
+  scope: PluginActionScopeContext;
   adapter: AssistantPluginAdapter;
   manifest: AssistantPluginManifest;
   action: AssistantPluginActionDescriptor;
@@ -610,14 +807,14 @@ async function resolveAutomatedWriteAuthorization(input: {
   }
   const targetContext = await input.adapter.resolveAuthorizationContext({
     controllerHome: input.controllerHome,
-    repoId: input.repository.repoId,
-    repoRoot: input.repository.canonicalRoot,
+    ...pluginActionExecutionFields(input.scope),
     pluginId: input.manifest.pluginId,
     actionId: input.action.actionId,
     requestId: input.requestId,
     args: input.args,
     origin: input.origin,
     jobId: input.jobId,
+    authorizationGrantRefs: refs,
   });
   if (!targetContext) {
     throw new AssistantPluginError(
@@ -630,7 +827,7 @@ async function resolveAutomatedWriteAuthorization(input: {
   const grant = refs
     .map((ref) => findActivePluginCapabilityAuthorizationById(input.controllerHome, ref))
     .find((candidate) => candidate
-      && candidate.repoId === input.repository.repoId
+      && candidate.repoId === input.scope.grantRepoId
       && candidate.pluginId === input.manifest.pluginId
       && candidate.capabilityId === capabilityId
       && authorizationTargetMatches(candidate.target, targetContext.target)
@@ -759,6 +956,7 @@ export function syncAssistantPluginRegistry(
   repository: RepositoryRecord,
 ): { manifests: AssistantPluginManifest[]; index: AssistantPluginRegistryIndex } {
   invalidateAssistantPluginManifestCache(controllerHome, repository.repoId);
+  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const manifests = listAssistantPluginManifests(controllerHome, repository, { forceRefresh: true });
   for (const manifest of manifests) {
     writeJsonAtomic(manifestPath(controllerHome, repository.repoId, manifest.pluginId), manifest);
@@ -776,6 +974,7 @@ export function syncAssistantPluginManifest(
   pluginId: string,
 ): { manifest: AssistantPluginManifest; index: AssistantPluginRegistryIndex } {
   invalidateAssistantPluginManifestCache(controllerHome, repository.repoId, pluginId);
+  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const manifest = computeManifest(controllerHome, repository, pluginId);
   writeJsonAtomic(manifestPath(controllerHome, repository.repoId, manifest.pluginId), manifest);
   markControllerContextProjectionDirty(repository.canonicalRoot, `plugin:${pluginId}:synced`);
@@ -819,25 +1018,39 @@ export function removeAssistantPluginManifestProjection(
 }
 
 export function isDirectPluginReadAction(action: AssistantPluginActionDescriptor): boolean {
-  return action.readOnly === true
+  return action.executionMode !== 'direct_non_persistent'
+    && action.readOnly === true
     && action.risk === 'readonly'
     && action.confirmation === 'none'
     && action.idempotent === true;
 }
 
 export function isDirectNonPersistentPluginAction(action: AssistantPluginActionDescriptor): boolean {
-  return action.executionMode === 'direct_non_persistent'
-    && action.readOnly === false
-    && action.risk === 'workspace_write'
-    && action.confirmation === 'authorization'
-    && action.idempotent === false
-    && action.remoteEffectWorkCompletion === undefined
-    && action.resourceClaims.length === 0;
+  if (
+    action.executionMode !== 'direct_non_persistent'
+    || action.remoteEffectWorkCompletion !== undefined
+    || action.resourceClaims.length !== 0
+  ) {
+    return false;
+  }
+
+  // Direct non-persistent actions are provider-local operations that must never
+  // enter the durable effect/receipt path. They are intentionally limited to
+  // either a pure provider read or a provider-local workspace effect. Remote
+  // writes/destructive effects still require the normal durable application
+  // path and its reconciliation authority.
+  if (action.readOnly) {
+    return action.risk === 'readonly'
+      && (action.confirmation === 'none' || action.confirmation === 'authorization')
+      && action.idempotent === true;
+  }
+  return action.risk === 'workspace_write'
+    && (action.confirmation === 'authorization' || action.confirmation === 'none');
 }
 
-export async function executeAssistantPluginDirectNonPersistent(
+async function executePluginDirectNonPersistentInScope(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   request: AssistantPluginActionRequest,
 ): Promise<{ manifest: AssistantPluginManifest; action: AssistantPluginActionDescriptor; result: Record<string, unknown> }> {
   const adapter = resolvePluginAdapter(controllerHome, request.pluginId);
@@ -845,7 +1058,9 @@ export async function executeAssistantPluginDirectNonPersistent(
   if (PLUGIN_ADAPTERS.get(request.pluginId) !== adapter) {
     throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_FIRST_PARTY_REQUIRED: ${request.pluginId}/${request.actionId}`);
   }
-  const manifestLookup = getAssistantPluginManifestForExecution(controllerHome, repository, request.pluginId, adapter);
+  const manifestLookup = scope.kind === 'controller'
+    ? getControllerPluginManifestForExecution(controllerHome, request.pluginId, adapter)
+    : getAssistantPluginManifestForExecution(controllerHome, scope.repository!, request.pluginId, adapter);
   const manifest = manifestLookup.manifest;
   const action = actionForManifest(manifest, request.actionId);
   if (!manifest.enabled && action.actionId !== 'configure') {
@@ -860,7 +1075,7 @@ export async function executeAssistantPluginDirectNonPersistent(
   if (request.workId || request.workRepoId) {
     throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_WORK_ATTRIBUTION_FORBIDDEN: ${request.pluginId}/${request.actionId}`);
   }
-  if (request.confirmAuthorization !== true) {
+  if (action.confirmation === 'authorization' && request.confirmAuthorization !== true) {
     throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_AUTHORIZATION_REQUIRED: ${request.pluginId}/${request.actionId} requires confirm_authorization=true for this invocation`);
   }
   const normalizedArgs = validateActionArguments(action, request.args ?? {});
@@ -868,7 +1083,7 @@ export async function executeAssistantPluginDirectNonPersistent(
   if (requiresAutomatedWriteAuthorization(request.origin)) {
     await resolveAutomatedWriteAuthorization({
       controllerHome,
-      repository,
+      scope,
       adapter,
       manifest,
       action,
@@ -880,8 +1095,7 @@ export async function executeAssistantPluginDirectNonPersistent(
   }
   const result = await adapter.executeAction({
     controllerHome,
-    repoId: repository.repoId,
-    repoRoot: repository.canonicalRoot,
+    ...pluginActionExecutionFields(scope),
     pluginId: request.pluginId,
     actionId: request.actionId,
     requestId: request.requestId,
@@ -895,12 +1109,29 @@ export async function executeAssistantPluginDirectNonPersistent(
   return { manifest, action, result };
 }
 
-export async function executeAssistantPluginReadDirect(
+export function executeAssistantPluginDirectNonPersistent(
   controllerHome: string,
   repository: RepositoryRecord,
   request: AssistantPluginActionRequest,
-): Promise<{ manifest: AssistantPluginManifest; action: AssistantPluginActionDescriptor; result: Record<string, unknown> }> {
-  const manifest = getAssistantPluginManifest(controllerHome, repository, request.pluginId);
+) {
+  return executePluginDirectNonPersistentInScope(controllerHome, repositoryPluginActionScope(repository), request);
+}
+
+export function executeControllerPluginDirectNonPersistent(
+  controllerHome: string,
+  request: AssistantPluginActionRequest,
+) {
+  return executePluginDirectNonPersistentInScope(controllerHome, controllerPluginActionScope(controllerHome), request);
+}
+
+async function executePluginReadDirectInScope(
+  controllerHome: string,
+  scope: PluginActionScopeContext,
+  request: AssistantPluginActionRequest,
+): Promise<{ manifest: AssistantPluginManifest; action: AssistantPluginActionDescriptor; result: Record<string, unknown>; receipt: PluginActionReceipt }> {
+  const manifest = scope.kind === 'controller'
+    ? getControllerPluginManifest(controllerHome, request.pluginId)
+    : getAssistantPluginManifest(controllerHome, scope.repository!, request.pluginId);
   const action = actionForManifest(manifest, request.actionId);
   if (!manifest.enabled && action.actionId !== 'configure') {
     throw new Error(`PLUGIN_DISABLED: ${request.pluginId} is disabled`);
@@ -910,24 +1141,68 @@ export async function executeAssistantPluginReadDirect(
   }
   const normalizedArgs = validateActionArguments(action, request.args ?? {});
   enforceConfirmation(action, { ...request, args: normalizedArgs });
-  const result = await executeAssistantPluginAction({
+  const result = await executePluginActionInScope(scope, {
     controllerHome,
-    repoId: repository.repoId,
-    repoRoot: repository.canonicalRoot,
+    ...pluginActionExecutionFields(scope),
     pluginId: request.pluginId,
     actionId: request.actionId,
     requestId: request.requestId,
     args: normalizedArgs,
     origin: request.origin,
   });
-  return { manifest, action, result };
+  const createdAt = new Date().toISOString();
+  const resultDigest = createHash('sha256').update(JSON.stringify(result)).digest('hex');
+  const observationSemanticKey = semanticKey(scope, request.pluginId, request.actionId, normalizedArgs);
+  const observationActor = request.origin?.actor?.trim() ?? '';
+  // Observation evidence is content-addressed so repeated identical reads do not create
+  // an unbounded receipt trail. This remains provenance only, never replay/effect state.
+  const receiptId = `PLG-OBS-${createHash('sha256')
+    .update(`${observationSemanticKey}:${resultDigest}:${observationActor}`)
+    .digest('hex').slice(0, 24)}`;
+  const receipt: PluginActionReceipt = {
+    schemaVersion: 1,
+    receiptId,
+    requestId: request.requestId,
+    scopeKey: scope.scopeKey,
+    ...(scope.repository ? { repoId: scope.repository.repoId } : {}),
+    pluginId: request.pluginId,
+    actionId: request.actionId,
+    semanticKey: observationSemanticKey,
+    status: 'succeeded',
+    createdAt,
+    ...(request.origin ? { origin: request.origin } : {}),
+    observationOnly: true,
+    resultDigest,
+  };
+  // Direct reads stay on the inline fast path. Persist only a compact observation
+  // receipt, never provider result content and never request replay state.
+  writeJsonAtomic(pluginActionReceiptPath(controllerHome, scope.scopeKey, receiptId), receipt);
+  return { manifest, action, result, receipt };
+}
+
+export function executeAssistantPluginReadDirect(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  request: AssistantPluginActionRequest,
+) {
+  return executePluginReadDirectInScope(controllerHome, repositoryPluginActionScope(repository), request);
+}
+
+export function executeControllerPluginReadDirect(
+  controllerHome: string,
+  request: AssistantPluginActionRequest,
+) {
+  return executePluginReadDirectInScope(controllerHome, controllerPluginActionScope(controllerHome), request);
 }
 
 export interface PluginActionReceipt {
   schemaVersion: 1;
   receiptId: string;
   requestId: string;
-  repoId: string;
+  /** Canonical plugin-action receipt scope: `instance` for controller plugins, repository id otherwise. */
+  scopeKey: string;
+  /** Repository provenance only; absent for controller-scoped plugin actions. */
+  repoId?: string;
   /** Work authority repository when it differs from controller/provider receipt scope. */
   workRepoId?: string;
   pluginId: string;
@@ -941,24 +1216,35 @@ export interface PluginActionReceipt {
   origin?: { surface: string; actor?: string; correlationId?: string };
   authorization?: PluginActionAuthorizationEvidence;
   result?: Record<string, unknown>;
-  error?: { code: string; message: string };
+  error?: { code: string; message: string; retryable?: boolean; details?: Record<string, unknown> };
+  /** True for a compact direct-read observation; it is evidence, never an effect-completion authority. */
+  observationOnly?: boolean;
+  /** SHA-256 of the direct-read result. Result content is intentionally not persisted for observation-only receipts. */
+  resultDigest?: string;
 }
 
 interface PluginActionRequestIndex {
   requestId: string;
-  repoId: string;
+  scopeKey: string;
+  repoId?: string;
   workRepoId?: string;
   receiptId: string;
   semanticKey: string;
   createdAt: string;
 }
 
-function pluginActionReceiptRoot(controllerHome: string, repoId: string): string {
-  const root = join(repositoryControllerRoot(controllerHome, repoId), 'plugin-action-receipts');
+function pluginActionReceiptRoot(controllerHome: string, scopeKey: string): string {
+  const root = scopeKey === CONTROLLER_PLUGIN_SCOPE_KEY
+    ? join(controllerSystemRoot(controllerHome), 'plugin-action-receipts')
+    : join(repositoryControllerRoot(controllerHome, scopeKey), 'plugin-action-receipts');
   mkdirSync(root, { recursive: true });
   return root;
 }
 
+function legacyControllerPluginActionReceiptPath(controllerHome: string, receiptId: string): string {
+  return join(repositoryControllerRoot(controllerHome, CONTROLLER_SCOPE_REPO_ID), 'plugin-action-receipts', `${sanitizeFileComponent(receiptId)}.json`);
+}
+
 function pluginActionRequestPath(controllerHome: string, requestId: string): string {
   const hash = createHash('sha256').update(requestId).digest('hex');
   const root = join(ensureControllerHome(controllerHome), 'indexes', 'plugin-actions', 'requests');
@@ -966,14 +1252,30 @@ function pluginActionRequestPath(controllerHome: string, requestId: string): str
   return join(root, `${hash}.json`);
 }
 
-function pluginActionReceiptPath(controllerHome: string, repoId: string, receiptId: string): string {
-  return join(pluginActionReceiptRoot(controllerHome, repoId), `${sanitizeFileComponent(receiptId)}.json`);
+function pluginActionReceiptPath(controllerHome: string, scopeKey: string, receiptId: string): string {
+  return join(pluginActionReceiptRoot(controllerHome, scopeKey), `${sanitizeFileComponent(receiptId)}.json`);
 }
 
-function readPluginActionReceipt(controllerHome: string, repoId: string, receiptId: string): PluginActionReceipt | undefined {
-  const path = pluginActionReceiptPath(controllerHome, repoId, receiptId);
-  if (!existsSync(path)) return undefined;
-  return readJsonFile<PluginActionReceipt>(path);
+function normalizePluginActionReceipt(receipt: PluginActionReceipt): PluginActionReceipt {
+  const scopeKey = receipt.scopeKey?.trim()
+    || (receipt.repoId === CONTROLLER_SCOPE_REPO_ID ? CONTROLLER_PLUGIN_SCOPE_KEY : receipt.repoId?.trim())
+    || '';
+  if (!scopeKey) throw new Error('PLUGIN_RECEIPT_SCOPE_CORRUPT');
+  return {
+    ...receipt,
+    scopeKey,
+    ...(scopeKey === CONTROLLER_PLUGIN_SCOPE_KEY ? { repoId: undefined } : { repoId: receipt.repoId ?? scopeKey }),
+  };
+}
+
+function readPluginActionReceipt(controllerHome: string, scopeKey: string, receiptId: string): PluginActionReceipt | undefined {
+  const path = pluginActionReceiptPath(controllerHome, scopeKey, receiptId);
+  if (existsSync(path)) return normalizePluginActionReceipt(readJsonFile<PluginActionReceipt>(path));
+  if (scopeKey === CONTROLLER_PLUGIN_SCOPE_KEY || scopeKey === CONTROLLER_SCOPE_REPO_ID) {
+    const legacyPath = legacyControllerPluginActionReceiptPath(controllerHome, receiptId);
+    if (existsSync(legacyPath)) return normalizePluginActionReceipt(readJsonFile<PluginActionReceipt>(legacyPath));
+  }
+  return undefined;
 }
 
 export function findPluginActionReceipt(
@@ -981,6 +1283,12 @@ export function findPluginActionReceipt(
   receiptId: string,
 ): PluginActionReceipt | undefined {
   const home = ensureControllerHome(controllerHome);
+  // Controller-scoped plugins (for example Local System) live under system/, not
+  // repositories/. They are first-class evidence producers and must be searched too.
+  const controllerReceipt = readPluginActionReceipt(home, CONTROLLER_PLUGIN_SCOPE_KEY, receiptId)
+    // One-way read compatibility for pre-cutover controller receipts only.
+    ?? readPluginActionReceipt(home, CONTROLLER_SCOPE_REPO_ID, receiptId);
+  if (controllerReceipt) return controllerReceipt;
   const repositoriesRoot = join(home, 'repositories');
   try {
     for (const repoId of readdirSync(repositoriesRoot)) {
@@ -999,7 +1307,9 @@ export function readPluginActionReceiptForRequest(controllerHome: string, reques
   if (!existsSync(path)) return undefined;
   const index = readJsonFile<PluginActionRequestIndex>(path);
   if (index.requestId !== requestId) throw new Error('PLUGIN_RECEIPT_REQUEST_MISMATCH');
-  const receipt = readPluginActionReceipt(controllerHome, index.repoId, index.receiptId);
+  const scopeKey = index.scopeKey?.trim() || index.repoId?.trim();
+  if (!scopeKey) throw new Error('PLUGIN_RECEIPT_REQUEST_SCOPE_CORRUPT');
+  const receipt = readPluginActionReceipt(controllerHome, scopeKey, index.receiptId);
   if (!receipt || receipt.requestId !== requestId || receipt.semanticKey !== index.semanticKey) throw new Error('PLUGIN_RECEIPT_LOST');
   return receipt;
 }
@@ -1011,86 +1321,20 @@ export function compatibilityPluginJobFromReceipt(
   return compatibilityJobFromReceipt(receipt, checkoutId);
 }
 
-const LOCAL_SYSTEM_MUTATION_ACTIONS = new Set([
-  'authorize_target',
-  'revoke_target',
-  'create_directory',
-  'write_text',
-  'delete_file',
-  'delete_empty_directory',
-  'initialize_git',
-  'execute_project_script',
-  'copy_file',
-  'move_file',
-  'rename_file',
-  'open_application',
-  'reveal_in_finder',
-  'open_file',
-]);
-
-function localSystemActionRequiresWork(
-  repository: RepositoryRecord,
-  pluginId: string,
-  actionId: string,
-  args: Record<string, unknown>,
-): boolean {
-  if (repository.repoId !== CONTROLLER_SCOPE_REPO_ID || pluginId !== 'local_system') return false;
-  if (LOCAL_SYSTEM_MUTATION_ACTIONS.has(actionId)) return true;
-  if (actionId !== 'execute_command' || !Array.isArray(args.command)) return false;
-  return classifyRepositoryCommand(args.command.map(String)).risk !== 'readonly';
-}
-
-function workRiskForPluginAction(action: AssistantPluginActionDescriptor): WorkRisk {
-  if (action.risk === 'readonly') return 'readonly';
-  if (action.risk === 'workspace_write') return 'medium';
-  if (action.risk === 'remote_write') return 'high';
-  return 'destructive';
-}
-
-function localEffectTarget(
-  args: Record<string, unknown>,
-  result: Record<string, unknown>,
-): LocalEffectCompletionReceipt['target'] {
-  const inner = result.result && typeof result.result === 'object' && !Array.isArray(result.result)
-    ? result.result as Record<string, unknown>
-    : result;
-  const target = inner.target && typeof inner.target === 'object' && !Array.isArray(inner.target)
-    ? inner.target as Record<string, unknown>
-    : undefined;
-  const id = String(
-    target?.workspaceId
-      ?? inner.workspaceId
-      ?? args.target_key
-      ?? args.destination_target_key
-      ?? args.source_target_key
-      ?? 'controller-local',
-  );
-  const identityFingerprint = typeof target?.identityFingerprint === 'string'
-    ? target.identityFingerprint
-    : typeof inner.identityFingerprint === 'string'
-      ? inner.identityFingerprint
-      : undefined;
-  return {
-    kind: id.startsWith('workspace_') || args.target_key || args.destination_target_key || args.source_target_key
-      ? 'workspace_target'
-      : 'controller_local',
-    id,
-    ...(identityFingerprint ? { identityFingerprint } : {}),
-  };
-}
-
-function workAttributionRepoId(repository: RepositoryRecord, request: AssistantPluginActionRequest): string {
+function workAttributionRepoId(scope: PluginActionScopeContext, request: AssistantPluginActionRequest): string {
   const explicit = request.workRepoId?.trim();
   if (!request.workId?.trim()) {
     if (explicit) throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_WITHOUT_WORK: ${explicit}`);
-    return repository.repoId;
+    return scope.repository?.repoId ?? '';
   }
-  return explicit || repository.repoId;
+  if (explicit) return explicit;
+  if (scope.repository) return scope.repository.repoId;
+  throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_REQUIRED: controller-scoped action ${request.pluginId}/${request.actionId} must name the Work repository explicitly`);
 }
 
 function remoteEffectWorkForPluginAction(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   action: AssistantPluginActionDescriptor,
   request: AssistantPluginActionRequest,
   receiptId?: string,
@@ -1100,7 +1344,7 @@ function remoteEffectWorkForPluginAction(
   if (action.risk !== 'remote_write') {
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_REQUIRES_REMOTE_WRITE: ${action.actionId}`);
   }
-  const workRepoId = workAttributionRepoId(repository, request);
+  const workRepoId = workAttributionRepoId(scope, request);
   const work = getWorkContract({ controllerHome, repoId: workRepoId }, workId);
   if (!work) throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_NOT_FOUND: ${workId}`);
   if (work.workKind !== 'remote_effect') {
@@ -1109,49 +1353,64 @@ function remoteEffectWorkForPluginAction(
   if (work.checks.length > 0) {
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_CHECKS_PRESENT: ${workId} declares repository checks and cannot be completed by a plugin receipt alone`);
   }
-  if (isTerminalWorkContractStatus(work.status)) {
+  if (isTerminalSemanticWorkState(work.semanticState)) {
     const receiptAlreadyBound = Boolean(receiptId) && (
       work.completionReceipt?.receiptId === receiptId
       || work.evidenceRefs.some((evidence) => evidence.evidenceId === receiptId)
     );
-    if (work.status === 'completed' && receiptAlreadyBound) return work;
-    throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_TERMINAL: ${workId} is ${work.status}`);
+    if (work.semanticState === 'completed' && receiptAlreadyBound) return work;
+    throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_TERMINAL: ${workId} is ${work.semanticState}`);
   }
   return work;
 }
 
 function attributedWorkForPluginAction(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   action: AssistantPluginActionDescriptor,
   request: AssistantPluginActionRequest,
 ): WorkContract | undefined {
   const workId = request.workId?.trim();
   if (!workId || action.risk === 'remote_write') return undefined;
-  const workRepoId = workAttributionRepoId(repository, request);
+  const workRepoId = workAttributionRepoId(scope, request);
   const work = getWorkContract({ controllerHome, repoId: workRepoId }, workId);
   if (!work) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workRepoId}:${workId}`);
-  if (isTerminalWorkContractStatus(work.status)) {
-    throw new Error(`WORK_PLUGIN_ATTRIBUTION_TERMINAL: ${workId} is ${work.status}`);
+  if (isTerminalSemanticWorkState(work.semanticState)) {
+    throw new Error(`WORK_PLUGIN_ATTRIBUTION_TERMINAL: ${workId} is ${work.semanticState}`);
   }
   return work;
 }
 
+/** Reuse the canonical Work binding check before a Process request ID is reserved. */
+export function preflightPluginActionWorkBinding(
+  controllerHome: string,
+  pluginScope: { kind: 'controller' } | { kind: 'repository'; repository: RepositoryRecord },
+  action: AssistantPluginActionDescriptor,
+  request: AssistantPluginActionRequest,
+): void {
+  if (!request.workId?.trim()) return;
+  const scope = pluginScope.kind === 'controller'
+    ? controllerPluginActionScope(controllerHome)
+    : repositoryPluginActionScope(pluginScope.repository);
+  if (action.risk === 'remote_write') remoteEffectWorkForPluginAction(controllerHome, scope, action, request);
+  else attributedWorkForPluginAction(controllerHome, scope, action, request);
+}
+
 function bindLocalEffectReceiptToAttributedWork(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   action: AssistantPluginActionDescriptor,
   request: AssistantPluginActionRequest,
   receipt: PluginActionReceipt,
   work?: WorkContract,
 ): WorkContract | undefined {
   if (!request.workId || receipt.status !== 'succeeded') return work;
-  const workRepoId = workAttributionRepoId(repository, request);
+  const workRepoId = workAttributionRepoId(scope, request);
   const attributed = work ?? getWorkContract({ controllerHome, repoId: workRepoId }, request.workId.trim());
   if (!attributed) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workRepoId}:${request.workId.trim()}`);
   if (attributed.workKind !== 'local_effect' || action.readOnly || action.risk === 'readonly') return attributed;
   if (attributed.evidenceRefs.some((evidence) => evidence.evidenceId === receipt.receiptId)) return attributed;
-  if (isTerminalWorkContractStatus(attributed.status)) return attributed;
+  if (isTerminalSemanticWorkState(attributed.semanticState)) return attributed;
   return appendWorkEvidence({ controllerHome, repoId: workRepoId }, attributed.workId, {
     evidenceId: receipt.receiptId,
     title: 'typed local plugin effect completed',
@@ -1160,7 +1419,7 @@ function bindLocalEffectReceiptToAttributedWork(
   });
 }
 
-export function finalizeRemoteEffectWorkFromActionReceipt(
+export function recordRemoteEffectWorkActionReceipt(
   controllerHome: string,
   repoId: string,
   workId: string,
@@ -1170,14 +1429,12 @@ export function finalizeRemoteEffectWorkFromActionReceipt(
   if (work.workKind !== 'remote_effect') {
     throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_KIND_MISMATCH: ${workId} is ${work.workKind}, expected remote_effect`);
   }
-  if (work.status === 'completed' && work.completionReceipt?.source === 'remote_effect') return work;
-  if (isTerminalWorkContractStatus(work.status)) {
-    throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_TERMINAL: ${workId} is ${work.status}`);
-  }
+  if (work.completionReceipt?.source === 'remote_effect') return work;
   const receipt = work.evidenceRefs
     .map((evidence) => {
       if (!evidence.evidenceId) return undefined;
       return readPluginActionReceipt(controllerHome, repoId, evidence.evidenceId)
+        ?? readPluginActionReceipt(controllerHome, CONTROLLER_PLUGIN_SCOPE_KEY, evidence.evidenceId)
         ?? readPluginActionReceipt(controllerHome, CONTROLLER_SCOPE_REPO_ID, evidence.evidenceId);
     })
     .find((candidate) => candidate?.workId === workId && candidate.status === 'succeeded');
@@ -1207,17 +1464,17 @@ export function finalizeRemoteEffectWorkFromActionReceipt(
 
 function bindRemoteEffectReceiptToWork(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   action: AssistantPluginActionDescriptor,
   request: AssistantPluginActionRequest,
   receipt: PluginActionReceipt,
 ): WorkContract | undefined {
   if (!request.workId) return undefined;
-  if (receipt.status !== 'succeeded') return remoteEffectWorkForPluginAction(controllerHome, repository, action, request);
-  const work = remoteEffectWorkForPluginAction(controllerHome, repository, action, request, receipt.receiptId);
+  if (receipt.status !== 'succeeded') return remoteEffectWorkForPluginAction(controllerHome, scope, action, request);
+  const work = remoteEffectWorkForPluginAction(controllerHome, scope, action, request, receipt.receiptId);
   if (!work) return undefined;
-  if (work.status === 'completed') return work;
-  const workRepoId = workAttributionRepoId(repository, request);
+  if (work.completionReceipt?.source === 'remote_effect') return work;
+  const workRepoId = workAttributionRepoId(scope, request);
   let updated = work;
   if (!work.evidenceRefs.some((evidence) => evidence.evidenceId === receipt.receiptId)) {
     updated = appendWorkEvidence({ controllerHome, repoId: workRepoId }, work.workId, {
@@ -1254,7 +1511,7 @@ function compatibilityJobFromReceipt(receipt: PluginActionReceipt, checkoutId: s
     schemaVersion: 1,
     revision: 1,
     jobId: receipt.receiptId,
-    repoId: receipt.repoId,
+    repoId: receipt.repoId ?? receipt.scopeKey,
     checkoutId,
     type: 'plugin-action',
     status: receipt.effectOutcome === 'outcome_unknown'
@@ -1286,9 +1543,9 @@ function compatibilityJobFromReceipt(receipt: PluginActionReceipt, checkoutId: s
  * Deterministic plugin action path: validate → authorize/confirm → invoke adapter → receipt.
  * Does not create ExecutionJobs or call a model.
  */
-export async function submitAssistantPluginAction(
+async function submitPluginAction(
   controllerHome: string,
-  repository: RepositoryRecord,
+  scope: PluginActionScopeContext,
   request: AssistantPluginActionRequest,
 ): Promise<{
   manifest: AssistantPluginManifest;
@@ -1302,7 +1559,9 @@ export async function submitAssistantPluginAction(
 }> {
   const adapter = resolvePluginAdapter(controllerHome, request.pluginId);
   if (!adapter) throw new Error(`PLUGIN_NOT_FOUND: ${request.pluginId}`);
-  const manifest = getAssistantPluginManifest(controllerHome, repository, request.pluginId);
+  const manifest = scope.kind === 'controller'
+    ? getControllerPluginManifest(controllerHome, request.pluginId)
+    : getAssistantPluginManifest(controllerHome, scope.repository!, request.pluginId);
   const action = actionForManifest(manifest, request.actionId);
   if (!manifest.enabled && action.actionId !== 'configure') {
     throw new Error(`PLUGIN_DISABLED: ${request.pluginId} is disabled`);
@@ -1313,36 +1572,38 @@ export async function submitAssistantPluginAction(
   const normalizedArgs = validateActionArguments(action, request.args ?? {});
   enforceConfirmation(action, { ...request, args: normalizedArgs });
 
-  const key = semanticKey(repository, request.pluginId, request.actionId, normalizedArgs);
+  const key = semanticKey(scope, request.pluginId, request.actionId, normalizedArgs);
   const requestPath = pluginActionRequestPath(controllerHome, request.requestId);
   if (existsSync(requestPath)) {
     const index = readJsonFile<PluginActionRequestIndex>(requestPath);
     if (index.semanticKey !== key) {
       throw new Error(`REQUEST_ID_CONFLICT: ${request.requestId} already belongs to ${index.semanticKey}`);
     }
-    if (index.repoId !== repository.repoId) {
-      throw new Error(`REQUEST_ID_REPO_CONFLICT: ${request.requestId} already belongs to repository ${index.repoId}`);
+    const existingScopeKey = index.scopeKey?.trim() || index.repoId?.trim();
+    if (!existingScopeKey) throw new Error(`PLUGIN_RECEIPT_REQUEST_SCOPE_CORRUPT: ${request.requestId}`);
+    if (existingScopeKey !== scope.scopeKey) {
+      throw new Error(`REQUEST_ID_SCOPE_CONFLICT: ${request.requestId} already belongs to ${existingScopeKey}`);
     }
-    const existing = readPluginActionReceipt(controllerHome, index.repoId, index.receiptId);
+    const existing = readPluginActionReceipt(controllerHome, existingScopeKey, index.receiptId);
     if (!existing) {
       throw new Error(`PLUGIN_RECEIPT_LOST: ${request.requestId}`);
     }
     if (request.workId && existing.workId !== request.workId) {
       throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_CONFLICT: ${request.requestId} already belongs to Work ${existing.workId ?? 'none'}`);
     }
-    const requestedWorkRepoId = request.workId ? workAttributionRepoId(repository, request) : undefined;
-    if (requestedWorkRepoId && (index.workRepoId ?? index.repoId) !== requestedWorkRepoId) {
-      throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_CONFLICT: ${request.requestId} already belongs to Work repository ${index.workRepoId ?? index.repoId}`);
+    const requestedWorkRepoId = request.workId ? workAttributionRepoId(scope, request) : undefined;
+    if (requestedWorkRepoId && index.workRepoId !== requestedWorkRepoId) {
+      throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_CONFLICT: ${request.requestId} already belongs to Work repository ${index.workRepoId ?? 'none'}`);
     }
     if (request.workId && action.risk === 'remote_write') {
-      bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, existing);
+      bindRemoteEffectReceiptToWork(controllerHome, scope, action, request, existing);
     } else if (request.workId) {
-      bindLocalEffectReceiptToAttributedWork(controllerHome, repository, action, request, existing);
+      bindLocalEffectReceiptToAttributedWork(controllerHome, scope, action, request, existing);
     }
     return {
       manifest,
       action,
-      job: compatibilityJobFromReceipt(existing, repository.activeCheckoutId),
+      job: compatibilityJobFromReceipt(existing, scope.checkoutId ?? CONTROLLER_PLUGIN_SCOPE_KEY),
       deduplicated: true,
       result: existing.result,
       receipt: existing,
@@ -1360,7 +1621,7 @@ export async function submitAssistantPluginAction(
   if (requiresAutomatedWriteAuthorization(request.origin)) {
     activeAuthorizationGrant = await resolveAutomatedWriteAuthorization({
       controllerHome,
-      repository,
+      scope,
       adapter,
       manifest,
       action,
@@ -1380,77 +1641,33 @@ export async function submitAssistantPluginAction(
       };
     }
   }
-  const requiresLocalEffectWork = localSystemActionRequiresWork(
-    repository,
-    request.pluginId,
-    request.actionId,
-    normalizedArgs,
-  );
   const boundRemoteWork = action.risk === 'remote_write'
-    ? remoteEffectWorkForPluginAction(controllerHome, repository, action, request)
+    ? remoteEffectWorkForPluginAction(controllerHome, scope, action, request)
     : undefined;
-  const attributedWork = !requiresLocalEffectWork
-    ? attributedWorkForPluginAction(controllerHome, repository, action, request)
+  // Capability execution never creates semantic Work implicitly. Existing Work
+  // attribution is opt-in through work_id; otherwise the plugin receipt is the
+  // durable effect record.
+  const attributedWork = action.risk !== 'remote_write'
+    ? attributedWorkForPluginAction(controllerHome, scope, action, request)
     : undefined;
-  const acceptedWork = requiresLocalEffectWork
-    ? acceptSubmittedWorkContract(controllerHome, {
-        requestId: request.requestId,
-        repoId: repository.repoId,
-        semanticKey: `local-effect:${key}`,
-        operation: {
-          name: `plugin:${request.pluginId}/${request.actionId}`,
-          semanticKey: key,
-          argumentHash: createHash('sha256').update(JSON.stringify(normalizedArgs)).digest('hex'),
-          mode: 'mutating',
-          idempotent: action.idempotent,
-          replayable: action.idempotent,
-          resourceClaims: claimsForAssistantPluginAction(action, repository, manifest.pluginId),
-        },
-        objective: `Execute bounded controller-local effect ${request.pluginId}/${request.actionId}`,
-        mode: 'direct_control',
-        requestedBy: 'chatgpt',
-        principalId: request.origin.actor,
-        controllerInstanceId: process.env.FORGE_RUNTIME_INSTANCE_ID?.trim()
-          || process.env.FORGE_WRITER_INSTANCE_ID?.trim()
-          || process.env.FORGE_DAEMON_INSTANCE_ID?.trim(),
-        workKind: 'local_effect',
-        risk: workRiskForPluginAction(action),
-        acceptanceCriteria: ['The requested local effect completes within its authorized Target Grant boundary.'],
-        constraints: {
-          requireHandoffOnAmbiguity: true,
-          allowDestructive: action.risk === 'destructive'
-            && request.confirmAuthorization === true
-            && request.confirmationText === action.requiredConfirmationText,
-        },
-      }).contract
-    : undefined;
-  if (acceptedWork) {
-    activateWorkContract(
-      { controllerHome, repoId: repository.repoId },
-      acceptedWork.workId,
-      {
-        phase: 'implementation',
-        summary: `Controller-local plugin action ${request.pluginId}/${request.actionId} started.`,
-        evidenceState: 'partial',
+  if (scope.repository) {
+    appendRuntimeEvent(controllerHome, {
+      repoId: scope.repository.repoId,
+      entityType: 'plugin',
+      entityId: manifest.pluginId,
+      eventType: 'plugin_action_requested',
+      requestId: request.requestId,
+      revision: manifest.revision,
+      data: {
+        actionId: action.actionId,
+        receiptId,
+        risk: action.risk,
+        confirmation: action.confirmation,
+        capabilityId,
+        authorizationReuseSupported: action.confirmation === 'authorization' && Boolean(adapter.resolveAuthorizationContext),
       },
-    );
+    });
   }
-  appendRuntimeEvent(controllerHome, {
-    repoId: repository.repoId,
-    entityType: 'plugin',
-    entityId: manifest.pluginId,
-    eventType: 'plugin_action_requested',
-    requestId: request.requestId,
-    revision: manifest.revision,
-    data: {
-      actionId: action.actionId,
-      receiptId,
-      risk: action.risk,
-      confirmation: action.confirmation,
-      capabilityId,
-      authorizationReuseSupported: action.confirmation === 'authorization' && Boolean(adapter.resolveAuthorizationContext),
-    },
-  });
 
   try {
     if (action.confirmation === 'authorization'
@@ -1458,8 +1675,7 @@ export async function submitAssistantPluginAction(
       && originMayEstablishCapabilityAuthorization(request.origin)) {
       authorizationContext = await adapter.resolveAuthorizationContext({
         controllerHome,
-        repoId: repository.repoId,
-        repoRoot: repository.canonicalRoot,
+        ...pluginActionExecutionFields(scope),
         pluginId: request.pluginId,
         actionId: request.actionId,
         requestId: request.requestId,
@@ -1479,7 +1695,7 @@ export async function submitAssistantPluginAction(
         try {
           activeAuthorizationGrant = findActivePluginCapabilityAuthorization(controllerHome, {
             ownerScope: pluginCapabilityAuthorizationOwnerScope(request.origin),
-            repoId: repository.repoId,
+            repoId: scope.grantRepoId,
             pluginId: request.pluginId,
             capabilityId,
             target: authorizationContext.target,
@@ -1504,15 +1720,21 @@ export async function submitAssistantPluginAction(
       }
     }
 
+    if (action.requiresExplicitCapabilityGrant && !activeAuthorizationGrant) {
+      throw new AssistantPluginError(
+        'PLUGIN_CAPABILITY_GRANT_REQUIRED',
+        `${manifest.pluginId}/${action.actionId} requires an explicit reusable capability grant for its exact target. Run the dedicated authorization action first.`,
+      );
+    }
+
     const result = await withAssistantPluginResourceLeases(
       controllerHome,
-      repository,
+      scope,
       action,
       request,
-      () => executeAssistantPluginAction({
+      () => executePluginActionInScope(scope, {
         controllerHome,
-        repoId: repository.repoId,
-        repoRoot: repository.canonicalRoot,
+        ...pluginActionExecutionFields(scope),
         pluginId: request.pluginId,
         actionId: request.actionId,
         requestId: request.requestId,
@@ -1527,6 +1749,31 @@ export async function submitAssistantPluginAction(
           : undefined,
       }),
     );
+    // create_session materializes the exact provider/session identity during
+    // execution, so its authorization target cannot always be resolved before
+    // the action runs. Resolve that postcondition once after a successful
+    // interactive bootstrap, then persist the same exact-target grant path as
+    // every other authorization-class Browser action. Scheduled execution
+    // still remains grant-only because this branch is interactive-origin only.
+    if (action.actionId === 'create_session'
+      && action.confirmation === 'authorization'
+      && !authorizationContext
+      && originMayEstablishCapabilityAuthorization(request.origin)
+      && adapter.resolveAuthorizationContext) {
+      authorizationContext = await adapter.resolveAuthorizationContext({
+        controllerHome,
+        ...pluginActionExecutionFields(scope),
+        pluginId: request.pluginId,
+        actionId: request.actionId,
+        requestId: request.requestId,
+        args: normalizedArgs,
+        origin: request.origin,
+        jobId: receiptId,
+        timeoutMs: request.timeoutMs,
+        signal: request.signal,
+      });
+    }
+
     if (action.confirmation === 'authorization'
       && authorizationContext
       && !activeAuthorizationGrant
@@ -1534,7 +1781,7 @@ export async function submitAssistantPluginAction(
       try {
         const grant = recordPluginCapabilityAuthorization(controllerHome, {
           ownerScope: pluginCapabilityAuthorizationOwnerScope(request.origin),
-          repoId: repository.repoId,
+          repoId: scope.grantRepoId,
           pluginId: request.pluginId,
           capabilityId,
           target: authorizationContext.target,
@@ -1568,42 +1815,8 @@ export async function submitAssistantPluginAction(
         work: {
           workId: boundRemoteWork.workId,
           workKind: 'remote_effect',
+          semanticState: 'open' as const,
           ...(terminalRemoteEffect ? { completionOutcome: 'completed_remote' as const } : {}),
-          status: terminalRemoteEffect ? 'completed' : 'running',
-        },
-      };
-    }
-    if (acceptedWork) {
-      const recordedAt = new Date().toISOString();
-      const target = localEffectTarget(normalizedArgs, result);
-      appendWorkEvidence({ controllerHome, repoId: repository.repoId }, acceptedWork.workId, {
-        title: 'controller-local effect completed',
-        summary: `${request.pluginId}/${request.actionId} completed for ${target.id}.`,
-        detailLevel: 'summary',
-      });
-      recordWorkCompletionReceipt(
-        { controllerHome, repoId: repository.repoId },
-        acceptedWork.workId,
-        {
-          schemaVersion: 1,
-          receiptId: `LFX-${Date.now()}-${createHash('sha256').update(`${request.requestId}:${acceptedWork.workId}`).digest('hex').slice(0, 8)}`,
-          source: 'local_effect',
-          workId: acceptedWork.workId,
-          operation: `${request.pluginId}/${request.actionId}`,
-          target,
-          changed: true,
-          recordedAt,
-        },
-        'completed_local',
-        'local_effect',
-      );
-      resultWithLineage = {
-        ...result,
-        work: {
-          workId: acceptedWork.workId,
-          workKind: 'local_effect',
-          completionOutcome: 'completed_local',
-          status: 'completed',
         },
       };
     }
@@ -1611,48 +1824,50 @@ export async function submitAssistantPluginAction(
       schemaVersion: 1,
       receiptId,
       requestId: request.requestId,
-      repoId: repository.repoId,
-      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
+      scopeKey: scope.scopeKey,
+      ...(scope.repository ? { repoId: scope.repository.repoId } : {}),
+      ...(request.workId ? { workRepoId: workAttributionRepoId(scope, request) } : {}),
       pluginId: request.pluginId,
       actionId: request.actionId,
       semanticKey: key,
       status: 'succeeded',
       createdAt,
-      ...(acceptedWork
-        ? { workId: acceptedWork.workId }
-        : boundRemoteWork
-          ? { workId: boundRemoteWork.workId }
-          : attributedWork
-            ? { workId: attributedWork.workId }
-            : {}),
+      ...(boundRemoteWork
+        ? { workId: boundRemoteWork.workId }
+        : attributedWork
+          ? { workId: attributedWork.workId }
+          : {}),
       origin: request.origin,
       authorization,
       result: resultWithLineage,
     };
-    writeJsonAtomic(pluginActionReceiptPath(controllerHome, repository.repoId, receiptId), receipt);
+    writeJsonAtomic(pluginActionReceiptPath(controllerHome, scope.scopeKey, receiptId), receipt);
     writeJsonAtomic(requestPath, {
       requestId: request.requestId,
-      repoId: repository.repoId,
-      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
+      scopeKey: scope.scopeKey,
+      ...(scope.repository ? { repoId: scope.repository.repoId } : {}),
+      ...(request.workId ? { workRepoId: workAttributionRepoId(scope, request) } : {}),
       receiptId,
       semanticKey: key,
       createdAt,
     } satisfies PluginActionRequestIndex);
     if (boundRemoteWork) {
-      bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, receipt);
+      bindRemoteEffectReceiptToWork(controllerHome, scope, action, request, receipt);
     } else if (attributedWork) {
-      bindLocalEffectReceiptToAttributedWork(controllerHome, repository, action, request, receipt, attributedWork);
+      bindLocalEffectReceiptToAttributedWork(controllerHome, scope, action, request, receipt, attributedWork);
     }
-    const nextManifest = getAssistantPluginManifest(controllerHome, repository, request.pluginId);
+    const nextManifest = scope.kind === 'controller'
+      ? getControllerPluginManifest(controllerHome, request.pluginId)
+      : getAssistantPluginManifest(controllerHome, scope.repository!, request.pluginId);
     return {
       manifest: nextManifest,
       action,
-      job: compatibilityJobFromReceipt(receipt, repository.activeCheckoutId),
+      job: compatibilityJobFromReceipt(receipt, scope.checkoutId ?? CONTROLLER_PLUGIN_SCOPE_KEY),
       deduplicated: false,
       result: resultWithLineage,
       receipt,
       authorization,
-      workId: acceptedWork?.workId ?? boundRemoteWork?.workId ?? attributedWork?.workId,
+      workId: boundRemoteWork?.workId ?? attributedWork?.workId,
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1663,69 +1878,60 @@ export async function submitAssistantPluginAction(
       ? error.effectOutcome
       : 'failed';
     const outcomeUnknown = effectOutcome === 'outcome_unknown';
+    const failure: NonNullable<PluginActionReceipt['error']> = {
+      code,
+      message: redactSensitiveText(message).text,
+      ...(isAssistantPluginError(error) ? { retryable: error.retryable } : {}),
+    };
+    // Error evidence stays compact; oversized provider diagnostics must not
+    // turn failure settlement into an unbounded persistence write.
+    if (isAssistantPluginError(error) && error.details) {
+      try {
+        const details = redactSensitiveValue(error.details).value;
+        if (Buffer.byteLength(JSON.stringify(details), 'utf8') <= 8_192) failure.details = details;
+      } catch {
+        // Non-JSON provider diagnostics cannot override the settled failure.
+      }
+    }
     const outcomeResult = outcomeUnknown
-      ? { outcome: 'outcome_unknown', error: { code, message } }
+      ? { outcome: 'outcome_unknown', error: failure }
       : undefined;
     if (boundRemoteWork) {
-      appendWorkEvidence({ controllerHome, repoId: workAttributionRepoId(repository, request) }, boundRemoteWork.workId, {
+      appendWorkEvidence({ controllerHome, repoId: workAttributionRepoId(scope, request) }, boundRemoteWork.workId, {
         title: outcomeUnknown ? 'typed remote plugin effect outcome unknown' : 'typed remote plugin effect failed',
         summary: `${request.pluginId}/${request.actionId}: ${message}`.slice(0, 1_000),
         detailLevel: 'summary',
       });
     }
-    if (acceptedWork) {
-      if (outcomeUnknown) {
-        appendWorkEvidence({ controllerHome, repoId: repository.repoId }, acceptedWork.workId, {
-          title: 'controller-local effect outcome unknown',
-          summary: `${request.pluginId}/${request.actionId}: ${message}`.slice(0, 1_000),
-          detailLevel: 'summary',
-        });
-      } else {
-        const current = getWorkContract({ controllerHome, repoId: repository.repoId }, acceptedWork.workId);
-        failWorkContract(
-          { controllerHome, repoId: repository.repoId },
-          acceptedWork.workId,
-          {
-            phase: current?.phase ?? 'implementation',
-            summary: `Controller-local plugin action failed: ${request.pluginId}/${request.actionId}: ${message}`.slice(0, 1_000),
-            evidenceRefs: [{
-              title: 'controller-local effect failed',
-              summary: `${request.pluginId}/${request.actionId}: ${message}`.slice(0, 1_000),
-              detailLevel: 'summary',
-            }, ...(current?.evidenceRefs ?? [])],
-          },
-        );
-      }
-    }
     const receipt: PluginActionReceipt = {
       schemaVersion: 1,
       receiptId,
       requestId: request.requestId,
-      repoId: repository.repoId,
-      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
+      scopeKey: scope.scopeKey,
+      ...(scope.repository ? { repoId: scope.repository.repoId } : {}),
+      ...(request.workId ? { workRepoId: workAttributionRepoId(scope, request) } : {}),
       pluginId: request.pluginId,
       actionId: request.actionId,
       semanticKey: key,
       status: 'failed',
       effectOutcome,
       createdAt,
-      ...(acceptedWork
-        ? { workId: acceptedWork.workId }
-        : boundRemoteWork
-          ? { workId: boundRemoteWork.workId }
-          : attributedWork
-            ? { workId: attributedWork.workId }
-            : {}),
+      ...(boundRemoteWork
+        ? { workId: boundRemoteWork.workId }
+        : attributedWork
+          ? { workId: attributedWork.workId }
+          : {}),
       origin: request.origin,
       authorization,
       ...(outcomeResult ? { result: outcomeResult } : {}),
-      error: { code, message },
+      error: failure,
     };
-    writeJsonAtomic(pluginActionReceiptPath(controllerHome, repository.repoId, receiptId), receipt);
+    writeJsonAtomic(pluginActionReceiptPath(controllerHome, scope.scopeKey, receiptId), receipt);
     writeJsonAtomic(requestPath, {
       requestId: request.requestId,
-      repoId: repository.repoId,
-      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
+      scopeKey: scope.scopeKey,
+      ...(scope.repository ? { repoId: scope.repository.repoId } : {}),
+      ...(request.workId ? { workRepoId: workAttributionRepoId(scope, request) } : {}),
       receiptId,
       semanticKey: key,
       createdAt,
@@ -1734,40 +1940,42 @@ export async function submitAssistantPluginAction(
       return {
         manifest,
         action,
-        job: compatibilityJobFromReceipt(receipt, repository.activeCheckoutId),
+        job: compatibilityJobFromReceipt(receipt, scope.checkoutId ?? CONTROLLER_PLUGIN_SCOPE_KEY),
         deduplicated: false,
         result: outcomeResult,
         receipt,
         authorization,
-        workId: acceptedWork?.workId ?? boundRemoteWork?.workId ?? attributedWork?.workId,
+        workId: boundRemoteWork?.workId ?? attributedWork?.workId,
       };
     }
     throw error;
   }
 }
 
-export async function executeControllerScopedPluginAction(
-  input: Omit<AssistantPluginActionExecutionInput, 'repoId' | 'repoRoot'>,
-): Promise<Record<string, unknown>> {
-  const repository = controllerPluginRepository(input.controllerHome);
-  return executeAssistantPluginAction({
-    ...input,
-    repoId: repository.repoId,
-    repoRoot: repository.canonicalRoot,
-  });
+export function submitAssistantPluginAction(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  request: AssistantPluginActionRequest,
+) {
+  return submitPluginAction(controllerHome, repositoryPluginActionScope(repository), request);
 }
 
-export async function executeAssistantPluginAction(
+export function submitControllerPluginAction(
+  controllerHome: string,
+  request: AssistantPluginActionRequest,
+) {
+  return submitPluginAction(controllerHome, controllerPluginActionScope(controllerHome), request);
+}
+
+async function executePluginActionInScope(
+  scope: PluginActionScopeContext,
   input: AssistantPluginActionExecutionInput,
 ): Promise<Record<string, unknown>> {
   const adapter = resolvePluginAdapter(input.controllerHome, input.pluginId);
   if (!adapter) throw new Error(`PLUGIN_NOT_FOUND: ${input.pluginId}`);
-  const repository = {
-    repoId: input.repoId,
-    canonicalRoot: input.repoRoot,
-    activeCheckoutId: 'active',
-  } as RepositoryRecord;
-  const manifestLookup = getAssistantPluginManifestForExecution(input.controllerHome, repository, input.pluginId, adapter);
+  const manifestLookup = scope.kind === 'controller'
+    ? getControllerPluginManifestForExecution(input.controllerHome, input.pluginId, adapter)
+    : getAssistantPluginManifestForExecution(input.controllerHome, scope.repository!, input.pluginId, adapter);
   const manifest = manifestLookup.manifest;
   const action = actionForManifest(manifest, input.actionId);
   if (action.executionMode === 'direct_non_persistent') {
@@ -1777,7 +1985,7 @@ export async function executeAssistantPluginAction(
   if (requiresAutomatedWriteAuthorization(input.origin)) {
     await resolveAutomatedWriteAuthorization({
       controllerHome: input.controllerHome,
-      repository,
+      scope,
       adapter,
       manifest,
       action,
@@ -1791,38 +1999,53 @@ export async function executeAssistantPluginAction(
   try {
     const result = await adapter.executeAction({
       ...input,
+      ...pluginActionExecutionFields(scope),
       args: normalizedArgs,
       providerIdentityPrevalidated: manifestLookup.providerIdentityPrevalidated,
     });
     for (const affectedPluginId of adapter.affectedPluginIdsAfterAction?.(input.actionId, result) ?? []) {
       if (!affectedPluginId || affectedPluginId === input.pluginId) continue;
-      invalidateAssistantPluginManifestCache(input.controllerHome, repository.repoId, affectedPluginId);
       const affectedAdapter = resolvePluginAdapter(input.controllerHome, affectedPluginId);
-      if (affectedAdapter && adapterMatchesRepository(affectedAdapter, repository)) {
-        syncAssistantPluginManifest(input.controllerHome, repository, affectedPluginId);
+      if (scope.kind === 'controller') {
+        invalidateAssistantPluginManifestCache(input.controllerHome, CONTROLLER_PLUGIN_CACHE_SCOPE, affectedPluginId);
+        if (affectedAdapter && adapterMatchesController(affectedAdapter)) {
+          syncControllerPluginManifest(input.controllerHome, affectedPluginId);
+        } else {
+          removeControllerPluginManifestProjection(input.controllerHome, affectedPluginId);
+        }
       } else {
-        rmSync(manifestPath(input.controllerHome, repository.repoId, affectedPluginId), { force: true });
+        const repository = scope.repository!;
+        invalidateAssistantPluginManifestCache(input.controllerHome, repository.repoId, affectedPluginId);
+        if (affectedAdapter && adapterMatchesRepository(affectedAdapter, repository)) {
+          syncAssistantPluginManifest(input.controllerHome, repository, affectedPluginId);
+        } else {
+          rmSync(manifestPath(input.controllerHome, repository.repoId, affectedPluginId), { force: true });
+        }
       }
     }
     const refreshManifest = adapter.shouldRefreshManifestAfterAction?.(input.actionId) ?? true;
     const nextManifest = refreshManifest
-      ? syncAssistantPluginManifest(input.controllerHome, repository, input.pluginId).manifest
+      ? scope.kind === 'controller'
+        ? syncControllerPluginManifest(input.controllerHome, input.pluginId).manifest
+        : syncAssistantPluginManifest(input.controllerHome, scope.repository!, input.pluginId).manifest
       : manifest;
-    appendRuntimeEvent(input.controllerHome, {
-      repoId: input.repoId,
-      entityType: 'plugin',
-      entityId: input.pluginId,
-      eventType: 'plugin_action_succeeded',
-      requestId: input.requestId,
-      revision: nextManifest.revision,
-      data: {
-        actionId: input.actionId,
-        jobId: input.jobId,
-        resultKeys: Object.keys(result).slice(0, 20),
-        lifecycleState: nextManifest.lifecycle.state,
-        healthState: nextManifest.health.state,
-      },
-    });
+    if (scope.repository) {
+      appendRuntimeEvent(input.controllerHome, {
+        repoId: scope.repository.repoId,
+        entityType: 'plugin',
+        entityId: input.pluginId,
+        eventType: 'plugin_action_succeeded',
+        requestId: input.requestId,
+        revision: nextManifest.revision,
+        data: {
+          actionId: input.actionId,
+          jobId: input.jobId,
+          resultKeys: Object.keys(result).slice(0, 20),
+          lifecycleState: nextManifest.lifecycle.state,
+          healthState: nextManifest.health.state,
+        },
+      });
+    }
     return {
       schemaVersion: 1,
       plugin: {
@@ -1850,25 +2073,49 @@ export async function executeAssistantPluginAction(
         actionId: input.actionId,
       },
     });
-    const refreshed = syncAssistantPluginManifest(input.controllerHome, repository, input.pluginId);
-    const nextManifest = refreshed.manifest;
-    appendRuntimeEvent(input.controllerHome, {
-      repoId: input.repoId,
-      entityType: 'plugin',
-      entityId: input.pluginId,
-      eventType: 'plugin_action_failed',
-      requestId: input.requestId,
-      revision: nextManifest.revision,
-      data: {
-        actionId: input.actionId,
-        jobId: input.jobId,
-        code: pluginError.code,
-        retryable: pluginError.retryable,
-      },
-    });
+    const nextManifest = scope.kind === 'controller'
+      ? syncControllerPluginManifest(input.controllerHome, input.pluginId).manifest
+      : syncAssistantPluginManifest(input.controllerHome, scope.repository!, input.pluginId).manifest;
+    if (scope.repository) {
+      appendRuntimeEvent(input.controllerHome, {
+        repoId: scope.repository.repoId,
+        entityType: 'plugin',
+        entityId: input.pluginId,
+        eventType: 'plugin_action_failed',
+        requestId: input.requestId,
+        revision: nextManifest.revision,
+        data: {
+          actionId: input.actionId,
+          jobId: input.jobId,
+          code: pluginError.code,
+          retryable: pluginError.retryable,
+        },
+      });
+    }
     throw new AssistantPluginError(pluginError.code, pluginError.message.replace(/^[^:]+:\s*/, ''), {
       retryable: pluginError.retryable,
       details: pluginError.details,
     });
   }
 }
+
+export function executeControllerScopedPluginAction(
+  input: Omit<AssistantPluginActionExecutionInput, 'repoId' | 'repoRoot'>,
+): Promise<Record<string, unknown>> {
+  const scope = controllerPluginActionScope(input.controllerHome);
+  return executePluginActionInScope(scope, {
+    ...input,
+    ...pluginActionExecutionFields(scope),
+  });
+}
+
+export function executeAssistantPluginAction(
+  input: AssistantPluginActionExecutionInput,
+): Promise<Record<string, unknown>> {
+  const repository = {
+    repoId: input.repoId,
+    canonicalRoot: input.repoRoot,
+    activeCheckoutId: 'active',
+  } as RepositoryRecord;
+  return executePluginActionInScope(repositoryPluginActionScope(repository), input);
+}