@moretea-labs/forge 1.5.0-rc.1 → 1.5.0

package/src/cli/mcp/setup.ts

@@ -1,6 +1,8 @@
+import { spawnSync } from "child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { isIP } from "net";
-import { dirname, join, relative } from "path";
+import { homedir } from "os";
+import { dirname, join, relative, resolve } from "path";
 import {
   ensureMcpControllerHomeBearerToken,
   ensureMcpControllerHomeOAuthPassphrase,
@@ -18,7 +20,6 @@ import { resolveMcpRepoRoot } from "./repo";
 import {
   FORGE_TOOL_SURFACE,
   DEFAULT_AGENT_TIMEOUT_MS,
-  defaultLocalAgentRunners,
   MAX_AGENT_TIMEOUT_MS,
 } from "../controller/runtime-config";
 import { ensureControllerHome, ensureRepoPreferredControllerHome } from "../repositories/controller-home";
@@ -35,7 +36,7 @@ export interface McpSetupResult {
 const REQUIRED_CODEX_TOOLS = [
   "harness_status",
   "read_workflow_file",
-  "latest_handoff",
+  "latest_session_context",
   "latest_checks",
   "prepare_codex_goal_from_sprint",
   "write_codex_goal",
@@ -184,265 +185,140 @@ function normalizeChatgptMcpServerName(value: string | undefined): string {
 export function chatgptGuideMarkdown(
   endpoint = CHATGPT_MCP_ENDPOINT_PLACEHOLDER,
 ): string {
-  return `# forge ChatGPT Controller Setup
+  return `# Forge ChatGPT Controller — Low-level Reference
 
-## Purpose
+> For normal onboarding, start with \`forge setup\` and [Tutorial 2](tutorials/02-connect-chatgpt.md). This file is the lower-level MCP reference and may also be regenerated by repository-scoped compatibility setup.
 
-The \`controller\` profile makes ChatGPT the project control plane. ChatGPT can inspect code and documents, maintain durable Issues and dependency-aware Tasks, apply bounded direct edits, publish Issues to GitHub Projects, dispatch short local Codex/Claude runs or visible GitHub Copilot cloud sessions, and review the resulting state. Repository files remain the source of truth; chat history is not required for recovery.
+## Product model
 
-## Prerequisites
+Forge has no internal AI brain. ChatGPT is one external controller option: ChatGPT decides semantic next steps, while Forge owns bounded execution, durable state, authorization, Runtime lifecycle, and evidence. Codex/Claude are optional and are not enabled merely because they are installed.
 
-- A forge adopted repository.
-- Bun and the \`forge\` CLI on PATH.
-- Codex and/or Claude CLI installed for delegated local execution.
-- GitHub CLI \`gh\` authenticated when GitHub Issues, Projects, or Copilot cloud sessions are used.
-- ChatGPT workspace access to Developer Mode and custom MCP Connectors.
-- A public HTTPS \`/mcp\` endpoint for ChatGPT.
+## Normal package path
 
-For a shared editable installation, keep the forge checkout at a stable path such as \`~/DevProjects/forge\`, run \`bun install\`, and reinstall the CLI after pulling updates.
-
-## One-time setup
-
-\`\`\`bash
-forge mcp setup chatgpt --repo .
-forge runtime service install \
-  --controller-home <absolute-controller-home> \
-  --repo <absolute-repo-root> \
-  --host 127.0.0.1 \
-  --port 8765
-\`\`\`
-
-The \`controller\` profile writes the service-level MCP configuration consumed by the single \`forge-runtime\`. The macOS launchd service starts and restarts that one root process; Gateway, Controller Services, Scheduler, and MCP Transport share the same Runtime lifecycle owner. There is no MCP KeepAlive wrapper or component-level lifecycle command.
-
-The Runtime endpoint is loopback-only at \`http://127.0.0.1:8765/\`. The local visual controller surface is part of the same Runtime configuration; do not expose it directly.
-
-Health check:
+A repository is not required for the user-level ChatGPT connection:
 
 \`\`\`bash
-curl http://127.0.0.1:8765/ready
-forge runtime status --controller-home <absolute-controller-home>
-forge mcp doctor --repo .
+forge setup configure --controller chatgpt --tunnel auto
+forge setup next
 \`\`\`
 
-For a fixed Cloudflare domain, verify both local and public discovery without leaking tokens:
+The corresponding low-level commands are:
 
 \`\`\`bash
-curl http://127.0.0.1:8765/ready
-curl https://${CHATGPT_NAMED_TUNNEL_HOST_PLACEHOLDER}/.well-known/oauth-protected-resource/mcp
-env | grep -Ei 'proxy|no_proxy'
-HTTPS_PROXY= HTTP_PROXY= ALL_PROXY= curl -v https://${CHATGPT_NAMED_TUNNEL_HOST_PLACEHOLDER}/mcp
+forge mcp setup chatgpt --user-level
+forge runtime service install-package
+forge runtime status --json
 \`\`\`
 
-If a local HTTP proxy interferes with endpoint checks, add the fixed domain, \`*.trycloudflare.com\`, \`*.ts.net\`, and \`100.64.0.0/10\` to \`NO_PROXY\` instead of disabling proxies globally.
-
-The controller profile stores service-level MCP config under \`controllerHome/mcp/mcp.local.json\`, including allowed local agents, timeout, endpoint, and \`chatgpt.serverName\`. OAuth credentials live in \`controllerHome/mcp/mcp.oauth.json\`; the bearer fallback lives in \`controllerHome/mcp/mcp.tokens.json\`. Existing repo-local \`.forge/mcp.*\` files remain a legacy fallback.
+The Package Runtime does not require a Forge Git checkout, Bun compilation, CodeGraph, or Standalone Recovery. The older \`forge runtime service install --repo ...\` command is an advanced source/immutable-release path.
 
-Repository-specific MCP access rules may be added in \`.forge/mcp.policy.json\`. Repository policy can narrow access, but immutable secret, credential, Git-internal, and build-output denies remain enforced.
+## Local boundaries
 
-## Stable endpoint
-
-Use this Connector URL:
+Forge MCP remains loopback-only, normally at:
 
 \`\`\`text
-${endpoint}
+http://127.0.0.1:8765/mcp
 \`\`\`
 
-Quick tunnels are useful for one-off smoke tests, but their URL may change. For routine use, prefer a fixed Cloudflare domain. Forge never owns the tunnel process: publish the loopback Runtime endpoint through your own stable HTTPS tunnel. With Cloudflare, create and route a named tunnel:
+The local Utility Console uses a separate loopback port (normally 8766). Never expose the Utility Console to the internet.
 
-\`\`\`bash
-cloudflared tunnel login
-cloudflared tunnel create forge-mcp
-cloudflared tunnel route dns forge-mcp ${CHATGPT_NAMED_TUNNEL_HOST_PLACEHOLDER}
-cloudflared tunnel run forge-mcp
-\`\`\`
+Service-level MCP configuration lives below \`Controller Home/mcp/\`. OAuth credentials and bearer fallback tokens are local secrets and must not be pasted into chat or committed. Repository-specific \`.forge/mcp.policy.json\` can narrow access when a repository is later adopted.
 
-Keep forge on the fixed public origin without owning the tunnel process:
+## Remote controller connection
 
-\`\`\`bash
-forge mcp setup chatgpt --repo . --endpoint https://${CHATGPT_NAMED_TUNNEL_HOST_PLACEHOLDER}/mcp
-forge runtime service install --controller-home <absolute-controller-home> --repo <absolute-repo-root> --host 127.0.0.1 --port 8765
-\`\`\`
+The setup profile owns the connection choice. Supported paths are:
 
-Regenerate this guide with the stable endpoint:
+1. **OpenAI Secure MCP Tunnel** — preferred when the OpenAI organization/workspace has tunnel permission; no public inbound Forge endpoint is required. Forge stores only the non-secret \`tunnel_id\`. The runtime API key remains an \`env:\`/file reference owned by the official \`tunnel-client\`.
+2. **Cloudflare Tunnel** — stable public/internet-reachable HTTPS endpoint.
+3. **Tailscale Funnel** — HTTPS endpoint for compatible Tailscale environments.
+4. **Existing HTTPS** — user-managed reverse proxy/tunnel ending in \`/mcp\`.
+5. **None** — local setup only; remote connectivity can be configured later.
 
-\`\`\`bash
-forge mcp setup chatgpt --repo . --endpoint <https-url>/mcp
-\`\`\`
-
-The real endpoint stays in ignored local config; the tracked guide stays placeholder-only. The OAuth discovery endpoint includes \`oauth-protected-resource\` metadata.
-
-## Create the ChatGPT Connector
-
-1. Open ChatGPT Settings and enable Developer Mode.
-2. Create a custom Connector using the server name from \`controllerHome/mcp/mcp.local.json\` under \`chatgpt.serverName\`.
-3. Paste the public HTTPS URL ending in \`/mcp\`.
-4. Configure Connector authentication as OAuth. ChatGPT must use the \`/mcp\` OAuth URL; do not point ChatGPT at \`/mcp-bearer\`.
-5. Scan tools and authorize with the passphrase from \`controllerHome/mcp/mcp.oauth.json\`.
-6. Keep write confirmations enabled.
-7. Re-scan tools after updating forge tool schemas.
-
-### Grok and other OAuth MCP clients
-
-Current Grok custom connectors support OAuth dynamic client registration + PKCE. Use the same canonical endpoint as ChatGPT:
-
-\`\`\`text
-<https-tunnel-url>/mcp
-\`\`\`
-
-Do not use the legacy \/mcp-grok route for new connectors. Grok's current OAuth callback is \/connectors-oauth-exchange-code\/ on grok.com; forge accepts that callback through dynamic registration or its public-client fallback.
-
-### Non-OAuth MCP clients
+For OpenAI Secure MCP Tunnel, setup uses the official supervised runtime surface and considers it ready only when \`tunnel-client runtimes status forge --json\` reports the runtime running, healthy, and ready.
 
-Clients that cannot complete OAuth dynamic client registration + PKCE should use the dedicated bearer endpoint instead of \`/mcp\` or \`/authorize\`:
+For public HTTPS paths, the configured connector URL is:
 
 \`\`\`text
-<https-tunnel-url>/mcp-bearer
+${endpoint}
 \`\`\`
 
-Authenticate with \`Authorization: Bearer <token>\` using the token stored under \`controllerHome/mcp/mcp.tokens.json\` (or \`FORGE_MCP_TOKEN\`). Do not paste the raw token into chat or docs. \`/health\` advertises both \`mcpEndpoint\` and \`bearerEndpoint\`. Incomplete OAuth hits on \`/authorize\` return HTTP 400 and point clients to \`/mcp-bearer\`.
-
-## Verify the loaded tool surface
-
-Default \`--toolset core\` and \`--toolset advanced\` expose the same bounded 20-tool ChatGPT surface: the five \`rh_*\` facades (with code retrieval routed through \`rh_context.search\`) plus repository selection, \`repository_command_execute\`, exact source read, safe patch, \`run_check\`, one typed \`plugin_action_execute\` dispatcher (action schemas via \`rh_context\`), managed process lifecycle, result retrieval, and approval resolution. Use \`--toolset full\` for exhaustive legacy compatibility, which keeps every atomic handler (including Git) registered. Confirm all five \`rh_*\` tools appear after connect. If only legacy planning tools are visible, refresh or recreate the Connector so ChatGPT reloads the MCP tool schema.
-
-## Refresh newly added repository tools
-
-For the current repository only, prefer a bounded local restart:
+Record a stable endpoint with:
 
 \`\`\`bash
-launchctl kickstart -k gui/$(id -u)/com.moretea.forge.runtime.<controller-home-suffix>
+forge setup configure --controller chatgpt --tunnel existing --endpoint https://forge.example.com/mcp
 \`\`\`
 
-The launchd label is printed by \`forge runtime service install\` (it is \`com.moretea.forge.runtime.<controller-home-suffix>\`). The single Runtime restart also refreshes repository tools. There is no per-repository rollout or component restart surface.
+Forge synchronizes an explicitly recorded endpoint into the user-level ChatGPT MCP configuration. A configured URL is not proof of live end-to-end connectivity; verify from ChatGPT with a real tool call.
 
-After the restart, rescan or recreate the ChatGPT Connector, then call \`controller_capabilities\` again and verify \`expectedTools\` still includes \`repository_latest_source_diagnose\` and \`repository_bootstrap_local_project\`.
+## ChatGPT-side setup
 
-## Daily workflow
+ChatGPT developer-mode/MCP availability is controlled by the current ChatGPT plan and workspace policy. Follow OpenAI's current developer-mode documentation; Forge cannot bypass plan, administrator, RBAC, or tool-action restrictions.
 
-Start a new ChatGPT conversation with:
+- With **Secure MCP Tunnel**, create the ChatGPT app/connector using the Tunnel connection and the tunnel ID.
+- With **HTTPS**, use the stable URL ending in \`/mcp\` and Forge's OAuth flow.
+- Refresh/scan tools after Forge tool definitions change.
 
-\`\`\`text
-Use forge as the project controller. Read project_snapshot, current Issues, active Runs, and relevant code before deciding the next action. Keep work in small dependency-aware Tasks. Do not dispatch one large Issue as one agent run.
-\`\`\`
-
-Typical requests:
-
-\`\`\`text
-Analyze this requirement and the current implementation. Create or update an Issue and split it into executable Tasks. Do not execute yet.
-\`\`\`
+The bounded default surface intentionally exposes the preferred \`rh_*\` facade plus repository/source/check/process/plugin escape hatches. Do not switch to exhaustive compatibility mode merely to see more tool names.
 
-\`\`\`text
-Inspect readiness for this Issue, publish it to GitHub when collaboration is useful, and launch at most two independent Tasks. Review every local diff or GitHub pull request and record verification evidence before accepting it.
-\`\`\`
+## Verify
 
-\`\`\`text
-Read the project board and failed Runs. Retry only the smallest failed Task, or re-plan the Issue when the original split is wrong.
-\`\`\`
+Local Runtime:
 
-\`\`\`text
-This is a small local fix. Open a bounded edit session, modify only the named files, inspect the Git diff, run focused checks, and finalize or rollback the edit.
+\`\`\`bash
+forge runtime status --json
+forge mcp doctor
 \`\`\`
 
-## Persistent model
+Then verify from the selected external controller:
 
 \`\`\`text
-Issue
-  -> Task T1
-       -> Run 1
-       -> Run 2 (retry)
-  -> Task T2
-  -> Task T3
-\`\`\`
-
-- Issues and Tasks are stored under \`tasks/issues/\` as JSON plus readable Markdown.
-- Agent jobs, logs, edit backups, and worktrees are stored under ignored \`.ai/harness/\` runtime directories.
-- A completed isolated agent Run moves its Task to review. ChatGPT must inspect it with \`get_task_diff\`, integrate it with \`integrate_task_run\`, record named-check and criterion evidence through \`verify_task\`, then explicitly accept it or request changes.
-- Dependency completion unlocks later Tasks automatically.
-- Any new ChatGPT conversation can recover state through \`project_snapshot\` and \`get_project_board\`.
-
-## Capability boundaries
-
-- \`observe\`: inspect repository state, search code, and read bounded file ranges.
-- \`manage\`: create Issues, dynamically split Tasks, inspect launch readiness, publish to GitHub Issues/Projects, update status, and maintain project documents.
-- \`edit\`: use a bounded edit session with allowed paths, SHA preconditions, change limits, backups, and rollback.
-- \`execute\`: dispatch a ready Task to an allowed local agent in an isolated worktree or to a visible GitHub Copilot cloud session.
-- Protected operations such as secrets, Git internals, package lockfiles, CI workflow changes, commits, merges, and pushes are not default controller actions.
-
-Kernel-managed Agent goals and persistent Task Runs are retired. New work uses
-\`rh_work\` to create or continue a WorkContract, \`rh_work.controller_claim\` to
-establish ownership, and \`rh_work.launcher_start\` to begin an external
-SuperController session.
-
-## Dev Mode Agent Runner
-
-Local Agent execution is opt-in. GitHub cloud sessions use authenticated \`gh\` and do not require the local dev runner:
-
-The runner is enabled through the service-level MCP configuration written by \`forge mcp setup chatgpt\` (\`devMode.agentRunner\` and \`devMode.allowedAgents\`). It executes inside the single Forge Runtime's bounded worker processes; there is no separate \`forge mcp serve\` lifecycle to supervise.
-
-The runner defaults to 60 minutes per local Task and supports explicit values up to 12 hours. Requested values are validated and persisted unchanged; an invalid value fails instead of silently falling back to 120 seconds.
-
-The runner:
-
-- accepts only configured \`codex\` or \`claude\` agents;
-- creates one persistent Run per Task;
-- normally creates an isolated Git worktree;
-- records prompt, process metadata, streaming stdout/stderr, structured events, and result under \`.ai/harness/jobs/\`;
-- never exposes arbitrary shell input through MCP;
-- does not commit, merge, or push automatically.
-
-Watch local or GitHub execution from a terminal:
-
-\`\`\`bash
-forge controller runs --repo .
-forge controller watch <RUN-ID> --repo . --log
+Use Forge. Call rh_status and report whether the Runtime is ready. Do not modify anything yet.
 \`\`\`
 
-The \`--log\` view streams local Codex/Claude output while the process is running and polls GitHub cloud-session logs when available.
+A successful controller-to-Forge tool call is the meaningful end-to-end setup milestone.
 
-## Local Codex MCP
+## Optional controller entries
 
-Configure Codex to read forge state:
+Codex and Claude are configured only when explicitly selected:
 
 \`\`\`bash
-forge mcp setup codex --repo . --scope project
+forge mcp setup codex --scope user --profile controller
+forge mcp setup claude --scope user --profile controller
 \`\`\`
 
-The executor profile remains read-oriented. Controller-dispatched Codex work is scoped by the generated Task prompt and worktree.
+Multiple controller entries may coexist, while one external controller remains the semantic owner at a time.
 
-## Security
+## Advanced source/Recovery path
 
-- Keep OAuth passphrases, bearer tokens, tunnel tokens, \`~/.codex/auth.json\`, and other credentials out of chat and Git.
-- Keep the MCP server bound to loopback; expose it only through the authenticated tunnel.
-- Do not remove immutable hard-deny patterns in order to make a Task pass.
-- Review every completed local diff or GitHub pull request and record passing Verification Gate evidence before accepting a Task.
-- Use the smallest allowed path set and focused checks for direct edits.
-
-## Troubleshooting
-
-- ChatGPT cannot connect: verify the HTTPS tunnel ends in \`/mcp\` and local \`/ready\` responds.
-- Grok cannot connect: recreate it with the canonical \`…/mcp\` URL. The legacy \`…/mcp-grok\` URL is compatibility-only.
-- A genuinely non-OAuth client loops on \`/authorize\`: use \`…/mcp-bearer\` with a bearer token from \`controllerHome/mcp/mcp.tokens.json\`.
-- ChatGPT auth loops: retry authorization and inspect \`controllerHome/mcp/mcp.oauth.json\` first, then legacy \`.forge/mcp.oauth.json\` only when using fallback; do not paste the passphrase into chat.
-- Tool scan misses tools: restart the Forge Runtime service with \`launchctl kickstart -k gui/$(id -u)/com.moretea.forge.runtime.<controller-home-suffix>\`, then rescan or recreate the versioned Connector and verify \`controller_capabilities.expectedTools\` includes \`repository_latest_source_diagnose\` and \`repository_bootstrap_local_project\`.
-- Codex cannot see the MCP server: rerun \`forge mcp setup codex --repo . --scope project\`.
-- A quick tunnel URL changed: update the Connector URL or switch to a named tunnel.
-- A Task is blocked: inspect \`get_task_run\`, shrink or re-plan the Task, then retry that Task rather than redispatching the full Issue.
+Maintainers who intentionally need immutable Git/source releases and independent disaster recovery may use the source Runtime and Standalone Recovery documentation. Those mechanisms are not required by ordinary npm/package users and are deliberately excluded from normal setup.
 `;
 }
 
 export function runMcpSetupChatgpt(opts: {
   repo?: string;
+  controllerHome?: string;
+  userLevel?: boolean;
   host?: string;
   port?: string;
   endpoint?: string;
   serverName?: string;
+  localControllerPort?: string;
 }): McpSetupResult {
   const repoRoot = resolveMcpRepoRoot(opts.repo ?? ".");
-  const controllerHome = ensureRepoPreferredControllerHome(repoRoot);
+  const controllerHome = opts.userLevel
+    ? ensureControllerHome(opts.controllerHome)
+    : ensureRepoPreferredControllerHome(repoRoot, opts.controllerHome);
   const changed: string[] = [];
   const existingConfig = loadMcpServiceLocalConfig(controllerHome, repoRoot);
   const host = opts.host ?? existingConfig?.server?.host ?? "127.0.0.1";
   const port = opts.port ?? String(existingConfig?.server?.port ?? 8765);
+  const parsedPort = Number(port);
+  if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65_535) throw new Error(`forge mcp setup chatgpt: invalid port ${port}`);
+  const localControllerPort = opts.localControllerPort !== undefined
+    ? Number(opts.localControllerPort)
+    : existingConfig?.localController?.port ?? (parsedPort < 65_535 ? parsedPort + 1 : 8766);
+  if (!Number.isInteger(localControllerPort) || localControllerPort < 1 || localControllerPort > 65_535) throw new Error(`forge mcp setup chatgpt: invalid Local Controller port ${opts.localControllerPort}`);
+  if (localControllerPort === parsedPort) throw new Error('forge mcp setup chatgpt: Local Controller port must differ from MCP port');
   const existingServerName = existingConfig?.chatgpt?.serverName;
   const migratedServerName =
     existingServerName && !LEGACY_DEFAULT_SERVER_NAMES.has(existingServerName)
@@ -455,7 +331,7 @@ export function runMcpSetupChatgpt(opts: {
     opts.endpoint ?? existingConfig?.chatgpt?.endpoint,
   );
   const configPath = mcpControllerHomeLocalConfigPath(controllerHome);
-  const guidePath = join(repoRoot, "docs", "forge-chatgpt-mcp-setup.md");
+  const guidePath = opts.userLevel ? undefined : join(repoRoot, "docs", "forge-chatgpt-mcp-setup.md");
   const token = ensureMcpControllerHomeBearerToken(controllerHome);
   const oauth = ensureMcpControllerHomeOAuthPassphrase(controllerHome);
   if (token.changed) changed.push(token.path);
@@ -464,11 +340,11 @@ export function runMcpSetupChatgpt(opts: {
   const toolset = migratedToolset.toolset;
   const config = {
     version: Math.max(existingConfig?.version ?? 1, 2),
-    repo: repoRoot,
+    ...(opts.userLevel ? (existingConfig?.repo ? { repo: existingConfig.repo } : {}) : { repo: repoRoot }),
     server: {
       ...existingConfig?.server,
       host,
-      port: Number(port),
+      port: parsedPort,
       transport: existingConfig?.server?.transport ?? "http",
     },
     auth: existingConfig?.auth ?? {
@@ -488,16 +364,22 @@ export function runMcpSetupChatgpt(opts: {
       ?? accessModeForLegacyToolset(existingConfig?.toolset ?? toolset),
     accessModeUpdatedAt: existingConfig?.accessModeUpdatedAt,
     accessModeRevision: existingConfig?.accessModeRevision ?? 0,
-    localController: existingConfig?.localController ?? {
-      enabled: true,
-      host: "127.0.0.1",
-      port: 8766,
-      autoOpen: false,
-    },
+    localController: opts.userLevel && !existingConfig?.repo
+      ? {
+          enabled: false,
+          host: existingConfig?.localController?.host ?? "127.0.0.1",
+          port: localControllerPort,
+          autoOpen: false,
+          mode: "disabled",
+        }
+      : {
+          ...(existingConfig?.localController ?? { enabled: true, host: "127.0.0.1", autoOpen: false }),
+          port: localControllerPort,
+        },
     devMode: {
       ...existingConfig?.devMode,
-      agentRunner: existingConfig?.devMode?.agentRunner ?? true,
-      allowedAgents: existingConfig?.devMode?.allowedAgents ?? defaultLocalAgentRunners(),
+      agentRunner: existingConfig?.devMode?.agentRunner ?? false,
+      allowedAgents: existingConfig?.devMode?.allowedAgents ?? [],
       timeoutMs:
         !existingConfig?.devMode?.timeoutMs ||
         existingConfig.devMode.timeoutMs === 120_000
@@ -512,105 +394,116 @@ export function runMcpSetupChatgpt(opts: {
     `${JSON.stringify(config, null, 2)}\n`,
     changed,
   );
-  writeFileIfChanged(guidePath, chatgptGuideMarkdown(), changed);
-  ensureGitignoreEntries(
-    repoRoot,
-    [
-      ".forge/mcp.local.json",
-      ".forge/mcp.tokens.json",
-      ".forge/mcp.oauth.json",
-      ".forge/mcp.oauth-tokens.json",
-      ".forge/mcp.runtime.json",
-      ".ai/harness/mcp/audit.log",
-      ".ai/harness/local-jobs/",
-      ".ai/harness/controller/",
-    ],
-    changed,
-  );
+  if (guidePath) {
+    writeFileIfChanged(guidePath, chatgptGuideMarkdown(), changed);
+    ensureGitignoreEntries(
+      repoRoot,
+      [
+        ".forge/mcp.local.json",
+        ".forge/mcp.tokens.json",
+        ".forge/mcp.oauth.json",
+        ".forge/mcp.oauth-tokens.json",
+        ".forge/mcp.runtime.json",
+        ".ai/harness/mcp/audit.log",
+        ".ai/harness/local-jobs/",
+        ".ai/harness/controller/",
+      ],
+      changed,
+    );
+  }
 
   return {
     status: "ok",
     repoRoot,
     changed,
     lines: [
-      `[forge mcp] Repo: ${repoRoot}`,
+      opts.userLevel ? `[forge mcp] Scope: user (${controllerHome})` : `[forge mcp] Repo: ${repoRoot}`,
       "[forge mcp] Profile: controller",
       `[forge mcp] Toolset: ${config.toolset}`,
       `[forge mcp] ChatGPT MCP server name: ${serverName}`,
       `[forge mcp] Local endpoint: http://${host}:${port}/mcp`,
       `[forge mcp] Local Controller: http://${config.localController.host}:${config.localController.port}/`,
-      `[forge mcp] Local agent timeout: ${config.devMode.timeoutMs}ms (max ${config.devMode.maxTimeoutMs}ms)`,
+      `[forge mcp] Optional external delegation: ${config.devMode.agentRunner ? `enabled (${config.devMode.allowedAgents.join(',') || 'none'})` : 'disabled'}`,
       endpoint
         ? `[forge mcp] ChatGPT endpoint: ${endpoint}`
         : "[forge mcp] ChatGPT endpoint: requires stable HTTPS tunnel",
       `[forge mcp] Auth: OAuth passphrase (${relative(repoRoot, oauth.path)})`,
       `[forge mcp] Bearer fallback token: ${relative(repoRoot, token.path)}`,
       `[forge mcp] Config: ${relative(repoRoot, configPath)}`,
-      `[forge mcp] Guide: ${relative(repoRoot, guidePath)} (generic; endpoint stays in ignored local config)`,
-      `[forge mcp] Runtime state: ${relative(repoRoot, mcpControllerHomeRuntimeStatePath(controllerHome))}`,
-      `Next: forge runtime service install --controller-home ${controllerHome} --repo ${repoRoot} --host ${host} --port ${port}`,
+      ...(guidePath ? [`[forge mcp] Guide: ${relative(repoRoot, guidePath)} (generic; endpoint stays in ignored local config)`] : []),
+      `[forge mcp] Runtime state: ${mcpControllerHomeRuntimeStatePath(controllerHome)}`,
+      opts.userLevel
+        ? 'Next: forge setup next'
+        : `Next: forge runtime service install-package --controller-home ${controllerHome} --host ${host} --port ${port}`,
     ],
   };
 }
 
-const CODEX_MCP_BLOCK = `[mcp_servers.forge]
-command = "forge"
-args = [
-  "mcp",
-  "serve",
-  "--repo",
-  ".",
-  "--transport",
-  "stdio",
-  "--profile",
-  "executor"
-]
-enabled_tools = [
-  "harness_status",
-  "read_workflow_file",
-  "latest_handoff",
-  "latest_checks",
-  "prepare_codex_goal_from_sprint",
-  "write_codex_goal",
-  "run_workflow_check"
-]
-default_tools_approval_mode = "prompt"
-`;
+type LocalControllerProfile = 'controller' | 'executor';
+
+function localControllerProfile(value: string | undefined, label: string, fallback: LocalControllerProfile): LocalControllerProfile {
+  const normalized = (value ?? fallback).trim().toLowerCase();
+  if (normalized !== 'controller' && normalized !== 'executor') {
+    throw new Error(`${label}: expected controller|executor`);
+  }
+  return normalized;
+}
+
+export function codexMcpBlock(profile: LocalControllerProfile = 'executor'): string {
+  const lines = [
+    '[mcp_servers.forge]',
+    'command = "forge"',
+    'args = [',
+    '  "mcp",',
+    '  "serve",',
+    '  "--repo",',
+    '  ".",',
+    '  "--transport",',
+    '  "stdio",',
+    '  "--profile",',
+    `  "${profile}"`,
+    ']',
+  ];
+  if (profile === 'executor') {
+    lines.push(
+      'enabled_tools = [',
+      ...REQUIRED_CODEX_TOOLS.map((tool) => `  "${tool}",`),
+      ']',
+      'default_tools_approval_mode = "prompt"',
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
 
-export function patchCodexConfigToml(current: string): string {
+export function patchCodexConfigToml(current: string, profile: LocalControllerProfile = 'executor'): string {
+  const block = codexMcpBlock(profile);
   const normalized = current.trimEnd();
   const blockPattern = /\n?\[mcp_servers\.forge\][\s\S]*?(?=\n\[|$)/;
-  const prefix = normalized.length > 0 ? `${normalized}\n\n` : "";
-  if (!blockPattern.test(normalized)) return `${prefix}${CODEX_MCP_BLOCK}`;
-  return `${normalized.replace(blockPattern, `\n${CODEX_MCP_BLOCK}`.trimEnd())}\n`;
+  const prefix = normalized.length > 0 ? `${normalized}\n\n` : '';
+  if (!blockPattern.test(normalized)) return `${prefix}${block}`;
+  return `${normalized.replace(blockPattern, `\n${block}`.trimEnd())}\n`;
 }
 
 export function runMcpSetupCodex(opts: {
   repo?: string;
   scope?: string;
+  profile?: string;
   dryRun?: boolean;
 }): McpSetupResult {
-  if ((opts.scope ?? "project") !== "project") {
-    throw new Error(
-      "forge mcp setup codex currently supports --scope project only",
-    );
+  const scope = (opts.scope ?? 'project').trim().toLowerCase();
+  if (scope !== 'project' && scope !== 'user') {
+    throw new Error('forge mcp setup codex --scope: expected project|user');
   }
-  const repoRoot = resolveMcpRepoRoot(opts.repo ?? ".");
-  const configPath = join(repoRoot, ".codex", "config.toml");
+  const profile = localControllerProfile(opts.profile, 'forge mcp setup codex --profile', 'executor');
+  const repoRoot = resolveMcpRepoRoot(opts.repo ?? '.');
+  const configPath = scope === 'user' ? join(homedir(), '.codex', 'config.toml') : join(repoRoot, '.codex', 'config.toml');
   const changed: string[] = [];
-  const current = existsSync(configPath)
-    ? readFileSync(configPath, "utf-8")
-    : "";
-  const next = patchCodexConfigToml(current);
+  const current = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+  const next = patchCodexConfigToml(current, profile);
   if (opts.dryRun === true) {
     return {
-      status: "ok",
-      repoRoot,
-      changed: [],
-      lines: [
-        `[forge mcp] Dry run: would patch ${relative(repoRoot, configPath)}`,
-        next,
-      ],
+      status: 'ok', repoRoot, changed: [],
+      lines: [`[forge mcp] Dry run: would patch ${scope === 'user' ? configPath : relative(repoRoot, configPath)}`, next],
     };
   }
   if (existsSync(configPath) && current !== next) {
@@ -619,13 +512,56 @@ export function runMcpSetupCodex(opts: {
   }
   writeFileIfChanged(configPath, next, changed);
   return {
-    status: "ok",
-    repoRoot,
-    changed,
+    status: 'ok', repoRoot, changed,
+    lines: [
+      `[forge mcp] Codex config: ${scope === 'user' ? configPath : relative(repoRoot, configPath)}`,
+      '[forge mcp] Server: forge',
+      '[forge mcp] Transport: stdio',
+      `[forge mcp] Role: external ${profile === 'controller' ? 'primary controller' : 'executor/delegate'}`,
+    ],
+  };
+}
+
+export function claudeMcpSetupCommand(repoRoot: string, profile: LocalControllerProfile = 'controller', scope = 'user'): string[] {
+  return [
+    'claude', 'mcp', 'add', 'forge', '--scope', scope, '--',
+    'forge', 'mcp', 'serve', '--repo', repoRoot, '--transport', 'stdio', '--profile', profile,
+  ];
+}
+
+export function runMcpSetupClaude(opts: {
+  repo?: string;
+  scope?: string;
+  profile?: string;
+  dryRun?: boolean;
+}): McpSetupResult {
+  const repoRoot = resolveMcpRepoRoot(opts.repo ?? '.');
+  const scope = (opts.scope ?? 'user').trim().toLowerCase();
+  if (!['local', 'project', 'user'].includes(scope)) {
+    throw new Error('forge mcp setup claude --scope: expected local|project|user');
+  }
+  const profile = localControllerProfile(opts.profile, 'forge mcp setup claude --profile', 'controller');
+  const command = claudeMcpSetupCommand(scope === 'user' ? '.' : repoRoot, profile, scope);
+  if (opts.dryRun === true) {
+    return {
+      status: 'ok', repoRoot, changed: [],
+      lines: [`[forge mcp] Dry run: ${command.join(' ')}`],
+    };
+  }
+  const result = spawnSync(command[0], command.slice(1), { cwd: repoRoot, encoding: 'utf8', timeout: 30_000 });
+  if (result.error && (result.error as NodeJS.ErrnoException).code === 'ENOENT') {
+    throw new Error('Claude Code CLI is not installed. Install/authenticate Claude only if you selected it as a Forge controller.');
+  }
+  if (result.status !== 0) {
+    throw new Error(`Claude MCP configuration failed (${result.status ?? 'unknown'}): ${(result.stderr || result.stdout || result.error?.message || '').trim()}`);
+  }
+  return {
+    status: 'ok', repoRoot, changed: [],
     lines: [
-      `[forge mcp] Codex config: ${relative(repoRoot, configPath)}`,
-      "[forge mcp] Server: forge",
-      "[forge mcp] Transport: stdio",
+      '[forge mcp] Claude Code MCP server configured through the Claude CLI.',
+      `[forge mcp] Scope: ${scope}`,
+      `[forge mcp] Role: external ${profile === 'controller' ? 'primary controller' : 'executor/delegate'}`,
+      '[forge mcp] Verify: claude mcp get forge',
     ],
   };
 }
@@ -709,7 +645,7 @@ export function runMcpDoctor(opts: {
       },
       devMode: {
         agentRunner: localConfig?.devMode?.agentRunner === true,
-        allowedAgents: localConfig?.devMode?.allowedAgents ?? defaultLocalAgentRunners(),
+        allowedAgents: localConfig?.devMode?.allowedAgents ?? [],
         timeoutMs: localConfig?.devMode?.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS,
         maxTimeoutMs:
           localConfig?.devMode?.maxTimeoutMs ?? MAX_AGENT_TIMEOUT_MS,