@moretea-labs/forge 1.7.1 → 1.8.0

package/src/cli/chatgpt-browser/native-provider.ts

@@ -1,10 +1,9 @@
-import { spawnSync } from 'child_process';
-import { existsSync } from 'fs';
+import { spawn } from 'child_process';
 import { createServer } from 'net';
-import { homedir } from 'os';
-import { join, resolve } from 'path';
+import { resolve } from 'path';
 import { pathToFileURL } from 'url';
 import type { BrowserConsultInput, NativeBrowserChannel, PromptBundle } from './types';
+import { describeNativeBrowserProduct, discoverNativeBrowserProduct } from '../../runtime/platform/browser-product-discovery';
 
 export interface NativeProviderResult {
   status: 'completed' | 'failed' | 'incomplete_capture';
@@ -46,25 +45,6 @@ const SEND_BUTTON_SELECTORS = [
 const ASSISTANT_SELECTOR = '[data-message-author-role="assistant"]';
 const STABLE_CAPTURE_MS = 5000;
 
-const CHANNEL_APPS: Record<NativeBrowserChannel, { appName: string; executable: string }> = {
-  chrome: {
-    appName: 'Google Chrome',
-    executable: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  },
-  'chrome-beta': {
-    appName: 'Google Chrome Beta',
-    executable: '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
-  },
-  'chrome-dev': {
-    appName: 'Google Chrome Dev',
-    executable: '/Applications/Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev',
-  },
-  'chrome-canary': {
-    appName: 'Google Chrome Canary',
-    executable: '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
-  },
-};
-
 interface CdpConnection {
   send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<any>;
   close(): void;
@@ -74,10 +54,6 @@ function browserChannel(input?: NativeBrowserChannel): NativeBrowserChannel {
   return input ?? 'chrome';
 }
 
-function chromeExecutable(channel: NativeBrowserChannel): string {
-  return CHANNEL_APPS[channel].executable;
-}
-
 function chromeProfileArgs(profileDir: string, profileDirectory?: string): string[] {
   return [
     `--user-data-dir=${profileDir}`,
@@ -90,41 +66,13 @@ function normalizeComparablePath(path: string): string {
   return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
 
-function defaultChromeUserDataDir(channel: NativeBrowserChannel): string | undefined {
-  if (process.platform === 'darwin') {
-    const base = join(homedir(), 'Library/Application Support/Google');
-    if (channel === 'chrome') return join(base, 'Chrome');
-    if (channel === 'chrome-beta') return join(base, 'Chrome Beta');
-    if (channel === 'chrome-dev') return join(base, 'Chrome Dev');
-    return join(base, 'Chrome Canary');
-  }
-
-  if (process.platform === 'win32') {
-    const base = join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData/Local'), 'Google');
-    if (channel === 'chrome') return join(base, 'Chrome/User Data');
-    if (channel === 'chrome-beta') return join(base, 'Chrome Beta/User Data');
-    if (channel === 'chrome-dev') return join(base, 'Chrome Dev/User Data');
-    return join(base, 'Chrome SxS/User Data');
-  }
-
-  if (process.platform === 'linux') {
-    const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
-    if (channel === 'chrome') return join(base, 'google-chrome');
-    if (channel === 'chrome-beta') return join(base, 'google-chrome-beta');
-    if (channel === 'chrome-dev') return join(base, 'google-chrome-unstable');
-    return join(base, 'google-chrome-unstable');
-  }
-
-  return undefined;
-}
-
 export function nativeDebuggingBlockedByDefaultProfile(profileDir: string, channel: NativeBrowserChannel): boolean {
-  const defaultDir = defaultChromeUserDataDir(channel);
+  const defaultDir = describeNativeBrowserProduct({ channel })?.defaultUserDataDir;
   return defaultDir !== undefined && normalizeComparablePath(profileDir) === normalizeComparablePath(defaultDir);
 }
 
 function defaultProfileCdpBlockedError(channel: NativeBrowserChannel, profileDir: string, profileDirectory?: string): NonNullable<NativeProviderResult['error']> {
-  const app = CHANNEL_APPS[channel].appName;
+  const app = describeNativeBrowserProduct({ channel })?.appName ?? channel;
   return {
     code: 'NATIVE_DEFAULT_PROFILE_CDP_BLOCKED',
     message: `${app} blocks remote debugging against the default Chrome data directory: ${profileDir}${profileDirectory ? ` (${profileDirectory})` : ''}`,
@@ -133,7 +81,7 @@ function defaultProfileCdpBlockedError(channel: NativeBrowserChannel, profileDir
 }
 
 export async function nativeProviderAvailable(): Promise<boolean> {
-  return process.platform === 'darwin' && existsSync(chromeExecutable('chrome'));
+  return discoverNativeBrowserProduct({ channel: 'chrome' }) !== undefined;
 }
 
 function conversationUrl(url: string): string | undefined {
@@ -175,7 +123,7 @@ async function waitForCdp(port: number, timeoutMs: number): Promise<{ webSocketD
     } catch (_error) {
       // Chrome may need a moment to expose the DevTools endpoint.
     }
-    await Bun.sleep(250);
+    await new Promise<void>((resolveSleep) => setTimeout(resolveSleep, 250));
   }
   throw new Error(`Chrome CDP endpoint did not become ready on port ${port}`);
 }
@@ -220,30 +168,22 @@ function connectCdp(webSocketUrl: string): Promise<CdpConnection> {
 }
 
 export function openNativeBrowserPage(channel: NativeBrowserChannel, profileDir: string, url: string, profileDirectory?: string): void {
-  const app = CHANNEL_APPS[channel];
-  if (!existsSync(app.executable)) throw new Error(`${app.appName} is not installed at ${app.executable}`);
+  const product = discoverNativeBrowserProduct({ channel });
+  if (!product) throw new Error(`Browser provider ${channel} is not installed or registered on this host`);
   const args = [
-    '-na',
-    app.appName,
-    '--args',
     ...chromeProfileArgs(profileDir, profileDirectory),
     '--no-first-run',
     '--no-default-browser-check',
     url.startsWith('/') ? pathToFileURL(url).toString() : url,
   ];
-  const result = spawnSync('open', args, { encoding: 'utf-8' });
-  if (result.status !== 0) {
-    throw new Error((result.stderr || result.stdout || `failed to open ${app.appName}`).trim());
-  }
+  const child = spawn(product.executable, args, { detached: true, stdio: 'ignore' });
+  child.once('error', () => undefined);
+  child.unref();
 }
-
 async function launchChrome(channel: NativeBrowserChannel, profileDir: string, port: number, headless: boolean, url = 'about:blank', profileDirectory?: string): Promise<void> {
-  const app = CHANNEL_APPS[channel];
-  if (!existsSync(app.executable)) throw new Error(`${app.appName} is not installed at ${app.executable}`);
+  const product = discoverNativeBrowserProduct({ channel });
+  if (!product) throw new Error(`Browser provider ${channel} is not installed or registered on this host`);
   const args = [
-    '-na',
-    app.appName,
-    '--args',
     `--remote-debugging-port=${port}`,
     '--remote-allow-origins=*',
     ...chromeProfileArgs(profileDir, profileDirectory),
@@ -252,12 +192,13 @@ async function launchChrome(channel: NativeBrowserChannel, profileDir: string, p
     ...(headless ? ['--headless=new'] : []),
     url,
   ];
-  const result = spawnSync('open', args, { encoding: 'utf-8' });
-  if (result.status !== 0) {
-    throw new Error((result.stderr || result.stdout || `failed to open ${app.appName}`).trim());
-  }
+  const child = spawn(product.executable, args, { detached: true, stdio: 'ignore' });
+  await new Promise<void>((resolveLaunch, rejectLaunch) => {
+    child.once('spawn', resolveLaunch);
+    child.once('error', rejectLaunch);
+  });
+  child.unref();
 }
-
 function browserEval(body: string): string {
   return `(() => { try { ${body} } catch (error) { return { ok: false, error: String(error), url: location.href, title: document.title }; } })()`;
 }
@@ -276,7 +217,7 @@ async function waitFor<T>(deadlineMs: number, fn: () => Promise<T>, accept: (val
   while (Date.now() < deadline) {
     const value = await fn();
     if (accept(value)) return value;
-    await Bun.sleep(500);
+    await new Promise<void>((resolveSleep) => setTimeout(resolveSleep, 500));
   }
   return null;
 }
@@ -356,7 +297,7 @@ export async function checkNativeChatgptSession(input: {
       error: {
         code: 'NATIVE_SESSION_CHECK_FAILED',
         message: error instanceof Error ? error.message : String(error),
-        recovery: `Verify Google Chrome is installed for channel "${channel}", close other Chrome windows using this profile, then retry.`,
+        recovery: `Verify a Chromium provider is installed or configure FORGE_BROWSER_EXECUTABLE for channel "${channel}", close other browser windows using this profile, then retry.`,
       },
     };
   } finally {
@@ -417,7 +358,7 @@ async function waitForStableAssistantText(connection: CdpConnection, sessionId:
         return { text, stable: true };
       }
     }
-    await Bun.sleep(500);
+    await new Promise<void>((resolveSleep) => setTimeout(resolveSleep, 500));
   }
   return { text: latest, stable: false };
 }
@@ -539,7 +480,7 @@ export async function runNativeProvider(input: BrowserConsultInput, bundle: Prom
       error: {
         code: 'NATIVE_PROVIDER_FAILED',
         message: error instanceof Error ? error.message : String(error),
-        recovery: `Verify Google Chrome is installed for channel "${channel}", close other Chrome windows using this profile, then retry.`,
+        recovery: `Verify a Chromium provider is installed or configure FORGE_BROWSER_EXECUTABLE for channel "${channel}", close other browser windows using this profile, then retry.`,
       },
     };
   } finally {

package/src/cli/chatgpt-browser/oracle-provider.ts

@@ -3,6 +3,7 @@ import { accessSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, r
 import { tmpdir } from 'os';
 import { isAbsolute, join, resolve } from 'path';
 import type { BrowserConsultInput, BrowserImportedArtifact, PromptBundle } from './types';
+import { discoverExecutable } from '../../runtime/platform/executable-discovery';
 
 export interface OracleProviderResult {
   status: 'completed' | 'recoverable' | 'failed';
@@ -64,7 +65,8 @@ function resolveConfiguredOracleBin(value: string, repoRoot: string): string | u
   if (!hasPathSeparator) {
     const repoRelative = join(repoRoot, value);
     if (existsSync(repoRelative)) return repoRelative;
-    return Bun.which(value) ?? undefined;
+    const discovered = discoverExecutable({ id: 'oracle', candidates: [value] });
+    return discovered.status === 'ready' ? discovered.executable : undefined;
   }
   const candidate = isAbsolute(value) ? value : resolve(repoRoot, value);
   return existsSync(candidate) ? candidate : undefined;
@@ -98,8 +100,8 @@ export function resolveOracleBin(input: Pick<BrowserConsultInput, 'repoRoot' | '
   }
   const repoLocal = join(input.repoRoot, 'node_modules', '.bin', 'oracle');
   if (existsSync(repoLocal)) return { binary: repoLocal, source: 'node_modules/.bin' };
-  const onPath = Bun.which('oracle');
-  if (onPath) return { binary: onPath, source: 'PATH' };
+  const onPath = discoverExecutable({ id: 'oracle', candidates: ['oracle'] });
+  if (onPath.status === 'ready' && onPath.executable) return { binary: onPath.executable, source: 'PATH' };
   return {
     source: 'missing',
     error: {

package/src/cli/chatgpt-browser/types.ts

@@ -26,6 +26,7 @@ export interface BrowserConsultInput {
   model?: string;
   thinking?: ThinkingLevel;
   provider?: BrowserProviderName;
+  dispatchOnly?: boolean;
   chatgptUrl?: string;
   timeoutMs?: number;
   heartbeatSeconds?: number;

package/src/cli/commands/bootstrap-control.ts

@@ -0,0 +1,334 @@
+import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
+import {
+  createBootstrapControlApi,
+  type BootstrapControlApi,
+  type BootstrapAction,
+  resolveBootstrapCapabilityProviders,
+  type BootstrapBlocker,
+  type BootstrapCapabilityProviderResolution,
+  type BootstrapDesiredState,
+  type BootstrapEvaluation,
+  type BootstrapObservation,
+  type BootstrapSnapshot,
+  type BootstrapStep,
+} from '../../runtime/control-plane/bootstrap';
+import {
+  detectSetupPlatform,
+  readSetupProfile,
+  resolveControllerGuidance,
+  resolveRuntimeGuidance,
+  resolveTunnelGuidance,
+  setupNeedsRemoteAccess,
+  type ControllerGuidance,
+  type RuntimeGuidance,
+  type SetupPlatformSnapshot,
+  type SetupProfile,
+  type SetupProfileOptions,
+  type TunnelGuidance,
+} from './setup-profile';
+import { listControllerPluginManifests } from '../../runtime/plugins/store';
+import { officialPluginCatalogItems } from './plugin';
+import { bootstrapWslWindowsBridgeBrowser, observeWslWindowsBridgeBrowser } from '../chatgpt-browser/bridge-provider';
+
+export interface SetupBridgeGuidance {
+  required: boolean;
+  ready: boolean;
+  automatic: boolean;
+  summary: string;
+}
+
+export interface SetupBootstrapDependencies {
+  capabilities(intents: readonly string[], options: { controllerHome: string; platform: SetupPlatformSnapshot }): BootstrapCapabilityProviderResolution[];
+  bridge(profile: SetupProfile | undefined, platform: SetupPlatformSnapshot, options: { controllerHome: string }): SetupBridgeGuidance;
+  controller(profile: SetupProfile | undefined, options: { controllerHome?: string; home?: string }): ControllerGuidance | undefined;
+  runtime(profile: SetupProfile | undefined, options: { controllerHome?: string }): RuntimeGuidance | undefined;
+  tunnel(profile: SetupProfile | undefined, platform: SetupPlatformSnapshot, options: { controllerHome?: string; env?: NodeJS.ProcessEnv }): TunnelGuidance;
+}
+
+export interface SetupBootstrapOptions extends SetupProfileOptions {
+  controllerHome?: string;
+  accountHome?: string;
+  profile?: SetupProfile;
+  platform?: SetupPlatformSnapshot;
+  capabilities?: string[];
+  dependencies?: Partial<SetupBootstrapDependencies>;
+}
+
+function setupBridgeRoot(controllerHome: string): string {
+  return controllerSystemRoot(controllerHome);
+}
+
+const DEFAULT_DEPENDENCIES: SetupBootstrapDependencies = {
+  capabilities: (intents, options) => {
+    if (intents.length === 0) return [];
+    const installedManifests = listControllerPluginManifests(options.controllerHome, { preferStored: true });
+    const catalog = officialPluginCatalogItems(options.platform.platform);
+    return resolveBootstrapCapabilityProviders({ capabilityIntents: intents, installedManifests, catalog });
+  },
+  bridge: (profile, platform, options) => {
+    if (!profile?.controllers.includes('chatgpt') || platform.environment !== 'wsl2') {
+      return { required: false, ready: true, automatic: false, summary: 'Windows ChatGPT bridge browser is not required for this setup.' };
+    }
+    const bridgeRoot = setupBridgeRoot(options.controllerHome);
+    const readiness = observeWslWindowsBridgeBrowser(bridgeRoot, { platform: 'linux', wslDistroName: 'ForgeSetup' });
+    return { required: readiness.required, ready: readiness.ready, automatic: readiness.automatic, summary: readiness.summary };
+  },
+  controller: resolveControllerGuidance,
+  runtime: resolveRuntimeGuidance,
+  tunnel: resolveTunnelGuidance,
+};
+
+function desiredState(profile: SetupProfile | undefined, capabilities: readonly string[] = []): BootstrapDesiredState {
+  const primaryController = profile?.primaryController ?? 'chatgpt';
+  const controllers = profile?.controllers ?? [primaryController];
+  const remote = setupNeedsRemoteAccess(profile ?? { schemaVersion: 1, primaryController, controllers, tunnel: { provider: 'auto' }, createdAt: '', updatedAt: '' });
+  const provider = profile?.tunnel.provider ?? 'auto';
+  const preferredTransport = !remote || provider === 'none'
+    ? 'none'
+    : provider === 'openai' || provider === 'auto'
+      ? 'openai-secure-tunnel'
+      : 'https-endpoint';
+  return {
+    schemaVersion: 1,
+    primaryController,
+    controllers,
+    connectivity: {
+      mode: remote ? 'remote' : 'local',
+      preferredTransport,
+      ...(profile?.tunnel.endpoint ? { endpoint: profile.tunnel.endpoint } : {}),
+      ...(profile?.tunnel.tunnelId ? { tunnelId: profile.tunnel.tunnelId } : {}),
+    },
+    capabilityIntents: [...new Set([...(profile?.capabilityIntents ?? []), ...capabilities])],
+  };
+}
+
+function actionFromGuidance(input: {
+  id: string;
+  kind: BootstrapAction['kind'];
+  title: string;
+  detail: string;
+  command?: string;
+  owner?: BootstrapAction['owner'];
+}): BootstrapAction {
+  return {
+    id: input.id,
+    kind: input.kind,
+    owner: input.owner ?? 'forge',
+    summary: `${input.title}: ${input.detail}`,
+    ...(input.command ? { command: input.command } : {}),
+    verification: 'forge setup next',
+  };
+}
+
+function blockerFor(stepId: string, code: string, action: BootstrapAction, summary: string): BootstrapBlocker {
+  return {
+    code,
+    kind: action.owner === 'user' ? 'user_action' : 'automatic_retry',
+    stepId,
+    summary,
+    actionIds: [action.id],
+  };
+}
+
+function step(input: {
+  id: string;
+  label: string;
+  state: BootstrapStep['state'];
+  dependsOn?: string[];
+  observation?: BootstrapObservation;
+  blocker?: BootstrapBlocker;
+  action?: BootstrapAction;
+}): BootstrapStep {
+  return {
+    id: input.id,
+    label: input.label,
+    state: input.state,
+    dependsOn: input.dependsOn ?? [],
+    observationIds: input.observation ? [input.observation.id] : [],
+    blockerCodes: input.blocker ? [input.blocker.code] : [],
+    actionIds: input.action ? [input.action.id] : [],
+  };
+}
+
+function userOwnsTunnelGuidance(guidance: TunnelGuidance): boolean {
+  return guidance.title === 'Create an OpenAI Secure MCP Tunnel'
+    || guidance.title === 'Install OpenAI tunnel-client'
+    || guidance.title === 'Record existing HTTPS endpoint'
+    || guidance.title === 'Create a stable Cloudflare Tunnel'
+    || guidance.title === 'Install Cloudflare Tunnel'
+    || guidance.title === 'Install Tailscale';
+}
+
+export function observeSetupBootstrap(options: SetupBootstrapOptions = {}): BootstrapEvaluation {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const profile = options.profile ?? readSetupProfile(options);
+  const platform = options.platform ?? detectSetupPlatform({ env: options.env });
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...options.dependencies };
+  const observedAt = (options.now ?? (() => new Date()))().toISOString();
+  const observations: BootstrapObservation[] = [];
+  const actions: BootstrapAction[] = [];
+  const blockers: BootstrapBlocker[] = [];
+  const steps: BootstrapStep[] = [];
+
+  const profileObservation: BootstrapObservation = profile
+    ? { id: 'setup.profile', component: 'platform', status: 'ready', summary: `Setup profile selects ${profile.primaryController} as primary controller.`, observedAt }
+    : { id: 'setup.profile', component: 'platform', status: 'missing', summary: 'No Forge setup profile is configured yet.', reasonCodes: ['SETUP_PROFILE_MISSING'], observedAt };
+  observations.push(profileObservation);
+  if (!profile) {
+    const action = actionFromGuidance({ id: 'controller.select', kind: 'configure', title: 'Configure Forge controller', detail: 'Create the instance-level setup profile.', command: 'forge setup configure --controller chatgpt' });
+    const blocker = blockerFor('profile', 'BOOTSTRAP_SETUP_PROFILE_MISSING', action, profileObservation.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: 'profile', label: 'Desired setup profile', state: 'blocked', observation: profileObservation, blocker, action }));
+  } else {
+    steps.push(step({ id: 'profile', label: 'Desired setup profile', state: 'ready', observation: profileObservation }));
+  }
+
+  const controllerGuidance = profile ? dependencies.controller(profile, { controllerHome, home: options.accountHome }) : undefined;
+  const controllerObservation: BootstrapObservation = !profile
+    ? { id: 'controller.primary', component: 'controller', status: 'unknown', summary: 'Controller readiness waits for setup profile selection.', observedAt }
+    : controllerGuidance && !controllerGuidance.ready
+      ? { id: 'controller.primary', component: 'controller', status: 'blocked', summary: `${controllerGuidance.title}: ${controllerGuidance.detail}`, provider: controllerGuidance.controller, reasonCodes: ['CONTROLLER_NOT_READY'], observedAt }
+      : { id: 'controller.primary', component: 'controller', status: 'ready', summary: 'Configured controller set is ready.', observedAt };
+  observations.push(controllerObservation);
+  if (!profile) {
+    steps.push(step({ id: 'controller', label: 'Controller connectivity', state: 'pending', dependsOn: ['profile'], observation: controllerObservation }));
+  } else if (controllerGuidance && !controllerGuidance.ready) {
+    const owner: BootstrapAction['owner'] = controllerGuidance.command ? 'forge' : 'user';
+    const action = actionFromGuidance({ id: `controller.${controllerGuidance.controller}.configure`, kind: controllerGuidance.command ? 'configure' : 'authenticate', title: controllerGuidance.title, detail: controllerGuidance.detail, command: controllerGuidance.command, owner });
+    const blocker = blockerFor('controller', `BOOTSTRAP_CONTROLLER_${controllerGuidance.controller.toUpperCase()}_NOT_READY`, action, controllerObservation.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: 'controller', label: 'Controller connectivity', state: 'blocked', dependsOn: ['profile'], observation: controllerObservation, blocker, action }));
+  } else {
+    steps.push(step({ id: 'controller', label: 'Controller connectivity', state: 'ready', dependsOn: ['profile'], observation: controllerObservation }));
+  }
+
+  const runtimeGuidance = profile ? dependencies.runtime(profile, { controllerHome }) : undefined;
+  const runtimeRequired = Boolean(profile && setupNeedsRemoteAccess(profile));
+  const runtimeObservation: BootstrapObservation = !profile
+    ? { id: 'runtime.package', component: 'runtime', status: 'unknown', summary: 'Runtime readiness waits for setup profile selection.', observedAt }
+    : !runtimeRequired
+      ? { id: 'runtime.package', component: 'runtime', status: 'ready', summary: 'Packaged Runtime is not required by the configured local-only controller set.', observedAt }
+      : runtimeGuidance?.ready
+        ? { id: 'runtime.package', component: 'runtime', status: 'ready', summary: runtimeGuidance.detail, observedAt }
+        : { id: 'runtime.package', component: 'runtime', status: 'blocked', summary: runtimeGuidance ? `${runtimeGuidance.title}: ${runtimeGuidance.detail}` : 'Packaged Runtime is not ready.', reasonCodes: ['RUNTIME_NOT_READY'], observedAt };
+  observations.push(runtimeObservation);
+  if (!profile) {
+    steps.push(step({ id: 'runtime', label: 'Packaged Runtime', state: 'pending', dependsOn: ['controller'], observation: runtimeObservation }));
+  } else if (!runtimeRequired || runtimeGuidance?.ready) {
+    steps.push(step({ id: 'runtime', label: 'Packaged Runtime', state: runtimeRequired ? 'ready' : 'skipped', dependsOn: ['controller'], observation: runtimeObservation }));
+  } else {
+    const action = actionFromGuidance({ id: 'runtime.package.install', kind: 'repair', title: runtimeGuidance?.title ?? 'Repair packaged Runtime', detail: runtimeGuidance?.detail ?? 'Install or repair the packaged Runtime.', command: runtimeGuidance?.command });
+    const blocker = blockerFor('runtime', 'BOOTSTRAP_RUNTIME_NOT_READY', action, runtimeObservation.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: 'runtime', label: 'Packaged Runtime', state: 'blocked', dependsOn: ['controller'], observation: runtimeObservation, blocker, action }));
+  }
+
+  const tunnelGuidance = profile ? dependencies.tunnel(profile, platform, { controllerHome, env: options.env }) : undefined;
+  const connectivityObservation: BootstrapObservation = !profile
+    ? { id: 'connectivity.controller', component: 'connectivity', status: 'unknown', summary: 'Connectivity policy waits for setup profile selection.', observedAt }
+    : tunnelGuidance?.ready
+      ? { id: 'connectivity.controller', component: 'connectivity', status: 'ready', summary: tunnelGuidance.detail, provider: tunnelGuidance.provider, endpoint: profile.tunnel.endpoint, observedAt }
+      : { id: 'connectivity.controller', component: 'connectivity', status: 'blocked', summary: tunnelGuidance ? `${tunnelGuidance.title}: ${tunnelGuidance.detail}` : 'Controller connectivity is not ready.', provider: tunnelGuidance?.provider, reasonCodes: ['CONNECTIVITY_NOT_READY'], observedAt };
+  observations.push(connectivityObservation);
+  if (!profile) {
+    steps.push(step({ id: 'connectivity', label: 'Controller transport', state: 'pending', dependsOn: ['runtime'], observation: connectivityObservation }));
+  } else if (tunnelGuidance?.ready) {
+    steps.push(step({ id: 'connectivity', label: 'Controller transport', state: setupNeedsRemoteAccess(profile) ? 'ready' : 'skipped', dependsOn: ['runtime'], observation: connectivityObservation }));
+  } else {
+    const userOwned = tunnelGuidance ? userOwnsTunnelGuidance(tunnelGuidance) : true;
+    const action = actionFromGuidance({ id: `tunnel.${tunnelGuidance?.provider ?? 'unknown'}.configure`, kind: userOwned ? 'authenticate' : 'reconnect', title: tunnelGuidance?.title ?? 'Configure controller transport', detail: tunnelGuidance?.detail ?? 'Configure controller transport.', command: tunnelGuidance?.command, owner: userOwned ? 'user' : 'forge' });
+    const blocker = blockerFor('connectivity', `BOOTSTRAP_CONNECTIVITY_${(tunnelGuidance?.provider ?? 'UNKNOWN').toUpperCase().replaceAll('-', '_')}_NOT_READY`, action, connectivityObservation.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: 'connectivity', label: 'Controller transport', state: 'blocked', dependsOn: ['runtime'], observation: connectivityObservation, blocker, action }));
+  }
+
+  const bridgeGuidance = dependencies.bridge(profile, platform, { controllerHome });
+  const bridgeObservation: BootstrapObservation = !bridgeGuidance.required
+    ? { id: 'provider.chatgpt.wsl-bridge', component: 'provider', status: 'ready', summary: bridgeGuidance.summary, observedAt }
+    : bridgeGuidance.ready
+      ? { id: 'provider.chatgpt.wsl-bridge', component: 'provider', status: 'ready', summary: bridgeGuidance.summary, provider: 'controlled-windows-chromium', observedAt }
+      : { id: 'provider.chatgpt.wsl-bridge', component: 'provider', status: 'missing', summary: bridgeGuidance.summary, provider: 'controlled-windows-chromium', reasonCodes: ['CHATGPT_WSL_BRIDGE_BROWSER_NOT_READY'], observedAt };
+  observations.push(bridgeObservation);
+  if (!bridgeGuidance.required) {
+    steps.push(step({ id: 'chatgpt-wsl-bridge', label: 'WSL ChatGPT bridge browser', state: 'skipped', dependsOn: ['connectivity'], observation: bridgeObservation }));
+  } else if (bridgeGuidance.ready) {
+    steps.push(step({ id: 'chatgpt-wsl-bridge', label: 'WSL ChatGPT bridge browser', state: 'ready', dependsOn: ['connectivity'], observation: bridgeObservation }));
+  } else {
+    const action: BootstrapAction = bridgeGuidance.automatic
+      ? { id: 'chatgpt.bridge.bootstrap', kind: 'install', owner: 'forge', summary: bridgeGuidance.summary, command: 'forge setup bridge-browser', verification: 'forge setup next' }
+      : { id: 'chatgpt.bridge.user-action', kind: 'install', owner: 'user', summary: bridgeGuidance.summary, verification: 'forge setup next' };
+    const blocker = blockerFor('chatgpt-wsl-bridge', 'BOOTSTRAP_CHATGPT_WSL_BRIDGE_BROWSER_NOT_READY', action, bridgeGuidance.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: 'chatgpt-wsl-bridge', label: 'WSL ChatGPT bridge browser', state: 'blocked', dependsOn: ['connectivity'], observation: bridgeObservation, blocker, action }));
+  }
+
+  const desired = desiredState(profile, options.capabilities);
+  for (const resolution of dependencies.capabilities(desired.capabilityIntents, { controllerHome, platform })) {
+    const safeCapabilityId = resolution.capabilityId.replace(/[^a-zA-Z0-9_.-]+/g, '-');
+    const observation: BootstrapObservation = {
+      id: `capability.${safeCapabilityId}`,
+      component: 'plugin',
+      status: resolution.status === 'ready' ? 'ready' : resolution.status === 'unsupported' ? 'unsupported' : 'degraded',
+      summary: resolution.summary,
+      ...(resolution.providerId ? { provider: resolution.providerId } : {}),
+      ...(resolution.status === 'ready' ? {} : { reasonCodes: [`CAPABILITY_${resolution.status.toUpperCase()}`] }),
+      observedAt,
+    };
+    observations.push(observation);
+    const stepId = `capability.${safeCapabilityId}`;
+    if (resolution.status === 'ready') {
+      steps.push(step({ id: stepId, label: `Capability ${resolution.capabilityId}`, state: 'ready', dependsOn: ['connectivity'], observation }));
+      continue;
+    }
+    if (resolution.status === 'unsupported' || !resolution.providerId) {
+      const blocker: BootstrapBlocker = {
+        code: `BOOTSTRAP_CAPABILITY_${safeCapabilityId.toUpperCase().replaceAll('.', '_').replaceAll('-', '_')}_UNSUPPORTED`,
+        kind: 'unsupported',
+        stepId,
+        summary: resolution.summary,
+        actionIds: [],
+      };
+      blockers.push(blocker);
+      steps.push(step({ id: stepId, label: `Capability ${resolution.capabilityId}`, state: 'blocked', dependsOn: ['connectivity'], observation, blocker }));
+      continue;
+    }
+    const action: BootstrapAction = {
+      id: `capability.${safeCapabilityId}.${resolution.status === 'installable' ? 'install' : 'repair'}`,
+      kind: resolution.status === 'installable' ? 'install' : 'repair',
+      owner: 'forge',
+      summary: `${resolution.status === 'installable' ? 'Install' : 'Repair'} ${resolution.providerName ?? resolution.providerId} for ${resolution.capabilityId}.`,
+      command: `forge plugin install ${resolution.providerId} --controller-home ${JSON.stringify(controllerHome)}`,
+      verification: 'forge setup next',
+    };
+    const blocker = blockerFor(stepId, `BOOTSTRAP_CAPABILITY_${safeCapabilityId.toUpperCase().replaceAll('.', '_').replaceAll('-', '_')}_${resolution.status.toUpperCase()}`, action, resolution.summary);
+    actions.push(action); blockers.push(blocker);
+    steps.push(step({ id: stepId, label: `Capability ${resolution.capabilityId}`, state: 'blocked', dependsOn: ['connectivity'], observation, blocker, action }));
+  }
+
+  return { desired, observations, steps, blockers, actions };
+}
+
+export function createSetupBootstrapControlApi(options: SetupBootstrapOptions = {}): BootstrapControlApi {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const observe = (): BootstrapEvaluation => observeSetupBootstrap({ ...options, controllerHome });
+  return createBootstrapControlApi({
+    controllerHome,
+    now: options.now,
+    adapter: {
+      observe,
+      observeSync: observe,
+      perform: async (action) => {
+        if (action.id !== 'chatgpt.bridge.bootstrap') throw new Error(`BOOTSTRAP_ACTION_EXECUTOR_UNSUPPORTED: ${action.id}`);
+        const platform = options.platform ?? detectSetupPlatform({ env: options.env });
+        if (platform.environment !== 'wsl2') throw new Error('CHATGPT_BRIDGE_BOOTSTRAP_WSL_REQUIRED');
+        const bridgeRoot = setupBridgeRoot(controllerHome);
+        if (!bridgeRoot) throw new Error('CHATGPT_CONTROLLER_BROWSER_ROOT_UNAVAILABLE');
+        await bootstrapWslWindowsBridgeBrowser(bridgeRoot, { platform: 'linux', wslDistroName: 'ForgeSetup' });
+      },
+    },
+  });
+}
+
+export function refreshSetupBootstrap(options: SetupBootstrapOptions = {}): BootstrapSnapshot {
+  return createSetupBootstrapControlApi(options).refreshSync();
+}

package/src/cli/commands/brain-assistant.ts

@@ -0,0 +1,38 @@
+import { readFileSync, statSync } from 'fs';
+import type { Command } from 'commander';
+import { recordExperience, retractExperience, supersedeExperience, type ExperienceDraft } from '../../../packages/kernel/memory/api/index';
+import { controllerExperienceStore } from '../../runtime/control-plane/persistence/experience-store';
+import { prepareAssistantWorkContext } from '../../runtime/context/assistant-work-context';
+
+function readBoundedJson(path: string): unknown {
+  if (statSync(path).size > 16 * 1024) throw new Error('BRAIN_INPUT_TOO_LARGE');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** Thin CLI over the same APIs used by Controller rounds. No independent memory writer. */
+export function addBrainAssistantCommands(brain: Command): void {
+  brain.command('recall').description('Resolve registered project knowledge and retained experience for an existing Work')
+    .requiredOption('--controller-home <path>').requiredOption('--repo-id <id>').requiredOption('--work-id <id>')
+    .option('--query <text>').option('--channel <id>').option('--account <id>').option('--locale <id>')
+    .action((options: { controllerHome: string; repoId: string; workId: string; query?: string; channel?: string; account?: string; locale?: string }) => {
+      console.log(JSON.stringify(prepareAssistantWorkContext({ ...options, applicability: { channel: options.channel, account: options.account, locale: options.locale } }) ?? { status: 'project_contract_missing' }, null, 2));
+    });
+  const experience = brain.command('experience').description('Submit or withdraw Controller-authored, evidence-backed experience');
+  for (const operation of ['record', 'supersede', 'retract'] as const) {
+    experience.command(operation)
+      .requiredOption('--controller-home <path>').requiredOption('--repo-id <id>').requiredOption('--work-id <id>')
+      .requiredOption('--controller-id <id>').requiredOption('--authority-env <name>', 'Environment variable containing the current Controller capability')
+      .requiredOption('--input <path>', 'Bounded JSON API input; never include the Controller capability')
+      .action((options: { controllerHome: string; repoId: string; workId: string; controllerId: string; authorityEnv: string; input: string }) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(options.authorityEnv)) throw new Error('BRAIN_AUTHORITY_ENV_INVALID');
+        const authorityId = process.env[options.authorityEnv];
+        if (!authorityId) throw new Error('BRAIN_CONTROLLER_AUTHORITY_REQUIRED');
+        const store = controllerExperienceStore({ ...options, identity: { workId: options.workId, controllerId: options.controllerId, authorityId } });
+        const data = readBoundedJson(options.input);
+        const result = operation === 'record' ? recordExperience(store, data as ExperienceDraft)
+          : operation === 'supersede' ? supersedeExperience(store, data as Parameters<typeof supersedeExperience>[1])
+            : retractExperience(store, data as Parameters<typeof retractExperience>[1]);
+        console.log(JSON.stringify(result, null, 2));
+      });
+  }
+}