refactor(chat): extract runtime state owners

[bkudiess]

Summary

• Reduce OpenClawChatDataProvider from 7,249 to about 1,700 lines while retaining the same public IChatDataProvider facade for bridge IO, telemetry, events, and composition.
• Move the sole atomic runtime lock into ChatConversationState and split queue, reset, history, presentation, lifecycle, approval, metadata, persistence, mapping, and projection into focused owners.
• Preserve current-main flattened session classification, compacted-history/checkpoint behavior, and compact/inspectable native-tool identity.
• Harden post-reset sends against gateway clock skew: generation-scoped local submission proof, exact-echo correlation, accepted-run/newest-candidate selection, and run-scoped timestamp floors preserve terminal events without admitting unrelated stale user frames.

Ownership transfer

New owner	Responsibility	Locking boundary
ChatConversationState	Timelines, entry metadata, and cross-domain atomic transactions	Sole runtime lock
ChatQueueState + ChatSendQueuePolicy	Queue/local-echo/drain/retry mechanics and decisions	Lock-free substate under root lock
ChatResetState	Reset generations, cutoffs, local-submission proof, accepted/ignored runs, buffered starts, run floors, backfill gates	Lock-free substate under root lock
ChatHistoryState + ChatHistoryLoader	History identity/generations/commit acceptance plus fetch lifetime, coalescing, retry, and rebuild plans	Root accepts immutable plans
ChatPresentationState	Sessions, models, catalog, remembered state, immutable projection inputs	Lock-free substate
ChatLifecycleState	Active runs, aborts, lifecycle sequence, terminal dedupe	Lock-free substate
ChatApprovalState	Bounded approval identity correlation/dedupe	Lock-free substate
ChatMetadataStore + ChatStatePersistence	Tool/attachment metadata and atomic chat-state persistence	Independent focused lifetimes
Mapper/projector/formatting owners	Pure gateway mapping, immutable projection, content formatting	Stateless

No substate owns a second runtime lock or duplicate reset/history generation. Source guards prevent runtime collections or _gate from returning to the provider.

Reset isolation and clock skew

• Local proof is registered before chat.send can complete, then removed by the matching failure/stale/deferred path.
• Apparently pre-cutoff lifecycle candidates buffer only behind recent same-generation local proof.
• Exact gateway echo opens the accepted-run candidate when available, otherwise the newest eligible post-submission candidate; the echo remains deduplicated.
• A run-and-generation-scoped timestamp floor admits only same-run non-user frames at or above the correlated lifecycle/echo floor.
• User chat frames never inherit active-run identity, so unrelated delayed pre-reset user/control messages remain behind the reset cutoff.
• Terminal, reset, reconnect, abort/ignore, and disposal paths clear submission proof and timestamp floors.

Validation

Exact D1 head 59096c38182f07e22bb8980951a9c80828f0c01f on current main aac07abb1fbdaf2d75aa269397f094256188e1b5:

• ./build.ps1: passed
• Shared: 3,412 passed / 32 skipped / 0 failed
• Tray: 2,233 passed / 0 failed
• Focused reset/lifecycle/provider/history/telemetry commands: 2, 37, and 353 passed
• Integration: 19 passed
• Functional UI: 19 passed
• Native UI: 100 passed
• Accessibility: 20 passed
• git diff --check, source-owner guards, conflict markers, UTF-8, and final-newline checks: clean

Real behavior proof

A fresh disposable real-gateway fixture validated exact head 59096c38:

• Reached Ready with compose ready, history loaded, queue 0, and no active turn.
• Called app.chat.reset immediately before app.chat.send and observed reset completion.
• The real send terminalized naturally in 1.040 seconds through the expected no-provider-key final error path.
• The marker appeared exactly once live, once after forced history remount, and once after gateway reconnect: 1 / 1 / 1.
• Gateway transitioned Connecting to Ready; post-reconnect history remained deduplicated.
• The isolated tray profile and WSL distro were removed; shared-profile marker count stayed 0 -> 0; Git remained clean.

Redacted package: d1-user-floor-proof-59096c38-20260806-144358
Manifest SHA-256: a2af2a8f886ba46c3e1185647d9c157e5d488573322d7e7bb4512096e0971fbf

Review

• Two independent full-diff adversarial reviews and a rubber-duck review are clean on the final behavior.
• Review cycles found and fixed concurrent disposal, stale history retry displacement, post-reset terminal loss, stale lifecycle candidate selection, deferred-abort generation races, duplicate echo handling, and stale user-frame admission through a run floor.
• No partial or truncated structured-review result was accepted.

Architecture

Adds authoritative/closed ledger rows and behavioral/source guards for the transaction root, queue/reset/history/presentation/lifecycle/approval substates, history loader, metadata/persistence owners, mapping/projection/formatting owners, and provider residue.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 17, 2026, 7:01 PM ET / 23:01 UTC.

ClawSweeper review

What this changes

The PR splits the tray chat provider’s queue, reset, history, lifecycle, metadata, mapping, and projection responsibilities into focused state owners while retaining the existing provider interface.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open. Current main still has the monolithic chat provider, while this cleanly mergeable branch performs the requested runtime ownership extraction with current-head UI proof and passing checks; it needs final maintainer review for compatibility-sensitive state behavior.

Priority: P1
Reviewed head: 8fa4702987544ed923f5bd7ebf333fe011f7befd

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The current-head proof and broad validation support the patch, with remaining review attention appropriately focused on its large state-boundary change.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): Current-head native UI screenshots and the supplied real-gateway reset, send, remount, and reconnect transcript provide after-fix behavior evidence.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): Current-head native UI screenshots and the supplied real-gateway reset, send, remount, and reconnect transcript provide after-fix behavior evidence.
Evidence reviewed	5 items	Current main does not contain the extraction: The current-main provider is 7,421 lines, while the reviewed head reduces it to 1,800 lines and composes dedicated runtime owners. Reset and event coordination are centralized: The conversation state performs reset, incoming-message gating, and agent-event transitions under its sole runtime lock. Focused ownership guards and behavioral coverage: The added test suite asserts one runtime lock, unique generation ownership, and cross-domain coordination for reset, history, queue, and agent events.
Findings	None	None.
Security	None	None.

How this fits together

The tray chat provider receives gateway chat, lifecycle, and history events, then projects state into the native chat UI. The new owners coordinate sends, resets, history reloads, and terminal events before snapshots reach rendering.

flowchart LR
  Gateway[Gateway chat events] --> Provider[Chat provider facade]
  Provider --> Runtime[Conversation state and reset rules]
  Runtime --> Queue[Queue and lifecycle state]
  Runtime --> History[History loader]
  Queue --> Snapshot[Chat snapshot projection]
  History --> Snapshot
  Snapshot --> UI[Native chat UI]

Loading

Before merge

• Resolve merge risk (P1) - The 26-file extraction redistributes queue, reset, history, and lifecycle state, so a merge requires maintainer confidence that upgrades preserve existing chat behavior beyond green checks.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Runtime extraction scope	26 files, +12,525/-6,585 lines	The refactor redistributes compatibility-sensitive chat runtime behavior across several focused owners.
Production versus tests	production +9,110/-6,438; tests +3,384/-143	The production movement is justified by replacing the provider’s monolithic state with covered owner boundaries.

Merge-risk options

Maintainer options:

1. Approve the extracted runtime boundary (recommended)
   Land the rebased branch after a maintainer confirms the existing chat reset, history, queue, and lifecycle contracts remain acceptable.

Technical review

Best possible solution:

Keep the provider facade stable and land the focused state owners only after a maintainer accepts the reset, reconnect, history, queue, and terminal-event compatibility risk.

Do we have a high-confidence way to reproduce the issue?

Not applicable. This PR refactors established chat runtime behavior rather than reporting a separate user bug.

Is this the best way to solve the issue?

Yes. The focused state owners retain the provider facade and add characterization coverage for the critical ownership and generation invariants.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d67ef5140d13.

Labels

Label justifications:

• P1: The changed code controls active chat sends, reset behavior, history reloads, and terminal lifecycle handling.
• merge-risk: 🚨 compatibility: Existing chat-provider behavior is redistributed across new runtime owners.
• merge-risk: 🚨 session-state: Reset generations, history revisions, queued sends, and active-run correlation cross the new boundaries.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): Current-head native UI screenshots and the supplied real-gateway reset, send, remount, and reconnect transcript provide after-fix behavior evidence.
• proof: sufficient: Contributor real behavior proof is sufficient. Current-head native UI screenshots and the supplied real-gateway reset, send, remount, and reconnect transcript provide after-fix behavior evidence.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. Current-head native UI screenshots and the supplied real-gateway reset, send, remount, and reconnect transcript provide after-fix behavior evidence.

Evidence

What I checked:

• Current main does not contain the extraction: The current-main provider is 7,421 lines, while the reviewed head reduces it to 1,800 lines and composes dedicated runtime owners. (src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs:139, d67ef5140d13)
• Reset and event coordination are centralized: The conversation state performs reset, incoming-message gating, and agent-event transitions under its sole runtime lock. (src/OpenClaw.Tray.WinUI/Chat/ChatConversationState.cs:1251, 8fa470298754)
• Focused ownership guards and behavioral coverage: The added test suite asserts one runtime lock, unique generation ownership, and cross-domain coordination for reset, history, queue, and agent events. (tests/OpenClaw.Tray.Tests/ChatRuntimeOwnersTests.cs:1196, 8fa470298754)
• Current-head proof and validation: The latest collaborator comment reports the rebased head passed build, shared and tray tests, native UI tests, integration coverage, isolated app launch, and current-head screenshots for native tool identity and session routing. (8fa470298754)
• Feature-history routing: History shows prior merged chat work by Barbara Kudiess, Régis Brid, and Ranjesh on the provider, native runtime behavior, and metadata persistence. (src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs, a3c5e0bf6fce)

Likely related people:

• Barbara Kudiess: Prior merged chat-provider history includes command-catalog work, and the reviewed branch owns the current runtime extraction. (role: recent chat-area contributor; confidence: high; commits: a3c5e0bf6fce, 8fa470298754; files: src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs, src/OpenClaw.Tray.WinUI/Chat/ChatConversationState.cs)
• Régis Brid: Feature history attributes core native chat runtime, approval delivery, and multi-segment handling to this area. (role: original native chat runtime contributor; confidence: medium; commits: 5505a85da7df; files: src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs)
• Ranjesh: Feature history includes persisted chat attachment metadata that this extraction moves into the metadata owner. (role: metadata and history adjacent contributor; confidence: medium; commits: 9a3a7a6131a8; files: src/OpenClaw.Tray.WinUI/Chat/ChatMetadataStore.cs, src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain final maintainer approval of the rebased compatibility-sensitive runtime boundary.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (23 earlier review cycles; latest 8 shown)

• reviewed 2026-08-08T14:23:25.360Z sha 59096c3 :: needs maintainer review before merge. :: none
• reviewed 2026-08-08T15:40:02.591Z sha 59096c3 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T00:06:43.446Z sha 59096c3 :: needs changes before merge. :: [P1] Preserve canonical native-tool correlation
• reviewed 2026-08-09T03:17:00.090Z sha 59096c3 :: needs changes before merge. :: [P1] Use the canonical native-tool correlation helper | [P1] Dispatch standalone patch events | [P1] Honor result errors signaled by the gateway | [P1] Keep terminal command and patch item handling | [P1] Accept completed command output without text
• reviewed 2026-08-09T09:27:46.229Z sha 59096c3 :: needs changes before merge. :: [P1] Route native-tool IDs through the canonical helper | [P1] Map error-valued tool results as errors | [P1] Dispatch standalone patch envelopes | [P1] Handle terminal command and patch item frames | [P1] Accept empty completed command output
• reviewed 2026-08-09T11:59:42.852Z sha 59096c3 :: needs changes before merge. :: [P1] Use the canonical tool correlation helper | [P1] Map error-valued tool results as errors | [P1] Dispatch standalone patch envelopes | [P1] Handle terminal command and patch item frames | [P1] Accept empty completed command output
• reviewed 2026-08-09T14:50:43.864Z sha 59096c3 :: needs changes before merge. :: [P1] Normalize tool correlations through the canonical helper | [P1] Honor error-valued tool results | [P1] Preserve standalone patch envelopes | [P1] Handle terminal command and patch item frames | [P1] Accept empty completed command output
• reviewed 2026-08-17T21:52:13.974Z sha 8fa4702 :: needs maintainer review before merge. :: none

[bkudiess]

Added exact-head real gateway proof to the PR body: authenticated app.chat.send, one user echo and terminal lifecycle, real chat.history remount without duplication, canonical gateway stop/start reconnect, and post-reconnect history preservation. The disposable gateway had no OpenAI API key, so the terminal assistant error path is documented rather than misreported as model streaming. All artifacts are redacted and the isolated profile/distro were removed.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31054643311
• Updated: 2026-08-05T22:57:28.524Z

[bkudiess]

Updated exact-head proof and review closeout for 67d8a8b5: real gateway send, terminal lifecycle, history replay without duplication, stop/start reconnect, and post-reconnect history all pass on the new head. #1069 classification is integrated into the projection owner. Final fixes cover concurrent first-wins disposal, stale retry accumulation, and stale retry displacement.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31070036890
• Updated: 2026-08-06T04:01:07.978Z

[karkarl]

Rebased conflict resolution and validation status

The five #1096 commits are rebased cleanly onto current origin/main:

• origin/main: d67ef5140d137a08b4898c5bd6faa79e9f93430b
• rebased local candidate: 8fa4702987544ed923f5bd7ebf333fe011f7befd
• 5 linear commits, 0 merge commits, original 26-file scope
• exact origin/main merge base and ancestor
• refactor(chat): extract composer ownership #1098 head is not an ancestor
• git diff --check passes and the local worktree is clean

After explicit creator approval, the remote branch was updated with force-with-lease pinned to old head 59096c38182f07e22bb8980951a9c80828f0c01f. The remote branch, tracking ref, and PR head now exactly match 8fa4702987544ed923f5bd7ebf333fe011f7befd. GitHub reports MERGEABLE / CLEAN, and the exact-head CI rerun passed.

Validation

Command	Result
.\build.ps1	Pass
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore	3,698 passed, 32 skipped, 0 failed
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore	2,537 passed, 0 skipped, 0 failed
dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj -r win-arm64 --no-restore	136 passed, 0 skipped, 0 failed
OPENCLAW_RUN_INTEGRATION=1 plus A2UICanvasIntegrationTests	1 passed, 0 skipped, 0 failed
NativeToolIdentityScreenshotProofTests	1 passed, synthetic accessibility-fixture coverage only
SessionTitleBehaviorProofTests	1 passed, synthetic accessibility-fixture coverage only

The exact-head CI rerun also passed the repository hygiene lane, setup-connect E2E, network-recovery E2E, revocation-recovery E2E, x64 and ARM64 builds, CodeQL, and Copilot setup. The tray virtualization test ChatTimelineVirtualizationProofTests.ModerateScrollUpDuringSettleTimer_IsNotRepinned passed on the rerun.

Real behavior proof

The earlier fixture screenshots remain withdrawn. The replacement proof below is from the production app at exact PR head 8fa4702987544ed923f5bd7ebf333fe011f7befd, not an accessibility test host.

An isolated tray profile copied only the local gateway registry and gateway identity, with notifications, telemetry, and node mode disabled. The app launched with:

.\run-app-local.ps1 -NoBuild -DataDir <isolated-proof-profile> -AllowNonMain

The live proof then verified:

1. winnode --list-tools advertised all five production app.chat.* commands.
2. app.connection.status reported Ready, operator connected, identity.DeviceToken, node mode not intended, and local MCP running.
3. app.navigate {"page":"chat"} opened the production Chat page.
4. app.chat.send accepted a unique proof thread through the native chat provider.
5. The completed app.chat.snapshot reported Connected, entries User,Assistant, turnActive=false, the expected assistant reply, and queue.totalCount=0.
6. After restarting the isolated app, the same proof thread replayed from gateway history with historyLoaded=true and both entries present.