tracking(desktop): evolve WorkHub into a per-Runtime-Host conversational coordinator

## Goal

Evolve WorkHub from a transient Session router into a unified conversational entry point backed by **one stable WorkHub Coordination Session per Runtime Host**.

The user should be able to ask an ordinary question, clarify intent, continue existing work, or create new work from the same conversation. Concrete execution remains in ordinary Sessions.

The approved architecture direction is recorded in [Discussion #3286](https://github.com/apache/maka/discussions/3286#discussioncomment-18135855). The exact routing strategy is intentionally left open until the R3 experiment is complete.

## Architecture contract

### Coordination Session lifecycle

- Reuse the existing Session, Turn, transcript, model, recovery, and event infrastructure; do not add a second WorkHub database or lifecycle.
- Lazily create one stable WorkHub Coordination Session for each Runtime Host and reuse it after restart.
- Hide it from the ordinary Session list and exclude it from routing candidates.
- Switching Runtime Host switches to that Host's Coordination Session.
- The first milestone does not coordinate across Runtime Hosts.

### Authority boundaries

| Concern | Durable authority |
| --- | --- |
| User messages sent in WorkHub, ordinary Q&A, clarification, coordination decisions, delegation references, and coordination summaries | WorkHub Coordination Session |
| Concrete execution, project/filesystem scope, model and permission mode, root-Turn admission, tools, artifacts, recovery, archive/delete, and the authoritative execution transcript | Target ordinary Session |
| Aggregated WorkHub cards, filters, status summaries, and navigation aids | Rebuildable projection; no durable authority |

The Coordination Session is a special **role of Session**, not a new authority outside the Session substrate. It owns only the coordination conversation; it never takes ownership of another Session's execution facts.

### Coordination outcomes

Every ordinary routing input resolves to one of four dispositions:

```text
answer_here
delegate_existing
create_new
clarify
```

- `answer_here`: answer inside the Coordination Session.
- `delegate_existing`: send concrete work to one bounded, valid ordinary Session.
- `create_new`: create an ordinary Session, then delegate the work to it.
- `clarify`: continue the clarification in the Coordination Session without guessing or creating.

### Routing dispositions and linked operations

Intent, routing disposition, and linked operation describe three different things:

- **Intent** describes what the user wants. It does not choose a target or authorize an effect.
- A **routing disposition** decides how to handle a new coordination request. The routing disposition set remains closed over `answer_here`, `delegate_existing`, `create_new`, and `clarify`.
- A **linked operation** acts on a delegation that WorkHub has already created. `correct`, `stop`, and `resume` are linked operations, not additional routing dispositions.

```text
user input
|
Intent analysis
|
+-------------+-------------+
| |
routing intent linked intent
discuss / execute / create correct / stop / resume
/ continue |
| |
Session Resolver linked-target resolution
| delegation -> Session -> Turn lineage
+-------------+-------------+
|
Action Policy
|
+-------------+-------------+
| |
routing disposition linked operation
answer_here / delegate_existing correct / stop / resume
create_new / clarify |
+-------------+-------------+
|
Action Gate
|
owning Host / Session
```

The two resolver paths have different evidence:

- `SessionResolver` recalls and ranks bounded existing ordinary Sessions for a new routing decision. It never creates a Session or grants execution authority.
- Linked-target resolution starts from a bounded WorkHub-owned delegation and follows its durable lineage to the authoritative Session and Turn. It must not approximate a target by selecting a similarly named Session.

For correction, the replacement must retain the source relationship (`replaces` / `replacedBy`) instead of appearing as an unrelated second delegation. Stop and resume must follow the linked delegation and continuation lineage, with expected-Turn ownership and current Runtime state revalidated by the Action Gate. Missing, stale, or ambiguous linkage must fail closed through clarification or an actionable rejection.

This clarification does not widen the four-disposition routing protocol. It makes the subsequently delivered Slice 5 correction, Stop, and resume operations explicit alongside that protocol while preserving target-Session execution authority.

### Delegation and safety

Delegation links the coordination and execution transcripts instead of copying execution history into WorkHub. The minimum linkage is:

```text
delegationId
coordinationTurnId
targetSessionId
targetTurnId
disposition
status
```

All strategy output is advisory. A shared deterministic Action Gate validates the target and operation before any write: current Runtime Host, target existence, archive/waiting state, self-routing, expected-Turn ownership for Stop, explicit `create_new`, risk confirmation, and existing tool/permission ceilings.

## Evolution from the current MVP

```text
Session projection + deterministic router (R2.3/R2.4)
↓
stable per-Host Coordination Session and persistent WorkHub transcript
↓
typed dispositions + deterministic Action Gate
↓
linked delegation to ordinary Sessions
↓
R2.4 vs R3-A vs R3-B experiment
↓
evidence-based production strategy and gradual cleanup
```

The existing work remains useful:

- #3497 merged the conservative R2.3 routing MVP.
- #3645 merged the WorkHub result-layout fix.
- #3648 merged bounded reconstruction of ordinary Session transcripts.
- #3674 merged the transitional R2.4 context-continuity work. It remains valuable as a deterministic baseline/resolver and as safety-test coverage, but it is not the final WorkHub architecture.

## Delivery slices

Slices and PRs are intentionally **not** one-to-one. A PR may deliver multiple tightly coupled checklist items when they form one reviewable, usable loop.

Current status (2026-09-13): Slices 1–5 have shipped incrementally; #4924 merged the Slice 6 component/comparison foundation and Slice 8 navigation enhancements. #5198 has merged conversation identity/status/filtering and Host-owned target selection through the default Coordination tool path. Three subsequent P2 findings remain to be independently verified and addressed below. Slice 7 comparative real-model evaluation, strategy selection and rollout remain open. The Coordination Turn-admission gap was closed by #4993.

### Slice 0 — Close and preserve the deterministic baseline

- [x] Keep the fixed 10-Session evaluation snapshot and versioned routing-policy IDs.
- [x] Preserve deterministic routing, clarification, correction, waiting protection, and expected-Turn Stop tests from #3497 and #3674.
- [x] Resolve #3674's overlapping-correction ordering finding before merge.
- [x] Update #3674's domain language so R2.4 is described as a baseline/resolver, not the final definition of WorkHub.
- [ ] Record a reproducible R2.4 baseline result for the future R3 comparison.

**Exit:** R2.4 is mergeable, reproducible, and safe to retain behind the new coordination layer.

### Slice 1 — Record the architecture decision and ubiquitous language

Delivered by #3742.

- [x] Add an ADR for one WorkHub Coordination Session per Runtime Host.
- [x] Define `Coordination Session`, `ordinary Session`, `disposition`, `delegation`, `Action Gate`, and `projection` in the domain language.
- [x] Record the authority table and the no-transcript-copying rule.
- [x] Record that Work identity/cardinality and cross-Host coordination are deferred decisions.

**Exit:** code and review can use one unambiguous authority and lifecycle vocabulary.

### Slice 2 — Coordination Session lifecycle

Delivered by #3764.

- [x] Introduce a special Session role/kind using the existing Session substrate.
- [x] Lazily create and durably resolve exactly one Coordination Session per Runtime Host.
- [x] Reuse it across renderer/app/Runtime Host restarts.
- [x] Hide it from ordinary Session navigation and exclude it from all route candidates.
- [x] Define recovery, feature-disable, Host-switch, archive/delete, and missing/corrupt-session behavior without losing ordinary Sessions.
- [x] Cover uniqueness, reuse, self-route exclusion, Host switching, and recovery with integration tests.

**Exit:** WorkHub always opens the correct persistent coordination conversation for the active Runtime Host.

### Slice 3 — Persistent unified conversation and `answer_here`

Delivered by #3798.

- [x] Render WorkHub from the Coordination Session transcript while continuing to project ordinary Session status read-only.
- [x] Persist user messages, assistant answers, clarification turns, and coordination summaries in that transcript.
- [x] Support ordinary Q&A through `answer_here` without creating or selecting an ordinary Session.
- [x] Preserve the conversation across navigation into an ordinary Session, return to WorkHub, and restart.
- [x] Keep bounded UI projections and fail-open transcript reads so one unavailable ordinary Session cannot hide the rest.

**Exit:** WorkHub is a real reusable conversation even when no concrete work is delegated.

### Slice 4 — Typed coordination actions and deterministic Action Gate

Delivered by #3818. The merged protocol is intentionally closed over `answer_here`, `delegate_existing`, `create_new`, and `clarify`; it rejects `replace` and exposes no Stop effect.

- [x] Add a typed result contract for `answer_here`, `delegate_existing`, `create_new`, and `clarify`.
- [x] Expose only bounded valid Session candidates; a model must not invent Session IDs.
- [x] Centralize non-destructive admission checks for current Runtime Host, target existence, archive/waiting state, self-routing, creation context, bounded candidate references, and conflicting action replay.
- [x] Keep tool and permission ceilings owned by the target ordinary Session; the closed WorkHub protocol cannot widen either ceiling.
- [x] Add linked replacement and expected-Turn Stop after durable linkage (#4242, #4439). Shared-Turn collateral-impact confirmation remains a separate follow-up under Discussion #4868.
- [x] Make `create_new` the only disposition allowed to create an ordinary Session.
- [x] Return safe clarification or an actionable error when the proposed action is rejected.
- [x] Test rejected-action paths independently of model behavior.

Historical Slice 4 scope was non-destructive. Production linked correction and direct Stop subsequently shipped in Slice 5; their admission remains owned by the Host and target Session.

**Exit:** no routing/model strategy can directly acquire execution authority or bypass Runtime safety for the non-destructive Slice 4 action set. The subsequently delivered destructive actions retain Slice 5 linkage and target ownership checks.

### Slice 5 — Linked delegation and execution feedback

Delivered incrementally by #3935, #4115, #4242, #4439 and #4713; #4699 removes full Coordination-history replay on open/reconnect (fixes #4647).

- [x] Delegate to existing/new ordinary Sessions with durable bounded linkage, without copying their full transcript (#3935).
- [x] Rebuild linkage and handle retries across Host restart using existing Session/Turn/event authorities.
- [x] Project acceptance, running, waiting, completion, failure, abort and recovery from the target Session (#4115).
- [x] Use hybrid first response: immediate durable assignment acknowledgement, followed by target execution feedback.
- [x] Support linked correction with ordering, expected-Turn ownership and fail-closed recovery (#4242).
- [x] Perform direct Stop through the authoritative target Session (#4439).
- [x] Resume named interrupted work through existing Host resume operations; follow continuation lineage for feedback and Stop (#4713). Safe-boundary resume still requires its existing feature flag; no separate durable Coordination resume receipt was added.

**Delivered behavior:** delegate, observe, correct, stop and resume from WorkHub. Coordination Turn admission was later repaired by #4993; queue/shared-Turn design follow-ups remain open below.

### Slice 6 — Composable routing experiment foundation

Delivered by #4924 as an incremental foundation, with broader semantic/orchestration migration explicitly deferred in review.

- [x] Define a strategy as one independently replaceable Intent implementation plus one independently replaceable Resolver; share controller Policy composition and Host Action Gate.
- [x] Retain R2.4 deterministic Intent + Resolver as the baseline at the #4924 milestone. This is historical delivery evidence, not a claim that it remains the current default production entry path.
- [x] Provide R3-A model-assisted Intent + Resolver and R3-B model-assisted Intent + deterministic Resolver. These components do not return the final Policy decision or authorize execution.
- [x] Keep creation under Policy/Host admission rather than an implicit Resolver effect.
- [x] Compare arms through the same real controller fixture with fresh Session snapshots, hydrated Coordination transcript, candidate-set state and repeated inputs. Bound model-facing text at the adapter boundary while retaining full trusted text for deterministic components and Policy.
- [ ] Run reproducible comparisons with real models through the production WorkHub/Host path, recording model/reasoning settings and repeated-run consistency (Slice 7).

**Evidence boundary:** the comparison fixture stubs `coordination.act`; it proves controller composition and proposal behavior, not real Host admission, model quality or a production winner. The unused production experiment shell was removed.

**Current production boundary:** the Coordination model can use bounded Session-management tools directly. The additional routing-model hook remains optional; #5198 does not enable the experiment by default. Its Host-owned target Form is available through `tasks.select_and_delegate`, independently of that hook. This delivery does not select a winner for Slice 7.

**Architecture direction:** Intent → Resolver → Policy → Gate remains the vocabulary; it does not require separate serial model calls before every Coordination Turn. The current Policy seam is not a decision to freeze language heuristics permanently. Evaluate LLM-driven semantic/orchestration decisions and retire redundant deterministic language rules when evidence supports replacement; Runtime retains structured identity, ownership, permission and admission constraints, and only Gate allow authorizes effects.

### Slice 7 — Evaluation, strategy selection, and rollout

- [ ] Include the direct Coordination-model + bounded management-tools path as a comparison baseline alongside R2.4 and staged Intent/Resolver strategies, following the [routing tradeoff discussion](https://github.com/apache/maka/issues/3492#issuecomment-5647191515). Use the same Host/Action Gate authority boundaries.

- [ ] Cover ordinary Q&A, explicit names, semantic references, current/previous work, ambiguity, explicit creation, first-time correction, in-work content edits, archived/running/waiting state, cross-Work questions, navigation/restart, and adversarial candidate text.
- [ ] Report disposition accuracy and target accuracy separately.
- [ ] Report unsafe/wrong-target action rate, unnecessary clarification/creation, correction recovery, ordinary-answer quality, multi-turn consistency, complete task outcomes, total model calls, end-to-end latency, tokens, and monetary cost, including retries and clarification.
- [ ] Keep routing failures separate from downstream target-model execution failures.
- [ ] Select the production strategy from evidence and record the choice as an ADR amendment / Discussion follow-up.
- [ ] Roll out behind the existing feature flag with telemetry and a rollback path that does not delete Sessions or transcripts.
- [ ] Remove obsolete transient router state only after parity and rollback verification.

**Exit:** the default strategy is evidence-backed, observable, and safely reversible.

### Slice 8 — Rebuildable WorkHub projection enhancements

Delivered by #4924; Session navigation and conversation prompt anchors are distinct features.

- [x] Add Work filtering derived from ordinary Sessions.
- [x] Add a bounded Session navigation list using Astryx List/ListItem/StatusDot, ordered by focus, delegation and recent state; opening a row navigates to its Session.
- [x] Add conversation prompt anchors for messages in the current WorkHub transcript, including click/keyboard navigation and scroll selection.
- [x] Keep projections bounded and generation-safe without introducing a lifecycle or execution authority (#4210, #4699, #4924).
- [x] Verify wide/narrow and light/dark interactions, including streaming growth while reading an earlier prompt. Preserve main's shared 28px chat/composer radius (#4919).

**Exit delivered:** filters, Session navigation and current-conversation anchors are available. This is not a claim that all future card/status UX work is complete.

## Next work (ordered follow-up plan)

### 1. Coordination Turn admission and transcript semantics — delivered by #4993

Follow up the [reported lifecycle gap](https://github.com/apache/maka/issues/3492#issuecomment-5564466411) and [commitment to a separate PR](https://github.com/apache/maka/issues/3492#issuecomment-5564735953). This was delivered by #4993.

- [x] Inspect current main and coordinate with the RuntimeEvent transcript migration referenced in the report; route Coordination actions through real Session/Turn admission, preserving atomic delegation assignment and unchanged target Message admission.
- [x] Remove the remaining `workhub.coordination.record`/renderer-authored synthetic assistant and terminal path; represent coordination acknowledgements as the proper action/Turn records.
- [x] Test admission, replay/idempotency, restart, failure cuts and resume acknowledgement; coordinate removal of the dedicated legacy Coordination transcript reader once its prerequisite is met.

### 2. Build Slice 7 evaluation on the production path

- [ ] Capture the direct Coordination/tool baseline through the existing `maka eval` path; compare it with additional routing stages before deciding whether their reliability benefit justifies extra serial calls and maintenance. Keep default-path acceptance separate from comparative evaluation.

- [ ] Capture a reproducible R2.4 baseline and versioned scenarios; run the same WorkHub controller → Host admission path used by the product through `maka eval`.
- [ ] Compare multiple Intent implementations, Resolver implementations and model/reasoning configurations independently and in combinations. Repeat runs; keep snapshots, inputs and context budgets comparable and record configuration differences.
- [ ] Report the Slice 7 quality/safety/latency/token/cost metrics above; separate intent errors, target-resolution errors, Policy/Gate rejections and downstream execution failures.
- [ ] Include real-model `answer_here` and delegation, navigation/restart, correction/Stop/resume, ambiguity, long inputs and adversarial candidate content. Fixture/browser passes alone do not close this gate.

### 3. Use evaluation evidence to migrate semantics and select a default

- [ ] Move semantic/orchestration decisions toward the evaluated LLM components; identify and explicitly retire superseded deterministic language rules. R2.4 is a temporary comparison/rollback baseline, not the final language authority.
- [ ] Record selection and trade-offs in the existing ADR/Discussion, then roll out with observability and a tested rollback preserving Sessions/transcripts.
- [ ] Preserve structured Runtime/target-Session constraints and Gate-only effect authorization throughout migration.

### 4. Track delegation queue/liveness refinements separately

- [ ] Continue [Discussion #4868](https://github.com/apache/maka/discussions/4868): target-owned execution liveness, queue placement/promotion and shared-Turn Stop impact/confirmation. Verify current implementation before defining its next PR; do not count this design work as delivered by #4924.
- [ ] Keep any remaining card/status or pre-first-Turn feedback UX work scoped against the now-shipped filters, Session navigation and prompt anchors to avoid duplicating them.

### 5. Close post-merge #5198 review findings

#5198 delivered shared conversation identity, per-prompt status, stripe/rail filtering, keyboard choices, Host-owned target confirmation and Main-owned native interaction presentation. It reuses existing Forms, interaction persistence and Action Gate; target Sessions retain execution authority.

The following P2 reports target the merged PR head. Reviewer reproductions are recorded; they have not yet been independently reproduced or fixed by the implementation follow-up:

- [ ] [Bounded label collisions](https://github.com/apache/maka/pull/5198#discussion_r3999052737): validate uniqueness after truncation so long same-name Sessions in different workspaces do not prevent Form publication.
- [ ] [Shared Form Decline action](https://github.com/apache/maka/pull/5198#discussion_r3999052740): preserve the protocol distinction between decline and cancel for ordinary single-select Forms.
- [ ] [Per-assignment status projection](https://github.com/apache/maka/pull/5198#discussion_r3999052741): deduplicate Session labels without dropping statuses for multiple assignments to the same Session.

These are label, shared-component and projection follow-ups; they do not close Slice 7 or change the deferred Work identity/cardinality decision.

## Release gates

- Focused policy, lifecycle, Action Gate, controller, and UI interaction tests pass.
- Full desktop tests, typecheck, production build, lint, format check, and affected knip workspaces pass.
- Navigation/restart and real-model end-to-end tests cover both `answer_here` and delegation.
- Adversarial review finds no second authority, transcript-copying path, self-route, unsafe Stop, implicit create, stale async overwrite, or model-bypass path.
- UI changes include current before/after evidence or a recording.

## Deferred decisions / non-goals for the first milestone

- Whether Work is 1:1 with Session, 1:N over Sessions, or an independent durable entity.
- A new Work database, event store, or lifecycle.
- Replacing ordinary Sessions as execution authorities.
- A single global Coordination Session across Runtime Hosts.
- Cross-Runtime-Host orchestration.
- Copying complete target transcripts into WorkHub.
- Letting a model output directly authorize creation, Stop, tools, permissions, or arbitrary Session IDs.
- Full cross-Work dependency planning or large-scale semantic recall/indexing.

## Existing evidence

- R2.3: 8/11 deterministic routing/interaction scenarios and 7/11 strict real-model end-to-end scenarios on the fixed 10-Session snapshot.
- #3648: 57/57 focused WorkHub tests, 1349/1349 full desktop tests, and 2/2 layout/reconstruction E2E tests.
- #3674 merged as [`464b6939`](https://github.com/apache/maka/commit/464b69391911d3c70d61063b9d71d384eb4a7da6), with the correction-ordering finding resolved and the GitHub CI `test` check passing. The merged PR records 71/71 focused WorkHub tests, 1359/1359 full desktop tests, and 2/2 reconstruction/correction E2E tests. No reproducible R2.4 baseline evaluation result is claimed here.
- #3742 merged the Slice 1 ADR, authority table, ubiquitous language, no-transcript-copying rule, and deferred decisions.
- #3764 merged the Slice 2 per-Runtime-Host Coordination Session lifecycle, reuse/recovery, reserved identity boundaries, Host switching, and candidate exclusion.
- #3798 merged the Slice 3 durable Coordination transcript, tool-free `answer_here`, persisted clarification and routing summaries, navigation/restart continuity, and bounded fail-open reads.
- #3818 merged as [`0e2074a9`](https://github.com/apache/maka/commit/0e2074a9d0574a8f98d51ff93cd8f3a2f47fe6f2), delivering the non-destructive Slice 4 typed Action Gate. Exact-head CI passed (`test` run `32948070394`, including Desktop E2E; `windows_recovery` run `32948070439`). The merged PR records 108 affected WorkHub tests and 1536/1536 full Desktop tests; `replace` and Stop were deferred at that milestone and subsequently delivered by the Slice 5 PRs above.

### Slice 6/8 merge evidence — 2026-09-07

- #4924 merged at [`8c8ad2744`](https://github.com/apache/maka/commit/8c8ad27448e346cfe0589b9ed5415ee50439df46). CI `test` passed on PR head `24bb31595`: [run 34118154658](https://github.com/apache/maka/actions/runs/34118154658).
- Integration head: clean Desktop suite 2390/2390; eight browser runs across both rails, wide/narrow × light/dark; bubble and composer both measured 28px. Build/typecheck/lint/format/architecture/locale/header/inventory/budget checks passed. Updated screenshots are in the PR.
- Seven original inline findings were resolved. The [approval](https://github.com/apache/maka/pull/4924#pullrequestreview-5131373681) covered `61a8b3068`; the subsequent main-conflict integration was validated separately as recorded above.
- Real-model comparative evaluation and real Host admission are not proven by the controller fixture; no Slice 7 result or production strategy selection is claimed.

### Default-path interaction and native acceptance — 2026-09-13

- #5198 merged; CI `test` passed on PR head `d2ad3262a`.
- Local validation recorded in the PR: full build and Desktop typecheck; 2,584 Desktop tests, 438 shared UI tests, 199 affected Host tests, 16 WorkHub Storybook interactions and six native Electron tests passed.
- Real-provider native acceptance exercised same-name target selection, keyboard confirmation, execution only in the selected target, pending-Form reload, passive floating-window display and cancellation. Selection/execution was repeated after rebasing. This establishes those observed paths, not comparative model quality or complete in-flight transcript recovery.
- Target selection now binds the exact Host-offered identity and passes it directly to Action Gate. The old renderer waiting Promise and dedicated pre-admission selector path were removed. Main owns the complete native expansion; fresh submission/rejected Retry remain separate from unknown-admission reconciliation and read refresh.
- This supersedes the earlier statement that a dedicated selector required production wiring of the optional routing experiment. The experiment remains optional by design; no R2.4 vs direct-tool vs staged-routing winner is claimed.