@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/plugins/google-shared.ts

@@ -1,6 +1,4 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
 import type {
   AssistantPluginHealth,
   AssistantPluginLifecycleState,
@@ -8,7 +6,8 @@ import type {
 } from './types';
 import { AssistantPluginError, toAssistantPluginError } from './errors';
 import { bootstrapManagedRuntimeEnv } from '../shared/managed-env';
-import { readStoredGoogleRefreshToken } from '../safe-tooling/google-credential-store';
+import { readStoredGoogleClientSecret, readStoredGoogleRefreshToken } from '../safe-tooling/google-credential-store';
+import { readRepositoryPluginConfig, writeRepositoryPluginConfig, type RepositoryPluginConfigContext } from './config-store';
 
 export type GoogleProviderKind = 'mock' | 'google-workspace';
 export type GoogleService = 'gmail' | 'calendar' | 'tasks';
@@ -59,7 +58,6 @@ export interface GoogleApiRequestOptions {
   timeoutMs?: number;
 }
 
-const CONFIG_ROOT = '.forge/plugins';
 const REFRESH_REQUIRED_ACCESS_TOKEN = '__forge_refresh_required__';
 
 interface CachedGoogleCredential {
@@ -130,8 +128,15 @@ function refreshCredential(service: GoogleService): { name: string; value: strin
   return stored ? { name: stored.source, value: stored.token } : undefined;
 }
 
+function clientSecretCredential(service: GoogleService): { name: string; value: string } | undefined {
+  const fromEnv = firstEnv(clientSecretEnvNames(service));
+  if (fromEnv) return fromEnv;
+  const stored = readStoredGoogleClientSecret(service);
+  return stored ? { name: stored.source, value: stored.secret } : undefined;
+}
+
 function refreshCredentialsReady(service: GoogleService): boolean {
-  return Boolean(refreshCredential(service) && firstEnv(clientIdEnvNames(service)) && firstEnv(clientSecretEnvNames(service)));
+  return Boolean(refreshCredential(service) && firstEnv(clientIdEnvNames(service)));
 }
 
 export function installGoogleAccessToken(service: GoogleService, accessToken: string, expiresInSeconds = 3600, source = 'oauth'): void {
@@ -144,10 +149,6 @@ export function installGoogleAccessToken(service: GoogleService, accessToken: st
   });
 }
 
-function repoPluginConfigPath(repoRoot: string, pluginId: string): string {
-  return join(repoRoot, CONFIG_ROOT, `${pluginId}.json`);
-}
-
 function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -219,75 +220,66 @@ export function normalizeGoogleTasksPluginConfig(raw: Partial<GoogleTasksPluginC
 
 function loadPluginConfig<T extends GooglePluginConfig>(
   repoRoot: string,
+  context: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'> | undefined,
   pluginId: string,
   normalize: (raw: Partial<T>) => T,
   defaults: () => T,
 ): T {
-  const path = repoPluginConfigPath(repoRoot, pluginId);
-  if (!existsSync(path)) return defaults();
-  try {
-    return normalize(JSON.parse(readFileSync(path, 'utf-8')) as Partial<T>);
-  } catch {
-    return defaults();
-  }
+  if (!context) return defaults();
+  const persisted = readRepositoryPluginConfig<Partial<T>>({ ...context, repoRoot }, pluginId);
+  return persisted ? normalize(persisted) : defaults();
 }
 
 function writePluginConfig<T extends GooglePluginConfig>(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   pluginId: string,
   config: T,
 ): T {
-  const path = repoPluginConfigPath(repoRoot, pluginId);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
-  return config;
+  return writeRepositoryPluginConfig(context, pluginId, config);
 }
 
-export function gmailPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/gmail.json`;
-}
-
-export function googleCalendarPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/google-calendar.json`;
-}
-
-export function googleTasksPluginConfigPath(): string {
-  return `${CONFIG_ROOT}/google-tasks.json`;
-}
-
-export function loadGmailPluginConfig(repoRoot: string): GmailPluginConfig {
-  return loadPluginConfig(repoRoot, 'gmail', normalizeGmailPluginConfig, defaultGmailPluginConfig);
+export function loadGmailPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GmailPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'gmail', normalizeGmailPluginConfig, defaultGmailPluginConfig);
 }
 
-export function loadGoogleCalendarPluginConfig(repoRoot: string): GoogleCalendarPluginConfig {
-  return loadPluginConfig(repoRoot, 'google-calendar', normalizeGoogleCalendarPluginConfig, defaultGoogleCalendarPluginConfig);
+export function loadGoogleCalendarPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GoogleCalendarPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'google-calendar', normalizeGoogleCalendarPluginConfig, defaultGoogleCalendarPluginConfig);
 }
 
-export function loadGoogleTasksPluginConfig(repoRoot: string): GoogleTasksPluginConfig {
-  return loadPluginConfig(repoRoot, 'google-tasks', normalizeGoogleTasksPluginConfig, defaultGoogleTasksPluginConfig);
+export function loadGoogleTasksPluginConfig(
+  repoRoot: string,
+  context?: Pick<RepositoryPluginConfigContext, 'controllerHome' | 'repoId'>,
+): GoogleTasksPluginConfig {
+  return loadPluginConfig(repoRoot, context, 'google-tasks', normalizeGoogleTasksPluginConfig, defaultGoogleTasksPluginConfig);
 }
 
 export type GooglePluginConfigPatch<T extends GooglePluginConfig> = Partial<Omit<T, 'schemaVersion'>>;
 
-export function saveGmailPluginConfig(repoRoot: string, patch: GooglePluginConfigPatch<GmailPluginConfig>): GmailPluginConfig {
-  const current = loadGmailPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'gmail', normalizeGmailPluginConfig({ ...current, ...patch }));
+export function saveGmailPluginConfig(context: RepositoryPluginConfigContext, patch: GooglePluginConfigPatch<GmailPluginConfig>): GmailPluginConfig {
+  const current = loadGmailPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'gmail', normalizeGmailPluginConfig({ ...current, ...patch }));
 }
 
 export function saveGoogleCalendarPluginConfig(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   patch: GooglePluginConfigPatch<GoogleCalendarPluginConfig>,
 ): GoogleCalendarPluginConfig {
-  const current = loadGoogleCalendarPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'google-calendar', normalizeGoogleCalendarPluginConfig({ ...current, ...patch }));
+  const current = loadGoogleCalendarPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'google-calendar', normalizeGoogleCalendarPluginConfig({ ...current, ...patch }));
 }
 
 export function saveGoogleTasksPluginConfig(
-  repoRoot: string,
+  context: RepositoryPluginConfigContext,
   patch: GooglePluginConfigPatch<GoogleTasksPluginConfig>,
 ): GoogleTasksPluginConfig {
-  const current = loadGoogleTasksPluginConfig(repoRoot);
-  return writePluginConfig(repoRoot, 'google-tasks', normalizeGoogleTasksPluginConfig({ ...current, ...patch }));
+  const current = loadGoogleTasksPluginConfig(context.repoRoot, context);
+  return writePluginConfig(context, 'google-tasks', normalizeGoogleTasksPluginConfig({ ...current, ...patch }));
 }
 
 function tokenEnvNames(service: GoogleService): string[] {
@@ -304,9 +296,9 @@ function tokenEnvNames(service: GoogleService): string[] {
 export function resolveGoogleAuth(
   service: GoogleService,
   config: GooglePluginConfig,
-  options: { repoRoot?: string } = {},
+  options: { repoRoot?: string; controllerHome?: string } = {},
 ): GoogleAuthState {
-  bootstrapManagedRuntimeEnv({ repoRoot: options.repoRoot });
+  bootstrapManagedRuntimeEnv({ repoRoot: options.repoRoot, controllerHome: options.controllerHome });
   if (config.provider === 'mock') {
     return {
       provider: 'mock', ready: true, authenticated: true, probed: true,
@@ -443,8 +435,8 @@ function serviceBaseUrl(service: GoogleService): string {
 async function refreshGoogleAccessToken(service: GoogleService, timeoutMs: number): Promise<string | undefined> {
   const refreshToken = refreshCredential(service);
   const clientId = firstEnv(clientIdEnvNames(service));
-  const clientSecret = firstEnv(clientSecretEnvNames(service));
-  if (!refreshToken || !clientId || !clientSecret) return undefined;
+  const clientSecret = clientSecretCredential(service);
+  if (!refreshToken || !clientId) return undefined;
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -452,8 +444,8 @@ async function refreshGoogleAccessToken(service: GoogleService, timeoutMs: numbe
       grant_type: 'refresh_token',
       refresh_token: refreshToken.value,
       client_id: clientId.value,
-      client_secret: clientSecret.value,
     });
+    if (clientSecret) body.set('client_secret', clientSecret.value);
     const response = await fetch('https://oauth2.googleapis.com/token', {
       method: 'POST',
       headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },

package/src/runtime/plugins/google-tasks-adapter.ts

@@ -1,6 +1,7 @@
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
@@ -10,7 +11,6 @@ import {
   type GoogleTasksPluginConfig,
   googleApiRequest,
   googlePermission,
-  googleTasksPluginConfigPath,
   loadGoogleTasksPluginConfig,
   pluginStateFromGoogleAuth,
   resolveGoogleAuth,
@@ -454,10 +454,10 @@ function tasksProvider(config: GoogleTasksPluginConfig, repoRoot?: string): Task
   return config.provider === 'mock' ? mockTasksProvider() : liveTasksProvider(config, repoRoot);
 }
 
-export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadGoogleTasksPluginConfig(root);
-  const auth = resolveGoogleAuth('tasks', config, { repoRoot: root });
+  const config = loadGoogleTasksPluginConfig(root, context);
+  const auth = resolveGoogleAuth('tasks', config, { repoRoot: root, controllerHome: context?.controllerHome });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
     schemaVersion: 1,
@@ -470,7 +470,7 @@ export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpd
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: [`repo-local:${googleTasksPluginConfigPath()}`, 'env:FORGE_*_ACCESS_TOKEN'],
+      sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/google-tasks.json', 'env:FORGE_*_ACCESS_TOKEN'],
     },
     enabled: config.enabled,
     lifecycle: {
@@ -490,11 +490,11 @@ export function buildGoogleTasksPluginManifest(previousRevision = 0, previousUpd
 }
 
 export async function executeGoogleTasksPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadGoogleTasksPluginConfig(input.repoRoot);
+  const current = loadGoogleTasksPluginConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveGoogleTasksPluginConfig(input.repoRoot, {
+      const config = saveGoogleTasksPluginConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'google-workspace' ? 'google-workspace' : args.provider === 'mock' ? 'mock' : current.provider,
         accountEmail: args.clear_account_email === true ? undefined : stringValue(args.account_email) ?? current.accountEmail,
@@ -504,7 +504,7 @@ export async function executeGoogleTasksPluginAction(input: AssistantPluginActio
       });
       return {
         config,
-        auth: resolveGoogleAuth('tasks', config, { repoRoot: input.repoRoot }),
+        auth: resolveGoogleAuth('tasks', config, { repoRoot: input.repoRoot, controllerHome: input.controllerHome }),
       };
     }
     case 'list_tasklists':

package/src/runtime/plugins/ios-adapter.ts

@@ -43,7 +43,6 @@ import {
 } from './ios-physical-device';
 
 const IOS_PLUGIN_ID = 'ios';
-const CONFIG_ROOT = '.forge/plugins';
 
 function now(): string {
   return new Date().toISOString();
@@ -346,7 +345,7 @@ function actions(): AssistantPluginActionDescriptor[] {
       description: 'Capture a simulator screenshot into controller artifact storage.',
       readOnly: false,
       risk: 'workspace_write',
-      confirmation: 'none',
+      confirmation: 'authorization',
       defaultTimeoutMs: 60_000,
       cancellable: true,
       idempotent: false,
@@ -414,7 +413,7 @@ export function buildIosPluginManifest(previousRevision = 0, previousUpdatedAt?:
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: ['local:xcodebuild', 'local:simctl', 'local:devicectl', 'local:agent-device-capability-contract', 'process-env:DEVELOPER_DIR', 'process-env:AGENT_DEVICE_IOS_TEAM_ID', 'process-env:AGENT_DEVICE_IOS_BUNDLE_ID', `repo-local:${CONFIG_ROOT}/ios.json`],
+      sourceOfTruth: ['local:xcodebuild', 'local:simctl', 'local:devicectl', 'local:agent-device-capability-contract', 'process-env:DEVELOPER_DIR', 'process-env:AGENT_DEVICE_IOS_TEAM_ID', 'process-env:AGENT_DEVICE_IOS_BUNDLE_ID'],
     },
     enabled,
     lifecycle: {

package/src/runtime/plugins/lightweight-action.ts

@@ -2,16 +2,22 @@ import { createHash } from 'crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import type { RepositoryRecord } from '../../cli/repositories/types';
-import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import { resolveTrustedNodeExecutable } from '../shared/trusted-node-executable';
 import { startLightweightInternalProcess, waitForLightweightProcess } from '../execution/process-runtime/lightweight-managed';
+import { getProcessHandle, spawnManagedProcess, waitForProcess } from '../execution/process-runtime/runtime';
+import { getProcessRecord, getProcessRequestBinding } from '../execution/process-runtime/store';
 import type { ProcessHandle } from '../execution/process-runtime/types';
+import { FORGE_INSTANCE_PROCESS_SCOPE_KEY } from '../execution/process-runtime/process-scope';
+import type { ResolvedExecutionIdentity } from '../control-plane/execution/execution-identity';
 import type { AssistantPluginActionRequest } from './types';
 
 interface LightweightPluginActionEnvelope {
   schemaVersion: 1;
   controllerHome: string;
-  repoId: string;
+  /** Legacy repository envelope coordinate; absent for ForgeInstance-scoped controller plugins. */
+  repoId?: string;
+  scope?: { kind: 'controller' } | { kind: 'repository'; repoId: string };
   request: Omit<AssistantPluginActionRequest, 'signal'>;
 }
 
@@ -28,6 +34,18 @@ function envelopeBytes(controllerHome: string, repository: RepositoryRecord, req
     schemaVersion: 1,
     controllerHome,
     repoId: repository.repoId,
+    scope: { kind: 'repository', repoId: repository.repoId },
+    request: serializableRequest,
+  };
+  return `${JSON.stringify(envelope)}\n`;
+}
+
+function controllerEnvelopeBytes(controllerHome: string, request: AssistantPluginActionRequest): string {
+  const { signal: _signal, ...serializableRequest } = request;
+  const envelope: LightweightPluginActionEnvelope = {
+    schemaVersion: 1,
+    controllerHome,
+    scope: { kind: 'controller' },
     request: serializableRequest,
   };
   return `${JSON.stringify(envelope)}\n`;
@@ -142,6 +160,194 @@ export async function startLightweightPluginAction(input: {
   return { handle, requestSha256 };
 }
 
+export async function startManagedControllerPluginAction(input: {
+  controllerHome: string;
+  request: AssistantPluginActionRequest;
+  interactiveWaitMs?: number;
+  timeoutMs: number;
+}): Promise<LightweightPluginActionStart> {
+  const scopeKey = FORGE_INSTANCE_PROCESS_SCOPE_KEY;
+  const requestToken = createHash('sha256')
+    .update(`${scopeKey}\u0000${input.request.requestId}`)
+    .digest('hex')
+    .slice(0, 24);
+  const instanceRoot = controllerSystemRoot(input.controllerHome);
+  const requestRoot = join(instanceRoot, 'plugin-action-processes');
+  const requestPath = join(requestRoot, `${requestToken}.request.json`);
+  const bytes = controllerEnvelopeBytes(input.controllerHome, input.request);
+  const requestSha256 = createHash('sha256').update(bytes).digest('hex');
+  const existingBinding = getProcessRequestBinding(input.controllerHome, scopeKey, undefined, input.request.requestId);
+  if (existingBinding) {
+    if (existsSync(requestPath)) {
+      const existingBytes = readFileSync(requestPath, 'utf8');
+      if (createHash('sha256').update(existingBytes).digest('hex') !== requestSha256) {
+        throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+      }
+    }
+    const existing = getProcessHandle(input.controllerHome, scopeKey, existingBinding.processId);
+    if (!existing) throw new Error(`PROCESS_REQUEST_INCOMPLETE: plugin request ${input.request.requestId} is bound to missing process ${existingBinding.processId}; refusing re-execution`);
+    const processRecord = getProcessRecord(input.controllerHome, scopeKey, existingBinding.processId);
+    if (processRecord?.origin?.requestSemanticFingerprint && processRecord.origin.requestSemanticFingerprint !== requestSha256) {
+      throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+    }
+    return { handle: { ...existing, deduplicated: true, requestId: input.request.requestId }, requestSha256 };
+  }
+  if (existsSync(requestPath)) {
+    const existingBytes = readFileSync(requestPath, 'utf8');
+    if (createHash('sha256').update(existingBytes).digest('hex') !== requestSha256) {
+      throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+    }
+  } else {
+    privateAtomicWrite(requestPath, bytes);
+  }
+  const invocation = resolveLightweightPluginActionRuntimeInvocation();
+  const executionIdentity: ResolvedExecutionIdentity = Object.freeze({
+    schemaVersion: 1 as const,
+    authority: 'forge_instance' as const,
+    repositoryId: scopeKey,
+    checkoutId: scopeKey,
+    canonicalRoot: instanceRoot,
+  });
+  const handle = await spawnManagedProcess({
+    controllerHome: input.controllerHome,
+    repoId: scopeKey,
+    principalId: input.request.origin.actor?.trim() || undefined,
+    executionIdentity,
+    commandId: `plugin-action:${input.request.requestId}`,
+    trustedRuntimeChild: 'plugin_action_sidecar',
+    command: {
+      kind: 'argv',
+      executable: invocation.executable,
+      args: [...invocation.argsPrefix, '--request', requestPath, '--expected-sha256', requestSha256],
+      cwd: instanceRoot,
+    },
+    interactiveWaitMs: Math.max(0, input.interactiveWaitMs ?? 750),
+    timeoutMs: input.timeoutMs,
+    maxOutputBytes: 64 * 1024,
+    origin: {
+      surface: 'mcp',
+      toolName: 'plugin_action_execute',
+      requestId: input.request.requestId,
+      requestSemanticFingerprint: requestSha256,
+      correlationId: input.request.workId,
+    },
+    signal: input.request.signal,
+  });
+  return { handle, requestSha256 };
+}
+
+export async function startManagedPluginAction(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  request: AssistantPluginActionRequest;
+  interactiveWaitMs?: number;
+  timeoutMs: number;
+}): Promise<LightweightPluginActionStart> {
+  const requestToken = createHash('sha256')
+    .update(`${input.repository.repoId}\u0000${input.request.requestId}`)
+    .digest('hex')
+    .slice(0, 24);
+  const requestRoot = join(repositoryControllerRoot(input.controllerHome, input.repository.repoId), 'plugin-action-processes');
+  const requestPath = join(requestRoot, `${requestToken}.request.json`);
+  const bytes = envelopeBytes(input.controllerHome, input.repository, input.request);
+  const requestSha256 = createHash('sha256').update(bytes).digest('hex');
+
+  const existingBinding = getProcessRequestBinding(
+    input.controllerHome,
+    input.repository.repoId,
+    input.repository.activeCheckoutId,
+    input.request.requestId,
+  );
+  if (existingBinding) {
+    if (existsSync(requestPath)) {
+      const existingBytes = readFileSync(requestPath, 'utf8');
+      const existingSha256 = createHash('sha256').update(existingBytes).digest('hex');
+      if (existingSha256 !== requestSha256) {
+        throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+      }
+    }
+    const existing = getProcessHandle(input.controllerHome, input.repository.repoId, existingBinding.processId);
+    if (!existing) {
+      throw new Error(`PROCESS_REQUEST_INCOMPLETE: plugin request ${input.request.requestId} is bound to missing process ${existingBinding.processId}; refusing re-execution`);
+    }
+    const processRecord = getProcessRecord(input.controllerHome, input.repository.repoId, existingBinding.processId);
+    if (processRecord?.origin?.requestSemanticFingerprint && processRecord.origin.requestSemanticFingerprint !== requestSha256) {
+      throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+    }
+    return { handle: { ...existing, deduplicated: true, requestId: input.request.requestId }, requestSha256 };
+  }
+
+  if (existsSync(requestPath)) {
+    const existingBytes = readFileSync(requestPath, 'utf8');
+    const existingSha256 = createHash('sha256').update(existingBytes).digest('hex');
+    if (existingSha256 !== requestSha256) {
+      throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+    }
+  } else {
+    privateAtomicWrite(requestPath, bytes);
+  }
+
+  const invocation = resolveLightweightPluginActionRuntimeInvocation();
+  const executionIdentity: ResolvedExecutionIdentity = Object.freeze({
+    schemaVersion: 1 as const,
+    authority: 'ephemeral_workspace' as const,
+    repositoryId: input.repository.repoId,
+    checkoutId: input.repository.activeCheckoutId,
+    canonicalRoot: input.repository.canonicalRoot,
+    ...(input.request.workId ? { workId: input.request.workId } : {}),
+  });
+  const handle = await spawnManagedProcess({
+    controllerHome: input.controllerHome,
+    repoId: input.repository.repoId,
+    checkoutId: input.repository.activeCheckoutId,
+    executionIdentity,
+    workId: input.request.workId,
+    commandId: `plugin-action:${input.request.requestId}`,
+    trustedRuntimeChild: 'plugin_action_sidecar',
+    command: {
+      kind: 'argv',
+      executable: invocation.executable,
+      args: [
+        ...invocation.argsPrefix,
+        '--request', requestPath,
+        '--expected-sha256', requestSha256,
+      ],
+      cwd: input.repository.canonicalRoot,
+    },
+    interactiveWaitMs: Math.max(0, input.interactiveWaitMs ?? 750),
+    timeoutMs: input.timeoutMs,
+    maxOutputBytes: 64 * 1024,
+    origin: {
+      surface: 'mcp',
+      toolName: 'plugin_action_execute',
+      requestId: input.request.requestId,
+      requestSemanticFingerprint: requestSha256,
+      correlationId: input.request.workId,
+    },
+    signal: input.request.signal,
+  });
+  return { handle, requestSha256 };
+}
+
+export async function waitManagedControllerPluginAction(
+  controllerHome: string,
+  processId: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<ProcessHandle> {
+  return waitForProcess(controllerHome, FORGE_INSTANCE_PROCESS_SCOPE_KEY, processId, { timeoutMs, signal });
+}
+
+export async function waitManagedPluginAction(
+  controllerHome: string,
+  repoId: string,
+  processId: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<ProcessHandle> {
+  return waitForProcess(controllerHome, repoId, processId, { timeoutMs, signal });
+}
+
 export async function waitLightweightPluginAction(
   controllerHome: string,
   repoId: string,