@moretea-labs/forge 1.7.1 → 1.8.0

package/src/cli/commands/init-hook.ts

@@ -16,16 +16,16 @@ import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { runDoctor, type CheckStatus, type DoctorReport } from './doctor';
 import { runStatus, type StatusReport } from './status';
-import { runMcpSetupChatgpt } from '../mcp/setup';
+import { runMcpSetupChatgpt } from '../../../adapters/mcp/setup';
 import { resolveControllerHome } from '../repositories/controller-home';
+import { createSetupBootstrapControlApi } from './bootstrap-control';
+import type { BootstrapSnapshot } from '../../runtime/control-plane/bootstrap';
 import {
   configureSetupProfile,
   detectSetupPlatform,
   formatSetupProfile,
   readSetupProfile,
-  resolveControllerGuidance,
-  resolveRuntimeGuidance,
-  resolveTunnelGuidance,
+  setupConnectorAuthMode,
   setupHostTarget,
   type SetupHostTarget,
   type SetupPlatformSnapshot,
@@ -686,6 +686,8 @@ export interface SetupSession {
   closedAt?: string;
   lastReport: InitHookReport;
   nextAction?: InitHookAction;
+  /** Compatibility projection now backed by the instance-level V2 bootstrap authority. */
+  bootstrap?: BootstrapSnapshot;
 }
 
 export interface SetupSessionOptions extends InitHookOptions {
@@ -733,55 +735,29 @@ function setupStatus(report: InitHookReport, nextAction?: InitHookAction): Setup
   return 'open';
 }
 
-function profileNextAction(profile: SetupProfile | undefined, platform: SetupPlatformSnapshot, options: { controllerHome?: string; accountHome?: string } = {}): InitHookAction | undefined {
-  if (!profile) {
-    return {
-      id: 'controller.select',
-      status: 'needs_agent',
-      reason: 'Choose the external controller that will act as Forge’s brain. ChatGPT is recommended; Codex, Claude, or another MCP client can be primary instead.',
-      requires_agent: true,
-      risk: 'Writes only the local Forge setup profile. It does not install or authenticate third-party software.',
-      command: 'forge setup configure --controller chatgpt',
-      verification: 'forge setup next',
-    };
-  }
-  const controller = resolveControllerGuidance(profile, { controllerHome: options.controllerHome, home: options.accountHome });
-  if (controller && !controller.ready) {
-    return {
-      id: `controller.${controller.controller}.configure`,
-      status: 'needs_agent',
-      reason: `${controller.title}: ${controller.detail}`,
-      requires_agent: true,
-      risk: 'Configures only the explicitly selected external controller entry. Unselected Codex/Claude providers remain untouched.',
-      ...(controller.command ? { command: controller.command } : {}),
-      verification: 'forge setup next',
-    };
-  }
-  const runtime = resolveRuntimeGuidance(profile, { controllerHome: options.controllerHome });
-  if (runtime && !runtime.ready) {
-    return {
-      id: 'runtime.package.install',
-      status: 'needs_agent',
-      reason: `${runtime.title}: ${runtime.detail}`,
-      requires_agent: true,
-      risk: 'Installs or diagnoses the user-level Forge Runtime only. Standalone Recovery and source-release activation are not part of normal setup.',
-      ...(runtime.command ? { command: runtime.command } : {}),
-      verification: 'forge setup next',
-    };
-  }
-  const tunnel = resolveTunnelGuidance(profile, platform, { controllerHome: options.controllerHome });
-  if (!tunnel.ready) {
-    return {
-      id: `tunnel.${tunnel.provider}.configure`,
-      status: 'needs_agent',
-      reason: `${tunnel.title}: ${tunnel.detail}`,
-      requires_agent: true,
-      risk: 'Remote connectivity is provider-owned. Forge keeps its MCP listener on loopback; credentials, authentication, and account changes remain explicit.',
-      ...(tunnel.command ? { command: tunnel.command } : {}),
-      verification: 'forge setup next',
-    };
-  }
-  return undefined;
+function bootstrapNextAction(snapshot: BootstrapSnapshot): InitHookAction | undefined {
+  const stateById = new Map(snapshot.steps.map((entry) => [entry.id, entry.state]));
+  const dependenciesReady = (entry: BootstrapSnapshot['steps'][number]): boolean => entry.dependsOn.every((dependency) => {
+    const state = stateById.get(dependency);
+    return state === 'ready' || state === 'skipped';
+  });
+  const step = snapshot.steps.find((entry) => entry.state === 'blocked' && entry.actionIds.length > 0 && dependenciesReady(entry))
+    ?? snapshot.steps.find((entry) => entry.state === 'pending' && entry.actionIds.length > 0 && dependenciesReady(entry));
+  const actionId = step?.actionIds[0];
+  if (!actionId) return undefined;
+  const action = snapshot.actions.find((entry) => entry.id === actionId);
+  if (!action) return undefined;
+  return {
+    id: action.id,
+    status: 'needs_agent',
+    reason: action.owner === 'user' ? `User action required: ${action.summary}` : action.summary,
+    requires_agent: true,
+    risk: action.risk ?? (action.owner === 'user'
+      ? 'This action crosses a user/account boundary and cannot be completed silently by Forge.'
+      : 'This action is scoped to the local Forge bootstrap lifecycle.'),
+    ...(action.command ? { command: action.command } : {}),
+    verification: action.verification ?? 'forge setup next',
+  };
 }
 
 export function openSetupSession(options: SetupSessionOptions = {}): SetupSession {
@@ -792,7 +768,10 @@ export function openSetupSession(options: SetupSessionOptions = {}): SetupSessio
   const target = options.target ?? setupHostTarget(profile);
   const report = options.report ?? runInitHook({ ...options, target });
   const controllerHome = resolveControllerHome(options.controllerHome);
-  const nextAction = profileNextAction(profile, platform, { controllerHome, accountHome: options.accountHome }) ?? report.agent_actions[0];
+  const bootstrap = createSetupBootstrapControlApi({
+    setupRoot: options.setupRoot, env: options.env, now: options.now, controllerHome, accountHome: options.accountHome, profile, platform,
+  }).refreshSync();
+  const nextAction = bootstrapNextAction(bootstrap) ?? report.agent_actions[0];
   const now = (options.now ?? (() => new Date()))().toISOString();
   const reuse = previous && previous.status !== 'closed';
   return writeSetupSessionAt(path, {
@@ -806,6 +785,7 @@ export function openSetupSession(options: SetupSessionOptions = {}): SetupSessio
     createdAt: reuse ? previous.createdAt : now,
     updatedAt: now,
     lastReport: report,
+    bootstrap,
     ...(nextAction ? { nextAction } : {}),
   });
 }
@@ -855,6 +835,7 @@ interface SetupCycleRawOptions {
   target?: string;
   controller?: string;
   addController?: string[];
+  capability?: string[];
   tunnel?: string;
   endpoint?: string;
   tunnelId?: string;
@@ -866,24 +847,30 @@ function collectOption(value: string, previous: string[] = []): string[] {
   return [...previous, value];
 }
 
-function syncExplicitRemoteControllerEndpoint(profile: SetupProfile | undefined, endpoint: string | undefined): void {
-  if (!profile || !endpoint || !profile.controllers.some((controller) => controller === 'chatgpt' || controller === 'mcp')) return;
-  runMcpSetupChatgpt({ userLevel: true, endpoint });
+function syncRemoteControllerTransport(profile: SetupProfile | undefined): void {
+  if (!profile || !profile.controllers.some((controller) => controller === 'chatgpt' || controller === 'mcp')) return;
+  runMcpSetupChatgpt({
+    userLevel: true,
+    ...(profile.tunnel.endpoint ? { endpoint: profile.tunnel.endpoint } : {}),
+    clearEndpoint: !profile.tunnel.endpoint,
+    connectorAuthMode: setupConnectorAuthMode(profile),
+  });
 }
 
 function setupCycle(rawOpts: SetupCycleRawOptions, surface: string): void {
   try {
     let profile = readSetupProfile();
-    if (rawOpts.controller || rawOpts.addController?.length || rawOpts.tunnel || rawOpts.endpoint || rawOpts.tunnelId) {
+    if (rawOpts.controller || rawOpts.addController?.length || rawOpts.capability?.length || rawOpts.tunnel || rawOpts.endpoint || rawOpts.tunnelId) {
       profile = configureSetupProfile({
         controller: rawOpts.controller,
         addControllers: rawOpts.addController,
+        capabilities: rawOpts.capability,
         tunnel: rawOpts.tunnel,
         endpoint: rawOpts.endpoint,
         tunnelId: rawOpts.tunnelId,
       });
-      syncExplicitRemoteControllerEndpoint(profile, rawOpts.endpoint);
     }
+    syncRemoteControllerTransport(profile);
     const session = openSetupSession({
       profile,
       target: setupTarget(rawOpts.target, surface) ?? setupHostTarget(profile),
@@ -901,6 +888,7 @@ function addSetupSelectionOptions(command: Command): Command {
   return command
     .option('--controller <controller>', 'Primary external controller: chatgpt|codex|claude|mcp')
     .option('--add-controller <controller>', 'Also configure another external controller entry (repeatable)', collectOption, [])
+    .option('--capability <capability-id>', 'Require a provider-neutral semantic capability (repeatable)', collectOption, [])
     .option('--tunnel <provider>', 'Remote connection: auto|openai|cloudflare|tailscale|existing|none')
     .option('--tunnel-id <id>', 'OpenAI Secure MCP Tunnel id (non-secret tunnel_...)')
     .option('--endpoint <url>', 'Existing/stable public HTTPS URL ending in /mcp')
@@ -929,20 +917,22 @@ export function buildSetupCommand(): Command {
     .description('Choose the primary external controller, optional additional controllers, and public access provider')
     .requiredOption('--controller <controller>', 'Primary external controller: chatgpt|codex|claude|mcp')
     .option('--add-controller <controller>', 'Also configure another external controller entry (repeatable)', collectOption, [])
+    .option('--capability <capability-id>', 'Require a provider-neutral semantic capability (repeatable)', collectOption, [])
     .option('--tunnel <provider>', 'Remote connection: auto|openai|cloudflare|tailscale|existing|none')
     .option('--tunnel-id <id>', 'OpenAI Secure MCP Tunnel id (non-secret tunnel_...)')
     .option('--endpoint <url>', 'Existing/stable public HTTPS URL ending in /mcp')
     .option('--json', 'Output JSON instead of human-readable text')
-    .action((rawOpts: { controller: string; addController?: string[]; tunnel?: string; tunnelId?: string; endpoint?: string; json?: boolean }) => {
+    .action((rawOpts: { controller: string; addController?: string[]; capability?: string[]; tunnel?: string; tunnelId?: string; endpoint?: string; json?: boolean }) => {
       try {
         const profile = configureSetupProfile({
           controller: rawOpts.controller,
           addControllers: rawOpts.addController,
+          capabilities: rawOpts.capability,
           tunnel: rawOpts.tunnel,
           endpoint: rawOpts.endpoint,
           tunnelId: rawOpts.tunnelId,
         });
-        syncExplicitRemoteControllerEndpoint(profile, rawOpts.endpoint);
+        syncRemoteControllerTransport(profile);
         console.log(rawOpts.json ? JSON.stringify(profile, null, 2) : `${formatSetupProfile(profile)}\n\nNext: forge setup next`);
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -950,6 +940,26 @@ export function buildSetupCommand(): Command {
       }
     });
 
+  command
+    .command('bridge-browser')
+    .description('Provision or repair the dedicated WSL Windows Chromium profile used by the ChatGPT bridge')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action(async (rawOpts: { json?: boolean }) => {
+      try {
+        const profile = readSetupProfile();
+        const api = createSetupBootstrapControlApi({ profile });
+        const snapshot = await api.act('chatgpt.bridge.bootstrap');
+        if (rawOpts.json) console.log(JSON.stringify(snapshot, null, 2));
+        else console.log(snapshot.status === 'ready'
+          ? 'Forge WSL ChatGPT bridge browser is ready.'
+          : `${snapshot.blockers.find((entry) => entry.stepId === 'chatgpt-wsl-bridge')?.summary ?? 'Dedicated bridge browser was provisioned. Complete any visible ChatGPT login step, then run forge setup next.'}\nNext: forge setup next`);
+        process.exitCode = snapshot.status === 'ready' ? 0 : 1;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 2;
+      }
+    });
+
   command
     .command('status')
     .description('Read the persisted setup session and external-controller profile')

package/src/cli/commands/init.ts

@@ -382,9 +382,11 @@ export function runInit(opts: InitCommandOptions = {}): InitCommandResult {
   const syncSkill = opts.syncSkill !== false;
   const hostAdapters = opts.hostAdapters !== false;
   const externalSkills = opts.externalSkills === true;
-  const codegraph = opts.codegraph !== false;
   const configureCgMcp = opts.configureCodegraphMcp === true;
   const syncCodegraph = opts.syncCodegraph === true;
+  // CodeGraph is an optional rebuildable tool cache. Ordinary adoption leaves it
+  // disabled; any explicit CodeGraph operation opts in and uses the Controller Home-backed compatibility link.
+  const codegraph = opts.codegraph === true || configureCgMcp || syncCodegraph;
   const brainMode = opts.brainMode ?? "skip";
   const target = opts.target ?? "both";
   const steps: InitStep[] = [];

package/src/cli/commands/mcp.ts

@@ -1,10 +1,10 @@
 import { Command } from 'commander';
 import { isAbsolute, relative } from 'path';
-import { createMcpToolContext } from '../mcp/server';
-import { startMcpHttp } from '../mcp/transports/http';
-import { startMcpStdio } from '../mcp/transports/stdio';
-import { callMcpTool } from '../mcp/tools';
-import { callAccessTool } from '../mcp/access-tools';
+import { createMcpToolContext } from '../../../adapters/mcp/server';
+import { startMcpHttp } from '../../../adapters/mcp/transports/http';
+import { startMcpStdio } from '../../../adapters/mcp/transports/stdio';
+import { callMcpTool } from '../../../adapters/mcp/tool-mapping/tools';
+import { callAccessTool } from '../../../adapters/mcp/tool-mapping/access-tools';
 import { assertControllerLifecycleOwner } from '../controller/lifecycle-authority';
 import { bindInheritedRuntimeWriteClaimFromEnvironment } from '../../runtime/root/write-fence';
 import {
@@ -13,7 +13,7 @@ import {
   runMcpSetupChatgpt,
   runMcpSetupCodex,
   runMcpSetupClaude,
-} from '../mcp/setup';
+} from '../../../adapters/mcp/setup';
 
 export interface McpServeOptions {
   repo?: string;
@@ -49,8 +49,11 @@ interface McpSetupChatgptOptions {
   port?: string;
   endpoint?: string;
   serverName?: string;
+  instanceId?: string;
   localControllerPort?: string;
   connectorPort?: string;
+  connectorAuthMode?: string;
+  clearEndpoint?: boolean;
 }
 
 interface McpSetupLocalControllerOptions {
@@ -162,7 +165,7 @@ export function buildMcpCommand(): Command {
     .command('serve')
     .description('Start the forge MCP server')
     .option('--repo <path>', 'Repository root to expose through the selected MCP profile')
-    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--controller-home <path>', 'Controller state root; defaults to FORGE_CONTROLLER_HOME/XDG state or ~/.forge/controller')
     .option('--transport <transport>', 'Transport: stdio|http', 'stdio')
     .option('--host <host>', 'HTTP bind host', '127.0.0.1')
     .option('--port <port>', 'HTTP bind port', '8765')
@@ -242,9 +245,12 @@ export function buildMcpCommand(): Command {
     .option('--host <host>', 'Local MCP HTTP bind host', '127.0.0.1')
     .option('--port <port>', 'Local MCP HTTP bind port', '8765')
     .option('--local-controller-port <port>', 'Local-only Utility Console port; defaults to MCP port + 1')
-    .option('--connector-port <port>', 'Loopback OAuth connector port for ChatGPT tunnels; defaults to MCP port + 2')
+    .option('--connector-port <port>', 'Loopback ChatGPT connector port; defaults to MCP port + 2')
+    .option('--connector-auth <mode>', 'Connector authorization boundary: oauth|none; none is only for an externally authorized private transport such as OpenAI Secure MCP Tunnel')
     .option('--endpoint <url>', 'Stable public HTTPS /mcp endpoint to store in ignored local config')
+    .option('--clear-endpoint', 'Remove a previously stored public HTTPS endpoint when switching to a private transport')
     .option('--server-name <name>', 'ChatGPT Connector/MCP server name to record in ignored local config')
+    .option('--instance-id <id>', 'Stable installation identity exposed by the ChatGPT Connector (for example forge-wsl)')
     .action((rawOpts: McpSetupChatgptOptions) => {
       void runMcpAction(() => {
         const result = runMcpSetupChatgpt(rawOpts);
@@ -289,7 +295,7 @@ export function buildMcpCommand(): Command {
     .command('get')
     .description('Read the access mode for one registered repository')
     .option('--repo <path>', 'Repository root used to resolve controllerHome', '.')
-    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--controller-home <path>', 'Controller state root; defaults to FORGE_CONTROLLER_HOME/XDG state or ~/.forge/controller')
     .option('--repo-id <id>', 'Stable registered repository id')
     .action((rawOpts: McpAccessOptions) => {
       void runMcpAction(() => runRepositoryAccessCommand('repository_access_get', rawOpts));
@@ -299,7 +305,7 @@ export function buildMcpCommand(): Command {
     .command('set')
     .description('Set Request or Full Access for one repository or every enabled repository')
     .option('--repo <path>', 'Repository root used to resolve controllerHome', '.')
-    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--controller-home <path>', 'Controller state root; defaults to FORGE_CONTROLLER_HOME/XDG state or ~/.forge/controller')
     .option('--repo-id <id>', 'Stable registered repository id; cannot be combined with --all-repositories')
     .option('--all-repositories', 'Apply to every enabled registered repository')
     .requiredOption('--mode <mode>', 'Access mode: request|full_access')

package/src/cli/commands/plugin.ts

@@ -5,31 +5,37 @@ import { dirname, isAbsolute, join, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
+import { withControllerLock, type ControllerLockKey } from '../repositories/locks';
 import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
 import { createDesktopOperatorRegistrationInput } from '../../runtime/plugins/desktop-operator-registration';
-import { controllerPluginRepository, getAssistantPluginManifest, syncAssistantPluginRegistry } from '../../runtime/plugins/store';
+import { getControllerPluginManifest, syncControllerPluginRegistry } from '../../runtime/plugins/store';
+import { assertExternalPluginRepositoryTrusted, assertFirstPartyPluginRepositoryTrusted, readControllerPluginTrustPolicy, trustExternalPluginRepository, untrustExternalPluginRepository } from '../../runtime/plugins/catalog-trust';
 
-export interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; providerVersion?:string; protocolVersion?:string; platforms:NodeJS.Platform[]; }
+export interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; providerVersion?:string; protocolVersion?:string; platforms:NodeJS.Platform[]; semanticCapabilities?:string[]; }
 interface Registry { schemaVersion:1; plugins:RegistryEntry[]; }
-interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; }
+interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; catalog?:string; }
 const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'../../..');
 const registryPath=join(packageRoot,'assets','plugin-registry.v1.json');
+const trustPolicyPath=join(packageRoot,'assets','plugin-trust-policy.v1.json');
 
-function registry():Registry{
-  const value=JSON.parse(readFileSync(registryPath,'utf8')) as Registry;
+function registryFromPath(path:string,trustRepository:(repository:string)=>string):Registry{
+  const value=JSON.parse(readFileSync(path,'utf8')) as Registry;
   if(value.schemaVersion!==1||!Array.isArray(value.plugins))throw new Error('PLUGIN_CATALOG_INVALID');
   const ids=new Set<string>();
   for(const plugin of value.plugins){
     if(!/^[a-z][a-z0-9_]{1,63}$/.test(plugin.id)||ids.has(plugin.id))throw new Error(`PLUGIN_CATALOG_INVALID_ID: ${plugin.id}`);
-    if(!plugin.repository.startsWith('https://github.com/moretea-labs/')||!plugin.repository.endsWith('.git'))throw new Error(`PLUGIN_CATALOG_UNTRUSTED_REPOSITORY: ${plugin.id}`);
+    plugin.repository=trustRepository(plugin.repository);
     if(!/^v\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.ref))throw new Error(`PLUGIN_CATALOG_UNPINNED_REF: ${plugin.id}`);
     if(plugin.installer!=='forge-plugin-install.mjs')throw new Error(`PLUGIN_CATALOG_INSTALLER_INVALID: ${plugin.id}`);
     if(plugin.providerVersion!==undefined&&!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.providerVersion))throw new Error(`PLUGIN_CATALOG_PROVIDER_VERSION_INVALID: ${plugin.id}`);
     if(plugin.protocolVersion!==undefined&&!/^\d+\.\d+$/.test(plugin.protocolVersion))throw new Error(`PLUGIN_CATALOG_PROTOCOL_VERSION_INVALID: ${plugin.id}`);
+    if(plugin.semanticCapabilities!==undefined&&(!Array.isArray(plugin.semanticCapabilities)||plugin.semanticCapabilities.some(capability=>!/^[-a-z0-9_.]{3,128}$/.test(capability))))throw new Error(`PLUGIN_CATALOG_SEMANTIC_CAPABILITY_INVALID: ${plugin.id}`);
     ids.add(plugin.id);
   }
   return value;
 }
+function registry():Registry{return registryFromPath(registryPath,repository=>assertFirstPartyPluginRepositoryTrusted(repository,trustPolicyPath));}
+function trustedExternalRegistry(path:string,controllerHome:string):Registry{return registryFromPath(resolve(path),repository=>assertExternalPluginRepositoryTrusted(controllerHome,repository));}
 function within(root:string,relative:string):string{const target=resolve(root,relative);const base=`${resolve(root)}${sep}`;if(target!==resolve(root)&&!target.startsWith(base))throw new Error('PLUGIN_INSTALL_PATH_ESCAPE');return target;}
 export function pluginCatalogCompatibility(entry:RegistryEntry,platform:NodeJS.Platform=process.platform):{compatible:boolean;reason?:string}{
   if(!entry.platforms.includes(platform))return{compatible:false,reason:`unsupported platform: ${platform}`};
@@ -37,15 +43,20 @@ export function pluginCatalogCompatibility(entry:RegistryEntry,platform:NodeJS.P
   return{compatible:true};
 }
 export function officialPluginCatalogItems(platform:NodeJS.Platform=process.platform){return registry().plugins.map(entry=>({...entry,...pluginCatalogCompatibility(entry,platform)}));}
+export function officialPluginCatalogEntry(pluginId:string):RegistryEntry|undefined{return registry().plugins.find(entry=>entry.id===pluginId);}
+export function trustedExternalPluginCatalogEntry(pluginId:string,catalogPath:string,controllerHome:string):RegistryEntry|undefined{return trustedExternalRegistry(catalogPath,controllerHome).plugins.find(entry=>entry.id===pluginId);}
+export function officialPluginLifecycleLockKey(pluginId:string):ControllerLockKey{return{scope:'global',resource:`external-plugin:${pluginId}`};}
+export function withOfficialPluginLifecycleLock<T>(controllerHome:string,pluginId:string,operation:()=>T):T{
+  return withControllerLock(controllerHome,officialPluginLifecycleLockKey(pluginId),`official-plugin-lifecycle:${pluginId}:${process.pid}`,operation);
+}
 export function externalPluginListItem(controllerHome:string,registration:ExternalPluginRegistration){
   const base={pluginId:registration.pluginId,version:registration.pluginVersion,provider:registration.provider,enabled:registration.enabled,scope:registration.scope,transport:registration.transport.kind};
   if(registration.scope==='repository')return{...base,healthScope:'repository_context_required' as const};
-  const repository=controllerPluginRepository(controllerHome);
-  try{return{...base,health:getAssistantPluginManifest(controllerHome,repository,registration.pluginId).health};}
+  try{return{...base,health:getControllerPluginManifest(controllerHome,registration.pluginId).health};}
   catch(error){return{...base,health:{state:'error',message:error instanceof Error?error.message:String(error)}};}
 }
 function run(command:string,args:string[],cwd:string,timeoutMs=120000):string{
-  const result=spawnSync(command,args,{cwd,encoding:'utf8',timeout:timeoutMs,maxBuffer:32*1024*1024,shell:false,windowsHide:true});
+  const result=spawnSync(command,args,{cwd,encoding:'utf8',env:process.env,timeout:timeoutMs,maxBuffer:32*1024*1024,shell:false,windowsHide:true});
   if(result.error)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${result.error.message}`);
   if(result.status!==0)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${command} exited ${result.status}: ${String(result.stderr||result.stdout).slice(-4000)}`);
   return String(result.stdout??'');
@@ -96,15 +107,30 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     // useful diagnostics, but must not strand a verified package when that
     // helper field is stale.
     const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry,{packageIdentityVerified:true}));
-    const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,entry.id);
+    syncControllerPluginRegistry(controllerHome);const plugin=getControllerPluginManifest(controllerHome,entry.id);
     if(backed)rmSync(backup,{recursive:true,force:true});
     return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health,nextSteps:installerNextSteps(result)};
   }catch(error){rmSync(stage,{recursive:true,force:true});if(backed&&existsSync(finalRoot))rmSync(finalRoot,{recursive:true,force:true});if(backed&&existsSync(backup))renameSync(backup,finalRoot);throw error;}
 }
+export function installOfficialPlugin(pluginId:string,controllerHome:string):Record<string,unknown>{
+  const entry=officialPluginCatalogEntry(pluginId);
+  if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${pluginId}`);
+  return withOfficialPluginLifecycleLock(controllerHome,pluginId,()=>install(entry,controllerHome));
+}
+export function installTrustedExternalPlugin(pluginId:string,catalogPath:string,controllerHome:string):Record<string,unknown>{
+  const entry=trustedExternalPluginCatalogEntry(pluginId,catalogPath,controllerHome);
+  if(!entry)throw new Error(`PLUGIN_NOT_IN_TRUSTED_CATALOG: ${pluginId}`);
+  return withOfficialPluginLifecycleLock(controllerHome,pluginId,()=>install(entry,controllerHome));
+}
+
 export function buildPluginCommand():Command{
   const root=new Command('plugin').description('Discover and install trusted Forge plugins');
   root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=officialPluginCatalogItems();if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':`incompatible (${x.reason})`}\t${x.name}`));});
-  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe controller-scoped providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>externalPluginListItem(home,r));if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${'healthScope' in x?'repository-context-required':((x.health as {state?:string})?.state??'unknown')}`));});
-  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else{console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);for(const step of (result.nextSteps as string[]|undefined)??[])console.log(`- ${step}`);}});
+  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe controller-scoped providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome);if(o.refresh)syncControllerPluginRegistry(home);const items=listExternalPluginRegistrations(home).map(r=>externalPluginListItem(home,r));if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${'healthScope' in x?'repository-context-required':((x.health as {state?:string})?.state??'unknown')}`));});
+  const trust=root.command('trust').description('Manage exact third-party plugin repository trust in Controller Home');
+  trust.command('list').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((o:CliOptions)=>{const policy=readControllerPluginTrustPolicy(resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(policy,null,2));else policy.trustedRepositories.forEach(repository=>console.log(repository));});
+  trust.command('add <repository-url>').option('--controller-home <path>','Override Controller Home').action((repository:string,o:CliOptions)=>{const policy=trustExternalPluginRepository(resolveControllerHome(o.controllerHome),repository);console.log(`Trusted exact plugin repository: ${policy.trustedRepositories.find(entry=>entry===new URL(repository).toString())??repository}`);});
+  trust.command('remove <repository-url>').option('--controller-home <path>','Override Controller Home').action((repository:string,o:CliOptions)=>{untrustExternalPluginRepository(resolveControllerHome(o.controllerHome),repository);console.log(`Removed plugin repository trust: ${repository}`);});
+  root.command('install <plugin-id>').description('Install/update a pinned plugin from the first-party catalog or an explicitly trusted external catalog').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--catalog <path>','External catalog file; every repository must already be explicitly trusted').action((id:string,o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome);const entry=o.catalog?trustedExternalPluginCatalogEntry(id,o.catalog,home):officialPluginCatalogEntry(id);if(!entry)throw new Error(o.catalog?`PLUGIN_NOT_IN_TRUSTED_CATALOG: ${id}`:`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=o.catalog?installTrustedExternalPlugin(id,o.catalog,home):installOfficialPlugin(id,home);if(o.json)console.log(JSON.stringify(result,null,2));else{console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);for(const step of (result.nextSteps as string[]|undefined)??[])console.log(`- ${step}`);}});
   return root;
 }