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

[ARE404]

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. 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 WorkHub input resolves to one of four dispositions:

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.

Delegation and safety

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

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

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:

• feat(desktop): add conservative WorkHub session router #3497 merged the conservative R2.3 routing MVP.
• fix(desktop): prevent WorkHub result overlap #3645 merged the WorkHub result-layout fix.
• feat(desktop): rebuild WorkHub from Session transcripts #3648 merged bounded reconstruction of ordinary Session transcripts.
• feat(desktop): preserve WorkHub routing context #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: Slices 1–4 are merged through #3742, #3764, #3798, and #3818. Slice 4 deliberately stops at non-destructive admission; durable delegation linkage and destructive correction remain Slice 5 work.

Slice 0 — Close and preserve the deterministic baseline

• Keep the fixed 10-Session evaluation snapshot and versioned routing-policy IDs.
• Preserve deterministic routing, clarification, correction, waiting protection, and expected-Turn Stop tests from feat(desktop): add conservative WorkHub session router #3497 and feat(desktop): preserve WorkHub routing context #3674.
• Resolve feat(desktop): preserve WorkHub routing context #3674's overlapping-correction ordering finding before merge.
• Update feat(desktop): preserve WorkHub routing context #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.

• Add an ADR for one WorkHub Coordination Session per Runtime Host.
• Define Coordination Session, ordinary Session, disposition, delegation, Action Gate, and projection in the domain language.
• Record the authority table and the no-transcript-copying rule.
• 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.

• Introduce a special Session role/kind using the existing Session substrate.
• Lazily create and durably resolve exactly one Coordination Session per Runtime Host.
• Reuse it across renderer/app/Runtime Host restarts.
• Hide it from ordinary Session navigation and exclude it from all route candidates.
• Define recovery, feature-disable, Host-switch, archive/delete, and missing/corrupt-session behavior without losing ordinary Sessions.
• 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.

• Render WorkHub from the Coordination Session transcript while continuing to project ordinary Session status read-only.
• Persist user messages, assistant answers, clarification turns, and coordination summaries in that transcript.
• Support ordinary Q&A through answer_here without creating or selecting an ordinary Session.
• Preserve the conversation across navigation into an ordinary Session, return to WorkHub, and restart.
• 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.

• Add a typed result contract for answer_here, delegate_existing, create_new, and clarify.
• Expose only bounded valid Session candidates; a model must not invent Session IDs.
• 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.
• Keep tool and permission ceilings owned by the target ordinary Session; the closed WorkHub protocol cannot widen either ceiling.
• Add destructive replace, expected-Turn Stop ownership, and risk confirmation only after Slice 5 persists delegation/action linkage across Runtime Host restart.
• Make create_new the only disposition allowed to create an ordinary Session.
• Return safe clarification or an actionable error when the proposed action is rejected.
• Test rejected-action paths independently of model behavior.

Production natural-language correction is classified before explicit creation. When a prior delegation/focus exists it fails closed before a second root; without focus, the same explicit creation language still reaches create_new. The legacy R2.4 destructive correction path remains test-only.

Exit: no routing/model strategy can directly acquire execution authority or bypass Runtime safety for the non-destructive Slice 4 action set. Destructive authority remains gated on Slice 5 linkage.

Slice 5 — Linked delegation and execution feedback

This is the next implementation boundary. Persist delegation/action linkage before adding replace or Stop so authorization and recovery survive Runtime Host restart and the non-atomic Stop-to-submit seam.

• Delegate concrete work to an existing or newly created ordinary Session without copying its full transcript.
• Persist the bounded coordination-to-execution linkage through existing Session/Turn/event mechanisms.
• Project target acceptance, running, waiting, completion, failure, abort, and recovery back into WorkHub.
• Define and implement the first response contract: immediate acknowledgement, wait-for-result, or an explicit hybrid.
• Support natural-language correction while preserving user order and stopping only the WorkHub-owned expected Turn.
• Delegate ordinary stop/cancel behavior to the authoritative target Session.

Exit: a user can delegate, observe, correct, stop, and resume work from one persistent coordination transcript.

Slice 6 — R3 routing experiment platform

• Put R2.4, R3-A, and R3-B behind the same versioned strategy interface and Action Gate.
• Keep R2.4 baseline fully deterministic for disposition and target selection.
• Implement R3-A model-direct: the model chooses a disposition and, for delegation, one bounded valid Session candidate.
• Implement R3-B model-gated-R2.4: the model chooses the disposition; R2.4 selects the target only for delegate_existing.
• Disable R2.4 auto-creation inside the R3-B delegation branch.
• Run all strategies with the same model/reasoning configuration, fixed Session snapshot, bounded Session summaries, WorkHub transcript prefix, Runtime state, and inputs.
• Repeat model-backed runs enough times to measure consistency rather than reporting a single lucky run.

Exit: all three strategies can be compared on the same end-to-end coordination shell without changing execution safety.

Slice 7 — Evaluation, strategy selection, and rollout

• 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-action rate, unnecessary clarification/creation, correction recovery, ordinary-answer quality, multi-turn consistency, latency, tokens, and cost.
• 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

• Add Work filtering derived from ordinary Sessions.
• Add an Anchor Rail derived from coordination focus, delegations, and target Session state.
• Keep projection refresh generation-safe and bounded.
• Verify that neither enhancement becomes a new lifecycle or execution authority.

Exit: the unified conversation remains understandable as the number of ordinary Sessions grows.

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.
• feat(desktop): rebuild WorkHub from Session transcripts #3648: 57/57 focused WorkHub tests, 1349/1349 full desktop tests, and 2/2 layout/reconstruction E2E tests.
• feat(desktop): preserve WorkHub routing context #3674 merged as 464b6939, 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.
• docs(workhub): record coordination session architecture #3742 merged the Slice 1 ADR, authority table, ubiquitous language, no-transcript-copying rule, and deferred decisions.
• feat(workhub): add coordination session lifecycle #3764 merged the Slice 2 per-Runtime-Host Coordination Session lifecycle, reuse/recovery, reserved identity boundaries, Host switching, and candidate exclusion.
• feat(workhub): persist Coordination conversation (Slice 3) #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.
• feat(workhub): add typed action gate #3818 merged as 0e2074a9, 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 remain intentionally deferred to Slice 5.

[0xMudit]

I'd like to contribute to this tracking issue.

How I can help

I'm interested in working on the smaller, self-contained sub-tasks within this tracking issue, such as:

• Individual integration points or lifecycle hooks
• Documentation of the new coordinator pattern
• Tests for per-Host session isolation

Please let me know which specific sub-tasks would be most helpful to pick up first.