docs(workhub): record coordination session architecture

docs/README.md

@@ -46,6 +46,8 @@ This page is the authority map for Maka documentation. Code and contract tests r
 - [Session task ledger lifecycle](./session-task-ledger-lifecycle.md)
 - [Work Board contract](./work-board-contract.md)
 - [Work Board Phase 1 surface](./work-board-phase1.md)
+- [WorkHub domain language](./workhub-domain-language.md)
+- [WorkHub Coordination Session ADR](./architecture/workhub-coordination-session-adr.md)
 - [Runtime resume architecture](./architecture/runtime-resume-architecture.md) ([中文](./architecture/runtime-resume-architecture.zh-CN.md))
 - [Runtime Host architecture](./architecture/runtime-host-architecture.md) ([中文](./architecture/runtime-host-architecture.zh-CN.md))
 - [Remote Runtime Host setup](./runtime-host-remote-access.md) ([中文](./runtime-host-remote-access.zh-CN.md))

docs/architecture/workhub-coordination-session-adr.md

@@ -0,0 +1,148 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# ADR: One WorkHub Coordination Session per Runtime Host
+
+- Status: Accepted
+- Date: 2026-08-25
+- Scope: WorkHub architecture
+- Decision source: [Discussion #3286](https://github.com/apache/maka/discussions/3286#discussioncomment-18135855)
+- Delivery tracker: [Issue #3492](https://github.com/apache/maka/issues/3492)
+
+## Context
+
+WorkHub is intended to be one persistent conversational place where a user can ask
+an ordinary question, clarify intent, continue existing work, or create new work.
+R2.4 is a deterministic routing and context-continuity baseline that may also serve
+as a future target resolver. It does not provide a persistent WorkHub conversation
+and is not the final definition or authority boundary of WorkHub.
+
+A persistent coordinator needs durable conversational continuity without creating
+a second WorkHub database, event store, transcript substrate, or lifecycle
+authority alongside Session.
+
+## Decision
+
+Each Runtime Host independently owns one stable WorkHub **Coordination Session**.
+The Coordination Session is a special role of the existing Session, not a new
+durable entity type or storage system. It reuses the existing Session, Turn,
+transcript, model, recovery, and event infrastructure. Session remains the only
+durable conversation and execution substrate.
+
+The role is provisioned lazily when WorkHub first needs it and resolves to the same
+Session after Runtime Host or application restarts. The representation, lookup, and
+recovery mechanisms that enforce this contract are deferred to Slice 2.
+
+The per-Host boundary is intentional. A Coordination Session coordinates only the
+ordinary Sessions belonging to the same Runtime Host. Switching Runtime Hosts
+selects the other Host's Coordination Session; the first milestone does not support
+cross-Host coordination or a global Coordination Session.
+
+The Coordination Session is hidden from the ordinary Session list and excluded
+from every routing-candidate set. The Action Gate's self-route rejection remains a
+defense in depth; it is not a substitute for keeping the Coordination Session out of
+ordinary navigation and target discovery.
+
+## Durable authority boundaries
+
+| Concern | Durable authority |
+| --- | --- |
+| User messages sent in WorkHub, ordinary Q&A, clarification, coordination decisions, bounded delegation references, and coordination summaries | The active Runtime Host's Coordination Session |
+| Concrete execution, project and filesystem scope, model and permission mode, root-Turn admission, tools, artifacts, recovery, archive/delete, and the authoritative execution transcript | The target ordinary Session |
+| Aggregated WorkHub cards, filters, status summaries, and navigation aids | No durable authority; these are rebuildable projections of Session facts |
+
+The Coordination Session is authoritative only for the coordination conversation.
+It never acquires authority over an ordinary Session's execution or lifecycle.
+
+## Dispositions and action admission
+
+Every WorkHub input resolves to exactly one proposed **disposition**:
+
+- `answer_here`: answer in the Coordination Session.
+- `delegate_existing`: delegate concrete work to one bounded, valid ordinary
+  Session.
+- `create_new`: create an ordinary Session, then delegate concrete work to it.
+- `clarify`: continue clarification in the Coordination Session without guessing a
+  target or creating a Session.
+
+All model and routing output is advisory. Before any write, a deterministic
+**Action Gate** admits or rejects the proposed disposition and operation. The gate
+enforces Runtime Host and target validity, archive and waiting state, self-route
+exclusion, explicit `create_new`, expected-Turn ownership for Stop, confirmation
+requirements, and existing tool and permission ceilings. Neither a model nor a
+routing policy can directly authorize a write or expand execution authority.
+
+## Delegation links rather than copies transcripts
+
+A delegation persists only a bounded link between the coordination and execution
+transcripts, such as:
+
+```text
+delegationId
+coordinationTurnId
+targetSessionId
+targetTurnId
+disposition
+status
+```
+
+`status` describes only whether the coordination-owned link is `active` or
+`superseded`; it never mirrors the target Turn's execution lifecycle. Target
+acceptance, running, waiting, completion, failure, abort, and recovery state remain
+ordinary Session facts. WorkHub derives those states as read-only projections and
+does not persist them as independent Coordination Session truth.
+
+The ordinary Session records the delegated request, tools, side effects, and
+authoritative result. WorkHub may display a bounded projection or record a
+coordination summary, but it does not copy the ordinary Session's complete
+transcript into the Coordination Session.
+
+## Consequences, costs, and reevaluation
+
+- WorkHub gains persistent conversational continuity without adding another
+  durable authority, database, event store, lifecycle, or transcript copy.
+- Coordination and execution remain separately authoritative within the shared
+  Session substrate.
+- The per-Host boundary fragments WorkHub continuity when a user switches Runtime
+  Hosts: each Host has a separate coordination transcript and cannot coordinate the
+  other Host's Sessions.
+- The special Session role adds provisioning, lookup, recovery, retention, and UI
+  obligations even though it deliberately reuses the existing Session substrate.
+- Whether Work is 1:1 with Session, 1:N over Sessions, or an independent durable
+  entity remains unresolved.
+- Cross-Runtime-Host coordination remains deferred.
+- Coordination Session kind/role representation, lazy creation, durable lookup,
+  recovery, UI treatment, and routing implementation belong to Slice 2 and later;
+  this ADR does not design or implement them.
+
+Reevaluate the per-Host decision if supported workflows require one WorkHub
+conversation to coordinate ordinary Sessions on multiple Runtime Hosts, or if Host
+switching creates user-visible continuity loss that rebuildable projections cannot
+resolve. Reevaluate the special Session role if implementing its lifecycle requires
+a second durable authority or exceptions that the ordinary Session substrate cannot
+enforce safely.
+
+## Rejected alternatives
+
+- A second WorkHub database, event store, transcript substrate, or lifecycle
+  authority.
+- One global Coordination Session spanning Runtime Hosts.
+- Copying an ordinary Session's complete transcript into WorkHub.
+- Allowing model or routing output to authorize writes without the deterministic
+  Action Gate.

docs/workhub-domain-language.md

@@ -25,20 +25,25 @@ Runtime Host while concrete execution remains authoritative in ordinary Sessions
 
 This document names the approved target architecture. The current R2.4
 implementation is a transitional deterministic router and does not yet create the
-Coordination Session described below.
+Coordination Session described below. The decision and authority boundaries are
+recorded in the [WorkHub Coordination Session ADR](./architecture/workhub-coordination-session-adr.md).
 
 ## Terms
 
 **Session**: The existing transcript, execution-boundary, permission, interaction,
 and recovery substrate. A Session owns only the conversation or execution admitted
 to that Session.
 
-**Coordination Session**: A special Session role used by WorkHub. Each Runtime Host
-has at most one stable Coordination Session. It owns WorkHub user messages, ordinary
-Q&A, clarification, coordination decisions, delegation references, and coordination
-summaries. It is hidden from the ordinary Session list and never routes to itself.
+**Coordination Session**: The stable special Session role owned independently by
+each Runtime Host for its WorkHub conversation. It owns WorkHub user messages,
+ordinary Q&A, clarification, coordination decisions, bounded delegation references,
+and coordination summaries, but no ordinary Session execution or lifecycle facts.
+It is not a separate database, event store, transcript substrate, or lifecycle
+authority. It is hidden from the ordinary Session list and excluded from every
+routing-candidate set, so it never routes to itself. Cross-Host coordination is not
+supported in the first milestone.
 
-**Ordinary Session**: A Session that owns concrete work execution, including its
+**ordinary Session**: A Session that owns concrete work execution, including its
 project/filesystem scope, model and permissions, root-Turn admission, tools,
 artifacts, recovery, lifecycle, and authoritative execution transcript.
 
@@ -49,18 +54,30 @@ artifacts, recovery, lifecycle, and authoritative execution transcript.
 the active Runtime Host's Coordination Session. It may answer locally, clarify,
 delegate to an existing ordinary Session, or create a new ordinary Session.
 
-**Session projection**: A rebuildable view derived from Session facts for display and routing. It can be discarded and recreated without losing work.
-
-**Disposition**: The coordination outcome for one WorkHub input:
-`answer_here`, `delegate_existing`, `create_new`, or `clarify`.
-
-**Delegation**: A reference from a Coordination Turn to a target ordinary Session
-and Turn. Delegation links the two authoritative transcripts; it does not copy the
-target execution transcript into WorkHub.
+**projection**: A rebuildable, read-only view derived from Coordination Session and
+ordinary Session facts. WorkHub cards, filters, status summaries, and navigation
+aids are projections; they own no durable facts and can be discarded without losing
+work.
+
+**disposition**: The single proposed coordination outcome for one WorkHub input:
+`answer_here` answers in the Coordination Session; `delegate_existing` targets one
+bounded, valid ordinary Session; `create_new` creates an ordinary Session before
+delegating; and `clarify` continues in the Coordination Session without guessing or
+creating.
+
+**delegation**: A bounded reference from a Coordination Turn to one target ordinary
+Session and Turn, including only its identity, disposition, and coordination-owned
+link status (`active` or `superseded`). Delegation links the separately authoritative
+transcripts; it does not copy the target's complete execution transcript into
+WorkHub. Target acceptance, running, waiting, completion, failure, abort, and
+recovery state remain ordinary Session facts and appear in WorkHub only as read-only
+projections.
 
 **Action Gate**: The deterministic Runtime boundary that validates a proposed
-disposition, target, creation, Stop, confirmation, tools, and permissions. A model
-or routing policy may propose an action but cannot authorize it.
+disposition and operation before any write, including target/Host validity,
+archive and waiting state, self-routing, explicit creation, expected-Turn Stop
+ownership, confirmation, tools, and permissions. All model and routing output is
+advisory and cannot authorize a write.
 
 **Route correction**: A user's decision that an input belongs to a different
 existing Session. R2.4 retains only bounded inference memory for later target