@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/plugins/store.ts

@@ -2,28 +2,34 @@ import { createHash } 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 { existsSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'fs';
 import type { ExecutionJob, ResourceClaimSpec } from '../execution/jobs/types';
 import { appendRuntimeEvent } from '../evidence/event-ledger';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 import { createFirstPartyPluginAdapterMap } from './first-party-registry';
+import { reconcileFirstPartyExternalPluginRegistration, reconcileFirstPartyExternalPluginRegistrations } from './first-party-external-registration';
+import { REPOSITORY_PLUGIN_CONFIG_IDS, repositoryPluginConfigFileName, repositoryPluginConfigPath } from './config-store';
 import { getExternalPluginAdapter, listExternalPluginAdapters } from './external-adapter';
-import { AssistantPluginError, toAssistantPluginError } from './errors';
+import { AssistantPluginError, isAssistantPluginError, toAssistantPluginError, type AssistantPluginEffectOutcome } from './errors';
 import {
+  findActivePluginCapabilityAuthorizationById,
   findActivePluginCapabilityAuthorization,
   pluginCapabilityAuthorizationOwnerScope,
   recordPluginCapabilityAuthorization,
   type PluginCapabilityAuthorizationGrant,
 } 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 {
   acceptSubmittedWorkContract,
+  activateWorkContract,
   appendWorkEvidence,
+  failWorkContract,
   getWorkContract,
   recordWorkCompletionReceipt,
   updateWorkContract,
-} from '../control-plane/facade/work-contract-store';
+} from '../../../packages/kernel/work/api/index';
 import { isTerminalWorkContractStatus, type LocalEffectCompletionReceipt, type RemoteEffectCompletionReceipt, type WorkContract, type WorkRisk } from '../control-plane/facade/types';
 import type {
   AssistantPluginAdapter,
@@ -43,8 +49,10 @@ function resolvePluginAdapter(controllerHome: string, pluginId: string): Assista
 }
 
 function listPluginAdapters(controllerHome: string): AssistantPluginAdapter[] {
-  const external = listExternalPluginAdapters(controllerHome).filter((adapter) => !PLUGIN_ADAPTERS.has(adapter.pluginId));
-  return [...PLUGIN_ADAPTERS.values(), ...external];
+  const firstParty = [...PLUGIN_ADAPTERS.values()].filter((adapter) => adapter.exposure !== 'internal');
+  const external = listExternalPluginAdapters(controllerHome)
+    .filter((adapter) => !PLUGIN_ADAPTERS.has(adapter.pluginId) && adapter.exposure !== 'internal');
+  return [...firstParty, ...external];
 }
 
 export function assistantPluginScope(pluginId: string, controllerHome?: string): AssistantPluginAdapter['scope'] | undefined {
@@ -89,6 +97,39 @@ export function controllerPluginRepository(controllerHome: string): RepositoryRe
   };
 }
 
+/**
+ * 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);
+}
+
+export function listControllerPluginManifests(
+  controllerHome: string,
+  options: ListAssistantPluginManifestsOptions = {},
+): AssistantPluginManifest[] {
+  return listAssistantPluginManifests(controllerHome, controllerPluginRepository(controllerHome), options);
+}
+
+export function getControllerPluginManifest(controllerHome: string, pluginId: string): AssistantPluginManifest {
+  return getAssistantPluginManifest(controllerHome, controllerPluginRepository(controllerHome), pluginId);
+}
+
+export function syncControllerPluginRegistry(controllerHome: string) {
+  reconcileFirstPartyExternalPluginRegistrations(controllerHome);
+  return syncAssistantPluginRegistry(controllerHome, controllerPluginRepository(controllerHome));
+}
+
+export function syncControllerPluginManifest(controllerHome: string, pluginId: string) {
+  reconcileFirstPartyExternalPluginRegistration(controllerHome, pluginId);
+  return syncAssistantPluginManifest(controllerHome, controllerPluginRepository(controllerHome), pluginId);
+}
+
+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;
@@ -99,8 +140,9 @@ function cloneCacheValue<T>(value: T): T {
   return structuredClone(value);
 }
 
-function listCacheKey(controllerHome: string, repoId: string, preferStored: boolean): string {
-  return `${controllerHome}::${repoId}::list::${preferStored ? 'stored' : 'live'}`;
+function listCacheKey(controllerHome: string, repoId: string, preferStored: boolean, fallbackToLive: boolean): string {
+  const mode = preferStored ? (fallbackToLive ? 'stored-with-live-fallback' : 'stored-only') : 'live';
+  return `${controllerHome}::${repoId}::list::${mode}`;
 }
 
 function itemCacheKey(controllerHome: string, repoId: string, pluginId: string, preferStored: boolean): string {
@@ -236,6 +278,15 @@ function readStoredManifest(controllerHome: string, repoId: string, pluginId: st
   }
 }
 
+/** Read-only persisted plugin projection. This never probes or rebuilds a provider manifest. */
+export function readStoredAssistantPluginManifest(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  pluginId: string,
+): AssistantPluginManifest | undefined {
+  return readStoredManifest(controllerHome, repository.repoId, pluginId);
+}
+
 function cachedManifestForRepository(
   controllerHome: string,
   repoId: string,
@@ -248,12 +299,48 @@ function cachedManifestForRepository(
   ) ?? readPluginManifestCache(pluginManifestItemCache, itemCacheKey(controllerHome, repoId, pluginId, false));
 }
 
+export function migrateRepositoryPluginConfigLegacyFiles(
+  controllerHome: string,
+  repository: Pick<RepositoryRecord, 'repoId' | 'canonicalRoot'>,
+): string {
+  const targetRoot = join(repositoryControllerRoot(controllerHome, repository.repoId), 'plugins', 'config');
+  const legacyRoots = [
+    join(repository.canonicalRoot, '.forge', 'plugins'),
+    join(repository.canonicalRoot, '.repo-harness', 'plugins'),
+  ];
+  mkdirSync(targetRoot, { recursive: true });
+  for (const legacyRoot of legacyRoots) {
+    if (!existsSync(legacyRoot)) continue;
+    const stat = lstatSync(legacyRoot);
+    // Historical compatibility symlinks may point at another Controller Home.
+    // Never traverse them; unlink only the retired repository-local compatibility entry.
+    if (stat.isSymbolicLink()) {
+      rmSync(legacyRoot, { force: true });
+      continue;
+    }
+    if (!stat.isDirectory()) throw new Error(`PLUGIN_CONFIG_LEGACY_PATH_INVALID: ${legacyRoot}`);
+    for (const pluginId of REPOSITORY_PLUGIN_CONFIG_IDS) {
+      const fileName = repositoryPluginConfigFileName(pluginId);
+      const source = join(legacyRoot, fileName);
+      if (!existsSync(source)) continue;
+      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 });
+      rmSync(source, { force: true });
+    }
+    if (readdirSync(legacyRoot).length === 0) rmSync(legacyRoot, { recursive: true, force: true });
+  }
+  return targetRoot;
+}
+
 function computeManifest(
   controllerHome: string,
   repository: RepositoryRecord,
   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);
@@ -307,6 +394,71 @@ export function claimsForAssistantPluginAction(
   }));
 }
 
+async function withAssistantPluginResourceLeases<T>(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  action: AssistantPluginActionDescriptor,
+  request: AssistantPluginActionRequest,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const claims = claimsForAssistantPluginAction(action, repository, request.pluginId).map((claim) => ({
+    ...claim,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+  }));
+  if (claims.length === 0) return operation();
+
+  const ownerJobId = `plugin:${request.requestId}`;
+  const timeoutMs = Math.max(5_000, Math.min(10 * 60_000, request.timeoutMs ?? action.defaultTimeoutMs));
+  const acquisition = acquireExecutionLeases(controllerHome, repository.repoId, ownerJobId, claims, {
+    ttlMs: timeoutMs + 60_000,
+    ownerIdentity: {
+      repositoryId: repository.repoId,
+      checkoutId: repository.activeCheckoutId,
+      worktreeId: repository.activeCheckoutId,
+      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()
+        || process.env.FORGE_ACTIVE_RUNTIME_REVISION?.trim()
+        || 'unbound',
+    },
+  });
+  if (!acquisition.acquired) {
+    throw new AssistantPluginError(
+      'PLUGIN_RESOURCE_CONTENTION',
+      `${request.pluginId}/${request.actionId} could not acquire its declared resource claims before dispatch.`,
+      { retryable: true, details: { blockers: acquisition.blockers } },
+    );
+  }
+  const expected = acquisition.leases.map((lease) => ({
+    leaseId: lease.leaseId,
+    fencingToken: lease.fencingToken,
+    repoId: lease.repoId,
+    checkoutId: lease.checkoutId,
+    resourceKey: lease.resourceKey,
+    ownerIdentityDigest: lease.ownerIdentityDigest,
+  }));
+  let retainForReconciliation = false;
+  try {
+    const result = await operation();
+    const nestedResult = result && typeof result === 'object' && !Array.isArray(result)
+      ? (result as Record<string, unknown>).result
+      : undefined;
+    retainForReconciliation = Boolean(nestedResult && typeof nestedResult === 'object' && !Array.isArray(nestedResult)
+      && (nestedResult as Record<string, unknown>).outcome === 'outcome_unknown');
+    return result;
+  } catch (error) {
+    retainForReconciliation = isAssistantPluginError(error) && error.effectOutcome === 'outcome_unknown';
+    throw error;
+  } finally {
+    if (!retainForReconciliation) releaseExactExecutionLeases(controllerHome, repository.repoId, ownerJobId, expected);
+  }
+}
+
 function semanticKey(repository: RepositoryRecord, 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}`;
@@ -408,6 +560,92 @@ function originMayEstablishCapabilityAuthorization(origin: AssistantPluginAction
   return INTERACTIVE_PLUGIN_AUTHORIZATION_SURFACES.has(origin.surface);
 }
 
+function requiresAutomatedWriteAuthorization(origin: AssistantPluginActionExecutionInput['origin']): boolean {
+  return ['schedule', 'reconciliation', 'system'].includes(origin.surface);
+}
+
+const AUTHORIZATION_RISK_RANK: Record<AssistantPluginActionDescriptor['risk'], number> = {
+  readonly: 0,
+  workspace_write: 1,
+  remote_write: 2,
+  destructive: 3,
+};
+
+function authorizationTargetMatches(
+  left: PluginCapabilityAuthorizationGrant['target'],
+  right: PluginCapabilityAuthorizationGrant['target'],
+): boolean {
+  return left.kind === right.kind
+    && left.id === right.id
+    && (left.identityFingerprint ?? '') === (right.identityFingerprint ?? '');
+}
+
+async function resolveAutomatedWriteAuthorization(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  adapter: AssistantPluginAdapter;
+  manifest: AssistantPluginManifest;
+  action: AssistantPluginActionDescriptor;
+  args: Record<string, unknown>;
+  origin: AssistantPluginActionExecutionInput['origin'];
+  requestId: string;
+  jobId?: string;
+  authorizationGrantRefs?: readonly string[];
+}): Promise<PluginCapabilityAuthorizationGrant | undefined> {
+  if (input.action.readOnly) return undefined;
+  if (input.action.confirmation === 'strong_confirmation') {
+    throw new AssistantPluginError(
+      'EXTERNAL_EFFECT_AUTHORIZATION_REQUIRED',
+      `${input.manifest.pluginId}/${input.action.actionId} requires an interactive strong confirmation.`,
+      { retryable: false },
+    );
+  }
+  const refs = [...new Set((input.authorizationGrantRefs ?? []).map((ref) => ref.trim()).filter(Boolean))];
+  if (refs.length === 0 || !input.adapter.resolveAuthorizationContext) {
+    throw new AssistantPluginError(
+      'EXTERNAL_EFFECT_AUTHORIZATION_REQUIRED',
+      `${input.manifest.pluginId}/${input.action.actionId} requires an active Workflow capability grant.`,
+      { retryable: false },
+    );
+  }
+  const targetContext = await input.adapter.resolveAuthorizationContext({
+    controllerHome: input.controllerHome,
+    repoId: input.repository.repoId,
+    repoRoot: input.repository.canonicalRoot,
+    pluginId: input.manifest.pluginId,
+    actionId: input.action.actionId,
+    requestId: input.requestId,
+    args: input.args,
+    origin: input.origin,
+    jobId: input.jobId,
+  });
+  if (!targetContext) {
+    throw new AssistantPluginError(
+      'PLUGIN_CAPABILITY_GRANT_TARGET_UNAVAILABLE',
+      `${input.manifest.pluginId}/${input.action.actionId} did not resolve an exact authorization target.`,
+      { retryable: false },
+    );
+  }
+  const capabilityId = reusableCapabilityId(input.manifest, input.action);
+  const grant = refs
+    .map((ref) => findActivePluginCapabilityAuthorizationById(input.controllerHome, ref))
+    .find((candidate) => candidate
+      && candidate.repoId === input.repository.repoId
+      && candidate.pluginId === input.manifest.pluginId
+      && candidate.capabilityId === capabilityId
+      && authorizationTargetMatches(candidate.target, targetContext.target)
+      && input.action.scopes.every((scope) => candidate.scopes.includes(scope))
+      && AUTHORIZATION_RISK_RANK[candidate.riskCeiling] >= AUTHORIZATION_RISK_RANK[input.action.risk]);
+  if (!grant) {
+    throw new AssistantPluginError(
+      'PLUGIN_CAPABILITY_GRANT_NOT_FOUND',
+      `${input.manifest.pluginId}/${input.action.actionId} has no active grant for this exact target.`,
+      { retryable: false },
+    );
+  }
+  return grant;
+}
+
 function authorizationTargetSummary(context: AssistantPluginAuthorizationContext): { kind: string; id: string } {
   return { kind: context.target.kind, id: context.target.id };
 }
@@ -429,19 +667,15 @@ function initialAuthorizationEvidence(
   return { source: 'host_permission_model', reusable: false, capabilityId };
 }
 
-function denyAutomatedWrite(manifest: AssistantPluginManifest, action: AssistantPluginActionDescriptor, origin: AssistantPluginActionExecutionInput['origin']): void {
-  if (!['schedule', 'reconciliation', 'system'].includes(origin.surface)) return;
-  if (action.readOnly) return;
-  throw new Error(`EXTERNAL_EFFECT_AUTHORIZATION_REQUIRED: ${manifest.pluginId}/${action.actionId} cannot run from ${origin.surface}`);
-}
-
 export type ListAssistantPluginManifestsOptions = {
   /**
    * Prefer previously persisted manifests for connector/status hot paths.
    * Live adapter rebuild (including host probes such as Xcode) runs only when
-   * no stored manifest exists, or when forceRefresh is true.
+   * no stored manifest exists, unless fallbackToLive=false, or when forceRefresh is true.
    */
   preferStored?: boolean;
+  /** Materialized projections set this false so a cold summary never synchronously probes providers. */
+  fallbackToLive?: boolean;
   forceRefresh?: boolean;
 };
 
@@ -458,7 +692,8 @@ export function listAssistantPluginManifests(
   options: ListAssistantPluginManifestsOptions = {},
 ): AssistantPluginManifest[] {
   const preferStored = options.preferStored === true && options.forceRefresh !== true;
-  const cacheKey = listCacheKey(controllerHome, repository.repoId, preferStored);
+  const fallbackToLive = options.fallbackToLive !== false || !preferStored;
+  const cacheKey = listCacheKey(controllerHome, repository.repoId, preferStored, fallbackToLive);
   if (options.forceRefresh !== true) {
     // Stored manifests are persisted snapshots. Their freshness is governed by
     // explicit registry/config mutation invalidation, not a wall-clock trust
@@ -475,9 +710,11 @@ export function listAssistantPluginManifests(
       if (preferStored) {
         const stored = readStoredManifest(controllerHome, repository.repoId, pluginId);
         if (stored) return stored;
+        if (!fallbackToLive) return undefined;
       }
       return computeManifest(controllerHome, repository, pluginId);
     })
+    .filter((manifest): manifest is AssistantPluginManifest => Boolean(manifest))
     .sort((left, right) => left.pluginId.localeCompare(right.pluginId));
   primePluginManifestItemCache(controllerHome, repository.repoId, manifests, preferStored);
   return writePluginManifestCache(pluginManifestListCache, cacheKey, manifests);
@@ -533,7 +770,7 @@ export function syncAssistantPluginRegistry(
   };
 }
 
-function syncAssistantPluginManifest(
+export function syncAssistantPluginManifest(
   controllerHome: string,
   repository: RepositoryRecord,
   pluginId: string,
@@ -558,6 +795,29 @@ function syncAssistantPluginManifest(
   };
 }
 
+/** Remove one persisted plugin projection without probing or rebuilding unrelated providers. */
+export function removeAssistantPluginManifestProjection(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  pluginId: string,
+): AssistantPluginRegistryIndex {
+  invalidateAssistantPluginManifestCache(controllerHome, repository.repoId, pluginId);
+  rmSync(manifestPath(controllerHome, repository.repoId, pluginId), { force: true });
+  const current = readJsonFile<AssistantPluginRegistryIndex>(indexPath(controllerHome, repository.repoId), {
+    schemaVersion: 1,
+    updatedAt: now(),
+    plugins: [],
+  });
+  const next: AssistantPluginRegistryIndex = {
+    ...current,
+    updatedAt: now(),
+    plugins: current.plugins.filter((entry) => entry.pluginId !== pluginId),
+  };
+  writeJsonAtomic(indexPath(controllerHome, repository.repoId), next);
+  markControllerContextProjectionDirty(repository.canonicalRoot, `plugin:${pluginId}:removed`);
+  return next;
+}
+
 export function isDirectPluginReadAction(action: AssistantPluginActionDescriptor): boolean {
   return action.readOnly === true
     && action.risk === 'readonly'
@@ -565,6 +825,76 @@ export function isDirectPluginReadAction(action: AssistantPluginActionDescriptor
     && 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;
+}
+
+export async function executeAssistantPluginDirectNonPersistent(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  request: AssistantPluginActionRequest,
+): Promise<{ manifest: AssistantPluginManifest; action: AssistantPluginActionDescriptor; result: Record<string, unknown> }> {
+  const adapter = resolvePluginAdapter(controllerHome, request.pluginId);
+  if (!adapter) throw new Error(`PLUGIN_NOT_FOUND: ${request.pluginId}`);
+  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 manifest = manifestLookup.manifest;
+  const action = actionForManifest(manifest, request.actionId);
+  if (!manifest.enabled && action.actionId !== 'configure') {
+    throw new Error(`PLUGIN_DISABLED: ${request.pluginId} is disabled`);
+  }
+  if (action.executionMode !== 'direct_non_persistent') {
+    throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_NOT_ALLOWED: ${request.pluginId}/${request.actionId}`);
+  }
+  if (!isDirectNonPersistentPluginAction(action)) {
+    throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_CONTRACT_INVALID: ${request.pluginId}/${request.actionId}`);
+  }
+  if (request.workId || request.workRepoId) {
+    throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_WORK_ATTRIBUTION_FORBIDDEN: ${request.pluginId}/${request.actionId}`);
+  }
+  if (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 ?? {});
+  enforceConfirmation(action, { ...request, args: normalizedArgs });
+  if (requiresAutomatedWriteAuthorization(request.origin)) {
+    await resolveAutomatedWriteAuthorization({
+      controllerHome,
+      repository,
+      adapter,
+      manifest,
+      action,
+      args: normalizedArgs,
+      origin: request.origin,
+      requestId: request.requestId,
+      authorizationGrantRefs: request.authorizationGrantRefs,
+    });
+  }
+  const result = await adapter.executeAction({
+    controllerHome,
+    repoId: repository.repoId,
+    repoRoot: repository.canonicalRoot,
+    pluginId: request.pluginId,
+    actionId: request.actionId,
+    requestId: request.requestId,
+    args: normalizedArgs,
+    origin: request.origin,
+    timeoutMs: request.timeoutMs,
+    signal: request.signal,
+    authorizationGrantRefs: request.authorizationGrantRefs,
+    providerIdentityPrevalidated: manifestLookup.providerIdentityPrevalidated,
+  });
+  return { manifest, action, result };
+}
+
 export async function executeAssistantPluginReadDirect(
   controllerHome: string,
   repository: RepositoryRecord,
@@ -604,6 +934,8 @@ export interface PluginActionReceipt {
   actionId: string;
   semanticKey: string;
   status: 'succeeded' | 'failed';
+  /** Durable semantic disposition for an attempted external/local effect. */
+  effectOutcome?: AssistantPluginEffectOutcome;
   createdAt: string;
   workId?: string;
   origin?: { surface: string; actor?: string; correlationId?: string };
@@ -661,6 +993,17 @@ export function findPluginActionReceipt(
   return undefined;
 }
 
+/** Exact request lookup for subordinate Workflow recovery; never dispatches an action. */
+export function readPluginActionReceiptForRequest(controllerHome: string, requestId: string): PluginActionReceipt | undefined {
+  const path = pluginActionRequestPath(controllerHome, requestId);
+  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);
+  if (!receipt || receipt.requestId !== requestId || receipt.semanticKey !== index.semanticKey) throw new Error('PLUGIN_RECEIPT_LOST');
+  return receipt;
+}
+
 export function compatibilityPluginJobFromReceipt(
   receipt: PluginActionReceipt,
   checkoutId = 'unknown',
@@ -914,7 +1257,9 @@ function compatibilityJobFromReceipt(receipt: PluginActionReceipt, checkoutId: s
     repoId: receipt.repoId,
     checkoutId,
     type: 'plugin-action',
-    status: receipt.status === 'succeeded' ? 'succeeded' : 'failed',
+    status: receipt.effectOutcome === 'outcome_unknown'
+      ? 'human_attention_required'
+      : receipt.status === 'succeeded' ? 'succeeded' : 'failed',
     priority: 'P2',
     requestId: receipt.requestId,
     semanticKey: receipt.semanticKey,
@@ -962,6 +1307,9 @@ export async function submitAssistantPluginAction(
   if (!manifest.enabled && action.actionId !== 'configure') {
     throw new Error(`PLUGIN_DISABLED: ${request.pluginId} is disabled`);
   }
+  if (action.executionMode === 'direct_non_persistent') {
+    throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_RECEIPT_PATH_FORBIDDEN: ${request.pluginId}/${request.actionId}`);
+  }
   const normalizedArgs = validateActionArguments(action, request.args ?? {});
   enforceConfirmation(action, { ...request, args: normalizedArgs });
 
@@ -1009,6 +1357,29 @@ export async function submitAssistantPluginAction(
   let authorization = initialAuthorizationEvidence(manifest, action);
   let authorizationContext: AssistantPluginAuthorizationContext | undefined;
   let activeAuthorizationGrant: PluginCapabilityAuthorizationGrant | undefined;
+  if (requiresAutomatedWriteAuthorization(request.origin)) {
+    activeAuthorizationGrant = await resolveAutomatedWriteAuthorization({
+      controllerHome,
+      repository,
+      adapter,
+      manifest,
+      action,
+      args: normalizedArgs,
+      origin: request.origin,
+      requestId: request.requestId,
+      jobId: receiptId,
+      authorizationGrantRefs: request.authorizationGrantRefs,
+    });
+    if (activeAuthorizationGrant) {
+      authorization = {
+        source: 'capability_grant',
+        reusable: true,
+        capabilityId,
+        target: activeAuthorizationGrant.target,
+        grantId: activeAuthorizationGrant.grantId,
+      };
+    }
+  }
   const requiresLocalEffectWork = localSystemActionRequiresWork(
     repository,
     request.pluginId,
@@ -1054,12 +1425,15 @@ export async function submitAssistantPluginAction(
       }).contract
     : undefined;
   if (acceptedWork) {
-    updateWorkContract({ controllerHome, repoId: repository.repoId }, acceptedWork.workId, {
-      status: 'running',
-      workKind: 'local_effect',
-      dispatchState: 'running',
-      evidenceState: 'partial',
-    });
+    activateWorkContract(
+      { controllerHome, repoId: repository.repoId },
+      acceptedWork.workId,
+      {
+        phase: 'implementation',
+        summary: `Controller-local plugin action ${request.pluginId}/${request.actionId} started.`,
+        evidenceState: 'partial',
+      },
+    );
   }
   appendRuntimeEvent(controllerHome, {
     repoId: repository.repoId,
@@ -1130,22 +1504,29 @@ export async function submitAssistantPluginAction(
       }
     }
 
-    const result = await executeAssistantPluginAction({
+    const result = await withAssistantPluginResourceLeases(
       controllerHome,
-      repoId: repository.repoId,
-      repoRoot: repository.canonicalRoot,
-      pluginId: request.pluginId,
-      actionId: request.actionId,
-      requestId: request.requestId,
-      args: normalizedArgs,
-      origin: request.origin,
-      jobId: receiptId,
-      timeoutMs: request.timeoutMs,
-      signal: request.signal,
-      deadlineAtMs: typeof request.timeoutMs === 'number'
-        ? Date.now() + Math.max(1, Math.trunc(request.timeoutMs))
-        : undefined,
-    });
+      repository,
+      action,
+      request,
+      () => executeAssistantPluginAction({
+        controllerHome,
+        repoId: repository.repoId,
+        repoRoot: repository.canonicalRoot,
+        pluginId: request.pluginId,
+        actionId: request.actionId,
+        requestId: request.requestId,
+        args: normalizedArgs,
+        origin: request.origin,
+        jobId: receiptId,
+        timeoutMs: request.timeoutMs,
+        signal: request.signal,
+        authorizationGrantRefs: request.authorizationGrantRefs,
+        deadlineAtMs: typeof request.timeoutMs === 'number'
+          ? Date.now() + Math.max(1, Math.trunc(request.timeoutMs))
+          : undefined,
+      }),
+    );
     if (action.confirmation === 'authorization'
       && authorizationContext
       && !activeAuthorizationGrant
@@ -1275,27 +1656,46 @@ export async function submitAssistantPluginAction(
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'PLUGIN_ACTION_FAILED';
+    const code = isAssistantPluginError(error)
+      ? error.code
+      : /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'PLUGIN_ACTION_FAILED';
+    const effectOutcome: AssistantPluginEffectOutcome = isAssistantPluginError(error)
+      ? error.effectOutcome
+      : 'failed';
+    const outcomeUnknown = effectOutcome === 'outcome_unknown';
+    const outcomeResult = outcomeUnknown
+      ? { outcome: 'outcome_unknown', error: { code, message } }
+      : undefined;
     if (boundRemoteWork) {
       appendWorkEvidence({ controllerHome, repoId: workAttributionRepoId(repository, request) }, boundRemoteWork.workId, {
-        title: 'typed remote plugin effect failed',
+        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) {
-      const current = getWorkContract({ controllerHome, repoId: repository.repoId }, acceptedWork.workId);
-      updateWorkContract({ controllerHome, repoId: repository.repoId }, acceptedWork.workId, {
-        status: 'failed',
-        workKind: 'local_effect',
-        dispatchState: 'terminal',
-        evidenceState: 'failed',
-        evidenceRefs: [{
-          title: 'controller-local effect failed',
+      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',
-        }, ...(current?.evidenceRefs ?? [])],
-      });
+        });
+      } 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,
@@ -1307,6 +1707,7 @@ export async function submitAssistantPluginAction(
       actionId: request.actionId,
       semanticKey: key,
       status: 'failed',
+      effectOutcome,
       createdAt,
       ...(acceptedWork
         ? { workId: acceptedWork.workId }
@@ -1317,20 +1718,45 @@ export async function submitAssistantPluginAction(
             : {}),
       origin: request.origin,
       authorization,
+      ...(outcomeResult ? { result: outcomeResult } : {}),
       error: { code, message },
     };
     writeJsonAtomic(pluginActionReceiptPath(controllerHome, repository.repoId, receiptId), receipt);
     writeJsonAtomic(requestPath, {
       requestId: request.requestId,
       repoId: repository.repoId,
+      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
       receiptId,
       semanticKey: key,
       createdAt,
     } satisfies PluginActionRequestIndex);
+    if (outcomeUnknown) {
+      return {
+        manifest,
+        action,
+        job: compatibilityJobFromReceipt(receipt, repository.activeCheckoutId),
+        deduplicated: false,
+        result: outcomeResult,
+        receipt,
+        authorization,
+        workId: acceptedWork?.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 async function executeAssistantPluginAction(
   input: AssistantPluginActionExecutionInput,
 ): Promise<Record<string, unknown>> {
@@ -1344,8 +1770,24 @@ export async function executeAssistantPluginAction(
   const manifestLookup = getAssistantPluginManifestForExecution(input.controllerHome, repository, input.pluginId, adapter);
   const manifest = manifestLookup.manifest;
   const action = actionForManifest(manifest, input.actionId);
-  denyAutomatedWrite(manifest, action, input.origin);
+  if (action.executionMode === 'direct_non_persistent') {
+    throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_APPLICATION_PATH_REQUIRED: ${input.pluginId}/${input.actionId}`);
+  }
   const normalizedArgs = validateActionArguments(action, input.args);
+  if (requiresAutomatedWriteAuthorization(input.origin)) {
+    await resolveAutomatedWriteAuthorization({
+      controllerHome: input.controllerHome,
+      repository,
+      adapter,
+      manifest,
+      action,
+      args: normalizedArgs,
+      origin: input.origin,
+      requestId: input.requestId,
+      jobId: input.jobId,
+      authorizationGrantRefs: input.authorizationGrantRefs,
+    });
+  }
   try {
     const result = await adapter.executeAction({
       ...input,