@moretea-labs/forge 1.7.2 → 1.8.1

package/docs/architecture/decisions/20261001-supervisor-turn-authority.md

@@ -0,0 +1,237 @@
+# Supervisor owns the enrolled prompt chain
+
+Status: accepted implementation contract for the autonomous-continuation candidate.
+
+## Decision
+
+An explicitly enrolled logical conversation is a durable task. Workflow Supervisor
+monitors its exact provider effect, commits the model's structured receipt, and
+reserves the next fixed prompt for CONTINUE. DONE and NEEDS_USER retain their
+configured semantic validators; STOPPED remains explicit operator authority.
+
+The first Work-bound enrollment still requires authenticated launcher admission,
+canonical Work lookup and a prepared ControllerRound. Before consulting that lower
+admission gate, the Runtime checks whether the exact conversation already has a
+Supervisor task. Once enrolled, that existing task/effect/completion journal is the
+only cross-turn authority and is reused even if its original ControllerRound is now
+closed, exhausted or absent. Neither Work absence/turnover nor ControllerRound
+status/budget is a second gate on a committed CONTINUE. Supervisor must not manufacture Controller claims,
+release another owner's lease, rotate round authority, or rearm lower budgets to
+make an outer prompt runnable. Normal MCP execution still enforces principal,
+Controller ownership, Work scope, resource and write fences independently.
+The enrollment compatibility receipt may settle only its exact origin Work and
+provider effect. A newer Requirement relay is never a substitute receipt target.
+
+Explicit Requirement cancellation revokes new sends for that Goal; Work carrier
+cancellation alone does not. An explicit Work conversation rebind fences new sends to the predecessor
+conversation at dispatch admission. Already-started effects remain observable
+on their original exact conversation: unknown never authorizes resend. New task
+registration retains the initial Work id as provenance even for Requirement
+contracts. Existing Work-named tasks provide the same provenance from their
+registered identity. Legacy Requirement-only tasks retain their registered
+conversation; no newest Requirement relay is selected as their transport owner.
+
+Scheduler liveness discovers existing relay references as well as repo Work
+projections and resolves them through canonical getWorkContract. A missing list
+entry is not deletion. A genuinely missing Work never implies completion or
+authorizes retiring an unresolved provider effect. This candidate does not add
+orphan deletion, a new relay index, or a second cleanup lifecycle.
+
+## Cross-cutting closure
+
+| Area | Existing owner and candidate behavior |
+| --- | --- |
+| Identity / scope | Exact enrolled task + conversation + causal effect; Work is execution context. |
+| Authority / authorization | Supervisor owns prompts; authenticated MCP and Controller own repository mutations. No lease or capability is synthesized by receipt processing. |
+| Concurrency / fencing | Existing effect dispatch transaction, unique causal successor, Runtime write claim and provider lane remain. Rebind is checked again at dispatch admission. |
+| Persistence / replay | Existing Supervisor SQLite schema and append-only event journal; every nonterminal task must mechanically derive one causal obligation (unapplied effect, applied effect awaiting completion, or committed completion awaiting successor/terminal settlement). Restart reconciliation repairs the same obligation without a new table, enum or writer. |
+| Unknown / recovery | Existing bounded provider attempts and independently spaced unknown observations. Retired Work does not suppress read-only effect reconciliation. |
+| Lifecycle / retention | Supervisor terminal receipts/operator stop own task termination; existing retention/backup policies remain. Missing Work is not semantic terminality. |
+| Evidence / privacy | Existing causal completion hashes, allowlisted provider evidence and redaction; no page-body persistence added. |
+| Capacity / time / performance | Existing send lane, bounded scanner and observation budgets. Provider-wide inventory/backpressure may delay the consumer globally; exact-conversation target failures are task-local and cannot back off unrelated Supervisor tasks. |
+| Topology / portability | Same in-process Runtime/Supervisor owner and native Browser adapter; no process, credential flow or platform dependency added. |
+| Release / rollback | ReleaseSession verifies isolated Candidate B, then cutover retains rollback authority during soak. The new Stable release cannot become known-good until the Supervisor ledger proves exact-active-release CONTINUE → CONTINUE → DONE across a Runtime reconnect. No component activation or manual live database repair. |
+
+## Predecessor obligations
+
+| Previous obligation | Disposition | Successor location |
+| --- | --- | --- |
+| 20260916 Supervisor authority: exact conversation, model receipt, fixed prompts, semantic validators | KEEP | Supervisor control-plane/protocol/store and forge-validators. |
+| Restart-safe effects, no unknown resend, bounded recovery | KEEP | Existing Supervisor effect journal and Browser adapter. |
+| 20261001 ambiguous-send reconciliation: observer snapshots never authorize provider mutation | KEEP | 19147d69 remains the candidate baseline; native reconciliation stays read-only. |
+| Lower ControllerRound continuation/provider authority | CHANGE | Initial admission/direct non-ChatGPT effects remain Controller-owned; enrolled ChatGPT continuation belongs exclusively to Supervisor. |
+| 20260919 autonomous Work liveness and same-occurrence recovery | CHANGE | Scheduler canonical lookup of relay-referenced semantic Work; subsequent prompt-chain repair stays in Supervisor. |
+| Explicit successor lineage/conversation inheritance | KEEP | Existing typed Work lineage and explicit binding API; outer task/effect identity does not change with a Work carrier. |
+| Real unattended restart, multiple CONTINUE, DONE/NEEDS_USER canary | KEEP | Existing focused scenarios, process-restart smoke and release-bound live continuation proof; candidate is not complete before that evidence. |
+
+## Verification
+
+Retained scenarios must prove causal CONTINUE successor idempotency through
+lower budget exhaustion without mutating the lower round, exact-conversation
+rebind fences, observation of old started effects, semantic Work discovery,
+the automation receipt successor baseline, bounded retry/unknown behavior and
+process restart. Compiler and canonical architecture gates precede deployment.
+Live acceptance requires a real enrolled conversation advancing multiple turns
+without human continuation and a validated terminal receipt.
+
+The native consumer must accept a causally completed tool-only turn even when
+ChatGPT renders no assistant prose and its last visible message role is user.
+Provider generation and cooldown still delay a new send, and dispatch admission
+still verifies the exact source effect. Browser resources have the disposable
+lifecycle defined below; task/effect history survives resource retirement.
+A real b388b27c canary exposed
+these consumer gaps after its first persisted CONTINUE, so source gates alone
+did not establish unattended continuation acceptance.
+
+## Timely consumption under observation backlog
+
+The native consumer refreshes the canonical pending-send projection between
+individual read-only tab inspections, including within bootstrap unknown-effect
+inventory walks. At most one send is serviced at each checkpoint; least-recently
+checked eligible effects receive the next opportunity. Busy/cooldown checks are
+spaced by the existing active tick. Observation resumes after that opportunity,
+so fresh sends cannot starve it and a full historical scan cannot hold a new
+CONTINUE until the next pass. This is serial cooperative scheduling within the
+same Runtime owner; its timestamps are ephemeral fairness hints, never dispatch
+authority. Existing bounded native calls and admitted provider dispatches finish
+before the next checkpoint; no operation is abandoned or allowed to race a
+second writer. Unknown observation spacing/budgets, durable dispatch CAS,
+source-completion validation and the shared provider lane remain authoritative.
+
+Live acceptance also records completion-to-successor dispatch latency under
+existing Browser backlog. An eventual CONTINUE/CONTINUE/DONE chain alone does
+not establish timely continuation. The previous 5a6fc9cb canary's 688,144 ms
+second-successor delay is failed timing evidence and remains in the incident
+record; it must not be erased or relabeled as successful timing acceptance.
+
+## Disposable browser resources
+
+The existing native Supervisor consumer owns tab retention and restoration.
+When browser work is suspended by durable cooldown or unknown-observation
+spacing, it may close its created canonical tab only after a readable snapshot
+proves that no provider generation is running. An unbound bootstrap's sole
+observation resource remains until binding or explicit task termination.
+An applied effect awaiting its model receipt remains eligible for observation.
+DONE, NEEDS_USER and explicit STOPPED retire owned resources; after restart the
+same owner reconstructs ownership from exact task identity and window.name.
+An adopted user tab loses only the Supervisor marker and stays open.
+
+When delivery or read-only observation is due, complete supported-browser
+inventory must prove the exact enrolled conversation absent before the owner
+opens its persisted conversation URL. An unreadable inventory, foreign owner,
+ambiguous exact candidate or unresolved resource close fails closed. At most one
+restoration per conversation is attempted in a consumer pass, with existing
+transport backoff after failure. Reopening a tab neither creates a ChatGPT
+conversation nor changes provider effect admission, generation or outcome.
+Outcome unknown is still read-only and never authorizes resend. No persistent
+state, extra lifecycle owner, schema or provider retry policy is added.
+
+The operator's three-goal consolidation explicitly stops historical duplicate
+tasks through the Supervisor API. It does not infer completion, clear effects,
+cancel another execution owner's claim or delete ControllerRound authority.
+
+Project discovery attributes a conversation to a project page only when its
+canonical route carries the same project id. Sidebar presence is not project
+membership. The existing discovery store validates both incoming and retained
+metadata against that route, including projects whose URLs omit a title slug;
+a conflicting observation cannot displace a proven title from another source.
+Discovery remains observation, never task enrollment or dispatch authority.
+
+## Provider observation and explicit recovery (20261002)
+
+The same native consumer reads the visible hydrated conversation surface.
+Hidden server-rendered copies, profile loading and unrelated page busy markers
+are not provider activity. Current-turn reasoning/tool text contributes only to
+the existing activity digest, even before an assistant role message exists.
+Current provider status regions include localized disconnect/delivery-timeout
+messages. A status region is evidence; arbitrary chat prose is not.
+
+A reserved recovery remains authorized across consumer passes and provider
+cooldown, but never authorizes stopping a live turn. Unchanged reasoning/tool
+activity and local wait expiry do not prove provider termination. A latest user
+role without a settled assistant remains unresolved even if the Stop button is
+absent. Only a settled idle assistant or explicit provider failure admits the
+existing bounded recovery; a resumed live provider delays its dispatch. The
+original applied prompt is never replayed. A dispatch function returning
+without clicking Send supplies a dispatch-owner negative proof. Browser observers
+still cannot turn absence or a transport exception into that proof.
+
+After bounded automatic recovery stops, an explicit user recovery may reserve
+one causally keyed recovery of the current applied leaf. The local operator RPC
+requires exact task/source effect, a request id and reason; Native Messaging has
+no access to it. Duplicate calls reuse the same recovery. Existing exhausted
+events, provider generations and task/conversation identity are retained; the
+new recovery itself cannot recursively auto-recover. No schema, enum, process,
+readiness authority or recovery owner is added. Existing terminal states remain
+terminal and an unresolved unknown effect blocks this operation.
+
+Bounded migration exception: the pre-20261002 native adapter recorded its own
+returned pre-click failures as unknown. Explicit recovery may reconstruct a
+negative proof only from the current dispatch's persisted native pre-send reason,
+never a browser snapshot or generic exception. Remove this reader after those
+historical effects reconcile; new producers write the negative proof directly.
+The same whole-Runtime release/rollback and existing Supervisor retention apply.
+
+## Productive turns and frozen tool context (20261002)
+
+Every newly rendered Supervisor prompt includes the existing `@forge` tool
+invocation used by the ordinary ChatGPT delivery adapter. Normal continuations
+retain conversation context instead of repeating the full historical objective,
+and ask for the next unfinished product change or acceptance check. Unchanged
+infrastructure summaries do not satisfy a work checkpoint.
+Normal turns carry the existing registered repository identity and name the
+direct read/edit/command/check tools. An explicitly registered checkout is carried
+with that identity, so concurrent platform tasks do not follow one mutable
+repository default. This is execution context, not checkout allocation or an
+authorization bypass; domain tools still validate the selected checkout and fences.
+Existing registration may fill this hint only once when it was initially absent
+and every task/conversation/repository/objective/policy/semantic obligation is
+unchanged. The existing Store transaction is the sole writer; conflicting
+checkout selections fail. One diagnostic event in the existing journal records
+the selected ids; retries of the original registration retain the selected hint.
+No schema, lifecycle enum, RPC, process or alternate routing
+authority is added. Effect prompts, unknowns, budgets and completion history are
+untouched; existing retention, backup and whole-Runtime rollback still apply.
+Semantic Work records are not execution.
+Retrieval readiness describes bounded evidence gaps; the model resolves relevant
+gaps and owns semantic sufficiency. It is not a second authorization/approval gate.
+Missing implementation requires a scoped architecture decision and implementation,
+rather than repeated substrate discovery. This adds prompt context only, with no
+dispatch authority, schema, lifecycle or heuristic productivity gate.
+Model judgment owns
+which coherent wave advances the authorized objective; no keyword/count/score
+gate, claim bypass, forced code mutation or automatic goal completion is added.
+Context materialization owns bounded, redacted source bytes and their line/hash/
+truncation metadata; the MCP facade must preserve them together. Explicit code
+needles retain lexical coverage even when fuzzy structural candidates fill the
+discovery budget. Existing current-turn provider status also recognizes analysis
+paused as unavailable response delivery, retaining outcome-unknown classification
+and the same single bounded resume. A live generating surface still blocks Send.
+The read-only Work continuation projection directs open Work toward its next
+authorized scoped step rather than prescribing a retired model-facing claim
+operation. Existing execution admission and writer/resource fences still apply.
+
+Newly rendered Supervisor prompts use the typed outer automation metadata already
+present on Forge tools: exact `automation_task_id`,
+`automation_type=autonomous_continuation`, and `automation_status`. Intermediate
+calls use `working`; the final Forge call for the turn uses `continue`, `done` or
+`needs_user`. Receipt processing still derives the exact source effect from the
+canonical Supervisor task and reserves the successor transactionally; tool payloads
+do not choose another task/effect/conversation. The historical
+`rh_work repair` / `automation.receipt:*` parser remains a bounded migration reader
+only for prompts already issued before cutover and must not be used by new prompt
+producers or become a second replay authority.
+
+An explicitly launched child ChatGPT Work already goes through
+`ensureWorkflowSupervisorEnrollmentForWork`: a distinct canonical conversation
+gets its own existing task/effect journal, while a reused conversation returns
+its original owner. Subsequent turns and accepted termination use the same
+Supervisor and disposable tab cleanup. Prompt guidance requires enrollment
+before a handoff; it does not create child conversations or a second parent
+lifecycle. Existing typed Work relations carry decomposition when needed.
+
+Verification extends retained compatibility, provider-wait and continuation
+scenarios. Whole-Runtime activation follows canonical gates; actual productive
+successive turns remain separate live acceptance evidence. Original exhausted
+records are preserved and may only receive the existing explicit operator
+recovery after the exact provider turn is proven settled or failed.

package/docs/architecture/decisions/20261005-forge-v3-desktop-client-boundary.md

@@ -0,0 +1,77 @@
+# Forge V3 desktop client boundary
+
+Status: accepted
+Date: 2026-10-05
+Authority: [`../CURRENT.md`](../CURRENT.md)
+
+## Decision
+
+Forge V3 introduces a fresh cross-platform desktop client under `apps/desktop`. The client is a presentation and interaction adapter over the existing Forge Runtime and Controller authorities; it is not a second control plane and does not reuse the retired Local Bridge web frontend as product architecture.
+
+The initial macOS shell exposes two explicit interaction modes without creating a new domain state machine: Local for client-owned conversation interaction, and MCP for Projects/Work plus Runtime/Recovery operations. A lightweight sidebar selects mode, repository scope and Work; the single main surface shows either the Local conversation or the MCP repository/work surface and immediate actions. Plan, evidence, IDs and mechanical Runtime facts are disclosed on demand rather than occupying a permanent inspector. These surfaces are views over canonical Runtime facts rather than independent client state machines.
+
+## Authority boundary
+
+- Requirement, Plan, Work, ControllerSession/ControllerRound, Scheduler, Workflow Supervisor, repository/worktree identity, connections and Runtime/Recovery lifecycle remain authoritative in their existing Forge owners.
+- The desktop client may own only transient presentation state such as selected navigation, active inspector tab, draft text, window geometry and replaceable transport handles.
+- The client must not persist a mirrored Requirement/Plan/Work database, infer semantic completion from UI state, or create a client-side scheduler/retry authority.
+- Runtime reads enter through typed projection/query contracts. Runtime mutations enter through existing typed Runtime/Controller capabilities and preserve their CAS, effect, authorization and outcome-unknown semantics.
+- Tauri owns desktop shell mechanics only. Starting or closing the UI must not mint another Forge Runtime, Recovery, Scheduler or Supervisor authority.
+- A disconnected UI is an adapter availability state. It does not redefine Work, Scheduler or Runtime semantic state.
+- Runtime/Recovery history is projected from the standalone Recovery authority's bounded canonical audit tail. The projection exposes event/time and a bounded outcome bit only, omits arbitrary audit detail and local paths, and is never persisted or reconstructed by the desktop client.
+
+## Foundation layout
+
+`apps/desktop/src/runtime-projection.ts` defines the projection-facing client boundary. Its bootstrap value is presentation-only and intentionally says `Runtime not connected`; no fake Requirement, Plan, Work or connection facts are synthesized before Runtime integration lands.
+
+`apps/desktop/src-tauri` is the fresh Tauri 2 shell. Platform-specific code remains behind this shell/provider boundary so Windows support can be added without changing semantic ownership.
+
+## Runtime transport
+
+The desktop shell reaches Canonical Runtime through its existing loopback MCP HTTP transport. The Tauri process resolves the installed Controller Home and Runtime service configuration, reads the Runtime bearer token only inside the native process, and issues stateless MCP `tools/call` requests. The token is never projected into the webview. Desktop mutations therefore still enter through `capability_execute`; the current automatic-continuation conversation switch calls `controller.workflow_supervisor.switch_to_fresh_conversation` and preserves the Supervisor CAS/effect fences.
+
+The bridge is intentionally typed and narrow. It exposes only the product facts/actions needed by the current macOS surfaces: Repository Registry projection, bounded repository/runtime status, selected Work detail, Requirement detail, Plan detail, pending UserRequest projection, automatic-continuation projection, controller/tunnel connection projection, explicit Work continuation, explicit fresh-conversation migration, and bounded connection repair. Each command forwards to an existing Forge facade/tool; it does not expose Controller Home persistence, a generic database API, or a client-owned retry/session engine.
+
+## Project Workbench projection
+
+The V3 Project Workbench remains projection-only. Entering MCP or selecting a Project first establishes a repository/worktree overview from canonical Repository Registry and repository-state facts; it does not implicitly select or create a Work. The primary MCP surface may summarize the already-projected Repository cleanliness/revision, current Work count, active worktree inventory and Runtime/MCP readiness in compact operational cards; once a Work is selected, the same summary layer may surface canonical Work revision/state, linked Plan revision/status, execution-evidence phase/check counts and Repository state before the detailed sections. These summaries are derived only from the projection already in memory and never become a client-owned status model. Project navigation reads the canonical Repository Registry through `repository_list`; active checkout/worktree inventory comes from the existing `repository_get(detail)` authority, then the native bridge strips it to checkout id, local path, branch, worktree kind, lifecycle and active identity and bounds the WebView list rather than copying complete historical Registry records; bounded Git/repository state comes from `rh_status(list)`; the sidebar's current Work collection and bounded recent completed/cancelled history come from canonical `rh_work(list)` rather than a client-invented `rh_status` snapshot shape; once the user selects a Work, its canonical `revisionHistory`, its decomposition/dependency graph, and a bounded execution-evidence projection come from `rh_work(get, detail)`; linked Requirement and Plan authored facts plus canonical Plan `revisionHistory` are read through `rh_work(requirement_get)` and `rh_work(plan_get, detail)`. The Work detail execution projection is sourced from the canonical WorkContract execution fields (`dispatchState`, `evidenceState`, `phase`, `workKind`, `completionOutcome`, declared checks, `phaseEvidence`, verification records and `evidenceRefs`) and strips process-local artifact paths or other unnecessary mechanics before crossing into the webview. The MCP Work surface may drill into the already-projected verification timing, stale reason, bounded receipt facts and evidence-reference identity/summary so a user can audit why a check is considered valid or stale; it must not re-run a check, infer freshness, resolve artifact paths or manufacture receipt state in the renderer. Work remains semantic scope only: unless a separate canonical execution-placement fact is supplied, the desktop must not present the Project active checkout as the Work's execution checkout. The desktop must not parse semantic `resultRefs` to infer check outcomes, phase completion, execution placement or execution progress. Pending human-boundary facts come from instance-level `rh_inbox(list)` and are filtered to an exact `targetScope.workId` match before appearing in the selected Work surface, so the client does not turn the main workspace into a global/stale handoff dump. The focused surface may show Work semantic state/revision, repository dirty state, branch/source revision and canonical `nextSafeAction` as a compact fact strip, while Requirement outcome/acceptance criteria, Plan items, Work parent/dependencies, execution/check evidence, semantic revision history and result references remain progressive disclosure. History renders recorded semantic revisions as supplied; the client does not calculate progress, backfill missing revisions, or reinterpret historical state. Selecting a Project or Work changes only transient desktop presentation state. An explicit MCP refresh may re-read Repository Registry, repository/worktree facts, Work/Plan/evidence projection and Supervisor facts as one user-requested snapshot refresh; it does not poll, reconcile, retry or maintain a client-owned synchronization lifecycle. The client does not persist or reconstruct Work, Requirement, Plan, UserRequest, Git or Scheduler authority.
+
+Continuing a selected Work is an explicit user mutation routed through `rh_work(launcher_start)` with the selected repository and Work identities. Automatic-continuation metadata comes from `controller.workflow_supervisor.list`; exact conversation URL, repository/Requirement contract bindings and created time are rendered only when supplied by the Supervisor authority. The desktop does not create its own controller session, retry loop, conversation authority, UserRequest lifecycle, or lifecycle transition.
+
+The shipped desktop UI is Chinese-first. Domain IDs, repository names, user-authored objectives and external product names remain verbatim canonical data, while navigation, labels, states, actions, errors and explanatory copy are rendered in Chinese.
+
+## Local conversation boundary
+
+Local Thread is client-owned interaction data, not a Forge semantic lifecycle record. The desktop may persist a bounded local transcript plus presentation metadata and an optional canonical repository id reference, but it must not copy Requirement, Plan, Work, Runtime or connection records into that store as mutable truth.
+
+Current Kernel `ControllerSession` / `ControllerRound` contracts are intentionally Work-bound. Local conversation therefore must not manufacture a Work merely to obtain a controller binding, and it must not reinterpret Workflow Supervisor or `launcher_start` as a general chat-session authority. Provider status and invocation live behind the typed `controller.local_conversation` capability. The initial provider is the installed Codex CLI and reuses Codex-owned authentication; Forge does not copy provider credentials into Controller Home or the renderer. Each local thread receives an invocation-scoped Forge MCP principal/session, while the provider thread id remains only an opaque resume handle. The provider/controller loop calls the existing Runtime MCP capabilities as tools, so Forge continues to own those capability effects and canonical semantic facts.
+
+Local Codex sessions start in a read-only provider sandbox. Repository and Runtime mutations therefore go through the injected Forge MCP capability surface rather than direct provider filesystem writes. Client-local thread create/select/archive, optional Project attachment, provider resume, and final assistant responses are functional without implicit Requirement/Plan/Work/ControllerRound creation. If Codex or Runtime is unavailable the UI reports that failure directly; there is no synthetic assistant output and no fallback to the retired Local Bridge/browser-profile path.
+
+## Runtime and Recovery surface
+
+The Runtime screen must remain usable when Canonical Runtime is unavailable. The native Tauri adapter therefore has a second narrow transport path to the already-authoritative Standalone Recovery Gateway at its configured loopback MCP endpoint. It reads the Recovery configuration and bearer token only inside the native process; Recovery credentials are never projected into the webview.
+
+This is not a fallback Runtime and does not start, stop, repair, or roll back any process directly. Readiness and diagnostics call Recovery's `runtime_status` and `verify_stable_runtime`. Explicit user mutations are limited to named Recovery tools such as `restart_primary_runtime` and `recover_primary_runtime`. Before a mutation, the adapter re-reads `runtime_status` and hydrates the exact host/platform/ControllerHome/Recovery-release/target-Runtime fencing identity exposed by Recovery itself; Standalone Recovery remains the authority that validates or rejects the operation.
+
+No client retry loop or inferred recovery lifecycle is introduced. The UI may own only transient loading/error/confirmation state around one explicit command, then it re-reads Recovery authority after completion. `restart_primary_runtime` already stops/quiesces as needed, starts the configured launchd/systemd service and verifies the whole Runtime, so the desktop may label that same Recovery-owned mutation `Start Runtime` when `runtime_status.running=false` and `Restart Runtime` otherwise; this creates no second start authority. `recover_primary_runtime` remains a distinct deeper recovery transaction that can enter release recovery/rollback and is exposed only as an explicitly warned action while Runtime is not ready.
+
+Controller and remote-transport setup is projected separately through the typed `controller.connection` capability. That facade derives product-safe status from the existing setup-profile authority (`readSetupProfile`, `resolveControllerGuidance`, and `resolveTunnelGuidance`) and does not persist a second connection model. Its only automatic mutation, `repair_connector`, delegates to the existing `runMcpSetupChatgpt` owner for the Forge-managed loopback Connector. OpenAI Secure Tunnel, Cloudflare, Tailscale, client installation, login, tunnel identity, and other external prerequisites remain explicit setup requirements rather than being silently repaired by the desktop client. Tauri and the webview never read or write setup files directly.
+
+## macOS presentation model
+
+The macOS client uses the system-owned decorated window. The webview must not draw duplicate traffic-light controls or treat an application toolbar as a synthetic title bar. Window close/minimize/zoom chrome remains owned by macOS/Tauri.
+
+The primary V3 layout is intentionally sparse: one lightweight navigation sidebar and one main work surface. A compact Local/MCP switch changes presentation scope only. In MCP mode, Project selection opens a repository/worktree overview and Work inventory; Work selection then focuses the same main surface on the selected Work and its immediate actions. Repository/Work/Plan/Evidence readiness may appear as a compact summary band on that main surface so MCP operation does not require opening several disclosure sections merely to understand current state. IDs, revision history, raw evidence references, runtime mechanics, and other secondary facts remain progressive disclosure rather than a permanent inspector column. Runtime/Recovery is a dedicated MCP main surface rather than a dashboard side panel.
+
+This follows the desktop-agent interaction model of task/session navigation plus a focused work area. It explicitly rejects a three-column web-dashboard composition as the default macOS product architecture.
+
+## Verification
+
+This foundation is acceptable when:
+
+1. the frontend source and Tauri shell form an independently reviewable application boundary;
+2. no desktop source imports Runtime persistence stores or writes Controller Home state directly;
+3. the UI can render without manufacturing semantic domain data;
+4. project source authority includes `apps/**` so future engineering checks and context retrieval treat the client as first-class source;
+5. subsequent Runtime bootstrap work can replace the disconnected projection through a typed client adapter without migrating client-owned semantic data, because none exists.

package/docs/architecture/domains/verification.md

@@ -17,6 +17,14 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 
 - Self-host and generated behavior must be checked together when shared assets change.
 - `bun test` is the broad regression gate.
+- Governed tests preserve typed per-file failure evidence (`source`, `fixture`, `infrastructure`, `interrupted`) in bounded receipts; Check/Work verification may collapse that evidence only to the existing acceptance-vs-infrastructure authority, never by reparsing human stderr.
+- The active Runtime always owns Process admission, leases, terminal Process state, and Work verification receipts. For ordinary repositories, persisted checks execute through that Runtime's immutable Check Runner.
+- Self-hosting Forge Work verification is the bounded exception to runner location, not to lifecycle authority: when the verified repository has the same durable `repoId` as the Runtime Source authority, a non-live verification snapshot executes the Check Runner from that exact candidate snapshot. Candidate runner/content identity is folded into the existing Check execution fingerprint so evidence cannot cross runner revisions.
+- A Work verification snapshot establishes its package dependency closure inside the existing Check Process before loading candidate Check Runner modules. Exact canonical `node_modules` reuse remains valid only when dependency metadata is equivalent; otherwise the disposable snapshot materializes dependencies from its own supported frozen lockfile. Bootstrap failure is infrastructure failure and never repository acceptance evidence.
+- `live_controller_home` certification never uses the candidate snapshot runner because it is explicitly verifying the installed Runtime. A candidate snapshot missing its Forge-owned sidecar fails closed; no arbitrary executable override or second scheduler/store is introduced.
+- Public `rh_work verify` accepts either one `check_id` or one non-empty `check_ids` batch, never both. A batch is admitted only when the registered checks form one ordinary resource-compatible wave according to Process Runtime `buildCheckExecutionSchedule`; invalid, cross-wave, release, and multi-phase batches fail closed before partial execution. Every admitted member still runs through the canonical Work verification service, Work snapshot, Process Runtime claims, Failure Contract, and VerificationRecord authority; batch aggregation is not a scheduler or lifecycle authority.
+- Work verification persistence is one read-modify-write authority: any decision derived from current `checkRefs`, scope evidence, review state, or lifecycle state must read the latest Work and derive its patch inside the existing Work-store writer critical section. Synchronous writer contention remains fail-fast/retryable rather than sleeping on the Gateway path; a retry must re-read current state before deriving its mutation, so stale snapshots cannot silently erase compatible evidence.
+- Legacy Work lifecycle inference is migration-only. The exact bounded historical shapes accepted by the compatibility migrator, including the pre-review-checkpoint schema-v3 row, are canonicalized and persisted once with revision-fenced Controller Home authority. Normal current-schema reads validate canonical state; malformed schema-v3 rows outside those historical shapes fail closed instead of receiving generic read-time repair.
 - `check-task-sync.sh` enforces that substantive repo changes update `tasks/`.
 - `check-task-workflow.sh --strict` is the repo-local harness readiness gate.
 - `sync-brain-docs.sh --check` verifies manifest-controlled repo-to-brain mirrors without making gbrain or MCP part of hook correctness.

package/docs/architecture/domains/workflow-engine.md

@@ -18,7 +18,7 @@ verify without a live service.
 ## Stable Rules
 
 - `assets/workflow-contract.v1.json` is the canonical contract asset.
-- `.ai/harness/workflow-contract.json` is the installed runtime copy.
+- `forge.config.json` (legacy `.ai/harness/workflow-contract.json` remains migration-only) is the installed runtime copy.
 - Migration deletes only manifest-owned `known_generated` surfaces.
 - User-authored legacy docs are preserved or archived before template refresh.
 - `_ref/`, `_ops/`, secrets, local env, and custom hooks are not product migration surfaces.
@@ -28,3 +28,9 @@ verify without a live service.
 - `bun test tests/migration-script.test.ts tests/create-project-dirs.runtime.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/migrate-project-template.sh --repo . --dry-run`
 - `bash scripts/check-task-workflow.sh --strict`
+
+## Autonomous WorkflowRun name boundary
+
+This repo-mutation **Workflow Engine** and the existing declarative `workflow_run` checkpoint records are not the cross-assistant-turn lifecycle authority for an autonomous development Goal.
+
+The V1 Workflow Supervisor defined in [`../decisions/20260916-workflow-supervisor-authority.md`](../decisions/20260916-workflow-supervisor-authority.md) uses a distinct Supervisor persistence authority/namespace. It may eventually converge with declarative Workflow assets only through an explicit migration and authority decision. Shared terminology is not permission to share writers, reinterpret persisted states, or copy lower-layer lifecycle states upward.

package/docs/architecture/index.md

@@ -8,7 +8,7 @@ The canonical documentation model is intentionally small:
 - [`../ROADMAP.md`](../ROADMAP.md) — current and next architecture/product priorities.
 - [`EVOLUTION.md`](EVOLUTION.md) — append-only historical architecture change log.
 - [`versions/`](versions/) — per-version architecture snapshots.
-- [`history/`](history/) and [`history.md`](history.md) — archived historical evidence, never runtime authority.
+- [`history.md`](history.md) — compatibility pointer to the evolution log and Git history; never runtime authority.
 - [`../../CHANGELOG.md`](../../CHANGELOG.md) — release history.
 - `decisions/` — accepted ADR rationale; accepted invariants are folded into `CURRENT.md` when they become ordinary current architecture.
 - `requests/` — pending architecture drift/change requests only.
@@ -19,7 +19,7 @@ Executable code and persisted schemas are authoritative for implementation facts
 ## Pending Architecture Requests
 
 <!-- BEGIN ARCHITECTURE PENDING REQUESTS -->
-- (none)
+- [ ] 2026-09-04 [unknown] `unknown` -> [2026-09-04-computer-plugin-workflow-taxonomy](requests/2026-09-04-computer-plugin-workflow-taxonomy.md)
 <!-- END ARCHITECTURE PENDING REQUESTS -->
 
 ## Accepted Architecture Decisions
@@ -28,4 +28,4 @@ Existing accepted ADRs remain under [`decisions/`](decisions/). Once a decision
 
 ## Change discipline
 
-Do not create another current-architecture page for each refactor. Architecture-root Markdown is limited to `CURRENT.md`, `EVOLUTION.md`, `history.md`, and this index; historical pages belong under `history/`. Update `CURRENT.md` only when the architecture contract changes, update `ROADMAP.md` when priorities change, append `EVOLUTION.md` for material architecture transitions, and create/update a version snapshot only at a release/version boundary. Implementation phases, pending manual work, operator-local paths, and other execution status belong in durable Work/Plan evidence rather than maintained current architecture.
+Do not create another current-architecture page for each refactor. Architecture-root Markdown is limited to `CURRENT.md`, `EVOLUTION.md`, `history.md`, and this index. Obsolete architecture evidence belongs in Git history rather than a maintained history tree. Update `CURRENT.md` only when the architecture contract changes, update `ROADMAP.md` when priorities change, append `EVOLUTION.md` for material architecture transitions, and create/update a version snapshot only at a release/version boundary. Implementation phases, pending manual work, operator-local paths, and other execution status belong in durable Work/Plan evidence rather than maintained current architecture.

package/docs/architecture/modules/controller-runtime/transport-lifecycle.md

@@ -5,20 +5,31 @@
 
 ## Responsibility
 
-`src/cli/mcp/transports/` owns HTTP authentication handoff, MCP Streamable HTTP session lifecycle, global admission capacity, transport leases, DELETE cleanup, and liveness/readiness metrics. It does not own durable Job execution or Gateway process recovery.
+`src/cli/mcp/transports/` owns HTTP authentication handoff and protocol-era serving. MCP 2026-07-28 is the canonical public boundary and is served per request without protocol-level sessions. The session registry, global admission capacity, transport leases, and DELETE cleanup exist only for the explicit 2025-era compatibility path. The transport does not own durable Work/Process/ControllerRound authority or Gateway process recovery.
 
 ## Invariants
 
-- All public MCP HTTP routes share one registry and one global maximum.
-- Route and authenticated principal must match the stored session on GET, POST, and DELETE.
-- Active POST work is protected from capacity eviction.
-- Stream-only sessions are reclaimable through client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime, or oldest-safe capacity eviction.
-- Initialize admission is an atomic registry reservation. Shared static-bearer clients use the global pool; per-principal fairness applies only where authentication provides a meaningful distinct principal.
-- Health metrics report actual global counts; readiness reflects whether initialize can be admitted safely.
-- Closing transport state never implies that a durably accepted Job is cancelled.
+- Modern `server/discover` and subsequent 2026-07-28 requests are handled by the SDK v2 per-request handler and do not require or emit `Mcp-Session-Id`.
+- Durable Work, Process, and ControllerRound identity is independent from both modern request bindings and legacy transport sessions.
+- A newly created Work may receive an opaque Work-bound controller capability for Runtime recovery and replay fencing. That capability is internal to normal model-facing Work execution: the Runtime/Supervisor establishes, rotates, and recovers it. Legacy owner records without a capability digest may use the explicit `controller_claim` compatibility upgrade; ordinary model-facing Work operations never require it.
+- Legacy 2025-era traffic is classified mechanically by the SDK and routed to one bounded stateful compatibility registry shared by all public MCP HTTP routes.
+- On the legacy path, route and authenticated principal must match the stored session on GET, POST, and DELETE; active POST work is protected from capacity eviction.
+- Legacy stream-only sessions are reclaimable through client DELETE, explicit prior-session replacement, lease expiry, absolute lifetime, or oldest-safe capacity eviction.
+- Legacy initialize admission is an atomic registry reservation. Shared static-bearer clients use the global pool; per-principal fairness applies only where authentication provides a meaningful distinct principal.
+- Legacy capacity readiness distinguishes `immediate`, `eviction`, and `blocked` admission. Capacity eviction releases registry routing/ownership synchronously before old transport cleanup; peer cleanup is best-effort and must never hold the serialized initialize admission lane after the old session is fenced out.
+- Health session metrics describe only legacy compatibility state; modern request serving has no long-lived session capacity authority.
+- Closing or replacing transport state never implies that a durably accepted Work or Process is cancelled.
+- The Gateway-to-Canonical-Runtime client classifies structured SDK HTTP 404 as an expired inner session, reconnects once, and replays only an operation already proven replay-safe by its idempotency contract.
+- The public Gateway may burst-scale a bounded shared pool of inner Canonical Runtime MCP lanes. A released lane remains hot only for a bounded idle lease; reuse cancels retirement, while expiry explicitly terminates the Streamable HTTP session before closing the local client so the Runtime does not retain an orphaned Server/transport graph. Durable Work, Process, and Controller authority is never coupled to that transport retention window.
 
 ## Verification
 
 ```text
 bun test tests/unit/fix-mcp-session-lifecycle.test.ts tests/cli/mcp-http.test.ts
 ```
+
+## MCP Runtime adapter decomposition boundary
+
+The public MCP Tool Contract is frozen independently from implementation placement. `check:mcp-compatibility` records both the stable tool-name fingerprint and the canonical schema fingerprint, so moving a handler between adapters cannot silently change the connector ABI.
+
+`runtime-tools.ts` and `router.ts` are currently migration debt, not architecture authorities. Runtime Architecture keeps shrinking inventories for their direct imports into Kernel/Context/Control Plane/Execution/Recovery/Plugin/Workflow/Repository domains and for the `callRuntimeTool` switch cases. A stage may remove an inventory entry only when ownership moves behind the correct domain adapter/application API; adding a new entry fails the architecture gate. This deliberately avoids source-line-count rules while making mega-adapter regrowth mechanically impossible.

package/docs/architecture/requests/2026-09-04-computer-plugin-workflow-taxonomy.md

@@ -0,0 +1,124 @@
+# Computer / Plugin / Workflow taxonomy convergence
+
+> **Status**: Pending
+> **Detected**: 2026-09-04
+> **Requirement**: `REQ-forge-v2-durable-agent-harness-foundation-20260902`
+> **Predecessor plan**: `PLAN-kernel-v2-module-authority-computer-convergence-20260903-r2`
+> **Captured successor draft**: `PLAN-kernel-v2-module-authority-computer-workflow-convergence-20260904-r3`
+> **Source revision reviewed**: `18490210a328fac2c4585ee4f2d43771dec19d3d`
+
+## Why this request exists
+
+The existing V2 Computer convergence plan already covers the important Computer-side architecture: `computer` as the single normal public interaction product, Browser/Desktop semantic namespaces, one durable interaction ownership graph, provider-only native Desktop Operator semantics, Process Runtime resource authority, and `outcome_unknown -> observe/reconcile`. It does **not** yet make the higher-level Plugin taxonomy or runtime Workflow model an explicit executable architecture boundary.
+
+Current source proves the gap: `src/runtime/plugins/first-party-registry.ts` registers Computer, Browser, true API integrations and the Xiaohongshu publishing flow through the same `AssistantPluginAdapter` abstraction. `src/runtime/plugins/xiaohongshu-publish.ts` is a compiled Browser workflow: it owns site URLs, selectors, visible-text anchors, publish modes, auth/page-state classification, ordered Browser actions and post-publish verification, then executes the actual steps through the Browser capability. That is workflow content, not an independent plugin/provider authority.
+
+## Required taxonomy
+
+V2 must explicitly distinguish four concepts even if compatibility transport still exposes `plugin_action_execute`:
+
+1. **Capability**: reusable semantic operation Forge can request.
+2. **Provider**: replaceable implementation of one or more capabilities.
+3. **Integration**: external-system owner justified by an independent protocol/auth/security/persistence/lifecycle boundary. Platform branding alone is insufficient.
+4. **Workflow / Recipe**: user-goal composition of capabilities. Site-specific URLs/selectors/visible-text/page-state/verification sequences belong here unless a real Integration boundary exists.
+
+`Plugin` must not remain the only internal taxonomy. A shared tool/manifest transport does not grant equal authority semantics.
+
+## Computer boundary that must be preserved
+
+- `computer` remains the single normal public interaction product.
+- Browser and Desktop remain distinct semantic subdomains beneath Computer.
+- Browser DOM/CDP/navigation/query/file-input semantics are preferred when stronger than physical input.
+- Desktop Operator/native macOS is provider/device-driver only: OS/TCC/socket/handshake/capture/input/live handles. It does not own Forge workflows, policy, durable lifecycle, semantic completion, scheduling or independent retry/reconciliation.
+- Browser session/Computer target state converges under one deliberate durable interaction ownership graph in Controller Home. Provider/browser/OS handles remain rebuildable observations.
+- Non-idempotent mutations never blind-replay after `outcome_unknown`; existing observe/reconcile authority remains canonical.
+- Process Runtime claims/leases remain the only execution concurrency authority.
+
+## Computer hot-path transport contract
+
+The 2026-09-09 #200 latency review proved that the native Desktop Operator is not the dominant warm-path cost, so provider transport optimization must preserve the existing authority boundary rather than introduce another controller or durable provider session. The Computer runtime therefore uses the following transport contract:
+
+- one live Desktop Operator provider binding is scoped to the current trusted registration identity/revision and endpoint contract;
+- provider identity/capability negotiation is reused only while the same Unix-socket connection generation remains live;
+- sequential Computer requests may reuse that bounded JSONL channel instead of reconnecting and handshaking for every action;
+- registration fingerprint/revision or endpoint-contract change disposes the old provider binding before replacement;
+- if the Unix connection changes after negotiation, the pending action is rejected before dispatch and the next explicit invocation must renegotiate; non-idempotent effects are never replayed automatically;
+- timeout, cancellation, response-size and protocol-error bounds remain per request; transport reuse creates no new durable lifecycle or retry authority.
+- Browser semantic mutations do not pay an unconditional fixed post-action sleep: provider primitives and bounded post-action identity/evidence are the normal completion path; `post_action_wait_ms` is explicit compatibility input only, while native foreground activation may retain a provider-specific verification budget because system foreground authority must be observed.
+- Desktop target-bound semantic actions dispatch through the current leased provider binding without a `desktop_status(limit: 500)` preflight. Only an explicit provider `SESSION_NOT_FOUND` transported as a failed/pre-effect result may rebuild the binding from stable application identity and retry once; transport, timeout, and outcome-unknown failures are never replayed. Target close likewise calls the bound session close directly instead of enumerating provider sessions first.
+- Desktop observe/input/capture product actions use the retained `ComputerProvider` channel instead of re-entering the legacy external-adapter transport for every semantic action. Target open/close remain low-frequency provider lifecycle operations; the hot path owns no parallel durable provider-session authority.
+- the external Unix JSONL and `ComputerProviderError` failure contracts preserve `failed` versus `outcome_unknown` across adapter boundaries. A provider-declared failure keeps the negotiated connection alive; transport loss after an effectful request is dispatched invalidates negotiation and is never eligible for implicit replay.
+
+The repeatable `benchmark:computer-hotpath` run on 2026-09-09 used 50 warm semantic samples after five warmups. The isolated real dispatch path measured cold first semantic action `4.398ms`; warm `p50=0.939ms`, `p95=1.511ms`, `max=1.894ms`. Across the 50 warm samples the provider observed exactly 50 semantic RPCs, zero new connections, zero handshakes, zero manifest preflights, zero `desktop_status` preflights, and zero session reopens. This benchmark is comparative evidence, not a machine-specific release threshold.
+
+This is a transport/runtime optimization beneath the existing Computer authority. Browser/OS handles remain ephemeral observations, and Process Runtime plus existing unknown-outcome reconciliation remain authoritative for execution concurrency and effect recovery.
+
+## Workflow Asset Contract
+
+Introduce the smallest generic versioned Workflow Asset model needed to move user-goal automation out of Core. Human-editable assets include:
+
+- workflow definition / step composition;
+- prompt guidance for semantic judgement;
+- deterministic helper scripts;
+- templates/selectors/resources;
+- asset version and content digest.
+
+Machine authority is separate and records only what the runtime must trust/decide, including installed/active workflow identity/version/digest, capability grants/bindings, and bounded execution receipts/checkpoints. Prompt/script bodies are not the primary SQLite authority.
+
+Default active user workflow assets belong under Controller Home, not the Forge source repository or arbitrary target repositories. Project-owned workflow assets are allowed only through an explicit project contract and remain project data. Secrets are referenced through existing secret/authorization authority; workflow files must not become a new secret store.
+
+## Workflow Runtime boundary
+
+The Workflow Runtime is a thin interpreter/composer, **not another Kernel**. It may validate inputs, resolve assets and capabilities, order steps, record subordinate checkpoints/receipts, and request reconciliation. It must not create competing authority for:
+
+- Requirement / Work / ControllerRound lifecycle;
+- semantic acceptance or goal completion;
+- scheduler continuation;
+- retry decisions after unknown external outcome;
+- process/resource locking.
+
+Durable or external-effect workflow execution is subordinate to an existing Work/run identity. Scripts execute only through existing Process Runtime, policy and resource-claim boundaries.
+
+## Xiaohongshu migration proof
+
+Use Xiaohongshu publishing as the first bounded migration proof after Computer/plugin taxonomy convergence:
+
+- remove compiled first-party workflow authority from `src/runtime/plugins/xiaohongshu-publish.ts`;
+- express publish modes, Browser actions, auth markers, selectors, checkpoints and dual verification as versioned workflow data;
+- do not recreate the same platform-specific TypeScript under `packages/workflow-runtime`;
+- any temporary `xiaohongshu` plugin/action compatibility alias is translation-only, owns no workflow state, has bounded consumers and an explicit removal trigger.
+
+If a future official Xiaohongshu API creates a true protocol/auth/resource boundary, only that protocol-facing owner becomes an Integration. User-goal orchestration remains Workflow.
+
+## Architecture gates
+
+Extend the existing architecture checker with ownership-aware rules so new business/site workflows cannot quietly return to Kernel/Computer/provider/first-party integration code. The gate must reject end-user workflow orchestration embedded in generic layers unless an independent Integration boundary is explicitly justified, while still allowing legitimate endpoint/protocol constants inside a real Integration adapter. Prefer import/manifest/ownership rules over brittle string bans.
+
+Workflow asset digest/version changes must invalidate stale binding/receipt reuse. Compatibility shims must have a named replacement owner, bounded consumers and removal trigger.
+
+## Required execution order
+
+Do **not** start a parallel V2 implementation from this request. Preserve the predecessor plan order and execute only after current overlapping V2 Stage8/final-certification/portability work is reconciled:
+
+1. Stage B: shrink module/legacy ownership debt and strengthen existing architecture gates.
+2. Stage C: finish Controller/MCP/composition convergence.
+3. Stage D: finish Computer/Browser/Desktop convergence **and** make Capability/Provider/Integration taxonomy explicit.
+4. Stage E: add Workflow Asset Contract + thin Workflow Runtime + Xiaohongshu migration + anti-regression gates.
+
+Before implementation starts, refresh exact source revision and active path ownership. Never open a second Computer/Workflow plan merely to bypass an occupied or stale scope.
+
+## Plan metadata blocker discovered while capturing this request
+
+The decision-complete successor was persisted as draft `PLAN-kernel-v2-module-authority-computer-workflow-convergence-20260904-r3`, with the four stages and detailed acceptance criteria above. Forge incorrectly persisted its `scopeKey` as `unknown`, so approval is blocked. Creating a successor with the intended scope `kernel-v2-module-authority-computer-convergence-20260903` is also blocked because the scope index still reports terminal predecessor `...-r1` as owner even though r1 already points to r2 and r2 was superseded during successor creation.
+
+This is a Forge Plan authority/index defect, not permission to create a parallel scope. Future V2 mainline must first repair/reconcile the stale scope owner + draft scope-key persistence, then approve/recreate the captured successor under the original scope. Do not delete this request until an approved successor PlanContract with the correct scope exists.
+
+## Completion criteria for this request
+
+This architecture request may be marked complete only when:
+
+- one approved successor PlanContract under the original Computer-convergence scope contains the taxonomy, Workflow Asset, runtime authority and Xiaohongshu migration decisions above;
+- predecessor/draft Plan metadata is reconciled with no duplicate active authority;
+- later implementation proves the Stage D/E boundaries and their focused architecture/type/main checks;
+- `docs/architecture/CURRENT.md` is updated **after** the implementation is true, not before;
+- obsolete public Browser/workflow-plugin compatibility authority is removed or bounded with an explicit removal trigger.

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: