@moretea-labs/forge 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,7 +4,14 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
-No unreleased public changes are currently recorded.
+## 1.5.1 - 2026-08-13
+
+### ChatGPT Secure Tunnel and package setup
+
+- Make `--tunnel auto` prefer OpenAI Secure MCP Tunnel instead of silently selecting an installed public-ingress CLI. Cloudflare, Tailscale, existing HTTPS, and deferred remote access remain explicit fallbacks.
+- Add a package-managed loopback OAuth Gateway for ChatGPT alongside the bearer-only Canonical Runtime, and persist the local OAuth endpoint in user-level MCP configuration so Secure Tunnel never targets the internal Runtime directly.
+- Accept modern ChatGPT `server/discover` probing with the correct legacy fallback response, detect tunnel runtimes by `tunnel_id` rather than a hard-coded alias, and prefer an existing repository Controller Home during setup reconciliation.
+- Clarify that the ChatGPT App/connector owns application/tool identity while Secure Tunnel owns transport, document migration from Cloudflare/HTTPS, and add the supported npm update flow (`npm install -g @moretea-labs/forge@latest` then `forge setup next`).
 
 ## 1.5.0 - 2026-08-13
 

package/README.md

@@ -44,9 +44,9 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next
 ```
 
-Setup persists progress and guides the selected path through the user-level Package Runtime, remote connectivity, controller registration, and connection verification. For ChatGPT, prefer **OpenAI Secure MCP Tunnel** when your organization supports it; Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` URL, or deferred remote access remain alternatives. Local Codex/Claude controllers do not need a tunnel.
+Setup persists progress and guides the selected path through the user-level Package Runtime, remote connectivity, controller registration, and connection verification. For ChatGPT, `--tunnel auto` now means **OpenAI Secure MCP Tunnel first**: Forge keeps the Canonical Runtime private, installs a loopback OAuth Gateway for ChatGPT, and lets the official `tunnel-client` carry MCP traffic outbound to OpenAI. Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` URL, or deferred remote access remain explicit fallbacks when Secure Tunnel is unavailable. Local Codex/Claude controllers do not need a tunnel. The ChatGPT App/connector is the application identity; Secure Tunnel is only its network transport, so switching transport does not create a second Forge tool schema.
 
-Then follow [Install and start](docs/tutorials/01-install-and-start.md) and [Connect ChatGPT](docs/tutorials/02-connect-chatgpt.md). A repository is optional during initial setup; add one later with `forge adopt --repo /path/to/your-project`.
+Then follow [Install and start](docs/tutorials/01-install-and-start.md) and [Connect ChatGPT](docs/tutorials/02-connect-chatgpt.md). A repository is optional during initial setup; add one later with `forge adopt --repo /path/to/your-project`. Upgrade an existing install with `npm install -g @moretea-labs/forge@latest`, verify with `forge --version`, then run `forge setup next` to reconcile newer Runtime/connector setup contracts.
 
 For a reviewed source checkout: `git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`.
 
@@ -58,7 +58,7 @@ Forge ships typed local/browser/desktop/iOS/GitHub/Gmail/Calendar/Tasks/App Stor
 
 Local read/write grants are explicit and expiring; remote or destructive effects are distinguished from ordinary local work; high-impact actions require stronger confirmation. Full Access reduces repetitive prompts for normal work without removing the hard boundaries around secrets, destructive actions, and outside-workspace access. See [Security](SECURITY.md) and the [Security Model](docs/wiki/Security-Model.md).
 
-**Docs:** [Wiki](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: `1.5.0`; stable installs use npm `latest`.
+**Docs:** [Wiki](docs/wiki/Home.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md). Current stable release: `1.5.1`; stable installs use npm `latest`.
 
 ---
 <a id="zh-cn"></a>
@@ -101,12 +101,12 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-远程主控的 setup 会继续引导 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp`，或暂缓远程连接。本地 Codex/Claude 主控不需要 tunnel，也不会配置未选择的 CLI。
+远程主控的 setup 会继续引导 Package Runtime、远程连接、主控配置和连接验证；对 ChatGPT，`--tunnel auto` 现在明确表示 **优先 OpenAI Secure MCP Tunnel**。Forge 保持 Canonical Runtime 私有，并安装一个仅监听 loopback 的 OAuth Gateway，再由官方 `tunnel-client` 出站连接 OpenAI。只有 Secure Tunnel 不可用时才显式选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地 Codex/Claude 主控不需要 tunnel。ChatGPT App/connector 是应用身份，Secure Tunnel 只是网络传输层，因此切换网络不会产生另一套 Forge 工具 schema。
 
-继续阅读[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md)和[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)。仓库不是首次 setup 的前置条件，需要开发能力时再运行 `forge adopt --repo /path/to/your-project`。源码安装：`git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`。
+继续阅读[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md)和[连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md)。仓库不是首次 setup 的前置条件，需要开发能力时再运行 `forge adopt --repo /path/to/your-project`。已安装用户升级：`npm install -g @moretea-labs/forge@latest`，确认 `forge --version` 后运行 `forge setup next` 让新版 setup 自动补齐 Runtime/connector 配置。源码安装：`git clone https://github.com/moretea-labs/forge.git && cd forge && npm ci --ignore-scripts --no-audit --no-fund && npm install -g . --omit=optional --no-audit --no-fund`。
 
 Forge 内置本机、Browser、Desktop、iOS、GitHub、Gmail、Calendar、Tasks、App Store Connect、Resend 等类型化能力；公开 Provider 目录还有 **Forge Desktop Operator / Forge Design / Personal Knowledge Assistant**。详见[功能清单](docs/operations/features.zh-CN.md)与[插件管理](docs/forge-plugin-management.md)。
 
 安全上，普通本地修改、远程影响、破坏性操作、密钥和工作区外访问是不同边界；Full Access 不会取消高风险确认。详见[安全说明](SECURITY.md)和[安全模型](docs/wiki/Security-Model.md)。
 
-**文档：** [Wiki](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 `1.5.0`，稳定安装使用 npm `latest`。
+**文档：** [Wiki](docs/wiki/Home.md) · [支持](SUPPORT.md) · [贡献](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)。当前稳定版为 `1.5.1`，稳定安装使用 npm `latest`。

package/README.zh-CN.md

@@ -52,10 +52,12 @@ forge setup configure --controller chatgpt --tunnel auto
 forge setup next     # 按每次显示的 Next 动作继续
 ```
 
-`forge setup` 会持久化进度。远程主控会继续经过 Package Runtime、远程连接、主控配置和连接验证；ChatGPT 在组织支持时优先 **OpenAI Secure MCP Tunnel**，也可选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地主控 Codex/Claude 不需要 tunnel。
+`forge setup` 会持久化进度。对 ChatGPT，`--tunnel auto` 现在明确表示 **优先 OpenAI Secure MCP Tunnel**：Forge 保持 Canonical Runtime 私有，安装一个仅监听 loopback 的 OAuth Gateway，再由官方 `tunnel-client` 通过出站连接接入 OpenAI。Secure Tunnel 不可用时，再显式选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接。本地主控 Codex/Claude 不需要 tunnel。ChatGPT App/connector 是应用身份，Secure Tunnel 是网络传输层；切换 tunnel 不会创建另一套 Forge 工具 schema。
 
 接着阅读：[安装与启动](docs/tutorials/01-install-and-start.zh-CN.md) · [连接 ChatGPT](docs/tutorials/02-connect-chatgpt.zh-CN.md) · [第一个仓库任务](docs/tutorials/03-first-repository-task.zh-CN.md)。仓库不是首次 setup 的前置条件；需要时再 `forge adopt --repo /path/to/your-project`。
 
+已安装用户升级：`npm install -g @moretea-labs/forge@latest` → `forge --version` → `forge setup next`。
+
 从源码安装已审查 checkout：
 
 ```bash
@@ -76,4 +78,4 @@ Forge 把读取、普通本地写入、远程操作、破坏性操作、工作
 
 [中文文档中心](docs/README.zh-CN.md) · [Wiki](docs/wiki/Home.md) · [SUPPORT.md](SUPPORT.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md)
 
-当前稳定版本是 `1.5.0`，稳定安装使用 npm `latest`。
+当前稳定版本是 `1.5.1`，稳定安装使用 npm `latest`。

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.0`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.1`.
 
 License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release preparation. This file is informational and does not replace the license text distributed by each dependency.
 

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.5.0",
-  "templateVersion": "1.5.0",
+  "version": "1.5.1",
+  "templateVersion": "1.5.1",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/docs/forge-chatgpt-mcp-setup.md

@@ -27,16 +27,40 @@ The Package Runtime does not require a Forge Git checkout, Bun compilation, Code
 
 ## Local boundaries
 
-Forge MCP remains loopback-only, normally at:
+Forge keeps two MCP boundaries on loopback by default:
 
 ```text
-http://127.0.0.1:8765/mcp
+ChatGPT OAuth Gateway: http://127.0.0.1:8767/mcp
+Canonical Runtime:      http://127.0.0.1:8765/mcp
 ```
 
+The OAuth Gateway is the endpoint for Secure Tunnel or HTTPS connectors. It proxies authenticated controller traffic to the bearer-only Canonical Runtime; remote clients should never target the internal Runtime directly. `forge mcp setup chatgpt --user-level` records the actual OAuth endpoint, so custom ports remain supported.
+
 Fresh user-level setup keeps the repository-centric Utility Console disabled until a repository/workbench target is configured. When enabled later it uses a separate loopback port (normally 8766). Never expose it to the internet.
 
 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.
 
+## App identity vs. transport
+
+The ChatGPT App/connector is the application identity and owns the visible Forge tool schema. **Secure MCP Tunnel is the transport.** Switching an existing Forge App from a public HTTPS/Cloudflare route to Tunnel changes how commands reach Forge; it does not create a second Forge tool schema.
+
+Default path:
+
+```text
+ChatGPT App -> OpenAI Secure MCP Tunnel -> tunnel-client
+            -> Forge loopback OAuth Gateway -> Canonical Runtime
+```
+
+A fresh chat is useful for isolated A/B testing, but Forge does not require a new conversation merely because transport changed when the same App is already connected and its tool schema is unchanged. If published tool definitions change, use ChatGPT's current app refresh/re-publish workflow.
+
+Upgrade existing Forge installs with:
+
+```bash
+npm install -g @moretea-labs/forge@latest
+forge --version
+forge setup next
+```
+
 ## Remote controller connection
 
 The setup profile owns the connection choice. Supported paths are:
@@ -47,7 +71,7 @@ The setup profile owns the connection choice. Supported paths are:
 4. **Existing HTTPS** — user-managed reverse proxy/tunnel ending in `/mcp`.
 5. **None** — local setup only; remote connectivity can be configured later.
 
-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.
+For OpenAI Secure MCP Tunnel, setup uses the official managed runtime surface and considers a matching local alias ready only when `tunnel-client` reports the configured `tunnel_id` running, healthy, and ready. Alias names are not tunnel identity.
 
 For public HTTPS paths, the configured connector URL is:
 

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.5.0` exists on npm;
-- Git tag and GitHub Release `v1.5.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.5.1` exists on npm;
+- Git tag and GitHub Release `v1.5.1` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

package/docs/public-usage-guide.md

@@ -18,7 +18,7 @@ forge setup next
 
 ## 2. Follow setup until the selected path is usable
 
-For a hosted controller, setup guides the user-level Package Runtime and a remote connection. Prefer OpenAI Secure MCP Tunnel when eligible; Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` endpoint, or deferred remote access are alternatives.
+For ChatGPT, `--tunnel auto` prefers OpenAI Secure MCP Tunnel and does not silently switch to a public ingress provider just because one is installed. The packaged setup keeps the bearer-only Canonical Runtime private and manages a separate loopback OAuth Gateway for the ChatGPT App. Cloudflare Tunnel, Tailscale Funnel, an existing HTTPS `/mcp` endpoint, or deferred remote access are explicit alternatives. Existing users update with `npm install -g @moretea-labs/forge@latest`, then `forge setup next`.
 
 The normal package Runtime is `forge runtime service install-package`. Source immutable Runtime and Standalone Recovery are advanced maintainer paths.
 

package/docs/public-usage-guide.zh-CN.md

@@ -18,7 +18,7 @@ forge setup next
 
 ## 2. 按 Next 完成所选路径
 
-远程主控会继续配置 Package Runtime 和远程连接。有权限时优先 OpenAI Secure MCP Tunnel；也可以选择 Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp`，或暂缓远程连接。
+对 ChatGPT，`--tunnel auto` 会优先 OpenAI Secure MCP Tunnel，不会因为机器上恰好安装了 cloudflared/Tailscale 就静默改用公网入口。Package setup 会保持 bearer-only Canonical Runtime 私有，并管理一个独立的 loopback OAuth Gateway 供 ChatGPT App 使用。Cloudflare Tunnel、Tailscale Funnel、已有 HTTPS `/mcp` 或暂缓远程连接都是显式 fallback。已安装用户运行 `npm install -g @moretea-labs/forge@latest` 后再执行 `forge setup next`。
 
 普通 package Runtime 是 `forge runtime service install-package`。源码 immutable Runtime 与 Standalone Recovery 属于高级维护路径。
 

package/docs/tutorials/01-install-and-start.md

@@ -20,7 +20,7 @@ See [Platform Support](../operations/platform-support.md) for the exact matrix.
 
 ## 2. Install Forge
 
-Release candidates use npm `next`:
+Stable releases use npm `latest`:
 
 ```bash
 npm install -g @moretea-labs/forge
@@ -38,7 +38,7 @@ npm ci --ignore-scripts --no-audit --no-fund
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 
-The published package exposes `forge`, `forge-hook`, and `forge-runtime`. Normal package users do **not** need a Forge source checkout, Bun compilation, CodeGraph, or Standalone Recovery to start the user-level Runtime.
+The published package exposes `forge`, `forge-hook`, and `forge-runtime`. Normal package users do **not** need a Forge source checkout, Bun compilation, CodeGraph, or Standalone Recovery to start the user-level Runtime. To upgrade, run `npm install -g @moretea-labs/forge@latest`, verify `forge --version`, then run `forge setup next` so newer setup contracts can be reconciled without reinstalling from source.
 
 ## 3. Start guided setup
 
@@ -78,7 +78,7 @@ The setup session is stored below the user-level Forge directory, so you can clo
 
 1. controller registration;
 2. the packaged user-level Runtime;
-3. secure public HTTPS for a remote controller;
+3. remote connectivity — OpenAI Secure MCP Tunnel first for ChatGPT, with explicit HTTPS fallbacks;
 4. account/browser authentication that only you can complete;
 5. a connection verification.
 
@@ -90,6 +90,8 @@ The normal Runtime action is:
 forge runtime service install-package
 ```
 
+For ChatGPT setups this installs two local service boundaries together: the bearer-only Canonical Runtime and a separate loopback OAuth Gateway used by Secure Tunnel or HTTPS connectors. Users should follow the OAuth endpoint printed by setup instead of tunneling directly to the internal Runtime port.
+
 The older `forge runtime service install --repo ...` path builds an immutable Git/source Runtime and is an **advanced maintainer path**, not normal onboarding. Standalone Recovery is likewise optional advanced infrastructure.
 
 ## 5. Repositories are optional at first

package/docs/tutorials/01-install-and-start.zh-CN.md

@@ -90,6 +90,8 @@ setup 进度保存在用户级 Forge 目录，可以退出终端后继续。根
 forge runtime service install-package
 ```
 
+对 ChatGPT，package 安装会同时维护两个本地服务边界：内部 bearer-only Canonical Runtime，以及供 Secure Tunnel/HTTPS connector 使用的 loopback OAuth Gateway。不要把 tunnel 直接指向内部 Runtime 端口，以 setup 输出的本地 OAuth endpoint 为准。
+
 旧的 `forge runtime service install --repo ...` 会构建 Git/source immutable Runtime，属于**高级维护路径**；Standalone Recovery 同样不是普通用户初始化的前置条件。
 
 ## 5. 首次 setup 不要求仓库

package/docs/tutorials/02-connect-chatgpt.md

@@ -42,7 +42,7 @@ Run `forge setup next`. Forge supports these connection providers:
 
 ### A. OpenAI Secure MCP Tunnel — preferred when available
 
-Secure MCP Tunnel lets an OpenAI-hosted product reach the local MCP server through an outbound tunnel, without creating public inbound access. See OpenAI's [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) and the official [`openai/tunnel-client`](https://github.com/openai/tunnel-client).
+Secure MCP Tunnel lets an OpenAI-hosted product reach the local MCP server through an outbound tunnel, without creating public inbound access. `--tunnel auto` treats this as the first-choice ChatGPT transport and does not silently choose Cloudflare/Tailscale merely because those CLIs are installed. See OpenAI's [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) and the official [`openai/tunnel-client`](https://github.com/openai/tunnel-client).
 
 You need a tunnel ID and tunnel-use permission from OpenAI Platform. Record only the non-secret tunnel ID in Forge:
 
@@ -67,13 +67,19 @@ tunnel-client runtimes connect \
   --alias forge \
   --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
   --runtime-api-key env:CONTROL_PLANE_API_KEY \
-  --mcp-server-url http://127.0.0.1:8765/mcp
+  --mcp-server-url http://127.0.0.1:8767/mcp
 
 tunnel-client runtimes status forge --json
 ```
 
 Forge reports this provider ready only when `tunnel-client` reports the managed runtime as running, healthy, and ready.
 
+#### What address changes?
+
+With Secure Tunnel there is no public Forge `/mcp` address to paste. The ChatGPT App selects the `tunnel_id`; `tunnel-client` forwards commands to Forge's **loopback OAuth Gateway** (default `127.0.0.1:8767/mcp`), which proxies to the internal bearer-only Runtime (default `127.0.0.1:8765/mcp`). If you customize ports, use the OAuth endpoint printed by `forge mcp setup chatgpt --user-level`.
+
+The App/connector identity and Forge tool schema are separate from the transport. Switching from Cloudflare/HTTPS to Secure Tunnel changes the network path, not the 19-tool Forge schema. A fresh chat is useful for isolated A/B testing, but it is not required merely because transport changed when the same App is already connected.
+
 ### B. Cloudflare Tunnel
 
 Choose this when you need a stable public HTTPS endpoint and control the Cloudflare account/domain:

package/docs/tutorials/02-connect-chatgpt.zh-CN.md

@@ -40,7 +40,7 @@ http://127.0.0.1:8765/mcp
 
 ### A. OpenAI Secure MCP Tunnel——有权限时优先
 
-Secure MCP Tunnel 通过出站连接把本机/private MCP 接到 OpenAI 托管产品，不要求给 Forge 开公网入站。详见 OpenAI 的 [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) 与官方 [`openai/tunnel-client`](https://github.com/openai/tunnel-client)。
+Secure MCP Tunnel 通过出站连接把本机/private MCP 接到 OpenAI 托管产品，不要求给 Forge 开公网入站。 `--tunnel auto` 会把它作为 ChatGPT 的第一优先传输，不会仅仅因为机器上装了 cloudflared/Tailscale 就静默改用公网方案。详见 OpenAI 的 [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) 与官方 [`openai/tunnel-client`](https://github.com/openai/tunnel-client)。
 
 需要先在 OpenAI Platform 获得 tunnel ID 和使用权限。Forge 只记录**非秘密**的 tunnel ID：
 
@@ -65,13 +65,19 @@ tunnel-client runtimes connect \
   --alias forge \
   --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
   --runtime-api-key env:CONTROL_PLANE_API_KEY \
-  --mcp-server-url http://127.0.0.1:8765/mcp
+  --mcp-server-url http://127.0.0.1:8767/mcp
 
 tunnel-client runtimes status forge --json
 ```
 
 只有 tunnel-client 返回 `process_running + healthy + ready` 后，Forge 才把这个连接判为 ready。
 
+#### 地址到底变成什么？
+
+使用 Secure Tunnel 后，不再需要给 Forge 准备一个公网 `/mcp` 地址。ChatGPT App 选择 `tunnel_id`；本机 `tunnel-client` 把命令转发到 Forge 的 **loopback OAuth Gateway**（默认 `127.0.0.1:8767/mcp`），再由 Gateway 代理到内部 bearer-only Runtime（默认 `127.0.0.1:8765/mcp`）。如果改过端口，以 `forge mcp setup chatgpt --user-level` 输出的 OAuth endpoint 为准。
+
+App/connector 身份及 Forge 工具 schema 与网络传输层是两件事。Cloudflare/HTTPS 切到 Secure Tunnel 改变的是网络路径，不会生成另一套 19-tool Forge schema。同一个 App 已连接且 schema 没变化时，单纯切换网络不要求新开会话；新会话主要用于隔离 A/B 或排查客户端缓存。
+
 ### B. Cloudflare Tunnel
 
 需要稳定公网 HTTPS、并且你管理 Cloudflare 账号/域名时使用：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",

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/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/local-bridge/console-assets.ts

@@ -0,0 +1,17 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+
+export type ConsoleAssetName = "app.js" | "app.css";
+
+export function resolveConsoleAssetPath(
+  asset: ConsoleAssetName,
+  executablePath = process.execPath,
+): string | URL {
+  const releaseAssetPath = join(dirname(executablePath), "ui-dist", asset);
+  if (existsSync(releaseAssetPath)) return releaseAssetPath;
+  return new URL(`./ui-dist/${asset}`, import.meta.url);
+}
+
+export function readConsoleAsset(asset: ConsoleAssetName): string {
+  return readFileSync(resolveConsoleAssetPath(asset), "utf8");
+}

package/src/cli/local-bridge/server.ts

@@ -73,6 +73,7 @@ import {
   verifyEditSession,
 } from "../editing/edit-session";
 import { localBridgeDashboardHtml } from "./dashboard";
+import { readConsoleAsset, type ConsoleAssetName } from "./console-assets";
 import { applyConsoleAutomationAction, listConsoleAutomations, summarizeConsoleAutomations } from "./console-automations";
 import {
   ackConsoleHandoff,
@@ -994,7 +995,7 @@ export async function startLocalBridgeServer(
     if (asset !== "app.js" && asset !== "app.css") { response.status(404).end(); return; }
     response.setHeader("Cache-Control", "no-cache");
     response.type(asset.endsWith(".css") ? "text/css" : "application/javascript");
-    response.send(readFileSync(new URL(`./ui-dist/${asset}`, import.meta.url), "utf8"));
+    response.send(readConsoleAsset(asset as ConsoleAssetName));
   });
 
   app.get("/", (_request, response) => {

package/src/cli/mcp/auth.ts

@@ -21,6 +21,8 @@ export interface McpLocalConfig {
   chatgpt?: {
     serverName?: string;
     endpoint?: string;
+    /** Loopback OAuth MCP endpoint used by ChatGPT tunnels/connectors. */
+    localEndpoint?: string;
   };
   profile?: string;
   toolset?: 'core' | 'advanced' | 'full';

package/src/cli/mcp/setup.ts

@@ -303,6 +303,7 @@ export function runMcpSetupChatgpt(opts: {
   endpoint?: string;
   serverName?: string;
   localControllerPort?: string;
+  connectorPort?: string;
 }): McpSetupResult {
   const repoRoot = resolveMcpRepoRoot(opts.repo ?? ".");
   const controllerHome = opts.userLevel
@@ -319,6 +320,11 @@ export function runMcpSetupChatgpt(opts: {
     : 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 connectorPort = opts.connectorPort !== undefined
+    ? Number(opts.connectorPort)
+    : parsedPort <= 65_533 ? parsedPort + 2 : 8767;
+  if (!Number.isInteger(connectorPort) || connectorPort < 1 || connectorPort > 65_535) throw new Error(`forge mcp setup chatgpt: invalid connector port ${opts.connectorPort}`);
+  if (connectorPort === parsedPort || connectorPort === localControllerPort) throw new Error('forge mcp setup chatgpt: connector port must differ from Runtime and Local Controller ports');
   const existingServerName = existingConfig?.chatgpt?.serverName;
   const migratedServerName =
     existingServerName && !LEGACY_DEFAULT_SERVER_NAMES.has(existingServerName)
@@ -356,6 +362,7 @@ export function runMcpSetupChatgpt(opts: {
       ...existingConfig?.chatgpt,
       serverName,
       ...(endpoint ? { endpoint } : {}),
+      localEndpoint: `http://127.0.0.1:${connectorPort}/mcp`,
     },
     profile: existingConfig?.profile ?? "controller",
     toolset,
@@ -421,7 +428,8 @@ export function runMcpSetupChatgpt(opts: {
       "[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] Internal Runtime endpoint: http://${host}:${port}/mcp`,
+      `[forge mcp] ChatGPT local OAuth endpoint: http://127.0.0.1:${connectorPort}/mcp`,
       `[forge mcp] Local Controller: http://${config.localController.host}:${config.localController.port}/`,
       `[forge mcp] Optional external delegation: ${config.devMode.agentRunner ? `enabled (${config.devMode.allowedAgents.join(',') || 'none'})` : 'disabled'}`,
       endpoint

package/src/cli/mcp/transports/http.ts

@@ -95,6 +95,24 @@ function isInitializeRequest(body: unknown): boolean {
   return typeof body === 'object' && body !== null && (body as Record<string, unknown>).method === 'initialize';
 }
 
+function isServerDiscoverRequest(body: unknown): boolean {
+  return typeof body === 'object' && body !== null && (body as Record<string, unknown>).method === 'server/discover';
+}
+
+function sendLegacyServerDiscoverUnsupported(res: Response, body: unknown): void {
+  const record = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {};
+  const id = typeof record.id === 'string' || typeof record.id === 'number' || record.id === null ? record.id : null;
+  res.setHeader('Cache-Control', 'no-store');
+  res.status(404).json({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32601,
+      message: 'Method not found',
+    },
+  });
+}
+
 function initializeClientIdentity(req: Request, body: unknown, route: McpSessionRoute, principalId: string): string {
   const params = typeof body === 'object' && body !== null
     ? (body as { params?: { clientInfo?: { name?: unknown; version?: unknown } } }).params
@@ -676,6 +694,15 @@ async function handleMcpPost(
     return;
   }
   const sessionId = req.headers['mcp-session-id'] as string | undefined;
+  // MCP 2026-07-28 clients probe legacy servers with server/discover before
+  // falling back to the initialize-era protocol. Forge still serves the
+  // legacy stateful transport, so reject the unsupported modern RPC with the
+  // protocol-prescribed Method not found / HTTP 404 response instead of
+  // misclassifying it as a missing-session HTTP 400.
+  if (isServerDiscoverRequest(body)) {
+    sendLegacyServerDiscoverUnsupported(res, body);
+    return;
+  }
   if (isInitializeRequest(body)) {
     if (sessionId) {
       res.setHeader('Mcp-Session-Reset', 'reinitialized');

package/src/runtime/root/package-connector-service.ts

@@ -0,0 +1,136 @@
+import { createHash } from 'crypto';
+import { closeSync, mkdirSync, openSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { basename, dirname, join, resolve } from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { bootstrapLaunchAgentWithRetryV2, installLaunchAgent, launchAgentPath } from '../../cli/controller/launch-agents';
+import type { PackageRuntimeRelease } from './package-runtime-release';
+
+export interface PackageConnectorServicePaths {
+  label: string;
+  serviceRoot: string;
+  sourcePlistPath: string;
+  installedPlistPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+}
+
+export interface PackageConnectorServiceResult {
+  endpoint: string;
+  mode: 'launchd' | 'systemd-user' | 'portable';
+  persistent: boolean;
+  servicePath?: string;
+  pid?: number;
+}
+
+function xml(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+function atomicWrite(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+export function packageConnectorServicePaths(controllerHome: string, accountHome = process.env.HOME ?? homedir()): PackageConnectorServicePaths {
+  const home = resolve(controllerHome);
+  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
+  const label = `com.moretea.forge.mcp-gateway.${suffix}`;
+  const serviceRoot = join(home, 'runtime', 'connector-service');
+  return {
+    label,
+    serviceRoot,
+    sourcePlistPath: join(serviceRoot, `${label}.plist`),
+    installedPlistPath: launchAgentPath(label, accountHome),
+    stdoutPath: join(serviceRoot, 'logs', 'stdout.log'),
+    stderrPath: join(serviceRoot, 'logs', 'stderr.log'),
+  };
+}
+
+export function packageConnectorLaunchSpec(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
+  const parsed = new URL(input.endpoint);
+  const port = Number(parsed.port);
+  if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp' || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_ENDPOINT_INVALID');
+  }
+  const executable = resolve(input.executable ?? process.execPath);
+  const packageRoot = resolve(input.release.packageRoot);
+  const cliEntry = join(packageRoot, 'src', 'cli', 'index.ts');
+  const nodeLoader = join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
+  const isBun = Boolean(process.versions.bun) || /(?:^|[/\\-])bun(?:$|[/\\]|\.exe$)/i.test(basename(executable));
+  const cliArgs = [
+    'mcp', 'serve', '--repo', packageRoot, '--controller-home', resolve(input.controllerHome),
+    '--transport', 'http', '--host', '127.0.0.1', '--port', String(port), '--profile', 'controller', '--auth', 'oauth',
+  ];
+  return {
+    executable,
+    args: isBun ? [cliEntry, ...cliArgs] : ['--loader', nodeLoader, cliEntry, ...cliArgs],
+    environment: { FORGE_CONTROLLER_HOME: resolve(input.controllerHome), FORGE_CONTROLLER_LIFECYCLE_OWNER: '1' },
+    port,
+  };
+}
+
+export function renderPackageConnectorLaunchAgent(input: { paths: PackageConnectorServicePaths; launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const environmentXml = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join('\n');
+  const args = [input.launch.executable, ...input.launch.args];
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>${xml(input.paths.label)}</string>\n  <key>ProgramArguments</key>\n  <array>\n${args.map((arg) => `    <string>${xml(arg)}</string>`).join('\n')}\n  </array>\n  <key>EnvironmentVariables</key>\n  <dict>\n${environmentXml}\n  </dict>\n  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict><key>SuccessfulExit</key><false/></dict>\n  <key>ThrottleInterval</key><integer>5</integer>\n  <key>StandardOutPath</key><string>${xml(input.paths.stdoutPath)}</string>\n  <key>StandardErrorPath</key><string>${xml(input.paths.stderrPath)}</string>\n</dict>\n</plist>\n`;
+}
+
+export function renderPackageConnectorSystemdUserUnit(input: { launch: ReturnType<typeof packageConnectorLaunchSpec> }): string {
+  const quote = (value: string) => `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+  const env = Object.entries(input.launch.environment).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
+  return ['[Unit]', 'Description=Forge ChatGPT OAuth Gateway', 'After=network-online.target', '', '[Service]', 'Type=simple', `ExecStart=${[input.launch.executable, ...input.launch.args].map(quote).join(' ')}`, ...env, 'Restart=on-failure', 'RestartSec=5', '', '[Install]', 'WantedBy=default.target', ''].join('\n');
+}
+
+function installSystemd(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): string {
+  const unitName = `${paths.label}.service`;
+  const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
+  atomicWrite(unitPath, renderPackageConnectorSystemdUserUnit({ launch }), 0o644);
+  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+    const result = spawnSync('systemctl', args, { encoding: 'utf8', env, timeout: 30_000 });
+    if (result.status !== 0) throw new Error(`FORGE_PACKAGE_CONNECTOR_SYSTEMD_INSTALL_FAILED: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return unitPath;
+}
+
+function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<typeof packageConnectorLaunchSpec>, env: NodeJS.ProcessEnv): number {
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const stdout = openSync(paths.stdoutPath, 'a', 0o600), stderr = openSync(paths.stderrPath, 'a', 0o600);
+  // A connector is not the Canonical Runtime writer. Never let a transient
+  // installer/worker write claim escape into this long-lived process; the claim
+  // would become stale as soon as its parent exits. Keep only the explicit
+  // Controller Home and lifecycle-role marker from launch.environment.
+  const childEnv = { ...env };
+  for (const key of [
+    'FORGE_RUNTIME_INSTANCE_ID', 'FORGE_RUNTIME_OWNER_PID', 'FORGE_RELEASE_AUTHORITY_REVISION',
+    'FORGE_RELEASE_FENCING_TOKEN', 'FORGE_RELEASE_ID', 'FORGE_ARTIFACT_IDENTITY', 'FORGE_WORKER_PROTOCOL_VERSION',
+  ]) delete childEnv[key];
+  try {
+    const child = spawn(launch.executable, launch.args, { detached: true, stdio: ['ignore', stdout, stderr], env: { ...childEnv, ...launch.environment } });
+    if (!child.pid) throw new Error('FORGE_PACKAGE_CONNECTOR_START_FAILED');
+    child.unref();
+    return child.pid;
+  } finally { closeSync(stdout); closeSync(stderr); }
+}
+
+export async function installPackageConnectorService(input: { release: PackageRuntimeRelease; controllerHome: string; endpoint: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean }): Promise<PackageConnectorServiceResult> {
+  const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
+  mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
+  const launch = packageConnectorLaunchSpec({ release: input.release, controllerHome: input.controllerHome, endpoint: input.endpoint });
+  const platform = input.platform ?? process.platform, env = input.env ?? process.env;
+  if (!input.forcePortable && platform === 'darwin') {
+    atomicWrite(paths.sourcePlistPath, renderPackageConnectorLaunchAgent({ paths, launch }), 0o600);
+    installLaunchAgent(paths.sourcePlistPath, paths.label);
+    const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
+    if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
+    return { endpoint: input.endpoint, mode: 'launchd', persistent: true, servicePath: paths.installedPlistPath };
+  }
+  if (!input.forcePortable && platform === 'linux') {
+    const probe = spawnSync('systemctl', ['--user', 'show-environment'], { encoding: 'utf8', env, timeout: 30_000 });
+    if (probe.status === 0) return { endpoint: input.endpoint, mode: 'systemd-user', persistent: true, servicePath: installSystemd(paths, launch, env) };
+  }
+  return { endpoint: input.endpoint, mode: 'portable', persistent: false, pid: startPortable(paths, launch, env) };
+}

package/src/runtime/root/package-runtime-service.ts

@@ -14,6 +14,8 @@ import {
   type ForgeRuntimeServiceConfig,
 } from './service';
 import { materializePackageRuntimeRelease, type PackageRuntimeRelease } from './package-runtime-release';
+import { loadMcpServiceLocalConfig } from '../../cli/mcp/auth';
+import { installPackageConnectorService, type PackageConnectorServiceResult } from './package-connector-service';
 
 export type PackageRuntimeServiceMode = 'launchd' | 'systemd-user' | 'portable';
 
@@ -26,6 +28,7 @@ export interface PackageRuntimeServiceInstallResult {
   servicePath?: string;
   pid?: number;
   warnings: string[];
+  connector?: PackageConnectorServiceResult;
 }
 
 export interface PackageRuntimeServiceOptions {
@@ -147,26 +150,36 @@ export async function installPackageRuntimeService(options: PackageRuntimeServic
     repositoryRoot: release.packageRoot,
     host: options.host ?? '127.0.0.1',
     port: options.port ?? 8765,
-    authTokenFile: resolve(options.authTokenFile),
+    authTokenFile: options.authTokenFile,
     ...(options.exclusiveWorkId?.trim() ? { exclusiveWorkId: options.exclusiveWorkId.trim() } : {}),
   };
   writeForgeRuntimeServiceConfig(config);
   syncForgeRuntimeActiveEntrypoint(controllerHome);
   const platform = options.platform ?? process.platform;
   const env = options.env ?? process.env;
+
+  let base: PackageRuntimeServiceInstallResult;
   if (!options.forcePortable && platform === 'darwin') {
     const paths = await installForgeRuntimeService({ config, runnerPath: join(release.packageRoot, 'bin', 'forge-runtime-service.mjs'), nodeExecutable: process.execPath });
-    return { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
-  }
-  if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
+    base = { status: 'installed', mode: 'launchd', persistent: true, controllerHome, release, servicePath: paths.installedPlistPath, warnings: [] };
+  } else if (!options.forcePortable && platform === 'linux' && systemdUserAvailable(env)) {
     const unitPath = installSystemdUserService(controllerHome, env);
-    return { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+    base = { status: 'installed', mode: 'systemd-user', persistent: true, controllerHome, release, servicePath: unitPath, warnings: [] };
+  } else {
+    const pid = startPortableRuntime(controllerHome, env);
+    base = {
+      status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
+      warnings: [platform === 'win32'
+        ? 'Native Windows is preview: Forge started detached Runtime and OAuth Gateway processes for this session; automatic login/reboot persistence is not yet claimed.'
+        : 'systemd --user is unavailable: Forge started detached Runtime and OAuth Gateway processes; enable a user service manager for reboot persistence.'],
+    };
   }
-  const pid = startPortableRuntime(controllerHome, env);
-  return {
-    status: 'installed', mode: 'portable', persistent: false, controllerHome, release, pid,
-    warnings: [platform === 'win32'
-      ? 'Native Windows is preview: Forge started a detached user process for this session; automatic login/reboot persistence is not yet claimed.'
-      : 'systemd --user is unavailable: Forge started a detached user process; enable a user service manager for reboot persistence.'],
-  };
+
+  const localConfig = loadMcpServiceLocalConfig(controllerHome);
+  const connectorEndpoint = localConfig?.chatgpt?.localEndpoint;
+  if (!connectorEndpoint) return base;
+  const connector = await installPackageConnectorService({
+    release, controllerHome, endpoint: connectorEndpoint, platform, env, forcePortable: options.forcePortable === true,
+  });
+  return { ...base, connector };
 }

package/src/runtime/root/release-materialize.ts

@@ -29,6 +29,7 @@ export interface StagedRuntimeRelease {
   codeGraphNodeArtifactIdentity?: string;
   codeGraphSidecarArtifactIdentity?: string;
   codeGraphLibraryArtifactIdentity?: string;
+  controllerUiArtifactIdentity?: string;
   manifestSha256: string;
   sourceCommit: string;
 }
@@ -395,6 +396,17 @@ export function stageRuntimeRelease(input: {
     const codeGraphSidecarArtifactIdentity = `sha256:${sha256(codeGraphSidecarPath)}`;
     const codeGraphLibraryArtifactIdentity = `sha256:${sha256Directory(codeGraphLibraryPath)}`;
 
+    const controllerUiRoot = 'ui-dist' as const;
+    const sourceControllerUiPath = join(sourceRoot, 'src', 'cli', 'local-bridge', controllerUiRoot);
+    const sourceControllerUiJs = join(sourceControllerUiPath, 'app.js');
+    const sourceControllerUiCss = join(sourceControllerUiPath, 'app.css');
+    if (!existsSync(sourceControllerUiJs) || !existsSync(sourceControllerUiCss)) {
+      throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_SOURCE_MISSING: ${sourceControllerUiPath}`);
+    }
+    const controllerUiPath = join(staging, controllerUiRoot);
+    cpSync(sourceControllerUiPath, controllerUiPath, { recursive: true, force: false });
+    const controllerUiArtifactIdentity = `sha256:${sha256Directory(controllerUiPath)}`;
+
     const desktopHelperEntrypoint = 'forge-desktop-helper.mjs' as const;
     const sourceDesktopHelperPath = join(sourceRoot, 'bin', desktopHelperEntrypoint);
     if (!existsSync(sourceDesktopHelperPath)) {
@@ -429,6 +441,8 @@ export function stageRuntimeRelease(input: {
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryRoot,
       codeGraphLibraryArtifactIdentity,
+      controllerUiRoot,
+      controllerUiArtifactIdentity,
       arguments: [],
       configurationSchemaVersion: 1,
       controllerHome: resolve(input.controllerHome),
@@ -460,6 +474,7 @@ export function stageRuntimeRelease(input: {
       codeGraphNodeArtifactIdentity,
       codeGraphSidecarArtifactIdentity,
       codeGraphLibraryArtifactIdentity,
+      controllerUiArtifactIdentity,
       manifestSha256: createHash('sha256').update(`${JSON.stringify(manifest, null, 2)}\n`).digest('hex'),
       sourceCommit,
     };
@@ -506,4 +521,8 @@ export function assertRuntimeReleaseFiles(release: StagedRuntimeRelease): void {
   if (release.codeGraphLibraryArtifactIdentity && !existsSync(join(release.releasePath, 'codegraph-lib', 'dist', 'index.js'))) {
     throw new Error(`RUNTIME_RELEASE_CODEGRAPH_LIBRARY_MISSING: ${join(release.releasePath, 'codegraph-lib', 'dist', 'index.js')}`);
   }
+  if (release.controllerUiArtifactIdentity
+    && (!existsSync(join(release.releasePath, 'ui-dist', 'app.js')) || !existsSync(join(release.releasePath, 'ui-dist', 'app.css')))) {
+    throw new Error(`RUNTIME_RELEASE_CONTROLLER_UI_MISSING: ${join(release.releasePath, 'ui-dist')}`);
+  }
 }