@moretea-labs/forge 1.5.0-rc.1

package/docs/architecture/current/personal-assistant-plugin-baseline.md

@@ -0,0 +1,207 @@
+# Personal Assistant Plugin Baseline
+
+> Status: **Runtime Authority**
+
+This document defines the concrete baseline for the "personal assistant plugin"
+surface inside the current Forge Controller Runtime. It exists to stop
+"assistant", "plugin", "Gmail", and "Calendar" from being treated as one
+undifferentiated feature set.
+
+## 1. Current implementation boundary
+
+Current implementation:
+
+- Forge already implements a durable Controller Runtime, not a generic
+  personal-app plugin host.
+- First-class persisted plugins in source are the optional GitHub plugin under
+  `src/cli/github/plugin.ts` plus Gmail, Google Calendar, and Google Tasks
+  adapters under `src/runtime/plugins/`, all surfaced through Controller CLI,
+  Local Bridge APIs, and MCP compatibility tools.
+- ChatGPT browser automation exists under `src/cli/chatgpt-browser/` and the
+  campaign/runtime control plane. It is an execution channel, not a plugin
+  registry entry.
+- Calendar support exists both as a runtime Schedule trigger under
+  `src/runtime/workflow/schedules/` and as a separate Google Calendar account
+  adapter under `src/runtime/plugins/`.
+- Gmail, Calendar, and Tasks live-provider credentials are environment-only and
+  are never persisted by this repository.
+
+Architecture requirement:
+
+- Docs and product language must distinguish repo-owned runtime capabilities,
+  optional in-repo plugins with persisted config, and external Connector/app
+  capabilities owned outside this repository.
+
+Compatibility rule:
+
+- Existing GitHub plugin behavior, runtime tool fingerprints, and packaging
+  surfaces remain stable while assistant-oriented capabilities are clarified.
+
+## 2. Concrete topology
+
+```text
+ChatGPT / Local UI / CLI
+  -> MCP Gateway + Local Bridge
+     -> Controller Runtime
+        -> durable Jobs / campaigns / schedules / evidence
+           -> optional provider adapters
+              -> GitHub plugin (implemented)
+              -> Gmail adapter (implemented)
+              -> Google Calendar adapter (implemented)
+              -> Google Tasks adapter (implemented)
+              -> ChatGPT browser channel (implemented)
+              -> Calendar trigger engine (implemented, separate from account adapter)
+```
+
+The runtime already owns admission, persistence, scheduling, isolation, and
+evidence. "Personal assistant" behavior must therefore be modeled as bounded
+operations on top of that runtime, not as a second orchestrator.
+
+## 3. Capability matrix
+
+| Capability | Source of truth | Persistence and boundary | External side effect | Status |
+| --- | --- | --- | --- | --- |
+| GitHub Issue/Project sync | `src/cli/github/plugin.ts`, `src/cli/commands/controller.ts`, `src/cli/local-bridge/server.ts` | `.Forge/plugins/github.json` plus repository registry mapping | GitHub issue/project mutation | Implemented |
+| Durable assistant work submission | `src/runtime/gateway/mcp/runtime-tools.ts`, `src/runtime/execution/jobs/` | Controller Home `execution-jobs/`, events, artifacts, projections | Repository-local work and approved provider actions | Implemented |
+| ChatGPT-supervised campaigns | `src/runtime/workflow/campaigns/`, `src/cli/chatgpt-browser/` | Campaign records, review packets, workspaces, evidence | Browser-visible ChatGPT session or delegated local work | Implemented and opt-in |
+| Calendar time-based triggering | `src/runtime/workflow/schedules/store.ts`, `engine.ts` | Schedule, Decision, Occurrence records | Launches bounded runtime Jobs only | Implemented |
+| Calendar account read/write | `src/runtime/plugins/google-calendar-adapter.ts` | `.Forge/plugins/google-calendar.json`, derived manifest/index, env-only credentials | Google Calendar event read/write | Implemented |
+| Gmail mailbox read/write | `src/runtime/plugins/gmail-adapter.ts` | `.Forge/plugins/gmail.json`, derived manifest/index, env-only credentials | Gmail read/send/trash | Implemented |
+| Google Tasks/reminder read/write | `src/runtime/plugins/google-tasks-adapter.ts` | `.Forge/plugins/google-tasks.json`, derived manifest/index, env-only credentials | Google Tasks list/task mutation | Implemented |
+| Generic plugin manifest/registry for personal apps | `src/runtime/plugins/`, `src/runtime/gateway/mcp/runtime-tools.ts`, `src/cli/local-bridge/server.ts` | Controller Home `plugins/` manifest/index projections derived from existing authority | Typed plugin action dispatch into durable Jobs | Implemented |
+
+## 4. Packaging baseline
+
+Current implementation:
+
+- `package.json` already ships `docs/architecture/`, runtime source, controller
+  verification script, and ChatGPT bridge skills as part of the public package.
+- `scripts/package-source-archive.sh` builds a portable archive from the working
+  tree while rejecting symlinks and excluding runtime state, Git metadata, and
+  secrets.
+
+Architecture requirement:
+
+- Assistant/plugin documentation must live under tracked docs already included in
+  the public package; introducing a new baseline doc must not require shipping
+  ignored runtime state or auth material.
+
+Compatibility rule:
+
+- Packaging must continue to exclude `.ai/` runtime state, local auth, tokens,
+  and browser profile data even when assistant-oriented features expand.
+
+## 5. Threat model
+
+| Asset or boundary | Primary threat | Current controls | Remaining gap |
+| --- | --- | --- | --- |
+| Public `/mcp` endpoint and local Gateway | Remote callers trigger long or unsafe work through request lifetime coupling | Thin Gateway, durable acknowledgement, loopback local UI, auth, bounded toolsets, readiness checks | Tool-level capability descriptions are clearer than provider-level assistant semantics |
+| Controller Home runtime state | Replayed or stale ownership mutates state after disconnect or restart | request-id dedupe, Leases, fencing, Operation Receipts, reconciliation, append-only events | Additional adapters beyond GitHub still need the same registry contract |
+| GitHub plugin config and repo mapping | Wrong repository/project mapping or silent remote mutation | explicit config, readiness probe, derived plugin manifests, action-scoped confirmation, warnings on remote drift | Google adapters use separate config authority and do not reuse GitHub registry mapping |
+| Browser-based ChatGPT automation | Session leakage, default-profile misuse, invisible side effects | dedicated profile guidance, CDP default-profile block, bounded capture, opt-in workflow, evidence records | Browser channel is still an execution transport, not a typed assistant-provider contract |
+| Gmail/Calendar/Tasks adapters | Overbroad mailbox/calendar/task scope and opaque side effects | read/write scope separation, action-scoped confirmation, env-only credentials, mock/live provider split, durable audit events, structured provider errors | No OAuth refresh/token broker is implemented; operators must supply short-lived access tokens outside repo state |
+| Local visual controller | Exposure beyond loopback or secret leakage in logs | loopback bind enforcement, token auth, bounded snapshots, redaction paths | Personal-app views do not exist yet, so no specialized redaction policy is defined |
+
+## 6. Migration plan
+
+### Phase A — Name the real provider classes
+
+- Keep "GitHub plugin", "ChatGPT browser channel", and "Schedule trigger"
+  separate in docs and CLI help.
+- Describe Gmail, Google Calendar, and Google Tasks as implemented runtime
+  plugins only through the generic plugin contract; do not present them as
+  browser-channel or schedule-engine features.
+
+### Phase B — Add a typed assistant-provider contract
+
+Current implementation:
+
+- The runtime now exposes a generic personal-assistant plugin contract with:
+  versioned manifests, derived registry/discovery, lifecycle/health, typed
+  action schemas, permission scopes, confirmation policies, idempotent durable
+  action dispatch, cancellation/timeout support through `ExecutionJob`, and
+  plugin audit events in the runtime ledger.
+- The first adapter is GitHub. Its configuration authority remains the existing
+  repository registry plus `.Forge/plugins/github.json`; the generic
+  manifest is a derived projection, not a second source of truth.
+
+- Introduce one provider contract for personal-app adapters with capability id,
+  read/write scope declaration, persisted config shape, readiness probe,
+  audit/evidence schema, env-only credential rule, and explicit
+  external-side-effect classification.
+- Reuse existing Controller authorization, durable Job, and evidence layers
+  instead of bypassing them.
+
+### Phase C — Run Gmail, Calendar, and Tasks adapters only behind the contract
+
+- Gmail is implemented as a bounded mailbox adapter with list/read, draft,
+  send, and trash actions.
+- Calendar is implemented as an account adapter distinct from the existing
+  time-trigger engine, with list/read, create, reschedule, and cancel actions.
+- Tasks is implemented as a reminder/task adapter with list/create/update,
+  reschedule, complete, and delete actions.
+- All three emit provider/action audit events, structured provider failures, and
+  integrate with existing approval and release boundaries.
+
+### Phase D — Preserve public package and source-archive invariants
+
+- Keep docs, scripts, and public source packaged.
+- Keep runtime state, auth material, browser profiles, and local Connector
+  secrets excluded from npm and source archives.
+- Extend focused checks before any new assistant provider becomes part of the
+  public contract.
+
+## 7. Delivery conclusion
+
+The current source-aligned assistant baseline is:
+
+- Controller Runtime plus durable Jobs/campaigns/schedules are the assistant
+  execution substrate.
+- GitHub, Gmail, Google Calendar, and Google Tasks are implemented persisted
+  plugin adapters behind the generic plugin runtime contract.
+- Generic plugin discovery, typed action execution, confirmation policy and
+  audit events are implemented through the runtime `plugins/` layer.
+- ChatGPT browser automation is an opt-in execution channel.
+- Calendar exists both as a scheduling primitive and as a separate Google
+  Calendar account adapter.
+- Live Google credentials remain environment-only; this repo persists plugin
+  config and derived health, not tokens.
+
+
+## 8. Bundled first-party and managed-provider boundary
+
+The current plugin baseline also includes a controller-scoped `desktop` plugin.
+It establishes the boundary between bundled first-party capability modules and
+managed native providers without introducing a plugin marketplace:
+
+- Core Controller authority remains compiled into Forge: admission,
+  authorization, resource claims, receipts, audit events, Work, Process, Git,
+  Runtime Root, recovery, and plugin discovery are not replaceable plugins.
+- First-party domain capabilities remain bundled with the Forge package
+  and are registered through `src/runtime/plugins/first-party-registry.ts`.
+- Desktop is the first bundled capability whose domain implementation executes
+  through the generic `managed-process-adapter.ts` backend.
+- The helper is package-owned and resolved from the active installation. Users do
+  not configure an absolute executable path, socket, or registration descriptor.
+- The initial transport is a one-shot versioned JSON-lines stdio protocol with
+  handshake, request identity, capability negotiation, bounded input/output,
+  timeout, cancellation, crash cleanup, and structured errors.
+- Existing `list_plugins`, `get_plugin`, and `plugin_action_execute` tools remain
+  the only public plugin entry points. This does not imply dynamic MCP schema
+  loading.
+
+Desktop configuration authority is
+`<controller-home>/system/desktop/config.json`. The manifest and registry index are
+derived projections, not a second source of truth. Current Desktop actions are
+limited to enable/disable, live status, frontmost-application observation through
+AppKit `NSWorkspace`, and explicitly authorized application launch. Screen capture,
+clicks, coordinates, keyboard input, accessibility-tree access, arbitrary shell,
+plugin downloads, and marketplace installation are intentionally absent.
+
+The managed helper threat model is process compromise, hidden native side effects,
+permission overclaim, protocol confusion, and unbounded output. Current controls
+are direct no-shell spawn, package-owned helper resolution, minimal environment,
+versioned handshake, required-capability matching, bounded diagnostics, timeout and
+AbortSignal handling, SIGTERM/SIGKILL cleanup, read-only observation, and typed
+application selectors. Any future interaction or screen-observation capability
+requires a separate permission model and fault-injection review.

package/docs/architecture/current/repository-access-modes.md

@@ -0,0 +1,102 @@
+# Repository access modes
+
+Forge keeps two user-selectable execution policies:
+
+- `full_access` — the default for a personal local controller. Normal work inside the selected repository can read, edit, run bounded local commands and checks, and perform local Git operations without repeated approval prompts.
+- `request` — keeps the same MCP tool schema, but asks before elevated local side effects.
+
+Access mode controls **execution approval only**. It never changes `tools/list`, never hides Direct Edit, Git, Agent, iOS, browser, plugin, or recovery tools, and never requires an MCP restart or ChatGPT reconnect.
+
+## Hard safety boundary
+
+Neither mode bypasses the controller's hard boundaries. These remain separately authorized or denied:
+
+- paths outside the selected repository;
+- external network effects;
+- Git push and other remote writes;
+- deployments, publishing, destructive cleanup, and irreversible operations;
+- raw secrets, tokens, private keys, and credentials;
+- controller policy bypass.
+
+`full_access` is therefore repository-local autonomy, not unrestricted host access.
+
+## Storage and defaults
+
+The repository policy is stored under controller-owned state:
+
+```text
+<controllerHome>/repositories/<repoId>/controller/access-policy.json
+```
+
+The setting is not written into the repository. When no policy file exists, the personal-controller default is `full_access` without creating a file. A malformed existing policy fails closed to `request`.
+
+Each durable `WorkContract` captures the effective `accessMode` in `constraints` when work starts. Changing the repository default affects new work only; an existing task keeps its immutable snapshot.
+
+## MCP and Local Controller UI
+
+The stable MCP schema always includes:
+
+- `rh_access`;
+- `repository_access_get`;
+- `repository_access_preview`;
+- `repository_access_set`.
+
+Changing a mode requires explicit authorization:
+
+```json
+{
+  "operation": "set",
+  "mode": "request",
+  "confirm_authorization": true
+}
+```
+
+No magic confirmation phrase is required for repository-local Full Access. The result explicitly reports:
+
+```json
+{
+  "reconnectRequired": false,
+  "schemaRefreshRequired": false,
+  "toolSchemaStable": true
+}
+```
+
+The Local Controller UI uses the same controllerHome policy and explains that switching mode changes approval behavior only.
+
+## Per-work override
+
+`rh_work` may override the repository default for one work item:
+
+```json
+{
+  "operation": "start",
+  "objective": "Refactor controller routing",
+  "constraints": {
+    "accessMode": "request",
+    "workspaceMode": "current"
+  }
+}
+```
+
+Both camelCase and snake_case are accepted inside constraints. The effective mode is captured in the created WorkContract.
+
+## Decision matrix
+
+| Effect | Request | Full Access |
+| --- | --- | --- |
+| Read selected repository | allow | allow |
+| Direct Edit / safe patch | allow | allow |
+| General repository write | request | allow |
+| Repository-scoped local command | request | allow |
+| Dependency change | request | allow |
+| Local Git write | request | allow |
+| Registered checks | allow | allow |
+| External network | request | request |
+| Remote write / push | request | request |
+| Destructive effect | explicit approval | explicit approval |
+| Raw secrets or credentials | deny | deny |
+| Outside-repository path | explicit grant | explicit grant |
+
+## Compatibility
+
+The legacy `core`, `advanced`, and `full` labels remain accepted. `core` and `advanced` resolve to the same stable, repair-capable schema. `full` exposes every historical compatibility tool and is intended only for legacy integrations and deep diagnostics.

package/docs/architecture/current/route-policy.md

@@ -0,0 +1,15 @@
+# Route Policy Authority
+
+Forge has one replayable routing authority: `src/runtime/control-plane/routing/route-policy.ts`.
+
+`decideRoute(RoutePolicyInput)` is a pure function. It applies hard constraints in lexical order: policy and authorization, destructive or remote effects, recovery and isolation, workspace state, explicit provider preference, then efficiency. It does not use dynamic weights.
+
+The decision records execution mode, executor kind, Work requirement, isolation, recovery, approval/handoff state, reasons, a stable input fingerprint, and a policy version. CLI `assessWorkMode`, Facade `selectExecutionMode`, and Goal Loop `routeExecutor` are compatibility adapters only; they may normalize legacy fields but cannot retain thresholds or fallback rules.
+
+Plan is optional reasoning evidence. It is created only for explicit planning, frozen scope, external approval, independent deliverables, or irreversible strategy review. Plan does not gate ordinary complex execution and is not a mutable execution state machine. Work remains the only execution contract for every mutation.
+
+Direct mutation stays on Direct Control but creates lightweight Work lineage. Goal Workloop uses the same Work contract with durable recovery and optional isolation. EditSession stores only a bound execution identity and post-diff assurance; it never owns lifecycle.
+
+Dirty workspaces are never adopted implicitly. A mutation must use a clean/isolated checkout or a separate exact reviewed adoption path. After a real diff exists, assurance is recalculated from changed paths and line count; protected paths can expand checks and require approval before finalization.
+
+Test checkpoint reuse is content-addressed and must expose provenance: checkpoint key, digests, completion time, and evidence path. `--no-cache` remains the deterministic force-execution path.

package/docs/architecture/current/route-session-concurrency.md

@@ -0,0 +1,85 @@
+# Route and Session Concurrency
+
+Status: current architecture
+
+This document records the invariants implemented for `ISS-20260803-90E84B` / `PLAN-ROUTE-SESSION-CONCURRENCY`. Runtime state in the controller-home SQLite control plane remains authoritative. Issue and Task files are historical/import/export artifacts and are not runtime write authority.
+
+## Identity and projection isolation
+
+Every context or projection result is accepted only when its immutable identity agrees with the active request identity. The cache/projection identity includes:
+
+- repository ID;
+- checkout ID and worktree identity;
+- observed Git source identity, including HEAD/source revision;
+- projection identity and generation.
+
+A late result from a previous repository, checkout, source identity, branch observation, or projection generation is discarded. Payload identity and `sourceIdentity` disagreement fails closed. Session default repository state never overrides an explicit repository ID. Registry branch data is advisory; Git HEAD observation is authoritative for source fencing.
+
+The T1 source-identity fencing introduced before this change remains mandatory. No shared mutable cache was added; Gateway contention metrics use bounded process-local aggregation and hashed low-cardinality dimensions only.
+
+## Typed diagnostic runtime resolution
+
+All persisted diagnostic/check launch paths use one typed runtime resolver. The resolver returns:
+
+- executable;
+- argv;
+- runtime kind;
+- source revision;
+- immutable-release flag;
+- a diagnostic explanation.
+
+Runtime kinds are `compiled_bun_release`, `bun_source`, `node_source`, and `package_launcher`. Runtime identity is established by an explicit runtime kind, an immutable standalone marker, the Bun virtual filesystem identity, an explicit package/global launcher entry, or the Bun/Node executable identity. File extensions are not used to guess launch semantics.
+
+Package/global shims and paths containing spaces remain separate argv entries. A package launcher requires an explicit launcher entry. Source and compiled runtimes therefore use the same resolver contract instead of separate argv fallback chains.
+
+If runtime identity cannot be resolved, the controller creates a short persistent Process that exits terminally and reports `DIAGNOSTIC_RUNTIME_UNRESOLVED`. The request cannot remain `running` or `validating` after resolver failure.
+
+## Gateway bounded-latency boundary
+
+Gateway synchronous work is limited to bounded identity resolution, registry/control-plane reads, routing, and admission. Heavy operations are Process-managed:
+
+- workflow watchdog;
+- runtime maintenance status;
+- cleanup preview;
+- runtime performance diagnostics, including process and temporary-directory scans;
+- capability recovery probe;
+- persisted check execution.
+
+The Gateway waits at most five seconds for an inline diagnostic result. The Process execution timeout remains independent. After the interactive budget expires, the response contains the durable Process reference and polling pointers. Process status, cancellation, timeout, terminal receipts, and restart reconciliation remain persisted and truthful.
+
+A diagnostic for one repository cannot occupy another repository session's request path. The routing regression starts a delayed Process for repository A while repository B continues a bounded board read.
+
+## Authoritative checkout mutation lease
+
+Direct Edit and durable execution use the same execution lease store and conflict rules. Mutation claims are explicitly scoped by repository and checkout; cwd, session defaults, and stale registry branch values cannot create an unscoped mutation owner.
+
+The authoritative owner identity contains:
+
+- repository ID;
+- checkout ID;
+- worktree ID;
+- branch;
+- principal ID;
+- controller instance ID;
+- controller generation.
+
+A SHA-256 owner identity digest is persisted with every lease and is included in renew, assert, rollback, and release fencing. A stale controller instance or generation cannot renew or release a live owner's lease. Terminal, cancelled, failed, timeout, snapshot-failure, and restart cleanup paths release only leases whose owner, lease ID, fencing token, and identity digest match.
+
+Conflict semantics are checkout-local:
+
+- two writers for the same checkout serialize;
+- different checkouts in the same repository can proceed in parallel;
+- different repositories can proceed in parallel;
+- read-only requests do not acquire the mutation lease.
+
+## Bounded lock acquisition and metrics
+
+Gateway-reachable controller locks never sleep synchronously. `tryAcquireControllerLock` performs one acquisition attempt. The compatibility synchronous API returns `LOCK_HELD` immediately on contention, even when an obsolete caller supplies a long wait budget. The asynchronous API yields to the event loop and caps its total wait at five seconds.
+
+Metrics record wall-clock, queue, lock wait, storage, Git observation, worker/process, projection, execution, and serialization phases. Aggregation dimensions are operation class plus hashed repository/checkout buckets. Full paths, secrets, request payloads, principals, branch names, and user input are not recorded. Aggregation is bounded to 256 buckets and 512 samples per bucket.
+
+## Operational consequences
+
+A contention response is an admission result, not a hidden blocking wait. Callers may retry durably or hand off to a Process/worker. A persistent Process reference is the continuation point for heavy diagnostics and checks. Restart recovery reads persisted state and never reconstructs ownership from cwd or session defaults.
+
+The reproducible capacity baseline and threshold derivation are documented in `docs/operations/route-session-concurrency-baseline.md` and materialized as `docs/operations/route-session-concurrency-baseline.json`.

package/docs/architecture/current/runtime-architecture-simplification.md

@@ -0,0 +1,214 @@
+# Canonical Single Runtime Architecture and Seven-Phase Replacement
+
+> **Status: Runtime Authority — Approved Target Architecture**
+>
+> **Scope:** Forge local Runtime process ownership, readiness, release/rollback, Worker fencing, and deletion of legacy lifecycle paths.
+>
+> **Current implementation status:** source convergence complete. The Canonical Runtime is the only core lifecycle architecture; Supervisor, independent Daemon/Ingress, runtime slots, bootstrap compatibility authority, restart coordinator, and component lifecycle scripts are deleted. Live activation of a release remains a separate explicitly authorized operational action.
+
+## 1. Non-negotiable end state
+
+Forge converges to:
+
+```text
+one local MCP application
+one active Runtime
+one root lifecycle owner
+one complete release
+one whole-Runtime readiness result
+one whole-Runtime publish and rollback unit
+```
+
+Gateway Adapter, Controller Services, Scheduler, SQLite, MCP Transport, and Worker Manager retain module boundaries for code organization. They are not independent deployments, generations, lifecycle owners, readiness authorities, or rollback units.
+
+The only supported core process topology is:
+
+```text
+forge-runtime
+  ├─ MCP Transport                 in process
+  ├─ Gateway Adapter               in process
+  ├─ Controller Services           in process
+  ├─ Scheduler                     in process
+  ├─ SQLite                        in process / library boundary
+  ├─ Worker processes              bounded child execution units
+  └─ Helper processes              bounded, request-owned execution units
+```
+
+External tunnels are optional transports. They may connect to the Runtime endpoint, but they cannot start, stop, restart, adopt, publish, roll back, or determine readiness for the Runtime.
+
+## 2. Target Runtime
+
+`CanonicalForgeRuntime` is the sole root lifecycle owner. It performs one ordered startup, one ordered shutdown, and one fatal-failure path for the complete application.
+
+After acquiring the single Runtime ownership claim and confirming the selected whole-release authority, startup collects the exact configured Runtime source identity and atomically rotates `system/runtime-generation.json`. This happens before the write claim, Controller Services, SQLite admission, Scheduler, Workers, or MCP Transport. Source collection or snapshot persistence failure is a release-coherence startup failure; startup must stop and release ownership rather than serve with an unknown source baseline.
+
+It alone may:
+
+- acquire the Controller Home Runtime ownership claim;
+- initialize SQLite and Controller Services;
+- start the in-process Scheduler;
+- create the Gateway Adapter and MCP Transport;
+- start and fence Workers through the Scheduler/Worker Manager boundary;
+- publish the single Runtime readiness result;
+- stop the complete Runtime after a fatal core-module failure.
+
+No core module may create a KeepAlive loop, detached restart coordinator, secondary generation, child lifecycle supervisor, component release pointer, or component rollback operation. The canonical `runtime` inspection surface does not own module lifecycle. The OS service manager owns one `forge-runtime` root service, while standalone Recovery may restart that complete service or perform an offline previous whole-release recovery under one cross-process lock.
+
+## 3. Seven phases
+
+| Phase | Required result | Current source assessment |
+| --- | --- | --- |
+| 1. Establish Canonical Single Runtime | MCP Transport, Gateway Adapter, Controller Services, Scheduler, SQLite, and Worker Manager are started by one Runtime Root | Implemented in the source architecture: `forge-runtime` starts the complete core application in one process |
+| 2. Converge lifecycle ownership | Runtime Root is the only in-process core owner; one OS service and one standalone Recovery owner operate only on the complete Runtime | Implemented: public component lifecycle commands, Supervisor, independent Daemon, KeepAlive wrappers, component restart owners, and detached recovery paths are deleted; the Forge service starts one Runtime Root, and standalone Recovery can restart that complete service or perform previous whole-release recovery |
+| 3. Simplify readiness | Public Runtime readiness is only `ready: true/false`; module observations are diagnostic evidence | Implemented: Canonical Runtime, status projection, Recovery verification, and public `controller_ready` use one binary Runtime decision |
+| 4. Remove ingress and Runtime slots | No Stable Ingress, fixed blue/green ports, runtime slots, mixed generation, adoption, or component cutover | Implemented: Stable Ingress, blue/green slots, slot homes, activation transactions, writer authority, and slot fallback readers are deleted |
+| 5. Whole-Runtime publish and rollback | Code, configuration, entrypoint, manifest, SQLite schema/backup, and Worker protocol move as one compatible set | Implemented: one active/previous whole-release authority, local SQLite backup/restore, service startup binding, bounded whole-Runtime restart, and automatic previous-release recovery after restart exhaustion; old bootstrap/slot authority is deleted |
+| 6. Complete Worker isolation and fencing | Workers are bounded Runtime-owned children; stale Workers cannot commit control-plane side effects | Implemented: Workers inherit Runtime instance, owner PID, release authority revision/token, release ID, artifact identity, and Worker protocol; write paths import the Canonical Runtime fence directly; durable OperationReceipt recovery matches non-secret Runtime/release identity plus Job/attempt/PID/Lease evidence |
+| 7. Delete legacy architecture | Supervisor, Ingress, KeepAlive, slots, component rollout/rollback, and old authority are removed | Implemented in source: Supervisor, Stable Ingress, independent Daemon, KeepAlive, component rollout, slots, activation transactions, writer authority, and public lifecycle commands are deleted |
+
+A change that cannot be assigned to one phase, or that does not reduce core processes, lifecycle owners, readiness authorities, release units, or compatibility paths, is presumed scope drift and must stop for review.
+
+## 4. Readiness contract
+
+The public contract is intentionally small:
+
+```ts
+interface RuntimeReadiness {
+  ready: boolean;
+  reasonCodes: string[];
+  diagnostics: {
+    database: DiagnosticEvidence;
+    scheduler: DiagnosticEvidence;
+    releaseCoherence: DiagnosticEvidence;
+    mcpEndToEnd: DiagnosticEvidence;
+  };
+  observedAt: string;
+}
+```
+
+Only `ready` is the Runtime decision. `reasonCodes`, `diagnostics`, and `observedAt` explain the decision. Public readiness does not expose `state`, component top-level readiness objects, slots, generations, Supervisor state, or Ingress state. Detailed legacy observations may remain internal temporarily, but must not become a second lifecycle state machine.
+
+Forbidden public Runtime readiness combinations include:
+
+- `degraded`, `partial`, `recovering`, or component-specific top-level states;
+- independently authoritative Gateway, Controller, Scheduler, or database readiness;
+- port/PID health promoted to Runtime readiness;
+- readiness that remains true after any fatal core module exits.
+
+The Runtime becomes ready only after release compatibility, SQLite, Scheduler, MCP initialize, tools/list, authenticated Controller access, and a SQLite-backed read all succeed in the same Runtime instance.
+
+## 5. Whole-Runtime release and rollback
+
+A Runtime release is one immutable compatibility set:
+
+```text
+entrypoint
+core code and assets
+bounded helper runtimes and libraries (Process/Check, Browser/Desktop, external-plugin probe, CodeGraph Node/library/sidecar)
+Runtime configuration schema
+release manifest
+SQLite schema compatibility (distributed metadata only; never database contents)
+local pre-upgrade database backup contract under Controller Home
+Worker protocol version
+migration and rollback metadata
+```
+
+Release validation is offline and does not require a second serving Runtime, traffic router, fixed alternate port, or persistent slot identity. `src/runtime/root/release-store.ts` records one atomic active/previous authority and binds each previous release to a verified local SQLite backup under Controller Home. SQLite rows are project execution state: they are not copied into the immutable release, source repository, installer, manifest, or anything distributed to another user.
+
+Activation is a whole-Runtime restart:
+
+1. validate the complete immutable release and configuration;
+2. verify database compatibility and create the required backup before mutation;
+3. stop admission and quiesce the current Runtime;
+4. stop the complete current Runtime;
+5. start the complete new Runtime from one release entrypoint;
+6. require whole-Runtime readiness;
+7. on failure, stop the failed Runtime and restore the complete previous release/config/database compatibility set;
+8. start the previous Runtime and require whole-Runtime readiness.
+
+No operation may independently publish, restart, or roll back Gateway, Controller, Scheduler, MCP Transport, SQLite schema, or Worker protocol.
+
+Bounded helper processes remain part of this one compatibility set. They do not become services or lifecycle owners: the Runtime launches them for one request, applies deadlines and cancellation, and collects typed evidence. In particular, CodeGraph reads only an existing checkout-local `.codegraph/` index; failure degrades the requesting structural-context contract and never establishes a separate readiness or recovery state machine.
+
+## 6. Worker boundary and fencing
+
+Workers remain separate processes because they execute bounded external work. They are not Runtime owners.
+
+Every Worker attempt must carry:
+
+- Runtime instance identity;
+- Runtime release identity;
+- Worker protocol version;
+- Job/Work identity and attempt;
+- exact Lease and fencing token set;
+- bounded deadline and cancellation channel.
+
+A Worker created by an old Runtime cannot renew Leases, publish heartbeats, commit results, write evidence as current, release replacement ownership, or perform control-plane side effects after Runtime ownership changes.
+
+Workers cannot schedule other Workers, select releases, recover the Runtime, mutate Runtime authority, or maintain a forever loop.
+
+## 7. Legacy inventory and deletion order
+
+The following paths are legacy implementation inventory, not target building blocks:
+
+| Legacy area | Required disposition |
+| --- | --- |
+| `src/runtime/supervisor/**` | deleted; architecture checks require the directory to remain absent |
+| Stable Ingress router and ingress session/process state | deleted in phase 4; one Runtime endpoint is configured directly |
+| MCP KeepAlive/restart commands and implementations | public/hidden entrypoints, the 911-line restart implementation, and the 1,136-line KeepAlive process/tunnel/restart owner are deleted in phase 2; reusable HTTP/stdio transports remain module code only |
+| MCP transport and Gateway tool Daemon auto-start | removed in phase 2; readiness and tool responses may observe daemon status but cannot create or recover Controller Services |
+| independent daemon entry and component service API | deleted; `runtime-status-client.ts` is read-only observation over Canonical Forge Runtime state |
+| `src/cli/controller/runtime-slots.ts` and slot homes | deleted in phase 4; architecture checks require them to remain absent |
+| `src/cli/controller/bluegreen-rollout.ts` | deleted; must not return |
+| public `controller` lifecycle/blue-green commands and public `supervisor` command | deleted from the supported CLI surface and implementation tree |
+| detached restart coordinator and component restart bridges | deleted, including retired stubs and repository lifecycle shell entrypoints |
+| standalone Recovery PI/agent repair and repository-write authority | removed in phase 2; Recovery code must never launch an agent in, generate scripts in, move files from, or otherwise mutate a source checkout |
+| stable ingress ports and private blue/green ports | deleted; one Runtime endpoint is configured directly |
+| component generation and mixed-generation coherence | deleted; one Runtime instance/release identity remains |
+| Gateway/MCP component restart, rollout, rollback, green-gate and Supervisor facade operations | removed from direct tools and `rh_status`/`rh_work`; no compatibility facade may trigger lifecycle changes |
+| Recovery lifecycle/self-healing compatibility surfaces | deleted from descriptors, MCP definitions, dispatch branches and maintenance status; source-coherence failure produces an external lifecycle handoff only |
+| component rollout/rollback operation stores | deleted with the Supervisor implementation; only whole-Runtime release authority remains |
+| compatibility authority projections | deleted after one-way migration; no permanent dual-read or dual-write remains |
+
+Legacy code may receive only deletion-enabling or safety-fencing changes. New features, new states, new rollback protocols, or new recovery automation must not be added to it. Recovery diagnostics may read source identity, but must never write a source checkout. Recovery state, evidence, and configuration remain below Controller Home; temporary OS service metadata is legacy deletion inventory, not a new authority. Autonomous code repair is not an allowed Runtime recovery mechanism.
+
+## 8. Scope-drift assessment of prior work
+
+The earlier fixed release-manifest work, Controller Home ownership, explicit Runtime configuration, SQLite inspection, in-process Scheduler, authenticated MCP end-to-end probe, and Worker fencing primitives remain useful.
+
+The following earlier direction is no longer an approved target:
+
+- treating Supervisor as the permanent root application;
+- retaining independently managed Daemon and Gateway processes;
+- moving Stable Ingress into the Supervisor process instead of deleting it;
+- replacing blue/green slots with candidate/current/previous traffic switching;
+- preserving component readiness, component restart budgets, and component rollback;
+- adding an independent primary Recovery service family for the local application.
+
+Those directions are historical only. They must not reappear as executable compatibility paths, fallback scripts, durable authority, or release mechanisms.
+
+## 9. Required review questions
+
+Every Runtime refactor review answers:
+
+1. Which of the seven phases owns this work?
+2. Does it directly reduce the gap for that phase?
+3. Does it add a process, state, owner, authority, or long-term compatibility path?
+4. Does it reintroduce component deployment, recovery, or rollback?
+5. Does completion move the system toward one Runtime, one Owner, and one release?
+6. Which legacy layers still remain?
+7. What is the next deletion or convergence step?
+
+## 10. Completed source convergence order
+
+1. `forge-runtime` became the only supported core startup entry.
+2. Controller startup and Worker Manager ownership moved into Runtime Root.
+3. Public readiness converged to one whole-Runtime boolean decision.
+4. Stable Ingress was removed and MCP Transport binds directly to the configured Runtime endpoint.
+5. Runtime slots, fixed alternate ports, mixed generations, and component cutover were removed.
+6. Whole-Runtime release, database backup, and rollback authority was established.
+7. Worker commits were bound to Runtime instance, release identity, Job attempt, and Lease fencing.
+8. Supervisor, KeepAlive wrappers, independent Daemon entry, restart coordinator, component rollout/rollback, and compatibility authority were deleted.
+9. One stable Forge Runtime service and standalone Recovery watchdog were added without slots: sustained failure triggers bounded whole-Runtime restart, then attested previous-release rollback and verification.
+
+Forge has no blue-green Runtime pair. Candidate canaries execute before an explicitly authorized stop/switch/start activation, and failed activation or later sustained failure uses the single previous whole-release authority. No rollout, service installation, service restart, or live cutover is implied by source implementation work.