@moretea-labs/forge 1.6.0 → 1.7.0

package/docs/architecture/history.md

@@ -1,38 +1,7 @@
-# Architecture Evolution History
+# Architecture History
 
 > **Historical Design — Not Runtime Authority**
->
-> Current architecture: [`docs/architecture/current/README.md`](current/README.md).
 
-This document is the compact history of the Controller Runtime architecture. Detailed superseded V5–V8 design and verification documents were removed from the current tree after their useful decisions were consolidated here. Their exact contents remain recoverable from Git history.
+The maintained architecture evolution log is [`EVOLUTION.md`](EVOLUTION.md), and the current contract is [`CURRENT.md`](CURRENT.md).
 
-## V5 — Durable execution and closure
-
-V5 separated durable Issue and Task intent from individual Run attempts. It introduced explicit run failure semantics, evidence-gated progress, direct local execution, governance diagnostics, and terminal Issue archiving. The lasting rule is that a failed attempt must not silently cancel the underlying task and that completion must be supported by durable evidence.
-
-## V6 — Direct change first
-
-V6 made bounded Direct Edit the default for known, low-to-medium-risk changes. It added stale-write guards, explicit allowed paths, atomic patch operations, persisted diffs, targeted checks, rollback, and finalization. The lasting rule is that a small change should not require an agent worktree when a transactional edit can prove exactly what changed.
-
-## V7 — Execution first and task-local policy
-
-V7 classified execution by task scope and risk, selected workspace or worktree isolation deliberately, and tightened task-local verification and lifecycle handling. The lasting rule is that execution mode is chosen from current task evidence rather than from a global one-size-fits-all workflow.
-
-## V8 — ChatGPT facade and visual controller
-
-V8 established the compact ChatGPT-facing facade, Direct Edit as the common path, optional agent execution, recovery projections, and a visual Local Controller. Later revisions moved heavy reads off the Gateway hot path, bounded default responses, and retained atomic typed tools behind the facade.
-
-## Legacy ChatGPT Controller and Local Bridge
-
-The earlier Controller and Local Bridge documents described recovery projections, compact MCP capabilities, Local Job tickets, visual review, diagnostics, and optional Codex or Claude sessions. Their current contracts now live in executable code, `docs/architecture/current/`, and `docs/operations/`; these older documents are no longer separate product surfaces.
-
-## Verification records
-
-V5, V6, and V8 verification files were snapshots of checks performed against specific historical revisions and environments. They are not current release evidence. Current verification is produced by repository checks, durable Evidence records, and exact-revision test output.
-
-## Preservation policy
-
-- Current architecture belongs only in `docs/architecture/current/`.
-- Important superseded decisions are summarized here instead of keeping many competing design documents.
-- Detailed removed documents remain available in Git history.
-- Historical text never overrides executable behavior, persisted schemas, accepted ADRs, or the current architecture set.
+Older V4–V8, Supervisor, Local Bridge, Issue/Task/Job, recovery, routing and migration documents remain available through Git history. They are intentionally not maintained as parallel architecture surfaces.

package/docs/architecture/index.md

@@ -1,100 +1,20 @@
 # Architecture Index
 
-> Controller Runtime architecture entry point.
+> Architecture request index and compatibility entry point. **Runtime Authority:** [`CURRENT.md`](CURRENT.md).
 
-## Runtime Authority
+The canonical documentation model is intentionally small:
 
-**`docs/architecture/current/` is the only Runtime Authority for the current and target Forge Controller Runtime architecture.**
+- [`CURRENT.md`](CURRENT.md) — sole maintained current architecture authority.
+- [`../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.
+- [`../../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.
+- `researches/`, plans and Work records — evidence, not architecture authority.
 
-Start here:
-
-- [Current architecture map and reading order](current/README.md)
-- [Architecture governance contract](current/governance.md)
-
-When current implementation, the consolidated architecture history, a research note, and a document under `current/` disagree, the following precedence applies:
-
-1. executable code and persisted schemas describe **Current Implementation** facts;
-2. `docs/architecture/current/` defines the approved **Target Architecture** and mandatory **Migration Rules**;
-3. accepted ADRs may amend the target architecture until their conclusions are merged into `current/`;
-4. the consolidated history, snapshots, plans, research reports, and diagrams are historical or exploratory evidence only.
-
-A target rule is not evidence that the implementation already satisfies it. Every current architecture document must distinguish:
-
-- **Current Implementation** — behavior verified in code, tests, or persisted schemas;
-- **Target Architecture** — the approved end state that future work must converge toward;
-- **Migration Rule** — constraints that apply while moving from the current implementation to the target.
-
-## Current Controller Runtime Scope
-
-Forge is a repository engineering control plane. It includes:
-
-- MCP and local UI entry points;
-- a multi-repository registry and per-repository runtime storage;
-- Issue, Task, Job, Run, Direct Edit, Verification, and evidence lifecycles;
-- optional Codex, Claude, and GitHub Copilot execution;
-- workspace and worktree isolation, integration, checks, recovery, and governance;
-- future schedule-driven bounded occurrences and cross-repository orchestration.
-
-It is not the product runtime of the repositories it manages. It must not replace repository-owned build, test, deployment, or release systems as the final authority.
-
-## Architecture Document Classes
-
-| Class | Location | Authority |
-| --- | --- | --- |
-| Current architecture | `docs/architecture/current/` | Runtime Authority |
-| Architecture decisions | `docs/architecture/decisions/` | Binding until merged or superseded |
-| Pending drift requests | `docs/architecture/requests/` | Proposed change only |
-| Architecture snapshots | `docs/architecture/snapshots/` | Historical evidence |
-| Consolidated architecture history | `docs/architecture/history.md` | Historical Design / Not Runtime Authority |
-| Research reports | `docs/researches/` | Hypothesis and supporting evidence |
-| Plans and task records | `plans/`, `tasks/` | Execution intent and progress, not architecture authority |
-| Diagrams | `docs/architecture/diagrams/` | Explanatory projection; semantic Markdown source wins |
-
-## Current Architecture Set
-
-The maintained current architecture set contains:
-
-- `README.md` — map, status labels, and reading order;
-- `governance.md` — authority, ownership, ADR, and drift rules;
-- `system-overview.md` — system boundary and process topology;
-- `personal-assistant-plugin-baseline.md` — concrete assistant/plugin/provider boundary, threat model, capability matrix, and migration baseline;
-- `architecture-invariants.md` — rules implementations must not violate;
-- `entity-model.md` — Issue, Task, Job, Run, Edit Session, Verification, Schedule, Occurrence, Claim, and Lease semantics;
-- `job-and-run-lifecycle.md` — durable execution and retry state machines;
-- `dispatch-and-agent-strategy.md` — Direct Edit, Quick Agent, durable Task, and role selection;
-- `scheduler-and-resource-claims.md` — repository actors, resource claims, leases, and conflict behavior;
-- `multi-repository-execution.md` — quotas, fairness, failure isolation, and portfolio workflows;
-- `automation-and-schedule-engine.md` — bounded occurrences, budgets, backoff, deduplication, and stop conditions;
-- `failure-recovery.md` — process boundaries, orphan handling, reconciliation, and fencing;
-- `verification-and-release-gates.md` — exact-revision evidence, integration gates, release freeze, and human authorization;
-- `implementation-status.md` — verified implementation coverage and explicit migration gaps;
-- `migration-roadmap.md` — evidence-driven implementation convergence order;
-- `runtime-architecture-simplification.md` — single-owner services, canonical authority/config, immutable activation, Recovery boundary, invariants, and deletion map;
-- ADR [`decisions/20260803-release-identity-binding-and-exit-policy.md`](decisions/20260803-release-identity-binding-and-exit-policy.md) — captured release identity binding for managed children and Supervisor vs launchd failure domains.
-
-A missing or proposed rule must be recorded in an accepted architecture request or ADR and must not be inferred from historical material.
-
-## Architecture Change Flow
-
-1. Identify whether the proposed change alters a boundary, entity semantic, lifecycle, resource rule, safety invariant, or public execution contract.
-2. Record the change as an architecture request or ADR before implementation when the answer is yes.
-3. Update the affected `current/` documents in the same change or explicitly record the temporary drift and its owner.
-4. Update tests and architecture checks that enforce the changed rule.
-5. Consolidate useful superseded decisions in `history.md`, then remove duplicate detailed documents from the current tree while preserving them in Git history.
-6. Close the request only after the current architecture and executable behavior no longer contradict each other, or the difference is explicitly labeled as a migration gap.
-
-See [Architecture governance contract](current/governance.md) for the full rule.
-
-## Existing Domain Documentation
-
-The following domain pages describe the earlier repo-local workflow-harness architecture. They remain useful implementation history but are not the current Controller Runtime authority:
-
-- [Public Surface](domains/public-surface.md)
-- [Workflow Engine](domains/workflow-engine.md)
-- [Runtime Harness](domains/runtime-harness.md)
-- [Verification](domains/verification.md)
-- [Transactional Adoption Planner](transactional-adoption-planner.md)
-- [Global Hook Runtime](global-hook-runtime.md)
+Executable code and persisted schemas are authoritative for implementation facts. `CURRENT.md` defines the architecture contract; a version snapshot or historical note never overrides it.
 
 ## Pending Architecture Requests
 
@@ -104,11 +24,8 @@ The following domain pages describe the earlier repo-local workflow-harness arch
 
 ## Accepted Architecture Decisions
 
-- [Controller-home SQLite state authority](decisions/20260801-controller-home-sqlite-state.md) — versioned controller-owned runtime facts, one-way JSON import, audit records, and phased migration.
-- [MCP Session Lifecycle and Stable Ingress Isolation](decisions/20260718-mcp-session-lifecycle-and-ingress-isolation.md) — one global transport-capacity authority, bounded stream leases, capacity-aware `/ready`, and a supervised ingress child process.
+Existing accepted ADRs remain under [`decisions/`](decisions/). Once a decision becomes ordinary current architecture, its durable rule should be folded into `CURRENT.md`; the ADR remains historical rationale.
 
-## Review Backlog
+## Change discipline
 
-- Continue converging P0 runtime behavior with the gaps recorded in `current/implementation-status.md`.
-- Add link validation and exact-revision release-manifest checks to the final release gate.
-- Keep diagrams as projections of the Markdown semantic source; a diagram must not introduce architecture rules absent from `current/`.
+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.

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

@@ -1,7 +1,7 @@
 # MCP HTTP Transport Lifecycle
 
 > Capability: `mcp-http-transport-lifecycle`
-> Runtime Authority: `docs/architecture/current/architecture-invariants.md` and `docs/architecture/current/failure-recovery.md`
+> Runtime Authority: `docs/architecture/../../CURRENT.md` and `docs/architecture/../../CURRENT.md`
 
 ## Responsibility
 

package/docs/architecture/reviews/2026-08-22-semantic-harness-convergence-acceptance.md

@@ -0,0 +1,39 @@
+# Semantic harness convergence acceptance — 2026-08-22
+
+## Scope
+
+This is the S4 exact-main acceptance record for `PLAN-FORGE-SEMANTIC-HARNESS-CONVERGENCE-20260821-V3R2`. The evaluation snapshot is `f69ad7d1282a8de2335ffe12adb2e54f01fd1b10`, the S3-integrated main revision.
+
+## Explicit evaluation ground truth
+
+The isolated evaluation catalog now has dedicated scenarios for:
+
+- semantic context plus root-to-nearest `AGENTS.md` / `CLAUDE.md` instruction recognition;
+- Scale coordination through approved Plan steps and independent bounded Work;
+- Direct/Lightweight execution with zero durable lifecycle side effects on the fast path.
+
+Each scenario freezes intended behavior, affected domains, invariants, regression risks, an immutable Git snapshot, and an executable focused validator. These scenarios do not create a second runtime or semantic authority.
+
+## Performance acceptance
+
+The Plan references the controller-recorded `03121020` baseline. That identifier is not stored as a repository artifact, so this repository record does not invent missing historical sample values. The durable comparison point available from the Plan is the historical 4–5 second public-gateway spike that motivated S3. Current exact-main measurements are materially below that failure mode:
+
+| Path | Current evidence | Acceptance |
+| --- | ---: | --- |
+| MCP file-read facade | p50 0.8 ms, p95 15.4 ms | no multi-second gateway tax |
+| MCP bounded readonly commands | p50 24.9–28.5 ms, p95 27.2–36.7 ms | no multi-second gateway tax |
+| MCP async Process handle admission | p50 13.9 ms, p95 14.4 ms | bounded and zero legacy Job/Worker side effects |
+| Context steady cold | p50 11.96 ms, p95 12.14 ms | stable after startup |
+| Context hot | p50 0.85 ms, p95 0.93 ms | session cache reuse proven |
+| Context startup cold | 221.79 ms | isolated startup cost, not steady-state |
+| Lightweight pre-spawn harness | p95 15 ms | zero durable Process writes and zero Lease operations |
+
+The gateway benchmark separately attributes classification and routing at approximately 0 ms; observed command time is in the concrete operation. The historical 4–5 second spike was not reproduced.
+
+### Concurrent semantic admission tail
+
+The 32-controller admission stress test remains semantically correct: one shared Requirement resolves to one authority, while 32 independent Requirements resolve to 32 authorities. Holder CPU p95 remains bounded (about 4 ms shared and 9 ms independent in the latest exact-main-aligned run), while wall-clock holder p95 can rise under simultaneous 32-process host scheduling. That divergence is attributed to OS scheduling/preemption rather than additional canonical persistence CPU. The correctness race discovered during S3 (`LOCK_OWNERSHIP_MISMATCH`) was repaired by identity-checked stale-lock reaping, with regression coverage. The benchmark deliberately keeps the wall-clock 10 ms assertion visible rather than hiding host-scheduling variance.
+
+## Architecture outcome
+
+The final contract remains: ChatGPT owns semantic judgement; Forge owns deterministic repository/runtime mechanisms; Plan/Work are the semantic lifecycle authorities; Scale coordinates existing authorities; Direct/Lightweight paths avoid unnecessary durable machinery; `rh_context` returns bounded source and applicable guidance evidence without turning guidance into scope authority.

package/docs/architecture/versions/1.6.md

@@ -0,0 +1,38 @@
+# Forge 1.6 Architecture Snapshot
+
+Status: **Version Snapshot — Not Runtime Authority**
+
+This is the release-family architecture record for Forge 1.6. The live architecture contract is [`../CURRENT.md`](../CURRENT.md).
+
+## Architecture shape
+
+```text
+ChatGPT / semantic controller
+  -> stable 19-tool MCP facade
+     -> Context Engine / repository primitives / plugin dispatcher
+     -> Ephemeral or Lightweight local execution
+     -> optional Work + Durable Process for continuity
+     -> immutable Canonical Runtime release + standalone recovery
+```
+
+## Key contracts
+
+- Default MCP surface: 19 stable tools; `core` and `advanced` are the same bounded default surface.
+- Explicit `full` profile preserves historical compatibility definitions but is not used to construct the default schema.
+- `rh_context` supports progressive raw-source retrieval with exact-known-path reservation, symbol materialization, session caching, CodeGraph hints and changed-file overlays.
+- Ordinary local command execution is Direct/Lightweight by default after command/effect policy admission.
+- Work is selected for continuity, scheduling, external effects, independent deliverables, recoverability or multi-controller coordination—not predicted file/line complexity.
+- Runtime availability/release recovery is separated from ordinary command recovery semantics.
+- Git/worktree, Edit Session, validation evidence, optional Work and optional durable Process each own one concern; compatibility projections are not current mutable authorities.
+- Canonical Runtime activates one immutable whole release and retains the previous release for rollback.
+
+## 1.6 simplification work
+
+The 1.6 line introduced the quality-first executable-harness direction, removed unreachable Local Bridge execution code, detached the stable Controller schema from legacy full-profile definitions, and added an internal TypeScript Language Service navigation prototype for compiler-backed references/definitions/implementations without a new dependency or durable index.
+
+## Known compatibility boundaries
+
+- `toolset=full` remains available for legacy consumers.
+- Some legacy Issue/Task/Job and Runtime modules remain for persisted-state or compatibility reads.
+- Several large modules still need responsibility-based decomposition.
+- TypeScript navigation remains internal until broader repository/project-config behavior is proven.

package/docs/architecture/versions/1.7.md

@@ -0,0 +1,41 @@
+# Forge 1.7 Architecture Snapshot
+
+This is the release-family architecture record for Forge 1.7. The live architecture contract is [`../CURRENT.md`](../CURRENT.md); this file is historical release evidence and must not become parallel runtime authority.
+
+## Controller and execution model
+
+- ChatGPT remains the sole semantic controller. Forge supplies deterministic repository, Work/Plan, Process, Schedule, provider, evidence, recovery, and release mechanisms.
+- Direct/Ephemeral execution remains the default for bounded understood work. Durable Work/Plan state is reserved for continuity, isolation, scheduling, recovery, independent delivery, external effects, or real dependency decomposition.
+- Work, Plan, Schedule, Handoff, Runtime, and Git are the existing durable authorities; Forge 1.7 does not add a second semantic scheduler, agent database, or completion engine.
+
+## Persistent Autonomous Continuation
+
+- Schedule wake resolves an existing durable Work and reuses its bound ChatGPT conversation; a new Controller round reconstructs authority from Forge state rather than chat memory.
+- Round disposition is explicit (`wait`, `continue_immediately`, `wait_for_user`, or `goal_complete`). Forge-owned ChatGPT tabs settle only after the round disposition/release boundary; immediate continuation is fenced against duplicate prompt/Work creation.
+- Local/remote effect Work is distinct from repository-change Work, so runtime/schedule effects can be durably verified and finalized without manufacturing a Git diff.
+- Retryable readiness failures use bounded backoff while user-action/security boundaries stay fail-closed. Stable release acceptance requires real timer-origin continuation evidence, not schedule configuration alone.
+
+## Browser Runtime V3
+
+- Controller Home BrowserSession is the sole durable browser-session authority. Stable provider/resource target identity is distinct from mutable URL/title.
+- Common native/DOM operations are background-safe when capability permits; user-owned tabs are preserved. Physical foreground input is an explicit last-resort provider and still requires independent postcondition verification.
+- Native replacement waits for the exact replacement tab to settle to HTTP(S), rejects transitional `about:*` state as success, preserves strict concrete-resource URL validation, and authorizes cross-origin navigation against the destination origin.
+- Transport, Apple Events, Accessibility, Desktop Operator, or CGEvent success alone is not factual completion; postconditions remain authoritative, and unknown non-idempotent outcomes are never blindly replayed.
+
+## Typed capabilities and global provider profiles
+
+- The ChatGPT facade remains stable while typed domain capability discovery can rank relevant plugin actions from natural intent. Discovery is read-only; `plugin_action_execute` remains the plugin execution authority.
+- Controller-global plugin profiles provide reusable provider configuration with repository overlays/restrictions. App Store Connect configuration carries credential references rather than private-key contents.
+- iOS build automation supports simulator and explicit physical-device destinations plus opt-in provisioning updates using file-backed App Store Connect authentication references, with redacted evidence.
+
+## Runtime, recovery, and release boundary
+
+- Canonical Runtime is activated as one immutable compatible release. Independent Recovery owns restart/rollback and verifies Runtime, Gateway, MCP, Scheduler, and release identity after activation.
+- Source and Runtime coherence remain explicit; advancing source does not silently mutate a pinned Runtime. Release/rollback scope is the complete compatible Runtime rather than individual components.
+- Finalization, target advancement, verification receipts, process/session identity, and lifecycle cleanup remain fenced so unrelated branch/source changes are not attributed to the wrong Work.
+
+## 1.7 release acceptance
+
+- `package:check:main` and `package:check:release` must pass on the exact candidate.
+- Persistent Autonomous Continuation must be demonstrated with real timer-origin Work/conversation reuse and a stabilization-only Continuous Evolution Supervisor soak before stable publication.
+- The immutable `v1.7.0` Git tag, npm `latest` package, published tarball evidence, and active Canonical Runtime must resolve to the accepted release candidate.

package/docs/forge-chatgpt-browser-engine.md

@@ -5,7 +5,7 @@ Forge exposes browser automation through the bundled `browser` capability, the s
 Authoritative references:
 
 - [Browser plugin operations](operations/controller-browser-plugin.md)
-- [Human Interaction Plane](architecture/current/human-interaction-plane.md)
-- [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md)
+- [Human Interaction Plane](architecture/CURRENT.md)
+- [Plugin baseline](architecture/CURRENT.md)
 
 The browser engine is not a second controller, Runtime, plugin marketplace, or lifecycle owner.

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

@@ -27,40 +27,16 @@ The Package Runtime does not require a Forge Git checkout, Bun compilation, Code
 
 ## Local boundaries
 
-Forge keeps two MCP boundaries on loopback by default:
+Forge MCP remains loopback-only, normally at:
 
 ```text
-ChatGPT OAuth Gateway: http://127.0.0.1:8767/mcp
-Canonical Runtime:      http://127.0.0.1:8765/mcp
+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.
+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.
 
-## 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:
@@ -71,7 +47,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 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 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 public HTTPS paths, the configured connector URL is:
 

package/docs/forge-chatgpt-supervised-automation.md

@@ -4,8 +4,8 @@ Forge models recurring or delegated work as bounded Schedules, Occurrences, Work
 
 Authoritative references:
 
-- [Automation and Schedule Engine](architecture/current/automation-and-schedule-engine.md)
-- [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md)
-- [Failure Recovery](architecture/current/failure-recovery.md)
+- [Automation and Schedule Engine](architecture/CURRENT.md)
+- [Dispatch and Agent Strategy](architecture/CURRENT.md)
+- [Failure Recovery](architecture/CURRENT.md)
 
 Automation does not gain permission to publish, deploy, merge, send, or perform destructive effects without the required authorization.

package/docs/forge-github-issue-launcher.md

@@ -4,4 +4,4 @@ GitHub is an optional first-party Forge provider for repository collaboration an
 
 Remote writes require explicit authorization and idempotent provider evidence. Configure the provider through the Forge CLI or plugin action surface and verify repository mapping before mutation.
 
-See [Integrations](wiki/Integrations.md), [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md), and [Verification and Release Gates](architecture/current/verification-and-release-gates.md).
+See [Integrations](wiki/Integrations.md), [Plugin baseline](architecture/CURRENT.md), and [Verification and Release Gates](architecture/CURRENT.md).

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

@@ -4,4 +4,4 @@ The canonical Forge Runtime reconciles durable Work, Process, Lease, projection,
 
 The OS service manager automatically starts and restarts the single `forge-runtime` process. Standalone Recovery remains independently installable for diagnostics, service repair, tunnel repair, and offline whole-Runtime rollback when the primary Runtime cannot start.
 
-See [Failure Recovery](architecture/current/failure-recovery.md), [Reliability runbook](operations/controller-reliability-runbook.md), and [Standalone disaster recovery](operations/standalone-disaster-recovery.md).
+See [Failure Recovery](architecture/CURRENT.md), [Reliability runbook](operations/controller-reliability-runbook.md), and [Standalone disaster recovery](operations/standalone-disaster-recovery.md).

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

@@ -34,8 +34,8 @@ Interactions that can mutate remote state still require `confirm_authorization=t
 
 The browser mode is explicit:
 
-- `managed_persistent` is the default and preserves the previous behavior: each action launches a visible persistent Playwright context, restores the target URL, performs one bounded operation, persists session metadata, then closes the context.
-- `attach_preferred` uses a strict order: configured loopback CDP endpoints; then an already-running, scriptable macOS Vivaldi or Google Chrome instance; then `cdpAttachFallback`. CDP inventory reuses a previously owned matching tab. Apple Events uses the active browser only for discovery, creates a plugin-owned background tab for a new session, preserves the user's active tab, and reattaches directly to the saved window/tab identity on later actions.
+- `attach_preferred` is the default. It uses a strict order: configured loopback CDP endpoints; then an already-running, scriptable macOS Google Chrome or Vivaldi instance; then `cdpAttachFallback`. The default fallback is `managed_persistent`, so Forge only launches its own Playwright browser after attach paths are unavailable. CDP inventory reuses a previously owned matching tab. Apple Events prefers the frontmost supported browser, otherwise Chrome before Vivaldi; it can reuse a unique existing tab at the requested URL, otherwise creates a plugin-owned background tab while preserving the user's active tab, and reattaches directly to the saved window/tab identity on later actions.
+- `managed_persistent` is the explicit managed-browser mode: each action uses a visible persistent Playwright context, restores the target URL, performs one bounded operation, persists session metadata, then closes the context.
 - `isolated` launches a visible persistent context with a per-session repo-local profile under `.forge/browser/profiles/isolated/<session_id>`. It does not share the default plugin profile or a configured custom profile.
 
 Session metadata is reusable across actions via `session_id`. Any action that returns a generated `sessionId` persists that session before returning, so the identifier is immediately valid for follow-up actions. Transient navigation failures can retry with `retries` (1–3).
@@ -43,13 +43,30 @@ Session metadata is reusable across actions via `session_id`. Any action that re
 ### Reliability and safety notes
 
 - Domain allowlist is checked before navigation and after interactive URL changes.
-- Selector failures include repair hints (`repairHint`) when possible. Selector snapshots prefer unique `data-*`, role/ARIA, name, and non-generated id anchors; structural `nth-of-type` paths are only a last resort and are derived from the actual DOM sibling position rather than result order.
+- Selector failures include repair hints (`repairHint`) when possible. Selector snapshots prefer unique `data-*`, role/ARIA, name, and non-generated id anchors; structural `nth-of-type` paths are only a last resort and are derived from the actual DOM sibling position rather than result order. Open Shadow DOM can be traversed explicitly with bounded `host >>> descendant` selectors; closed shadow roots remain inaccessible.
+- Reusing a saved macOS native session is fail-closed: if the stable plugin-owned tab identity disappears, Forge returns `PLUGIN_BROWSER_SESSION_STATE_LOST` instead of silently creating a replacement tab that could discard unsaved form/editor state.
 - Console errors and failed requests are captured for Playwright/CDP cycles. Apple Events attachment reports empty console/network diagnostics because those streams are not exposed by the browser scripting dictionary.
 - 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`, `session active`, or setup states.
 
+## Browser Runtime V3 contract
+
+Browser Runtime V3 is the current Browser authority. The V2 ADR in [`../architecture/decisions/20260826-browser-runtime-v2.md`](../architecture/decisions/20260826-browser-runtime-v2.md) remains historical rationale; it is not a second runtime contract. Public Browser action IDs remain stable.
+
+- controller-home BrowserSession state is the only durable browser-session authority;
+- exact provider/resource identity is stable while URL/title are mutable observations and are refreshed after persisted reads;
+- provider routing is capability-based instead of fallback-by-exception;
+- a warm provider handle is reusable across bounded actions and full rediscovery is exceptional;
+- cold native rebind uses the saved exact `windowId` + `tabId`; losing optional global tab inventory does not authorize guessing a user tab;
+- mutations compile to provider-local `observe -> act -> verify` transactions;
+- raw Apple Events / AX / socket / CGEvent success is not accepted as mutation success without postcondition evidence;
+- typed browser-internal capabilities are preferred for bookmarks/tabs/downloads instead of driving `chrome://` UI;
+- foreground physical input is explicit and separate. Browser `trusted_input` does not silently foreground a tab or reuse Desktop coordinates; use an explicitly authorized Desktop Operator foreground/physical action when that is the intended capability.
+
+The warm-path performance targets remain p95 <= 350 ms for reads, <= 600 ms for DOM interaction plus verification, and <= 700 ms for typed browser-internal-resource operations. Explicit physical-input fallback targets p95 <= 1500 ms and is foreground-capable only when requested. Current-source live evidence is emitted by `tests/live/browser-runtime-v3.e2e.ts`; Work/Plan evidence owns measured p50/p95 values rather than this maintained runbook.
+
 ## Configuration
 
 The source of truth is `.forge/plugins/browser.json`.
@@ -170,13 +187,16 @@ Apple Events attachment treats silence as the default execution contract:
 - native tab ownership is the stable window/tab reference itself. CDP keeps its separate owner-token mechanism;
 - only explicitly foreground-dependent operations such as screenshot capture or human handoff may require visible foreground presentation. They fail closed rather than activating implicitly.
 
-The live macOS acceptance test covers background replacement, DOM fill/click, click-driven navigation, session URL refresh, `go_back`, `reload`, explicit screenshot refusal, session close, and verifies both the user's active Chrome tab and the system frontmost application remain unchanged.
-Run it explicitly on a macOS workstation with a running Chrome instance:
+The legacy macOS acceptance test remains available through `bun run test:browser-live`. Browser Runtime V3 adds `tests/live/browser-runtime-v3.e2e.ts`, which uses loopback fixtures and exact owned refs to cover Chrome/Vivaldi lifecycle, competing-foreground preservation, same-origin URL drift plus cold rebind, failed replacement postconditions, Chrome internal-resource adoption, cleanup, and per-operation p50/p95 reporting. Run the V3 gate explicitly on a macOS workstation with the target browsers already running:
 
 ```bash
-bun run test:browser-live
+bun tests/live/browser-runtime-v3.e2e.ts
 ```
 
+Set `FORGE_BROWSER_V3_REQUIRE_COMPETING_FOREGROUND=1` when a non-browser application is already frontmost to make foreground preservation a hard precondition. Set `FORGE_BROWSER_V3_REQUIRE_DOM_ALL=1` only when JavaScript-from-Apple-Events permission is expected for every requested native browser. Without that strict flag, a browser whose lifecycle is available but DOM automation is blocked is reported as `external_permission_required` with `PLUGIN_BROWSER_JAVASCRIPT_PERMISSION_REQUIRED`; the harness still verifies exact-ref cleanup and active-user-tab preservation for that product.
+
+The stable Desktop Operator broker may omit global `list_tabs` or Browser `trusted_input`. Forge treats inventory absence as a loss of reuse optimization, not as permission to inspect or adopt unknown user tabs: new sessions create a Forge-owned tab, saved sessions validate exact refs, and close/reconcile operate on exact refs. Missing native trusted input remains a typed Browser capability limitation; explicit Desktop Operator foreground/physical interaction is a separate, visually verified path.
+
 ## Tab Resume And Diagnostics
 
 When attaching through CDP, the plugin inventories existing tabs by index, URL, and title. Selection is deterministic:

package/docs/operations/controller-performance-and-502.md

@@ -39,6 +39,130 @@ Call `GET /health` on the local MCP endpoint. The response includes:
 
 A growing `rejectedOverload` value with no matching capacity-eviction or close activity means clients are submitting protected work faster than the Controller can accept it. A pool full of stream-only sessions should now self-recover. Retrying with backoff is preferable to increasing every limit.
 
+## Runtime Activation Failure Looks Like a 502 (2026-08-23 incident)
+
+When a new Runtime release activation fails, the public MCP path can return
+HTTP `500` on `initialize`, which the tunnel surfaces as a `502`-style
+connection failure. The chain observed on 2026-08-23:
+
+1. A Runtime release activation started a new `mcp serve` process while the
+   launchd gateway already owned `127.0.0.1:8767`. The new process failed to
+   bind (`Failed to start server. Is port 8767 in use?`) but did **not exit**;
+   it kept running as an orphan (`PPID 1`) spinning at ~98% CPU.
+2. The canonical Runtime (port 8765) failed to start for the new release
+   (`RUNTIME_RELEASE_AUTHORITY_MISMATCH` in
+   `runtime/service/logs/stderr.log`), so the gateway could not complete MCP
+   `initialize` and returned HTTP 500.
+3. `tunnel-client` posted the upstream error to the control plane
+   (`dispatcher received MCP upstream error`, `upstream_status=500`,
+   `rpc_method=initialize`), which the remote client saw as a failed
+   connection / 502.
+
+Diagnostic fingerprint:
+
+- `gateway.stderr.log` contains `Failed to start server. Is port 8767 in use?`
+- `runtime/service/logs/stderr.log` contains repeated
+  `RUNTIME_RELEASE_AUTHORITY_MISMATCH`
+- recovery watchdog log shows `restart_primary_runtime` attempts followed by
+  `action":"rollback"` restoring the previous release
+- a stray `bun ... mcp serve` process with `PPID 1` and high `%CPU`
+
+Remediation:
+
+- The standalone Recovery watchdog automatically rolls back after the bounded
+  restart budget is exhausted; wait for `action":"healthy"` in
+  `recovery/audit/watchdog.log` before doing anything else.
+- Kill the orphaned `mcp serve` child of the failed release (verify it holds no
+  listening sockets first); it only burns CPU after a failed port bind.
+- Verify the canonical Runtime answers `initialize` on its own port and that
+  the tunnel log shows no new `upstream_status=500` entries.
+
+Known code defect to fix: `mcp serve` should exit with a non-zero status when
+the requested port is already in use instead of staying alive in a hot loop.
+
+## Connector/Activation Recovery Gaps Behind Intermittent 502 (2026-08-27)
+
+A second class of intermittent `502` was traced to release/Connector coherence rather
+than to a permanently dead Recovery service.
+
+Observed evidence:
+
+- a live Forge MCP request returned `502` while independent Recovery observed the
+  Canonical Runtime briefly as `RUNTIME_NOT_RUNNING`; the Runtime became ready again
+  a few seconds later after release authority reverted to the prior package release;
+- separate MCP connection failures also occurred while independent Recovery still
+  observed the Canonical Runtime as ready, proving that not every `502` is a whole-
+  Runtime failure;
+- the persistent package Connector health probe accepted any received HTTP status,
+  so `500`/`502` could be classified as healthy and the broken service reused;
+- detached macOS package activation scheduled the Runtime switch and then rebound the
+  Connector to the candidate release before the activation helper committed the
+  Runtime service. If helper activation failed, Runtime authority/service rolled back
+  while Connector authority/plist could remain on the candidate generation;
+- standalone Recovery's Connector action previously restarted the already-installed
+  launchd service. A stale/mutable launch spec therefore remained stale after restart.
+
+Corrected invariants:
+
+1. Connector reuse accepts only the expected MCP/OAuth endpoint semantics (`200` or
+   the unauthenticated `401` Bearer challenge); `5xx` is always unhealthy.
+2. Detached activation does not switch the Connector in the installer. The activation
+   helper installs the Runtime service first and only then commits the Connector to the
+   same immutable package release. A Runtime activation failure therefore leaves the
+   prior Connector generation untouched.
+3. Connector-only Recovery first reconciles the canonical package Connector against
+   the active immutable Runtime release, then verifies local ownership/public MCP, and
+   only then decides whether a launchd/tunnel restart is still required.
+4. Whole-Runtime rollback remains deliberately stricter than Connector recovery. A
+   known-good Runtime is not rolled back merely because its Connector or external
+   tunnel drifted; those hops must be repaired independently.
+5. Recovery `runtime_status` reports bounded Watchdog decision evidence (last action,
+   reason and restart/failure counters) so incident review can distinguish "Recovery
+   never fired" from "Recovery fired and the client observed the bounded outage".
+
+## Session Continuation Fails With 404 MCP_TOOL_SURFACE_CHANGED (2026-08-23)
+
+Second incident on the same day, different failure mode. After a session is
+created, every follow-up (`notifications/initialized`, `tools/call`) returned
+HTTP 404 with:
+
+```json
+{"error":"session_not_found","code":"MCP_TOOL_SURFACE_CHANGED",
+ "message":"MCP Runtime tool surface changed; initialize a new session so tools/list is refreshed.",
+ "recoverable":true,"action":"reinitialize",
+ "previousFingerprint":"<session>","currentFingerprint":"<published>"}
+```
+
+Root cause: the Gateway session fence compares the **live** Runtime schema
+fingerprint captured at `initialize` (`readCanonicalRuntimeToolSchema` ->
+`proxy.listTools()`) against the **published** fingerprint in
+`runtime/status.json`. The Runtime publishes `status.json` once at startup and
+does not republish when its live tool surface changes at runtime (e.g. a
+plugin registers or code edits change the tool set). Once the two values
+diverge, every session continuation is rejected as a tool-surface change, so
+the tunnel/connector appears broken even though `/health` shows both
+fingerprints matching the published value.
+
+Diagnostic fingerprint:
+
+- Gateway `/health` shows `toolSurfaceFingerprint` equal to
+  `runtimeToolSurfaceFingerprint` (both read the published value), but a real
+  `initialize` session stores a different fingerprint.
+- Follow-up requests get the `MCP_TOOL_SURFACE_CHANGED` 404 with
+  `previousFingerprint != currentFingerprint`.
+
+Remediation:
+
+- Restart the canonical Runtime service
+  (`launchctl kickstart -k gui/$UID/com.moretea.forge.runtime.<suffix>`) so it
+  republishes `status.json` from its current surface, then verify
+  `initialize` -> `notifications/initialized` (202) -> `tools/call` (200) with
+  a valid OAuth token.
+- Known code defect to fix: the Runtime should republish `status.json`
+  whenever its live tool surface changes (tool list changed), and/or the
+  Gateway fence should prefer the live fingerprint for the current-schema
+  comparison instead of trusting a stale publication.
+
 Call `GET /ready` separately. A 503 from `/ready` with `/health` still returning 200 means the Runtime is live but cannot safely admit another initialize. `sessionCapacity.recoveryRecommended=false` preserves active work and waits; `true` is evidence for standalone Recovery's bounded whole-Runtime restart policy after the configured stall limit.
 
 ## Diagnostic Order

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

@@ -68,7 +68,7 @@ A release change is performed only as an explicitly authorized whole-Runtime ope
 1. validate one immutable release manifest, configuration, database compatibility range, and Worker protocol;
 2. quiesce admission and stop the complete Runtime;
 3. atomically select the candidate as the one active whole release;
-4. let the single Forge Runtime service start `forge-runtime` from that complete release;
+4. atomically mirror the selected release's signed `forge-runtime` entrypoint to the fixed physical service path `runtime/service/active-forge-runtime`, then let the single Forge Runtime service start that stable path with the selected release manifest/environment;
 5. require binary whole-Runtime readiness;
 6. on failure, stop the service, restore the previous release and its bound local SQLite backup, then start and verify the complete previous Runtime.