@moretea-labs/forge 1.7.2 → 1.8.1

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.4.5` | 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. Desktop Operator owns native macOS Computer observe/input/capture/console-unlock/element capabilities; Browser automation remains under the separate Browser provider authority rather than being claimed by the Desktop Operator catalog. `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/controller-performance-and-502.md

@@ -256,6 +256,23 @@ Different repository roots never share a cache entry. When the registry
 is unavailable, Git discovery (`origin/HEAD`, `main`/`master`, current
 branch) is used.
 
+## Autonomous continuation cost boundary
+
+The five-second Scheduler reconciliation is a liveness safety net, not permission
+to replay a terminal provider retry decision. When a failed ControllerRound has
+already consumed `maxFailures`, autonomous continuation skips it until the
+existing provider-environment recovery transition supplies new evidence and
+resets that budget. This prevents an unchanged failed round from becoming a
+five-second error/repair loop.
+
+Automatic Forge incident repair also treats Runtime release provenance as
+existing authority. Source-mode Runtime may resolve repair ownership by exact
+registered checkout path. Immutable/package Runtime resolves it from the staged
+release manifest `sourceRepositoryId`. It must not scan every registered
+repository with synchronous `git cat-file` / `merge-base` calls from the Runtime
+Scheduler path. A package manifest without that repository identity is not
+silently repaired through Git ancestry discovery.
+
 ## Safe Cleanup
 
 Safe source-distribution exclusions:

package/docs/operations/controller-reliability-runbook.md

@@ -68,8 +68,8 @@ A release change is performed only as an explicitly authorized whole-Runtime ope
 1. validate one immutable release manifest, configuration, database compatibility range, and Worker protocol;
 2. quiesce admission and stop the complete Runtime;
 3. atomically select the candidate as the one active whole release;
-4. atomically mirror the selected release's signed `forge-runtime` entrypoint to the fixed physical service path `runtime/service/active-forge-runtime`, then let the single Forge Runtime service start that stable path with the selected release manifest/environment;
-5. require binary whole-Runtime readiness;
+4. atomically mirror the selected release's signed `forge-runtime` supervisor launcher to the fixed physical service path `runtime/service/active-forge-runtime`; the launcher validates the selected release's hashed `forge-runtime-bundle.js` and release-owned Bun interpreter, then starts exactly one interpreter child with the selected manifest/environment and forwards lifecycle/diagnostic signals to it;
+5. require whole-Runtime readiness from the child-owned Runtime owner/status and release canaries; the launcher itself is never a second Runtime authority;
 6. on failure, stop the service, restore the previous release and its bound local SQLite backup, then start and verify the complete previous Runtime.
 
 There is no blue-green pair, fixed alternate port, slot adoption, mixed-generation traffic, or component rollback. Release safety comes from pre-activation canaries, immutable artifacts, one atomic active/previous authority, whole-Runtime readiness, and previous-release recovery.

package/docs/operations/features.md

@@ -26,7 +26,7 @@ These features are part of the default local setup:
 | Tailscale / Cloudflare | Stable HTTPS endpoint for ChatGPT MCP | Tunnel client and appropriate account/domain configuration. |
 | Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and HTTP(S) URL scheme validation. |
 | CodeGraph | Additional code relationships and impact navigation | CodeGraph CLI; native Windows automatic setup is not yet enabled. |
-| Google Workspace | Gmail and Calendar plugin actions | Explicit OAuth setup and plugin permission. |
+| Google Workspace | Gmail and Calendar plugin actions | Explicit OAuth setup and plugin permission. The OAuth client ID is non-secret managed configuration; refresh tokens and imported client secrets are stored in the platform credential store. Forge sends `client_secret` when one is stored and otherwise attempts the public-client/PKCE path; the live provider response remains authoritative for whether a specific OAuth client requires the secret. |
 | Schedules | Supervised recurring checks | Canonical Forge Runtime running; live actions remain policy-gated. |
 
 ## Tool exposure

package/docs/operations/features.zh-CN.md

@@ -26,7 +26,7 @@ Forge 不依赖编码 Agent 或外部插件也能使用。先完成核心工作
 | Tailscale / Cloudflare | 为 ChatGPT MCP 提供稳定 HTTPS 地址 | 隧道客户端及对应账号/域名。 |
 | Browser | Playwright 浏览、截图和证据 | 浏览器 binary 与允许访问的域名。 |
 | CodeGraph | 代码关系和影响范围导航 | CodeGraph CLI；Windows 原生暂不自动配置。 |
-| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。 |
+| Google Workspace | Gmail、Calendar 助手能力 | 显式 OAuth 与插件权限。OAuth Client ID 是非秘密受管配置；refresh token 与导入的 client secret 保存到平台凭据存储。Forge 在凭据存储存在 `client_secret` 时发送它，否则尝试 public-client/PKCE 路径；具体 OAuth client 是否强制要求 secret，以实时 provider 响应为准。 |
 | Schedule / Finding | 受监督的周期检查和候选发现 | Canonical Forge Runtime 持续运行，真实动作仍受策略控制。 |
 
 ## 工具暴露

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.1` exists on npm;
+- Git tag and GitHub Release `v1.8.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/operations/mcp-tool-exposure.md

@@ -1,5 +1,7 @@
 # MCP tool exposure profiles
 
+Every Controller MCP tool definition receives the same optional bounded `cognition_settlement` transport field at the final exposure layer, including ordinary repository/edit/process tools as well as the `rh_*` facade. The model emits it only at a meaningful successful outcome boundary; routine micro-steps omit it. Model-authored learning and feedback are mechanically routed to the same Cognitive writers used by `rh_work learning_record/learning_feedback`. Settlement runs after the primary tool succeeds, so a cognition-write defect is returned as explicit settlement metadata/warning rather than converting an already-applied primary effect into a retryable failure. The envelope is not a lifecycle or authority surface.
+
 Controller MCP uses one stable default schema so ChatGPT can reliably read, edit, run checks, use Git, delegate to local Agents, coordinate durable Goal/Work, capture iOS evidence, and recover from failures without a permission switch hiding tools.
 
 ## Profiles

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/releasing.md

@@ -34,6 +34,8 @@ bun bin/forge.mjs --help
 
 The main gate reuses the focused task receipt and does not run the full suite. The release gate reuses that receipt, verifies package identity, documentation, licenses and notices, tracked-file hygiene and public export contents, then creates one tarball under `.ai/harness/artifacts/release/`. Isolated installation and publication consume that same tarball. `test:full` is a manual diagnostic only.
 
+The committed `package-lock.json` must resolve all distribution artifacts through the public `https://registry.npmjs.org/` origin with unchanged integrity checksums. Local npm mirrors and private CI package gateways must not become dependencies of the public source archive. An isolated install timeout is an incomplete release gate, not a passing smoke test.
+
 ## Bootstrap npm publication (only while the package does not exist)
 
 npm Trusted Publishing cannot be configured for a package that does not exist yet. The bootstrap publication therefore requires an npm maintainer for the `@moretea-labs` scope with two-factor authentication. Because this one-time local path has no OIDC provider, `NPM_RELEASE_BOOTSTRAP=1` disables provenance only for that bootstrap publish; `publishConfig.provenance` remains `true` for normal GitHub OIDC releases.

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

@@ -58,7 +58,9 @@ reconnect_primary_connector
 
 `runtime_status` reads canonical Runtime observation. `list_releases` reads the whole-release authority. `attest_known_good` succeeds only after Runtime status, release identity, authenticated MCP initialization, tools/list, and the configured read-only MCP call pass together.
 
-The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers, MCP payloads and session identifiers are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers and MCP payloads are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+
+For MCP transport lifecycle, Standalone Recovery deliberately owns **no transport-session state**. MCP 2026-07-28 and bounded 2025-era compatibility requests are both served statelessly by the SDK handler. `Mcp-Session-Id` is therefore never Recovery authority and is not required to survive a Recovery Gateway process replacement; an old client sending a stale session header cannot strand the independent recovery path. Runtime/release authority remains durable and separate from transport process identity.
 
 ## Whole-Runtime rollback
 
@@ -93,26 +95,49 @@ The watchdog cannot launch an Agent, edit a source checkout, generate repair scr
 
 ## Installation
 
-Build, canary, and activate the immutable Recovery release with the public CLI:
+Build and canary the immutable Recovery release with the public CLI. Installation role is explicit:
+
+- `manual` is the default. It publishes the Recovery artifact/configuration but registers no persistent Recovery Gateway or Watchdog.
+- `gateway` registers only the independently reachable Recovery Gateway.
+- `self-healing` registers Gateway plus Watchdog and is the only profile that pays the autonomous health-monitoring/recovery cost.
 
 ```sh
 forge recovery install \
   --controller-home /absolute/controller-home \
+  --profile gateway \
   --public-mcp-url https://mcp.example.com/mcp \
   --recovery-public-url https://recovery.example.com/recovery/mcp \
   --recovery-tunnel-service-label com.example.forge-recovery-tunnel \
   --recovery-tunnel-service-plist /absolute/path/com.example.forge-recovery-tunnel.plist
 ```
 
-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.
+`--stage-only` remains a compatibility alias for build/canary-only behavior and does not mutate installed Recovery configuration or services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface. Shipping Forge source/CLI does not itself activate any persistent Recovery profile.
 
-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 \
+  --profile gateway \
+  --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 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.
+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.
+
+When the selected profile includes Gateway, the Recovery Gateway and any dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, so a primary Runtime outage does not remove that external Recovery control path. Watchdog independence applies only to the explicit `self-healing` profile.
+
+The installer owns Recovery publication and role reconciliation. It activates only the roles selected by the typed install profile and explicitly retires Recovery-owned Gateway/Watchdog services that are no longer selected. It never treats a package/source install as permission to enable Watchdog. 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 +159,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 action surface includes `runtime_status`, `list_releases`, read-only `verify_stable_runtime`, the compatibility candidate-build action `stage_and_activate_runtime_release`, and the durable ReleaseSession lifecycle (`release_session_status`, static verification, isolated Candidate B verification, pre-cutover Candidate retirement, cutover, exact-session rollback, and known-good promotion). A source or admission gate discovered after Candidate creation invalidates that frozen candidate: Recovery retires it through the existing `failed` terminal state and removes the isolated Candidate lane before a replacement ReleaseSession is prepared. While a ReleaseSession owns an activation transaction, the watchdog may restart the same candidate Runtime but must not generically commit or roll back that transaction; exhausted recovery delegates back to the exact ReleaseSession rollback path. Ordinary actions accept no caller arguments; ReleaseSession actions accept only the bounded `session_id`, while mutation request ids remain provider-owned. 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 同样不是普通用户初始化的前置条件。