@moretea-labs/forge 1.5.0 → 1.6.0

package/docs/architecture/current/entity-model.md

@@ -13,6 +13,26 @@ Forge separates four kinds of truth:
 
 Entities from different categories must not be collapsed merely because they are currently stored in adjacent files or exposed by one tool.
 
+The current Controller model also separates semantic ownership from execution depth and placement. Requirement/Plan/Work describe intent and finite delivery lineage; Direct/Process/Agent describe execution mechanisms; Workspace/Worktree/provider resources describe placement. None of those dimensions substitutes for another.
+
+### 1.1 Current intent hierarchy
+
+```text
+Requirement?          long-lived user outcome
+  -> Plan?            optional decomposition/replanning contract
+       -> Work         finite recoverable objective
+            -> Edit Session / Process / Run / Verification evidence
+
+Schedule              long-lived trigger/policy
+  -> Occurrence        one bounded terminal firing
+```
+
+A Requirement may have more than one active Plan slice. Current Plan rows own the forward `requirementId` relation; `Requirement.activePlanId` is migration compatibility only and MUST NOT become a second lifecycle authority. A failed/cancelled Work moves its Plan to `replanning`; a reusable slice returns to `ready` rather than pretending to be in verification.
+
+A Durable repository Work has one execution `WorkHandle` with the same Work identity. The handle records the selected checkout/worktree, execution-session binding, permission snapshot and finalization stages; it is execution state, not another user objective. New `rh_work start` creation materializes this handle and claims the initiating authenticated Controller in the same facade flow. `managedWorktree=false` means the Work does not own the current checkout/branch as disposable resources, so terminal cleanup releases lifecycle/process ownership without deleting them.
+
+Conversation/session bindings are transport and presentation preferences. They may help resume a Controller, but Work/Schedule identity survives a changed or missing conversation.
+
 ## 2. Identity Hierarchy
 
 ```text

package/docs/architecture/current/external-plugin-governance.md

@@ -71,7 +71,7 @@ Current source uses Forge authorities for active configuration:
 - GitHub: `.forge/plugins/github.json` plus Repository Registry GitHub identity;
 - Gmail/Calendar/Tasks: `.forge/plugins/...`, `FORGE_*_ACCESS_TOKEN`;
 - iOS: `.forge/plugins/ios.json`, `FORGE_IOS_DEVICE_RUNNER_URL` plus local Xcode/CoreDevice/agent-device facts;
-- Desktop: Controller Home `system/desktop/config.json`;
+- Desktop Operator: trusted external registration under Controller Home plus the stable signed macOS app identity;
 - Local System: Controller Home `system/local-system`.
 
 App Store Connect intentionally retains `.repo-harness/plugins/app-store-connect.json` as a named `legacy-read-fallback`. This is an acceptable migration pattern and must not become a new write authority.
@@ -326,7 +326,7 @@ Runtime/recovery/worktree directories are governed separately and are never trea
 7. Route a non-destructive status/observe action end-to-end.
 8. Add write action policy tests for press/type/screenshot/batch without bypassing normal Forge confirmation rules.
 9. Run real macOS E2E when the registered Desktop Operator build/service is available.
-10. Only then decide whether the bundled Desktop helper remains fallback or is retired.
+10. Retire the bundled Desktop helper after the external Desktop Operator is healthy; do not retain a second desktop authority.
 
 ### Phase 1 acceptance
 
@@ -368,7 +368,7 @@ Preserve its independent Git/product boundary. Integrate only through stable con
 Audit and close every built-in plugin:
 
 - Browser: Chrome/Vivaldi attach, ownership/reuse, DOM/native capability matrix, failure paths, real E2E.
-- Local System/Desktop: unregistered target operations, application control, external Desktop provider, destructive-path safeguards.
+- Local System/Desktop Operator: unregistered target operations, background-safe application control, external Desktop provider, destructive-path safeguards.
 - iOS: simulator, agent-device, CoreDevice, physical runner configuration/E2E.
 - App Store Connect: auth/read/preview/write policy and remote-write guarded E2E.
 - GitHub: canonical Forge remote identity after repository rename; issue/project read/write acceptance.

package/docs/architecture/current/system-overview.md

@@ -1,10 +1,35 @@
 # Controller Runtime System Overview
 
 > Status: **Runtime Authority**
+>
+> Control convergence: ChatGPT/human Controller owns semantic understanding and commits Direct/Process/Durable Work/Plan only after sufficient context; Forge does not classify every request at ingress. `RouteDecision` owns execution mechanics after that commitment, while unrelated Work/Plan state never upgrades or blocks ordinary Direct execution. Semantic ownership, execution depth, and resource placement stay independent. CodeGraph/lexical/Forge relations are bounded impact evidence, not another decision authority.
 
 ## 1. System Definition
 
-Forge Controller Runtime is an Agent Engineering Control Plane for one or more local Git repositories. ChatGPT, Local UI, CLI and optional GitHub integrations submit decisions and commands. The runtime persists accepted work, schedules it under repository-owned conflict rules, executes it outside the Gateway process and records evidence for recovery, acceptance and release.
+Forge Controller Runtime is an Agent Engineering Control Plane for one or more local Git repositories. ChatGPT is the primary semantic Controller: it may inspect first, then choose whether a request needs only a Direct action, a Process, finite durable Work, a Plan, or a Workflow. Local UI, CLI and integrations can submit the same explicit decisions and commands. Forge supplies bounded context, hard policy/resource constraints, persistence, execution and machine evidence; it does not replace the Controller with prompt classifiers or Plan/Work ceremony.
+
+### 1.1 End-to-end authority map
+
+```text
+User request
+  -> ChatGPT / human Controller
+       -> Explore when needed: rh_context + raw reads + CodeGraph/Runtime/history evidence
+       -> semantic commitment: answer | Direct | Process | finite Work | Plan | Workflow
+  -> Forge execution boundary
+       -> hard policy / authorization / claims / leases / fencing
+       -> placement and executor mechanics; no semantic reinterpretation
+  -> execution
+       -> Direct mutation: SafePatch -> EditSession -> MutationGate
+       -> command/check: Unified Process Runtime
+       -> durable responsibility: finite Work using the same execution primitives
+       -> recurrence: Workflow/Schedule -> bounded Occurrence -> Controller decision
+  -> machine evidence
+       -> diff / Process receipt / check / delivery / cleanup facts
+  -> ChatGPT / user acceptance
+       -> accept, continue, replan, or close the semantic goal
+```
+
+Authority rule: Context providers return evidence, RoutePolicy selects mechanics from a Controller commitment, Plan/Requirement/Work persist explicitly chosen durable semantics, and Process/EditSession/Evidence record execution facts. None of those layers may infer that a missing Plan/Work makes ordinary implementation unauthorized, or that a successful/failed cleanup receipt by itself proves the user's goal accepted/rejected.
 
 ## 2. Canonical Runtime Topology
 

package/docs/architecture/current/thin-harness-v1.md

@@ -174,6 +174,16 @@ bounded child process (process group) / yielded search
 - Timeout/cancel: SIGTERM process group → grace → SIGKILL via `terminateProcessTree`.
 - stdout/stderr collectors cap while streaming.
 
+## MCP tool-surface freshness
+
+The Canonical Runtime `tools/list` schema fingerprint is the tool-surface identity. Release identity alone does not invalidate a session, while any exposed schema change does.
+
+HTTP MCP sessions capture the exact Canonical Runtime fingerprint and tool names at initialize time. The Gateway also observes the existing atomic `runtime/status.json` publication; when its published tool-surface fingerprint changes, it sends the standard MCP `notifications/tools/list_changed` notification to connected sessions whose captured fingerprint is stale. This is event-driven over the existing Runtime status publication—there is no schema poller, refresh daemon, or extra control-plane entity.
+
+The notification is an optimization hint, not authority. It never rewrites a session's captured fingerprint. Until the client re-runs discovery/reinitializes, the existing per-request fingerprint fence still rejects stale-schema execution. A lost notification therefore cannot make an obsolete tool call valid; it only risks falling back to the deterministic reinitialize path.
+
+This removes the normal stale-tool extra round trip for clients that honor standard MCP list-changed notifications while retaining the same fail-closed schema fence for clients that do not.
+
 ## Process output confidentiality
 
 Process Runtime applies one shared bounded redaction policy before stdout/stderr

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

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

package/docs/operations/chatgpt-personal-assistant-runtime.md

@@ -54,7 +54,15 @@ A routine stores the user's natural-language goal rather than a traditional GUI
 }
 ```
 
-The first version stores the routine and can run it on demand. Automatic time-based scheduling should attach this store to the existing schedule engine in a later iteration.
+Routine execution and long-lived goal continuation use the existing Schedule Engine rather than a second assistant daemon. Semantic/model-backed routine logic remains external-controller-owned; the Kernel does not execute an unbounded model loop on a timer.
+
+For an accepted non-terminal Work, ChatGPT can create a bounded `rh_work.schedule_create` policy in one of three modes:
+
+- `continuation` — wake the bound ChatGPT/Codex/Claude/Grok Controller at the configured trigger;
+- `browser_watch` — silently refresh/read an allowed browser target, fingerprint a deterministic text projection, and wake the bound Controller only when the observation changes;
+- `browser_keepalive` — silently refresh an authenticated browser target and wake only when configured login markers indicate that user authentication is required.
+
+The first `browser_watch` observation is a silent baseline by default. Unchanged observations do not create a ChatGPT conversation turn. When the bound Work becomes terminal, Forge disables the Schedule before performing another external probe, so temporary watchers naturally disappear with the Goal they serve.
 
 ## Policy defaults
 
@@ -76,8 +84,10 @@ Requires human approval:
 
 ## Assistant Inbox
 
-Assistant Inbox is the user-facing result surface for routine outputs and intent execution records. ChatGPT can read it and then present the result conversationally, for example: "今天助理整理了什么？"
+Assistant Inbox is the user-facing result surface for meaningful routine outputs, approval/authentication needs, and intent execution records. A successful scheduled probe with no external change should remain silent rather than generating a daily "completed" notification. ChatGPT can read meaningful items and then present the result conversationally, for example: "今天助理整理了什么？"
 
 ## Current limitation
 
 The runtime does not embed a full NLP model. ChatGPT Actions should provide structure when precision matters. The local runtime includes conservative intent inference only for routine creation, reminders, and immediate mail-summary collection.
+
+`browser_watch` is a fallback observation source for services without a usable API or webhook; it depends on a live authenticated browser session and caller-supplied selectors/terms when the page contains unrelated or volatile content. Browser refresh can reduce inactivity-related logout but cannot override a provider's absolute session lifetime, security checks, or MFA policy. Provider-native APIs/events should replace browser probes when they are available and more reliable.

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

@@ -48,7 +48,7 @@ Session metadata is reusable across actions via `session_id`. Any action that re
 - Artifacts stay under `.forge/browser/**` (not arbitrary local paths).
 - CDP attach is bounded to configured loopback endpoints only; the plugin does not scan arbitrary ports or remote hosts. Native discovery checks only the configured Chrome/Vivaldi candidates and does not launch them.
 - CDP browsers are disconnected after the action; Apple Events keeps plugin-owned session tabs open until `close_session`/`close_page` while preserving user-owned tabs; managed contexts are closed after the action. Standard native DOM reads/interactions do not foreground the owned tab and return DOM evidence instead of attempting a screenshot.
-- Health `userFacingStatus` reports `ready`, `domain restricted`, `session active`, or setup states.
+- Health `userFacingStatus` reports `ready`, `session active`, or setup states.
 
 ## Configuration
 
@@ -67,12 +67,11 @@ Example:
   "nativeBrowserCandidates": ["vivaldi", "chrome"],
   "cdpAttachFallback": "managed_persistent",
   "browserChannel": "chromium",
-  "defaultTimeoutMs": 30000,
-  "allowedDomains": ["example.com", "docs.example.com"]
+  "defaultTimeoutMs": 30000
 }
 ```
 
-`allowedDomains` is the safety boundary. If it is empty, the plugin can target any HTTP(S) host. If it is set, the plugin accepts only exact hosts or subdomains of those entries.
+Browser URLs are open by default across hosts. The URL boundary is scheme-based: top-level navigation accepts absolute `http://` and `https://` URLs and rejects `file://`, `data:`, browser-internal pages, and custom schemes. Interaction risk and authorization are enforced by the typed action policy rather than a domain grant.
 
 Additional browser/profile fields:
 
@@ -131,8 +130,7 @@ Example custom Chrome automation-profile binding:
   "browserChannel": "chrome",
   "cdpEndpoint": "http://127.0.0.1:9222",
   "cdpAttachFallback": "fail_closed",
-  "defaultTimeoutMs": 30000,
-  "allowedDomains": ["appstoreconnect.apple.com"]
+  "defaultTimeoutMs": 30000
 }
 ```
 
@@ -152,12 +150,11 @@ Use native attachment when the target session is already logged in:
   "browserMode": "attach_preferred",
   "nativeAttachMode": "auto",
   "nativeBrowserCandidates": ["vivaldi", "chrome"],
-  "cdpAttachFallback": "managed_persistent",
-  "allowedDomains": ["chatgpt.com", "example.com"]
+  "cdpAttachFallback": "managed_persistent"
 }
 ```
 
-The attach order is CDP, then Apple Events, then managed fallback. macOS may require Automation permission for the controller/Node process to control Vivaldi or Google Chrome. The browser must also permit JavaScript from Apple Events for DOM extraction and interaction. If either permission is unavailable or the browser has no window, the attempt is recorded and fallback policy applies. The provider uses the active browser only for discovery, then operates on a plugin-owned tab identified by stable window/tab metadata. It does not read cookies or storage and re-checks the target URL against `allowedDomains` before and after actions.
+The attach order is CDP, then Apple Events, then managed fallback. macOS may require Automation permission for the controller/Node process to control Vivaldi or Google Chrome. The browser must also permit JavaScript from Apple Events for DOM extraction and interaction. If either permission is unavailable or the browser has no window, the attempt is recorded and fallback policy applies. The provider uses the active browser only for discovery, then operates on a plugin-owned tab identified by stable window/tab metadata. It does not read cookies or storage. Top-level Browser actions accept any absolute HTTP(S) URL; non-HTTP(S) schemes fail before launch.
 
 Native limitations are explicit: console/network event capture is unavailable and native file-input/download semantics are not equivalent to Playwright. A screenshot of a plugin-owned background tab fails closed with `PLUGIN_BROWSER_FOREGROUND_REQUIRED`; Forge does not silently activate the tab just to capture evidence. Use explicit foreground/human handoff, CDP, or a managed context for workflows that require screenshots or capabilities not available through background DOM automation.
 
@@ -219,15 +216,14 @@ Risk levels:
 - `click`, `type`, `press` use `risk=remote_write`
 - `wait_for_selector` uses `risk=workspace_write`
 
-## Allowed-domain enforcement
-
-The plugin enforces `allowedDomains` in three places:
+## URL scheme boundary
 
-1. It validates the explicit `url` before opening a page.
-2. It validates any saved `session_id` target before interaction.
-3. It re-checks the resulting page URL after the action and rejects the result if navigation leaves the allowed set.
+Browser no longer maintains per-domain grants or a host allowlist. Any absolute HTTP(S) URL may be opened, redirected to, or reached by an interaction. This avoids configuration churn for normal browsing while preserving the actual trust boundaries:
 
-The plugin does not intentionally provide any action that can bypass this boundary.
+1. top-level Browser targets must use `http:` or `https:`;
+2. local files, browser-internal URLs, `data:` URLs, and custom schemes are rejected as Browser targets;
+3. action risk and confirmation still govern remote writes and interactive operations;
+4. silent native automation stays on plugin-owned background tabs unless an explicit human handoff requires foreground presentation.
 
 ## Dependency requirement
 

package/docs/operations/features.md

@@ -24,7 +24,7 @@ These features are part of the default local setup:
 | Codex / Claude | Delegated implementation for work too large for Direct Edit | Install and authenticate the corresponding CLI; explicitly enable the dev runner. |
 | GitHub | Issue/Project synchronization, PR workflows, cloud-agent sessions | Authenticated `gh` and repository permission. |
 | 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 allowed domains. |
+| 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 assistant actions | Explicit OAuth setup and plugin permission. |
 | Schedules and findings | Supervised recurring checks and candidate findings | Canonical Forge Runtime running; live actions remain policy-gated. |

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.5.0` exists on npm;
-- Git tag and GitHub Release `v1.5.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.6.0` exists on npm;
+- Git tag and GitHub Release `v1.6.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/public-usage-guide.md

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

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

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

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

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

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

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

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

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

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

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

package/docs/wiki/Installation.md

@@ -7,7 +7,7 @@
 This is the verified path while `@moretea-labs/forge` remains unpublished:
 
 ```bash
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/docs/wiki/Quick-Start.md

@@ -7,7 +7,7 @@ Until the npm RC is publicly available, use the verified source path:
 ```bash
 git clone https://github.com/moretea-labs/forge.git
 cd forge
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/package.json

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

package/scripts/check-public-docs.sh

@@ -72,9 +72,22 @@ grep -q "$README_CHANNEL_EN" README.md || { echo "[public-docs] English README m
 grep -q "$README_CHANNEL_ZH" README.zh-CN.md || { echo "[public-docs] Chinese README must state the npm channel for $PACKAGE_VERSION" >&2; exit 1; }
 grep -q 'See \[README.md\](README.md)' README.en.md || { echo "[public-docs] README.en.md must point to the maintained English README" >&2; exit 1; }
 
+source_install_docs=(
+  README.md README.zh-CN.md
+  docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md
+  docs/wiki/Quick-Start.md docs/wiki/Installation.md
+)
+for path in "${source_install_docs[@]}"; do
+  grep -q 'bun install --frozen-lockfile' "$path" || { echo "[public-docs] source checkout must use the CI-authoritative Bun frozen lock: $path" >&2; exit 1; }
+  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source package install: $path" >&2; exit 1; }
+done
+if git grep -n 'npm ci --ignore-scripts --no-audit --no-fund' -- "${source_install_docs[@]}" >/dev/null; then
+  echo "[public-docs] generic npm ci must not be advertised for Forge source checkouts" >&2
+  exit 1
+fi
+
 for path in docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md; do
   grep -q 'Node.js 20.10' "$path" || { echo "[public-docs] missing Node baseline: $path" >&2; exit 1; }
-  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source install: $path" >&2; exit 1; }
   grep -q "$INSTALL_SPEC" "$path" || { echo "[public-docs] missing package command for $PACKAGE_VERSION: $path" >&2; exit 1; }
 done
 

package/scripts/migrate-chatgpt-automation-schedules.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+import { listRepositories } from '../src/cli/repositories/registry';
+import { migrateChatgptAutomationSchedule } from '../src/runtime/workflow/schedules/chatgpt-automation-migration';
+import { listSchedules, saveSchedule } from '../src/runtime/workflow/schedules/store';
+import type { RepositorySchedule } from '../src/runtime/workflow/schedules/types';
+
+interface Args { controllerHome?: string; apply: boolean; json: boolean; }
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = { apply: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--apply') args.apply = true;
+    else if (value === '--json') args.json = true;
+    else if (value === '--controller-home') args.controllerHome = resolve(argv[++index] ?? '');
+    else throw new Error(`unknown argument: ${value}`);
+  }
+  return args;
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const controllerHome = resolveRepoPreferredControllerHome(process.cwd(), args.controllerHome);
+  const repositories = listRepositories(controllerHome, { includeRemoved: true });
+  const candidates: Array<{ repositoryName: string; original: RepositorySchedule; migrated: RepositorySchedule }> = [];
+  for (const repository of repositories) {
+    for (const schedule of listSchedules(controllerHome, repository.repoId)) {
+      const result = migrateChatgptAutomationSchedule(schedule);
+      if (result.changed) candidates.push({ repositoryName: repository.displayName, original: schedule, migrated: result.schedule });
+    }
+  }
+
+  let backupPath: string | undefined;
+  if (args.apply && candidates.length > 0) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    backupPath = join(controllerHome, 'backups', `chatgpt-automation-schedules-${stamp}.json`);
+    mkdirSync(dirname(backupPath), { recursive: true });
+    writeFileSync(backupPath, `${JSON.stringify({ schemaVersion: 1, createdAt: new Date().toISOString(), schedules: candidates.map((item) => item.original) }, null, 2)}\n`);
+    for (const candidate of candidates) saveSchedule(controllerHome, candidate.migrated);
+  }
+
+  const output = {
+    schemaVersion: 1,
+    controllerHome,
+    repositoryCount: repositories.length,
+    migratedCount: candidates.length,
+    writesApplied: args.apply,
+    backupPath,
+    schedules: candidates.map((item) => ({ repoId: item.original.repoId, repositoryName: item.repositoryName, scheduleId: item.original.scheduleId, name: item.original.name })),
+  };
+  if (args.json) console.log(JSON.stringify(output, null, 2));
+  else {
+    console.log(`[chatgpt-automation-migration] ${candidates.length} schedule(s) eligible across ${repositories.length} repository record(s).`);
+    console.log(args.apply ? `[chatgpt-automation-migration] Applied. Backup: ${backupPath ?? 'not needed'}` : '[chatgpt-automation-migration] Preview only; pass --apply after the new Runtime baseline is active.');
+  }
+}
+
+try { main(); } catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/sprint-backlog.sh

@@ -21,7 +21,7 @@ Usage:
 
 Program-level sprint backlog helper. PRDs live in plans/prds/ as the upper
 planning layer; sprints live in plans/sprints/ as ordered execution backlogs.
-Each backlog row is expanded with $think before the existing plan -> contract
+Each backlog row is expanded with /plan before the existing plan -> contract
 -> worktree flow. tasks/todos.md stays the deferred-goal ledger.
 
 start-task reserves the next (or named) pending backlog row and can capture a