@moretea-labs/forge 1.8.0 → 1.8.1

package/docs/architecture/decisions/20260918-stable-candidate-release-lifecycle.md

@@ -0,0 +1,221 @@
+# ADR: Stable A / Candidate B and ReleaseSession authority
+
+- **Status:** Accepted source architecture; authority boundary refined 2026-09-20; live cutover remains a separate release operation
+- **Date:** 2026-09-18
+- **Authority:** [`../CURRENT.md`](../CURRENT.md) and executable Runtime/Recovery contracts
+
+## Decision
+
+Forge self-hosting has two lanes during a release session:
+
+```text
+Stable A (fixed known-good package Runtime)
+  source read/edit/build/static verification + Recovery control
+  remains running and is never upgraded by the session
+
+Candidate B (one isolated Controller Home)
+  copied SQLite snapshot + independent token/config/port/service label
+  portable immutable release materialized once and tree-hashed
+  all candidate canaries on the exact artifact later promoted to A
+
+ReleaseSession (release domain)
+  sole durable normal-release lifecycle authority
+  durable receipt/fence journal
+  final semantic routing decision: B or still-healthy A
+
+Standalone Recovery provider
+  physical Candidate B preparation and verification
+  fenced Runtime activation / rollback
+  Watchdog health recovery only
+```
+
+Candidate B never shares A's Controller Home, `control-plane.sqlite`, release
+authority, token file, TCP port, service label, Runtime incarnation, Supervisor
+socket or writer claim. B is not a second production authority: its Home is a
+bounded test clone. New compiled release manifests are deployment-portable and
+omit Controller Home; deployment binding belongs to release authority/service
+contract instead. The exact verified B artifact is promoted byte-for-byte into
+A's immutable release store. A remains the execution plane until an approved
+ReleaseSession reaches one final cutover.
+
+No source build, static gate, architecture review or ordinary test may stop or
+activate Stable A. After the source batch is accepted, ReleaseSession may boot
+and restart only isolated Candidate B while A remains continuously available.
+The sole production cutover happens only after B passes Recovery, MCP,
+Scheduler, Supervisor and controller canaries. Final certification then covers
+A→B→C continuation, failed startup, Recovery interruption, Runtime restart,
+MCP reconnection, stale Supervisor writer and return-to-A rollback.
+
+## Incarnation and writer fence
+
+`runtime-incarnation.json` is the Controller-Home durable writer epoch. Runtime
+ownership acquires it monotonically with `runtimeInstanceId`, PID and
+`fencingGeneration`; a child claim contains the same generation. A write is
+valid only when owner, incarnation and whole-release authority all match.
+Crash/hard-stop replacement advances the generation, making every old Runtime,
+Scheduler worker, Gateway request and process writer stale without relying on
+their `close()` handlers.
+
+Supervisor's Unix socket has only ephemeral owner evidence containing the same
+incarnation. A live socket is a hard writer conflict. A non-connectable socket
+can be reconciled only as stale evidence for a different incarnation; the
+historical `WORKFLOW_SUPERVISOR_WRITER_ALREADY_PRESENT` condition is therefore
+an acceptance case, not a fallback branch.
+
+Every service/Recovery/child boundary starts from the shared private-authority
+environment sanitizer. It strips `FORGE_CONTROLLER_*`, `FORGE_RUNTIME_*`,
+`FORGE_RELEASE_*`, `FORGE_SUPERVISOR_*`, `FORGE_WRITER_*` (including
+`FORGE_WRITER_SLOT`) and related process identity. The exact selected release
+contract may then add its own values. No ambient host claim is inherited.
+
+## Recovery bundle and known-good
+
+Known-good schema v2 means all of the following validate together:
+
+1. immutable release manifest identity;
+2. Recovery-owned SQLite `VACUUM INTO` snapshot with SHA-256 and inspection
+   counts/schema;
+3. a hashed declarative Runtime service-contract snapshot.
+
+The bundle lives below `Recovery/bundles/known-good/<attestationId>`. Recovery
+creates its data before atomically publishing the known-good record, then
+prunes unreferenced bundles only after publication. A crash leaves at most an
+orphan for the same Recovery owner to clean; it never publishes a metadata-only
+known-good record. Release retention uses this exact validator. Legacy schema-1
+records remain audit history only and have no retention or rollback authority.
+
+## ReleaseSession state
+
+`Recovery/state/release-sessions/<id>.json` is the durable storage path for the
+ReleaseSession transaction journal; that path is not a second authority. The
+ReleaseSession domain owns semantic phase progression and a per-record revision
+CAS, while the executing Recovery provider holds the existing mutation lock for
+physical operations. Authority decisions read the complete journal through a
+process-local cache that is invalidated by atomic session writes and directory
+changes; bounded inventories are diagnostic/projection surfaces only and may
+never decide whether an active or prior-attempt session exists. Terminal session
+records remain durable evidence, while their Candidate B homes are physically
+retired once; an already-absent home is an idempotent no-op and is not emitted as
+a fresh cleanup event. A stateless ReleaseCoordinator derives the next action
+from the persisted phase and has no second daemon, scheduler, Work, or durable
+coordinator state. Only one non-terminal ReleaseSession may exist per Forge
+instance. An interrupted `source_frozen` preparation resumes that same session
+when the frozen source and Stable A identity still match.
+
+Recovery's own bundle handoff acquires that same exclusive operation lock before
+changing the immutable release pointer and holds it through activation verification
+or exact rollback. New Gateway requests are fenced during this interval and the
+admission marker is cleared on every exit. Open read-only MCP streams are transport
+connections, not in-flight mutation evidence; HTTP request counts cannot add a
+second quiescence gate. The existing service handoff still proves the previous
+process has stopped and the exact replacement is serving before acceptance.
+
+ReleaseSession separates wire compatibility from semantic authority. One-way migration also reconciles historical legacy `soaking` records without guesswork: Candidate B is terminalized as `known_good` only when exact durable lineage proves it became a later Stable A, or current RuntimeReleaseAuthority `previous` references that exact release identity; missing proof fails closed. Multiple later ReleaseSession attempts that all name the same exact Candidate B as Stable A are corroborating acceptance evidence, not branches. Successor proof is derived from one pre-migration inventory snapshot, so rewrite order cannot manufacture or erase acceptance evidence. Its
+storage `schemaVersion` remains 1 so the immediately previous Recovery release
+can still inventory the record after an exact rollback; current code requires
+`semanticEpoch=2`. The migration boundary rewrites legacy epoch-1/epoch-less
+records once and thereafter steady-state code consumes only epoch 2. The
+`transaction` field is additive on the wire and ignored by the prior reader.
+RuntimeReleaseAuthority schema 2 is the physical active/previous pointer plus
+rollback SQLite artifact only; it carries no ReleaseSession transaction state.
+
+```text
+source_frozen → built → static_verified → candidate_booted
+  → candidate_verified → cutover_eligible → cutover_attempting
+  → cutover_committed → soaking → known_good
+                         ↘ rolled_back / failed
+```
+
+`static_verified` requires type, runtime-architecture, architecture-sync and
+bootstrap receipts from the frozen source revision. `candidate_verified`
+requires Recovery restart, MCP, Scheduler, Supervisor and controller receipts
+from isolated B. `cutover_eligible` is impossible while A and B collide on Home
+or port. Before the first production activation, a transient failure to obtain a
+fresh Stable A verification leaves the same ReleaseSession `cutover_eligible` so
+the exact candidate can be retried after observation recovers; proven Stable A
+identity drift is a real precondition failure. `cutover_attempting` permits
+exactly one fenced production cutover; verified return to exact A terminalizes
+`rolled_back` and is never retried. If observation is interrupted after the
+rollback authority commit but before the ReleaseSession phase write,
+reconciliation requires the exact `release-session-rollback:<sessionId>:`
+authority operation plus matching Stable A, candidate and transaction identities;
+it then records `rolled_back` without replaying the rollback effect.
+Physical service handoff follows the same effect rule: a launchd/systemd helper
+error or timeout is not itself authority that the requested stop/start failed.
+Recovery performs bounded observation of the exact service identity and may
+continue the same fenced transaction only when the physical effect is proven;
+otherwise that transaction fails. Before stopping Stable A, Recovery may build
+the rollback SQLite snapshot while A is still serving, but only under a
+long-lived SQLite `data_version` observer. Any commit by another SQLite
+connection during or after that speculative snapshot invalidates it; after
+quiescence the release store discards it and falls back to the stopped-state
+snapshot. Recovery also computes the bounded SHA-256 of that snapshot while A
+is still serving. RuntimeReleaseAuthority persists this whole-database identity;
+on rollback, a fresh live `VACUUM INTO` snapshot is compared against it. Only an
+identical whole-database snapshot may be restored from the cutover backup. Any
+SQLite change, including domain tables outside `control_plane_audit`, preserves
+the newer live database while the Runtime release rolls back. Legacy backups
+without whole-database identity also preserve live state. This optimization
+therefore removes normal-path database copy/hash cost from the outage window
+without weakening rollback or losing post-cutover durable state.
+
+During the stop/start critical section, readiness convergence is intentionally
+narrow: canonical Runtime owner/status, exact release/artifact authority and the
+local `/ready` endpoint. Recovery Gateway/watchdog/tunnel probes, Connector
+transport probes, execution canaries, known-good inspection and MCP protocol
+verification are not activation-readiness inputs. After Runtime readiness,
+Recovery rebinds the persistent Connector and then runs strict whole-Runtime
+verification exactly once. There is no second readiness polling phase after
+Connector rebinding. Once the physical candidate authority is published, the
+ReleaseSession rollback transaction is durably captured before Candidate B is
+started, so every later start/Connector/acceptance failure already has exact
+Stable A rollback identity. Recovery never replays a cutover merely because a
+helper response was lost.
+Automatic source reconciliation is also revision-bounded: once an immutable
+source revision has any terminal ReleaseSession, the daemon will not create a
+second automatic ReleaseSession for that same revision. Explicit human release
+operations remain available, and a changed source revision becomes eligible for
+a new automatic attempt. This rule is derived from ReleaseSession history; it
+introduces no retry ledger or second release authority.
+
+Successful cutover enters `soaking` as soon as the canonical live Runtime observation proves the expected release/artifact identity is running, ready and non-stale. Cutover reconciliation does not rerun the expensive full verification suite after activation. Only the existing full verification + performance observation + recoverable release/SQLite/service bundle attestation may terminalize `known_good`. A definitive runaway-CPU rejection is an acceptance
+failure, so Recovery executes the existing exact Stable A rollback transaction
+instead of leaving Candidate B in `soaking` for repeated performance sampling.
+Transient/unknown observations remain non-terminal and may be reconciled against
+the same ReleaseSession. The state machine records redacted receipt ids and
+summaries, never tokens, raw database payloads or browser messages.
+
+## Persistent-state contract
+
+| State | Semantic owner / writer | Terminal & retention | Recovery |
+| --- | --- | --- | --- |
+| `runtime-incarnation.json` | Canonical Runtime ownership acquisition | latest epoch; superseded generations remain stale | next owner CAS-reconciles |
+| Supervisor socket owner evidence | Canonical Runtime/Supervisor composition | deleted with socket; ephemeral | probe then remove only stale non-connectable socket |
+| known-good bundle | Standalone Recovery | bounded live attestations; prune only after state commit | validate release + DB + service contract offline |
+| RuntimeReleaseAuthority | Runtime Root physical release store | schema 2; active/previous release identity and previous SQLite backup only | physical publish/rollback; no release-phase or transaction intent |
+| ReleaseSession | Release domain / stateless ReleaseCoordinator | wire schema 1 + current semantic epoch 2; `known_good`, `rolled_back`, `failed`; bounded session retention is physical cleanup | revision CAS resumes the same session; Recovery provider executes physical effects |
+| Candidate B Home | ReleaseSession semantic authority / Recovery physical provider | explicit terminal cleanup only after evidence retention | no deletion/rebuild of A; B can be inspected independently |
+| Process Runtime terminal lease | Process Runtime lease authority | terminal evidence and lease release are separate idempotent phases | terminal observation/wait/cancel and full maintenance retry exact lease release until settled |
+
+All bundle and session data is local Controller state. It contains no secrets:
+the service contract records a token *path*, while each B token is an independently generated private credential and is never copied from A. SQLite data follows the Controller Home's existing privacy/backup policy.
+
+## Verification
+
+- Ordinary repository Work terminalizes at accepted source delivery and cannot depend on Runtime staging, activation, soak or known-good;
+- release-level gates execute once for the frozen ReleaseSession candidate rather than once per contributing Work;
+- Candidate lane derivation/build cannot mutate A; Candidate boot/restart touches only B's isolated service/Home;
+- byte-identical release-tree identity is required for B→A promotion; no production rebuild is allowed;
+- stale Runtime generation and release claims cannot write;
+- every Recovery restart/release transition proves service, Runtime owner, TCP listener and Supervisor writer quiescence before authority may change;
+- Recovery restart/cutover readiness polling is bounded to fenced Runtime identity plus local readiness; strict whole-Runtime verification remains a single post-Connector acceptance gate;
+- the normal cutover prebuilds and hashes its rollback SQLite snapshot while Stable A is live and reuses it only when one SQLite-wide `data_version` observer proves no intervening commit; otherwise stopped-state backup remains the fail-closed fallback;
+- rollback restores the cutover SQLite snapshot only when whole-snapshot SHA-256 matches a fresh live snapshot; any database-wide change preserves live SQLite, while `auditEventCount` remains compatibility/diagnostic evidence only;
+- ReleaseSession captures exact rollback transaction identity immediately after the physical authority publish and before Candidate B starts;
+- private writer environment cannot cross service or child boundaries;
+- stale or missing known-good bundle material cannot protect a release;
+- ReleaseSession cannot advance past static/candidate gates or a stale CAS;
+- no-op automatic reconciliation does not fork a Recovery worker, and terminal source revisions are not autonomously replayed;
+- definitive runaway-CPU rejection restores Stable A through the existing ReleaseSession rollback authority rather than repeating soak measurement;
+- terminal Process observation and full maintenance both reconcile any exact leftover workspace lease; `completed_unknown` cannot permanently fence a checkout;
+- final live release testing remains a separate, one-shot governed operation.

package/docs/architecture/decisions/20260919-autonomous-work-liveness.md

@@ -0,0 +1,62 @@
+# Autonomous Work liveness invariant
+
+Date: 2026-09-19
+Status: accepted
+
+## Problem
+
+Forge could retain a non-terminal Work indefinitely after its execution carrier and
+Controller ownership disappeared. A current Plan protected that Work from stale
+authority retirement, but nothing materialized the already-existing semantic
+decision that the Work was ready to continue. The visible result was an unfinished
+conversation/task with no process, no live Controller owner and no next round.
+
+## Decision
+
+Global Scheduler's normal reconciliation cadence owns materialization, not semantic
+planning.
+
+For every active runnable Work with no active execution and no live Controller
+owner:
+
+1. If the Work is Plan-bound, projectAutonomousGoalProgression() is the sole
+   authority deciding whether the current Work is WORK_READY_TO_CONTINUE.
+2. If the Work is not Plan-bound, reconciliation may perform only the lower-level
+   mechanical liveness wake when Work/Requirement/ControllerRound state contains
+   no terminal or explicit wait authority. It never invents Plan authority.
+3. Existing retained ControllerSession identity and ControllerBinding are reused.
+   A retained session is identity evidence, not a live ownership lease.
+4. ControllerRound remains the sole provider-effect fence. The progression
+   idempotency key, or a deterministic planless Work occurrence key, becomes the
+   occurrence identity, so repeated scheduler ticks converge rather than replay.
+5. If Workflow Supervisor owns the outer ChatGPT turn, Scheduler only ensures the
+   idempotent Supervisor enrollment effect. It must not dispatch a competing
+   provider prompt.
+6. Existing semantic wait, wait_for_user, blocked/failed round state, live
+   execution, live Controller ownership and terminal Work/Requirement state all
+   suppress automatic continuation.
+
+No new lifecycle state, watchdog table, polling daemon, retry authority or
+Process-specific continuation path is introduced.
+
+## Baseline boundary
+
+Liveness reconciliation does not re-check the repository integration baseline in
+the middle of an already-running isolated Work. For Plan-bound Work it evaluates
+Goal Progression against the Plan's frozen source revision. Baseline drift remains
+an admission/replan boundary after the independent Work reaches its semantic
+boundary; it is not a reason to repeatedly interrupt execution.
+
+## Recovery boundary
+
+The existing periodic stalled-ControllerRound recovery remains responsible for
+already-open rounds whose provider dispatch or closure was abandoned. The new
+normal reconciliation path handles the previously invisible case where no round
+exists at all.
+
+## Acceptance
+
+A runnable ownerless Work converges to exactly one existing Controller continuation
+authority within the normal Scheduler reconciliation cadence. Repeated ticks and
+runtime re-entry cannot duplicate provider dispatch, and explicit waits remain
+stable.

package/docs/architecture/decisions/20260924-thin-semantic-working-context.md

@@ -0,0 +1,72 @@
+# Thin semantic working context and revision authority
+
+Status: accepted architecture; canonical cutover is implemented in current source with final verification pending. Frozen-client compatibility projections remain where required.
+
+## Decision
+
+Forge exposes only three cross-domain model-authored semantic records: Requirement, Plan, and optional Work. Requirement is stable intent, Plan is model-authored strategy/decisions/progress, and Work is an independently resumable semantic unit. Workflow, Schedule, Connection/Grant, Process, ControllerRound, repository state, and domain handles remain operational, security, execution, or domain facts rather than additional working-memory authorities.
+
+Each semantic record has one stable identity, one portable semantic scope and one monotonic semantic revision. ForgeInstance is the root authority; repository/checkout identity is execution placement or optional domain context, never synthetic semantic ownership. Model-facing writes use expected-revision compare-and-swap. A stale write fails with the current semantic record/revision and never silently merges. The append-only requirement_revision, plan_semantic_revision, and work_semantic_revision records are immutable history evidence, not independently mutable authorities; Controller storage revisions remain internal persistence concurrency metadata.
+
+Plan semanticContext is the model-facing semantic authority once present. Legacy PlanContract goal/step/lifecycle fields remain migration/execution compatibility data and cannot implicitly rewrite semanticContext. Requirement/source basis revisions are provenance and staleness hints only. Source movement is observed at concrete mutation boundaries and does not make Plan working memory an execution gate. Thin Plan `scopeKey` is descriptive discovery/lineage metadata only, never an ownership mutex; current model-facing replanning revises the same stable Plan id rather than superseding it.
+
+New Work records materialize semanticState from creation. Mechanical Work status, phase, verification, review, delivery, cleanup, provider, recovery, and completion receipts do not rewrite semanticState. Pre-semantic legacy Work may infer an initial semantic state from its historical terminal status until its first semantic revision; that revision materializes the state and ends the fallback. Work resultRefs are model/user-selected references only. Mechanical completion and check receipts are exposed separately.
+
+ResumeContext is a derived read bundle assembled on demand from the latest relevant semantic records plus current source/resource facts, unresolved human requests, active durable handles, and pertinent receipts. It is never persisted as a fourth aggregate, and conversation text or projection caches are never authority.
+
+## Concurrency and migration boundary
+
+Semantic CAS protects authored context. Git/worktree, Process/resource leases, authorization grants, effect identities, and other concrete fences protect the resources they actually own. Verification is Work-bound evidence and is never gated by a Work-wide ControllerSession claim; durable checks are admitted by the Work's declared check set and then fenced by immutable execution identity plus Process Runtime resource claims. A semantic revision must be applied to the latest persisted aggregate inside the same storage transaction so a concurrent mechanical update cannot be overwritten merely because the semantic revision did not change.
+
+The source still contains legacy Requirement waiting/continue, Plan approval/PlanStep/supersession data, Work finalization, and ControllerRound machinery for frozen-client compatibility and historical delivery continuity. These mechanisms are not current model-facing semantic authorities and cannot be consulted as semantic-write gates. `plan_approve` and `plan_accept_step` are compatibility no-ops; Work completion, verification, review, and terminal state never claim, complete, release, or reopen Plan item state. ControllerRound identity may fence the frozen transport/resume envelope but cannot authorize Requirement/Plan/Work semantic writes, and a frozen client may carry that exact authority through the bounded `session_id` compatibility carrier as long as the canonical principal/Work/round comparison still decides the claim.
+
+Plan items are now authored working memory with no execution authority at all. No active path records a Plan item Work link, promotes item status, requires Plan approval/acceptance, or selects a successor from Plan dependencies: Work start/continue/completion read Plan and Plan item references as provenance only, and `plan.step.retry:<workId>` is a read-only compatibility report. Predecessor obligation continuity, Plan-source drift and Plan-finalization no longer gate Plan admission, Revision, Work execution or Requirement completion. Legacy `PlanContract.steps`/status/obligation fields remain migration-readable data; the retired PlanStep execution plane, obligation-continuity enforcement, Plan-bound Work refresh/retirement helpers and the PlanStep progression projector are deleted, and the architecture check forbids reintroducing them.
+
+No Runtime/Recovery release transition is part of this decision.
+
+## Thin capability substrate consolidation (2026-09-24)
+
+### 0. Execution target and host-local command lane (2026-09-26, Slice 2 partial)
+
+- `ProcessScope` is the canonical Process/Operation storage scope. Repository placement is optional context; the ForgeInstance scope is a sibling partition (`<controllerHome>/instance`) so a non-repository process never needs a synthetic repository identity.
+- The Process Runtime owns an instance-level handle index (`process_handle_index`) recording processId -> target (`forge_instance` | `repository`) -> principal. Attachment resolves its target from the handle, never by scanning repositories or replaying placement inputs.
+- `process_get`/`process_wait`/`process_logs`/`process_cancel` are addressed by `process_id`. An explicit `repo_id` is still accepted and validated against the recorded target.
+- Instance-level handles are principal-bound and ForgeInstance-bound: an opaque handle id locates a record and never authorizes attachment on its own.
+- `process_exec` is the canonical host-local command lane: the target is the serving ForgeInstance, `cwd` is an execution argument, and neither a repository nor a Work is required. It never parses command text to prove path safety; narrow path/repository guarantees remain with typed filesystem/source/git capabilities.
+- Host process execution requires one explicit canonical Grant for `process:exec` whose typed target is the exact ForgeInstance. Missing instance identity, principal, or grant fails closed with no fallback host, container, or checkout.
+- Distinct-by-design from the narrow typed `local_system` plugin lane: `execute_command` is a bounded, target-grant-scoped, typed-argv action whose path operands must stay inside a registered workspace target, while `process_exec` is the deliberately broad raw host capability with no path sandbox and a process handle. Consolidating the two into one owner (or retiring the narrow lane's command action) is an explicit open obligation of this slice, not a settled decision.
+- Already satisfied (reconciled 2026-09-26, source evidence only): a Work-bound repository command defaults cwd to the resolved Work/checkout identity and an authorized explicit cwd outside it is served by the host lane; `git worktree remove` already resolves the owning repository/checkout (`selectTerminalCleanupTarget`) and never selects the removed target checkout as current; `process_get`/`process_wait`/`process_logs`/`process_cancel` resolve by handle with `repo_id` optional.
+- Done — semantic storage identity (Slice 1 remainder): Requirement was already ForgeInstance-scoped (`scope: 'controller'`). Plan is repository-optional: `PlanContract.repoId` (and its revision/summary/input carriers) is optional provenance, `PlanContractStoreLocation` accepts a portable `scopeKey` (`semantic` is the reserved ForgeInstance scope, mirroring the workspace/instance partitions), and `plan_create` with zero enabled repositories creates the Plan in that scope — one repository stays authoritative, several keep the explicit ambiguity error. Plan and Work were already resolvable by stable id across scopes without a repository (`findControlPlaneRecordsByKey`). Work remains repository-bound on purpose: its execution semantics (WorkHandle, leases, checkout/delivery) have no meaning without a target, so its `repoId` is not a fake identity. `rh_status` is now instance-scoped: with zero or several repositories the summary resolves no repository target, reports `repositoryContext: null`, keeps runtime/tool-surface/source-coherence readiness, lists active Plans from the semantic scope, reports Work/handoff sections as unavailable rather than inventing a repository, downgrades `detail_level: detail` to the instance summary (reporting `requestedDetailLevel`), and fails closed with `REPOSITORY_CONTEXT_REQUIRED_FOR_REPAIR`/`..._FOR_DETAIL` only where repository context is genuinely required. `rh_inbox` (legacy Handoff) stays repository-scoped until Slice 7 replaces it with UserRequest.
+- Done — ephemeral workspace scope and typed command target: `workspace_*` is a reserved workspace scope key (`controller-home.ts` `WORKSPACE_SCOPE_PREFIX`/`scopedOperationRoot`). An arbitrary workspace is now a `RepositoryCommandScopeTarget` (`workspaceScopeKey` + root + workspace checkout coordinate) instead of a fabricated `RepositoryRecord`; `resolveEphemeralWorkspaceTarget` no longer builds a repository record. Process/Operation records, lightweight receipts, logs, GC, handle-index targets, command audit, git-command audit, access policy, approval requests, work-handle mirrors and execution leases for a workspace target live in `<controllerHome>/workspaces/<workspaceId>`, and attachment resolves by handle or by the workspace id. Repository and `__controller__` scopes keep their established roots and payload fields byte-for-byte; repository-semantic checks (bound-session mutation, default-branch delivery, work-handle authority, `repositoryGitStatus`) now run only when a repository target exists. Workspace preview/execute payloads report `scopeId` + `workspace` and never a `repoId`. Bounded read-only fallbacks still resolve facts written to the old repository location (process records, lightweight receipts, access policy, approval requests). Residual: `ResolvedExecutionIdentity.repositoryId` still carries the workspace scope key as its required field name, and the controller lock scope key for a workspace is still spelled `{ scope: 'repository', repoId }`; both are naming/typing debt rather than repository identity or repository storage. Repository-semantic behavior for a workspace target (mutation authority, delivery guards) is now explicitly "not applicable" rather than evaluated against a fabricated repository.
+- Open obligation — Grant target matching: exact matching with explicit wildcard only is blocked by `PluginCapabilityAuthorizationGrant.repoId` and `target.identityFingerprint` being optional while plugin queries always normalize `repoId`. Making matching exact requires migrating the stored plugin grants and the query normalization together; tightening only `grant-store.ts` would deny live plugin capabilities.
+- Still open in this slice: generalizing the durable Process/result/artifact/evidence stores to domain-handle scope, making `repository_command_execute` a translation-only facade over the host lane, and the instance-scoped recovery *apply* split (its audit record and several repository-repair actions still require RepositoryContext).
+
+### 1. Mode-free capability surface
+- Capabilities (`read`, `search`, `edit`, `command`, `process`, `git`, `workspace`, `browser`, `computer`, `plugin`, `API`, `agent`, `schedule`, `release`, `recovery`) remain domain-shaped public capabilities and compose without mandatory Requirement, Plan, Work, task-size thresholds, or mode tokens.
+- Shared invocation conventions are deliberately small: principal/target, typed arguments, optional expected revision, timeout/cancellation, idempotency token, and result or typed handle.
+- A direct task may acquire Work durability later by attaching existing semantic refs/handles/receipts without replaying prior effects.
+
+### 2. Mechanical authority consolidation
+- Canonical `Grant` is the single authorization fact for principal + capability/action set + target/resource scope + constraints + expiry/revocation. Plugin authorization reads/revokes/reconciles canonical Grant first; the old plugin grant JSON is migration seed/compatibility projection only. Repository ID is optional locator metadata, not mandatory scope.
+- `OwnedResource` records Forge-created worktrees/branches and cleanup provenance. Creating/recovering a managed workspace records ownership; cleanup receipts settle that ownership idempotently.
+- Optimistic CAS and native Git/OS conflict semantics are default; short exclusive claims exist only for concrete shared mutable resources (Git refs/index, release promotion, physical input, mutable provider target).
+- Work is not a mutex. ControllerSession/ControllerRound remains only where transport, external-effect, or destructive resource fencing needs an exact mechanical identity; it is not a semantic mutation lock.
+
+### 3. Continuity, schedule, and user requests
+- Open Work is durable context, not an autonomous execution loop instruction.
+- `ScheduleDefinition` (authored trigger, target, policy, action, stop conditions, enabled) is split from `ScheduleRuntimeState` (lastTriggeredAt, consecutiveFailures, nextEligibleAt, occurrences, observation data). Scheduler records triggers, timing, bounded backoff and dispatch facts; internal watcher/provider failures do not manufacture human Handoffs.
+- `UserActionRequest` / `UserDecisionRequest` is the canonical person-only blocker/decision authority and coalesces repeated occurrences by rootCauseKey. Legacy Handoff is written only as a compatibility/UI projection after the UserRequest exists.
+- A Schedule occurrence is continuation input, not a human blocker: semantic/model-owned schedules record trigger, decision and occurrence identity without manufacturing Handoff/UserRequest state.
+- Workflow Supervisor observes outstanding external-turn effects and may reserve one exactly-once provider resume for an applied-but-uncompleted effect. It does not own recursive provider retry depth or Scheduler retry policy.
+
+### 4. Completion vs release/recovery
+- `work_complete` records only the model/user semantic decision and result references. Source integration, git merge, publication, release activation, and resource cleanup are separate capabilities/effects.
+- `finalize`, `verify`, `review`, `controller_claim`, controller disposition/release, and plan approval/step-acceptance are not Work operations. After Runtime/Connector rollover they are rejected rather than translated.
+- Pre-cutover `work_finalize` Worker payloads and review-candidate preparation are hard-rejected as well; a restart cannot replay them. Typed repository execution owns Git effects directly.
+- Periodic cleanup does not treat semantic `completed`/`cancelled` as deletion authorization. A dirty managed worktree is retained in place; cleanup never auto-commits, archives, discards, or force-removes uncommitted bytes merely because Work became terminal.
+- Cleanup debt is derived from owned-resource facts, acts only on resources proven Forge-owned, and is retryable/idempotent independently of Work completion.
+
+### 5. Compatibility surface and projections
+- There is no frozen lifecycle envelope after the cutover. Clients reconnect to the current MCP schema and use explicit semantic CAS operations.
+- Deprecated route/work-mode/operational-plan surfaces are compatibility projections only. They may report concrete continuity/placement needs and available capabilities, but must not prescribe task-size modes, worker choice, validation policy, review lifecycle, or next engineering method.
+- Activity/status/Handoff/legacy PlanStep data are derived or compatibility views. A stale projection is repairable cache debt, never a reason to reject a canonical semantic CAS or concrete resource/effect operation.

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

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