@moretea-labs/forge 1.8.0 → 1.8.2

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

@@ -0,0 +1,342 @@
+# 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 Supervisor Effect prompt carries immutable task identity, outcome objective and terminal receipt; it is not a per-turn checklist, execution-time budget, or reason to perform a status probe before work. Ordinary CONTINUE turns should resume substantive work for as long as safe, useful actions remain. A terminal C receipt is a protocol acknowledgment, not evidence of productive progress; observed tool calls and deliverables are separate evidence. JSON metadata and Project instructions do not grant a missing ChatGPT App capability.
+
+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 canonical Supervisor ledger proves a causal CONTINUE → CONTINUE → DONE on the exact active release: one dispatch and applied receipt per source effect, terminal_done after the third assistant_completion, and at least two Runtime incarnations. A bounded disposable acceptance task supplies this proof; long-running production Work need not terminate. Historical receipts before the active-release boundary never qualify. 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.
+
+An operator-STOPPED bootstrap may have written an entire machine-authored effect to a
+Project composer without clicking Send. A subsequent bootstrap for that **same Project**
+may replace the residue only if the canonical Supervisor ledger proves the prior task is
+STOPPED, the prior effect has zero dispatch generations, and its last pre-Send failure
+durably attests that exact, single visible editor (classification=current_effect,
+send_clicked=false, matching full text length and SHA-256 fingerprint). The permitted editor payload must either match the canonical
+immutable effect bytes exactly or match that persisted pre-Send observation's
+full length and fingerprint exactly. This dual exact check handles a corrected
+ProseMirror reader that no longer synthesizes layout newlines inside auto-linked
+URLs, without ignoring any other whitespace or allowing arbitrary human edits.
+New observations reconstruct text from the direct ProseMirror paragraphs' text
+nodes rather than CSS-rendered layout text. The sole Chrome extension
+rechecks the stopped effect marker and a fresh exact editor fingerprint immediately
+before its prepare-only replacement. If ChatGPT hydrates this exact STOPPED-owned draft
+after the first bootstrap snapshot, the same pinned Computer target may obtain
+one fresh read-only observation following a `composer_not_empty` prepare refusal
+and attempt exactly one guarded second **prepare**, still before any Send
+generation. Unknown mutation, foreign text or missing precise evidence remain
+blocked; no task, effect or provider is duplicated. This grants no replay or
+new provider authority. Ambiguous/applied/possibly-sent effects, user or foreign drafts,
+and a generating assistant always fail closed. A successful prepare still requires the
+normal exact-effect Send and completion checks; never count typing as delivery.
+
+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`. The provider-facing continuation is intentionally close to a
+human "continue working" request: the model reads the previous result and
+live project evidence, chooses useful actions and keeps executing while meaningful
+authorized work remains. It does not prescribe an existing Work, checkout,
+sequence or phase as a mandatory path, nor treat one successful check or tool
+call as completion. Parallel user and autonomous efforts may share an outcome
+without sharing a Work; models assess ownership and live source evidence,
+while Forge enforces mechanical writer/resource boundaries at execution. The
+prompt discourages repeated status-only rounds and requests actual results and
+remaining gaps. This is model guidance, not a semantic scoring gate, new state
+store or second Work/progress authority. An `automation:*` or `receipt:*` causal checkpoint
+is retained in the durable completion ledger but omitted from model-facing
+`continuity.summary`: it is a transport reference, not an engineering handoff.
+Meaningful non-receipt checkpoints and recovery/correction reasons remain
+bounded advisory context. No elapsed-time quota, forced operation count,
+semantic scoring gate, extra state store, or new lifecycle authority is added.
+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.
+
+## Chrome attachment continuity (20261015)
+
+Computer owns browser/profile selection and tab attachments. The extension keeps
+one random provider instance id in `chrome.storage.local`, scoped by Chrome to
+that extension/profile. Worker suspension, extension reload and browser restart
+therefore preserve profile identity. The id is removed on extension uninstall;
+there is no task/effect state, credential, URL, or conversation content in this
+cache. The existing Computer Controller authority remains the only durable
+attachment writer. The extension owns only this constant-size transport identity,
+requires the standard storage permission and grants no new host access. Discovery
+and target-command heartbeats derive their source identity from this same
+persisted profile id; a worker restart must not orphan discovery or change
+the physical-tab binding. See the
+[Chrome storage contract](https://developer.chrome.com/docs/extensions/reference/api/storage#storage_areas).
+
+The native Browser primitive treats Runtime's process lookup as liveness
+only. Desktop Operator exclusively establishes exact Chrome GUI PID and Tab ID
+authority through ScriptingBridge and revalidates bundle/executable identity.
+Independent headless Chrome roots may coexist; zero or multiple GUI roots fail
+closed in Desktop Operator before Apple Events. Runtime must not re-implement
+process selection by counting every pgrep match or fall back to another
+provider.
+
+A missing pinned profile stays unavailable even when another profile is the sole
+live provider. Within the same profile, Chrome tab id takes precedence over
+window id so moving a tab between windows preserves attachment. An existing pin
+at another conversation URL is identity drift. Only a positive Chrome tab-missing
+result permits recovery through complete exact-conversation inventory: reuse the
+unique existing conversation tab, or reopen the persisted conversation URL when
+absent. This preserves the existing disposable-resource restoration rule without
+creating a new ChatGPT conversation. Ambiguous matches and unreadable inventory
+remain unresolved; they do not authorize profile replacement or another tab.
+Bootstrap recovery still requires the same live provider's positive missing-tab
+proof and the existing Computer binding CAS.
+
+Tab creation and conversation hydration are separate outcomes. An ensure failure
+may return its exact physical attachment alongside the error. The existing
+Computer surface lease stores that attachment before reporting failure; page
+readiness and Send remain unavailable. A subsequent worker uses that binding
+instead of creating another Project tab. Claimed commands without a result stay
+unknown and cannot authorize provider fallback or another tab creation. The
+optional failure binding is backward compatible; only updated extensions supply
+it. No database schema, lifecycle, process, retry budget, external send, or second
+writer is added. Existing leases, redacted receipts, task terminalization,
+tombstone retention, backpressure and unknown-effect fences remain. Complete
+Runtime release/rollback includes the adapter contract and matching extension.
+
+Incident evidence: read-only Runtime calls on 2026-10-15 observed 188 historical
+Supervisor tasks and zero active tasks; recent retrieved acceptance tasks were
+terminal. That inventory is not evidence of current autonomous sends. Computer
+reported 227 saved records, 221 unverified and six dead native records; metadata
+is not proof of a live tab. Existing discovery stays observation-only and never
+enrolls historical conversations. A source reproduction combined unavailable
+content scripts with worker restart: the old code changed instance id, returned
+no binding, and created two tabs for one bootstrap key. The candidate retained
+one instance and returned the failed page's binding, keeping one tab and sending
+nothing. A separate Controller probe verified failed-binding persistence, broker
+restart reuse and no commands to a foreign profile. These are bounded adapter
+facts; live release acceptance remains separate.
+
+### Live Chrome content contract at Bootstrap
+
+A projected Chrome extension on disk is not evidence that an existing Chrome tab has loaded the same content script. Before Supervisor consumes an exact, single-use authorization to back up and replace an unrelated Project composer draft, the actual pinned tab must attest `composerReplacementContract=exact-backed-up-project-draft-v1` in its read-only snapshot. An absent attestation is a task-local `COMPUTER_CHATGPT_BOOTSTRAP_LOADED_SCRIPT_STALE` pre-send failure, not permission to clear the editor, switch providers, create a replacement tab, or record Send. The Chrome background independently checks this exact-tab capability when preparing a guarded draft replacement. The original draft and one-use authorization remain intact when the loaded script is stale; after reloading the extension, the original unspent effect may be rearmed only within its existing bounded operator-retry contract. Projection checks and MCP health cannot substitute for this live evidence. Final release acceptance still requires independent actual multi-turn work to DONE.

package/docs/architecture/decisions/20261005-forge-v3-desktop-client-boundary.md

@@ -0,0 +1,77 @@
+# Forge V3 desktop client boundary
+
+Status: accepted
+Date: 2026-10-05
+Authority: [`../CURRENT.md`](../CURRENT.md)
+
+## Decision
+
+Forge V3 introduces a fresh cross-platform desktop client under `apps/desktop`. The client is a presentation and interaction adapter over the existing Forge Runtime and Controller authorities; it is not a second control plane and does not reuse the retired Local Bridge web frontend as product architecture.
+
+The initial macOS shell exposes two explicit interaction modes without creating a new domain state machine: Local for client-owned conversation interaction, and MCP for Projects/Work plus Runtime/Recovery operations. A lightweight sidebar selects mode, repository scope and Work; the single main surface shows either the Local conversation or the MCP repository/work surface and immediate actions. Plan, evidence, IDs and mechanical Runtime facts are disclosed on demand rather than occupying a permanent inspector. These surfaces are views over canonical Runtime facts rather than independent client state machines.
+
+## Authority boundary
+
+- Requirement, Plan, Work, ControllerSession/ControllerRound, Scheduler, Workflow Supervisor, repository/worktree identity, connections and Runtime/Recovery lifecycle remain authoritative in their existing Forge owners.
+- The desktop client may own only transient presentation state such as selected navigation, active inspector tab, draft text, window geometry and replaceable transport handles.
+- The client must not persist a mirrored Requirement/Plan/Work database, infer semantic completion from UI state, or create a client-side scheduler/retry authority.
+- Runtime reads enter through typed projection/query contracts. Runtime mutations enter through existing typed Runtime/Controller capabilities and preserve their CAS, effect, authorization and outcome-unknown semantics.
+- Tauri owns desktop shell mechanics only. Starting or closing the UI must not mint another Forge Runtime, Recovery, Scheduler or Supervisor authority.
+- A disconnected UI is an adapter availability state. It does not redefine Work, Scheduler or Runtime semantic state.
+- Runtime/Recovery history is projected from the standalone Recovery authority's bounded canonical audit tail. The projection exposes event/time and a bounded outcome bit only, omits arbitrary audit detail and local paths, and is never persisted or reconstructed by the desktop client.
+
+## Foundation layout
+
+`apps/desktop/src/runtime-projection.ts` defines the projection-facing client boundary. Its bootstrap value is presentation-only and intentionally says `Runtime not connected`; no fake Requirement, Plan, Work or connection facts are synthesized before Runtime integration lands.
+
+`apps/desktop/src-tauri` is the fresh Tauri 2 shell. Platform-specific code remains behind this shell/provider boundary so Windows support can be added without changing semantic ownership.
+
+## Runtime transport
+
+The desktop shell reaches Canonical Runtime through its existing loopback MCP HTTP transport. The Tauri process resolves the installed Controller Home and Runtime service configuration, reads the Runtime bearer token only inside the native process, and issues stateless MCP `tools/call` requests. The token is never projected into the webview. Desktop mutations therefore still enter through `capability_execute`; the current automatic-continuation conversation switch calls `controller.workflow_supervisor.switch_to_fresh_conversation` and preserves the Supervisor CAS/effect fences.
+
+The bridge is intentionally typed and narrow. It exposes only the product facts/actions needed by the current macOS surfaces: Repository Registry projection, bounded repository/runtime status, selected Work detail, Requirement detail, Plan detail, pending UserRequest projection, automatic-continuation projection, controller/tunnel connection projection, explicit Work continuation, explicit fresh-conversation migration, and bounded connection repair. Each command forwards to an existing Forge facade/tool; it does not expose Controller Home persistence, a generic database API, or a client-owned retry/session engine.
+
+## Project Workbench projection
+
+The V3 Project Workbench remains projection-only. Entering MCP or selecting a Project first establishes a repository/worktree overview from canonical Repository Registry and repository-state facts; it does not implicitly select or create a Work. The primary MCP surface may summarize the already-projected Repository cleanliness/revision, current Work count, active worktree inventory and Runtime/MCP readiness in compact operational cards; once a Work is selected, the same summary layer may surface canonical Work revision/state, linked Plan revision/status, execution-evidence phase/check counts and Repository state before the detailed sections. These summaries are derived only from the projection already in memory and never become a client-owned status model. Project navigation reads the canonical Repository Registry through `repository_list`; active checkout/worktree inventory comes from the existing `repository_get(detail)` authority, then the native bridge strips it to checkout id, local path, branch, worktree kind, lifecycle and active identity and bounds the WebView list rather than copying complete historical Registry records; bounded Git/repository state comes from `rh_status(list)`; the sidebar's current Work collection and bounded recent completed/cancelled history come from canonical `rh_work(list)` rather than a client-invented `rh_status` snapshot shape; once the user selects a Work, its canonical `revisionHistory`, its decomposition/dependency graph, and a bounded execution-evidence projection come from `rh_work(get, detail)`; linked Requirement and Plan authored facts plus canonical Plan `revisionHistory` are read through `rh_work(requirement_get)` and `rh_work(plan_get, detail)`. The Work detail execution projection is sourced from the canonical WorkContract execution fields (`dispatchState`, `evidenceState`, `phase`, `workKind`, `completionOutcome`, declared checks, `phaseEvidence`, verification records and `evidenceRefs`) and strips process-local artifact paths or other unnecessary mechanics before crossing into the webview. The MCP Work surface may drill into the already-projected verification timing, stale reason, bounded receipt facts and evidence-reference identity/summary so a user can audit why a check is considered valid or stale; it must not re-run a check, infer freshness, resolve artifact paths or manufacture receipt state in the renderer. Work remains semantic scope only: unless a separate canonical execution-placement fact is supplied, the desktop must not present the Project active checkout as the Work's execution checkout. The desktop must not parse semantic `resultRefs` to infer check outcomes, phase completion, execution placement or execution progress. Pending human-boundary facts come from instance-level `rh_inbox(list)` and are filtered to an exact `targetScope.workId` match before appearing in the selected Work surface, so the client does not turn the main workspace into a global/stale handoff dump. The focused surface may show Work semantic state/revision, repository dirty state, branch/source revision and canonical `nextSafeAction` as a compact fact strip, while Requirement outcome/acceptance criteria, Plan items, Work parent/dependencies, execution/check evidence, semantic revision history and result references remain progressive disclosure. History renders recorded semantic revisions as supplied; the client does not calculate progress, backfill missing revisions, or reinterpret historical state. Selecting a Project or Work changes only transient desktop presentation state. An explicit MCP refresh may re-read Repository Registry, repository/worktree facts, Work/Plan/evidence projection and Supervisor facts as one user-requested snapshot refresh; it does not poll, reconcile, retry or maintain a client-owned synchronization lifecycle. The client does not persist or reconstruct Work, Requirement, Plan, UserRequest, Git or Scheduler authority.
+
+Continuing a selected Work is an explicit user mutation routed through `rh_work(launcher_start)` with the selected repository and Work identities. Automatic-continuation metadata comes from `controller.workflow_supervisor.list`; exact conversation URL, repository/Requirement contract bindings and created time are rendered only when supplied by the Supervisor authority. The desktop does not create its own controller session, retry loop, conversation authority, UserRequest lifecycle, or lifecycle transition.
+
+The shipped desktop UI is Chinese-first. Domain IDs, repository names, user-authored objectives and external product names remain verbatim canonical data, while navigation, labels, states, actions, errors and explanatory copy are rendered in Chinese.
+
+## Local conversation boundary
+
+Local Thread is client-owned interaction data, not a Forge semantic lifecycle record. The desktop may persist a bounded local transcript plus presentation metadata and an optional canonical repository id reference, but it must not copy Requirement, Plan, Work, Runtime or connection records into that store as mutable truth.
+
+Current Kernel `ControllerSession` / `ControllerRound` contracts are intentionally Work-bound. Local conversation therefore must not manufacture a Work merely to obtain a controller binding, and it must not reinterpret Workflow Supervisor or `launcher_start` as a general chat-session authority. Provider status and invocation live behind the typed `controller.local_conversation` capability. The initial provider is the installed Codex CLI and reuses Codex-owned authentication; Forge does not copy provider credentials into Controller Home or the renderer. Each local thread receives an invocation-scoped Forge MCP principal/session, while the provider thread id remains only an opaque resume handle. The provider/controller loop calls the existing Runtime MCP capabilities as tools, so Forge continues to own those capability effects and canonical semantic facts.
+
+Local Codex sessions start in a read-only provider sandbox. Repository and Runtime mutations therefore go through the injected Forge MCP capability surface rather than direct provider filesystem writes. Client-local thread create/select/archive, optional Project attachment, provider resume, and final assistant responses are functional without implicit Requirement/Plan/Work/ControllerRound creation. If Codex or Runtime is unavailable the UI reports that failure directly; there is no synthetic assistant output and no fallback to the retired Local Bridge/browser-profile path.
+
+## Runtime and Recovery surface
+
+The Runtime screen must remain usable when Canonical Runtime is unavailable. The native Tauri adapter therefore has a second narrow transport path to the already-authoritative Standalone Recovery Gateway at its configured loopback MCP endpoint. It reads the Recovery configuration and bearer token only inside the native process; Recovery credentials are never projected into the webview.
+
+This is not a fallback Runtime and does not start, stop, repair, or roll back any process directly. Readiness and diagnostics call Recovery's `runtime_status` and `verify_stable_runtime`. Explicit user mutations are limited to named Recovery tools such as `restart_primary_runtime` and `recover_primary_runtime`. Before a mutation, the adapter re-reads `runtime_status` and hydrates the exact host/platform/ControllerHome/Recovery-release/target-Runtime fencing identity exposed by Recovery itself; Standalone Recovery remains the authority that validates or rejects the operation.
+
+No client retry loop or inferred recovery lifecycle is introduced. The UI may own only transient loading/error/confirmation state around one explicit command, then it re-reads Recovery authority after completion. `restart_primary_runtime` already stops/quiesces as needed, starts the configured launchd/systemd service and verifies the whole Runtime, so the desktop may label that same Recovery-owned mutation `Start Runtime` when `runtime_status.running=false` and `Restart Runtime` otherwise; this creates no second start authority. `recover_primary_runtime` remains a distinct deeper recovery transaction that can enter release recovery/rollback and is exposed only as an explicitly warned action while Runtime is not ready.
+
+Controller and remote-transport setup is projected separately through the typed `controller.connection` capability. That facade derives product-safe status from the existing setup-profile authority (`readSetupProfile`, `resolveControllerGuidance`, and `resolveTunnelGuidance`) and does not persist a second connection model. Its only automatic mutation, `repair_connector`, delegates to the existing `runMcpSetupChatgpt` owner for the Forge-managed loopback Connector. OpenAI Secure Tunnel, Cloudflare, Tailscale, client installation, login, tunnel identity, and other external prerequisites remain explicit setup requirements rather than being silently repaired by the desktop client. Tauri and the webview never read or write setup files directly.
+
+## macOS presentation model
+
+The macOS client uses the system-owned decorated window. The webview must not draw duplicate traffic-light controls or treat an application toolbar as a synthetic title bar. Window close/minimize/zoom chrome remains owned by macOS/Tauri.
+
+The primary V3 layout is intentionally sparse: one lightweight navigation sidebar and one main work surface. A compact Local/MCP switch changes presentation scope only. In MCP mode, Project selection opens a repository/worktree overview and Work inventory; Work selection then focuses the same main surface on the selected Work and its immediate actions. Repository/Work/Plan/Evidence readiness may appear as a compact summary band on that main surface so MCP operation does not require opening several disclosure sections merely to understand current state. IDs, revision history, raw evidence references, runtime mechanics, and other secondary facts remain progressive disclosure rather than a permanent inspector column. Runtime/Recovery is a dedicated MCP main surface rather than a dashboard side panel.
+
+This follows the desktop-agent interaction model of task/session navigation plus a focused work area. It explicitly rejects a three-column web-dashboard composition as the default macOS product architecture.
+
+## Verification
+
+This foundation is acceptable when:
+
+1. the frontend source and Tauri shell form an independently reviewable application boundary;
+2. no desktop source imports Runtime persistence stores or writes Controller Home state directly;
+3. the UI can render without manufacturing semantic domain data;
+4. project source authority includes `apps/**` so future engineering checks and context retrieval treat the client as first-class source;
+5. subsequent Runtime bootstrap work can replace the disconnected projection through a typed client adapter without migrating client-owned semantic data, because none exists.

package/docs/architecture/decisions/20261009-exact-code-context-discovery.md

@@ -0,0 +1,19 @@
+# Exact code-symbol discovery within bounded Context retrieval
+
+`docs/architecture/CURRENT.md` remains the sole architecture authority. This note records a focused Context Plane implementation decision and test contract; it adds no store, cache, result state, or secondary search authority.
+
+## Observed defect
+
+A request containing two exact source symbols could split them into common word fragments or treat both as one literal query. Early broad matches then filled the candidate window and prevented later exact hits from entering. Separately, the Git inventory's alphabetic first-800-file cap made files beyond that prefix unsearchable by the lexical pass. Increasing the scan cap would add disk/CPU cost without fixing symbol priority.
+
+## Existing-authority correction
+
+- Parse explicit code-shaped tokens into independent bounded exact queries. Preserve caller-provided ordinary literal phrases (`return 42`) as search queries as well. Keep camel-case fragments as nonbinding discovery hints, not mandatory matches.
+- Preserve later exact hits when broad candidate capacity is reached, and reserve the highest-ranked candidate for each matched exact symbol before ordinary ranked results.
+- Use Git's read-only tracked-file grep only to **prioritize candidate paths** when the inventory exceeds the existing scan cap. The original policy-checked repository source matcher validates each file and enforces exact identifier boundaries. Git grep supplies no policy, semantic completion, persistence, or source identity authority.
+- Apply equivalent search admission and cache identity in synchronous and asynchronous Context paths. Neither path increases the existing actual-file scan cap or accepts forbidden paths from Git hints.
+- Context results remain bounded evidence, not completeness proof. Git hints may omit untracked files and max-files/snippet caps still apply; explicit known paths and progressively narrowed source requests remain the existing precise retrieval surfaces.
+
+## Verification
+
+Regression fixtures place two complete symbol declarations after more than 800 broad distractors, with multiple longer-prefix false positives. Both synchronous and asynchronous Context materialization must select the two exact target files and inspect fewer than 30 candidate source files. Process Runtime timeout observations independently release monitor waiters and abort listeners, with no post-timeout cancellation of a live command.

package/docs/architecture/decisions/20261009-generated-xcode-cache-retention.md

@@ -0,0 +1,37 @@
+# Checkout-local Xcode cache reuse and reclamation
+
+Status: accepted contract for the storage repair candidate; activation is a separate complete Runtime release decision.
+Evidence: local 2026-10-09 disk audit reclaimed 60.39 GiB of generated Xcode subdirectories across 384 directories; issue #194 records the bounded-retention gap.
+
+## Root causes and decision
+
+The existing iOS producer already used stable build buckets, but the key included device identity and tests used a separate scheme-only bucket. Build and test now reuse the same checkout-local container/scheme/configuration/platform bucket. Simulator identities, test selectors and invocation timestamps do not create another cache. Device and simulator platforms and configurations remain separate; Xcode owns source, SDK and toolchain invalidation. Cross-checkout mutable DerivedData sharing is forbidden because absolute paths and concurrent writers differ.
+
+The existing Runtime maintenance owner reclaims generated caches on its five-minute retention cadence, with one repository and the existing 1,000-entry/eight-removal budget per pass. Repository, checkout, namespace and nested directory rotations consume independent visit ordinals; a global sequence must not couple these selection layers.
+
+Discovery uses Xcode's info.plist plus known rebuildable directories, including arbitrary preview bucket names under existing owned namespaces. Reclamation deletes only Build, ModuleCache.noindex, Index.noindex, CompilationCache.noindex, SDKExplicitPrecompiledModules and SDKStatCaches.noindex. Logs, result bundles, SourcePackages, metadata, unknown contents and tracked content remain. This replaces the unsafe whole-DerivedData deletion contract.
+
+## Cross-cutting closure
+
+| Area | Owner and behavior |
+| --- | --- |
+| Identity / scope | Existing repository registry and active managed checkouts; existing .forge/ios, .ai/harness, .repo-harness and .tmp namespaces only. A cache name alone is not ownership or disposable-content proof. |
+| Authority / trust | Existing Runtime maintenance write claim and explicit full-maintenance action. No new daemon, registry, schema, credential or permission authority. Symlink ancestors and unprovable Git/process inventory stop deletion. |
+| Concurrency / fencing | Existing plugin workspace claims serialize canonical build/test operations. Maintenance protects processes referencing the cache and conservatively protects checkout-scoped or unscoped xcodebuild commands. Producer refreshes bucket last-use before and after execution; six-hour periodic grace remains. External shell activity is observable process evidence, not a Forge lease; this is conservative protection rather than a transactional filesystem lock. |
+| Lifecycle / retention | Reusable cache lives within its checkout. Rebuildable children expire after idle grace and are regenerated by Xcode. Source checkout and evidence lifecycle remain separate. Missing process inventory yields a bounded diagnostic and no reclamation. |
+| Persistence / integrity / recovery | No database migration. Deleting disposable children is idempotent; interrupted passes leave a valid surviving bucket for the next scan/build. Existing source, Git, dependency and evidence backups retain their owners. |
+| Evidence / privacy | Existing cleanup reports record removed paths, protection reasons and budget exhaustion; no source, credential or process text persistence added. Result bundles use the existing collision-resistant artifact stamp. |
+| Capacity / time / performance | Stable keys reduce cache production. Existing bounded scan/removal budgets protect scheduler latency; rotation prevents protected early entries from permanently starving later directories. Grace uses the newer bucket/child mtime and completed reuse refreshes last-use. This is idle reclamation, not a hard global disk quota. |
+| Topology / portability / release | Same in-process Runtime maintenance owner; no additional process. iOS commands remain Darwin-only. Deploy/rollback is the complete Runtime release under existing authority; source delivery alone does not activate the fix. |
+
+## Preserved and deferred boundaries
+
+KEEP existing bounded budgets, active-process protection, Git ownership checks, evidence retention and complete Runtime rollback.
+CHANGE whole-directory deletion to typed disposable children; cache key to compatible build/test reuse; correlated/deep-only cache scheduling to independent five-minute rotation.
+DEFER relocating existing iOS build caches into Controller Home: install/build product paths and checkout fencing need one coherent owner migration. This candidate creates no additional cache root and does not duplicate or copy legacy buckets.
+DEFER arbitrary external /private/tmp builds and third-party caches: neither naming nor age grants Forge deletion ownership. Use the canonical build/test producer for managed builds; manual external runs should reuse an explicit per-checkout cache and remove it at their own terminal boundary.
+DEFER cloud transfer of cold recovery bundles until verified upload/restore and local-retention authority exist. Rebuildable caches are not cloud backup data.
+
+## Verification
+
+Extend retained iOS producer and generated-cache safety scenarios; do not add tests during Kernel V2 suite freeze. Verify cache reuse across simulators/build/test, platform/configuration separation, unique result bundles, arbitrary-name recognition, nested evidence/dependency preservation and independent rotation. Run affected type and repository/architecture checks before source delivery.