@moretea-labs/forge 1.7.2 → 1.8.1

package/docs/architecture/decisions/20260907-controller-round-transition-policy.md

@@ -0,0 +1,311 @@
+# ControllerRound uses one provider-neutral transition policy
+
+Status: Accepted design contract for PLAN-forge-v2-assistant-loop-execution-degradation-20260907-r3.
+
+## Decision
+
+Every durable ControllerRound lifecycle mutation MUST pass through one provider-neutral Kernel transition policy. Scheduler, Launcher, MCP compatibility, ChatGPT/Browser adapters, recovery jobs, Runtime bootstrap/restart code and provider hosts may only:
+
+1. observe durable state,
+2. submit a typed lifecycle event plus bounded fenced evidence,
+3. perform an external effect explicitly authorized by the returned transition/effect intent, and
+4. persist only the transition decision produced by the canonical policy.
+
+They MUST NOT directly invent status changes, clear blocker strings, reset budgets, rotate round authority, promote dispatch outcome, reopen waits, or create provider-specific recovery exceptions. Provider-specific facts are translated into provider-neutral evidence before reaching the Kernel.
+
+The canonical owner belongs under `packages/kernel/controller/**`. Persistence remains atomic/CAS guarded, but persistence is an executor of the policy decision rather than a second lifecycle authority.
+
+## Why
+
+The existing lifecycle has ten relay statuses and four lifecycle stages, but transition authority is distributed across initial launch, dispatch settlement, claim acknowledgement, stalled recovery, explicit authority recovery, disposition submission, release handling, successor handoff and terminal cleanup. `blocked` additionally carries several unrelated meanings. Local guards are individually sensible but the combined system permits gaps, duplicated recovery rules and route-dependent semantics.
+
+The fix is not another blocked-reason branch. The invariant is one lifecycle decision authority.
+
+## Durable state classes
+
+| Class | Relay status | Meaning | Automatic recovery |
+| --- | --- | --- | --- |
+| Open execution | `dispatching`, `dispatched`, `claimed`, `pending_release` | One semantic round is still mechanically open or closing | Yes, only idempotent recovery of the same semantic round |
+| Semantic pause | `waiting`, `waiting_for_user` | Controller intentionally stopped semantic progression | No stalled-time recovery; requires an explicit legal event |
+| Semantic terminal | `goal_complete`, `handed_off` | This lineage node is semantically closed | Never automatically reopened |
+| Failure/fuse | `failed`, `blocked` | Mechanical failure or an explicit policy fuse | Only according to typed failure class and matching evidence |
+
+`lifecycleStage` remains orthogonal evidence of the semantic boundary:
+
+- `dispatching`
+- `dispatch_confirmed`
+- `controller_claimed`
+- `semantic_round_closed`
+
+A status and lifecycle stage combination not admitted by the transition policy is invalid durable state and must fail closed.
+
+## Canonical event model
+
+External layers submit events, never target statuses. The exact TypeScript names may differ during implementation, but the semantics are frozen here.
+
+| Event | Required evidence | Policy responsibility |
+| --- | --- | --- |
+| `occurrence_requested` | occurrence identity, origin, Work/Requirement state, caller authority | Decide whether this is a legal genuinely new occurrence or an illegal fuse/wait bypass |
+| `provider_dispatch_succeeded` | exact round authority + relay scope + provider dispatch receipt/effect identity | Confirm dispatch, clear only provider-dispatch failure state for this round |
+| `provider_dispatch_failed` | exact round identity + classified failure evidence | Increment provider-failure budget and choose retry/fail/fuse |
+| `provider_dispatch_outcome_unknown` | exact effect identity, no contradictory settlement | Enter outcome-unknown reconciliation state; never blind replay |
+| `provider_effect_reconciled` | exact previously unknown effect identity + confirmed executed/not-executed evidence | Confirm existing dispatch or authorize a new dispatch only when absence is proven |
+| `controller_claim_observed` | active ControllerSession ownership + exact round authority/scope | Move the same round to claimed; never create a new semantic round |
+| `semantic_disposition_submitted` | exact claimed round identity + disposition + required handoff/evidence | Close semantic round and consume semantic budgets exactly once |
+| `controller_release_observed` | exact released controller epoch + already persisted disposition | Mechanically continue post-disposition flow without re-submitting disposition |
+| `successor_bound` | completed predecessor + already-admitted successor lineage | Atomically close predecessor relay and create successor round according to authority rule |
+| `stalled_round_observed` | exact current relay revision, liveness evidence, no active conflicting execution/claim | Recover only an unfinished open mechanical transition; elapsed time is never semantic evidence |
+| `semantic_state_changed` | new mechanical/semantic fingerprint tied to exact relay lineage | May rearm `repeated_state`; cannot clear unrelated fuse classes |
+| `provider_environment_recovered` | exact blocked relay revision + verified provider/runtime capability evidence + failure-class match | May rearm `consecutive_failures` for the same undispatched round without consuming another semantic round |
+| `user_resume_requested` | explicit user authority + exact paused/failure lineage | Resume only states whose policy explicitly permits user resume |
+| `terminal_work_observed` | failed/cancelled Work + no active claim | Retire surviving relay mechanically; never fabricate semantic completion |
+| `authority_recovery_requested` | explicit authorized recovery + no active execution/claim + exact current relay | Rekey capability only where policy permits; never change semantic budgets |
+| `runtime_or_session_evicted` | durable round still current, transport/session gone | Preserve semantic round and authority unless an explicit authority-recovery rule applies |
+
+## Blocked policy is typed, not a free-form string switch
+
+`blockedReason` may remain as a compatibility projection, but policy decisions use a typed blocker class. At minimum:
+
+| Blocker class | Meaning | Legal exit | Budget behavior | Authority behavior |
+| --- | --- | --- | --- | --- |
+| `repeated_state` | semantic continuation repeated without meaningful state progress | `semantic_state_changed` with a changed exact fingerprint | reset repeated-state counter only; round/provider-failure budgets preserved | same semantic-round authority when rearming the same undispatched/claimed lineage |
+| `provider_unavailable` / `consecutive_failures` | provider/runtime path repeatedly failed before successful progression | `provider_environment_recovered` with exact relay and verified environment/provider evidence | provider failure streak may start a new recovery epoch; historical failures remain auditable; round/repeated budgets unchanged | preserve authority for the same undispatched semantic round |
+| `round_budget_exhausted` | hard semantic continuation budget reached | no automatic exit; only explicit higher-level replanning/new authorized occurrence that does not pretend to be the same exhausted round | never reset because time passed or provider recovered | old round authority cannot be reused as a fresh semantic round |
+| `provider_dispatch_outcome_unknown` | provider effect may already have happened | exact `provider_effect_reconciled`; positive evidence confirms existing effect, negative evidence may authorize one new dispatch | no blind retry; no semantic-round budget duplication | preserve same authority/effect identity until reconciled |
+| `provider_user_action_required` | provider needs human/auth action | explicit user/handoff resolution followed by legal resume event | no background retry budget churn | same lineage; new semantic round only if policy says the resolved occurrence is new |
+
+No generic `blocked -> dispatching` transition exists.
+
+For the ChatGPT Controller provider, `provider_environment_recovered` is admitted only through exact ControllerRound authority plus a fresh non-semantic provider probe. The probe must use the same runtime provider selection as ordinary Controller dispatch, must not replay the blocked Work prompt, and must produce a server-authored durable Recovery audit record only after dispatch is confirmed. The audit identity is recovery evidence, not a second lifecycle authority: the Kernel still performs the exact relay-scope/authority/CAS checks and the canonical `provider_environment_recovered` transition. Failed, ambiguous, user-action-required, stale, or mismatched probes cannot rearm the fuse. MCP compatibility may expose this as a bounded repair intent, but it must not duplicate `controller.authority.recover` or invent a provider-specific round state.
+
+## Budget contract
+
+ControllerRound has three independent budget dimensions. No code path may use one to reset another.
+
+### `roundCount`
+
+Counts semantic `continue_immediately` progression rounds, not transport retries, Runtime restarts, claim migration, release recovery, provider recovery, outcome reconciliation or stalled-transition repair. It is consumed exactly once at semantic close/open according to the canonical policy.
+
+### `repeatedStateCount`
+
+Measures semantic continuation without meaningful state fingerprint progress. It resets only when policy observes a changed canonical semantic/mechanical fingerprint. Provider health changes alone do not reset it.
+
+### Provider failure budget
+
+Tracks failed provider dispatch/recovery attempts for the exact provider-neutral dispatch responsibility. A verified environment/provider repair may begin a bounded recovery epoch for the same semantic round, but must not erase historical failure evidence or change `roundCount`/`repeatedStateCount`. The implementation may store a typed recovery epoch or derive it from immutable evidence; either way, `consecutiveFailures = 0` alone is not sufficient evidence of recovery.
+
+Time passage is never a budget reset signal.
+
+## Authority contract
+
+There are distinct authorities and they must not be conflated:
+
+- `authorityId`: opaque per-semantic-round ControllerRound capability.
+- `relayScopeId`: durable semantic lineage scope.
+- `claimGeneration`: ControllerSession ownership epoch.
+- provider effect/dispatch identity: evidence identity for an external effect, never Controller authority.
+- MCP/browser/session ids: transport identities only.
+
+Rules:
+
+1. The same undispatched semantic round keeps `authorityId` through transport loss, Runtime restart, MCP eviction, stalled mechanical recovery and verified provider/environment recovery.
+2. A genuinely new semantic round rotates `authorityId`.
+3. Successor Work handoff creates the successor round under the same relay lineage and rotates to a new round capability.
+4. Claim/session migration changes ControllerSession identity/`claimGeneration`, not semantic round identity.
+5. Explicit authority recovery is a separate fenced capability-rekey operation. It must not silently consume a new round or reset budgets.
+6. Provider, Browser and MCP adapters can never mint lifecycle authority by presenting a transport/session id.
+
+## Fresh occurrence rule
+
+`launcher_start` or a schedule/manual trigger is not automatically proof of a fresh semantic occurrence. The transition policy must classify `occurrence_requested` against the latest lineage.
+
+A new occurrence is legal only when the prior semantic state and trigger contract explicitly allow it, for example a designed future schedule occurrence after a semantic `wait`, or an explicit higher-level user/replan action after a recoverable failure.
+
+A launch request MUST NOT bypass:
+
+- `round_budget_exhausted`,
+- an unresolved `provider_dispatch_outcome_unknown`,
+- `waiting_for_user`,
+- `goal_complete`,
+- `handed_off`, or
+- a `consecutive_failures` fuse that lacks verified provider/environment recovery evidence.
+
+Whether ordinary `waiting` permits a later scheduled occurrence is determined by the Schedule/occurrence contract and an explicit occurrence identity, not merely because `beginInitialControllerRoundDispatch` was called again.
+
+## Legal lifecycle skeleton
+
+The policy must preserve this semantic ordering while allowing idempotent retries of each mechanical edge:
+
+```text
+legal new occurrence
+  -> dispatching
+  -> dispatched          (or blocked/failed/waiting_for_user by typed provider outcome)
+  -> claimed
+  -> semantic disposition
+       continue_immediately -> pending_release -> release -> next dispatching/new authority
+       wait                 -> waiting
+       wait_for_user        -> waiting_for_user
+       goal_complete        -> goal_complete
+
+completed predecessor + admitted successor
+  -> predecessor handed_off + successor dispatching (atomic lineage transition)
+```
+
+Recovery never skips semantic edges. It only completes or replays an idempotent mechanical edge of the same semantic decision.
+
+## Persistence boundary
+
+The transition policy consumes an immutable current snapshot plus one event and returns one of:
+
+- `accept`: exact next relay record and optional external-effect intent,
+- `no_op`: idempotent duplicate with the already-authoritative record,
+- `reject`: stable reason/error code,
+- `needs_evidence`: missing exact evidence required to decide safely.
+
+The store applies accepted decisions under the relay-scope lock / transaction using the expected record revision. External effects occur only where the policy explicitly emits an effect intent. After the effect, the adapter submits its receipt as a new event; it never writes the post-effect relay state directly.
+
+This separates lifecycle decision authority from persistence and provider execution while preserving CAS fencing.
+
+## Crash-window contract
+
+Each window has exactly one legal recovery interpretation.
+
+| Crash window | Durable fact | Recovery rule | Forbidden shortcut |
+| --- | --- | --- | --- |
+| before provider dispatch starts | `dispatching`, no effect receipt | same-round dispatch may be authorized by policy | rotate authority or increment semantic round |
+| after provider may have acted but before receipt persistence | effect outcome uncertain | enter/reconcile exact outcome-unknown identity | blind replay |
+| after dispatch receipt, before relay becomes `dispatched` | durable receipt exists | replay `provider_dispatch_succeeded` idempotently | send provider effect again |
+| after `dispatched`, before Controller claim | dispatch confirmed | claim same round from exact ownership evidence | create fresh occurrence |
+| after claim persistence, before prompt/controller observes response | claimed + live/recoverable ownership | duplicate claim is no-op/migration if fenced | consume another round |
+| after semantic disposition persistence, before controller release | `pending_release`/semantic terminal | retry release/post-disposition mechanics only | resubmit disposition |
+| after controller release, before next round creation | closed disposition + released exact epoch | create/restore exactly one next round according to disposition | repeat prior round close |
+| during predecessor/successor handoff | transaction must contain both lineage writes or neither | retry atomic handoff | independently mutate predecessor and successor |
+| Runtime restart | durable relay survives transport | reconstruct from durable state and same round authority | treat restart as fresh occurrence |
+| MCP/session eviction | transport lost only | reclaim/migrate ControllerSession if fenced; preserve relay identity | use new MCP session as authority |
+
+## Fault-injection matrix frozen for the next Plan step
+
+The implementation step must add focused failures at least at:
+
+1. crash before provider call,
+2. provider call succeeds but receipt write is lost,
+3. receipt exists but `dispatched` transition is lost,
+4. `dispatched` exists but claim response is lost,
+5. claim persists then Runtime/MCP restarts,
+6. disposition persists then release fails,
+7. release persists then next-round creation fails,
+8. successor handoff crashes between predecessor/successor writes,
+9. repeated-state block with unchanged fingerprint,
+10. repeated-state block with changed fingerprint,
+11. provider failures reach fuse,
+12. verified provider/environment recovery for that exact fuse,
+13. stale/mismatched provider recovery evidence,
+14. outcome-unknown positive reconciliation,
+15. outcome-unknown proven-not-executed reconciliation,
+16. hard round-budget exhaustion,
+17. waiting scheduled occurrence with explicit occurrence identity,
+18. waiting_for_user without explicit user/handoff resolution,
+19. goal_complete/handed_off relaunch attempt,
+20. failed/cancelled Work terminal cleanup with and without active claim.
+
+Assertions must cover status, lifecycleStage, `roundCount`, `repeatedStateCount`, provider-failure epoch/history, `authorityId`, `claimGeneration`, provider dispatch/effect receipt identity, duplicate-effect count and durable revision/CAS behavior.
+
+## ControllerRound validation Supervisor Work acceptance sequence
+
+Here, “Supervisor” is the historical name of the existing long-lived **ControllerRound validation Work lineage**. It is not the cross-assistant-turn Workflow Supervisor defined by `20260916-workflow-supervisor-authority.md` and owns no outer WorkflowRun scheduling authority.
+
+Production validation uses that existing ControllerRound validation Work lineage. It may not manufacture a new Work/Requirement/relay to make the test pass.
+
+1. Build and activate one exact candidate Runtime containing the transition policy.
+2. Verify required provider/plugin capability on that installed Runtime before relay mutation.
+3. Re-read the exact existing ControllerRound validation Supervisor Work, Requirement, relay scope, authority, blocked class, budgets and current record revision.
+4. Submit verified provider/environment recovery evidence for the existing `consecutive_failures` block.
+5. Prove the same semantic round is rearmed without changing `roundCount`, `repeatedStateCount`, relay scope or per-round authority, and without erasing historical failure evidence.
+6. Prove provider dispatch occurs at most once and exact Controller claim succeeds.
+7. Let ChatGPT submit its semantic disposition.
+8. Prove at least one `continue_immediately -> pending_release -> controller release -> successor/next dispatch` sequence completes automatically without a human sending `继续`.
+9. Verify round authority rotates only at the true new-round boundary and no duplicate disposition/provider effect exists.
+10. Only after this sequence may the Automatic Progression acceptance step be considered complete.
+
+## Required implementation shape
+
+The next Plan step must converge existing mutation helpers onto one policy rather than wrapping the old special cases with another layer of exceptions. A suitable shape is:
+
+```ts
+type ControllerRoundEvent = ... // provider-neutral typed events
+type ControllerRoundTransitionDecision = Accept | NoOp | Reject | NeedsEvidence
+
+function decideControllerRoundTransition(
+  current: ControllerRoundAggregateSnapshot,
+  event: ControllerRoundEvent,
+): ControllerRoundTransitionDecision
+```
+
+Existing public helpers may remain as compatibility facades during migration, but they become thin event builders around the canonical policy. Scheduler, Launcher, MCP and provider adapters must contain no independent status/blocker transition tables after convergence.
+
+## Explicit non-solutions
+
+Do not:
+
+- add a one-off `consecutive_failures` rearm branch,
+- raise `maxFailures`/`maxRounds`,
+- clear durable counters or edit SQLite by hand,
+- use elapsed time as provider recovery proof,
+- treat Browser/ChatGPT registration as Kernel-specific lifecycle logic,
+- infer successful dispatch from a transport session id,
+- reopen semantic terminal states from stalled recovery,
+- create another ControllerRound validation Supervisor Work/relay to avoid the blocked lineage, or
+- keep parallel mutation tables in Scheduler/Launcher/MCP while claiming a central policy exists.
+
+This ADR is the acceptance authority for the r3 ControllerRound recovery-convergence implementation.
+
+## Explicit migration map from current implementation
+
+Current `controller-round-store.ts` exposes ten lifecycle mutators and contains fifteen direct ControllerRound persistence write sites. Migration is complete only when these entry points no longer contain independent lifecycle decision tables.
+
+| Current helper | Compatibility role after convergence | Policy event / responsibility |
+| --- | --- | --- |
+| `bindControllerRoundSuccessorWork` | thin facade | submit `successor_bound`; policy validates predecessor/successor lineage and atomic handoff eligibility |
+| `submitControllerRoundDisposition` | thin facade | submit `semantic_disposition_submitted`; all semantic-close budget/status decisions move to policy |
+| `beginInitialControllerRoundDispatch` | thin facade | submit `occurrence_requested`; policy decides whether occurrence is genuinely new and legal |
+| `beginControllerRoundRelayAfterRelease` | thin facade | submit `controller_release_observed`; policy chooses same-lineage next-round transition and authority rotation |
+| `reconcileControllerRoundAfterAbandonedRelease` | thin facade | submit released-without-disposition evidence; policy chooses mechanical failure/retirement only |
+| `reconcileControllerRoundAfterTerminalWork` | thin facade | submit `terminal_work_observed`; policy retires failed/cancelled Work relay only |
+| `finishControllerRoundRelayDispatch` | thin facade | submit one of dispatch succeeded/failed/outcome-unknown/user-action events; no local status ternary remains |
+| `acknowledgeControllerRoundClaim` | thin facade | submit `controller_claim_observed`; repeated-state/outcome-unknown recovery must not live in claim code |
+| `recoverControllerRoundRelayAuthority` | thin facade | submit `authority_recovery_requested`; policy validates state and emits capability rekey only |
+| `claimStalledControllerRoundRelays` | scanner/orchestrator only | identify candidates and submit `stalled_round_observed` / evidence events; it must not write recovered relay states itself |
+
+### Persistence convergence
+
+The current store has fifteen `writeControlPlaneRecord*` call sites associated with these lifecycle paths. The target is not necessarily one physical SQL statement, because successor handoff legitimately needs a two-record transaction, but there must be **one logical apply authority**:
+
+- ordinary single-relay transitions go through one `applyControllerRoundTransitionDecision(...)` persistence executor;
+- predecessor/successor handoff goes through one atomic `applyControllerRoundHandoffDecision(...)` executor produced by the same policy;
+- no public mutation facade calls `writeControlPlaneRecord*` after making its own status/budget/blocker decision.
+
+### Outer-layer convergence
+
+Current outer composition demonstrates why this is necessary:
+
+- `chatgpt-round-continuation.ts` currently composes initial dispatch, dispatch finish, claim acknowledgement, disposition and release/next-round helpers; after migration it orchestrates provider effects around policy events only.
+- Scheduler maintenance currently claims stalled relays and directly records dispatch success/failure; after migration it scans/authorizes wake, performs the provider effect intent, then submits the resulting receipt event.
+- MCP runtime tools currently invoke claim, disposition, release, launch and dispatch settlement helpers directly; after migration MCP is a compatibility/event translation surface only.
+- ChatGPT/Browser provider adapters remain responsible for provider-specific observation and effect execution, never lifecycle status selection.
+
+### Completion assertion
+
+A static regression should fail if Scheduler, Launcher, MCP compatibility or provider adapters acquire a new direct ControllerRound status/blocker mutation table or write ControllerRound relay records outside the canonical apply executor. This is an architecture boundary, not a code-style preference.
+
+
+## Workflow Supervisor boundary clarification
+
+ControllerRound transition authority remains lower-layer execution authority. Any provider-observed `controller_turn_settled` event in this ADR is a mechanical liveness fallback for an exact claimed round. It must not be reused as the outer Workflow Supervisor's assistant-message commit event or next-turn scheduling authority. The latter requires the completed `FORGE_WORKFLOW_SUPERVISOR_V1` block, exact END marker, conversation identity and causal submission-effect evidence defined in [`20260916-workflow-supervisor-authority.md`](20260916-workflow-supervisor-authority.md).
+
+## 2026-09-16 amendment: settled Controller turns cannot silently strand nonterminal Work
+
+User-free continuation is a P0 lifecycle invariant. A provider may submit a typed `controller_turn_settled` fact only after the exact assistant turn is observably complete; prompt submission itself is not completion evidence. The provider supplies bounded completion evidence, never a disposition.
+
+The canonical ControllerRound transition policy decides the consequence. If the current round is still `claimed`, its Work is nonterminal, and no explicit stop state exists, the policy records the existing `continue_immediately -> pending_release` lifecycle while preserving round/repeated/failure budgets. If an active control-plane Handoff proves a user decision is required, the same policy closes as `wait_for_user`. If `wait`, `wait_for_user`, `goal_complete`, `blocked`, `failed`, or another already-closed state won the race first, settled-turn replay is idempotent and changes nothing. Terminal Work is retired through the existing terminal-work transition.
+
+This amendment does not create a second Scheduler or semantic Controller. It changes the default for one previously ambiguous state only: **a completed Controller turn may not leave a still-running Work silently claimed merely because the model failed to call the explicit continue helper.** The provider-specific observation and same-conversation dispatch mechanics remain adapter responsibilities, while all durable lifecycle mutation continues through this provider-neutral policy.

package/docs/architecture/decisions/20260907-maintenance-diagnosis-bounded-read.md

@@ -0,0 +1,39 @@
+# Runtime maintenance diagnosis uses bounded read-side inventory
+
+Status: Accepted and implemented on 2026-09-07.
+
+## Problem
+
+Runtime maintenance diagnosis had three multiplicative costs on repositories with long-lived Controller history:
+
+- stale EditSession discovery called `reconcileEditSession` for every open-like candidate, which hashes tracked after-images, runs Git dirty-path inspection, and may persist reconciliation metadata;
+- every stale Work/EditSession independently reloaded active Plans, Schedules, Controller ownership and up to 500 Process history records;
+- stale Work repository source inspection ran before the visible `maxCandidates` bound, so expensive Git status/revision/containment checks could exceed the advertised candidate budget.
+
+On the real Forge Controller Home with 637 WorkContracts and 388 EditSessions, the observed maintenance diagnosis path took roughly 25–35 seconds.
+
+## Decision
+
+Maintenance status discovery is inventory, not repair:
+
+1. Resolve the existing repository runtime-storage binding first, then build one bounded authority snapshot for the status pass.
+2. Reuse Work, live Controller session, active Plan, Requirement, Schedule and Process ownership facts across all candidates in that pass.
+3. Read active Process authority from Process Runtime's recoverable index instead of enumerating terminal Process history.
+4. EditSession discovery reads summary/ownership metadata only. Workspace hashing, Git dirty checks, supersession and finalization occur only in explicit maintenance for a selected candidate.
+5. Sort and bound stale Work candidates before repository source Git inspection.
+6. Destructive stale-Work maintenance re-reads current authority at its mutation boundary; the status snapshot never becomes mutation authority.
+
+The snapshot is a derived in-memory view for one diagnosis call. It is not persisted and is not a second lifecycle authority.
+
+## Verification
+
+After implementation on the same real Controller data set:
+
+- `buildRuntimeMaintenanceStatus`: 563.8 ms for 200 returned candidates;
+- legacy `listProcessRecords(..., 500)`: 729.82 ms for 500 historical records;
+- `listRecoverableProcessRecords`: 2.82 ms for the active/recoverable index in the same repository;
+- targeted maintenance semantic regressions: 5 passed, 0 failed;
+- Direct Edit / EditSession continuity consumers: 28 passed, 0 failed;
+- `package:check:type`: passed.
+
+The 25–35 second diagnosis regression is therefore removed without lowering lifecycle gates or hiding candidates.

package/docs/architecture/decisions/20260916-workflow-supervisor-authority.md

@@ -0,0 +1,249 @@
+# Workflow Supervisor authority above the ChatGPT-turn / Forge execution boundary
+
+Status: **Accepted architecture contract; production Runtime integration implemented, live unattended canary proof remains pending.**
+
+Date: 2026-09-16
+
+## Context
+
+Forge already has durable authorities for repository Work, Controller ownership, ControllerRound transition, Scheduler occurrences, provider recovery, verification evidence, Outcome and Experience. Those authorities are inside the Forge execution/control plane. They can record that more semantic work is required and can prepare or dispatch a lower-layer continuation while the controlling call stack is alive.
+
+That does not solve the outer lifecycle gap for a ChatGPT Web controller. A typical development loop is:
+
+```text
+ChatGPT assistant turn
+  -> calls Forge
+  -> Forge Work / ControllerRound executes
+  -> Forge returns evidence
+  -> ChatGPT reasons over the evidence
+  -> assistant response commits
+  -> original assistant/MCP call stack ends
+  X  no durable authority outside that call stack owns starting the next assistant turn
+```
+
+A ControllerRound continuation record is therefore not, by itself, an assistant-turn scheduler. Likewise, an MCP session, Browser session, Work lease, Schedule occurrence, or conversation binding is not the authority to decide and durably execute the next outer ChatGPT turn.
+
+The missing authority is a **Workflow Supervisor** above the ChatGPT-turn / Forge execution boundary. It is part of Forge's general autonomous-workflow architecture, but it is not another Work, ControllerRound, Scheduler, or MCP lifecycle owner.
+
+## Decision
+
+Introduce one logical `WorkflowRun` supervised by one durable **Workflow Supervisor**. The Supervisor owns only cross-turn continuation of the original Goal. It delegates each semantic turn to ChatGPT and delegates repository execution to Forge.
+
+```text
+Original Goal / logical WorkflowRun
+              |
+              v
+       Workflow Supervisor
+       durable single writer
+              |
+              v
+        ChatGPT assistant turn
+              |
+              v
+       Forge Controller / Work
+              |
+              v
+       repository execution
+```
+
+V1 is a **TypeScript/Bun Supervisor authority co-hosted inside the Canonical Forge Runtime process**. It has its own dedicated Supervisor persistence and Unix socket under the exact configured Controller Home, and only the Supervisor composition opens/writes that database. Authority separation is therefore defined by persistence/protocol/single-writer boundaries, not by inventing a second OS daemon. The existing Canonical Runtime launchd/systemd/portable lifecycle starts and stops Supervisor with the rest of the Runtime. Go or another runtime is reconsidered only if later packaging, restart-recovery or operability evidence proves a material benefit without changing this protocol or authority contract. ChatGPT Web is the first execution target, not the definition of the Supervisor.
+
+### Authority matrix
+
+| Concern | Authority | What it may decide | What it must not decide |
+| --- | --- | --- | --- |
+| 1. Forge Work completion | Forge Work finalization / completion receipt | Whether one Work has satisfied its declared Work contract and delivery gates | Whether the original multi-turn Goal is globally DONE |
+| 2. ControllerRound continuation | Canonical provider-neutral ControllerRound transition policy | Lower-layer round transitions and fenced continuation obligations | Whether a new outer assistant turn should be scheduled after the caller has disappeared |
+| 3. MCP / execution-session recovery | MCP/session/Controller ownership recovery authorities | Rebind transport, recover session/claim, preserve exact lower-layer authority | Goal semantics, outer turn scheduling, or user escalation |
+| 4. ChatGPT assistant-turn commit | Workflow Supervisor completion contract, based on a complete final assistant message | Whether one supervised assistant turn committed a valid completion proposal | Goal acceptance merely because the page stopped generating |
+| 5. Next assistant-turn startup | Workflow Supervisor | Reserve/reconcile and submit one next turn to the exact execution target | Forge Work internals or repository mutation |
+| 6. Long-lived Goal completion | Requirement/Goal semantics plus the WorkflowRun `completionContract` | Validate that a model `DONE` proposal actually satisfies the original Goal and required gates | Treat one Work, patch, test, round or model assertion as sufficient by itself |
+| 7. Stagnation / no-progress detection | Workflow Supervisor using execution-quality / evidence observations | Detect repeated checkpoints, no new evidence, repeated failure/verification/recovery patterns | Rewrite lower-layer verification gates or silently terminate the Goal |
+| 8. Workflow strategy adaptation | Semantic Controller, guided by Supervisor correction policy and Experience/evaluation evidence | Choose a different execution strategy for the same Goal; later evaluate cross-Work candidates | Create a second execution state machine or promote policy without evidence |
+
+The separation is deliberate. A lower layer may report facts upward, but it does not acquire the upper layer's lifecycle authority by exposing more states.
+
+## Logical WorkflowRun contract
+
+The generic upper-layer contract is intentionally small:
+
+```text
+WorkflowRun
+  objective
+  executionTarget
+  completionContract
+  continuationPolicy
+  userBlockerPolicy
+```
+
+`executionTarget` is an adapter identity. Initial support is ChatGPT Web; future targets may include ChatGPT Work, Forge local, Forge Cloud, browser/desktop automation, or another agent runtime.
+
+`completionContract` is a read/validation contract for the original Goal and required evidence. For Forge-backed development Goals it may consult Requirement/Plan/Work receipts and semantic acceptance, but it does not mutate those lower authorities.
+
+`continuationPolicy` defines the fixed enrollment/continuation template, exact target identity, recovery bounds and correction policy. It never accepts model-generated executable `next_prompt` content.
+
+`userBlockerPolicy` validates whether a `NEEDS_USER` proposal is a genuine user-only action, authorization, consent/legal decision, or equivalent blocker with no autonomous recovery path.
+
+### Namespace boundary
+
+Forge already persists `workflow_run` for the declarative Workflow asset interpreter. That record is a checkpoint for executing a versioned Workflow asset; it is not the long-lived autonomous development Goal described here.
+
+V1 Supervisor storage therefore uses a **dedicated Supervisor persistence authority/namespace**. It must not alias or reinterpret the existing declarative `workflow_run` record. Any future convergence requires an explicit migration and authority contract rather than a same-name shortcut.
+
+## Assistant completion proposal protocol
+
+Every supervised ChatGPT turn ends with exactly one machine-readable terminal block at the end of the assistant response:
+
+```text
+<<<FORGE_WORKFLOW_SUPERVISOR_V1>>>
+{
+  "action": "CONTINUE",
+  "conversation_id": "<exact ChatGPT conversation id>",
+  "task_id": "<stable conversation-scoped Supervisor task id>",
+  "supervisor_state": "running",
+  "active_scope": "requirement:<id>",
+  "source_effect_id": "fx_...",
+  "checkpoint": "...",
+  "reason": "...",
+  "evidence": ["..."]
+}
+<<<END_FORGE_WORKFLOW_SUPERVISOR_V1>>>
+```
+
+`action` is exactly one of:
+
+- `CONTINUE`: the original Goal is not complete and autonomous work remains.
+- `DONE`: a terminal **proposal** that requires `completionContract` validation.
+- `NEEDS_USER`: a blocker **proposal** that requires `userBlockerPolicy` validation.
+
+Each newly rendered Supervisor prompt also requires exactly one concise user-visible status line before the control block, derived only from that same action:
+
+- `CONTINUE` → `🔄 仍在执行，无需你操作`
+- `NEEDS_USER` → `⏸ 需要你处理，暂时不要关闭会话`
+- `DONE` → `✅ 已完成，可以关闭此会话`
+
+This is presentation, not lifecycle authority or persisted state. In particular, completion wording is reserved for `DONE`; a model cannot make work complete by printing it, and the existing `completionContract` validation remains authoritative.
+
+The exact `<<<END_FORGE_WORKFLOW_SUPERVISOR_V1>>>` marker is required before the Supervisor accepts the turn as committed. Prompt delivery, `Stop generating`, spinner/loading state, button state, DOM stability, a text-stability timer, Work completion, ControllerRound closure, or transport disconnection are not assistant-turn commit authority.
+
+Every newly rendered Supervisor enrollment or continuation message also carries a machine-readable marker containing its daemon-minted `submission_effect_id` and instructs the assistant to echo exact `conversation_id`, stable `task_id`, `supervisor_state`, and `active_scope` together with `source_effect_id`. `supervisor_state` is redundant by design (`CONTINUE -> running`, `DONE -> done`, `NEEDS_USER -> needs_user`) so each response is independently classifiable. `active_scope` identifies the current durable lower-layer relay authority, normally `requirement:<id>` or `goal:<id>`; it never replaces that authority. The assistant may only echo these immutable/observed identities; it does not mint, rewrite or interpret them as executable prompt authority. A completion is commit-eligible only when `source_effect_id` matches the exact applied outbound effect for the exact task and conversation and the echoed identities match the registered task/scope. Already-reserved pre-upgrade effects remain parse-compatible so a Runtime upgrade does not strand an unknown remote effect.
+
+The Supervisor never executes arbitrary model-provided `next_prompt`. Enrollment, normal continuation, recovery correction and stagnation correction use Supervisor-owned fixed templates. The normal same-conversation continuation is intentionally context-light. It does not repeat the original objective, checkpoint payload, Requirement/Plan/AGENTS text, or lower-layer authority context already present in the conversation. Its semantic instruction is bounded to one coherent safe work wave:
+
+```text
+Continue using the context already present in this same conversation.
+Complete one coherent safe work wave and persist/checkpoint durable progress.
+Use CONTINUE while autonomous work remains; use DONE only after the completion contract is satisfied; use NEEDS_USER only for a genuine user-only blocker.
+Echo the immutable effect/task/conversation/scope identities and end with the FORGE_WORKFLOW_SUPERVISOR_V1 control block.
+```
+
+Enrollment, recovery and correction prompts may include bounded original-objective, checkpoint, validation-result or lower-layer recovery context because those turns are specifically reconstructing durable state. Implementations may localize the wording, but not delegate prompt-chain control back to the assistant.
+
+## DONE and NEEDS_USER validation
+
+A model control block is evidence, not terminal authority.
+
+For `DONE`, the Supervisor validates the configured `completionContract`. A Forge-backed development run must preserve the distinction between Requirement acceptance, Plan/Work delivery, verification/review evidence and outer Goal completion. Missing required evidence causes the `DONE` proposal to be rejected and converted into continuation/correction evidence; it does not lower the gate.
+
+For `NEEDS_USER`, the Supervisor validates `userBlockerPolicy`. Test failures, tool failures, MCP errors, session replacement, provider recovery, implementation failures and ordinary Forge recovery are autonomous failure/recovery facts, not user blockers. A false `NEEDS_USER` proposal is rejected and routed to recovery/correction. Only a validated user-only blocker makes the WorkflowRun quiescent for user action.
+
+## Single writer and event journal
+
+The long-lived Supervisor authority hosted by Canonical Runtime is the **only durable writer** for Supervisor task/run state. Chrome Extension, Native Messaging transport, Forge execution, and lower schedulers submit observations or execute authorized effects; they never independently mutate Supervisor state.
+
+V1 owns a dedicated `supervisor.sqlite` authority under the Forge user-data root instead of reusing `control-plane.sqlite`, generic `control_plane_records`, the declarative `workflow_run` namespace, or a collection of mutable status JSON files. It reuses only the runtime-neutral SQLite mechanics already proven by Forge: Bun/Node driver adaptation, WAL, foreign keys, bounded busy waiting, lifecycle integrity checks, statement finalization and short `BEGIN IMMEDIATE` write transactions.
+
+The core schema keeps the exactly-once invariants relational rather than burying them in opaque JSON payloads. It has explicit task, append-oriented event and outbound-effect facts (`tasks`, `events`, `effects` or schema-equivalent names), with database-level uniqueness for committed completion fingerprints and for the one successor effect derived from a committed completion. Supervisor task identity is stable per exact conversation; Requirement and Work changes advance `active_scope` rather than minting a second outer-turn identity for the same conversation. Bounded discovered-conversation metadata may be persisted in the same Supervisor database so Runtime/browser restarts do not erase project inventory, but discovery rows are observations only and cannot reserve effects or terminalize a task by themselves. Durable journal facts include at least:
+
+- enrollment / turn submission intent;
+- assistant turn committed;
+- continuation effect reserved;
+- external effect observed `applied`, `not_applied`, or `unknown`;
+- completion/blocker proposal validation;
+- recovery/correction decisions;
+- verified terminalization.
+
+Current state is derived from those durable facts. The Canonical Forge Runtime owns the one long-lived process lifecycle and starts the Supervisor server in-process; Supervisor still owns its separate SQLite and Unix-JSONL socket authority. The Chrome Native Messaging host is only a bounded stdin/stdout-to-socket relay; it does not open `supervisor.sqlite`, make continuation/terminal decisions, or become a second writer. Relay processes may reconnect or respawn without changing WorkflowRun identity.
+
+## Exactly-once continuation and external-effect reconciliation
+
+Each supervised outbound turn is assigned a daemon-minted `submission_effect_id`, and the exact fixed outbound message embeds that id in its machine-readable marker. The completion of that turn is causally tied to that applied effect and must echo it as `source_effect_id`. When a stable provider message id is unavailable, the completion fingerprint is derived from:
+
+```text
+task identity
++ exact conversation identity
++ source_effect_id
++ canonical full assistant-response hash
++ control-block hash
+```
+
+This prevents two different turns with identical assistant text from colliding.
+
+For a valid `CONTINUE`, one short SQLite transaction consumes/idempotently records the committed assistant completion and reserves the one successor `submission_effect_id`. Database uniqueness makes duplicate observations converge on the same logical successor effect. The transaction does not claim that the external ChatGPT send committed.
+
+`DONE` and `NEEDS_USER` proposals have a different boundary because their contracts may read Forge or other authoritative evidence. The daemon first journals the proposal idempotently, releases the SQLite write transaction, performs the required read-only completion/blocker validation, then uses another short transaction either to record validated terminalization or to reserve a correction/continuation effect. No SQLite write lock is held across Forge, browser or other external evidence reads.
+
+External send outcome uses the same three-way rule as Forge's non-idempotent effect reconciliation:
+
+- `applied`: the exact effect marker/fixed outbound message is observed in the exact conversation; acknowledge it and never resend.
+- `not_applied`: affirmative preserved-baseline proof establishes that the exact source completion is still the latest committed assistant turn, the latest user message is still the previously applied source/baseline message, and the target `submission_effect_id` marker is absent; only then may retry reuse the same reserved effect identity.
+- `unknown`: any conflicting, newer, partial or otherwise insufficient observation stays reconciliation-only; do not blindly resend.
+
+The crash windows before reservation, after reservation/before send, after send/before acknowledgement, and after acknowledgement must all converge through this journal plus remote observation. Daemon restart, extension reload, Chrome restart, tab close/reopen/discard/freeze, Native Messaging reconnect and Forge/MCP session replacement never create a new original Goal or a second continuation for the same committed completion.
+
+## ChatGPT Web adapter boundary
+
+The Chrome Extension is a discovery/assistant-observation adapter, not a state authority or outbound sender. Native macOS Browser transport is the single sender: it uses trusted input, confirms the composer contains the exact fixed prompt before it clicks Send, and waits for the exact committed user message before recording the effect outcome. It may:
+
+- locate or open only an allowlisted exact conversation id/URL;
+- obtain repository-derived ChatGPT Project scopes from the Supervisor and scan visible project links for canonical `/c/<id>` conversation identities;
+- publish bounded project/conversation discovery observations; the Supervisor alone decides whether an unbound discovered conversation receives one enrollment effect;
+- read the final complete assistant response, its echoed identity/state fields and `source_effect_id`, and forward bounded evidence;
+- rediscover a closed/discarded tab without changing durable task identity.
+
+It must not select durable tasks by mutable title, open the Supervisor database, decide `CONTINUE/DONE/NEEDS_USER`, invent prompts, weaken Forge gates, or depend on private ChatGPT APIs. A repository/project title is only a bounded discovery selector; exact conversation URL/id becomes the stable execution target before any enrollment effect exists. Transient generation UI may help avoid pointless reads but is never commit evidence.
+
+Existing conversations require an explicit enrollment handshake. A conversation may be explicitly bound by a current Work or discovered inside the repository-derived ChatGPT Project scope. In either case the Supervisor persists exact conversation identity and one conversation-stable task, then reserves one fixed enrollment effect. A discovered conversation that has not yet recovered a durable Requirement must use a bootstrap enrollment turn that recovers the original task from conversation history plus Forge durable state and emits the exact `active_scope` before repository mutation. Repeated project scans never reserve a second bootstrap for an already enrolled conversation. A pre-enrollment response without the END marker is never retroactively imported as a committed supervised turn.
+
+## Relationship to existing Forge continuation
+
+The cross-turn dependency described in this section is superseded by [Supervisor turn authority](20261001-supervisor-turn-authority.md): ControllerRound remains initial admission and direct non-ChatGPT provider-effect authority, while enrolled ChatGPT turns use only the Supervisor causal effect ledger. Exact-conversation Supervisor lookup occurs before lower ControllerRound readiness, so an already-enrolled conversation cannot be stranded by a retired lower round. Every nonterminal Supervisor task must retain one mechanically derivable causal obligation; Runtime restart repairs missing enrollment/successor/terminal settlement from the existing ledger rather than adding lifecycle state. Schedule occurrences hand exact trigger identity into ControllerRound; Scheduler-owned continuation-dispatch persistence has been removed. ControllerRound is not the authority that reactivates ChatGPT after the outer assistant call stack is gone, and it is not proof that the long-lived WorkflowRun progressed or completed.
+
+The existing Scheduler remains only an execution/occurrence scheduler. Once an exact Requirement-backed ChatGPT conversation binding exists, lower Scheduler/maintenance/direct-continuation paths must not submit the next outer ChatGPT turn; Workflow Supervisor is the single outer writer.
+
+Standalone Supervisor lifecycle and release-bound live proof are reachable from the six-tool ChatGPT facade as the `controller.workflow_supervisor` core capability on `capability_execute`. Its `start/list/get/stop/proof` actions route into the same `WorkflowSupervisorControlPlane` adapter and dedicated Supervisor persistence. Newly generated autonomous turns carry typed automation metadata on their real Forge calls; the old receipt-only `rh_work repair` carrier is migration-only for already-issued prompts. The retained internal/compatibility `supervisor_task` definition is not a second facade or authority. ReleaseSession keeps Candidate B's isolated Runtime canaries separate from the real external multi-turn proof: after cutover the session remains `soaking` until the exact active release has durable `CONTINUE → CONTINUE → DONE` proof spanning a Runtime reconnect; only then may it become known-good.
+
+No Supervisor state is added to Work, ControllerRound, relay, MCP session or existing declarative Workflow asset records in V1. Integration is through typed observations/read-only completion evidence and authorized execution effects.
+
+## Stagnation and strategy evolution
+
+P0 is cross-turn liveness and correctness: durable Supervisor, exactly-once/restart recovery and real unattended Avela development canaries.
+
+After P0 proof, P1 may consume existing execution-quality and Experience evidence to detect repeated checkpoint/evidence/failure/verification/recovery patterns. First confirmed stagnation injects one fixed root-cause correction while keeping the same original Goal and gates. It does not immediately escalate to the user.
+
+Only after P0/P1 evidence should P2 perform cross-Work strategy comparison, policy candidate trials, evaluation and bounded promotion. Existing Experience/evaluation authorities are reused rather than replaced.
+
+## First P0 canary
+
+The current P0 canary also exercises the Forge ChatGPT Project itself: the adapter must discover the repository-matched project conversations by exact `/c/<id>` identity, persist the inventory across Runtime restart, enroll each unbound nonterminal conversation at most once, and allow each conversation to recover its own durable `active_scope`. The historical Avela three-conversation canary remains valid evidence for exact-conversation isolation; promotion/excluded conversations must remain outside any configured discovery scope.
+
+P0 is not complete when Forge can send one automatic `continue` or merely list browser tabs. It is complete only after a real project/conversation canary demonstrates multi-turn unattended progress with no user continuation messages, correct conversation isolation, no duplicate bootstrap/continuation, restart recovery, technical-failure recovery, MCP-session replacement, validated `DONE`, and validated `NEEDS_USER`, without lowering Forge verification/review/authorization gates.
+
+## Consequences
+
+- Forge gains one missing upper lifecycle authority instead of stretching lower state machines upward.
+- The external protocol remains deliberately smaller than Forge's internal lifecycles.
+- Exactly-once is treated as an external-effect reconciliation problem, not as a SQLite uniqueness problem pretending the network does not exist.
+- ChatGPT remains the semantic reasoner, but model assertions do not bypass durable Goal or blocker evidence.
+- The system can later add execution targets without making Chrome Extension behavior part of the kernel.
+
+
+## Restart-safe remote effect generations
+
+The remote ChatGPT send boundary is recovered from the Supervisor journal, never from browser-local shadow state. Each reserved effect keeps one stable `submission_effect_id`; retries do **not** mint a replacement effect. Instead, every authorized send attempt appends an `effect_dispatch_started` event carrying a monotonically increasing dispatch generation. Generation 1 is allowed before any prior dispatch. A later generation is allowed only when a canonical `effect_not_applied` event was committed after the previous dispatch. `effect_unknown` never authorizes a resend.
+
+`not_applied` is a daemon-validated fact, not a caller assertion. The generic observation RPC may record only `applied` or `unknown`. The browser reconciliation path may commit `effect_not_applied` only when the exact conversation remains on the preserved dispatch baseline, the target effect marker is absent, and, for continuation/correction effects, the latest complete assistant response hashes to the exact source completion while the latest user message is the exact applied source-effect prompt. Any drift, partial response, conflicting message, missing baseline, or other ambiguity is recorded as `unknown` and remains reconciliation-only.
+
+Raw ChatGPT page bodies are ephemeral verifier input. The Supervisor persists bounded hashes and a fixed allowlist of small browser evidence fields, not arbitrary `latest_user_text` or `latest_assistant_response` payloads. This keeps restart evidence durable without turning the event journal into a conversation mirror.
+
+Daemon restart, Native Messaging respawn, extension reload, Chrome tab reopen/discard recovery, and Forge/MCP session replacement therefore reconstruct the same task/effect chain from `supervisor.sqlite`. The relay and extension may disappear and return freely; neither owns retry generations, terminal state, or durable recovery policy. Verified `DONE` and `NEEDS_USER` remain quiescent because terminal tasks expose no browser continuation command.