@moretea-labs/forge 1.5.0 → 1.6.0

package/src/cli/commands/chatgpt.ts

@@ -13,7 +13,11 @@ import {
 } from '../chatgpt-browser/engine';
 import type { BrowserProviderName, BrowserSessionStatus, NativeBrowserChannel, ThinkingLevel } from '../chatgpt-browser/types';
 import { durableControllerHome } from '../repositories/controller-home';
-import { runWorkChatgptContinuation } from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
+import {
+  runWorkChatgptContinuation,
+  type ChatgptAutomationReasoning,
+  type ChatgptAutomationTabPolicy,
+} from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
 
 interface BrowserCommonOptions {
   repo?: string;
@@ -84,6 +88,9 @@ interface WorkChatgptContinueOptions extends BrowserCommonOptions {
   title?: string;
   session?: string;
   conversationUrl?: string;
+  model?: string;
+  reasoning?: string;
+  tabPolicy?: string;
   timeoutMs?: string;
 }
 
@@ -109,6 +116,18 @@ interface BrowserFollowupOptions extends BrowserCommonOptions {
   oracleBin?: string;
 }
 
+function parseAutomationReasoning(value?: string): ChatgptAutomationReasoning | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'medium' || value === 'high' || value === 'xhigh') return value;
+  throw new Error(`invalid --reasoning "${value}" (expected: medium, high, xhigh)`);
+}
+
+function parseAutomationTabPolicy(value?: string): ChatgptAutomationTabPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'auto' || value === 'reuse' || value === 'new') return value;
+  throw new Error(`invalid --tab-policy "${value}" (expected: auto, reuse, new)`);
+}
+
 function parseProvider(value?: string): BrowserProviderName {
   if (value === undefined || value === 'oracle') return 'oracle';
   if (value === 'native') return 'native';
@@ -384,8 +403,11 @@ export function buildChatgptCommand(): Command {
     .requiredOption('--work-id <work-id>', 'Stable Forge Work id')
     .requiredOption('--prompt <text>', 'Bounded continuation prompt')
     .option('--title <title>', 'Human-readable local conversation alias')
-    .option('--session <session-id>', 'Legacy saved browser session to seed the binding')
+    .option('--session <session-id>', 'Saved browser session to seed or resume the Work binding')
     .option('--conversation-url <url>', 'Explicit ChatGPT conversation URL to seed the binding')
+    .option('--model <label>', 'Requested ChatGPT automation model', 'gpt-5.6')
+    .option('--reasoning <level>', 'Reasoning level: medium|high|xhigh', 'high')
+    .option('--tab-policy <policy>', 'Browser tab policy: auto|reuse|new', 'auto')
     .option('--timeout-ms <ms>', 'Assistant timeout in milliseconds')
     .action((rawOpts: WorkChatgptContinueOptions) => {
       void runChatgptAction(async () => {
@@ -398,6 +420,9 @@ export function buildChatgptCommand(): Command {
           title: rawOpts.title,
           browserSessionId: rawOpts.session,
           conversationUrl: rawOpts.conversationUrl,
+          model: rawOpts.model,
+          reasoning: parseAutomationReasoning(rawOpts.reasoning),
+          tabPolicy: parseAutomationTabPolicy(rawOpts.tabPolicy),
           timeoutMs: parsePositiveInteger('timeout-ms', rawOpts.timeoutMs),
         });
         console.log(JSON.stringify({
@@ -408,6 +433,10 @@ export function buildChatgptCommand(): Command {
           conversationId: result.conversationId,
           localAlias: result.localAlias,
           resumedFromBinding: result.resumedFromBinding,
+          model: result.model,
+          reasoning: result.reasoning,
+          tabPolicy: result.tabPolicy,
+          executionPreferenceVerified: result.executionPreferenceVerified,
           error: result.error,
         }, null, 2));
       });

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

@@ -17,6 +17,7 @@ import { Command } from 'commander';
 import { runDoctor, type CheckStatus, type DoctorReport } from './doctor';
 import { runStatus, type StatusReport } from './status';
 import { runMcpSetupChatgpt } from '../mcp/setup';
+import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
 import {
   configureSetupProfile,
   detectSetupPlatform,
@@ -790,7 +791,8 @@ export function openSetupSession(options: SetupSessionOptions = {}): SetupSessio
   const platform = options.platform ?? detectSetupPlatform({ env: options.env });
   const target = options.target ?? setupHostTarget(profile);
   const report = options.report ?? runInitHook({ ...options, target });
-  const nextAction = profileNextAction(profile, platform, { controllerHome: options.controllerHome, accountHome: options.accountHome }) ?? report.agent_actions[0];
+  const controllerHome = resolveRepoPreferredControllerHome(options.cwd ?? process.cwd(), options.controllerHome);
+  const nextAction = profileNextAction(profile, platform, { controllerHome, accountHome: options.accountHome }) ?? report.agent_actions[0];
   const now = (options.now ?? (() => new Date()))().toISOString();
   const reuse = previous && previous.status !== 'closed';
   return writeSetupSessionAt(path, {

package/src/cli/commands/mcp.ts

@@ -50,6 +50,7 @@ interface McpSetupChatgptOptions {
   endpoint?: string;
   serverName?: string;
   localControllerPort?: string;
+  connectorPort?: string;
 }
 
 interface McpSetupLocalControllerOptions {
@@ -237,6 +238,7 @@ 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('--endpoint <url>', 'Stable public HTTPS /mcp endpoint to store in ignored local config')
     .option('--server-name <name>', 'ChatGPT Connector/MCP server name to record in ignored local config')
     .action((rawOpts: McpSetupChatgptOptions) => {

package/src/cli/commands/plugin.ts

@@ -5,11 +5,11 @@ import { dirname, isAbsolute, join, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
-import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
+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';
 
-interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer: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[]; }
 interface Registry { schemaVersion:1; plugins:RegistryEntry[]; }
 interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; }
 const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'../../..');
@@ -24,11 +24,26 @@ function registry():Registry{
     if(!plugin.repository.startsWith('https://github.com/moretea-labs/')||!plugin.repository.endsWith('.git'))throw new Error(`PLUGIN_CATALOG_UNTRUSTED_REPOSITORY: ${plugin.id}`);
     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}`);
     ids.add(plugin.id);
   }
   return value;
 }
 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}`};
+  if(entry.providerVersion&&entry.providerVersion!==entry.version)return{compatible:false,reason:`catalog version ${entry.version} does not match pinned provider version ${entry.providerVersion}`};
+  return{compatible:true};
+}
+export function officialPluginCatalogItems(platform:NodeJS.Platform=process.platform){return registry().plugins.map(entry=>({...entry,...pluginCatalogCompatibility(entry,platform)}));}
+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};}
+  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});
   if(result.error)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${result.error.message}`);
@@ -40,17 +55,29 @@ function installerJson(stdout:string):Record<string,unknown>{
   for(let i=lines.length-1;i>=0;i--){try{const x=JSON.parse(lines[i]);if(x&&typeof x==='object'&&!Array.isArray(x)&&x.schemaVersion===1)return x;}catch{}}
   throw new Error('PLUGIN_INSTALLER_OUTPUT_INVALID');
 }
+export function installerNextSteps(result:Record<string,unknown>):string[]{
+  if(!Array.isArray(result.nextSteps))return[];
+  return result.nextSteps
+    .filter((value):value is string=>typeof value==='string')
+    .map(value=>value.replace(/[\u0000-\u001F\u007F]/g,' ').trim().slice(0,1000))
+    .filter(Boolean)
+    .slice(0,10);
+}
 function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
   if(result.registration){const input=result.registration as ExternalPluginRegistrationInput;if(input.pluginId!==entry.id)throw new Error('PLUGIN_INSTALLER_ID_MISMATCH');if(input.pluginVersion!==entry.version)throw new Error('PLUGIN_INSTALLER_VERSION_MISMATCH');return input;}
   const facts=result.providerInstall as Record<string,unknown>|undefined;
   if(!facts||facts.kind!=='desktop_operator'||entry.id!=='desktop_operator')throw new Error('PLUGIN_INSTALLER_REGISTRATION_MISSING');
-  if(facts.pluginVersion!==entry.version||facts.protocolVersion!=='1.0')throw new Error('PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH');
+  const expectedProviderVersion=entry.providerVersion??entry.version;
+  const expectedProtocolVersion=entry.protocolVersion??'1.0';
+  if(facts.pluginVersion!==expectedProviderVersion)throw new Error(`PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH: expected ${expectedProviderVersion} for ${entry.id}@${entry.version}, actual ${String(facts.pluginVersion??'missing')}`);
+  if(facts.protocolVersion!==expectedProtocolVersion)throw new Error(`PLUGIN_INSTALLER_PROTOCOL_VERSION_MISMATCH: expected ${expectedProtocolVersion} for ${entry.id}@${entry.version}, actual ${String(facts.protocolVersion??'missing')}`);
   const socketPath=typeof facts.socketPath==='string'?facts.socketPath:'';const launchAgentLabel=typeof facts.launchAgentLabel==='string'?facts.launchAgentLabel:'';const expectedProgramContains=typeof facts.expectedProgramContains==='string'?facts.expectedProgramContains:'';
   if(!isAbsolute(socketPath)||!launchAgentLabel||!expectedProgramContains)throw new Error('PLUGIN_INSTALLER_PROVIDER_FACTS_INVALID');
-  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:entry.version,protocolVersion:'1.0'});
+  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:expectedProviderVersion,protocolVersion:expectedProtocolVersion});
 }
 function install(entry:RegistryEntry,controllerHome:string):Record<string,unknown>{
-  if(!entry.platforms.includes(process.platform))throw new Error(`PLUGIN_PLATFORM_UNSUPPORTED: ${entry.id}/${process.platform}`);
+  const compatibility=pluginCatalogCompatibility(entry,process.platform);
+  if(!compatibility.compatible)throw new Error(`PLUGIN_CATALOG_INCOMPATIBLE: ${entry.id}@${entry.version}: ${compatibility.reason}`);
   const packagesRoot=join(controllerSystemRoot(controllerHome),'plugins','packages');mkdirSync(packagesRoot,{recursive:true,mode:0o700});
   const finalRoot=join(packagesRoot,entry.id),stage=join(packagesRoot,`.${entry.id}.${randomUUID()}.staging`),backup=join(packagesRoot,`.${entry.id}.${randomUUID()}.backup`);let backed=false;
   try{
@@ -62,13 +89,13 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
     const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,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};
+    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 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=registry().plugins.map(x=>({...x,compatible:x.platforms.includes(process.platform)}));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':'unsupported'}\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 providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>{let health:unknown;try{health=getAssistantPluginManifest(home,repo,r.pluginId).health;}catch(e){health={state:'error',message:e instanceof Error?e.message:String(e)};}return{pluginId:r.pluginId,version:r.pluginVersion,provider:r.provider,enabled:r.enabled,transport:r.transport.kind,health};});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${(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'}).`);});
+  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}`);}});
   return root;
 }

package/src/cli/commands/runtime.ts

@@ -72,6 +72,7 @@ export function buildRuntimeCommand(): Command {
         },
         servicePath: result.servicePath,
         pid: result.pid,
+        connector: result.connector,
         warnings: result.warnings,
         next: `forge runtime status --controller-home ${home}`,
       });

package/src/cli/commands/setup-profile.ts

@@ -206,6 +206,20 @@ export function detectSetupPlatform(options: { platform?: NodeJS.Platform; arch?
 }
 
 
+function isLoopbackMcpEndpoint(value: string | undefined): boolean {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'http:'
+      && (parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost' || parsed.hostname === '::1')
+      && parsed.pathname === '/mcp'
+      && !parsed.search
+      && !parsed.hash;
+  } catch {
+    return false;
+  }
+}
+
 export interface ControllerGuidance {
   controller: SetupControllerKind;
   ready: boolean;
@@ -244,8 +258,9 @@ export function resolveControllerGuidance(
       const localReady = localConfig?.profile === 'controller'
         && localConfig.server?.host === '127.0.0.1'
         && Number.isInteger(localConfig.server?.port);
+      const connectorReady = controller !== 'chatgpt' || isLoopbackMcpEndpoint(localConfig?.chatgpt?.localEndpoint);
       const endpointReady = !profile.tunnel.endpoint || localConfig?.chatgpt?.endpoint === profile.tunnel.endpoint;
-      if (!localReady || !endpointReady) {
+      if (!localReady || !connectorReady || !endpointReady) {
         const endpoint = profile.tunnel.endpoint ? ` --endpoint ${profile.tunnel.endpoint}` : '';
         return {
           controller,
@@ -319,7 +334,7 @@ export function resolveRuntimeGuidance(
 export function resolveTunnelGuidance(
   profile: SetupProfile | undefined,
   platform = detectSetupPlatform(),
-  options: { controllerHome?: string } = {},
+  options: { controllerHome?: string; env?: NodeJS.ProcessEnv } = {},
 ): TunnelGuidance {
   if (!profile || !setupNeedsRemoteAccess(profile)) {
     return { provider: 'none', ready: true, title: 'Remote controller connection', detail: 'Not required by the configured local controller set.' };
@@ -329,15 +344,11 @@ export function resolveTunnelGuidance(
   }
   let provider = profile.tunnel.provider;
   if (provider === 'auto') {
-    if (platform.commands.tunnelClient) provider = 'openai';
-    else if (platform.commands.cloudflared) provider = 'cloudflare';
-    else if (platform.commands.tailscale) provider = 'tailscale';
-    else {
-      return {
-        provider: 'auto', ready: false, title: 'Choose secure remote access',
-        detail: 'For ChatGPT, prefer OpenAI Secure MCP Tunnel when your workspace/Platform organization supports it; otherwise choose Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS endpoint, or defer remote access. Forge never requires public ingress when a private tunnel is available.',
-      };
-    }
+    // ChatGPT's private outbound path is the default. Do not silently choose a
+    // public ingress provider merely because cloudflared/tailscale happens to
+    // be installed; users without Secure Tunnel access can explicitly select a
+    // fallback provider.
+    provider = 'openai';
   }
   if (provider === 'openai') {
     if (!profile.tunnel.tunnelId) {
@@ -353,9 +364,22 @@ export function resolveTunnelGuidance(
         detail: 'Install the supported tunnel-client binary from OpenAI Platform Tunnels or the official openai/tunnel-client release. The runtime API key remains an environment/file reference owned by tunnel-client; Forge does not store it.',
       };
     }
-    const alias = 'forge';
-    const status = spawnSync('tunnel-client', ['runtimes', 'status', alias, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000 });
-    if (status.status === 0) {
+    const preferredAlias = 'forge';
+    const aliases = [preferredAlias];
+    const listed = spawnSync('tunnel-client', ['runtimes', 'list', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000, env: options.env ?? process.env });
+    if (listed.status === 0) {
+      try {
+        const value = JSON.parse(listed.stdout || '{}') as { aliases?: Array<{ alias?: string; tunnel_id?: string }> };
+        for (const entry of value.aliases ?? []) {
+          if (entry.tunnel_id === profile.tunnel.tunnelId && entry.alias) aliases.push(entry.alias);
+        }
+      } catch {
+        // Older clients may not expose local aliases as JSON. Keep the preferred alias fallback.
+      }
+    }
+    for (const alias of Array.from(new Set(aliases))) {
+      const status = spawnSync('tunnel-client', ['runtimes', 'status', alias, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000, env: options.env ?? process.env });
+      if (status.status !== 0) continue;
       try {
         const value = JSON.parse(status.stdout || '{}') as { process_running?: boolean; healthy?: boolean; ready?: boolean; tunnel_id?: string };
         if (value.process_running === true && value.healthy === true && value.ready === true
@@ -369,13 +393,20 @@ export function resolveTunnelGuidance(
         // Treat malformed or older status output as not-ready instead of claiming success.
       }
     }
+    const alias = preferredAlias;
     const localConfig = loadMcpServiceLocalConfig(resolveControllerHome(options.controllerHome));
-    const configuredPort = localConfig?.server?.port;
-    const mcpPort = typeof configuredPort === 'number' && Number.isInteger(configuredPort) ? configuredPort : 8765;
+    const localEndpoint = localConfig?.chatgpt?.localEndpoint;
+    if (!isLoopbackMcpEndpoint(localEndpoint)) {
+      return {
+        provider, ready: false, title: 'Prepare the local ChatGPT OAuth endpoint',
+        detail: 'Secure Tunnel must terminate at Forge’s loopback OAuth Gateway, not the bearer-only Canonical Runtime. Refresh the user-level ChatGPT MCP configuration first.',
+        command: 'forge mcp setup chatgpt --user-level',
+      };
+    }
     return {
       provider, ready: false, title: 'Connect OpenAI Secure MCP Tunnel',
-      detail: 'Create a supervised tunnel-client runtime and verify it with runtimes status. Set CONTROL_PLANE_API_KEY in the invoking environment; Forge passes only an env reference and never reads or stores the key.',
-      command: `tunnel-client runtimes connect --alias ${alias} --tunnel-id ${profile.tunnel.tunnelId} --runtime-api-key env:CONTROL_PLANE_API_KEY --mcp-server-url http://127.0.0.1:${mcpPort}/mcp`,
+      detail: 'Create a supervised tunnel-client runtime and verify it with runtimes status. Keep the runtime API key in an environment or file reference owned by tunnel-client; Forge never reads or stores the key.',
+      command: `tunnel-client runtimes connect --alias ${alias} --tunnel-id ${profile.tunnel.tunnelId} --runtime-api-key env:CONTROL_PLANE_API_KEY --mcp-server-url ${localEndpoint}`,
     };
   }
   if (provider === 'none') {

package/src/cli/controller/context-pack.ts

@@ -67,6 +67,8 @@ export interface ControllerContextPackOptions {
   maxSnippets?: number;
   maxCharsPerSnippet?: number;
   structuralContext?: StructuralContextMode;
+  /** Optional repository-level CodeGraph root used as structural baseline when the selected checkout has no local index. */
+  structuralIndexRoot?: string;
   retrievalMode?: ControllerContextRetrievalMode;
   /** GPT-selected cross-cutting evidence dimensions. Forge expands mechanically and never treats them as semantic completeness proof. */
   impactDomains?: ControllerContextImpactDomain[];
@@ -138,6 +140,9 @@ export interface ControllerContextPackProjection {
     requestedMode: StructuralContextMode;
     status: "disabled" | "ready" | "stale" | "unavailable" | "degraded";
     requiredSatisfied: boolean;
+    indexSource: "current_checkout" | "repository_baseline";
+    overlayChangedFiles: string[];
+    baselineRevisionMatches: boolean;
     query?: string;
     entryPoints: Array<Pick<CodeGraphNodeSummary, "id" | "kind" | "name" | "filePath" | "startLine" | "endLine">>;
     relatedFiles: string[];
@@ -146,6 +151,26 @@ export interface ControllerContextPackProjection {
     timingsMs?: CodeGraphReadProviderResponse["timingsMs"];
     truncated: boolean;
   };
+  impactContext: {
+    status: "not_requested" | "ready" | "degraded";
+    confidence: "low" | "medium" | "high";
+    primaryTargets: string[];
+    mustInspect: string[];
+    likelyAffected: string[];
+    relevantTests: string[];
+    relevantChecks: string[];
+    architectureContracts: string[];
+    coverageGaps: string[];
+    relationSources: Array<"codegraph" | "lexical" | "forge_checks">;
+    freshness: {
+      structuralStatus: "disabled" | "ready" | "stale" | "unavailable" | "degraded";
+      lastIndexedAt?: number | null;
+      changedFileCount: number;
+      indexSource: "current_checkout" | "repository_baseline";
+      overlayChangedFileCount: number;
+      baselineRevisionMatches: boolean;
+    };
+  };
   files: ControllerContextPackFile[];
   deniedPaths: Array<{ path: string; reason: string }>;
   omitted: Array<{ path: string; reason: string }>;
@@ -273,6 +298,18 @@ function coveredByGlob(path: string, globs: string[]): boolean {
   return globs.length === 0 || globs.some((glob) => globMatches(glob, path));
 }
 
+function gitStatusChangedPaths(status: string): string[] {
+  const paths: string[] = [];
+  for (const line of status.split(/\r?\n/)) {
+    if (!line.trim() || line.startsWith("##") || line.length < 4) continue;
+    let path = line.slice(3).trim();
+    if (path.includes(" -> ")) path = path.slice(path.lastIndexOf(" -> ") + 4).trim();
+    if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
+    if (path && !paths.includes(path)) paths.push(path);
+  }
+  return paths;
+}
+
 function addReason(map: Map<string, { reasons: Set<string>; lines: Set<number> }>, path: string, reason: string, line?: number): void {
   const entry = map.get(path) ?? { reasons: new Set<string>(), lines: new Set<number>() };
   entry.reasons.add(reason);
@@ -453,11 +490,19 @@ export function buildControllerContextPack(
   let skippedBinaryFiles = 0;
   let searchTruncated = false;
   const structuralMode = options.structuralContext ?? "off";
+  const structuralIndexRoot = options.structuralIndexRoot?.trim() || repoRoot;
+  const indexSource = structuralIndexRoot === repoRoot ? "current_checkout" : "repository_baseline";
+  const overlayChangedFiles = indexSource === "repository_baseline" ? gitStatusChangedPaths(git.status) : [];
+  const baselineRevisionMatches = indexSource === "current_checkout" || gitSnapshot(structuralIndexRoot).head === git.head;
+  const graphImpactFiles = new Set<string>();
   let structuralContext: ControllerContextPackProjection["structuralContext"] = {
     provider: "codegraph",
     requestedMode: structuralMode,
     status: "disabled",
     requiredSatisfied: structuralMode !== "required",
+    indexSource,
+    overlayChangedFiles,
+    baselineRevisionMatches,
     entryPoints: [],
     relatedFiles: [],
     truncated: false,
@@ -474,7 +519,7 @@ export function buildControllerContextPack(
       };
     } else {
       const queryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
-      const structural = queryCodeGraph(repoRoot, {
+      const structural = queryCodeGraph(structuralIndexRoot, {
         operation: "context",
         query: structuralQuery,
         limit: Math.min(Math.max(maxFiles, 4), 12),
@@ -496,8 +541,11 @@ export function buildControllerContextPack(
       structuralContext = {
         provider: "codegraph",
         requestedMode: structuralMode,
-        status: structural.status,
-        requiredSatisfied: structuralMode !== "required" || structural.status === "ready",
+        status: indexSource === "repository_baseline" && (!baselineRevisionMatches || overlayChangedFiles.length > 0) && structural.status === "ready" ? "stale" : structural.status,
+        requiredSatisfied: structuralMode !== "required" || (structural.status === "ready" && baselineRevisionMatches && overlayChangedFiles.length === 0),
+        indexSource,
+        overlayChangedFiles,
+        baselineRevisionMatches,
         query: structuralQuery,
         entryPoints: graph.entryPoints.slice(0, 12).map((node) => ({
           id: node.id,
@@ -530,17 +578,50 @@ export function buildControllerContextPack(
         addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
       }
       for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
+      // Context search identifies the structural entry points. For a bounded
+      // number of those files, enrich the same Context Plane call with direct
+      // file dependencies/dependents. This is impact evidence, not a second
+      // routing/tool surface, and remains completely off for ordinary Direct.
+      if (structural.status === "ready") {
+        const primaryFiles = Array.from(new Set(graph.entryPoints.map((node) => node.filePath).filter(Boolean))).slice(0, 4);
+        for (const filePath of primaryFiles) {
+          const adjacency = queryCodeGraph(structuralIndexRoot, { operation: "file_dependencies", filePath, limit: 40 });
+          if (!adjacency.ok || adjacency.status !== "ready") continue;
+          const dependencies = Array.isArray(adjacency.result?.dependencies)
+            ? adjacency.result.dependencies.filter((value): value is string => typeof value === "string")
+            : [];
+          const dependents = Array.isArray(adjacency.result?.dependents)
+            ? adjacency.result.dependents.filter((value): value is string => typeof value === "string")
+            : [];
+          for (const path of dependencies.slice(0, 40)) {
+            graphImpactFiles.add(path);
+            addStructuralPath(path, `codegraph:dependency:${filePath}`);
+          }
+          for (const path of dependents.slice(0, 40)) {
+            graphImpactFiles.add(path);
+            addStructuralPath(path, `codegraph:dependent:${filePath}`);
+          }
+        }
+      }
       for (const path of metadata?.changedFiles.added ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
       for (const path of metadata?.changedFiles.modified ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
       for (const path of metadata?.changedFiles.removed ?? []) omitted.push({ path, reason: "codegraph reports file removed since index" });
+      for (const path of overlayChangedFiles) addStructuralPath(path, "worktree:changed-file", 1);
     }
   }
 
+  const exactKnownFiles: string[] = [];
+  let exactKnownFileScope = explicitKnownPaths.length > 0;
   for (const path of explicitKnownPaths) {
     const expanded = expandKnownPath(repoRoot, policy, path, Math.max(maxFiles * 4, 40));
     for (const file of expanded.files) {
       addReason(candidates, file, expanded.directory ? `explicit-known-directory:${expanded.directory}` : "explicit-known-path", 1);
     }
+    if (!expanded.directory && expanded.files.length === 1 && expanded.denied.length === 0 && !expanded.truncated) {
+      exactKnownFiles.push(expanded.files[0]!);
+    } else {
+      exactKnownFileScope = false;
+    }
     deniedPaths.push(...expanded.denied);
     scannedFiles += expanded.files.length;
     searchTruncated = searchTruncated || expanded.truncated;
@@ -550,16 +631,27 @@ export function buildControllerContextPack(
     if (!includeGlobs.includes(glob)) includeGlobs.push(glob);
   }
 
+  // Exact known files are already a caller-selected implementation scope. When
+  // no broader impact/structural/include scope was requested, search those files
+  // for useful hit lines instead of rereading the whole repository. Planning,
+  // debugging, directories and explicit broader scopes retain full discovery.
+  const scopedExactKnownFileSearch = exactKnownFileScope
+    && retrievalMode === "implementation"
+    && structuralMode === "off"
+    && impactDomains.length === 0
+    && searchIncludeGlobs.length === 0;
+
   // Lexical retrieval is one bounded pass across candidate files for all terms.
   // The old per-term loop reread the same source files up to 14 times even
   // though inventory itself was cached.
   if (searchQueries.length > 0 && candidates.size < maxFiles * 3) {
     const search = searchRepositoryMany(repoRoot, policy, {
       queries: searchQueries,
-      includeGlobs: searchIncludeGlobs,
+      files: scopedExactKnownFileSearch ? exactKnownFiles : undefined,
+      includeGlobs: scopedExactKnownFileSearch ? undefined : searchIncludeGlobs,
       excludeGlobs,
       maxResultsPerQuery: Math.max(maxFiles * 4, 12),
-      maxFiles: MAX_TOTAL_SEARCHED_FILES,
+      maxFiles: scopedExactKnownFileSearch ? exactKnownFiles.length : MAX_TOTAL_SEARCHED_FILES,
       caseSensitive: false,
       cacheKey: JSON.stringify({ head: git.head, status: git.status, diffStat: git.diffStat }),
     });
@@ -685,6 +777,65 @@ export function buildControllerContextPack(
   const rawCodeRequiredForImplementation = retrievalMode !== "implementation"
     || files.length === 0
     || rawSnippetTruncated;
+  const primaryTargets = Array.from(new Set(structuralContext.entryPoints.map((entry) => entry.filePath).filter(Boolean))).slice(0, 20);
+  const structuralUniverse = Array.from(new Set([
+    ...primaryTargets,
+    ...graphImpactFiles,
+    ...structuralContext.relatedFiles,
+    ...selected.map((entry) => entry.path),
+  ])).slice(0, 160);
+  const relevantTests = structuralUniverse.filter((path) => /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(path)).slice(0, 40);
+  const architectureContracts = structuralUniverse.filter((path) =>
+    path === "AGENTS.md"
+    || path === "CLAUDE.md"
+    || path.startsWith("docs/architecture/")
+    || path.startsWith(".ai/context/"),
+  ).slice(0, 40);
+  const mustInspect = Array.from(new Set([...primaryTargets, ...graphImpactFiles, ...relevantTests, ...architectureContracts])).slice(0, 80);
+  const mustInspectSet = new Set(mustInspect);
+  const likelyAffected = structuralUniverse.filter((path) => !mustInspectSet.has(path)).slice(0, 80);
+  const changedFileCount = structuralContext.metadata
+    ? structuralContext.metadata.changedFiles.added.length
+      + structuralContext.metadata.changedFiles.modified.length
+      + structuralContext.metadata.changedFiles.removed.length
+    : 0;
+  const coverageGaps = [
+    ...(structuralContext.status === "stale" ? ["structural_index_stale"] : []),
+    ...(structuralContext.indexSource === "repository_baseline" ? ["structural_repository_baseline_overlay"] : []),
+    ...(!structuralContext.baselineRevisionMatches ? ["structural_baseline_revision_mismatch"] : []),
+    ...(structuralContext.status === "unavailable" || structuralContext.status === "degraded" ? ["structural_provider_unavailable"] : []),
+    ...(structuralContext.truncated ? ["structural_result_truncated"] : []),
+    ...(changedFileCount > 0 ? ["structural_index_has_unindexed_changes"] : []),
+    ...impactCoverage.filter((coverage) => coverage.status !== "selected").map((coverage) => `impact_domain_${coverage.status}:${coverage.domain}`),
+  ];
+  const impactContext: ControllerContextPackProjection["impactContext"] = {
+    status: structuralMode === "off" ? "not_requested" : structuralContext.status === "ready" ? "ready" : "degraded",
+    confidence: structuralContext.status === "ready" && primaryTargets.length > 0 && !structuralContext.truncated
+      ? "high"
+      : structuralContext.status === "ready" || files.length > 0
+        ? "medium"
+        : "low",
+    primaryTargets,
+    mustInspect,
+    likelyAffected,
+    relevantTests,
+    relevantChecks: taskChecks,
+    architectureContracts,
+    coverageGaps: Array.from(new Set(coverageGaps)).slice(0, 40),
+    relationSources: [
+      ...(structuralMode !== "off" ? ["codegraph" as const] : []),
+      ...(files.length > 0 ? ["lexical" as const] : []),
+      ...(taskChecks.length > 0 ? ["forge_checks" as const] : []),
+    ],
+    freshness: {
+      structuralStatus: structuralContext.status,
+      lastIndexedAt: structuralContext.metadata?.lastIndexedAt,
+      changedFileCount,
+      indexSource: structuralContext.indexSource,
+      overlayChangedFileCount: structuralContext.overlayChangedFiles.length,
+      baselineRevisionMatches: structuralContext.baselineRevisionMatches,
+    },
+  };
 
   return {
     schemaVersion: CONTEXT_PACK_SCHEMA_VERSION,
@@ -712,6 +863,7 @@ export function buildControllerContextPack(
       truncated: searchTruncated,
     },
     structuralContext,
+    impactContext,
     files,
     deniedPaths: deniedPaths.slice(0, 20),
     omitted: omitted.slice(0, 30),
@@ -732,7 +884,7 @@ export function buildControllerContextPack(
         retrievalMode === "implementation"
           ? "The pack already contains policy-approved current raw source snippets with file SHA identities. Request wider/exact ranges only when ChatGPT judges the impact surface ambiguous or an expansion signal makes the raw evidence mechanically incomplete."
           : "Investigation modes may intentionally expand exact ranges, structural relationships, tests, and neighboring modules before any implementation decision.",
-        "Search/CodeGraph ranking is discovery evidence, not a business-semantics authority. Forge never decides that the returned files are the complete semantic impact surface.",
+        "Search/CodeGraph ranking is discovery evidence, not a business-semantics authority. impactContext makes the bounded evidence surface and coverage gaps explicit; ChatGPT still decides semantic sufficiency.",
         impactDomains.length > 0 ? `Impact domains were selected by ChatGPT and expanded mechanically in this same retrieval call: ${impactDomains.join(", ")}. Missing or omitted domain evidence is an ambiguity signal, not proof that the domain is irrelevant.` : "No explicit cross-cutting impact domains were requested; ChatGPT may add them when state, scheduling, notifications, events, caching, API, or concurrency could materially change the implementation.",
         "CodeGraph structural evidence is discovery evidence. Raw source access still passes through Forge repository policy and current-file reads.",
         structuralContext.status === "stale" ? "CodeGraph reports stale structural evidence. Treat graph relationships as hints and prefer the returned current raw source for changed files." : structuralContext.status === "unavailable" || structuralContext.status === "degraded" ? "Structural context was unavailable or degraded; bounded text search remains the fallback." : structuralContext.status === "ready" ? "CodeGraph structural context was queried read-only with index sync disabled." : "Structural context was not requested.",