@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -18,7 +18,7 @@ forge setup next
 The corresponding low-level commands are:
 
 ```bash
-forge mcp setup chatgpt --user-level
+forge mcp setup chatgpt --user-level --connector-auth none --clear-endpoint
 forge runtime service install-package
 forge runtime status --json
 ```
@@ -27,12 +27,14 @@ The Package Runtime does not require a Forge Git checkout, Bun compilation, Code
 
 ## Local boundaries
 
-Forge MCP remains loopback-only, normally at:
+The bearer-only Canonical Runtime remains loopback-only, normally at:
 
 ```text
 http://127.0.0.1:8765/mcp
 ```
 
+ChatGPT uses a separate loopback Connector (normally `127.0.0.1:8767/mcp`). With OpenAI Secure MCP Tunnel the Connector uses tunnel/workspace authority (`auth=none` locally) and must remain loopback-only. Public HTTPS providers expose this Connector with OAuth; they must never expose the bearer-only Runtime directly.
+
 The local Utility Console uses a separate loopback port (normally 8766). Never expose the Utility Console 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.
@@ -47,7 +49,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 supervised runtime surface and considers it ready only when the local Connector is configured for Secure Tunnel authority and `tunnel-client runtimes status forge --json` reports the runtime running, healthy, and ready. The loopback Connector is not a browser-facing OAuth authorization server.
 
 For public HTTPS paths, the configured connector URL is:
 

package/docs/forge-plugin-management.md

@@ -10,18 +10,34 @@ forge plugin catalog
 
 | Plugin ID | Product | Pinned release | Platforms |
 | --- | --- | --- | --- |
-| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.2.3` | macOS |
+| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.3.0` | macOS |
 | `design` | [Forge Design](https://github.com/moretea-labs/forge-design) | `v0.3.0` | macOS, Linux, Windows |
 | `personal_knowledge` | [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | `v0.2.1` | macOS, Linux, Windows |
 
 Investment Decision System remains an independent product and is intentionally not a Forge plugin.
 
-## Install and inspect
+## Product facades and generic provider management
+
+The native macOS provider has a product-level **Computer** facade. This is the preferred user surface:
+
+```bash
+forge computer setup
+forge computer status
+forge computer doctor
+forge computer update
+forge computer uninstall
+# destructive provider-state removal is explicit:
+forge computer uninstall --purge
+```
+
+`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.
+
+Generic provider administration remains available for diagnostics and non-Computer providers:
 
 ```bash
 forge plugin install design
 forge plugin install personal_knowledge
-forge plugin install desktop_operator   # macOS
+forge plugin install desktop_operator   # compatibility/advanced path on macOS
 forge plugin list --refresh
 ```
 
@@ -67,7 +83,7 @@ This split keeps Forge extensible without moving product-specific implementation
 
 ### `unix_socket_jsonl`
 
-Used by long-lived native providers such as Forge Desktop Operator. Forge connects to a stable local socket after trusted provider installation and lifecycle verification.
+Used by long-lived native providers such as Forge Desktop Operator. Forge connects to a stable local Unix socket on Unix hosts or a Windows named pipe on Windows after trusted provider installation and lifecycle verification; both use the same bounded JSONL protocol.
 
 ### `managed_cli_json`
 

package/docs/forge-runtime-self-healing-loop.md

@@ -4,4 +4,6 @@ The canonical Forge Runtime reconciles durable Work, Process, Lease, projection,
 
 The OS service manager automatically starts and restarts the single `forge-runtime` process. Standalone Recovery remains independently installable for diagnostics, service repair, tunnel repair, and offline whole-Runtime rollback when the primary Runtime cannot start.
 
+On macOS, an immutable compiled release keeps `forge-runtime` as the small, Developer-ID-signed stable service executable, while the full Canonical Runtime is a co-located `forge-runtime-bundle.js` artifact in the same release. The loader verifies the bundle SHA-256 declared by `manifest.json` before importing it; there is no source-checkout fallback. This preserves one Runtime/release/TCC authority without embedding the full application graph in Bun's standalone executable image.
+
 See [Failure Recovery](architecture/CURRENT.md), [Reliability runbook](operations/controller-reliability-runbook.md), and [Standalone disaster recovery](operations/standalone-disaster-recovery.md).

package/docs/operations/benchmark-cross-version-freeze.md

@@ -0,0 +1,38 @@
+# Cross-version benchmark freeze authority
+
+This runbook is an audit index for the S5 cross-version freeze. Machine authority lives in `evaluation/frozen-cross-version-authority.json`, `evaluation/aa-calibration.json`, `evaluation/baselines/v1.7.2/reconstruction.json`, and `evaluation/baselines/v1.7.2/authority.json`; this document never overrides those records.
+
+## Frozen S5 authority
+
+- Evaluator implementation: `sha256:7c3b8c1417dbd71705bd53649289a525217cc218392a65b45067a2845bfb367a`
+- Shared corpus: `sha256:cd45a4ff9b3a5a7b84aed736f72fd7d920115225c2b35fcb74fd0e80337233ee`
+- Formal protocol: `sha256:b383b97aacc5995ba69525d1aac5f031046c8708db3c32011e484444818d2700`
+- Baseline identity: `sha256:1a496185beb3776588884b4cac513a23b65a44a66f54e506eab0d3fe1ef6f727`
+- Baseline reconstruction: `sha256:d9a0a99a5bf7eeccdbaf2f186bceeaf8a29b33400e8ac6d9c21edfb1d0d0fc3b`
+- Baseline output authority: `sha256:46f99c71b4ae68d2e2dc9741f51a8bfa5cac06155011e997d00b982ffd44438d`
+- A/A calibration: `sha256:ef8a99ff549481779a35158abe7a8b2e1c86d67f04771665f7623f20dcb3f2ea`
+- Environment policy: `sha256:5f740890588e533517eb8878e2326867e911d5b6a9240c7dcdba2272883c5904`
+
+The evaluator identity includes the `01616fdbc55da77a9bad34ac94bc382c9fdd811a` process-isolation supervision repair and the candidate-neutral execution, validation, statistics, baseline-validation, and process-tree dependencies listed by `CROSS_VERSION_EVALUATOR_FILES`. Any change to those inputs creates a new evaluator authority and requires a new S5 A/A calibration before S6 evidence is valid.
+
+## Reproducible v1.7.2 baseline
+
+The source remains tag `v1.7.2`, commit `c873cfeb11a223ced342e7101c016261b4a93b38`, with published tarball SHA-256 `2073bf8a6ab377e63ebe109c197039647bcf0626fb357954156c9f83f429fb10`.
+
+The historical runnable artifact `sha256:52ef73f9299d84895cd1a0692bf53023608dff6bc4ba29942a8f8d2bc3837db0` is retained only as historical evidence. The current S5 baseline is rebuilt from the exact published tarball plus the committed normalized release lock and exact installer recipe. Two independent strictly-offline builds produced the same full runnable artifact `sha256:1a0bb50ad97c414f4c553ef790b29c8786a76d0f6ca29e04bbd9fed3bb46d43e`.
+
+The output authority also binds the production dependency graph: 100 package entries, 99 unique content blobs, graph digest `sha256:4acfb83f4e977d16a077020e3c3279dedaf7e307f12d06a99d8fb2701c78c16c`. Temporary build directories and cleaned Process records are audit evidence, not reconstruction dependencies.
+
+## v1.7.2 A/A calibration
+
+Fresh A/A Process `proc_v2_aa_evaluator7c3b_20260909` used the same current baseline artifact on both arms across the 24-scenario shared corpus. All 48 trials passed with zero candidate failures or timeouts. The evaluator implementation digest is `sha256:7c3b8c1417dbd71705bd53649289a525217cc218392a65b45067a2845bfb367a`.
+
+For latency, the signed delta is arm B minus arm A, one paired sample per scenario. Mean delta was `10.462 ms`, p50 `2.156 ms`, p95 `103.154 ms`, with 16 positive and 8 negative samples. The scenario-blocked 95% confidence interval was `[-9.992 ms, 30.915 ms]`; because it crosses zero, the run does not establish a systematic harness arm advantage. This is symmetry/noise calibration only, never V2 superiority evidence or a regression tolerance.
+
+The raw evidence bundle is `/tmp/forge-v2-aa-evaluator7c3b-run`; its `rawBundleDigest` is `sha256:05247c1e36e2917aefec2f972a5ade7be8ae493313abb6c38c2de130a4756fbc`. It is reproducible as `sha256(JSON.stringify(manifest))`, where `manifest` has schema `forge-aa-raw-bundle-manifest/v1` and lists every raw JSON file sorted by relative path with its SHA-256 and byte length. Earlier S5 commits stored raw bundle digests without preserving their construction algorithm, so this documented convention starts with this freeze rather than pretending that missing provenance existed.
+
+## Process-isolation and S6 gate
+
+`package:check:evaluation-framework` must pass on the frozen source before S5 is accepted. Timed candidate and warmup paths must reclaim evaluator-owned process trees; any recurrence of residual children invalidates the freeze rather than justifying threshold adjustment or result filtering.
+
+S6 must not start until Kernel V2 has an immutable release candidate. Formal A/B must use the exact frozen evaluator, corpus, protocol, baseline, A/A, and environment authorities above, keep shared-capability A/B separate from V2-only expansion, and keep correctness/reliability blocking ahead of efficiency or performance gains.

package/docs/operations/controller-browser-plugin.md

@@ -28,10 +28,12 @@ Interactions that can mutate remote state still require `confirm_authorization=t
 - the provider is local browser automation: configured loopback CDP, macOS Apple Events for an already-running Chrome/Vivaldi tab, or a Playwright persistent context
 - the default profile mode is `repo_local`, with profile data under `.forge/browser/profiles/`
 - `profileMode=custom` is explicit-only and uses the configured Chromium-family profile path directly when launching a managed context
-- saved sessions live under `.forge/browser/sessions/`
+- controller-home BrowserSession state is authoritative; legacy `.forge/browser/sessions/*.json` files are imported once and then removed
 - screenshots live under `.forge/browser/screenshots/`
 - downloads live under `.forge/browser/downloads/`
 
+Runtime maintenance bounds repository-local browser artifacts: upload staging is retained for 24 hours and screenshots for seven days. Profiles, downloads, diagnostics, and user-created review artifacts are not included in this automatic cleanup.
+
 The browser mode is explicit:
 
 - `attach_preferred` is the default. It uses a strict order: configured loopback CDP endpoints; then an already-running, scriptable macOS Google Chrome or Vivaldi instance; then `cdpAttachFallback`. The default fallback is `managed_persistent`, so Forge only launches its own Playwright browser after attach paths are unavailable. CDP inventory reuses a previously owned matching tab. Apple Events prefers the frontmost supported browser, otherwise Chrome before Vivaldi; it can reuse a unique existing tab at the requested URL, otherwise creates a plugin-owned background tab while preserving the user's active tab, and reattaches directly to the saved window/tab identity on later actions.

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.7.2` exists on npm;
-- Git tag and GitHub Release `v1.7.2` exist and point to the tested commit;
+- `@moretea-labs/forge@1.8.0` exists on npm;
+- Git tag and GitHub Release `v1.8.0` 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/operations/platform-support.md

@@ -4,12 +4,14 @@ This document defines the currently claimed Forge user experience. It distinguis
 
 ## Support matrix
 
-| Platform | Status | Normal user path |
-| --- | --- | --- |
-| macOS | Supported | Package install, controller-first setup, Package Runtime via launchd, repositories, local files, MCP, browser/desktop providers, and plugins. |
-| Modern Linux | Supported | Package install, controller-first setup, Package Runtime via `systemd --user` when available, repositories, local files, MCP, and portable providers. |
-| WSL2 on Windows | Supported and recommended for Windows | Run the Linux Forge Runtime inside WSL2; Windows can still host ChatGPT/browser clients. |
-| Native Windows | Preview | Package install, setup, portable Runtime/MCP, repository registration/inspection, and portable capabilities. Automatic reboot-persistent Runtime ownership and every external provider combination are not yet claimed. |
+| Platform | Runtime | Controller / MCP | Browser | Native Desktop / Computer | Recovery | Service persistence |
+| --- | --- | --- | --- | --- | --- | --- |
+| macOS | **Supported.** Packaged Runtime is the normal path. | **Supported.** Local and explicit remote MCP/controller setup are normal product paths. | **Supported.** Browser semantics use product discovery/registration rather than a developer-specific executable or profile. | **Supported when the registered macOS Computer provider is installed and healthy.** Missing provider/permission state is reported per capability. | **Advanced.** Standalone Recovery remains a maintainer capability, not an installation prerequisite. | **Supported** through the user launchd owner. |
+| Modern Linux | **Supported.** Packaged Runtime is the normal path. | **Supported.** Local and explicit remote MCP/controller setup are normal product paths. | **Supported** for portable Browser-side Computer capabilities. | **Not claimed** for native Desktop interaction. | **Not claimed as a normal-user prerequisite.** Recovery remains capability/host-specific. | **Supported** through `systemd --user` when available; otherwise Forge selects an explicit **non-persistent portable** session and reports that limitation. |
+| WSL2 on Windows | **Supported and recommended for Windows.** The Linux Runtime runs inside WSL2. | **Supported.** Windows may host ChatGPT/browser clients while WSL owns the Forge Runtime. | **Supported** through discovered Windows browser interop and, when allowed, a dedicated Forge-controlled Chromium profile. | **Partial.** Browser capability may be usable while native Desktop capabilities remain non-ready until a truthful Windows-host provider exists. | **Supported for the Windows-host Recovery binding** when Windows environment/mount discovery succeeds; paths are derived from the host rather than a fixed drive or username. | WSL uses `systemd --user` when available or the explicit portable fallback; native Windows Runtime reboot persistence is not implied. |
+| Native Windows | **Preview.** Portable package/runtime use is tested at the advertised surface. | **Preview.** Setup/MCP and repository inspection are tested, but shell-heavy parity is not claimed. | **Preview / capability-specific.** Do not infer every browser/provider integration from OS support. | **Not claimed.** | **Not claimed as native Runtime persistence.** The Windows-host Recovery capability is a distinct WSL/host binding. | **Portable only / preview.** Automatic reboot-persistent Runtime ownership is not claimed. |
+
+For scheduled ChatGPT Controller continuation on WSL2, Forge uses the existing ChatGPT Bridge authority rather than macOS native browser attach. The bridge keeps its capability token in the controller-scoped ChatGPT browser binding, opens the exact ChatGPT target through Windows browser interop, and treats prompt dispatch as complete only after the browser extension reports the postcondition. Forge may automatically provision only a dedicated Forge-controlled Chromium profile when the detected runtime explicitly supports unpacked-extension startup; that profile is separate from the user's ordinary browser profile. Google Chrome is not treated as automatic unpacked-extension bootstrap authority. An already enabled compatible bridge extension in an explicitly selected Chrome profile may be observed and reused, but otherwise setup returns a precise resumable user action instead of mutating or restarting the user's normal Chrome profile. This host bootstrap remains transport state, not a second Browser session authority.
 
 ## Base installation requirements
 
@@ -26,7 +28,7 @@ Capability-specific dependencies include:
 - Git for repository adoption, Git operations, worktrees, commits, and source development;
 - Codex or Claude only when explicitly configured as an external controller/execution entry;
 - GitHub CLI for GitHub workflows that require it;
-- browser/OS provider prerequisites for browser or desktop automation;
+- Computer provider prerequisites for Browser or native Desktop interaction; Forge discovers supported Chromium-family products instead of binding readiness to one developer browser/path;
 - Google/Apple/service credentials for their respective plugins;
 - one remote connection provider when a hosted controller must reach the loopback MCP endpoint.
 
@@ -67,4 +69,10 @@ The native PowerShell path is release-tested for installer/CLI loading, doctor,
 
 ## Verification boundary
 
-The repository has platform/public-doc checks and a Windows smoke workflow. A platform claim means its named path is tested; it does not imply that every optional third-party provider is installed or available on every machine.
+Portability is checked at two separate layers:
+
+- `check:platform-support` is the static anti-binding gate. Product/runtime surfaces may not encode personal absolute home paths as deployment authority, and the documented package/runtime contracts must remain present.
+- `check:portable-package` installs the packed npm artifact into a temporary application with an isolated `HOME`, `XDG_STATE_HOME`, npm cache, and `FORGE_CONTROLLER_HOME`. It exercises the packaged CLI/hook without Bun or pre-existing Forge state and rejects source-checkout leakage into Controller state.
+- The Windows smoke workflow covers the advertised native PowerShell/Node preview surface. Platform-specific live provider checks remain capability-scoped rather than being inferred from the operating-system name.
+
+A platform claim therefore means its named capability path is tested; it does not imply that every optional third-party provider is installed or available on every machine.

package/docs/operations/platform-support.zh-CN.md

@@ -6,7 +6,7 @@
 
 | 平台 | 状态 | 普通用户路径 |
 | --- | --- | --- |
-| macOS | 支持 | Package 安装、主控优先 setup、launchd Package Runtime、仓库/普通目录、MCP、Browser/Desktop 与插件。 |
+| macOS | 支持 | Package 安装、主控优先 setup、launchd Package Runtime、仓库/普通目录、MCP、插件与统一 `Computer` 产品。Browser 语义内置；原生 Desktop 语义需要已注册的 macOS Computer provider。 |
 | 现代 Linux | 支持 | Package 安装、主控优先 setup、优先 `systemd --user` 的 Package Runtime、仓库/普通目录、MCP 与可移植 Provider。 |
 | Windows + WSL2 | 支持且为 Windows 推荐路径 | Forge Runtime 在 WSL2 内按 Linux 方式运行；Windows 仍可承载 ChatGPT/浏览器客户端。 |
 | Windows 原生 | 预览 | Package 安装、setup、portable Runtime/MCP、仓库注册/读取和可移植能力；暂不宣称重启后 Runtime 自动持久化和所有外部 Provider 组合都完整。 |
@@ -21,7 +21,7 @@
 
 **Git 只在启用仓库/软件开发能力时才需要。** 普通 package 用户不要求 Bun、Forge 源码 checkout、CodeGraph、Codex、Claude、Standalone Recovery、Cloudflare、Tailscale 或 OpenAI tunnel-client。
 
-按能力才出现的依赖包括：Git 仓库操作；明确选择的 Codex/Claude 主控或执行入口；GitHub CLI；Browser/Desktop 平台依赖；Google/Apple 等账号凭证；以及远程主控连接本机 MCP 时选择的 tunnel/provider。
+按能力才出现的依赖包括：Git 仓库操作；明确选择的 Codex/Claude 主控或执行入口；GitHub CLI；Computer Browser/Desktop provider 平台依赖；Google/Apple 等账号凭证；以及远程主控连接本机 MCP 时选择的 tunnel/provider。
 
 ## 各平台 Runtime owner
 

package/docs/operations/standalone-disaster-recovery.md

@@ -106,12 +106,29 @@ forge recovery install \
 
 Use `--stage-only` to build and canary without activating Gateway or Watchdog services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface.
 
-A public Recovery endpoint is optional for local-only operations. A ChatGPT Recovery Connector requires an explicit HTTPS Recovery URL and its dedicated tunnel service owner. Print the exact non-secret connector descriptor with:
+A public Recovery endpoint is optional for local-only operations. A ChatGPT Recovery Connector requires one independently owned external transport: either an explicit HTTPS Recovery URL plus its dedicated tunnel service owner, or a dedicated OpenAI Secure MCP Tunnel. The OpenAI transport keeps the Recovery Gateway on loopback; `tunnel-client` is the outbound transport and is supervised separately from the primary Forge Runtime/Connector.
+
+For a Windows/WSL Recovery installation, create a new OpenAI tunnel identity that is not the primary Forge tunnel and is not the macOS Recovery tunnel. Supply only that dedicated tunnel id and an approved runtime-key reference; omit the alias unless an explicit stable alias is required. Forge derives a machine-specific Recovery alias from host, platform, and Controller Home and rejects alias/tunnel-id reuse with the primary tunnel configured on the same machine:
+
+```sh
+forge recovery install \
+  --controller-home /home/<user>/.forge/controller \
+  --recovery-openai-tunnel-id <dedicated-wsl-recovery-tunnel-id> \
+  --recovery-openai-runtime-api-key-ref env:FORGE_RECOVERY_TUNNEL_KEY
+```
+
+The runtime key value is never copied into Recovery configuration or status; only the `env:`/`file:` reference is stored. The local Recovery Gateway remains bound to `127.0.0.1`.
+
+Print the exact non-secret connector descriptor with:
 
 ```sh
 forge recovery connector --controller-home /absolute/controller-home
 ```
 
+The descriptor and `runtime_status` expose a `RecoveryMachineIdentity` containing host, platform, resolved Controller Home, current Recovery release identity, and the exact target Runtime service/release identity. Every external Recovery mutation requires the caller to echo the current `expected_host`, `expected_platform`, `expected_controller_home`, `expected_recovery_release`, and `expected_target_runtime` values from that observation. Missing, stale, or cross-machine values are rejected before any mutation. Successful mutation responses include the post-operation machine identity as well. This makes accidentally selecting the macOS Recovery connector while intending to repair WSL fail closed rather than repairing the wrong machine.
+
+Because Gateway, Watchdog, immutable Recovery release, and the dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, a primary Runtime outage does not remove this external Recovery control path.
+
 The installer owns publication and activation. Before registering `com.moretea.forge-recovery-gateway` and `com.moretea.forge-recovery-watchdog`, it exits and removes stale Recovery services discovered under the Recovery-owned launchd directory. Configuration is rewritten from the current schema and does not preserve retired ingress, agent-repair, or legacy tunnel fields. Direct reload scripts are not a second mutation path.
 
 Forge deliberately has no blue-green Runtime topology. There is one active whole-release authority and one canonical service. Candidate validation happens before activation; activation stops the complete Runtime, switches the atomic active release, starts one Runtime, and gates on whole-Runtime readiness. Failure restores the previous whole release and its bound SQLite backup.
@@ -134,3 +151,11 @@ forge recovery activate-runtime --controller-home /absolute/controller-home --re
 ```
 
 `forge runtime status --controller-home /absolute/controller-home` reads the canonical Runtime status projection. `forge runtime service install --stage-only` builds and validates an immutable Runtime release without publishing it; the staged manifest can then be activated through `forge recovery activate-runtime` when the primary Runtime is fenced or unavailable.
+
+## Local Recovery transport adapter
+
+The controller may install the `local_recovery` external Assistant Plugin when the independently configured ChatGPT Recovery Connector is unavailable or bound to a stale external transport while the primary Runtime is still healthy enough to host plugins. This adapter is a transport client only; it is not another Runtime lifecycle authority.
+
+The managed helper is `scripts/forge-local-recovery-helper.mjs`. Its provider configuration contains only the absolute installed `controllerHome`. The helper loads the installed Recovery configuration and scoped Gateway token from that Controller Home, requires the Recovery Gateway endpoint to remain loopback, and invokes only allowlisted Recovery MCP tools. The initial action surface is `runtime_status`, `list_releases`, and `stage_and_activate_runtime_release`; every action has an empty caller argument schema. In particular, callers cannot supply a source root, release path, endpoint, token path, executable, command, tunnel identity, or mutation request id.
+
+`stage_and_activate_runtime_release` delegates to the existing standalone Recovery MCP tool of the same name. Staging source authority, Repository Registry provenance, Recovery mutation locking, active/previous whole-release authority, SQLite backup/rollback, launch-service ownership, and post-activation verification therefore remain entirely owned by standalone Recovery. The adapter is useful for in-band maintenance while the primary Runtime is alive; it does not replace the independent Recovery Connector for disaster recovery when the primary Runtime itself is unavailable.

package/docs/operations/uu-remote-rescue.md

@@ -0,0 +1,41 @@
+# UU Remote emergency rescue
+
+Forge can install an optional **controller-scoped** `uu_remote_rescue` plugin on the macOS emergency operator. It exists only to recover the already-authoritative Windows/WSL Forge when the primary Forge Connector/Runtime and the WSL Recovery endpoint cannot be reached.
+
+## Authority boundary
+
+- `uuyc-cli` is the device identity and terminal-connection authority. The plugin stores only the exact non-secret device id/name, expected Windows platform, WSL distro, and remote Controller Home path.
+- Forge Desktop Operator remains the macOS Accessibility/TCC authority. The helper talks to its stable Unix socket and never gives `forge-runtime` direct Accessibility permissions.
+- WSL `systemd --user` remains the service owner. Start/restart actions target only the canonical Runtime/Connector unit names derived from the configured Controller Home and the fixed Recovery gateway/watchdog units.
+- `runtime_recover` invokes only the existing `forge recovery recover --controller-home <configured-home>` whole-release recovery transaction. The macOS machine never becomes another Forge Runtime authority.
+
+There is intentionally no action accepting a device selector, service name, path override, command, script, shell fragment, or password/token. A wrong device identity or offline device is rejected before the terminal is opened or a remote mutation is attempted.
+
+## Install
+
+Run from the trusted Forge package/source that contains the helper:
+
+```bash
+bun scripts/install-uu-remote-rescue-registration.ts \
+  --controller-home "$HOME/.forge/controller" \
+  --device-id '<exact uuyc-cli device id>' \
+  --device-name '<exact device name>' \
+  --wsl-distro '<exact WSL distro>' \
+  --remote-controller-home '/home/<user>/.forge/controller'
+```
+
+The installer writes a mode-0600 non-secret config below Controller Home and a normal external-plugin registration using the existing `managed_cli_json` transport. It does not persist UU Remote unlock codes, passwords, OAuth material, bearer tokens, or clipboard contents.
+
+## Typed actions
+
+`device_status` performs exact identity/online observation without opening a terminal. `wsl_status` and `forge_health` open the exact configured UU terminal transiently and send built-in observation commands. `runtime_start`, `runtime_restart`, `connector_start`, `connector_restart`, `recovery_start`, and `recovery_restart` operate only the derived/fixed systemd-user units. `runtime_recover` delegates the rollback/restart/verification transaction to canonical standalone Recovery logic.
+
+The helper saves the current macOS clipboard only in process memory, uses it to paste the fixed command into the exact UURemote terminal session, restores the clipboard in `finally`, closes the Desktop Operator session, and clears the transient UU remote shell. Clipboard contents are never returned in plugin results or written to disk.
+
+## Health payload
+
+`forge_health` returns structured data for the configured WSL distro including Controller Home presence, `control-plane.sqlite`, Runtime owner/status files, Connector authority, Recovery config presence, canonical systemd service states, and the latest `controller_home_migration` record when `sqlite3` is available in WSL. Missing `sqlite3` is reported as bounded migration-state unavailability rather than guessed state.
+
+## Operational caveat
+
+UU Remote terminal interaction requires an unlocked macOS GUI session because Desktop Operator deliberately refuses foreground input while the console is locked. This is a fail-closed condition; the rescue plugin does not add coordinate automation, OCR, login-window automation, or a raw remote-shell fallback.

package/docs/operations/windows-wsl-host-rescue.md

@@ -0,0 +1,133 @@
+# Independent Windows/WSL host rescue
+
+This is the emergency availability path for a Forge installation whose normal
+Runtime, Connector, Controller, or existing Recovery Gateway cannot be used.
+It is a small fixed-command agent installed outside both the Forge source
+checkout and Controller Home:
+
+```text
+GREYSON-DESKTOP / Windows
+  C:\ProgramData\ForgeRecovery\ForgeRecovery.ps1
+       |
+       | wsl.exe --distribution <exact distro> --exec <exact agent> <fixed action>
+       v
+WSL /home/<user>/.forge-recovery/
+  forge-wsl-rescue + root-owned config + one systemd --user watchdog
+       |
+       +-- canonical Runtime systemd unit
+       +-- canonical Secure-Tunnel Connector systemd unit
+       +-- exact OpenAI Secure Tunnel runtime alias
+```
+
+The two scripts are copied as bootstrap artifacts. Their normal operation does
+not read a Forge checkout, call Forge MCP, invoke the Controller, use the
+Controller database, or execute a supplied shell command. The only mutable
+state they own is their configuration and a cross-process lock below
+`/home/<user>/.forge-recovery`; Runtime releases, database backups, schedules,
+and Controller state remain under the canonical Controller Home.
+
+## Fixed action surface
+
+The Windows wrapper validates one fixed action before it calls WSL. The WSL
+agent accepts only these action names:
+
+```text
+host_status
+wsl_status, wsl_start
+forge_source_status, controller_status
+runtime_status, runtime_start, runtime_restart
+connector_status, connector_start, connector_restart
+recovery_status, recovery_start, recovery_restart
+tunnel_status, tunnel_start, tunnel_restart
+forge_cloud_verify, full_recover
+```
+
+There is intentionally no `execute`, `powershell`, `bash`, or arbitrary-command
+action. All lifecycle mutations acquire the same rescue-root lock. The Windows
+logon task is only a cold-start trigger; it delegates the actual mutation to
+that WSL lock owner and holds no release, database, tunnel, or lifecycle state.
+
+`full_recover` starts the one configured independent Recovery service, then the
+exact canonical Runtime and Connector units, waits for the local MCP
+endpoint, reconnects the exact tunnel alias when needed, and verifies both
+local MCP reachability and tunnel readiness. It never selects a release,
+changes Controller Home, edits source, or falls back to another host.
+
+## Bootstrap
+
+Run the installer directly from a clean WSL source checkout. It is a bootstrap
+script, not a Forge Runtime command:
+
+```sh
+bun scripts/install-independent-windows-wsl-recovery.ts \
+  --distro UbuntuDev \
+  --controller-home $HOME/.forge/controller \
+  --tunnel-client $HOME/.local/bin/tunnel-client \
+  --tunnel-alias forge \
+  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
+  --tunnel-profile forge \
+  --tunnel-profile-dir $HOME/.config/tunnel-client \
+  --tunnel-admin-profile default \
+  --install-windows-logon-task
+```
+
+Use `--stage-only` to write and inspect the external artifacts without enabling
+the WSL watchdog. The installer fails closed unless the Controller Home is the
+canonical user-level path (`/home/<user>/.forge/controller`) and the rescue
+root is exactly `/home/<user>/.forge-recovery`.
+
+Windows Task Scheduler may require elevation to create the optional logon task.
+When that happens, the installer still reports the installed WSL rescue and
+returns `windowsLogonTask.installed=false` with the exact Scheduler error; the
+fixed-action host script is still available for an elevated administrator to
+register later. Do not replace it with a second background service.
+
+The agent contains no tunnel credential. Its configuration holds only a
+`file:` reference below the independent rescue root; `tunnel-client` reads the
+permissioned value only when reconnecting. Before retiring a legacy Controller
+Home, move that reference to the rescue root or the canonical Controller Home
+and confirm the profile resolves it there.
+
+## Controller Home cutover
+
+For the retired repo-local home, use the separate direct migration bootstrap.
+Its default invocation is read-only and fails closed if both legacy and
+canonical Runtime/Connector units are active:
+
+```sh
+bun scripts/migrate-windows-wsl-controller-home.ts \
+  --source-home $HOME/src/forge/_ops/controller-home \
+  --destination-home $HOME/.forge/controller
+```
+
+Only after its preflight is correct, repeat the exact command with `--execute`.
+The transaction stops the legacy Runtime and Connector, copies the complete
+Controller Home into a staged sibling, preserves the prior canonical directory,
+rewrites only known service path references, preserves the legacy
+Controller-bound release authority as evidence, stages and publishes one fresh
+whole Runtime release from the clean WSL checkout, installs the canonical unit
+pair, and requires both local MCP endpoints before retiring the legacy unit
+files. A failed cutover stops the canonical pair, restores the prior canonical
+directory/unit files, and starts the legacy pair again. It never deletes either
+Controller Home or performs database cleanup.
+
+For this Secure Tunnel path, the Connector remains bound to `127.0.0.1` and is
+started with `--auth none`: the authenticated OpenAI Secure Tunnel is the only
+external ingress and authorization boundary. Do not reuse this unit for an
+HTTPS/public connector; that separate topology requires its own OAuth setup.
+
+## Operational acceptance
+
+After installation, invoke the following fixed actions from Windows PowerShell:
+
+```powershell
+& 'C:\ProgramData\ForgeRecovery\ForgeRecovery.ps1' host_status
+& 'C:\ProgramData\ForgeRecovery\ForgeRecovery.ps1' full_recover
+& 'C:\ProgramData\ForgeRecovery\ForgeRecovery.ps1' forge_cloud_verify
+```
+
+Then perform the recoverable drill sequence: restart Runtime, verify; restart
+Connector, verify; restart tunnel, verify; restart the WSL user service and
+verify all three. A stopped Runtime must be restored by `full_recover` without
+depending on Forge's normal execution surface. Do not use this path to delete a
+Controller database, source checkout, release, or credential.

package/docs/public-usage-guide.md

@@ -18,7 +18,7 @@ forge setup next
 
 ## 2. Follow setup until the selected path is usable
 
-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`.
+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 ChatGPT Connector: Secure Tunnel uses tunnel/workspace authority there, while public HTTPS providers use OAuth there. 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 完成所选路径
 
-对 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`。
+对 ChatGPT，`--tunnel auto` 会优先 OpenAI Secure MCP Tunnel，不会因为机器上恰好安装了 cloudflared/Tailscale 就静默改用公网入口。Package setup 会保持 bearer-only Canonical Runtime 私有，并管理独立的 loopback ChatGPT Connector：Secure Tunnel 在这里使用 tunnel/workspace authority，公网 HTTPS provider 则在这里使用 OAuth。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

@@ -90,7 +90,7 @@ 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.
+For ChatGPT setups this installs two local service boundaries together: the bearer-only Canonical Runtime and a separate loopback ChatGPT Connector. OpenAI Secure MCP Tunnel uses tunnel/workspace authority at that Connector, while public HTTPS providers use OAuth there. Never tunnel 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.
 

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

@@ -90,7 +90,7 @@ 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 为准。
+对 ChatGPT，package 安装会同时维护两个本地服务边界：内部 bearer-only Canonical Runtime，以及独立的 loopback ChatGPT Connector。OpenAI Secure MCP Tunnel 在这个 Connector 上使用 tunnel/workspace authority，公网 HTTPS provider 则在这里使用 OAuth。绝不能把 tunnel 直接指向内部 Runtime 端口。
 
 旧的 `forge runtime service install --repo ...` 会构建 Git/source immutable Runtime，属于**高级维护路径**；Standalone Recovery 同样不是普通用户初始化的前置条件。
 

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

@@ -76,7 +76,7 @@ Forge reports this provider ready only when `tunnel-client` reports the managed
 
 #### 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`.
+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 Secure Tunnel Connector** (default `127.0.0.1:8767/mcp`), which proxies to the internal bearer-only Runtime (default `127.0.0.1:8765/mcp`). The Connector uses the OpenAI tunnel/workspace as its outer authorization boundary (`auth=none` locally); it is not a browser-facing OAuth authorization server and must remain loopback-only. `forge setup next` keeps this transport-specific auth mode aligned automatically.
 
 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.
 
@@ -89,7 +89,7 @@ forge setup configure --controller chatgpt --tunnel cloudflare
 forge setup next
 ```
 
-Setup detects `cloudflared` and the current platform. On macOS it can suggest Homebrew when present; Linux/WSL2 and Windows receive their platform-specific official installation path. After creating a stable named tunnel, record only the resulting `/mcp` URL:
+Setup detects `cloudflared` and the current platform. On macOS it can suggest Homebrew when present; Linux/WSL2 and Windows receive their platform-specific official installation path. The public tunnel must terminate at the loopback OAuth Connector (normally port `8767`), never the bearer-only Runtime. After creating a stable named tunnel, record only the resulting `/mcp` URL:
 
 ```bash
 forge setup configure \
@@ -107,7 +107,7 @@ forge setup configure --controller chatgpt --tunnel tailscale
 forge setup next
 ```
 
-Forge detects the Tailscale CLI and guides Funnel setup for the current platform. Record the final HTTPS `/mcp` URL when available.
+Forge detects the Tailscale CLI and guides Funnel setup for the current platform. Funnel exposes the loopback OAuth Connector (normally port `8767`), never the bearer-only Runtime. Record the final HTTPS `/mcp` URL when available.
 
 ### D. Existing HTTPS endpoint or defer
 
@@ -127,7 +127,7 @@ Cloudflare/Tailscale/existing HTTPS make the MCP endpoint public or internet-rea
 
 The ChatGPT UI changes over time, so follow the current OpenAI developer-mode instructions rather than relying on screenshots in this repository.
 
-For a Secure MCP Tunnel connection, choose the **Tunnel** connection type and select/paste the tunnel ID. For an HTTPS connection, use the stable HTTPS URL ending in `/mcp` and the OAuth flow generated by Forge.
+For a Secure MCP Tunnel connection, choose the **Tunnel** connection type, select/paste the tunnel ID, and choose **No authentication**: the authenticated OpenAI Tunnel is the external authorization boundary. For an HTTPS connection, use the stable HTTPS URL ending in `/mcp` and the OAuth flow generated by Forge.
 
 After creating the app/connector, scan/refresh tools. Do not switch Forge to an exhaustive compatibility toolset simply to expose more names; the bounded default surface is intentional.
 

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

@@ -74,7 +74,7 @@ tunnel-client runtimes status forge --json
 
 #### 地址到底变成什么？
 
-使用 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 为准。
+使用 Secure Tunnel 后，不再需要给 Forge 准备公网 `/mcp` 地址。ChatGPT App 选择 `tunnel_id`；本机 `tunnel-client` 把命令转发到 Forge 的 **loopback Secure Tunnel Connector**（默认 `127.0.0.1:8767/mcp`），再由 Connector 代理到内部 bearer-only Runtime（默认 `127.0.0.1:8765/mcp`）。这个 Connector 以 OpenAI tunnel/workspace 作为外层授权边界，本地使用 `auth=none`；它不是浏览器可访问的 OAuth authorization server，而且必须保持 loopback-only。`forge setup next` 会自动保持 transport 与 auth mode 一致。
 
 App/connector 身份及 Forge 工具 schema 与网络传输层是两件事。Cloudflare/HTTPS 切到 Secure Tunnel 改变的是网络路径，不会生成另一套 19-tool Forge schema。同一个 App 已连接且 schema 没变化时，单纯切换网络不要求新开会话；新会话主要用于隔离 A/B 或排查客户端缓存。
 
@@ -87,7 +87,7 @@ forge setup configure --controller chatgpt --tunnel cloudflare
 forge setup next
 ```
 
-setup 会检测当前平台与 `cloudflared`。macOS 有 Homebrew 时可直接给出安装命令；Linux/WSL2 与 Windows 会给对应的官方安装路径，不会假设所有机器都是 Mac。
+setup 会检测当前平台与 `cloudflared`。macOS 有 Homebrew 时可直接给出安装命令；Linux/WSL2 与 Windows 会给对应的官方安装路径，不会假设所有机器都是 Mac。公网 tunnel 必须终止在 loopback OAuth Connector（通常是 `8767`），绝不能直接暴露 bearer-only Runtime。
 
 named tunnel 建好后，只记录最终 `/mcp` URL：
 
@@ -107,7 +107,7 @@ forge setup configure --controller chatgpt --tunnel tailscale
 forge setup next
 ```
 
-Forge 检查当前平台的 Tailscale CLI 并引导 Funnel；获得最终 HTTPS `/mcp` URL 后再记录。
+Forge 检查当前平台的 Tailscale CLI 并引导 Funnel；Funnel 暴露的是 loopback OAuth Connector（通常是 `8767`），绝不能直接暴露 bearer-only Runtime。获得最终 HTTPS `/mcp` URL 后再记录。
 
 ### D. 已有 HTTPS 或暂缓远程连接
 
@@ -127,7 +127,7 @@ Cloudflare/Tailscale/已有 HTTPS 本质上会让 MCP endpoint 成为公网或
 
 ChatGPT UI 会变化，所以以 OpenAI 当前 Developer Mode 文档为准，不在 Forge 文档中固定截图路径。
 
-使用 Secure MCP Tunnel 时选择 **Tunnel** 连接方式并选择/填入 tunnel ID；使用 HTTPS 时填入稳定、以 `/mcp` 结尾的 URL，并走 Forge 生成的 OAuth 流程。
+使用 Secure MCP Tunnel 时选择 **Tunnel** 连接方式并选择/填入 tunnel ID，然后选择 **无身份验证**：已认证的 OpenAI Tunnel 就是外部授权边界；使用 HTTPS 时填入稳定、以 `/mcp` 结尾的 URL，并走 Forge 生成的 OAuth 流程。
 
 创建后扫描/刷新工具。不要为了看到更多工具名而直接切到 exhaustive compatibility toolset；默认收敛工具面是安全和可用性设计的一部分。
 

package/docs/wiki/Implementation.md

@@ -17,7 +17,7 @@ src/runtime/gateway/mcp/
 
 `toolset-names.ts` defines the bounded default connector surface. The five facade tools come from `src/runtime/control-plane/facade/types.ts`; repository, patch, check, Process, plugin-dispatch, and result tools bring the current default to 19.
 
-The HTTP transport owns authentication and MCP session lifecycle. `McpSessionRegistry` owns session capacity, active-request protection, stream leases, replacement, and close accounting. A tool-surface fingerprint mismatch returns a recoverable reinitialize response; replacement initialize owns actual supersession and transport cleanup.
+The HTTP transport owns authentication and protocol-era routing. MCP 2026-07-28 is the canonical public path: `createMcpHandler` serves each modern request without `Mcp-Session-Id`. `McpSessionRegistry` is retained only for explicit 2025-era compatibility, where it owns session capacity, active-request protection, stream leases, replacement, and close accounting. Durable Work/Process/ControllerRound authority never comes from either transport form. New Work claims mint an opaque Work-bound controller capability immediately; modern sessionless follow-up calls must present it, while legacy owner records without a digest require explicit `controller_claim` upgrade instead of principal-only inference. Legacy tool-surface mismatches still return a recoverable reinitialize response; modern requests resolve the current Runtime schema per request.
 
 ## 2. Repository registry and execution identity