@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -20,6 +20,7 @@ repos, command facades, hooks, migration helpers, and installed runtime copies.
 - 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.

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

@@ -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/modules/controller-runtime/transport-lifecycle.md

@@ -11,7 +11,7 @@
 
 - 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 is claimed with an opaque Work-bound controller capability immediately; modern sessionless follow-up requests must present that exact authority. Legacy owner records without a capability digest require an explicit `controller_claim` authority upgrade and are never accepted by principal identity alone.
+- 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.

package/docs/forge-plugin-management.md

@@ -10,7 +10,7 @@ forge plugin catalog
 
 | Plugin ID | Product | Pinned release | Platforms |
 | --- | --- | --- | --- |
-| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.3.0` | macOS |
+| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.4.5` | macOS |
 | `design` | [Forge Design](https://github.com/moretea-labs/forge-design) | `v0.3.0` | macOS, Linux, Windows |
 | `personal_knowledge` | [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | `v0.2.1` | macOS, Linux, Windows |
 
@@ -30,7 +30,7 @@ forge computer uninstall
 forge computer uninstall --purge
 ```
 
-`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.
+`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. Desktop Operator owns native macOS Computer observe/input/capture/console-unlock/element capabilities; Browser automation remains under the separate Browser provider authority rather than being claimed by the Desktop Operator catalog. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.
 
 Generic provider administration remains available for diagnostics and non-Computer providers:
 

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

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

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

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

package/docs/operations/features.md

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

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

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

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.8.0` exists on npm;
-- Git tag and GitHub Release `v1.8.0` exist and point to the tested commit;
+- `@moretea-labs/forge@1.8.1` exists on npm;
+- Git tag and GitHub Release `v1.8.1` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

package/docs/operations/mcp-tool-exposure.md

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

package/docs/operations/releasing.md

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

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

@@ -58,7 +58,9 @@ reconnect_primary_connector
 
 `runtime_status` reads canonical Runtime observation. `list_releases` reads the whole-release authority. `attest_known_good` succeeds only after Runtime status, release identity, authenticated MCP initialization, tools/list, and the configured read-only MCP call pass together.
 
-The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers, MCP payloads and session identifiers are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+The Recovery Gateway listens on loopback, uses a separate scoped credential, bounds request/output size, and stores no primary MCP credential in logs. External HTTPS verification uses the trusted system curl transport; temporary headers and MCP payloads are written only to bounded mode-0600 files below `recovery/tmp` and are removed after each request.
+
+For MCP transport lifecycle, Standalone Recovery deliberately owns **no transport-session state**. MCP 2026-07-28 and bounded 2025-era compatibility requests are both served statelessly by the SDK handler. `Mcp-Session-Id` is therefore never Recovery authority and is not required to survive a Recovery Gateway process replacement; an old client sending a stale session header cannot strand the independent recovery path. Runtime/release authority remains durable and separate from transport process identity.
 
 ## Whole-Runtime rollback
 
@@ -93,18 +95,23 @@ The watchdog cannot launch an Agent, edit a source checkout, generate repair scr
 
 ## Installation
 
-Build, canary, and activate the immutable Recovery release with the public CLI:
+Build and canary the immutable Recovery release with the public CLI. Installation role is explicit:
+
+- `manual` is the default. It publishes the Recovery artifact/configuration but registers no persistent Recovery Gateway or Watchdog.
+- `gateway` registers only the independently reachable Recovery Gateway.
+- `self-healing` registers Gateway plus Watchdog and is the only profile that pays the autonomous health-monitoring/recovery cost.
 
 ```sh
 forge recovery install \
   --controller-home /absolute/controller-home \
+  --profile gateway \
   --public-mcp-url https://mcp.example.com/mcp \
   --recovery-public-url https://recovery.example.com/recovery/mcp \
   --recovery-tunnel-service-label com.example.forge-recovery-tunnel \
   --recovery-tunnel-service-plist /absolute/path/com.example.forge-recovery-tunnel.plist
 ```
 
-Use `--stage-only` to build and canary without activating Gateway or Watchdog services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface.
+`--stage-only` remains a compatibility alias for build/canary-only behavior and does not mutate installed Recovery configuration or services. The source-level `bun scripts/install-standalone-recovery.ts` entry remains an internal packaging primitive, not a second operator surface. Shipping Forge source/CLI does not itself activate any persistent Recovery profile.
 
 A public Recovery endpoint is optional for local-only operations. A ChatGPT Recovery Connector requires one independently owned external transport: either an explicit HTTPS Recovery URL plus its dedicated tunnel service owner, or a dedicated OpenAI Secure MCP Tunnel. The OpenAI transport keeps the Recovery Gateway on loopback; `tunnel-client` is the outbound transport and is supervised separately from the primary Forge Runtime/Connector.
 
@@ -113,6 +120,7 @@ For a Windows/WSL Recovery installation, create a new OpenAI tunnel identity tha
 ```sh
 forge recovery install \
   --controller-home /home/<user>/.forge/controller \
+  --profile gateway \
   --recovery-openai-tunnel-id <dedicated-wsl-recovery-tunnel-id> \
   --recovery-openai-runtime-api-key-ref env:FORGE_RECOVERY_TUNNEL_KEY
 ```
@@ -127,9 +135,9 @@ forge recovery connector --controller-home /absolute/controller-home
 
 The descriptor and `runtime_status` expose a `RecoveryMachineIdentity` containing host, platform, resolved Controller Home, current Recovery release identity, and the exact target Runtime service/release identity. Every external Recovery mutation requires the caller to echo the current `expected_host`, `expected_platform`, `expected_controller_home`, `expected_recovery_release`, and `expected_target_runtime` values from that observation. Missing, stale, or cross-machine values are rejected before any mutation. Successful mutation responses include the post-operation machine identity as well. This makes accidentally selecting the macOS Recovery connector while intending to repair WSL fail closed rather than repairing the wrong machine.
 
-Because Gateway, Watchdog, immutable Recovery release, and the dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, a primary Runtime outage does not remove this external Recovery control path.
+When the selected profile includes Gateway, the Recovery Gateway and any dedicated Recovery tunnel are installed independently of the primary Runtime/Connector, so a primary Runtime outage does not remove that external Recovery control path. Watchdog independence applies only to the explicit `self-healing` profile.
 
-The installer owns publication and activation. Before registering `com.moretea.forge-recovery-gateway` and `com.moretea.forge-recovery-watchdog`, it exits and removes stale Recovery services discovered under the Recovery-owned launchd directory. Configuration is rewritten from the current schema and does not preserve retired ingress, agent-repair, or legacy tunnel fields. Direct reload scripts are not a second mutation path.
+The installer owns Recovery publication and role reconciliation. It activates only the roles selected by the typed install profile and explicitly retires Recovery-owned Gateway/Watchdog services that are no longer selected. It never treats a package/source install as permission to enable Watchdog. Configuration is rewritten from the current schema and does not preserve retired ingress, agent-repair, or legacy tunnel fields. Direct reload scripts are not a second mutation path.
 
 Forge deliberately has no blue-green Runtime topology. There is one active whole-release authority and one canonical service. Candidate validation happens before activation; activation stops the complete Runtime, switches the atomic active release, starts one Runtime, and gates on whole-Runtime readiness. Failure restores the previous whole release and its bound SQLite backup.
 
@@ -156,6 +164,6 @@ forge recovery activate-runtime --controller-home /absolute/controller-home --re
 
 The controller may install the `local_recovery` external Assistant Plugin when the independently configured ChatGPT Recovery Connector is unavailable or bound to a stale external transport while the primary Runtime is still healthy enough to host plugins. This adapter is a transport client only; it is not another Runtime lifecycle authority.
 
-The managed helper is `scripts/forge-local-recovery-helper.mjs`. Its provider configuration contains only the absolute installed `controllerHome`. The helper loads the installed Recovery configuration and scoped Gateway token from that Controller Home, requires the Recovery Gateway endpoint to remain loopback, and invokes only allowlisted Recovery MCP tools. The initial action surface is `runtime_status`, `list_releases`, and `stage_and_activate_runtime_release`; every action has an empty caller argument schema. In particular, callers cannot supply a source root, release path, endpoint, token path, executable, command, tunnel identity, or mutation request id.
+The managed helper is `scripts/forge-local-recovery-helper.mjs`. Its provider configuration contains only the absolute installed `controllerHome`. The helper loads the installed Recovery configuration and scoped Gateway token from that Controller Home, requires the Recovery Gateway endpoint to remain loopback, and invokes only allowlisted Recovery MCP tools. The action surface includes `runtime_status`, `list_releases`, read-only `verify_stable_runtime`, the compatibility candidate-build action `stage_and_activate_runtime_release`, and the durable ReleaseSession lifecycle (`release_session_status`, static verification, isolated Candidate B verification, pre-cutover Candidate retirement, cutover, exact-session rollback, and known-good promotion). A source or admission gate discovered after Candidate creation invalidates that frozen candidate: Recovery retires it through the existing `failed` terminal state and removes the isolated Candidate lane before a replacement ReleaseSession is prepared. While a ReleaseSession owns an activation transaction, the watchdog may restart the same candidate Runtime but must not generically commit or roll back that transaction; exhausted recovery delegates back to the exact ReleaseSession rollback path. Ordinary actions accept no caller arguments; ReleaseSession actions accept only the bounded `session_id`, while mutation request ids remain provider-owned. Callers cannot supply a source root, release path, endpoint, token path, executable, command, tunnel identity, or mutation request id.
 
 `stage_and_activate_runtime_release` delegates to the existing standalone Recovery MCP tool of the same name. Staging source authority, Repository Registry provenance, Recovery mutation locking, active/previous whole-release authority, SQLite backup/rollback, launch-service ownership, and post-activation verification therefore remain entirely owned by standalone Recovery. The adapter is useful for in-band maintenance while the primary Runtime is alive; it does not replace the independent Recovery Connector for disaster recovery when the primary Runtime itself is unavailable.

package/docs/wiki/Implementation.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",
@@ -62,9 +62,20 @@
     "install.ps1",
     "bin/",
     "scripts/",
+    "!scripts/benchmark-*",
+    "!scripts/route-nl-vs-ts-eval.ts",
+    "!scripts/check-npm-release.sh",
+    "!scripts/check-public-release-surface.sh",
+    "!scripts/check-release-*",
+    "!scripts/check-tarball-install-smoke.sh",
+    "!scripts/public-release*",
+    "!scripts/publish-release-tarball.sh",
+    "!scripts/stage-runtime-release.ts",
+    "!scripts/package-source-archive.sh",
     "adapters/",
     "packages/",
     "src/",
+    "supervisor/",
     "AGENTS.md",
     "CLAUDE.md",
     "SKILL.md",
@@ -80,9 +91,8 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "build:controller-ui": "bun scripts/build-controller-ui.ts",
-    "check:controller-ui": "bun scripts/build-controller-ui.ts --check",
     "check:design": "npx -y @google/design.md@0.4.0 lint DESIGN.md",
+    "check:desktop-client": "npm --prefix apps/desktop run check",
     "benchmark:controller-hotpath": "bun scripts/benchmark-controller-hotpath.ts",
     "benchmark:computer-hotpath": "bun scripts/benchmark-computer-hotpath.ts",
     "benchmark:thin-harness-mcp-e2e": "bun scripts/benchmark-thin-harness-mcp-e2e.ts --json",
@@ -93,7 +103,7 @@
     "benchmark:quality-harness": "bun scripts/benchmark-quality-harness.ts",
     "benchmark:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
     "check:quality-harness": "bun scripts/benchmark-quality-harness.ts",
-    "check:evaluation-framework": "bun test ./tests/evaluation-framework.test.ts && bun test ./evaluation/protocol.test.ts && bun test ./evaluation/candidate-runner.test.ts && bun test ./evaluation/calibration.test.ts && bun test ./evaluation/certification.test.ts && bun test ./evaluation/public-mcp-runner.test.ts",
+    "check:evaluation-framework": "bun test ./tests/evaluation-framework.test.ts && bun test ./evaluation/protocol.test.ts && bun test ./evaluation/candidate-runner.test.ts && bun test ./evaluation/calibration.test.ts && bun test ./evaluation/certification.test.ts && bun test ./evaluation/public-mcp-runner.test.ts && bun test ./evaluation/cognitive-skill-retirement.test.ts",
     "check:v2-certification": "bun evaluation/check-v2-certification.ts",
     "check:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
     "check:typescript-navigation": "bun scripts/benchmark-typescript-navigation.ts",
@@ -108,7 +118,13 @@
     "test:fault": "bun scripts/test-governance.ts fault",
     "test:full": "bun scripts/test-governance.ts full",
     "test:coverage": "bun test --coverage",
-    "check:type": "bun x tsc --noEmit",
+    "check:type": "bun x tsc --noEmit && bun x tsc -p supervisor/tsconfig.json",
+    "workflow-supervisor": "bun supervisor/entry.ts",
+    "smoke:workflow-supervisor": "bun scripts/smoke-workflow-supervisor.ts",
+    "smoke:workflow-supervisor-process-restart": "bun scripts/smoke-workflow-supervisor-process-restart.ts",
+    "smoke:workflow-supervisor-restart-recovery": "bun scripts/smoke-workflow-supervisor-restart-recovery.ts",
+    "smoke:workflow-supervisor-chrome-adapter": "bun scripts/smoke-workflow-supervisor-chrome-adapter.ts",
+    "smoke:user-request-continuation-restart": "bun scripts/smoke-user-request-continuation-restart.ts",
     "check:runtime-architecture": "node scripts/check-runtime-architecture.mjs",
     "check:repository-hygiene": "node scripts/check-repository-hygiene.mjs",
     "check:generated-authority": "node scripts/sync-generated-authority.mjs --check",
@@ -118,9 +134,11 @@
     "check:test-governance": "bun scripts/test-governance.ts validate",
     "check:mcp-compatibility": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/check-mcp-compatibility.ts",
     "smoke:runtime-recovery": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/smoke-runtime-recovery.ts",
+    "smoke:unattended-transport-recovery": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/smoke-unattended-transport-recovery.ts",
+    "smoke:control-plane-failure-domain": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/smoke-control-plane-failure-domain.ts",
     "smoke:mcp-http-runtime": "node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/smoke-mcp-http-runtime.ts",
     "smoke:tool-surface": "bun scripts/smoke-mcp-tool-surface.ts",
-    "check:smoke": "bun run smoke:mcp-http-runtime && bun run smoke:runtime-recovery && bun run smoke:schedule-engine && bun run smoke:tool-surface",
+    "check:smoke": "bun run smoke:workflow-supervisor && bun run smoke:workflow-supervisor-process-restart && bun run smoke:workflow-supervisor-restart-recovery && bun run smoke:workflow-supervisor-chrome-adapter && bun run smoke:mcp-http-runtime && bun run smoke:runtime-recovery && bun run smoke:unattended-transport-recovery && bun run smoke:control-plane-failure-domain && bun run smoke:schedule-engine && bun run smoke:tool-surface",
     "check:task": "bun scripts/run-governed-gate.ts task",
     "check:main": "bun scripts/run-governed-gate.ts main",
     "check:ci": "bun run check:main",
@@ -158,7 +176,6 @@
     "test:bun": "bun -e 'console.error(\"[tests] test:bun is deprecated; running explicit test:full\")' && bun run test:full",
     "test:node-smoke": "node --test tests/node/*.test.mjs",
     "check:ci:portable": "FORGE_ALLOW_NODE_ONLY=1 bash scripts/check-ci.sh",
-    "dev:controller-ui": "vite --config src/cli/local-bridge/frontend/vite.config.ts",
     "prepack": "node scripts/sync-generated-authority.mjs --check",
     "check:portable-package": "node --test tests/node/*.test.mjs && npm run smoke:tarball-install"
   },
@@ -166,18 +183,12 @@
     "@colbymchenry/codegraph": "1.0.1",
     "@types/bun": "latest",
     "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "@vitejs/plugin-react": "^5.2.0",
-    "vite": "^7.3.0"
+    "@types/express": "^5.0.6"
   },
   "dependencies": {
     "commander": "^14.0.3",
     "express": "^5.2.1",
     "playwright": "^1.54.1",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "@modelcontextprotocol/client": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",

package/packages/kernel/cognition/api/index.ts

@@ -0,0 +1,6 @@
+export * from '../domain/memory';
+export * from '../domain/learning';
+export * from '../application/activation-service';
+export * from '../application/consolidation-service';
+export * from '../application/memory-service';
+export * from '../application/legacy-experience-adapter';