This document is the living source of truth for the architecture refactor that decomposes the repository's god objects. It is required reading before you touch any file listed in the ledger below.
Its job is to stop the refactor from silently regressing: when a PR moves a responsibility out of a god object, it records the move here and (for high-regression closures) adds a guard test. A later PR that tries to move the work back then shows up as either a visible ledger edit or a failing test.
See AGENTS.md → "Architecture Guardrails" for the hard rules, and the full
multi-PR refactor plan for the reasoning behind each boundary.
- Before editing a file named in the ledger, read its row(s). Do not add
back anything a row marks
closed. - When you extract a responsibility, in the same PR:
- Flip/add the ledger row for the new owner to
authoritative. - Mark the vacated responsibility in the old owner as
closed. - Update the "when you touch file X, extract toward Y" guidance below.
- Add a guard test for the closure when a silent revert would be dangerous.
- Flip/add the ledger row for the new owner to
- Prefer behavioral/golden guards. Use
source-shapeguards only for a concrete prohibited pattern (a banned helper signature, a forbidden direct constructor call), never for broad architectural wishes, and always with aretirement_condition.
- View (XAML + code-behind): layout, named-control wiring, lifecycle event forwarding, minimal WinUI-only adapters. No gateway JSON parsing, no polling loops, no settings mutation, no imperative row factories.
- ViewModel / Presenter (
OpenClaw.Tray.WinUI/ViewModels,.../Presentation): observable state, commands, pure projection. WinUI-free where practical - noMicrosoft.UI.Xaml, noApplication.Current, noWindow/Frame/Brush/Color, no concreteSettingsManager. Unit-tested. - Service: IO, gateway calls, registry/settings persistence, timers, process execution, WebSocket/MCP hosting. No UI types. No background work started from constructors.
- App (
App.xaml.cs): composition root and top-level lifecycle only. - Shared mutable domains: one observable service/store owns each persisted domain. View models consume snapshots and field-scoped or compare-and-swap mutations; they never own backing files, concrete managers, file observers, or parallel mutable caches.
These are the canonical homes. Do not reintroduce private copies elsewhere.
The tray icon's primary activation opens or focuses Workspace chat for configured
profiles, including while disconnected. TrayController invokes its chat callback and
App composes that callback with the WindowManager chat route. Explicit
Connection menu actions retain their settings route; opening Workspace does
not bypass chat authorization or pairing requirements.
StartupSetupState owns first-run eligibility from saved gateway configuration
or local MCP mode, independently of current connectivity and node pairing.
WindowManager applies the same eligibility to Workspace activation, including
forwarded launches and tray clicks: an unconfigured profile opens or refocuses
setup instead of creating Workspace behind it. Explicit companion routes remain
available for advanced connection setup.
Workspace footer identity uses the native macOS chat sidebar at
882e4a1
and its person label,
as a reference, except for the shared gateway-owner profile: its footer shows
only the saved first name, or localized Owner when unnamed, without a shared-owner
marker. This is display-only; anyone using the shared Gateway credential still
appears as this profile. The label never uses the shared owner's email or profile
id. Any other profile shows its first name,
then email, then profile id, and localized Owner is shown while no profile is
known (connecting, disconnected or a failed read). First name means the first
whitespace-delimited part of the saved display name; the full profile name
remains unchanged for avatar initials and other profile consumers. Email and
profile-id fallbacks are not shortened. The second
line is omitted; connection status overlays the avatar with a theme-aware separating stroke and remains in the tooltip and UIA HelpText. Like macOS, there are no separate loading, unavailable
or unnamed labels and no profile setup action. WorkspaceIdentitySource reads
users.self profile fields (displayName, first emails entry, id) and the
Gateway-served avatar, never an agent identity or Windows account.
Chat and Settings show this in the same WorkspacePaneFooter; the Settings
compact rail keeps the name in the account button's tooltip and UIA Name, and status
in its tooltip and UIA HelpText. The account menu's profile header repeats the label
with the profile's first email as its second line (omitted when the label already is
that email); the shared owner never shows one.
WorkspaceWindow decodes the avatar once per image, fences late decode results,
and applies the same bitmap to all footer instances and queued chat rows. ChatPage
retains these presentation inputs for a later mount; an active Reactor host
reconciles profile changes without replacing the composer or owning a profile fetch.
A footer created later receives
the current bitmap immediately; WorkspacePaneFooter only applies it to its native
PersonPicture and owns no profile fetch or decode lifetime.
sessions.changed with reason profile-identity invalidates the profile through
GatewayService/AppState; ordinary session updates do not trigger profile RPCs.
The window owns the display source lifetime, and stale results cannot survive
disconnect, replacement, or close. This cache is not used for authorization.
The release updater is optional. Store, development and Debug builds skip it
before any vendor implementation is created. For production release checks,
UpdateBackendLoader invokes a non-inlined factory so dependency resolution
failures (including Windows application-control rejection) cannot fail App type
initialization. A load failure disables automatic updates for that process,
records a warning, and publishes a failed update status with recovery guidance.
A manual update check also offers the
official releases page.
The app remains usable; restarting after repairing the dependency permits a
new attempt. This boundary does not change release signing or Windows policy.
| Concern | Canonical owner | Status |
|---|---|---|
| Test temp directories | OpenClaw.TestSupport.TempDirectory |
authoritative |
| Bounded audio child-process wait and disposal | BoundedProcessWait owns the supplied Process, including deferred disposal after its kill worker finishes; callers must not dispose it on bounded cancellation return |
authoritative |
| Test env var save/restore | OpenClaw.TestSupport.EnvironmentScope |
authoritative |
| CLI stdout/stderr/env capture | OpenClaw.TestSupport.CliHarness |
authoritative |
| Loopback MCP server for tests | OpenClaw.TestSupport.FakeMcpServer |
authoritative |
| Authenticated MCP HTTP client for app fixtures | OpenClaw.TestSupport.McpClient |
authoritative |
| Synthetic Gateway protocol/scenarios, including the authenticated owner-avatar HTTP route | OpenClaw.TestSupport.Gateway.FixtureGatewayServer + GatewayScenario |
authoritative |
| Interactive synthetic Gateway state and run lifetime | InteractiveGatewayRuntime owns memory-only sessions, transcripts, idempotency, runs and decisions; FixtureQuestion validates question records and FixturePlayback owns host-side pacing. No production provider or page bypass |
authoritative |
| Fixture-backed app profile/process lifetime | OpenClaw.GatewayFixtureHost.GatewayFixtureProfile + GatewayFixtureRun |
authoritative |
| Automations editor draft and save lifetime | AutomationsRoot owns EditorSession form, revision source, validation and save feedback plus an application-lifetime in-memory draft bank scoped by Gateway and route agent, keyed separately by new, copy:id and edited id; Cancel and native dialog dismissal retain edits, Discard resets only its draft, and root callbacks admit only the active editor nonce. Save reads that current nonce-bound session before validation and submission, even when an input update precedes the next render (AutomationsEditorSaveTests); AutomationTextInput binds native Text properties to that owner without deferred counter suppression, preserves pending input on same-value renders and applies deliberate replacement/reset values |
authoritative |
| Automations page anatomy and inline expansion | PageResponsiveLayout owns pure shared page-host width tiers and content geometry; shared PageHero in Presentation/Adapters/PageHero.cs owns native rendering of the responsive accent-wash header, summary tiles, transitions and reveal/highlight behavior (its existing OpenClawTray.Presentation namespace is retained for caller compatibility); AutomationsRoot exposes its localized page marker on the retained native ScrollView, not the decorative icon Border; it renders inline failure badges, grouped agenda and inventory, keeps independently expanded native Expander rows with non-interactive headers and sibling chat actions plus scoped run snapshots, and scrolls/focuses only explicit reveal targets; AutomationDetail renders each expanded row's dynamically overflowing native CommandBar and definition/results columns; AutomationEditor is hosted in a native ContentDialog |
authoritative |
| Automations split-pane and page-local Back navigation | Closed in AutomationsRoot; expanding a row does not replace the inventory or add a Back button |
closed |
| Automations gateway-wide overview and navigation attention | AutomationsOverviewSource owns host-lifetime enabled/disabled paging, ID deduplication and the exact IsFailing attention count; the All agents page and shared navigation observe the same snapshot. Refresh, failure, disconnect, client identity or authenticated socket epoch changes invalidate the nullable count, including before queued notifications. No unsolicited read precedes the first explicit global page refresh; the source owns global cron-event refresh afterward |
authoritative |
| Page-local gateway-wide overview/cache | Closed in AutomationsStore and CronPage; the live page borrows the host source and neither starts a second global reader nor disposes it on page unload |
closed |
| Automations agenda completeness and local dates | AutomationsStore retains server-scoped enabled/disabled overview reads for agent filters, including missing owner metadata; All agents consumes AutomationsOverviewSource without projecting scoped results globally. CronAgenda groups only reported instants by exact local dates, with failed past runs first; the agenda measures its own ActualWidth, stacks below 820 DIPs and reduces collapsed row budgets below 1000 DIPs without resetting expanded groups; offline dates use the last sync instant; RevealAsync loads through a target's real inventory row, selects it only when the Gateway returns it and otherwise raises the informational JobUnavailable notice without a phantom selection |
authoritative |
| Automations confirmation and result presentation | AutomationsRoot owns shared modal anatomy, explicit Cancel initial focus with a named accent primary action and page-owned result toasts; errors remain until explicitly closed and are not mirrored by CronPage into global notifications; CronPage supplies the connected Gateway display name from the current connection snapshot; AutomationDetail supplies exact job facts and retains store mutation/revision guards; AutomationRunResult renders only the three reachable recent results and owns the inert link/image/HTML policy for full results, reusing ChatMarkdownSanitizer and ChatMarkdownPresentation without adopting chat navigation; errors remain selectable literal text |
authoritative |
| Native full-history UI and its view/filter/paging state | Closed in the former AutomationRuns component and AutomationsStore; AutomationDetail retains recent results and sends All runs through the existing web handoff. Protocol queries and selected-job result snapshots remain live. InlineInventory_DoesNotReintroduceSplitNavigation guards the closure until mounted navigation proof covers absence of the old surface |
closed |
| Locally accepted automation run lifetime | AutomationsStore owns a distinct invocation before acknowledgement and retains its accepted RunId; only a matching job and RunId history entry completes it. Independent list timestamps cannot settle local runs; ID-less acknowledgements retain their owner-bound safety timeout or confirmed removal/disconnect. Observed-only running rows still reconcile from the list |
authoritative |
| Child-local Automations draft ownership | Closed in AutomationEditor; its controls update the root-owned session so reconnect/layout remounts cannot reset the draft |
closed |
| Automations inventory scope and web handoff | AutomationsStore owns the agent filter (route agent initially, null for every agent) and fences list, stats and run reloads; CronPage hands off to the web through IAppCommands.OpenDashboard with CronProtocol.WebPath |
authoritative |
| Automations Hub-search reveal | SettingsShellView.RevealSearchTarget fences page, client, handshake and search generation, then calls CronPage.RevealSearchJob; AutomationsRevealChannel hands the job id to the mounted AutomationsRoot (or holds the newest request until it attaches) and AutomationsStore.RevealAsync selects the real inventory row, widening a specific agent filter to All agents only when the job is elsewhere. A missing job shows the in-page Search_TargetUnavailable notice like ConfigPage, never a global notification |
authoritative |
| Automations basic-edit preservation | CronJobForm maps Main to systemEvent/text and other editable session targets to agentTurn/message without losing entered text; it loads every saved setting and preserves unshown ones; unchanged active hours and idle-only fields are omitted from update patches for released Gateway compatibility. Native validation explicitly directs timing changes and copies with inherited timing to the web without discarding the draft. Owner delivery creation, copying and routing changes also stay web-managed because the released Gateway does not accept delivery.target and method advertisement does not negotiate that field; unrelated edits omit an unchanged saved delivery object rather than resending or rewriting it. The editor retains the routing and offers localized web guidance; event, process and command definitions are omitted from patches and changed on the web |
authoritative |
| Explicit fixture context and host-effect isolation gate | OpenClaw.Shared.GatewayFixtureIsolation |
authoritative |
| Passive fixture chat-render acknowledgement | GatewayFixtureRenderObservation (pure metadata) + ReactorChatComposer (UI applicator) |
authoritative |
| External chat session selection without remounting | WorkspaceWindow.SelectSession owns destination/sidebar/history selection; MountedReactorChat forwards to ChatComposerController's existing root selection handoff. Its selection revision fences delayed lifecycle navigation. Workspace invalidates that revision when committing a destination, before deferred chat rendering; ChatPage also invalidates it on unload and retains initial-mount fallback for an unready or replaced provider |
authoritative |
| Composer-created Workspace session selection | ChatComposerController captures the previous effective thread before the root handoff; ChatPage.SessionSelected forwards both keys to WorkspaceWindow.OnChatSessionSelected. WorkspaceNavigationHistory.SelectChatSession binds an unresolved initial Home entry to that previous cached/default conversation before adding the new entry. Draft-to-Gateway promotion replaces the local key in Current, ChatDestination, app destination, Back and Forward history before the adapter refreshes selected-agent/sidebar controls. A newer page/session navigation fences a late lifecycle completion without discarding the created session from the catalog. Same-key echoes are idempotent |
authoritative |
| Workspace agent creation | AgentCreationDialog owns inputs and feedback; AgentCreationService owns permission checks and response-aware gateway creation |
authoritative |
| Workspace Pages shortcuts: catalog, tag normalization, availability and per-Gateway scope key | PinnedPages (6 native destinations from the Settings catalog; Home, Debug, Settings and the entire This Computer group (local-ai, voice, permissions, sandbox) excluded). These pages remain accessible normally in Settings. Removed or unknown stored tags, including the retired bindings, channels, agentevents, and skills routes, remain persisted but do not appear in the picker or effective shortcuts. Known selected pins remain visible across connection states. WorkspaceWindow.Pins applies IsEnabled using HubPageRegistry.IsGatewayPageTag + GatewayNavVisibilityDebouncePolicy immediate availability: unavailable pins disable without replacing their keyed rows and re-enable on reconnect; Connection remains enabled. The picker remains configurable offline. Focus ownership is captured before native disabling; a focused or saved-focus pin that becomes unavailable falls back to Customize without navigating. Invocation rechecks live availability before recording sidebar intent or routing, including queued stale UI actions. Current Settings-page pruning remains a separate policy. Persistence is local only, SettingsManager.PinnedPagesByGateway keyed by GatewayRegistry.ActiveGatewayId (no sync, no SettingsSaved); WorkspaceWindow.Pins reconciles keyed rows through PinnedPageRows + WorkspaceItemsSync.Arrange (unchanged pins keep their row; an actually removed focused row also falls back to Customize) and routes items through OpenSettings(route, embedded: true) (one history entry; the page renders full-bleed beside the sidebar via WorkspaceDestination.Embedded and SettingsShellView.ContentOnly, without Settings' own section list or header; in-page links to other sections fall back to the full Settings view). Hiding that section list does not change the saved HubNavPaneOpen: only SettingsShellView.OnNavPaneToggleButtonClick saves it, and ContentOnly reapplies it when the list returns (GatewayFixtureUiTests.SettingsPane_KeepsToggleChoiceAcrossPinnedPagesAndRestart). PinnedPages_DisconnectRetainsDisabledRowsAndFocus_AndReconnectEnablesSameRows covers the native lifecycle; QueuedPinInvocation_RechecksAvailabilityBeforeRoutingOrRecordingSidebarIntent guards the stale-event boundary until it can be exercised through native event injection without a production test hook |
authoritative |
| Native Dashboards shortcut extension | PinnedPages adds standalone Dashboards to the six Settings shortcuts. Dashboards is not in the Settings section list. A scope without a saved choice defaults to Dashboards; customized and explicit empty lists remain unchanged. WorkspaceDestination.Settings enforces standalone presentation for every Dashboards route, including session links and commands |
authoritative |
| Dashboard fresh-day selection | Shared DashboardGalleryPolicy.FreshToday owns local-calendar-day bounds, inventory thresholds and shelf ordering. The native gallery consumes that projection; deterministic DashboardGalleryPolicyTests.FreshToday_* cover midnight, invalid timestamps and shelf limits without a WinUI process |
authoritative |
| Native-local Fresh today selection | Closed in DashboardsPresentation; the shared gallery policy owns selection, while native presentation retains localized labels and layout |
closed |
| Workspace pin selection synchronization | WorkspaceWindow.UpdateNavigationSelection applies the current destination under the existing _updating guard; OnPinItemInvoked ignores guarded callbacks before recording sidebar activation. WinUI can synchronously invoke and reject a nonselecting item from its SelectedItem setter, so the projection temporarily enables SelectsOnInvoked and restores it in finally. User pin invocations remain nonselecting. Pins sit immediately after Home, with no Pages heading or empty hint; the localized customize button uses native Symbol.Edit in a 12-DIP Viewbox with theme-aware secondary foreground, within its unchanged 40-DIP hit target. Zero padding and a Home-only compensation for the native presenter's trailing gutter align it with Sessions + without replacing its template or animations. A native separator precedes Sessions. GatewayFixtureUiTests.PinnedPages_SelectionCallbacksDoNotReinvokeNavigation exercises real native activation, repeated selection and Back/Forward; HomeSidebar_CustomizeDoesNotNavigate_AndHomeRestoresCanonicalConversation covers right-edge alignment and the customize/Home boundary; WorkspaceSessionLayoutTests.CustomizePencil_FitsInsideNativeButtonWithRoundingRoom protects native Light/Dark icon containment. The source guard remains until that native regression is mandatory in the local closeout |
authoritative |
| Preparing the pinned-page host | WorkspaceWindow.Pins.QueuePinnedPageHostPreparation prepares an unbound Settings XAML shell at low dispatcher priority after a pin preference changes. It rechecks window lifetime, shell existence and current Gateway pin scope before preparation. EnsureSettings consumes it and binds current state at invocation; window close disposes any unused shell. Preparation does not establish Settings agent identity or subscriptions, select or initialize a page, change history, cache additional pages, or change native transitions. GatewayFixtureUiTests.PinnedPages_NativeSwitchTiming records click-to-visible timings and checks that preparation and repeated page visits preserve the chat draft; the source guard protects the preparation boundary and animation contract until equivalent native lifecycle coverage is mandatory |
authoritative |
| Workspace owner display identity | WorkspaceIdentitySource reads the current operator's users.self profile (trimmed name, else first non-blank email, else profile id, matching the macOS sidebar label; IsSharedOwner marks the gateway-owner profile and SharedOwnerName keeps only its saved trimmed display name) and, for every valid profile as on macOS, a Gateway-served avatar through OpenClawGatewayClient.ResolveUserAvatarAsync, which reuses the existing authenticated media HTTP lease (the lease's fixed Gateway host, header auth, no redirect, 1 MB cap, no SVG) and refuses a blank, . or .. profile id, or an id or revision over 512 characters, before any request; the Gateway avatar route owns upload, GitHub and Gravatar precedence, so the client does not pre-filter on hasAvatar or email; avatar failure never clears the name; the avatar request has one end-to-end deadline covering headers and body (OPENCLAW_USER_AVATAR_TIMEOUT_MS, default 15000) and the users.self read waits for its response for at most OPENCLAW_USER_SELF_TIMEOUT_MS (default 12000, counted from when the request has been sent); a timeout is a failure, and caller or connection cancellation stays silent; an explicit profile invalidation (SelfProfileRevision change) or connection change cancels the current attempt through one per-attempt linked token, so a stalled users.self read or avatar never delays the refreshed identity (the known name stays visible meanwhile; the request API takes no token, so an abandoned users.self read is left to the client's own request handling while its result is fenced and its late fault is observed); ordinary presence refreshes never cancel or restart the current attempt (they coalesce into one follow-up read), never return a known profile to Owner, and keep the current image for an unchanged profile id and revision without refetching; every settled avatar outcome (image, not found, unsupported, unauthorized or failed) is remembered per profile id and revision, so a failed avatar stays as initials until the revision changes, an explicit invalidation retries it, a failed users.self read forgets the outcome, or the connection changes (no timer-based retry), and an unresolved (cancelled) attempt is never remembered or treated as done, so the next refresh retries it; a failed users.self read settles (reports its category and clears the profile, so the footer shows Owner) instead of retrying on a queued ordinary refresh; GatewayRequestErrors exposes only codes from fixed protocol lists (anything else becomes UNKNOWN; local refusals carry none) and IdentityFailure classifies them without claiming a cause: NotReady/Timeout/Unavailable retry on the next lifecycle event; Forbidden/InvalidRequest/Unknown/MalformedReply/ServerMissingScope stay suppressed until invalidate or connection switch; ServerMissingScope is a FORBIDDEN reply carrying the fixed MISSING_SCOPE detail (scope names never captured) and a detail-less Forbidden stays unattributed; LocalScopeGate is reported once per connection when the local scope gate skips users.self; WorkspaceWindow applies WorkspaceIdentitySource.FooterLabel (shared owner: saved first name only, else localized Owner, never its email or id and no shared-owner marker; otherwise the profile label or Owner), plus native PersonPicture (initials from the profile label, never from Owner) |
authoritative |
| Chat and Settings pane footer (account, Dashboard, bell) layout, compact rail, and Chat title-bar actions | WorkspacePaneFooter owns layout and control application only; WorkspaceWindow is the single applicator of identity, connection, badge, account menu and Dashboard command for the Chat, title-bar and Settings instances; WorkspaceFooterPlacement decides title-bar visibility (an embedded pinned page hides the Settings pane, so the Chat sidebar footer serves it) |
authoritative |
| Dashboards history-band viewport | DashboardsPage implements ISettingsPageContentInset, retaining allocation before mounting and forwarding it to DashboardsPageState. Gallery, board and disconnected content move their scroll viewport, not the page frame or copy-notice overlay. The shared Settings page history-band owner below supplies the inset; page width tiers never change shell embedding, pane preference or Escape behavior. Mounted DashboardWidgetCellTests retain page inset and resize coverage; SettingsPageInsetTests exercises the native shell allocation without remounting |
authoritative |
| Account menu contents and routing | WorkspaceAccountMenu (pure, unit-tested) projects the active Gateway name, status and version (version and the profile header follow the operator channel, not the aggregate state), saved Gateways (active first), Retry now (an active Gateway that is neither live nor pending), and the Companion update badge (UpdateCommandCenterInfo.IsUpdateAvailable; Settings then opens About). WorkspaceWindow.PopulateOwnerMenu rebuilds the native MenuFlyout on each open: profile header (Dashboard profile), Gateway submenu (switch through GatewayConnectionManager.SwitchGatewayAsync exactly as the Connection page's saved-gateway Connect, Add gateway through ConnectionPage.BeginAddGateway, which keeps an Add or Edit form already in progress, Reconnect, the shared status flyout, Connection settings, Dashboard Gateway settings), Settings (Ctrl+,, hidden while the row opens About), Pair a device (Dashboard Devices via /nodes), and Help & about. The /profile, /nodes and /config Dashboard aliases are unversioned because every released Gateway from v2026.8.35 through v2026.11.1 defines them in ui/src/app-route-paths.ts. AccountMenuItem and Themes/AccountMenuResources.xaml only add the second line, badge and picture to native menu templates. The footer avatar's update dot mirrors the same badge state |
authoritative |
| Top-level account-menu Usage, About, Get apps, Connection timeline and Connection status rows | Closed in WorkspaceWindow. Usage stays in Settings navigation and search; About, Get apps and Connection timeline live in Help & about; Connection status lives in the Gateway submenu. WorkspaceNavigationTests.NativeFooter_DashboardAndNotificationsAreIndependentAndRightOfOwner guards Usage |
closed |
| Settings width-dependent chrome | Superseded by the canonical shared foundation. Do not restore width-driven embedding, temporary narrow-pane preference, or Escape-to-collapse in SettingsShellView / WorkspaceWindow. The destination owns embedding, the user's saved choice owns pane state, and window-owned Back to app / Escape owns leaving Settings. Page-responsive sizing remains page-owned; history allocation uses the minimal policy below |
closed |
| Systems shell inset presentation | PageResponsiveLayout owns pure shared page-host width tiers and content geometry; shared PageHero in Presentation/Adapters/PageHero.cs owns native rendering of the plain responsive header, summary tiles, transitions and reveal/highlight behavior (its existing OpenClawTray.Presentation namespace is retained for caller compatibility). Header copy and actions remain fixed Grid siblings across width tiers; the adapter changes placement only, never action parentage. SystemsPage implements ISettingsPageContentInset through its retained SystemsViewport, independent of SystemsController. SystemsPageView subscribes to inset changes and re-reads after subscribing, applying inset only to the keyed ScrollViewer viewport. Its full-frame root, dialogs and feedback overlays do not move; the shared header scrolls with inventory and there is no full-page backdrop. Loading/error/disconnected content uses the same scroll allocation. SystemsViewportTests protects notification/pre-mount retention and no controller/remount calls; SystemsPageProofTests.ShellInset_UpdatesRetainedScrollAtConstantWidthWithoutMovingRoot protects retained controls and zero reset. Hero_StateMatrixRetainsFocusAndGeometryAcrossMountedWidths protects original Add/action-host/Grid identities and actual focused-object continuity across startup and both resize directions. Native execution/visual proof remains required |
authoritative |
| Tracked Sessions publication | GatewayService captures the client generation and canonical SessionMutationConnectionEpoch, then rechecks identity, generation, connection and epoch inside the dispatcher before writing the existing AppState.Sessions array and pruning previews. Status/auth callbacks retain their independent identity/epoch guards. No second admission layer, mirrored freshness epoch or unused attention aggregate lives in AppState. GatewayServiceSessionPublicationTests exercises queued publication, client replacement, same-client reattach/reconnect, disconnect and current/null-epoch compatibility through the actual dispatcher. Systems hero counts remain page-scoped inventory/pairing projections |
authoritative |
| Adaptive auxiliary Settings presentation | Each native page applies allocated-width layout without changing its data owner: Config measures its editor grid at 728 DIPs, retains tree/detail draft controls and constrains preview splitters; Local AI, Default Model, Voice, Notifications and Diagnostics stack action rows below 720 DIPs. SchemaConfigEditor stretches generated fields instead of forcing fixed/minimum widths. AdaptiveSettingsLayoutSourceTests and AdaptiveAuxiliaryRoutesSourceTests protect prohibited remount, data mutation and fixed-width patterns; retire these source guards when populated native narrow-viewport proof covers the same fields, selected agent, focus and actions |
authoritative |
| Settings footer status pill and footer Diagnostics/Settings routes; inline per-window account and bell footer controls | Closed in SettingsShellView and WorkspaceWindow.xaml; host WorkspacePaneFooter. General, Diagnostics and About live in "System"; Connection is first under "Gateway"; notification preferences live inside General; status is the account dot/subtitle and the account menu's Gateway row and submenu status row |
closed |
| Search shortcut pressed while the search flyout is still closing | DeferredFlyoutShowState (pure, unit-tested) decides; FlyoutShowRequest adapts flyout events and replays the owner's open path after Closed (WorkspaceWindow.OpenCommandCenter; Settings replays through the host's CommandCenterRequested so modal-dialog deferral applies). Owners cancel queued reopens when their section hides or closes |
authoritative |
| Shared native command execution | HubCommandExecutor executes typed navigation-only search targets through Workspace navigation and the existing Dashboard launcher. Legacy command callers retain settings-store toggle handling; search never emits a toggle |
authoritative |
| Shared native command-catalog inputs | HubCommandCatalog adapts app state/localization and HubPageRegistry metadata into navigation search items. The registry supplies localized destination label keys and FluentIconCatalog glyphs for search, independently of legacy command wording/emoji; old titles remain search aliases. HubSearchCatalog.Navigation groups aliases by canonical destination, retaining their searchable titles and descriptions: notification preferences finds one General row, notification history remains separate, and About has its own destination. Removed Event Stream commands are not indexed. The legacy Channels command projects as a Dashboard destination even when the broader Dashboard route catalog is unavailable. MCP uses that local catalog and HubSearch, independent of the visible surface; message snippets are excluded |
authoritative |
| Unified icon-opened search | HubSearch ranks and deduplicates items; HubSearchCatalog projects Gateway data; window-owned HubSearchController fences async publication and activation. Same-context refresh preserves pending reads and remote results; Retry reloads them. The active SearchHost owner prevents a previous shell's Closed event from closing newer search. SearchHost preserves same-query scroll and surviving selected-row/input focus through metadata rebuilds; Show more transfers focus to the first newly revealed result before its disappearing button can restore an old row. It owns popup sizing, keyboard handling and one native list scroller containing only wrapped results. There is no search footer or visible status-message block; More/Retry sit beside the input and source status remains accessible through the input's UI Automation ItemStatus. HubPresentationContractTests.SearchPopup_HasNoFooterOrVisibleStatusBlock_AndKeepsActionsBesideInput guards the prohibited footer until the native SearchHost surface is replaced. Shells retain icons, flyout lifetime and per-open focus. Cross-surface requests coordinate both existing FlyoutShowRequest close owners and replay through the window's current-surface admission path; deferred destination reveal cannot take focus from a newer search generation. PermissionSettingsWriterRoutingTests.MainAndSettingsSearch_ShareCatalogExecutorAndLabel_WithoutChangingTheVisibleSurface guards these native owner boundaries until the shared shell search is replaced |
authoritative |
| Detached search RPC responses | OpenClawGatewayClient uses private search: request IDs and drops uncorrelated replies before legacy payload dispatch. Request cancellation frees the pending registration and stops queued writes; WebSocketClientBase drains a started frame under client-lifetime cancellation so a cancelled query cannot abort the shared socket. Loopback request and blocked real-stream send tests cover both boundaries |
authoritative |
| Search destination section and agent provenance | ConfigEditorModel resolves sections from schema independently of saved values; ConfigPage renders missing sections with empty data. Its field reveal is bound to the requested section, consumed after one attempt, and cleared on manual navigation/unload; cancelling detail rendering also dismisses that operation's overlay without allowing a stale continuation to clear a newer one. SchemaConfigEditor applies field reveal after layout. Search-owned skills reads retain selected-agent cache provenance and open explicitly labeled Dashboard destinations. HubSearchCatalog uses established web routes without release allowlists, including /skills, /systems and full-key /chat?session= handoff. Systems destinations must not substitute the separate Devices settings page. RPC advertisement, permissions and connection/profile fencing remain authoritative for remote search reads; route availability is not capability negotiation. Retired Skills/Bindings native pages and global SkillsData are not restored |
authoritative |
| Settings-only command-catalog input adaptation | Closed in SettingsShellView; delegate to HubCommandCatalog so Workspace-first MCP searches use the same inputs |
closed |
| Gateway record test data | OpenClaw.Connection.Tests.GatewayRecordBuilder |
authoritative |
| Settings test data | OpenClaw.TestSupport.SettingsDataBuilder |
authoritative |
JSON JsonElement coercion (non-nullable fallback family) |
JsonReadHelpers |
authoritative |
| Ollama node command risk taxonomy | OllamaNodeCommandPolicy |
authoritative |
| WSL/POSIX shell quoting | WslShellQuoting |
authoritative |
| UI-thread marshaling for presentation code | IUiDispatcher |
authoritative |
| Optional release updater dependency lifetime | UpdateBackendLoader + non-inlined ReleaseUpdateBackendFactory; UpdatumUpdateBackend alone owns vendor types |
authoritative |
| Eager release updater construction in App and vendor-typed download UI | Closed in App and DownloadProgressDialog; UpdateCoordinator admits the release channel before lazy creation and reports unavailable recovery through existing update state |
closed |
| Shared page presentation and responsive sizing | PageResponsiveLayout owns host-width tiers, 1200-DIP inner content cap, padding and tile sizing for all non-chat pages. PageContentLayout applies that policy to XAML columns and releases page-size subscriptions on unload. PageHero renders plain caller-owned localized headings in Reactor without colored banners, card chrome or a leading icon column. Header actions retain native ancestry across resize. No page data, routing or Gateway subscriptions move into these helpers |
authoritative |
| Settings page history-band allocation | WorkspaceSettingsLayout computes allocation; WorkspaceWindow keeps the embedded host full-height and SettingsShellView allocates 56 DIPs exactly once, through ISettingsPageContentInset for opted-in pages or internal Frame padding for ordinary pages. This applies in both full Settings and embedded pages, regardless of pane visibility. Non-chat page headings then share the same 4-DIP top padding. NavigationView retains its native 1-DIP left content divider in expanded and minimal states, without a top divider or exposed backdrop strip above headings. Pane toggles stay above full-frame backdrops. Navigation identity, Back to app, Escape, Dashboard dispatch and saved pane preference remain unchanged. WorkspaceNavigationTests.HiddenPane_UsesZeroWidthAndReopenRowWithoutCoveringContent guards chrome stacking; WorkspaceSettingsLayoutTests.OptedInPageAllocation_PreservesOrdinaryPagePaddingAndNavigationIdentity guards inset delivery after initialization, reset and the prohibition on adding full-Settings frame margins. Retire these source guards when native opted-in-page coverage is mandatory in closeout |
authoritative |
| Page view-model activation/deactivation + disposal lifetime | NavigationScopeManager |
authoritative |
| Presentation-layer DI composition root | AppServiceRegistration (root ServiceProvider, owned by App) |
authoritative |
| Settings snapshot read + field-scoped save + origin-aware change notification | ISettingsStore; SettingsManager captures the immutable presentation snapshot and commit-order version from the data being persisted, then delivers Saved outside save serialization. SettingsStore forwards that payload with its writer origin, never resnapshots a concurrent edit. Delayed notifications retain their original versions so consumers can reject stale delivery |
authoritative |
| Hosted setup settings writes | SetupSettingsWriter through ISettingsStore; SetupWindow and the pipeline supply only reviewed field patches |
authoritative |
| Committed node Sandbox permission snapshot and launch ordering | SettingsManager.SandboxPolicies owns the NodeSandboxPolicyStore; settings replacement and exact detached policy publication share its ordered dispatcher with final launch submission. Revisions increase only for changed Sandbox policy. Failed saves publish nothing, queued stale work fails and admitted operations finish on their original snapshot. Saved/UI notifications run after publication and outside settings serialization |
authoritative |
| Editable system.run settings projection | SettingsManager.SnapshotSystemRunSettings supplies detached editor snapshots, not runtime grants; persisted JSON names and unknown-field preservation remain unchanged |
authoritative |
| Live System tools revocation | SettingsManager.IsSystemRunPermissionGranted permits grants only after persistence and reads revocations immediately; SystemCapability checks the predicate supplied by NodeService during discovery, dispatch and approval/prelaunch revalidation, without waiting for Gateway reconnect |
authoritative |
| Runtime permission field-by-field projection | Closed in NodeService; delegate to the authoritative settings snapshot rather than reconstructing a hybrid policy |
closed |
| Complete node Sandbox policy and execution ownership | MxcRequestBuilder composes one resource policy; NodeSandboxExecutor owns mode selection, final policy admission, capacity, scratch and content-free spawn diagnostics. Its per-instance owned-work join is registered before scheduling and completes after managed preparation/process/pipe/cleanup work; callers stop producers before taking the join snapshot. Join cancellation affects only the waiter, and join completion does not establish that an uncertain native child exited or release retained leases. MxcOwnedOperation atomically creates and retains the operation's full native directory identity and no-follow ancestry. MxcOperationCleanup retries sharing failures, then retains at most 16 active/deferred cleanup leases per executor and retries only ended owned leases on admission, without occupying the eight execution slots indefinitely. Uncertain launches/finalization retain payload pins until owner shutdown and are never automatically reaped. There is no crash-recovery sweeper or adoption by directory name. MxcProcessLifetime owns SDK/host processes, binary pipes, interruption, root observation, late-launch finalization and SDK exit diagnostics after finalization. NodeService composes one executor from committed settings and fresh Windows protection |
authoritative |
| system.run approval and text adaptation | MxcCommandRunner supplies the already-approved command, final approval revalidation and bounded text protocol to the shared executor. NodeSandboxPolicyStore awaits approval revalidation after the launch queue drains, then checks the prepared Sandbox snapshot and invokes the synchronous launch prefix before another policy commit can run. It preserves finite command deadlines, truncation and public results |
authoritative |
| Shared executor shutdown | NodeService.DisposeCoreAsync stops MCP, disposes upload retention and detaches Gateway handlers before disposing its shared executor. Disposal releases retained uncertain-launch payload/ancestry pins without assuming safe directory deletion. AppRefactorContractTests.NodeService_ShutsDownProducersBeforeReleasingExecutorCleanupLeases guards the WinUI-only ordering until executor ownership moves to a directly testable service |
authoritative |
| Independent system.run process ownership | Closed in MxcCommandRunner and UnsupportedWindowsCommandExecutor; both contained and host execution delegate to NodeSandboxExecutor and MxcProcessLifetime. The compatibility helper only constructs approved host start information |
closed |
| Fixed-worker data versus infrastructure access | NodeSandboxResources separates persisted DataAccess from trusted loader/image/scratch InfrastructureAccess; only the minimum union reaches the SDK. FixedFileWorkload supplies binary IO, bounds and a finite file-operation descriptor, never mode or caller-selected grants. The executor admits the operation before launch; the worker rejects a different operation before filesystem IO. InstalledFileWorkerResolver selects installed code from Companion's embedded manifest and process RID. Its executor-private persistent cache creates one full-manifest-addressed entry with an atomic native EA execution veto, then publishes through the EA state transition under a cross-process file lock, without directory rename. Every lease independently verifies the complete source and cached inventories, manifests, full digests and no-follow identities before execution; verification child pins stay held through publication and the final full verification. Eight 128 MiB reservations bound completed, partial and unknown entries across restarts; unaccountable entries block new admission. The active creator rolls back its own unpublished failure only through retained native directory/ancestry handles and a complete inventory of exact create-new child identities. Unknown, replaced, aliased or locked children block cleanup explicitly; cancellation stays cancellation. A deterministic crash-orphaned preparation, including an old .preparing-* directory, is never executed, adopted, deleted or duplicated merely because the builder lock is available. The narrow CacheOwnership owner below handles admission-only published reclamation; corrupt current entries are never repaired or replaced. Source and execution pins survive late launch and process/pipe cleanup. The installed source remains protected, even for LocalAppData Inno installs. Only the selected published code receives SDK read-only infrastructure access, never data authority or scratch write access. Payload hash reads use a per-instance internal reader over already-pinned streams, with cancellation checkpoints around hashing and both successful resolver returns. The reader owns neither the stream nor publication; native committed entries are retained on cancellation. A fresh worker process still serves each operation. Unsupported-Windows host execution retains the verified installed image without using the cache. The fixed worker omits native speech dependencies, and its manifest generator rejects direct or delayed external VC runtime imports. FileOperations serializes only the executor-admitted snapshot, never caller policy |
authoritative |
| Fixed-worker cache native ownership and upgrade admission | CacheOwnership in InstalledFileWorkerCache.cs binds newly created private roots and complete published entries through flushed native EAs with parent/root/entry/full child identities. Every new entry, even under an unowned legacy root, receives a private ACL and an atomic NtCreateFile initial preparing EA that vetoes execution before child identities exist. One bounded EA replacement commits published only after full copied-code verification and exact create-new identity checks. Flush and a native receipt precede lease return; post-commit cancellation or flush failure retains the complete entry, never rollback. The embedded manifest remains the sole code authority. Existing unowned roots and unknown preparations are never adopted; an entry record alone never grants legacy-root eviction authority. New-entry capacity admission, under the existing cross-process builder lock, considers non-current owned entries. Complete no-follow inventory and nonshared read/delete handles precede ordinary non-POSIX apphost disposition; a mapped apphost veto leaves all children intact and restores published metadata. Exclusive opens alone never establish idleness. A durable deleting record precedes disposition and permits recovery of only matching remaining children, not execution or in-place repair. Same-version resolution may finish that owned interrupted deletion under the builder lock through the same identity and kernel guards, then publish a fresh complete entry. Published current entries are never evicted by this recovery path; active or unproven remaining children block recovery explicitly. No recursive deletion, POSIX bypass, background sweeper, process killing or inferred SDK termination receipt. Eight 128 MiB reservations include unknown/deleting/preparing entries and new-entry ownership metadata headroom. Owned idle versions permit continued upgrades; live/unproven slots and legacy unowned roots retain explicit backpressure. The root ACL and existing all-command physical denies protect ownership metadata; selected code gains no EA-write or data authority |
authoritative |
| Typed file-command execution | FileCapability and FileCommandParser adapt the eight file commands to the shared executor. OpenClaw.FileWorker owns retained native handles, data-only authorization, bindings, bounded reads/listing/gzip-tar, identity-preserving overwrite, create-only streaming and private upload staging. Contained top-level writes fail explicitly rather than treating their traversal anchor as a parent; streaming create revalidates an existing target after input verification. IFileInvocationChannel is the transport-owned logical-message seam; NodeInvokeRequest.FileChannel cannot be set by command JSON. Binary fetch/create use a ten-minute executor ceiling and retain shorter transport cancellation, without changing unary/system.run deadlines or permission admission. NodeInvokeResponse.FileOutcome preserves semantic failure separately from the six plugin commands' outer success envelope |
authoritative |
| Gateway file-transfer policy entry for this node | GatewayFileAccessPolicy appends allow-all (**) to this node's entry in plugins.entries.file-transfer.config.nodes.<nodeId>, inheriting the effective entry's controls and denies for a new entry, and, in the write that first gives this node **, appends missing, non-denied file commands to the Gateway node command allowlist; it never removes entries (the Gateway rejects shrinking writes) and leaves an unsupported policyVersion unchanged; GatewayFileAccessPolicySync is the single-flight writer, bound to the operator client, connection epoch and connected paired node, triggered by StateChanged, settles one outcome per connection, confirms application through config.get revisions, and logs non-success outcomes without UI. It writes nothing unless NodeService.FileCommandsEnforceSandbox is true (false means uncontained compatibility execution; null means a failed or pending probe). It only adds to that node's allowReadPaths and allowWritePaths; the Node Sandbox (FileDataAccess.Demand) is the only file-access enforcement and names the cause in its denial |
authoritative |
| Per-folder Gateway file-transfer projection | Closed in GatewayFileAccessPolicy; Sandbox folder grants are not mirrored into Gateway path rules or re-synced on settings saves |
closed |
| File-worker native path lifetime | RetainedFileSystem holds ancestors against rename/delete, opens children with relative NtCreateFile, uses full volume/file IDs, and publishes with NtSetInformationFile on the stage handle (null RootDirectory, no replacement). The destination comes from the retained parent's native volume-device path, not a caller or remappable DOS-drive spelling; every ancestor stays pinned, including newly materialized parents. This avoids transporting a second handle inside an MXC rename buffer. Contained traversal starts at the first non-root component with read-attributes and traverse rights, without drive-root grants, ancestor enumeration or ACL reads; canonical handle paths reject drive aliases. Directory handles include traverse rights because Windows does not enforce sharing restrictions on metadata-only handles. Owned staging starts with kernel delete-on-close; only a verified complete rename can clear its on-close disposition. Caller paths never reopen through a checked path string. Unproven reparse/Cloud Files, physical aliases, device/ADS names and case-sensitive directories fail explicitly; contained hard-link targets fail rather than asserting alias containment |
authoritative |
| Retained-upload cleanup | UploadStore owns private ACL/identity validation, the short cross-process lock, disk-authoritative 24-hour/64-directory/256-MiB inventory and handle-based reap inside the worker. UploadOwnership stores one native EA, atomically attached at directory creation with the retained parent identity/name, then flushed with the directory/payload identities before content publication. Creating/deleting phases recover missing owned children without deleting replacements or unknown entries. Complete legacy JSON records migrate before deletion; incomplete or invalid legacy records remain blocked. UploadRetentionCoordinator.Start explicitly starts app-lifetime scheduling of remembered/admitted roots only; admission durably reserves each exact new root before mutation and later persists its identity. Every admission invalidates older cleanup results and holds scheduling until all admitted workers for that root settle. NodeSandboxExecutor issues the settlement receipt only after confirmed process finalization and pipe settlement, including interruption; uncertain finalization retains the reservation. Expected worker-command failures publish blocked cleanup without stopping the scheduling loop. A configured but unused root is not scanned. Notifications run outside locks and NodeService surfaces blocked cleanup in diagnostics and Sandbox. Inventory failure blocks new uploads without turning completed writes into retryable failures. Remembered roots confer no grants; each reap uses current executor admission. SandboxUploadStagingPath is preserved as legacy configuration but never selects new automatic storage or grants. SandboxMaxTransferBytes remains in the existing committed settings store, with valid saved values preserved |
authoritative |
| Automatic profile upload storage | ManagedUploadPolicy derives one direct sibling of the actual Runs/FileWorkerCache roots from normalized SettingsDirectory identity. ManagedUploadRootLease verifies native root EA, private ACL, physical identity and no-follow ancestry, retaining pins through execution and uncertain finalization. MxcRequestBuilder supplies the saved resource projection; the executor applies ordinary RO only for proven complete ownership and finite Upload/Reap RW before launch. Restrictive saved RO/NoAccess and immutable protected/runtime paths still veto access. Missing or unproven storage grants no ordinary access; descendant RW cannot pierce the ordinary managed RO boundary. ManagedUploadRootLease.Bootstrap establishes only the derived root metadata with FILE_CREATE, atomic owner/System ACL and the shared root EA format after durable inventory reservation, inside the existing policy-epoch launch prefix. No parent SDK RW is granted. UploadStore retains all payload creation, content IO and reaping in the worker. Unknown/unbound or nonempty incomplete roots remain blocked; a bound empty creating root can finish identity-matched metadata recovery. Failed prelaunch operations settle reservations and retain owned empty metadata; uncertain children retain both pins and reservations. Same-profile consumers may read all retained uploads, not a per-file/session capability. Remembered legacy roots gain no automatic authority | authoritative |
| Managed upload first-boundary creation in the worker | Closed for executor-admitted Upload: the trusted metadata owner establishes and pins the exact profile boundary before SDK launch, and the worker receives its expected native identity. UploadStore never recreates a missing admitted root; payload and legacy identity checks remain in the worker | closed |
| Fixed contained Windows UI API compatibility | MxcRequestBuilder always sets Ui.Disable=false for PowerShell/console startup, independently of presets; container desktop isolation, desktop/job restrictions, input-injection denial and configured clipboard policy remain enforced |
authoritative |
| User-controlled Win32k syscall blocking | Closed in SettingsData, SettingsManager and SandboxPage. Legacy SystemRunAllowWindowsUi values are ignored on load and excluded from unknown-field preservation on save; no runtime flag or UI replacement |
closed |
| Exact-path personal-folder projection and editor overrides | MxcFolderPermissions coalesces preset roots, known-folder overrides and explicit paths for both SandboxPage and MxcRequestBuilder. Its pure specificity query mirrors SDK precedence for cwd/image admission, including explicit child exceptions to user No access. Immutable protected denies veto every descendant grant independently in the builder; metadata admission remains unchanged. Editing returns a detached settings snapshot and retains known-folder identities. Legacy Blocked (2) is quarantine; NoAccess (3) is a distinct persisted deny |
authoritative |
| Incremental command output and terminal snapshots | CommandOutputCapture owns bounded UTF-8 snapshots for both SDK and unsupported-Windows execution. Root exit is independent of pipe EOF; native interruption uses SDK stream closers, host reads use public cancellation |
authoritative |
| MXC child environment and temporary storage | Official SDK/Windows defaults; OpenClaw omits the request Environment and does not rewrite TEMP, appdata or PATH | authoritative |
| MXC custom child environment | Closed in MxcRequestBuilder; no replacement environment dictionary or in-band bootstrap. Caller environment remains subject to the independent approval rejection |
closed |
| OS runtime, personal/redirected folder and sensitive-root capture | MxcRequestContext captures trusted OS inputs, including immutable .openclaw-companion protection for host-executed cleanup state; injected synthetic context exercises the same product builder/runner without granting real profiles |
authoritative |
| Registered Companion private-state protection | MxcWindowsRequestContext reads current-user Windows package registration and unredirected LocalAppData per contained command; MxcCompanionPackagePaths projects only exact Store/Dev Companion identities into immutable private-state denies. NodeService only supplies this existing runner context callback; Shared has no package-discovery dependency |
authoritative |
| Physical MXC protection and owned scratch paths | MxcPhysicalPaths expands logical sensitive and executor-private roots to metadata-verified physical deny spellings. MxcRequestContext reserves default/isolated OpenClawMxc\Runs and OpenClawMxc\FileWorkerCache; the executor adds its actual roots. NodeSandboxResources vetoes both private namespaces for typed caller data independently of immutable sensitive roots. The SDK denies those namespaces for every contained command, including system.run, with only executor-issued selected published code RO and own scratch RW grants. Caller descendant overrides and selected cwd/image paths cannot reopen them. MxcOwnedOperation creates/pins ordinary no-follow operation storage; cleanup reopens through the retained parent, compares full file ID and deletes only opened objects, never follows reparse entries or adopts replacements. It cannot delete the separate shared code cache. The worker resolver separately rejects aliases in executable paths. No package-name guesses, caller-grant alias exceptions, protected-root exceptions or writable parent SDK grants |
authoritative |
| Folder metadata admission for MXC grants and cwd | MxcFolderAdmission checks ancestors root-first using no-follow, read-attributes-only handles. Only ordinary paths and directory CLOUD/CLOUD_1..F tags with matching final paths are admitted. Cleanup's all-reparse refusal remains separate |
authoritative |
| Implicit volume-root readonly compatibility grants | Closed in MxcRequestBuilder. Native evidence found unrelated reads; never re-add roots as metadata or scope ancestry shortcuts |
closed |
| Raw MXC EXE/Win32-pipe transport, generic JSON policy DTOs and failure-triggered host fallback | Retired. SDK/load/request failures never select host execution | closed |
| Positively unsupported Windows compatibility | MxcAvailability supplies the positive OS verdict; NodeSandboxExecutor alone selects owned host execution with approved argv or the fixed worker, deadline and shared process ownership. Unknown, probe, policy and launch failures never trigger host fallback; host IO carries no enforced Sandbox resource projection |
authoritative |
| Obsolete npm MXC payload cleanup on unpackaged startup | LegacyMxcFiles deletes only four historically shipped files, refuses reparse traversal and preserves unknown files and OS-managed package versions; App only delegates after primary-instance admission |
authoritative |
| Cooperating JSON persistence coordination | PersistenceFileLease; registry expected-snapshot Save and settings loaded-JSON CAS hold it through atomic replacement |
authoritative |
| Settings persistence conflict state and visible recovery | SettingsManager owns typed CAS rejection; SettingsPersistenceNotification owns dispatched, deduplicated restart guidance; App composes/disposes it |
authoritative |
| V2 exec-approvals snapshot/CAS persistence + observation | ExecApprovalsStore through IExecApprovalsPresentationStore |
authoritative |
| General load/persist view logic, including notification preferences | SettingsPageViewModel |
authoritative |
| Native tool identity, display arguments, payload extraction, and flattened-history projection | NativeToolProjector |
authoritative |
| Managed-local listener provenance and strong-credential authorization | ManagedLocalGatewayPortProvenanceService |
authoritative |
| Native Gateway fixed-product WinGet installation from Microsoft Store and bounded App Installer bootstrap | NativeGatewayMsixInstaller |
authoritative |
| Trusted Store and existing development Gateway registration identities | NativeGatewayPackageIdentity |
authoritative |
| Current-user Gateway package registration, health and package-qualified alias discovery | NativeGatewayPackageResolver |
authoritative |
| Prospective Companion-to-native-Gateway state/config/workspace path mapping | NativeGatewayDataPathMapper; NativeGatewayPackageResolver supplies package and known-folder context. Independent of existing-log resolution |
authoritative |
| Store package install/update, one acquisition attempt and bounded registration verification | NativeGatewayPackageAcquisition |
authoritative |
| Current-user registration of the already staged Store Gateway family after WinGet success | NativeGatewayStagedPackageRegistrar (classification in NativeGatewayPackageRegistration), invoked once by NativeGatewayPackageAcquisition |
authoritative |
| Shared Windows capability and permission selection, with runtime-specific install review | CapabilitiesPage |
authoritative |
| Native profile draft creation and canonical state/config launch paths | NativeGatewaySetupService + NativeGatewayPaths |
authoritative |
| Native onboarding capability admission and default/remembered gateway choice policy | NativeGatewaySetupEligibility, consuming MxcAvailability session probe metadata |
authoritative |
| Package-contract runtime selection and lifetime | NativeGatewayRuntimeRouter selects IsolatedGatewayRuntime or the recognized legacy NativeGatewayRuntime |
authoritative |
| Isolated package control and listener/process-sequence verification | NativeGatewayPackageClient, IsolatedGatewayRuntime and WindowsProcessSequenceSnapshot |
authoritative |
| Retained package-launcher identity, live same-user ancestry and lifetime attribution | WindowsPackagedProcessAncestry, anchored by WindowsNativeGatewayProcessHost |
authoritative |
| Native setup staged-record runtime, reload restoration, config/health and exact-AI gates, publication | NativeGatewaySetupSession |
authoritative |
| Staged native setup operator connection, pairing, per-handshake/request provenance and bound AI transport | NativeGatewaySetupConnection borrowing the runtime from NativeGatewaySetupSession |
authoritative |
| Setup completion authority across native runtime contracts | GatewayDashboardBinding includes the package family and non-null runtime contract; NativeGatewaySetupSession rechecks agent configuration without reading a host config for isolated sessions |
authoritative |
| Native operator connection construction inside the classic wizard page | WizardPage.ConnectNativeClientAsync delegates to NativeGatewaySetupConnection |
closed |
| Published native AI transport and restart verification | GatewayAiSetupTransport.BorrowNativeAsync + GatewayConnectionManager.RequireNativeSetupClientAsync + SetupNativeCompletionVerifier |
authoritative |
| Reviewed native Local AI installation continuation | LocalAiInstallAndUseIntent binds single-use consent to Gateway/endpoint/model/port; LocalAiOnboardingUse retains mutation outcome and drain ownership. SetupWindow transfers the intent after artifact acquisition; AiSetupPage applies progress and exact-model verification without provider rediscovery |
authoritative |
| Native Local AI explicit running intent | LocalAiNativeBindingStore persists automatic-recovery intent separately from ownership; LlamaServerRuntimeService serializes explicit Start/Stop, guarded Resume, withdraw-only reconciliation and explicit release under its operation gate. LocalAiGatewayLifecycle never converts connection notifications into explicit Start; it drains recovery before shutdown withdraws through the still-authorized manager |
authoritative |
| Existing-native Local AI Settings entry | SetupAccessDraft.SelectExistingNativeGateway binds the existing record and preserves Settings ownership; WindowManager initializes only a newly created setup window, and SetupWindow applies the native route without WSL finalization or unrelated settings writes |
authoritative |
| Hosted Gateway onboarding RPC and provider/auth/model rendering for WSL and native | WizardPage |
authoritative |
| Audited optional onboarding defaults shared by native, WSL and headless setup | WizardOnboardingPolicy |
authoritative |
| Optional-tail cancellation acknowledgement and saved-config/authenticated-health gates | WizardOptionalSetupHandoff |
authoritative |
| Native terminal TUI onboarding and pre-wizard registry publication | NativeGatewaySetupHost / NativeGatewaySetupService |
closed |
| Native Gateway credential preflight and retry authorization | NativeGatewayEndpointSecurity owns the bounded native readiness allowance and sanitized startup-timeout classification; GatewayConnectionManager applies that allowance without changing non-native handoff deadlines or authority fences |
authoritative |
| HTTP/dashboard/web-chat credential handoff routing and fresh native inspection | InteractiveGatewayEndpointAuthorizer, borrowing the manager-owned runtime |
authoritative |
| Local AI gateway-record ownership and WSL distro binding | LocalAiGatewayDistroResolver |
authoritative |
| Local AI provider policy and configuration execution | LocalAiGatewayProviderCoordinator owns publication/fallback; ILocalAiGatewayConfigurationTransport separates execution, with WslLocalAiGatewayConfigurationTransport retaining pinned-distro commands |
authoritative |
| Native Local AI admission, publication and reconnect ownership | NativeLocalAiGatewayTarget admits the exact authenticated isolated record; LocalAiGatewayLifecycle binds the single runtime to that owner, borrows authorized connections and journals guarded RPC changes through LocalAiNativeBindingStore; the provider coordinator retains publication/fallback policy |
authoritative |
| Native Local AI recovery discovery | LocalAiGatewayLifecycle.ObserveOwnershipAsync reads current-profile binding and authenticated configuration without mutation or credential access; SetupLocalAiHost supplies evidence to LocalAiOnboardingSnapshot. Only a usable same-owner managed choice replaces a detected model; AiSetupPage renders guidance and retains the existing explicit Use path |
authoritative |
| Native Local AI setup, cancellation and staged handoff | SetupLocalAiHost admits explicit Use; LocalAiOnboardingUse.Expected supplies the explicit managed-use requirement carried by GatewayAiSetupCompletion through fresh verification and restart. NativeGatewaySetupSession retains its verification/publication gate; SetupWindow wires Local AI reconciliation only for that managed choice. Ordinary detected use never gains runtime/reconciliation requirements from matching receipts; setup cancellation withdraws only its selected route |
authoritative |
| Optional managed llama API authentication substrate | LocalAiApiCredentialStore protects a stable key with current-user DPAPI; LlamaServerRuntimeService supplies LLAMA_API_KEY only in the child environment; health/inference clients use Bearer headers and the process host redacts echoed keys |
authoritative |
| Native Local AI artifact-only acquisition | SetupStepFactory.BuildNativeLocalAiAcquisitionSteps reuses Windows hardware, receipt, runtime and model owners without WSL, inference, provider publication or Gateway restart; caller-owned target admission and explicit Use remain required |
authoritative |
| Managed Local AI hardware profiles | LocalManagedInferenceProfile and LocalInferenceSelector bind runtime families, resource requirements and ordered model/context candidates; LocalInferenceProfileRecommendation supplies UI fallback facts |
authoritative |
| Local AI model cache acquisition, explicit legacy migration, and active-path receipt selection | HuggingFaceModelInstaller + LocalAiManifestStore + LocalAiInstallReconciler |
authoritative |
| In-place Local AI model change (catalog or custom Hugging Face GGUF) | LocalAiModelSwitcher acquires and verifies the new weights while the current model serves, writes the receipt through LocalAiManifestFactory, and commits through ILocalAiRuntime.ReplaceInstallAsync, which withdraws the old route before saving; a failed start restores the previous receipt. The App-owned instance runs one switch at a time, rejects a concurrent switch before reading the receipt, and publishes IsSwitching so every page instance stays busy until a switch that outlived navigation finishes. HuggingFaceModelReferenceResolver pins custom references to a commit, LFS digest and GGUF geometry; LocalAiPageViewModel only presents it |
authoritative |
Local AI model change through the setup wizard (ShowLocalAiModelSetup) |
Replaced by the in-place Local AI page switcher | closed |
| Gateway default model selection | DefaultModelPageViewModel decides; DefaultModelGatewayService writes agents.defaults.model.primary with a guarded partial config.patch and, in the same patch, removes the default agent's own primary (agents.entries.<id>.model), which the Gateway otherwise prefers for new conversations; the page shows that effective model. While Local AI is installed, a cloud choice is also recorded as its fallback through ILocalAiRuntime.SetGatewayFallbackModelAsync, and Local AI publication or withdrawal stays with the runtime; a successful Local AI change then removes the agent primary the same way. A saved native ownership receipt for the active Gateway (DefaultModelGatewayState.LocalAiReceiptOwnsGateway) routes cloud choices through the runtime even when the install cannot be loaded, so its Pending guard runs before any write. LocalAiGatewayLifecycle.SetPrimaryAndFallbackModelAsync saves the target as LocalAiNativeBinding.UnconfirmedPrimary before the Gateway write, and every lifecycle Gateway config read settles it to the primary the Gateway shows |
authoritative |
| Adding Gateway model providers (API key, provider sign-in, custom endpoint) | ModelProviderSetupViewModel decides; ModelProviderGatewayService calls models.authStatus/models.authSetApiKey/models.authLogin and writes only models.providers.<id> with a guarded config.patch. A sign-in is bound by BeginLogin to the client, connection epoch and Gateway it started on; every wizard.next/wizard.cancel rechecks that binding and sends only on the captured epoch, and a lost binding retires the flow before any retained answer is transmitted. DefaultModelPage hosts the shared ProviderSetupDialog for sign-in steps; the chat model picker only navigates there. DefaultModelPageViewModel re-raises ModelProviderSetupViewModel changes as Providers so DefaultModelPage re-renders the provider card and sign-in dialog from its single subscription |
authoritative |
| Exact Gateway wizard terminal-restart compatibility and bounded retry policy | GatewayWizardRestartRecoveryPolicy |
authoritative |
| Interactive onboarding routes and installation-step selection | OnboardingFlowPolicy |
authoritative |
| Accessible provider/model and completion-card invocation | SetupActionCard supplies the native Invoke provider; AiSetupPage and AiReadyPage retain their guarded selection and completion actions |
authoritative |
| Setup-lifetime capability/profile/explicit Custom intent/consent draft and ordered installation requirements | SetupAccessDraft + SetupCapabilityProfiles, owned by SetupWindow |
authoritative |
| Setup provider artwork resolution and bounded page-owned download lifetime | GatewayAiSetupPresentation + ProviderArtworkSession + ProviderArtworkLoader, rendered by ProviderArtwork |
authoritative |
| Native setup editor mounting and committed-result routing | SetupWindow through ISetupNativeConnectionHost + SetupNativeConnectionPage |
authoritative |
| Setup-only Windows privacy preview and probing | Retired; current Permissions settings and runtime consent retain their existing owners | closed |
| Setup Local AI and Tailscale control lifetimes | LocalAiSetupControl in GatewaySetupDetailPage; TailscaleSetupControl inline in GatewaySetupPage with a compatibility detail route |
authoritative |
| Per-setup-window CUDA probe reuse and incomplete/faulted-result refresh | LocalAiHardwareProbeCache; SetupWindow composes it for Welcome and LocalAiSetupControl |
authoritative |
| Temporary setup operator connection, captured identity and endpoint provenance | SetupGatewaySession + SetupGatewaySessionBinding |
authoritative |
| Expected AI restart admission during missing live handshake | GatewayAiSetupController bounds the wait; transports use the existing binding owner to validate persisted authority, then the client requires a fresh exact authenticated route |
authoritative |
| Native setup verify-only connection and isolated validation identity/tunnel | GatewayConnectionValidator + GatewayValidationIdentity |
authoritative |
| Native setup connection input and host transaction adapter | SetupNativeConnectionInputResolver + SetupNativeConnectionHost through GatewayDirectConnectService |
authoritative |
| Committed Existing/Remote Gateway through capability review and AI admission | GatewayDirectConnectService captures endpoint binding; SetupAccessDraft retains it; SetupGatewaySession / borrowed native transport reject drift before credentials or RPC |
authoritative |
| Focused AI setup protocol state and provider progress polling | GatewayAiSetupClient + GatewayAiSetupController |
authoritative |
| Verified AI completion intent and opaque pending restart handoff | GatewayAiSetupClient + GatewayAiSetupCompletion + SetupDashboardHandoffStore + SetupDashboardHandoff |
authoritative |
| Chat-only native setup completion and post-restart navigation | SetupCompletionPreparation + SetupNativeCompletionVerifier + SetupReadyCoordinator; SetupWindow composes preparation and finalization, SetupReadyWindow exposes only Chat |
authoritative |
| Processing supported legacy setup destination receipts | SetupNativeHandoffLauncher + SetupNativeNavigationRequest; WindowManager routes WhatsApp, Telegram, and Channels receipts to the Gateway Dashboard's channels path with the verified completion, and the dashboard launcher rechecks Gateway and identity authority at credential resolution and browser dispatch. Retired Skills receipts are rejected |
authoritative |
| Verified native setup Chat window boundary | SetupNativeNavigationRequest projects the exact Workspace session; WorkspaceWindow calls ChatPage.BindNativeSetupRequest explicitly, not a Frame navigation override. WindowManager awaits the retained page before activation and receipt consumption |
authoritative |
| Verified setup Chat hosting in the Settings view | Closed in SettingsShellView; typed native Chat requests must use Workspace without dropping endpoint, identity, agent or session verification |
closed |
| Settings Chat rail action | SettingsShellView forwards a non-selecting item invocation through WorkspaceNavigation to the retained chat destination in the same window; Settings never mounts Chat |
authoritative |
| Gateway dashboard entry points | ConnectionPage retains the status-card dashboard icon and saved-Gateway menu actions, forwarding to the existing GatewayDashboardLauncher path. The standalone Channels/integrations dashboard card is removed; ChatPage has no management banner |
authoritative |
| In-flight native chat navigation identity | SetupNativeChatBinding holds the exact request reference; WorkspaceWindow invalidates it at admitted agent/session navigation intent, before asynchronous creation. ChatPage checks identity and cancellation on ready and waiting paths; SetupNativeHandoffLauncher fences receipt consumption with the linked timeout |
authoritative |
| Setup-bound Chat warning and recovery presentation | SetupNativeChatPresentation retains the exact verified target through failed mounts; temporary unavailability and provider-confirmation waits hide but retain the host/draft and cannot satisfy handoff readiness. SetupNativeChatRefresh observes the existing manager with activation/request/manager fences and operator-only coalescing. ChatPage applies the InfoBar, releases the binding for composer navigation through ChatComposerHostActions as well as foreign-session queues, and performs the unchanged authority check before reuse. Hidden hosts cancel capture; pending voice starts only after successful evaluation |
authoritative |
| Native receipt acquisition classification and restart recovery settlement | SetupDashboardHandoffStore distinguishes acquired/busy/invalid/unavailable; SetupNativeHandoffLauncher retains recovery on busy/unavailable and clears it only after consumption or definitive rejection |
authoritative |
| Native completion startup readiness | SetupNativeCompletionTiming defines finite phase budgets; SetupNativeCompletionVerifier enforces both borrows, the existing Local AI recovery join and exact-model proof; SetupDashboardHandoffStore starts new preparation execution at issuance, including old-process teardown, and preserves that deadline through acquisition and retry. Destinations and legacy preparations retain five-minute unused admission and their original execution deadlines. SetupNativeHandoffLauncher enforces navigation and total execution deadlines and does not redisplay settled retry failures on automatic activation |
authoritative |
| Production native finishing deadline and admitted-work ownership | SetupCompletionPreparation bounds the whole in-process drain/verification/finalization/publication wait with one startup-derived monotonic execution deadline across retries; retains the actual execution and drain through cancellation/disposal. SetupWindow composes finalization and blocks Back while retained work is pending; committed/uncertain operations cannot be replayed |
authoritative |
| Pre-acquisition restart recovery deletion | App.OpenNativeSetupCompletion; deletion is delegated to the receipt outcome owner |
closed |
| Setup startup availability | WindowManager supplies app identity availability; SetupWindow gates presentation and persisted preference |
authoritative |
| Setup registration outcome and fallback admission | WindowsStartupTaskRegistration classifies completed numeric HRESULT; SetupStartupPolicy still requires strict task absence for rejected-operation Run-key fallback |
authoritative |
| Pipeline failure plus failed registry settlement | SetupPipeline.RunWithSettlementAsync and SetupPipelineSettlementException retain both outcomes; ProgressPage renders/logs them without declaring reconciliation success |
authoritative |
| Setup HWND sizing and DPI-aware minimum | SetupWindow applies OverlappedPresenter constraints; SetupWindowSizing projects DIP dimensions to physical pixels |
authoritative |
| Verified setup authority across fresh clients | OpenClawGatewayClient.AuthenticatedSigningDeviceId + SetupCompletionAuthority + SetupGatewaySessionBinding; accepted signing identity and exact session survive completion, disk reads only detect drift |
authoritative |
| Native startup versus ordinary update prompt | ActivationRouter.CheckOrdinaryStartupUpdateAsync; App retains startup composition and receipt dispatch |
authoritative |
| Credential-recovery transport admission | GatewayCredentialRecoveryPolicy; normal connection recovery and disposable native validation retain their endpoint-provenance checks |
authoritative |
| User-requested Dashboard launch and visible retry | GatewayDashboardLauncher; dialog lifetime remains in WindowManager; no setup receipt or intent |
authoritative |
| Experimental browser setup-completion handoff | Removed; all completion activation goes through the native receipt owner, including visible rejection of obsolete handles | closed |
| Explicit AI preparation continuation, fresh auth-URL admission and bounded restart wait | GatewayAiSetupController |
authoritative |
| Continuous AI provider dialog visibility and exact row-command admission | AiSetupPage |
authoritative |
| Focused AI discovery display grouping | AiSetupPresentationModel |
authoritative |
| Setup installation three-phase overview and exact step-count projection | SetupInstallationProgress; SetupPhaseStatus renders native status icons/text; ProgressPage retains logs and real download progress |
authoritative |
| Onboarding Local AI readiness, fresh-unsupported visibility projection and cancellable read-only observation | LocalAiOnboardingSnapshot + LocalAiOnboardingObservation |
authoritative |
| Same-window Local AI admission and runtime action bridge | ISetupLocalAiHost + SetupLocalAiHost; route inspection shared with Settings through LocalAiSetupRouteResolver |
authoritative |
| Explicit Local AI mutation drain and retained Gateway/model verification binding | LocalAiOnboardingUse; SetupWindow retains the setup lock through its drain |
authoritative |
| Focused provider prompt controls and input clearing | ProviderSetupDialog, owned by AiSetupPage |
authoritative |
Inline provider wizard rendering in AiSetupPage |
ProviderSetupDialog replaces the inline WizardPanel; page retains request/lifetime ownership |
closed |
| AI provider list selection plus a duplicate page-footer Continue | Explicit native row command or inline API Connect, bound to the exact choice | closed |
| Managed-local automatic repair eligibility and orchestration | ManagedLocalGatewayAutoRepairMonitor + ManagedLocalGatewayRepairCoordinator |
authoritative |
| Permissions page state, settings commands, and exec-approvals presentation | PermissionsPageViewModel |
authoritative |
| Permissions runtime status projection | PermissionsPageRuntimeSource |
authoritative |
| Hub navigation tags, page mapping, legacy command metadata and gateway-page classification | HubPageRegistry; unified navigation search ranking belongs to HubSearch |
authoritative |
| Workspace Home/Notifications and exact session-key identity, deprecated-link fallback, back/forward history, and companion boundaries | WorkspaceNavigation + WorkspaceNavigationHistory; WorkspaceWindow restores the selected agent/session on the retained chat host; WindowManager routes pending session links directly without an intermediate Home entry |
authoritative |
| Leaving full Settings for the app (macOS "Back to app" parity) | WorkspaceNavigationHistory.AppDestination (the last shown chat, Notifications or pinned page; chat resolves to the retained conversation; a pruned pinned page falls back to chat) + SettingsEscapePolicy (Escape leaves only full Settings, after the focused control, open popups and text/selection editors had it, never on auto-repeat). SettingsShellView owns the native PaneCustomContent header (Back to app with its Esc key hint, then the Settings title; the compact rail keeps the arrow with a tooltip) and raises ExitRequested; WorkspaceWindow.ExitSettings defers the whole exit while a dialog is open, prunes unavailable Gateway history like Back/Forward, then navigates once through the normal history path; chat focus returns through LeaveSettings, and Notifications or pinned pages focus their destination (the page when the pin row is hidden). Its bubbling KeyDown applies Escape. The former Settings rail Chat item is closed. Pinned pages hide the pane, so they show neither header nor Escape exit. WorkspaceNavigationTests.BackToApp_* and SettingsEscape_* cover the policy; WorkspaceWindowProofTests.SettingsBackToApp_ReturnsToAppDestinationInSameWindow drives mouse, Enter and Escape natively |
authoritative |
| Workspace-versus-Settings dispatch, legacy Channels/activity dashboard aliases, and rejection of unknown prefixed routes before window side effects | WorkspaceNavigation.Dispatch; WindowManager and WorkspaceWindow supply native window actions; retired unprefixed channels and activity tags open the Gateway Dashboard channels path; AppCapability propagates navigation error payloads as tool errors |
authoritative |
| Unvalidated Workspace-prefix forwarding and Settings fallback | Closed in SettingsShellView and WindowManager.ShowHub; delegate boundary dispatch to WorkspaceNavigation |
closed |
| Workspace agent/session identity and background-session filtering | WorkspaceProjection; Home resolves the selected agent's canonical main conversation (Gateway main key, matching IsMain metadata, then the exact agent main key). Without a selected agent or Gateway main key, only a sole IsMain row resolves Home. The sidebar omits only that conversation, never a display-name match. WorkspaceWindow applies Home selection and repeated invocation through its retained chat/history path |
authoritative |
| Gateway-bound remembered assistant, transient roster continuity, and explicit assistant-selection readiness for conversation creation | WorkspaceAgentSelection uses WorkspaceProjection; WorkspaceWindow reports fresh roster updates, applies readiness to Sessions +, and guards assistant/session actions. Explicit unsupported-method status travels from the operator client through GatewayService/AppState, permitting legacy session access and Gateway-default creation without inventing an agent roster |
authoritative |
| Default-agent fallback caused by clearing a transient connection cache in Workspace | Closed in WorkspaceWindow; WorkspaceAgentSelection retains the same Gateway's explicit choice and waits for its authoritative roster |
closed |
| Workspace sidebar session context menu: entries, patch payloads, fork request; flyout, dialogs, and gateway dispatch | WorkspaceSessionMenu (pure entries/patches/fork request), WorkspaceSessionMenuController (flyout, dialogs, gateway dispatch); WorkspaceWindow applies active rows and owns session creation/navigation |
authoritative |
Settings Sessions page: shared PageHero header, roster scoping/filters/paging with inline stopped-run badges, transcript search, category moves, details/overrides, single-session archive/unarchive/delete with archive Undo, and the Worktrees tab. Appearance editing, bulk deletion, category catalog edits, owner assignment and cloud-worker stop stay in the web dashboard |
SessionsHubController owns state and every Gateway request (response-confirmed, connection-bound); Reactor views in Sessions/SessionsHub*View.cs render it; SessionsPage mounts the root, forwards AppState, and retains optional shell inset input separately from controller state. SessionsHubRoot applies that inset only to its scroll viewport; the toast, dialog, and announcement layers remain rooted full-frame. Pure query, grouping and permission policy live in OpenClaw.Shared.Sessions (SessionListQuery, SessionsHubProjection, SessionsHubPolicy); RPCs live in OpenClawGatewayClient.SessionsHub.cs. Session menu entries reuse WorkspaceSessionMenu |
authoritative |
| Archived session browsing and restoration | The Sessions page Archived status filter and response-confirmed Unarchive action in SessionsHubController; accepted changes also refresh the app's tracked sessions for the Workspace sidebar |
authoritative |
ArchivedSessionsSource snapshot and the XAML Archived section in SessionsPage |
Removed; replaced by the paged sessions.list roster in SessionsHubController |
closed |
| Archived dropdown, archived row cache, and archive-list fetching in the Workspace sidebar | Removed by design; archived conversations are managed from Settings Sessions, not WorkspaceWindow |
closed |
| Workspace response-confirmed patch/delete and dialog ownership | WorkspaceSessionOperation binds the original operator client and authenticated transport epoch; OpenClawGatewayClient uses PendingRequestRegistry for matching replies; the menu controller reports errors and refreshes accepted changes |
authoritative |
| Explicit Workspace conversation removal | WorkspaceNavigationHistory.RemoveSession prunes removed destinations; ChatPage.ClearRemovedSession disposes the mounted host and invalidates pending surface work; ordinary Home retains its draft-preserving behavior |
authoritative |
| Canonical background-session classification for Workspace sidebar and latest agent session | SessionDisplayResolver.IsBackground, consumed by WorkspaceProjection; nullable gateway flags must not bypass classification/key fallback |
authoritative |
| Native Workspace pane visibility, non-overlapping reopen row, toggle focus handoff, and the pane width animation | WorkspaceWindow, with WorkspacePaneAnimator easing the width |
authoritative |
| Speculative Workspace management cards and responsive grids | removed with Home/Sessions-only navigation | closed |
| Foreground Workspace and separate Settings companion lifetime | WindowManager |
authoritative |
| Chat-visible notification suppression | ChatVisibilityPolicy owns the pure visibility decision; WorkspaceWindow supplies current destination, AppWindow visibility and minimized state; WindowManager.IsChatVisible evaluates only Workspace chat |
authoritative |
| Inferring chat visibility from any existing main window | Closed in App.ShouldShowNotification; use IWindowManager.IsChatVisible, retaining chat/per-type notification toggles |
closed |
| Readiness-gated, single-use native chat voice launch | PendingVoiceActivation |
authoritative |
| Opt-in Gateway chat speech lifetime and late-result rejection | GatewaySpeechPlayback captures the operator client, authenticated epoch and chat target; mounted composer input projection supplies initial, fallback and explicit targets without becoming another selection owner; OpenClawChatCoordinator routes chat/preview and owns microphone playback-muting leases. TextToSpeechService remains the serialized native playback owner |
authoritative |
| Outward Gateway speech protocol and payload admission | OpenClawGatewayClient.Speech uses the existing response registry; GatewaySpeech validates method/scope authority, bounded inline MP3/WAV. Inward node/MCP TtsCapability keeps its local provider selection |
authoritative |
| Playback mute intent and overlapping leases across voice captures | PlaybackMuteState owns desired mute and registrations. App supplies one mute domain to independently owned standalone/node VoiceService instances, including later node/MCP activation, and disposes it after both services. One-shot pipelines remain local. OpenClawChatCoordinator acquires directly from that domain even before STT is enabled, without creating a capture service, and releases generation-scoped leases after playback drains. SpeechInputContractTests.AppVoiceServices_SharePlaybackMuteWithoutSharingCaptureOwnership protects composition until real App transition tests cover that wiring |
authoritative |
| Hub notification banner severity and action projection | AppNotificationInfoBarPresenter |
authoritative |
| Inbox entry classification, action-first order, tab counts, dismissible set and bell badge (count capped at "9+", caution tone while an approval waits) for app notifications and Gateway facts alike | InboxProjection (WinUI-free); InboxFeed combines AppNotificationService with InboxGatewaySource and is the only source hosts read; WorkspaceWindow applies its badge to every footer |
authoritative |
Gateway-sourced Inbox facts: pending exec/plugin/system-agent approvals (typed PendingApprovalRequested/PendingApprovalResolved from OpenClawGatewayClient, hydrated by *.approval.list on connect, removed on resolve, disconnect or a local-clock deadline fixed at arrival, with bounded terminal/deadline retention until disconnect to reject replay, so Gateway clock skew cannot end them early or keep them forever), failed/overdue automations from complete cron.list inventories through the shared revision-consistent catalog reader and cron.status (partial or failed refreshes retain the last accepted inventory), and expired or missing model-provider accounts from models.authStatus, plus their session-scoped dismissals |
InboxGatewaySource (App-owned, attached to the operator client by App.OnOperatorClientChanged; no own connection); pure rules in InboxGatewayItems. Approval and Gateway text is untrusted display data and is never logged; approval previews, complete selectable commands, host/directory metadata and scope text use the shared secret-redacting display sanitizer without changing the observed request |
authoritative |
| Inbox row reconciliation, tabs, expansion, host-bound relative-age clock and approval countdown, "Dismiss shown" and row actions ("Open chat" for exec approvals, the existing Dashboard launcher for non-exec approvals, "Ask OpenClaw", native page links) for the bell flyout and the full Inbox page | InboxView, hosted by WorkspacePaneFooter (flyout) and NotificationsPage (page); the footer uses FlyoutShowRequest to retain a bell invocation during native closing and cancels pending reopening when its host hides or closes; hosts supply app-reminder admission, Gateway-only route, settings/page/ask callbacks, and "Ask OpenClaw" sends through InboxChatPrompt to the main conversation's chat provider |
authoritative |
| Fire-and-forget app-reminder routing and parallel host route implementations | Closed with InboxViewCommands.OpenRoute, WorkspaceWindow.OpenInboxRoute and NotificationsPage.OpenAppRoute; app-reminder actions use TryNavigateAsync through InboxFeed.NavigateNotificationAsync and AppNotificationService.NavigateActionAsync. HubPresentationContractTests.InboxHosts_ForwardAdmissionResultsAndRequestLocalChatKeys guards this closure until mounted refusal/deferral proof covers both hosts |
closed |
| Gateway-only Inbox navigation for projected chat, Automations and Models routes | InboxViewCommands.OpenGatewayRoute is consumed only by Gateway primary/secondary row actions; WorkspaceWindow.OpenGatewayInboxRoute and NotificationsPage.OpenGatewayRoute retain native navigation and request-local chat selection. WorkspacePaneFooter hides before forwarding. These actions never dismiss or decide Gateway facts; app reminders still require admission. HubPresentationContractTests.InboxGatewayRoutes_CannotBypassAppReminderAdmission guards the boundary until mounted secondary-handler injection is mandatory |
authoritative |
| Separate bell-flyout and page notification lists, raw active-notification badge count, and history-style "Clear all" | Closed with NotificationFlyoutContent/NotificationItemViewModel; informational and success results are not Inbox rows |
closed |
| Notification action navigation and retention | AppNotificationService.NavigateActionAsync shares the InboxView/banner policy (InboxFeed forwards app reminders only; Gateway rows keep their independent action/decision owner); IAppCommands.TryNavigateAsync forwards to WindowManager.TryShowHubAsync through WorkspaceNavigation.DispatchAsync. Native destinations report synchronous mounted-host admission; Dashboard routes await GatewayDashboardLauncher.OpenAsync and report whether Windows accepts the browser launch, not remote page loading. Opening retains the reminder, matching the web Inbox, including when its destination is already shown. Setup redirection, unavailable services, closed/unmounted windows, section fallback, modal deferral, exceptions and delayed completion also leave reminders unchanged. Only explicit dismissal or the source's lifecycle removes them; opening does not acknowledge, approve or abort the underlying action. Notification chat keys are request-local; existing ChatPage consumption of ambient intent is unchanged |
authoritative |
| Optional desktop lobster lifetime and notification arrival tracking | DesktopCompanionController + DesktopCompanionState; DesktopCompanionSurface owns the Reactor mascot projection and the retained setup-mascot adapter; DesktopCompanionBubble owns the notification and quick-chat bubble hosted in an acrylic windowed popup; DesktopCompanionWindow owns native window lifetime, mascot hit region, popup anchoring, drag placement and bubble timeout |
authoritative |
| Desktop lobster imperative notification-control projection | Closed in DesktopCompanionWindow; presentation changes reconcile through DesktopCompanionSurface and DesktopCompanionBubble, not direct text/mood/control setters in the window |
closed |
| Desktop lobster quick-chat mounts and dedicated session identity | DesktopCompanionChatHost borrows the current app provider and owns separate retained dedicated/reply Reactor mounts, window-owned attachment picking and invocation-scoped voice-service callbacks. Notification replacement hides the mount and cancels capture without discarding its draft; late picker/capture results cannot cross hide or Gateway changes. DesktopCompanionChatSessions retains one confirmed or in-flight dedicated session per Gateway; closing a bubble does not repeat sessions.create. ReactorChatHostExtensions remains the shared mount owner and OpenClawReactorChatRoot supplies the compact layout. Chat notifications select their existing action-route session, never the main conversation as a fallback |
authoritative |
| Gateway/operator/node status flyout controls | GatewayStatusContent |
authoritative |
| Tray-menu semantic composition and connection-toggle state | TrayMenuPresenter + ConnectionTogglePresenter |
authoritative |
| App-owned non-tray window creation, reuse, focus, theme, and lifetime | IWindowManager + WindowManager; Workspace is the only application chat host, and the never-activated runtime anchor stays hidden without shell switcher registration |
authoritative |
| Standalone compact chat hosting and prewarming | Removed; chat entry points use Workspace, with no hidden replacement window during background startup | closed |
| Composer session picker and compact-host layout mode | Removed, including the picker-only IsVisibleInChatPicker helper; non-picker session filters remain. Workspace owns session selection, while actual-width observation retains responsive model/reasoning controls and transcript geometry |
closed |
| Composer host settings-navigation callback and single-attachment ingress wrappers | Removed after the single-host audit. Voice readiness dialogs retain direct, actionable settings navigation; attachment ingress uses the controller's plural API. MountedReactorChat retains callback clearing and exactly-once disposal for late voice/mute events |
closed |
| Tray icon, popup coordination, live status, and callback lifetime | ITrayController + TrayController; unsupported-desktop tray construction is logged without preventing requested Hub startup |
authoritative |
| Deep-link/protocol/toast/forwarded activation normalization, current-user IPC, and semantic activation plans | ActivationRouter |
authoritative |
| Packaged activation-kind preservation | App.GetLaunchActivation adapts Windows AppLifecycle metadata into LaunchActivationInput; ActivationRouter shares candidate selection for initial/secondary launches and reserves implicit foreground navigation for interactive Launch |
authoritative |
| Post-save settings change effect ordering, detached snapshot comparison, and concurrent save serialization | SettingsChangeCoordinator |
authoritative |
| Exactly-once ordered app shutdown sequencing | AppShutdownCoordinator |
authoritative |
| App composition-root startup sequencing | AppBootstrapper (planned) |
planned |
| Packaged uninstall cleanup, preservation recovery and removed-target reconciliation | GatewayPackageCleanup; App only invokes its startup gate and presents recovery. Legacy name/path markers never grant unattended deletion authority; malformed receipts/settings retain pending evidence and fail closed |
authoritative |
| Windowless scheduled cleanup launch after Companion removal | OpenClaw.GatewayCleanupHost (GUI-subsystem .NET Framework helper), embedded and deployed by GatewayPackageCleanup; GatewayPackageCleanup.Task.ps1 registers its durable versioned path. PowerShell starts with CreateNoWindow; worker exit codes reach Task Scheduler |
authoritative |
| Inno migration records, preparation, and pre-start completion guard | MigrationRecordCodec, MigrationPreparation, MigrationInventory, InnoMigrationStartupGuard |
authoritative |
| Cross-session migration exclusion and source activity inspection | MigrationOperationLock, InnoSourceActivityVerifier (App only retains the runtime handle through process exit) |
authoritative |
| Store migration startup admission and finalization | InnoInstallationDetector, InnoSourceRemovalVerifier, MigrationStartupRecordReader, MigrationInventoryCapture, StoreMigrationStartupCoordinator, StoreMigrationFinalizationCoordinator, StoreMigrationStartupGuard |
authoritative |
| Windows node connection generation, cancellation, start ordering, recovery, events, and telemetry | NodeConnectionCoordinator |
authoritative |
| Bootstrap/shared/device credential handoff, durable clear gate, and operator token recovery timing | BootstrapTokenLifecycle |
authoritative |
| Device role-upgrade approval, confirmation, and bounded node reconnect queue | DevicePairApprovalCoordinator |
authoritative |
Gateway wire protocol range, minimal hello-ok validation, and sanitized compatibility state |
GatewayProtocolContract + GatewayProtocolCompatibility |
authoritative |
| Capability UI metadata | NodeCapabilityUiCatalog (planned) |
planned |
| Capability registration/gating | NodeCapabilityRegistrationPolicy (planned) |
planned |
| Local MCP exposure policy | McpCapabilityPolicy (planned) |
planned |
| Gateway connect envelope | ConnectEnvelopeBuilder |
authoritative |
| Gateway request tracking | PendingRequestRegistry |
authoritative |
| File transport framing and lifetime | FileFrameChannel owns strict upstream JSON fragmentation and bounded callback delivery. GatewayFileInvocation serializes progress/heartbeats, with at most sixteen wire frames awaiting correlated responses; readiness and logical-message completion still await every required response. WindowsNodeClient fences input/results by connection generation and uses PendingRequestRegistry for progress acknowledgments. McpFileChannels owns authenticated command/request-bound leases, cursor retention and input deduplication on the existing listener; McpHttpServer separates ingress, controls, ordinary calls and streams |
authoritative |
| Local raw file IO | OpenClaw.WinNode.Cli.FileTransferClient preserves caller bindings, computes bounded input identity, and validates fetched size/hash before no-clobber publication. It uses the existing CLI endpoint/token resolution, not a second credential or command registry |
authoritative |
| Chat atomic runtime transaction lock and cross-domain commits | ChatConversationState; assistant admission, transcript reconciliation, usage and finalization commit together before publication. Terminal chat envelopes settle independently of visible content; ChatLifecycleState retains run outcome and terminal-delivery identity without converting a yield into descendant completion. Persisted snapshots and late frontier repair cannot reopen a turn. ChatTimelineReducer separates visible streaming from frontier reconciliation eligibility. Idle session rows only trigger a ChatHistoryLoader read; settlement requires explicit idle state for the captured run/session incarnation and current connection/reset/replacement/start generations |
authoritative |
| Chat queue collections, echo correlation, drain and retry commit mechanics | ChatQueueState under the ChatConversationState lock |
authoritative |
| Pending chat bubble presentation | ReactorChatTimeline no longer projects queued submissions into virtualized history |
closed |
| Pending chat queue presentation | ReactorChatPendingMessages renders the selected-thread queue as a bounded, keyed panel above the composer; OpenClawReactorChatRoot supplies the existing controller cancellation and keeps the panel separate from history |
authoritative |
| Empty-chat hero and recent/prompt content | ReactorChatWelcome renders native localized welcome copy; ReactorChatComposer applies Gateway catalog agent identity and OpenClawReactorChatRoot centers the stable composer subtree |
authoritative |
| Agent display name and avatar rules | AgentAvatarPresentation follows the web Control UI: name is roster name, then configured identity name, then agent.identity.get name, then id; text avatars reject blank, A, path/URL-like or over-8-character values; a resolved identity owns image absence; otherwise AgentIdentityBadge renders image, then text, then the seeded generated face. Avatar-only badges use their requested size without the two-line row's minimum height |
authoritative |
| Sidebar agent identity hydration | GatewayService.RefreshAgentIdentities reads agent.identity.get for each roster agent after agents.list and stores results in AppState.AgentIdentities; client replacement clears the roster and identity cache and invalidates pending identity reads; WorkspaceProjection.Agents composes them. WorkspaceWindow.UpdateAssistantItem refreshes the native closed selection under the sidebar update guard without navigating |
authoritative |
| Active chat agent identity and avatar image lifetime | AppState exposes the current roster-first ChatAgentPresentation to OpenClawReactorChatRoot; chat subscribes to identity changes and shares that presentation across the welcome header and transcript sender, accessibility name and avatar. The provider identity RPC remains a fallback when no roster presentation is available. AgentAvatarImageCache is bounded to four sources per mounted chat tree, shares in-flight/completed loads across transcript avatar badges, preserves MediaResolver host and size policy, invalidates on roster changes, and cancels/disposes with the chat tree |
authoritative |
| Welcome copy | Native .resw resources own guidance, the Recent chats label, and starter prompts in every supported language; ReactorChatWelcome renders them and sends the displayed prompt through the existing composer action. No Gateway welcome catalog or connection-scoped fetch state |
authoritative |
| Pending new-chat selection | OpenClawReactorChatRoot retains the exact requested key until a materialized session arrives; a synthetic compose-only thread is not publication acknowledgment |
authoritative |
| Pending chat preview list inside the composer | Closed in ReactorChatComposer; the composer contains only the unsubmitted draft and attachments |
closed |
| Chat reset generations, gates, echoes and backfill state | ChatResetState under the ChatConversationState lock |
authoritative |
| Chat history identity, revisions and connection-generation tokens | ChatHistoryState under the ChatConversationState lock |
authoritative |
| Chat sessions, models, catalog and snapshot projection inputs | ChatPresentationState under the ChatConversationState lock |
authoritative |
| Chat run, abort and terminal lifecycle state | ChatLifecycleState under the ChatConversationState lock; known terminal runs cannot restart through delayed output or replayed starts, even without a newer run. Identity-matched retained tool repairs (including pending child outcomes while idle), pending approval resolution and last-run usage updates remain admissible without reopening work |
authoritative |
| Chat approval identity correlation and dedupe state | ChatApprovalState under the ChatConversationState lock |
authoritative |
| Chat send admission/retry decision policy | ChatSendQueuePolicy with atomic commits coordinated by ChatConversationState |
authoritative |
| Chat history request/retry/rebuild mechanics | ChatHistoryLoader with token acceptance coordinated by ChatConversationState |
authoritative |
| Gateway agent event to chat event mapping | ChatEventMapper |
authoritative |
| Gateway append-only chat reconstruction | GatewayChatStreamProjection, called once by OpenClawGatewayClient.ChatStreaming; connection/session/agent/run baselines never belong to a renderer |
authoritative |
| Transient interactive agent questions and confirmed answer/cancel recovery | GatewayQuestions + OpenClawGatewayClient.Questions own protocol and structured not-found classification; ChatQuestionCoordinator owns one bridge's generation-fenced, coalesced recovery, bounded read retries and per-question unavailable retirement, separate from transcript persistence |
authoritative |
| Native question controls and answer drafts | ReactorQuestionPanel + ChatQuestionDraft own the compact dock, question/request navigation and transient answers. The root hides, never remounts, the composer while the dock is expanded; it only subscribes/selects/composes and never sends answers as chat messages |
authoritative |
| Live run timing, output usage and active-turn working indicator | ChatTimelineReducer stores observed turn boundaries and latest-run sequence-fenced usage; ChatHistoryState preserves it across reloads, including before the first entry; ChatRunProgressProjection exposes only active or input-pending turns without discarding completed metadata; ReactorRunProgress owns disposable UI timing and row entrance. ChatWorkingClawMotion owns source-derived geometry/keyframes; NativeWorkingClaw owns native transforms, reduced motion and rendering subscription cleanup. Session totals never supply the live counter |
authoritative |
| Chat snapshot projection | ChatSnapshotProjector |
authoritative |
| Direct-subagent pill and status list | ChatSubagentPresentation is the single status, count and elapsed projection over the root's current, exact-parent subagent snapshot. ReactorChatSubagentsPill (above the composer) opens the tab; ReactorChatSubagents renders non-interactive Running/Finished rows without loading child history or changing Workspace selection. ChatConversationPanelState / ReactorConversationPanelHost own the shared Subagents/Files/Dashboard/Tool details tab strip, resizing, compact visibility, minimize, empty-panel launcher, expanded presentation, the wide-layout column width motion between hidden, split and expanded (eased by WorkspacePaneAnimator) and focus; WorkspaceWindow's title-bar side-panel toggle and Expand only mirror and invoke that state through ChatPage.ConversationPanels, and WorkspaceTitleRow offers the window's caption row through SetTitleRow (panel header and divider reach the window top; the tab strip the host publishes through SetTabStrip is a title-bar pass-through region; the row is withdrawn while a banner shows above chat); closing a tab moves focus to the next tab or, for the last tab, its opener before the focused tab item is removed, and automatic focus that still reaches the transcript during that close is redirected, so WinUI cannot fall back to a transcript row and move the reader. ReactorItemsViewScrollController also rejects ItemsView's unfocused reveal of its last keyboard-current row while focus is outside the transcript. No child transcript, separate child discovery, Stop, docking or layout persistence yet |
authoritative |
| Subagent-specific split layout, Close button and main-conversation visibility | Closed in ReactorChatSubagents; the shared conversation panel host owns these responsibilities for both tabs |
closed |
| Panel-host Subagents toggle button and embedded child transcript | Closed: the pill above the composer is the only opener, and ReactorChatSubagentTranscript was removed with the detail screen |
closed |
| Pinned child activity expander below the timeline | Removed from ReactorChatTimeline. Child inspection belongs to the Subagents tab, and provider review moved to ReactorChatProviderReview |
closed |
| Provider-review notice | ReactorChatProviderReview renders the web-style paused/stopped warning card above the composer and a read-only findings dialog. Continuation permission comes only from CanContinue; the card never acknowledges or resumes the run |
authoritative |
| Full-width provider-review Expander in the timeline | Closed in ReactorChatTimeline; ChatTimelinePresentationContext no longer carries ProviderReview |
closed |
| Tool and attachment metadata cache lifecycle | ChatMetadataStore |
authoritative |
| Aborted IDs and last-chat-state persistence | ChatStatePersistence |
authoritative |
| Sensitive instant-capture ordering | SensitiveCaptureExecutor + SensitiveCapturePlans |
authoritative |
Windows deploys the MSIX. The current Gateway package owns its isolated session
and Gateway service; Companion owns setup, connection and credential handoff;
upstream OpenClaw supplies onboarding over RPC. The known legacy proof package
instead uses Companion's same-user process supervisor. Package installation,
a listening port, and successful onboarding are not
interchangeable readiness signals. App remains the composition root; do not
move package resolution, process inspection or setup finalization back into it.
Isolated runtime inspection and lifecycle ownership are separate. Verification is cached per record and is always checked against fresh listener snapshots; probing another package cannot transfer stop ownership. Only starts issued by Companion are stopped on detach, and failed authorization rolls back only a start issued by that same call. Explicit wizard restart uses a separate runtime operation and preserves a pre-existing service's leave-running policy. Ownership inspection, including the fresh check before credential handoff, has a five-second deadline. Package inspection failures, including WinRT deployment errors and an explicit unknown service state, deny handoff as unavailable inspection rather than claiming a conflicting listener. Authentication recovery classifies these unavailable probes as network failures.
NativeGatewayMsixInstaller.InstallAsync invokes the signed-in user's App Installer
alias (%LOCALAPPDATA%\Microsoft\WindowsApps\winget.exe) through the existing
CommandRunner, without a shell or elevation. The fixed command is
install --id 9NV70LV3D6XC --source msstore --silent --accept-package-agreements --accept-source-agreements --disable-interactivity.
The native review explains that selecting Set up gateway authorizes installation
and accepts the package and Store source agreements. Microsoft Store still owns
architecture/package selection, signature validation and deployment. There is no
automatic Store-page fallback: missing WinGet, policy/source failures and nonzero
exit codes produce explicit retry/repair guidance with sanitized, bounded output.
Command success is not package readiness. There is no local source path,
environment override, direct download, certificate-trust change, or ARM64-only gate.
NativeGatewayPackageResolver.ResolveAsync subsequently requires exactly one
matching current-user package registration, verifies package health, and resolves
its package-qualified openclaw.exe and clawctl.exe execution aliases. Never
substitute a generic PATH/npm command, copied executable or guessed WindowsApps
installation path. NativeGatewayPackageClient probes clawctl status --json
for integration.kind: "isolated-session" and version 1. An unversioned
response that already describes a session is unsupported, not a legacy
fallback. Only the known 0.0.0.0 and 0.0.0.1 proof packages retain the
same-user path.
NativeGatewaySetupHost invokes clawctl setup --json and requires a ready
isolated session before configuring it; that command does not perform
Gateway onboarding.
NativeGatewayPackageIdentity accepts the Store manifest's exact pair:
OpenClawFoundation.OpenClawGateway and
CN=4BA40A7A-B719-4C40-BF91-84AF4F1136FC
(packaging manifest).
The original OpenClaw.Gateway / OpenClaw Foundation development publisher pair
remains accepted for already installed packages and saved profiles. Names and
publishers cannot be mixed. New setup with both identities installed produces an
explicit duplicate-registration error, not an implicit migration or preferred-package
fallback. The runtime resolver selects the saved profile's exact family, so an
existing Gateway remains usable when both packages are installed. Runtime records
remain pinned to their saved package family; Store
installation does not rewrite a development profile's identity. Package-family
syntax checks admit both names, while registration and exact family matching
remain mandatory before launching. An existing same-user record is not silently
migrated to a newly installed isolated package; it requires new setup.
scripts\NativeGatewaySourceBuild.psm1 owns the source-build safety boundary:
machine-wide build/unregister serialization, protected creation of work directories,
read-only validation of existing tree and ancestor ACLs, and prebuilt metadata/hash
validation before cache selection. Existing unsafe permissions are rejected, not
silently repaired. This protects loose-package code without changing Store resolution.
Developers opt in to a source-built Gateway with
OPENCLAW_NATIVE_GATEWAY_DEV_PATCH=<patch>. scripts\Build-NativeGatewayFromSource.ps1
builds an openclaw/openclaw ref and registers it with the packaging repo's
Deploy-LocalPackage.ps1 -Patch as the side-by-side loose registration
OpenClawFoundation.OpenClawGateway-<patch> under the Store publisher, with
package-qualified aliases openclaw-<patch>.exe and clawctl-<patch>.exe. While the
variable is set, new setup selects only that patched package
(NativeGatewayPackageIdentity.IsSelectable) and a missing patch is an explicit error,
never NativeGatewayPackageNotInstalledException, so WinGet never runs. Saved profiles
bound to a patched family resolve only while the variable names that patch
(IsResolvable); otherwise the resolver reports which value to set. With the variable
unset, selection, resolution and aliases are identical to the Store path.
After native capability/permission review, NativeGatewaySetupPage starts
automatically. It rechecks device support, then calls
NativeGatewayPackageAcquisition.EnsureAsync. Missing packages and existing Store
packages start WinGet install/update once per attempt; development packages skip it.
Duplicate registration, unhealthy packages
and missing aliases fail explicitly instead of triggering reinstall loops.
The cancellable acquisition deadline defaults to 30 minutes, including installation and
registration verification, with one-second polling after WinGet completes.
If WinGet succeeds but the first post-install resolve still finds no registration,
NativeGatewayStagedPackageRegistrar registers the staged Store family for the current user once.
"Not staged" keeps polling within the deadline; any other registration error fails immediately.
OPENCLAW_SETUP_PACKAGE_ACQUISITION_TIMEOUT overrides that bound in seconds; an explicit
EnsureAsync timeout argument still wins.
Cancellation reaches CommandRunner, which stops its WinGet process tree;
Windows may still finish an already submitted deployment. No installed package
is removed, and retry starts by resolving registration again.
The page uses the shared OnboardingMascot, native SettingsCard rows with
SetupPhaseStatus, and SetupProgressIndicator for support, package readiness,
profile preparation and verified runtime startup. Completed rows get checkmarks.
Its Install stage leads to the same focused AI and Ready stages as WSL, with six
native stages (WSL has an additional installation review). Progress sits above wrapping navigation actions on
both pages so narrow windows do not overlay buttons on the indicator.
It automatically transfers the staged session to AiSetupPage; no separate
Install, Check again or Open Gateway setup actions remain. Retry is error/cancel
recovery only. Preview never installs or starts a Gateway.
Native and WSL use the same CapabilitiesPage profiles and toggles. Native
installation consent stays on that page, without a separate review or
WSL/Local AI/Tailscale probes. Cancelling returns to capabilities without
automatically restarting a runtime.
On finalization, the session applies selected command IDs to the Gateway's
gateway.nodes.commands.allow through the upstream CLI before config/health
verification. The isolated path applies this inside the agent account, not
under Companion's Windows profile; legacy profiles retain the local writer.
Focused completion explicitly restarts through the selected runtime owner and
reverifies the exact model before publication. The isolated runtime preserves
whether a pre-existing service should be left running on detach. Focused setup
drains its operator before finalization and does not call isolated Stop before
Restart, which would otherwise discard stop ownership for a setup-started service.
The shared setup settings owner then saves the reviewed capability, transport
and startup choices without overwriting unrelated settings. Settings write
failure stays retryable before releasing the session. Completion shows the
verified model and one Chat action, not a running or paired Windows node.
The normal connection owner still performs node connection/pairing; Windows
permission and exec-approval gates are unchanged.
Native package setup uses the shared AiSetupPage and AiReadyPage flow.
Only an explicit unsupported-method result offers WizardPage compatibility
setup. Authentication failures, timeouts and uncertain writes do not enter that
fallback. Healthy native and WSL AI/Ready screens use the same presentation:
providers, verified model and the Chat-only completion action, without a native-only
summary. Gateway and permission details remain in Connection and Permissions.
Native recovery actions and output appear only for actionable errors or uncertain
outcomes on the AI page/provider dialog, and hide again during normal progress or
after recovery. Their native ownership and cancellation guards are unchanged.
The 2026-09-18 onboarding decision removed the separate "not isolated" warning/checkbox. General security consent and exact-identity pairing remain. Capability eligibility alone does not establish the Gateway's runtime account: the package-qualified versioned integration check selects the isolated package path, while the known legacy proof remains same-user.
On Welcome, NativeGatewaySetupEligibility consumes the actual
wxc-exec --probe result probes.isolationSessionAvailable exposed by
MxcAvailability.IsolationSessionCapability. It must not infer session capability
from IsolationProxy.exe, a process-containment tier or a Windows build alone.
Windows Server/unknown SKU suppression remains in the shared probe. Missing or
invalid session metadata does not invalidate a usable process sandbox, but it
cannot authorize native onboarding.
A positive result enables and initially selects the first Install a local native gateway card with the accent highlight and Recommended badge. A negative capability result leaves that recommended choice visible but disabled after WSL and Connect to an existing gateway, with Windows Update guidance directly below the choice list; reopening the page rechecks support. The guidance names the unavailable isolation-session capability, explains that a newer Windows version alone does not guarantee availability, and offers the existing WSL and existing-Gateway routes. For users who need to update Windows, it describes joining the Windows Insider Program, selecting the Beta or Experimental channel, and choosing Windows 11, version 26H1 under Advanced options during enrollment. It warns that returning to Windows 11, version 25H2/26H2 requires a clean reinstall. After enrolling, users return to Settings > Windows Update and check for updates; the update may take a few minutes to appear. The guidance notes that feature availability can vary by device and tells users to reopen the page to check support again, including when Windows is already up to date. It does not promise a rollout or that updating fixes the capability. The live probe remains authoritative. The native boolean cannot distinguish every OS API failure from missing support. Missing executables, malformed results and probe errors instead offer retry or Companion repair, not an assertion that Windows must be updated.
The Welcome page presents WSL, Connect to an existing gateway, then disabled native
Gateway while support is being checked or unavailable. A positive result moves native
to the first position, followed by WSL and the existing-Gateway choice. WSL is visible
and selectable during the native probe and for every probe outcome, without an expander.
There is no Welcome-page Check again button.
WSL/Local AI discovery starts on page load; fresh WSL readiness and
destructive-replacement confirmation still run before its capabilities page.
WSL is never selected implicitly after a failed native probe. A late probe
result preserves explicit WSL and existing-gateway selections, including choices
restored on Back navigation. Re-entering the
page rechecks support, stale results cannot mutate an unloaded page, and native
package setup rechecks capability before preparing a profile.
ms-settings:windowsupdate only opens Settings; Companion does not enroll the
device in an Insider channel or change Windows feature flags.
NativeGatewaySetupService creates or resumes a credential-free draft descriptor
containing a Gateway ID, preferred loopback port, package family, and runtime
contract. The draft is not yet a published GatewayRegistry record. Companion
keeps its device identity under its own data directory, but an isolated package
keeps OpenClaw configuration, credentials and workspace under the agent account.
For an isolated package, clawctl companion prepare --port <preferred> --json
reads the agent's default openclaw.json and invokes upstream
openclaw config patch inside the recorded session. It preserves an existing
local port and token plus unrelated settings and rejects incompatible mode,
bind and authentication settings. Companion records the returned effective
port and token; it does not create a host-side openclaw.json, forward its
profile paths or install its own Gateway supervisor. Package
gateway-service start/status/stop owns the service lifetime. A cancelled
draft can resume without replacing the agent's credential. Finalization
checks that the returned port and token still match before publishing.
If an unpublished same-user draft survives an upgrade to an isolated package,
Companion shows an explicit replacement choice. Discarding removes only the
Companion draft descriptor, then starts isolated setup with a new identity.
Existing configuration, credentials and workspace files remain untouched, even
if a previously published connection was removed from the registry. Like
StoreMigrationRecoveryDiscard, native recovery discards intent, not user data;
the Inno-specific receipts and installation checks are not shared with native setup.
It never reuses host configuration as agent configuration. A published
same-user profile remains blocked and directs the user through Connections to
remove it and create a new isolated profile. It never adopts a foreign listener
or session, and it does not modify WSL or other package paths.
The following same-user profile and port-rotation path applies only to the
recognized legacy proof package. It creates a separate profile at
<Companion data>\gateways\<gateway-id>\native-gateway, with its own
openclaw.json, generated authentication token and workspace.
Retry re-reads the draft instead of keeping a stale in-memory port. If an
unpublished draft's port is occupied, NativeGatewaySetupService selects another
loopback port and updates only the port in the descriptor and configuration.
Gateway ID, identity, authentication token and provider settings are preserved.
A durable PreviousPort intent in the descriptor allows either interrupted
write to finish on the next attempt. Published records are never rotated by
this recovery. Runtime ownership checks still reject listeners that race startup;
no conflicting process is adopted or terminated.
For that legacy path, NativeGatewayPaths supplies explicit OPENCLAW_STATE_DIR and
OPENCLAW_CONFIG_PATH for package commands, rather than using the user's default
Gateway profile. Launch paths are mapped through ResolveDataPath to physical
locations because Companion and Gateway can have different MSIX filesystem
views; canonical registry paths are unchanged. External-supervisor/service-repair
flags and disabled automatic updates preserve Companion's lifecycle ownership.
NativeGatewaySetupSession owns cancellation, pairing and final publication
gates for both paths. Only legacy setup backs up and suspends the reload setting
in its host-owned profile; the isolated path leaves the agent's existing
reload setting intact. Stopping either runtime does not delete its configuration.
IsolatedGatewayRuntime applies one absolute startup budget from before the start
command through readiness. It is five minutes by default. Slow hosts reached a
verified listener after about 210 seconds
(#1969).
OPENCLAW_NATIVE_GATEWAY_START_TIMEOUT (whole seconds, 30 to 3600, read once
per process) overrides that budget; the package command timeout is the larger of
three minutes and the startup budget, and the derived credential handoff and setup
connection phase budgets follow it. A late successful acknowledgement retains ten
seconds for status confirmation, extending the start/status ceiling to at most 310
seconds at the default. This allowance remains subordinate to caller deadlines;
the outer 330-second default connection budget also includes preflight, inspection
and handshake work. Native setup configuration validation uses the native CLI
timeout (four minutes by default, overridable with
OPENCLAW_SETUP_NATIVE_CLI_TIMEOUT) and must return successfully before the
admission budget begins; its elapsed time does not reduce the admission window.
Setup logs distinguish configuration-validation, admission, and startup timeout
failures. Runtime status is polled every two seconds without issuing another start.
A timeout raises NativeGatewayStartupTimeoutException with its phase (start request or
readiness), budget and last package status. Its message uses only validated lifecycle
states and token-shaped readiness reason codes, never package prose.
starting or unhealthy with no listener is only a pending observation, never
credential authority. A listener racing the pending observation permits one fresh
status recheck, but only running plus full port/process attribution can pass.
Unknown/terminal states, persistently unattributed listeners and failed
ownership checks fail closed. Each ownership inspection (lifecycle-gate wait,
package resolution and one package status read) has a 15-second deadline by
default; OPENCLAW_NATIVE_GATEWAY_INSPECT_TIMEOUT (whole seconds, 5 to 120, read
once per process) overrides it. Expiry reports inspection unavailable and sends no
credential. The default fits inside the twenty-second admission margin; a larger
override remains subordinate to the caller's deadline. Cancellation/deadline failure retains the existing
owned-start rollback rules; pre-existing pending services are not adopted. A
pre-existing starting service is observed without ownership until it reports
running (then full listener proof) or the startup budget expires. Because an
external restart can bind its port before the package reports running, that
observation keeps waiting while a listener exists; the listener stays untrusted.
A start Companion still owns (for example after a lost acknowledgement whose
rollback failed) is waited on the same way but is never reclassified as external,
even when the user later restarts it; such a failure needs a manual reconnect.
A completed owned start keeps only its detach ownership, so a later external
restart of it is external. A listener failure that ends and rolls back a start
the same call requested stays terminal, so reconnect cannot start it again.
A status read that times out before any lifecycle decision reports unavailable
inspection. An external start that exhausted a full startup budget is then read
once per reconnect attempt rather than polled for another budget, and
configuration repair never runs while the service is starting.
Only reconnect authorization, which runs before a new socket is opened, may start
or wait for the Gateway. Per-socket handshake authorization runs after a peer has
already accepted the socket, so it only re-inspects current ownership: a foreign
process could otherwise keep that accepted socket while the real Gateway later
takes the listening port.
Endpoint denials carry a typed retry disposition that defaults to terminal.
NativeGatewayEndpointSecurity marks only temporary causes retryable and reports
them as Network, never port-conflict guidance: no
listener, unavailable or busy inspection, a listener snapshot that changed during
verification, and a not-running state or startup timeout for a lifecycle
Companion did not request. A pre-existing unhealthy or unknown service is not
waited on within one attempt, but it is such a state, so reconnect keeps
observing it until it recovers or the user disconnects. Each role then reads
clawctl status once per reconnect attempt; the delay grows from one second to
a 60-second cap, plus jitter. Untyped timeouts and the credential handoff's own
outer deadline stay terminal because both can end Companion's own start. The
outer deadline is retryable only when the runtime reports that the call merely
observed (waited for the lifecycle gate or an external start) and started nothing.
A user disconnect still waits for an in-flight initial connect to finish, which
can include one startup wait. The WebSocketClientBase reconnect
loop is the single retry owner: a retryable denial reports Error like a
transport failure and observes again after the normal capped backoff, while
terminal denials (unattributed listeners, missing process identity, contract
failures, Companion's own failed start, changed records) still stop it. A
deferral also discards any retained startup-sidecars retry hint, so the
normal backoff grows instead of repeating the Gateway's short hint. No
denied attempt sends a credential. For a retryable denial the node client raises
no terminal ConnectionFailure and the node coordinator publishes no terminal
block, so the automatic node-start guard stays armed and cannot replace a node
that recovers first.
See native startup contract limitations
for the older package's ambiguous failed-start response, which is not admitted.
The pending-start fixtures are conditional client-contract tests, not proof that
the installed package can acknowledge a pending launch.
NativeGatewaySetupSession starts one monotonic admission budget after successful
configuration validation and before initial runtime authorization.
NativeGatewaySetupConnection consumes the remainder through preparation, challenge
authorization, startup-sidecar retries, pairing and operator hello. The default is
the existing 330-second native allowance (300-second start, ten-second confirmation,
twenty-second admission margin).
Reconnects, failed connections and credential recovery do not renew it.
Successful admission ends that operation. Exhausted unadmitted sessions require
new setup preparation, not another connection retry. Terminal handshake errors still fail immediately, caller/session
cancellation stays cancellation, and deadline expiry reports timeout with the
current typed startup rejection when available. /startupz is not a universal
preconnect gate: supported Gateways can admit operators before sidecars finish.
The current package status contract has no attempt-bound startup-phase progress
signal. Repeated starting or startup-eligible snapshots and unverified Gateway
log lines do not renew or extend either budget. A future progress-aware wait requires
a package contract that reports validated progress for the owned launch attempt;
until then, the absolute startup ceiling and ownership checks remain authoritative.
The optional package advertisement integration.gatewayLaunch={version:1}
enables attempt-owned cleanup. NativeGatewayPackageClient validates the
advertisement and receipts, including on non-running/failed status responses.
IsolatedGatewayRuntime chooses a fresh lowercase nonzero GUID-N before start
dispatch and retains it even if the acknowledgement is lost. A created
receipt describes persisted intent, not listener readiness; an adopted receipt
never grants detach or rollback ownership. Cleanup uses only
stop --if-attempt-id for receipt-capable starts. Replacement, unverified
ownership, missing/malformed responses and conditional-stop refusal cannot fall
back to unconditional stop. The package still verifies its process under its
lifecycle lock, independently of Companion's fresh listener proof.
Genuinely absent advertisement preserves shipping isolated-session-v1 behavior
and its weaker unconditional cleanup guarantee. These stronger receipt guarantees
require the newer packaging producer; they are not claims about the released
Store package or proof from mocked contracts.
IsolatedGatewayRuntime accepts a running Gateway only after a fresh
package-qualified clawctl gateway-service status --json attributes its
listener process IDs, creation times, and OS sequence numbers to the
recorded isolated session and agent SID. Companion compares that
attribution to two complete IPv4/IPv6 loopback snapshots and
SystemBasicProcessInformation process-sequence snapshots. It does not
open the isolated agent's process handle: Windows denies that cross-account
query. Windows 11 build 26100.4770 or newer is required for that
process-sequence API; unsupported builds fail closed with update guidance.
A port alone, a stale process ID, an unrelated listener, or a
replaced listener is denied. When several session-owned listeners leave the
package unable to name the Gateway port, such as OpenClaw's MCP App sandbox
host beside it or a plugin's loopback proxy that opens after Companion
connected, status omits gateway.port but still attests every listener.
Each credential handoff reads status again, and listener snapshots consider
only Companion's port, so another owned listener does not change that proof.
Companion then requires its saved port among them and a live, credential-free
connect.challenge from that port (connected directly, never through a proxy)
before treating it as the Gateway, so an attested sandbox listener on that
port is denied. A running status with no listener attestation (older packages
with a second listener, or Windows without process sequences), or a listener
that does not answer that check in time, names that cause, and Companion keeps
a start it requested instead of rolling it back on every retry. Automatic
reconnect keeps observing an unanswered check, which can clear on its own, but
stops for missing attestation, which needs a newer package. Its
synchronous browser credential callback uses the last attributed identity
plus fresh OS snapshots; it never starts a Gateway on the UI thread.
The process-job and ancestry checks below describe only the legacy same-user runtime. They are not an MXC session ownership proof.
The installed package's launcher owns a separate kill-on-close job for Node. Observed ownership with the development package was:
Companion-owned Windows lifecycle job
Packaged Gateway launcher
Package-owned Windows lifecycle job
Node process hosting the Gateway TCP listener
The original requirement that the TCP listener itself belong to Companion's job rejected this valid arrangement: the launcher was in Companion's job, but Node was not. A longer timeout, direct executable launch or an open loopback port could not establish ownership. The exact Windows job-inheritance mechanism behind that separation was not established.
WindowsNativeGatewayProcessHost now creates the package launcher suspended,
assigns it to Companion's kill-on-close job, retains its process handle, then
resumes it. Assignment/resume failures terminate the created process. Atomic
job-list creation had failed while the package was already active; suspended
creation and assignment worked with the existing Gateway still running.
NativeGatewayRuntime accepts the listener through direct job membership or
WindowsPackagedProcessAncestry: a live same-user descendant chain anchored to
that exact, still-job-owned launcher with the expected package family. Retained
process handles, parent/child creation ordering and bounded ancestry checks
prevent cached PIDs or executable names from being treated as ownership proof.
The runtime also requires complete IPv4/IPv6 inspection, loopback-only listeners,
the requested address, matching process creation times and two consistent TCP
snapshots. Unknown or replaced listeners are rejected, not adopted.
No new cross-package process-handle protocol was added to the packaging repo.
An explicit authenticated handle-handoff contract was considered; the implemented
solution uses local retained-handle attribution with the existing package.
Companion owns the launcher lifetime, while the launcher owns Node cleanup.
NativeGatewayEndpointSecurity and setup authorization use this verification
before credential-bearing connections, including reconnects.
InteractiveGatewayEndpointAuthorizer routes dashboard and web-chat HTTP
credential handoffs to the same runtime's fresh, double-snapshot inspection.
Its synchronous UI callback never starts a Gateway or waits for a busy lifecycle
gate; busy, stopped, disposed or replaced workloads fail closed. It does not
trust cached proof or connected status. App only composes this non-owning adapter;
process inspection stays in NativeGatewayRuntime. Non-native handoffs retain
ManagedLocalGatewayPortProvenanceService authorization. Typed native listener
conflicts retain LocalPortConflict classification instead of becoming generic
network failures.
The legacy path is same-user supervision, not an MXC sandbox or a security boundary against malicious same-user code. There is a narrow crash window between suspended creation and job assignment that can leave a suspended launcher; kill-on-close cleanup applies after assignment, and no launcher code has resumed before then.
This section describes the explicit compatibility path only. The normal native
path uses the same detected providers, activation and exact-model verification
as WSL, followed by a Chat-only completion screen. Already-issued WhatsApp,
Telegram, and Channels receipts remain accepted until expiry and open the
Gateway Dashboard's channels path. Retired Skills receipts are rejected.
NativeGatewaySetupConnection owns the
temporary operator socket in both paths; it never owns or replaces the native
runtime. SetupWindow retains NativeGatewaySetupSession across AI/Ready navigation.
The compatibility page retains the native wrapper with its exact client binding. All wizard RPCs, including progress, cancellation and the optional-policy config/health checks, pass through the generation-fenced request helper and native per-request authorization. Replaced bindings cannot send through a newer client. Page teardown cancels/drains requests and disposes the captured socket wrapper; only the window releases the native session/runtime after page cleanup.
NativeGatewaySetupPage prepares the session and passes it to the shared
WizardPage. The page owns RPC/rendering; the session owns the profile/runtime.
There is no second provider UI or normal terminal-based onboarding path.
- Validate initial configuration, start the package-owned service or legacy runtime as appropriate, and verify its listener before sending credentials.
- Connect using the per-Gateway identity and prefer its stored device token.
When pairing is required,
ApproveWizardPairingAsyncmatches the handshake request ID against that identity's device ID and public key, rechecks endpoint ownership/configuration, and approves only the exact request via the package CLI. Never approve the latest unrelated request or bypass onboarding consent. The package omits listener ownership details if Windows cannot supply process-sequence evidence. Gateway health remains independent, but Companion refuses credential handoff until running on Windows 11 build 26100.4770 or later. Re-runningclawctl setupcannot add this OS capability. - For the legacy profile, clear inherited URL overrides, pin the port and
supply the token in the child environment, not argv. The isolated path
uses package-qualified
openclaw devices listandopenclaw devices approve <request-id>. These commands run in the agent context and use its Gateway config; Companion checks that its saved port and token still match the agent config before each command. It does not pass the token or host profile paths to the CLI. The CLI budget includes slow package startup. Dispose the failed-handshake client before one bounded retry; disconnect alone does not stop its reconnect loop. - Call
wizard.startwithmode=localandinstallDaemon=false; render upstream steps and submit answers throughwizard.next.wizard.cancelends the session. Companion does not install a competing Gateway service.
WizardOnboardingPolicy supplies the same audited optional skip/keep answers to
native, WSL and headless onboarding. Consent, provider/auth/model choices,
permissions, unknown prompts and errors are not silently answered.
For isolated setup, WizardConsoleTail uses the authenticated operator's
upstream logs.tail RPC to project only root-logger console.log entries
after listener verification. The initial cursor is captured before
wizard.start, and later polls are byte/line bounded and already redacted
by OpenClaw. A gap or failure surfaces recovery-terminal guidance rather
than silently discarding an OAuth prompt. No package log-file path or host
profile is passed to the agent; legacy profile and WSL tail modes remain
separate.
The focused path admits only GatewayAiSetupCompletion bound to the same
Gateway endpoint/package family, persisted signing identity, agent, canonical
session and verified primary model. Showing the chooser publishes nothing.
Each destination freshly verifies through the staged native owner, then
CompleteVerifiedAsync stops the setup runtime, restores reload, applies selected
capabilities, validates configuration and health, and performs another exact-model
verification on the restarted runtime before publishing the record. It does not
set the classic wizard-completed flag. Publication reloads unrelated Gateway edits
and uses an expected registry snapshot; an already occupied draft ID is rejected.
After Companion restarts, verification borrows the normal connection manager's
native-authorized operator connection. It rechecks provenance on every request
and never starts a parallel native runtime or disposes that borrowed connection.
The generic SetupGatewaySession rejects native records. Windows-node WSL
workspace finalization never runs for this route.
At the Optional apps checkpoint, WizardOptionalSetupHandoff explicitly cancels
the remaining optional wizard tail, requires cancellation acknowledgement, and
checks config.get validity and authenticated health. The native session records
optional setup as deferred, not upstream wizard completion. Arbitrary errors or
user cancellation cannot take this success path.
After real wizard completion or the validated optional handoff,
NativeGatewaySetupSession.CompleteAsync performs:
Stop setup-owned Gateway -> apply capability policy (and restore legacy reload)
-> validate endpoint/auth and config -> restart with verified ownership
-> authenticated health -> stop setup-owned runtime
-> save and activate GatewayRegistry record -> release setup ownership
Only then does the existing setup-completion restart path hand normal operation
to GatewayConnectionManager and its App-composed
NativeGatewayRuntimeRouter. The isolated branch delegates lifecycle to
clawctl gateway-service; it leaves a pre-existing package service running
when Companion detaches. The legacy branch retains Companion-owned process
supervision. Reconnect verifies package/agent listener identity again rather
than adopting an unrelated port. Failed/cancelled setup
must not publish an unverified Gateway record.
Focused CompleteVerifiedAsync retains isolated ownership through its explicit
restart and replaces the separate CLI health connection with health {} on
NativeGatewaySetupConnection. After the runtime-owned restart, per-handshake
provenance checks, typed startup retries and health share the remaining admission
budget. Restart retains its existing bound and outer completion deadline. Exact-model
verification keeps its existing bound and must use the same authenticated
generation as health; reconciliation cannot replace that generation before
publication. Configuration, selected model, agent, session and signing identity
checks remain mandatory, without automatic pairing or credential recovery.
Only a successful registry publication releases a focused isolated runtime for adoption. An observation timeout or cancellation leaves that runtime with the session until explicit disposal, rather than stopping it as a side effect of a failed readiness wait. Typed inspection-unavailable failures retain that same uncertainty through handshake authorization. Confirmed terminal failures still use the runtime's owned cleanup. Once focused finalization is admitted, another call cannot repeat capabilities, configuration or restart mutations; a published call is an idempotent read. Failed finalization ends its admission operation so explicit Local AI withdrawal on Back/Close can establish a separate bounded connection without replaying it. Runtime-internal launch rollback and pre-existing-service cleanup rules are unchanged. The connection regression covers startup past ten seconds, remaining deadline, cancellation, terminal auth/provenance rejection and generation drift. Installed producer mapping and fixture/live-proof limits are documented in native startup and completion deadlines.
Disconnect stops a Gateway that Companion started, but preserves its data; an already-running package-owned service is not stopped merely because Companion detached. Removing the saved Gateway in Connection settings removes the registry entry, not the agent's OpenClaw configuration or a legacy Companion-owned profile. Windows Installed apps owns MSIX uninstallation and package-managed agent data; Companion's device identity is separate. Back up configuration, credentials, workspace and conversation state before destructive cleanup. The broader Companion/WSL uninstall flow is not a native-Gateway-only uninstaller.
Gateway health alone does not prove AI-provider authentication, required
model-runtime availability or a usable default chat. The focused native path
requires live exact-model verification as well; the compatibility wizard retains
its narrower configuration/health summary. Real-package/provider E2E proof and
MXC isolation remain separate gates. See
Gateway setup responsibilities for the
investigation, production-backed proof and local-only recovery workarounds, and
onboarding wizard for the user flow. Regression coverage
lives in NativeGatewayRuntimeTests, NativeGatewayWindowsProcessHostTests,
NativeGatewaySetupTests, WizardOptionalSetupHandoffTests and
NativeGatewaySetupUxContractTests.
| If you are editing… | Do not grow it. Extract toward… |
|---|---|
src/OpenClaw.Tray.WinUI/App.xaml.cs |
use the authoritative IWindowManager, ITrayController, ActivationRouter, SettingsChangeCoordinator, and AppShutdownCoordinator; keep optional updater dependencies behind UpdateCoordinator and UpdateBackendLoader, never in App type initialization; the remaining A3 extraction target is startup sequencing into AppBootstrapper (planned/deferred) |
src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs |
page policy → HubPageRegistry; search → SearchHost/HubSearchController; notification banner projection → AppNotificationInfoBarPresenter; keep Frame, NavigationView, control application and route side effects in the view; history stays in WorkspaceNavigationHistory |
src/OpenClaw.Tray.WinUI/Windows/WorkspaceWindow.xaml.cs |
route/history policy → WorkspaceNavigation; agent/session projection → WorkspaceProjection; window lifetime → WindowManager; session context menu → WorkspaceSessionMenuController; keep named-control application and existing page hosting in the view |
src/OpenClaw.Tray.WinUI/Services/TrayMenuRenderer.cs |
semantic composition → TrayMenuPresenter; connection toggle projection → ConnectionTogglePresenter; keep WinUI control construction and callback application in the renderer |
src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs |
Keep as the IChatDataProvider facade; atomic runtime coordination → ChatConversationState, lock-internal state mechanics → its queue/reset/history/presentation/lifecycle/approval substates, queue decisions → ChatSendQueuePolicy, history IO → ChatHistoryLoader, mapping → ChatEventMapper, native tool projection → NativeToolProjector, snapshots → ChatSnapshotProjector, metadata → ChatMetadataStore, persistence → ChatStatePersistence |
src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs |
ChatBubbleRenderer, PermissionRequestCard, AttachmentBubbleRenderer; tool rendering stays in ToolCallCardRenderer |
src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs |
Keep as the provider-subscription/selection/timeline-composition root only; composer state → ChatComposerViewModel, composer workflow → ChatComposerController, composer view → ReactorChatComposer.cs |
src/OpenClaw.Tray.WinUI/Chat/ReactorChatComposer.cs |
Declarative view only; workflow/state changes go in ChatComposerViewModel/ChatComposerController, not new Reactor UseState/refs here |
src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs |
ConnectionPagePlan (pure), ConnectionPageViewModel, GatewayDirectConnectService, gateway row models |
src/OpenClaw.Tray.WinUI/Pages/SettingsPage.xaml.cs |
settings read/persist → SettingsPageViewModel + ISettingsStore; keep notification preferences, managed-Gateway setup/removal and saved-indicator in General; AboutPage owns app/Gateway info and update/migration UI |
src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs |
state/commands → PermissionsPageViewModel; runtime projection → PermissionsPageRuntimeSource; persistence → ISettingsStore and IExecApprovalsPresentationStore; keep exact WinUI rendering, clipboard/privacy actions, and save-hint timer in the view |
src/OpenClaw.Tray.WinUI/Services/NodeService.cs |
McpServerHost, CanvasWindowManager, MediaCapabilityHost, RecordingConsentService, SensitiveCaptureExecutor, NodeCapabilityRegistry |
src/OpenClaw.Shared/OpenClawGatewayClient.cs |
GatewayMessageRouter, per-domain API facades |
src/OpenClaw.Shared/Models.cs |
per-domain model files + *Mapper classes |
src/OpenClaw.Shared/Capabilities/SystemCapability.cs |
ExecApprovalService |
src/OpenClaw.SetupEngine/SetupSteps.cs |
one file per step (done for the steps still referencing this file); WslShellClient and GatewayConfigScriptBuilder remain pending. WSL/POSIX quoting is done - use WslShellQuoting, never a local ShellEscape. Setup-time keepalive process ownership is authoritative in KeepaliveProcessManager (see setup-keepalive-process-manager). |
src/OpenClaw.Connection/GatewayConnectionManager.cs |
The three connection-domain owners are authoritative. Keep only the public lifecycle facade, manager-owned operator/state/tunnel orchestration, typed source/sink/security ports, and event forwarding. |
| Any test hand-rolling a temp dir / env save-restore / CLI capture | OpenClaw.TestSupport fixtures |
The ledger is machine-readable and validated by
OpenClaw.Shared.Tests/Architecture/ArchitectureLedgerConsistencyTests.cs.
Rows live between the BEGIN/END markers, one per line, pipe-delimited, with a
leading and trailing pipe. Columns, in order:
id | status | old_owner | closed_responsibility | new_owner | allowed_residue | invariant | guard_test | guard_type | retirement_condition
status:planned|authoritative|closedguard_type:behavioral|golden|source-shape|review-only- For
authoritative/closedrows,guard_testmust name a test asType.Method(validated for format), ORguard_typemust bereview-onlywith a real rationale inguard_test(placeholders like-/noneare rejected). - For
behavioral/goldenrows, the namedguard_testmust actually exist in thetests/source tree - the consistency test scans for it, so renaming or deleting a guard without updating the ledger fails CI. source-shaperows must set a concreteretirement_condition.- No literal
|characters inside a cell (they break the pipe-delimited parse). - Use
-for a genuinely empty cell (except where a value is required above).
| id | status | old_owner | closed_responsibility | new_owner | allowed_residue | invariant | guard_test | guard_type | retirement_condition |
|---|---|---|---|---|---|---|---|---|---|
| automations-content-allocation | authoritative | SettingsShellView full ContentFrame allocation | moving Automations content and overlays below collapsed history controls | ISettingsPageContentInset + CronPage + AutomationsViewportState | ordinary pages retain frame or outer-host margin allocation; window retains and resets embedded-host contribution | collapsed full Settings and embedded pins with collapsed Chat apply 56 DIPs only to the retained Automations ScrollView with frame at origin, never doubled; dialogs/toasts stay full-frame without store/root recreation; inset-only changes notify independently of width/data; the hero accent wash scrolls with the page; EmbeddedOperationInfo follows the host inset | AutomationsViewportStateTests.InsetAppliesOnlyToScrollWithoutRecreatingTheStoreOrRoot | source-shape | retire when mounted page/shell transition proof mandates equivalent retention and inset bounds |
| automations-editor-draft | authoritative | AutomationEditor child hooks | form, revision source, validation and save feedback lifetime | AutomationsRoot with EditorSession | editor applies controls and holds transient discovery/presentation state | disconnect and reconnect preserve unsaved input rather than recreate the starting form | GatewayFixtureUiTests.Automations_EditorDraftSurvivesReconnect | behavioral | - |
| automations-editor-completion | authoritative | AutomationEditor.SaveAsync root callback | unguarded closing or changing the current editor after a delayed save | AutomationsRoot.UpdateEditor + CloseEditor | editor performs the save and reports results through nonce-bound callbacks | an older editor completion cannot discard a replacement editor draft | GatewayFixtureUiTests.Automations_OldSaveCannotCloseNewEditor | behavioral | - |
| automations-inline-inventory | authoritative | AutomationsRoot split detail pane | split-pane, detail-only narrow layout and page-local Back controls | AutomationsRoot inline rows + AutomationDetail | shell title-bar navigation remains shell-owned | opening an automation preserves the inventory and uses a native CommandBar; only editing is modal | AutomationsTextTests.InlineInventory_DoesNotReintroduceSplitNavigation | source-shape | retire when a mounted layout owner exposes an equivalent guard |
| automations-inventory-scope | authoritative | CronPage route agent wired into every list, stats and run query | an inventory limited to the route agent with no discovery of other agents | AutomationsStore.AgentFilter + SetAgentFilter | the route agent stays the initial filter and default owner of new automations | All agents lists every readable automation including paused ones; an agent filter narrows inventory and stats, while recent results stay scoped to the selected job and excluded selection retires late reads | GatewayFixtureProtocolTests.AutomationsStore_AllAgentsListsEveryOwnerAndAgentFilterNarrowsIt | behavioral | - |
| automations-search-reveal | authoritative | CronPage.RevealSearchJob global notification and unscoped selection | selecting a search-targeted automation and reporting a missing one through a global notification | AutomationsStore.RevealAsync + AutomationsRevealChannel + AutomationsRoot.RevealJob | CronPage forwards the shell request and logs an unavailable target; the shell keeps its page, client, handshake and search-generation fences | a search-targeted job is selected in its real inventory row, a job outside a filtered agent switches the filter to All agents, and a missing job selects nothing and shows the in-page notice | GatewayFixtureProtocolTests.AutomationsStore_RevealStaysInTheFilteredAgentUnlessWidened | behavioral | - |
| automations-basic-edit-preservation | authoritative | AutomationEditor advanced and event sections | native authoring of conditions, event sources, failure alerts, delivery routing, timing windows and model options | CronJobForm round-trip with web management through CronProtocol.WebPath | the editor names preserved settings and links to the web | a basic edit preserves unshown settings, omits unchanged timing fields from the patch, explicitly rejects unsupported timing copies/changes without discarding them, and never rewrites an unsupported schedule, action, legacy delivery or a Gateway-omitted delivery, session target or wake mode through defaults | CronJobFormTests.BasicEdit_KeepsSettingsTheNativeEditorDoesNotShow | behavioral | - |
| usage-page-analytics | authoritative | src/OpenClaw.Tray.WinUI/Pages/UsagePage.xaml.cs | usage reads, released-Gateway basic fallback, unsupported-Gateway notice, search/sort/paging gating, stale-reply fencing, incomplete-data recheck, derived allowance attention and loaded-session drilldowns, and guarded CSV export/feedback flow | UsagePageController + UsageProviderReadSource + UsageProviderAttention + UsageDashboardProjection + UsageInsights + UsageSessionDetailProjection + UsageExport + UsageExportWorkflow + UsageHandoffs (native chat by session key, web Usage route only), with UsageJsonParser and the sessions.usage overview retry in OpenClaw.Shared | UsagePage hosts the Reactor tree, forwards connection changes, owns the system save picker/file write/folder launcher and supplies IAppCommands and the PendingChatSessionKey setter to UsageHandoffs | the page renders controller state only, stale replies never replace a newer range, and filters a Gateway cannot apply are neither sent nor shown as active | UsagePageControllerTests.SupersededOverviewReplies_AreDiscarded | behavioral | - |
| usage-provider-read | authoritative | UsagePageController | direct provider RPC, provider-read cancellation/generation, provider snapshot storage and reset notifications | UsageProviderReadSource + UsageRead + UsageProviderAttention | App composes one source, binds the live client/authenticated epoch and disposes it before gateway teardown; UsagePage explicitly injects it. The controller requests one refresh on activation, waits for a matching authenticated binding if needed, and reuses an in-flight read without polling; standalone test hosts may own a source | no duplicate provider read/cache; the page derives attention from current successful rows and valid windows, while reset notifications refresh retained presentation without reading again; disposal of a consuming page does not dispose an injected source | UsagePageControllerTests.InjectedProviderSource_BindsAfterActivationAndDeduplicatesPendingRead | behavioral | - |
| usage-provider-composition | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | page-lifetime provider source creation in production | App composition + UsagePage injected consumption + AppShutdownCoordinator step plan | App contains only construction, live connection binding and shutdown plan entries; the source owns reads, freshness and timers | production UsagePage never creates a second provider source, and source disposal precedes gateway teardown | UsagePageOwnershipTests.ProductionPageUsesTheAppSourceAndShutdownDisposesItBeforeTheGateway | source-shape | retire when mounted app lifecycle proof covers page unload, nonmounted reconnect and shutdown ordering |
| usage-page-xaml-closed | closed | src/OpenClaw.Tray.WinUI/Pages/UsagePage.xaml.cs | AppState Usage/UsageCost/UsageStatus observation, fire-and-forget RequestUsage refreshes and named-control setters | ReactorUsagePage views in Pages/Usage rendering UsagePageController state | UsagePage.xaml keeps one UsageHost border | usage views neither observe AppState, parse Gateway JSON, create colors nor build or launch Gateway URLs | UsagePageOwnershipTests.UsagePageHostAndViewsDoNotParseGatewayJsonOrHardCodeColors | source-shape | retire when UsagePage.xaml is replaced by a direct Reactor route |
| systems-inventory-projection | authoritative | src/OpenClaw.Tray.WinUI/Pages/InstancesPage.xaml.cs | machine inventory joins, presence and status mapping, session relations, measurement freshness and desktop availability projection | SystemsProjection + SystemsFreshness + DesktopPresentation (Shared) + SystemsController (Tray, WinUI-free) | SystemsPage hosts the Reactor SystemsPageView, forwards AppState and Gateway events, runs dialog-confirmed node rename/forget after a live operator.pairing check, routes pairing decisions to Connection and opens the web Systems page, or the web root on a Gateway without one, through IAppCommands.OpenDashboard |
only exact Gateway identities join; node.list entries absent from environments.list are never resurrected; requested placements bind to no machine; Systems never approves pairings, patches Gateway config, reads backup state or probes storage | SystemsProjectionTests.Project_JoinsExactIdentitiesAndClassifiesKinds | behavioral | - |
| instances-page-closed | closed | src/OpenClaw.Tray.WinUI/Pages/InstancesPage.xaml.cs | imperative XAML instance cards and InstanceManagementControls builders | SystemsPageView (Reactor) | instances and nodes routes alias to the systems page | the legacy routes resolve to Systems and no second inventory page exists | HubPageRegistryTests.ResolvePage_OwnsDirectLegacyAndAgentMappings | behavioral | - |
| systems-master-detail-closed | closed | SystemsPageView | independently scrolling inventory ListViews and selected-machine side pane | SystemsPageView single scroll with independent inline native disclosures | SystemsController retains the selected id, including unresolved deep links; SystemsPageView observes default selection arriving after a held first inventory and keys inventory groups independently of pending pairing rows | no second machine details pane or nested inventory scroll; expanding a row preserves siblings and scroll position, and removing pairing rows does not remount the device group | SystemsPageProofTests.InlineExpanders_KeepMultipleRowsOpenWithoutChangingScrollPosition | behavioral | - |
| systems-gateway-native-row | authoritative | SystemsPageView | retained Toolkit control hosting for Gateway hosts and workers | SystemsSettingsExpanderView owns the native SettingsExpander, its header action slot, flat expanded content items and nested Reactor host disposal | SystemsPageView retains content projection, expansion/selection policy and existing command authority; nodes and connected apps retain native Expanders | refresh reconciles existing controls, header actions do not toggle disclosure, and Machine details collapses with the Gateway while its heading copy action retains the allowlisted summary | SystemsPageProofTests.GatewayRow_CollapsesMachineDetailsAndCopiesSummaryFromOneSubtleHeadingButton | behavioral | - |
| systems-initial-selection | authoritative | SystemsPageView | synchronizing the first asynchronous inventory selection with inline expansion | SystemsPageView selection effect and current native row Loaded state | SystemsController retains default-selection policy; explicit same-ID requests still use SelectionRequest | a default selected after the loading view mounts realizes its details without a second selection; user collapse survives later inventory refresh | SystemsPageProofTests.DelayedInitialInventory_ExpandsDefaultRowWithoutAnotherSelection | behavioral | - |
| systems-inventory-group-identity | authoritative | SystemsPageView | sibling inventory group reconciliation across pending pairing changes | SystemsPageView keyed pairing, device, worker and connected-app groups | rows retain their existing per-identity keys and native disclosure ownership | removing a preceding pairing group retains the device group and expanded native rows instead of remounting their controls | SystemsPageProofTests.HeroAndRowBadges_UseReportedStateAndResponsiveNativeLayout | behavioral | - |
| systems-backup-health-closed | closed | SystemsPageView | backup targets, schedules, push-failure presentation, backup.status polling and BackupsPresentation |
web interface through the page-level Open in web action | the Systems mast keeps the single Open in web action | no native Backups section, backup attention pip or backup.status read; backup administration stays in the web interface |
SystemsPageProofTests.SelectedMachine_HasNoBackups | behavioral | - |
| optional-updater-lifetime | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | eagerly constructed vendor updater and vendor-typed orchestration | UpdateBackendLoader + ReleaseUpdateBackendFactory + UpdatumUpdateBackend | UpdateCoordinator retains channel admission, prompts, state publication and install concurrency | dependency load failure disables only automatic updates for this process; successful checks and installs retain one backend | UpdateBackendLoaderTests.Load_DependencyFailureIsContainedAndCached | behavioral | - |
| app-updater-dependency-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | Updatum imports, fields, constructor calls and startup signatures | UpdateCoordinator + IUpdateBackend | composition of the vendor-free coordinator only | Store, Dev and Debug skip before loading; production optional assembly resolution occurs across a non-inlined factory under the loader catch frame | UpdateBackendLoaderTests.StartupFacingOwners_DoNotReferenceOptionalAssembly | source-shape | when process-level blocked-assembly startup tests cover packaged, Dev, Debug and production Release entry points |
| setup-chat-warning-recovery | authoritative | src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs | setup warning lifetime and refresh admission | SetupNativeChatPresentation + SetupNativeChatRefresh | page applies localized InfoBar state, forwards dispatcher/lifecycle/composer navigation events and calls existing authority and renderer owners | clearing a binding clears only presentation; same-client recovery retains draft after full authority checks; composer /new releases the setup target before async creation; node-only events do not remount; visual recheck never retries or settles receipts | SetupNativeChatPresentationTests.SameClientRecoveryRetainsHostAndHealthyRefreshDoesNotReseed | behavioral | - |
| setup-installation-overview | authoritative | src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs | overview phase inference from visual row order | SetupInstallationProgress | page retains logs, download detail, dispatcher forwarding and pipeline lifetime; SetupPhaseStatus applies localized icon/text state | every real installation step has an explicit phase; failed state outranks running; skipped work is not claimed as installed | SetupInstallationProgressTests.EveryActualStep_HasAnExplicitPhaseInPipelineOrder | behavioral | - |
| setup-native-window-lifetime | authoritative | src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs | implicit classic Settings handoff for native routes | SetupNativeConnectionPage + ISetupNativeConnectionHost | SetupWindow owns typed mounting, same-draft routing, cancellation and drain; AdvancedSetupRequested remains explicit classic fallback only | only committed native results advance to access/privacy then AI; departed native pages drain before the setup lock is released | OnboardingPresentationContractTests.NativeEditor_IsTypedAndDrainedBeforeTheRunLockIsReleased | source-shape | when native setup mounting and close ordering have mounted UI lifecycle tests |
| setup-access-draft | authoritative | src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs | capability preset detection and per-visit setup defaults | SetupAccessDraft + SetupCapabilityProfiles | page applies typed projections and forwards input; SetupWindow owns the draft lifetime | only bundled all-on placeholder defaults once; explicit profiles, consent and independent transports survive navigation without persistence | SetupAccessDraftTests.BundledPlaceholder_DefaultsOnlyAtDraftCreation | behavioral | - |
| setup-capabilities-review-closed | closed | src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs | Local AI probing, Tailscale probing, OS privacy probing and installation review | LocalAiSetupControl + TailscaleSetupControl + GatewaySetupPage; OS privacy stays outside setup | capability page owns transport/profile/Fine-tune controls only | ordinary capabilities must not reabsorb probe lifetimes or consent; only the window draft retains profile intent and disclosure | OnboardingPresentationContractTests.SetupOwnership_ClosesCombinedCapabilitiesReview | source-shape | when setup no longer presents capability and installation choices |
| setup-windows-access-preview-closed | closed | src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs | obsolete permissions preview, dedicated control, probe helper and observation policy | removed; native Permissions settings retain their existing owners | no setup privacy probes, preview route or extra stage | removing the developer-only screen must not reintroduce OS probing in capabilities or change runtime consent | OnboardingPresentationContractTests.RetiredWindowsAccessPreview_CannotReintroduceProbesOrAnExtraSetupStage | source-shape | when setup no longer has a preview router |
| setup-browser-completion-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | experimental browser-completion issuer, event payload and activation fallback | SetupNativeHandoffLauncher + SetupDashboardHandoffStore | ordinary Dashboard opening and classic chat/settings/connection restart targets remain | only native receipts can complete setup; obsolete or invalid handles fail visibly without opening a browser | NativeCompletionPresentationTests.CompletionActivation_HasNoSupersededBrowserFallback | source-shape | when setup no longer uses restart receipts |
| setup-instance-admission | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | forwarding an expiring native handoff to a shutting-down primary | NativeRestartAdmission + NativeRestartRecoveryStore | App applies synchronous mutex admission before starting services; ordinary secondary forwarding remains | bounded same-thread waits retain the private handle until authoritative admission; no failed-forward exit discards it | NativeRestartAdmissionTests.DelayedOldOwnerIsNeverForwardedToAndMutexAcquisitionStaysOnOneThread | behavioral | - |
| direct-connect-rollback-observation | authoritative | src/OpenClaw.Tray.WinUI/Services/GatewayDirectConnectService.cs | reasserting stale candidate after rollback CAS conflict | GatewayRegistry.ReplaceSnapshotAndSave/AdoptPersistedSnapshot | only observed persisted active state can reconcile settings; unknown state reports attention | concurrent saved/live authority is preserved, candidate commit requires actual active equivalence, and later normal saves remain possible | GatewayDirectConnectServiceTests.RollbackConflictAdoptsActualNewerSavedSelectionNotStaleCandidate | behavioral | - |
| strict-startup-registration-proof | authoritative | src/OpenClaw.Tray.WinUI/Services/SetupStartupPolicy.cs | interpreting ambiguous registration failure as absence | WindowsStartupTaskRegistration.RegisterForSetup/InspectStrict | old best-effort API stays separate | uncertain registration cannot create duplicate Run-key fallback; only exact enabled task proof may complete it | SetupStartupPolicyTests.AmbiguousRegistrationNeverCreatesRunKey | behavioral | - |
| registry-shared-persistence | authoritative | src/OpenClaw.Connection/GatewayRegistry.cs | per-instance-only compare/write ordering | PersistenceFileLease + persisted snapshot CAS | instance lock precedes path lease; Changed events are outside both | all registry writers reject stale authority and coordinate final compare through replacement; LastConnected merges only for unchanged authority | GatewayRegistryPersistenceTests.OtherInstanceCannotWriteBetweenFinalCheckAndReplacement | behavioral | - |
| setup-settings-owner | authoritative | src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs | hosted direct settings-file merging | SetupSettingsWriter + ISettingsStore | standalone merging remains under the shared path lease | background app.settings.set and setup serialize through one owner, preserve unrelated fields and reject same-field conflicts | SettingsStoreTests.HostedSetupSerializesWithBackgroundSettingsMutationWithoutLosingUnrelatedFields | behavioral | - |
| setup-strict-startup | authoritative | src/OpenClaw.Tray.WinUI/Services/AutoStartManager.cs | treating legacy best-effort return as setup success | SetupStartupPolicy + AutoStartSettingsApplier | native strict application uses the existing mutation gate; classic startup failure warns before restart continues | failed removal/fallback never marks native startup applied; classic optional failure does not lose durable setup | SetupStartupPolicyTests.DisableRequiresBothRunKeyRemovalAndSuccessfulTaskRemoval | behavioral | - |
| setup-completion-stable-authority | authoritative | src/OpenClaw.SetupEngine/GatewayAiSetupCompletion.cs | original signing identity and exact session ownership across fresh clients | OpenClawGatewayClient.AuthenticatedSigningDeviceId + SetupCompletionAuthority + SetupNativeVerification | domain-separated identity hash and exact session persist without path or token contents; server echo remains diagnostics only | accepted connect signing identity supplies authority; missing/rotated disk identity rejects without regeneration or relabeling the live client | OpenClawGatewayClientTests.AuthenticatedSigningIdentity_ComesFromConnectNotOptionalHelloEcho | behavioral | - |
| setup-completion-effective-endpoint | authoritative | src/OpenClaw.Connection/GatewayDashboardBinding.cs | stable persisted endpoint ownership including SSH forwarding port | GatewayClientEndpointResolver + GatewayDashboardBinding | temporary validation listener allocation remains separate | only-local-port drift rejects the original receipt before a new connection | SetupCompletionAuthorityTests.PersistedPortDrift_IsRejectedBeforeFreshSessionCanConnect | behavioral | - |
| setup-native-revoked-token-recovery | authoritative | src/OpenClaw.Connection/GatewayConnectionValidator.cs | typed, one-shot saved operator-token mismatch recovery | GatewayValidationIdentity + GatewayCredentialRecoveryPolicy | shared/bootstrap requires renewed endpoint authorization; normal device-token precedence remains | Check never changes saved identity; recovery preserves keypair and original CAS baseline; authenticated bootstrap replacement survives Next | GatewayConnectionValidatorTests.RevokedDeviceToken_RecoversOnceInCopyAndPreservesKeypairThroughCheckAndNext | behavioral | - |
| setup-startup-update-admission | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | ordinary startup update prompt ordering versus expiring native receipt | ActivationRouter.CheckOrdinaryStartupUpdateAsync | App composes startup and dispatch; ordinary startup update behavior is retained | a shaped native handle bypasses update prompting, not receipt verification; installer exit cannot skip that handoff | SetupDashboardHandoffTests.NativeStartup_DoesNotWaitForUpdatePromptOrExitForInstaller | behavioral | - |
| setup-snapshot-bookkeeping | authoritative | src/OpenClaw.Connection/GatewayRegistry.cs | setup baseline admission during LastConnected Update/Save gap | GatewayRegistry.CapturePersistedSnapshot | canonical memory snapshot is returned unchanged | only LastConnected differences are ignored; authority and configuration edits still reject | GatewayRegistryTests.CapturePersistedSnapshot_AcceptsOnlyPendingConnectionBookkeeping | behavioral | - |
| setup-native-progress | authoritative | src/OpenClaw.SetupEngine.UI/Pages/SetupNativeConnectionPage.xaml | route progress and nonoverlapping narrow-window actions | SetupProgressIndicator + SetupWindow.RefreshFlowProgress | separate progress and wrapping action rows | native connection has the Gateway stage announcement without overlaying Back/Cancel/Check/Next | NativeCompletionPresentationTests.NativeConnectionProgress_HasItsOwnRowAboveWrappableActions | source-shape | when the native editor footer is no longer XAML |
| setup-local-ai-review | authoritative | src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs | Local AI hardware/model readiness and generation-fenced recheck | LocalAiSetupControl | GatewaySetupDetailPage forwards lifecycle; SetupWindow keeps hardware probe cache | unknown is not unsupported; pinned recovery cannot silently opt out; global WSL consent is explicit and retained | SetupReviewOwnershipTests.LocalAiReview_PreservesGenerationEligibilityAndPinnedRecovery | source-shape | when the setup Local AI control has mounted hardware-probe tests |
| setup-tailscale-review | authoritative | src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs | Windows Tailscale read-only readiness probe and draft options | TailscaleSetupControl + SetupTailscaleReadiness | GatewaySetupPage binds inline and detaches on navigation/unload; GatewaySetupDetailPage retains compatibility hosting | bounded generation-fenced status probe precedes selected Tailscale installation; off does not probe; rebind cancels before changing drafts; auth key and identity trust remain separate | SetupReviewOwnershipTests.TailscaleReview_PreservesBoundedReadOnlyProbeAndGenerationFence | source-shape | when mounted injected-probe lifecycle tests have authorized native execution proof |
| setup-wsl-route-guard | authoritative | src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs | installation eligibility for alternate routes and reviewed replacement | SetupAccessDraft | SetupWindow checks CanInstall before navigating; engine retains destructive ownership guard | only ManagedWsl installs and replacement consent binds to the exact inspected distro | SetupAccessDraftTests.AlternateRoutes_NeverInstallWsl | behavioral | - |
| workspace-navigation | authoritative | SettingsShellView.xaml.cs | main landing, chat and Settings route ownership | WorkspaceNavigation, WorkspaceNavigationHistory and WorkspaceWindow | HubPageRegistry retains page metadata; HubSearch owns unified search ranking. Settings reports navigation to Workspace and keeps no back stack | Workspace is the landing page; Settings is one history destination in the same window and Back restores the prior chat | WorkspaceNavigationTests.CompanionRoutes_DoNotReplaceWorkspace | behavioral | - |
| workspace-composer-selection | authoritative | src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs | composer-created thread selection without matching Workspace destination/sidebar/history state | WorkspaceNavigationHistory.SelectChatSession + WorkspaceWindow.OnChatSessionSelected | ChatPage retains mounted-thread/setup-binding ownership and forwards the previous effective thread captured before the composer handoff; Workspace applies agent/sidebar and history-control updates | Initial Home is bound to the previous cached/default conversation before /new adds one history entry; same-key echoes add no entries; late completion on Notifications changes only retained ChatDestination; no queue, navigation replay, or remount of the already selected chat | WorkspaceChatSelectionTests.InitialComposerConversation_IsThePreviousHistoryEntryAfterNew | behavioral | - |
| hub-chat-hosting | closed | SettingsShellView.xaml.cs | hosting Chat as a Settings navigation page | WorkspaceWindow with existing ChatPage under ContentHost | legacy chat route redirects to Workspace chat | SettingsShellView never mounts ChatPage; Settings is a retained sibling of chat in the same window and cannot destroy the composer draft | WorkspaceWindowProofTests.DefaultLaunchAndCompanionRefocus_PreserveNativeComposerDraft | behavioral | - |
| workspace-window-lifetime | authoritative | WorkspaceWindow.xaml.cs | one shared foreground surface for chat and settings | WindowManager | App composes callbacks only; Workspace close resets the navigation scope and disposes the Settings view | Settings deep links reuse the one Workspace window (same HWND, no second Settings window) | WorkspaceWindowProofTests.NativePagesAndOwnerLinks_StayInOneWorkspaceWindow | behavioral | - |
| workspace-profile-completion | authoritative | WorkspaceWindow.xaml.cs | ad hoc Windows account prefill or Gateway profile writes from the window | ProfileCompletionService + ProfileCompletionContext + WindowsAccountIdentityProvider | Workspace silently fills missing owner fields when it observes a profile, including after an app update; no setup step, completion dialog, or Skip store; manual edits stay in the Gateway's own profile settings and Windows adds no profile editor; unlike macOS's dynamic host-photo fallback, Windows persists the photo on the Gateway with shared visibility | before account access and at later read/write boundaries, connection snapshot ID, selected registry ID, connected client and the same record's managed eligibility must agree; only the canonical owner with write scope is filled; name or email keeps the name, avatar keeps the photo, including each field's fresh recheck (best effort, not atomic compare-and-set) | ProfileAutoFillCoordinatorTests.SelectionMovesBeforeClientRetirement_RejectsOldClient_ThenAllowsCoherentTarget | behavioral | native proof when launching is authorized |
| workspace-profile-autofill-lifetime | authoritative | WorkspaceWindow.xaml.cs | per-window last-Gateway attempt flag, in-flight fill ownership and retry scheduling | ProfileAutoFillCoordinator | App composes one process-lifetime coordinator; Workspace reports loaded profiles and subscribes/unsubscribes to read-only identity refresh notifications, including a replacement client on the same Gateway | one writer across window reopen; remember every attempted Gateway; only retryable results release that Gateway's attempt; uncertain writes remain non-retrying even on reconnect; success or fault clears pending state and may hand off once to the still-current differing observed context, never an immediate same-context Unavailable loop; original faults propagate and pending faults use their own event-handler guard | ProfileAutoFillCoordinatorTests.OncePerGateway_SurvivesObserversAndGatewayRoundTrip | behavioral | - |
| workspace-profile-autofill-state-closed | closed | WorkspaceWindow.xaml.cs | window-owned profile service, attempt history and single-flight state | ProfileAutoFillCoordinator | Workspace applies identity and reports observations to the App-owned coordinator | window recreation cannot recreate attempt history or a concurrent writer; subscribe once and detach on close | ProfileCompletionTests.Window_ProfileAutoFillStateStaysInAppLifetimeOwner | source-shape | when Workspace identity uses mounted injected-lifecycle coverage |
| workspace-profile-completion-ui | closed | ProfileCompletionDialog.cs + WorkspaceWindow.xaml.cs | dedicated completion dialog, menu entry, per-field retry UI and Skip persistence | ProfileCompletionService for automatic fill; the Gateway's own profile settings for manual edits | Workspace only observes identity and triggers automatic fill | do not restore a setup-specific profile offer or parallel editor | ProfileCompletionTests.Window_DoesNotHostProfileCompletionUi | source-shape | when the Workspace profile entry point is retired |
| workspace-card-renderer | closed | WorkspaceContentPage.xaml.cs | speculative management-page cards and rows | removed per Home/Sessions-only Workspace correction | real management pages remain in the Settings companion | removed pages cannot return through navigation history or deprecated links | WorkspaceNavigationTests.DeprecatedWorkspaceLinks_ReturnHomeAndCannotResurrectRemovedPages | behavioral | - |
| workspace-agent-projection | authoritative | WorkspaceWindow.xaml.cs | ad hoc agent and session identity projection | WorkspaceProjection | view applies projected values | no fixture agents and no background-session selection | WorkspaceNavigationTests.Projection_DoesNotSelectBackgroundSessionsForAssistantChat | behavioral | - |
| chat-voice-readiness | authoritative | ChatPage.xaml.cs | timed retries for cold voice launch | PendingVoiceActivation | ChatPage forwards native readiness and cancels pending activation on unload, retained Settings suspension or legacy surface | one explicit request is consumed once when ready, never after cancellation or page exit | PendingVoiceActivationTests.DelayedComposer_ConsumesExactlyOnceWhenReady | behavioral | - |
| chat-retained-capture-wiring | authoritative | WorkspaceWindow.xaml.cs and ChatPage.xaml.cs | retained Settings transition and capture lifetime wiring | ChatPage.SuspendSurface and ChatComposerSession.SetHostVisible | Workspace suspends before hiding Chat; the session intersects host and composer visibility | pending and active capture are cancelled before Settings collapse without discarding the host or draft | WorkspaceNavigationTests.SettingsTransition_SuspendsCaptureBeforeHidingRetainedChat_AndSearchKeepsLocalAliases | source-shape | when a mounted ChatPage navigation regression directly asserts pending and active capture cancellation before Settings collapse |
| chat-capture-progress | authoritative | src/OpenClaw.Tray.WinUI/Services/VoiceService.cs | per-listen transcription and level routing | VoiceService.ListenOnceAsync over the invocation-owned AudioPipeline | SpeechToTextService implements the transcription I/O contract; AudioPipeline retains capture, VAD, shutdown flush and result aggregation | a cancelled pipeline's shutdown progress cannot enter another listen's preview; each call retains its own result and legacy global events remain available | VoiceServiceProgressRoutingTests.CancelledFlush_DoesNotReachReplacementPreviewOrFinishReplacementListen | behavioral | - |
| chat-capture-progress-wiring | authoritative | src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs | service-wide progress subscriptions in the native composer | per-call VoiceService callbacks plus ChatPage's existing cancellation, host and surface-generation checks | ChatPage dispatches progress onto its UI thread without subscribing to service broadcasts | an unrelated pipeline cannot pass a newer capture's lifetime checks and update its live preview | WorkspaceNavigationTests.ChatCaptureProgress_UsesPerInvocationCallbacksAndKeepsLifetimeFence | source-shape | when a mounted ChatPage regression directly drives overlapping per-call progress across Settings suspension and return |
| test-temp-dir | authoritative | scattered test files | hand-rolled Path.GetTempPath temp dirs in migrated tests | OpenClaw.TestSupport.TempDirectory | pre-existing un-migrated tests until adopted | temp dirs are created unique and best-effort deleted | TestSupportFixtureTests.TempDirectory_CreatesAndDeletes | behavioral | when all temp-dir tests are migrated |
| test-env-scope | authoritative | scattered test files | hand-rolled env var save/restore in migrated tests | OpenClaw.TestSupport.EnvironmentScope | pre-existing un-migrated tests until adopted | env vars set in a test are restored on dispose | TestSupportFixtureTests.EnvironmentScope_RestoresOriginal | behavioral | when all env-mutating tests are migrated |
| test-cli-harness | authoritative | CLI test projects | duplicated stdout/stderr/env capture tuples | OpenClaw.TestSupport.CliHarness | - | stdout/stderr/env lookup are captured consistently | TestSupportFixtureTests.CliHarness_CapturesAndLooksUp | behavioral | when CLI tests adopt the harness |
| test-fake-mcp | authoritative | OpenClaw.WinNode.Cli.Tests | private internal FakeMcpServer copy | OpenClaw.TestSupport.FakeMcpServer | - | one loopback MCP server captures method/body/auth and returns canned/timeout responses | TestSupportFixtureTests.FakeMcpServer_CapturesRequest | behavioral | when all MCP-round-trip tests share it |
| test-app-mcp-client | authoritative | tests/OpenClaw.Tray.IntegrationTests/McpClient.cs | authenticated MCP request/response helper | OpenClaw.TestSupport.McpClient | original app tests retain the same API through a shared namespace import | fixture-host and original MCP integration consumers share request correlation, bearer handling and tool-error parsing without changing original fixture defaults | GatewayFixtureAppTests.RealOperatorPopulatesSessionsWithoutEnablingNodeExecution | behavioral | - |
| gateway-fixture-isolation | authoritative | App startup and service boundaries | implicit isolated-profile safety assumptions | OpenClaw.Shared.GatewayFixtureIsolation | composition-root validation and narrow service checks | explicit fixture mode requires valid absolute profile and setup-local overrides; ordinary isolated mode is unchanged | GatewayFixtureIsolationTests.Get_MissingOrRelativeRoot_ThrowsWithoutFallback | behavioral | - |
| test-gateway-builder | authoritative | OpenClaw.Connection.Tests | per-file MakeRecord(id,url) helpers | OpenClaw.Connection.Tests.GatewayRecordBuilder | pre-existing MakeRecord until migrated | gateway record test data has one builder | TestSupportFixtureTests.GatewayRecordBuilder_BuildsRecord | behavioral | when MakeRecord helpers are removed |
| test-settings-builder | authoritative | scattered test files | ad hoc SettingsData construction in migrated tests | OpenClaw.TestSupport.SettingsDataBuilder | pre-existing un-migrated tests until adopted | settings test data starts from production defaults | TestSupportFixtureTests.SettingsDataBuilder_StartsFromDefaults | behavioral | when settings tests adopt the builder |
| json-read-helpers | authoritative | OpenClaw.Shared (multiple files) | duplicate non-nullable fallback-returning JsonElement getters | JsonReadHelpers | null-sentinel / non-negative / whitespace-absent / trimming variants stay separate | canonical non-nullable fallback JSON coercion; divergent-contract helpers are not blindly routed here | JsonReadHelpersTests.GetString_ReturnsNull_WhenPropertyMissing | behavioral | when the non-nullable fallback getters are all routed here |
| ollama-node-command-policy | authoritative | src/OpenClaw.Shared/Models.cs | Ollama read-only and sensitive command taxonomy | OllamaNodeCommandPolicy | Models consumes the focused command sets when projecting Command Center health | ollama.models remains optional read-only inventory, ollama.chat remains sensitive, and neither becomes a platform parity requirement | OllamaNodeCommandPolicyTests.ClassifiesCommands | behavioral | - |
| wsl-posix-quoting | authoritative | OpenClaw.SetupEngine/SetupSteps.cs | ad hoc ShellEscape with divergent wrap semantics | WslShellQuoting | - | WSL command lines use POSIX single-quote quoting via WslShellQuoting not cmd/PowerShell quoting | WslShellQuotingTests.QuotePosixSingleQuote_WrapsAndEscapesEmbeddedQuote | behavioral | when no code builds WSL command lines outside WslShellQuoting |
| setup-shellescape-closed | closed | src/OpenClaw.SetupEngine/SetupSteps.cs | private ShellEscape helpers with divergent wrap semantics | WslShellQuoting | - | OpenClaw.SetupEngine builds WSL command lines only via WslShellQuoting; no local ShellEscape helper anywhere in the project | SetupStepsShellEscapeClosureTests.SetupEngine_DoesNotReintroduce_PrivateShellEscape | source-shape | when no file under src/OpenClaw.SetupEngine builds any WSL command strings |
| setup-keepalive-process-manager | authoritative | src/OpenClaw.SetupEngine/SetupSteps.cs (StartKeepaliveStep) | setup-time WSL keepalive process discovery, start, marker read/write, command-line identity, and rollback cleanup | KeepaliveProcessManager (raw OS calls delegated to internal IKeepaliveProcessRuntime seam; StartKeepaliveStep is the only caller that reads SetupContext) | StartKeepaliveStep keeps Id/DisplayName and thin ExecuteAsync/RollbackAsync orchestration only | setup-time keepalive never hard-fails the pipeline on start failure (null PID or thrown exception both soft-fail identically); its marker path/JSON are the intentional handoff consumed by the tray keepalive service; rollback kills only wsl/wsl.exe processes whose command line matches this distro via WslCommandLineMatcher, leaves wrong-distro/unmatched command lines untouched, and deletes only its own marker/empty directory | KeepaliveProcessManagerTests.RollbackAsync_KillsOnlyMatchingDistroProcesses_LeavesOthersUntouched | behavioral | when StartKeepaliveStep contains no process/marker logic of its own |
| wsl-distro-install-path | authoritative | OpenClaw.SetupEngine/SetupSteps.cs | inline Path.Combine wsl distro install-path derivation | DistroInstallPathPolicy | - | new installs use the strict supported name grammar; teardown accepts only unambiguous single-segment names whose canonical path is an immediate child of LocalDataDir\wsl with no aliases, case or Unicode collisions, or reparse points at the root or child | SetupStepsTests.DistroInstallPathPolicy_ResolvesImmediateChild | behavioral | - |
| setup-managed-distro-ownership | authoritative | ExistingConfigDetector, CleanupStaleDistroStep, and CreateWslInstanceStep | durable ownership evidence parsing, current-user WSL registration binding, and marker lifecycle | ManagedDistroOwnership plus WindowsWslRegistrationInspector | detector and setup steps request ownership checks or scoped marker operations only | automatic unregister requires durable OpenClaw evidence plus exactly one readable current-user WSL registration whose canonical BasePath is the expected managed install path; automatic orphan-directory deletion requires a path-bound marker; missing, duplicate, malformed, unreadable, or mismatched registration metadata fails closed; exact UI or CLI destructive consent may override | SetupStepsTests.CleanupStaleDistro_PreservesUnownedRegisteredDistro | behavioral | - |
| managed-local-provenance | authoritative | scattered connection, setup, browser, and reconnect call sites | implicit loopback trust and duplicated strong-credential listener checks | ManagedLocalGatewayPortProvenanceService | callers request inspection, authorization, or conflict repair only | unknown, incomplete, conflicting, or changed Windows listener ownership never receives strong credentials or destructive remediation; relayless ownership requires a complete empty Windows snapshot, expected-distro systemd MainPID proof, and immediate complete empty revalidation | ManagedLocalGatewayPortProvenanceServiceTests.InteractiveCredentialGate_ExpectedCacheThenOwnerChanges_FailsClosed | behavioral | - |
| local-ai-gateway-distro-binding | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | hardcoded Local AI WSL distro selection | LocalAiGatewayDistroResolver | App loads the gateway registry and composes the resolver, provider coordinator, and runtime | the singleton Local AI installation binds to exactly one explicit setup-managed local no-SSH gateway record; its record ID and SetupManagedDistroName are pinned and revalidated before every WSL command, while missing, ambiguous, unavailable, or drifted ownership fails closed | LocalAiGatewayProviderCoordinatorTests.Quiesce_OwnerDriftsAfterInspection_BlocksFirstMutation | behavioral | - |
| gateway-wizard-restart-recovery | authoritative | WizardPage + SetupWizardRunner reconnect call sites | duplicated exact-version terminal-restart classification and bounded provenance retry orchestration | GatewayWizardRestartRecoveryPolicy | WizardPage and SetupWizardRunner apply hosted and headless lifecycle and consume provenance inspection results | only managed-local restart-like disconnects may retry NoListener or the typed snapshot-changed race; other unknown or conflicting ownership fails immediately, retryable startup close 1013 stays inside the existing reconnect bound, and exact Gateway 2026.7.1 final model-check close 1012 completes only after a fresh hello-ok, and a terminal hosted-wizard payload completes on the exact TUI SIGTERM termination only when the request just sent answered the authoritative final done acknowledgement step | GatewayWizardRestartRecoveryPolicyTests.Exact2026_7_1TerminalModelCheckServiceRestart_IsExpected | behavioral | when the 2026.7.1 terminal-restart compatibility path is removed |
| managed-local-repair | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs and direct reconnect callbacks | repair eligibility, restart budgets, port remediation, and reconnect verification | ManagedLocalGatewayAutoRepairMonitor + ManagedLocalGatewayRepairCoordinator | App composition and dependency callbacks only | explicit disconnect and gateway switches abort repair before restart or reconnect | ManagedLocalGatewayRepairCoordinatorTests.UserDisconnectedIntent_AbortsBeforeProbeOrRestart | behavioral | - |
| app-managed-local-repair-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | managed-local repair loops, probing, restart budgeting, and verification implementation | ManagedLocalGatewayAutoRepairMonitor + ManagedLocalGatewayRepairCoordinator | service construction, callback adapters, and lifetime wiring only | App remains the composition root and does not regain repair implementation | AppRefactorContractTests.ManagedLocalGatewayRepair_StaysDelegatedToDedicatedOwners | source-shape | when App no longer constructs the managed-local repair services directly |
| connection-page-direct-connect-closed | closed | src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs | direct-connect registry, identity-token, settings, rollback, terminal-wait, and runtime-tunnel transaction | GatewayDirectConnectService | add-form control reads, input validation, result text, and post-success visual refresh only | the page delegates one request; rollback restores the durable registry before identity and settings, reconnects a previously live gateway, and a later credential writer wins | GatewayDirectConnectServiceTests.Connect_Failure_RestoresPreviousLiveConnection | behavioral | when the Connection page no longer contains any direct-connect persistence or rollback logic |
| connection-status-direct-connect-closed | closed | src/OpenClaw.Tray.WinUI/Windows/ConnectionStatusWindow.xaml.cs | direct-connect registry, settings, rollback, terminal-wait, and runtime-tunnel transaction | GatewayDirectConnectService | diagnostics control reads, input validation, and result text only | diagnostics direct connect delegates one request and cannot report success before a terminal manager state | AppRefactorContractTests.StatusWindowDirectConnect_WaitsForManagerStateBeforeReportingConnected | source-shape | when the status window no longer contains direct-connect persistence or rollback logic |
| app-window-manager | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | Settings companion, Workspace, status, setup, canvas request, and runtime-anchor window creation, reuse, focus, theme, owner, and lifetime mechanics | IWindowManager + WindowManager | App owns composition, typed activation-plan application through WindowManager, service-policy callback adapters, setup restart policy, pairing approval dialog workflow and shell, and shutdown-plan callback construction | distinct window types and exact routes are preserved; Settings close resets navigation scope; setup replacement waits for cleanup; shutdown closes owned windows once before provider disposal | WindowManagerTests.CloseForShutdown_GatesCreationAndClosesOwnedWindowsOnce | source-shape | when App is replaced as the WinUI composition root |
| app-window-surface-ownership-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | concrete non-tray window fields, constructors, show/hide/focus/theme/close mechanics, and window event lifetime | IWindowManager + WindowManager | interface forwarding, immutable request construction, route and policy callbacks, and setup restart dialog policy only | App cannot regain a parallel Settings, Workspace, status, setup, canvas-request, or runtime-anchor owner, nor revive the retired chat popup | AppSurfaceOwnershipContractTests.App_DelegatesConcreteTrayAndWindowOwnership | source-shape | when App is replaced as the WinUI composition root |
| app-tray-controller | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | tray icon creation, tray popup coordination, click routing, tooltip and live-toggle refresh, theme, callbacks, and disposal | ITrayController + TrayController | App captures immutable snapshots, implements semantic action callbacks, triggers refresh from authoritative state, preserves startup construction order, and constructs shutdown-plan callbacks | one tray icon and root menu are reused; A1 presenters retain semantics; TrayMenuWindow retains native popup mechanics; callbacks detach and resources dispose once | TrayControllerTests.Dispose_UnsubscribesAndDisposesEachResourceOnce | source-shape | when the WinUI tray surface is replaced |
| app-tray-surface-ownership-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | concrete tray icon, root menu, weak live-control state, event subscriptions, popup build coordination, and resource disposal | ITrayController + TrayController | immutable snapshot and action callbacks plus state-change triggers only | App cannot regain tray controls or popup lifetime and TrayController cannot duplicate A1 semantic projection or TrayMenuWindow native mechanics | AppSurfaceOwnershipContractTests.App_DelegatesConcreteTrayAndWindowOwnership | source-shape | when the WinUI tray surface is replaced |
| native-tool-projector | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | pure native tool identity, allowlisted summaries, bounded redacted structured details, payload extraction, and flattened-history detection/classification/summary | NativeToolProjector | ChatEventMapper and ChatHistoryLoader call the projector; ChatConversationState supplies scoped correlation plans and ChatMetadataStore owns persistence | unknown identities remain truthful Tool; title aliases are strict; preview limits do not truncate the separately bounded full-detail projection; yield continuation input stays suppressed; live/history projection stays consistent | NativeToolProjectorTests.ExtractToolIdentity_TitleRequiresExactTrustedAlias | behavioral | - |
| provider-native-tool-projection-closed | closed | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | private static copies of native tool identity, display argument, payload, flattened-history projection, and scoped metadata upsert | NativeToolProjector + ChatEventMapper + ChatHistoryLoader + ChatConversationState + ChatMetadataStore | provider forwards typed tool metadata writes while retaining bridge IO, telemetry, and event publication only | provider does not regain native tool JSON projection, identity policy, timeline correlation, or metadata persistence | review-only: pure projection, atomic correlation, and persistence are delegated to focused owners while the provider remains the IO facade | review-only | when OpenClawChatDataProvider is retired |
| chat-conversation-state | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | provider-owned runtime gate and cross-domain state transactions | ChatConversationState | sole lock, timeline and entry metadata, connection/disposal flags, and typed orchestration across lock-free substates; provider supplies bridge context and coordinates IO, telemetry, and events | one authoritative lock atomically commits reset, reconnect, dispose, queue, history, and event transitions without duplicate shared versions | ChatRuntimeOwnershipContractTests.Root_CoordinatesCrossDomainCommitsUnderSoleGate | source-shape | when the chat runtime is replaced by a different atomic transaction boundary |
| chat-provider-state-closed | closed | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | private runtime gate and mutable conversation/queue/reset/history collections | ChatConversationState | bridge subscription, telemetry, public API/events, composition, persistence coordination, and static image preview compatibility | provider cannot regain a private state lock or duplicate runtime collections | ChatRuntimeOwnershipContractTests.Provider_DelegatesRuntimeStateWithoutPrivateGate | source-shape | when OpenClawChatDataProvider is retired |
| chat-send-queue | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs and monolithic ChatConversationState | send admission, next-drain eligibility, local echo and run correlation, deferred-admission classification/backoff, retry decisions, and queue commit mechanics | ChatSendQueuePolicy + ChatQueueState | ChatConversationState coordinates queue commits with timeline, reset, and lifecycle state; provider executes typed bridge dispatch plans and records telemetry | queue collections and mechanics live in the lock-free substate under the sole conversation lock while pure policy decisions remain separately testable | ChatRuntimeOwnershipContractTests.RuntimeSubstates_AreLockFreeAndVersionOwnershipIsUnique | source-shape | when queue state and decision policy are replaced without a lock-internal substate |
| chat-reset-state | authoritative | monolithic ChatConversationState | reset versions and cutoffs, accepted and ignored runs, submitted echoes, no-run send proof, buffered starts, and remote-backfill gates | ChatResetState | ChatConversationState supplies queue and lifecycle facts and atomically applies returned typed lifecycle transitions | reset mechanics have no private lock or duplicate version and are invoked only under the conversation lock | ChatRuntimeOwnershipContractTests.RuntimeSubstates_AreLockFreeAndVersionOwnershipIsUnique | source-shape | when reset gating is replaced without a lock-internal substate |
| chat-history-state | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs and monolithic ChatConversationState | session identity, loaded/revision state, reset-cleared identity, connection generation, activation barrier, commit-token validation, and transcript merge reconciliation | ChatHistoryState | ChatConversationState supplies reset/status/disposal facts and atomically coordinates timeline commit; no history IO lives in the substate | one authoritative connection generation and reset-aware commit token accepts or drops history under the sole conversation lock | ChatConversationStateTests.HistoryGeneration_WaitsForLoaderActivation | behavioral | - |
| chat-history-loader | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | chat.history fetch lifetime, in-flight ownership, generation cancellation, retry budget/scheduling, ordered transcript rebuild plans, and stale-result delivery filtering | ChatHistoryLoader | ChatHistoryState owns authoritative identity and generation tokens; ChatConversationState coordinates commit acceptance; provider publishes typed completion results and notifications | stale connection/reset responses cannot commit, deliver, clear a newer in-flight owner, or carry retry work/budget across generations; authoritative reload coalescing remains generation-safe | OpenClawChatDataProviderTests.LoadHistoryAsync_DelayedRetryDoesNotCrossResetGeneration | behavioral | - |
| chat-checkpoint-history-replacement | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | checkpoint-restore timeline clearing, replacement generation fencing, and replacement-over-authoritative reload priority | ChatHistoryState + ChatHistoryLoader coordinated by ChatConversationState | provider starts the typed replacement transition, publishes its immutable snapshot, and delegates gateway IO | replacement atomically clears timeline metadata, invalidates stale results, preserves post-restore live entries, and suppresses stale retries and notifications | ChatConversationStateTests.HistoryReplacement_ClearsTimelineAndAdvancesOwnedTokenAtomically | behavioral | - |
| chat-presentation-state | authoritative | monolithic ChatConversationState | sessions, usage, models, choices, command catalog/fetch epoch, pending model patches, keyless diagnostics, remembered last state, and immutable projection inputs | ChatPresentationState | ChatConversationState supplies timeline/queue/reset/history snapshots and coordinates session identity and usage timeline updates | presentation mechanics have no private lock, IO, or mutable collection exposure and snapshot values remain byte-for-byte compatible | OpenClawChatDataProviderTests.RuntimeGolden_PublicSnapshotPreservesCrossDomainState | golden | - |
| chat-lifecycle-state | authoritative | monolithic ChatConversationState | active run IDs/start sequences, pending aborts, aborted runs/threads, terminal-run dedupe, and lifecycle sequence | ChatLifecycleState | ChatConversationState coordinates lifecycle changes with reset gates, queue state, and timeline reducer events | lifecycle mechanics have no private lock and reset/reconnect/dispose remain root-coordinated atomic transitions | ChatRuntimeOwnershipContractTests.Root_CoordinatesCrossDomainCommitsUnderSoleGate | source-shape | when run lifecycle is replaced without a lock-internal substate |
| chat-approval-state | authoritative | monolithic ChatConversationState | bounded seen-approval identity order/set and alternate-ID correlation | ChatApprovalState | ChatConversationState coordinates approval identity with permission timeline transitions; ChatEventMapper remains the pure payload mapper | approval identity mechanics have no private lock, IO, or timeline callbacks | ChatRuntimeOwnershipContractTests.RuntimeSubstates_AreLockFreeAndVersionOwnershipIsUnique | source-shape | when approval correlation is replaced without a lock-internal substate |
| chat-event-mapper | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | pure agent-stream payload to ChatEvent/content mapping and terminal approval decision classification | ChatEventMapper | provider retains stateful approval dedupe and telemetry orchestration through ChatConversationState | tool, reasoning, lifecycle, command-output, job, and permission payloads map without provider-owned JSON mapping branches | ChatEventMapperTests.Map_ApprovalRequestPreservesIdentityAndActions | behavioral | - |
| chat-agent-assistant-text-closed | closed | ChatEventMapper agent assistant delta mapping |
rendering live reply text from agent assistant events alongside chat frames |
ChatConversationState.ApplyAssistant (chat frames) + ConnectEnvelopeBuilder chat-only-assistant-text |
Gateways that ignore the cap still send agent assistant text; the mapper ignores it and ChatThroughputTracker counts cumulative chat growth | one live reply renders one bubble whether or not the Gateway filters agent assistant text; agent text is never merged into the timeline | InteractiveGatewayChatTests.LiveReplyRendersOneBubbleWithOrWithoutAgentAssistantText | behavioral | when the native timeline adopts a separate current-item agent text view |
| chat-reasoning-presentation | authoritative | native conversation timeline | admitted cumulative thinking occurrences, exact saved-message receipts and visible reasoning preference projection | ChatTimelineReducer + ChatReasoningPresentation | ChatEventMapper reads supplied facts; ChatConversationState acknowledges accepted publication under its lock; ChatHistoryState preserves the active stream; root passes session preferences and the current run | no invented item/receipt identity; no imported-message acknowledgment; empty tail cannot transfer earlier reasoning; terminal/reset clears previews; saved thinking wins over draft transfer | ChatStreamingParityTests.ThinkingReceipt_OnlyExactNativePublicationHandsOffPreview | behavioral | - |
| chat-tool-output-recovery | authoritative | bounded chat history and native tool disclosures | lazy hydration of a saved tool result without changing transcript authority | OpenClawGatewayClient + ChatConversationState + OpenClawChatDataProvider | the client owns authenticated bounded message reads; conversation state admits exact session/reset/history/entry/result identities; ChatToolOutputOperation retires view lifetimes; ToolCallCardRenderer owns inline previews and automatically loads saved output only when its side-panel reader opens | canonical result-message/call identity is separate from invocation input; no inline render-time fetch; cancellation and stale completions cannot replace another slot; server/client limits stay explicit; no raw payload or private continuation disclosure | OpenClawChatDataProviderTests.ToolRecovery_ScopeChangeRejectsPendingAndFutureReads | behavioral | - |
| chat-tool-details-profile | authoritative | native tool details and full-output recovery | connection-bound reader identity verification and opaque revision invalidation | ChatToolDetailsProfile owned once by GatewayClientChatBridge | reuses users.self and WorkspaceIdentitySource parsing/deadline/category; provider forwards start/completion invalidation; consumers capture and compare ChatToolDetailsProfileState | unknown denies; verification advances revision before reading; same canonical ID recovers at a new revision, different ID retires until reconnect; no display identity or avatar ownership is imported, and no private profile ID is exposed | ChatToolDetailsProfileTests.RevalidationRetiresCapturedReaderRevisionEvenForTheSameAccount | behavioral | - |
| chat-snapshot-projector | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | thread/compose-target/status/model/catalog/timeline-generation/history-revision/queued-message snapshot projection including flattened gateway session classification | ChatSnapshotProjector | provider supplies bridge handshake context; ChatConversationState captures immutable projection input; SessionDisplayResolver owns flattened session display mapping | public snapshots preserve defensive dictionary copies, raw session keys, flattened agent/background classification, compose readiness, synthetic pending thread behavior, model order, and render identity generations | OpenClawChatDataProviderTests.RuntimeGolden_PublicSnapshotPreservesCrossDomainState | golden | - |
| chat-content-formatting | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | content text formatting, truncation, content-block seam repair, and trace hashing | ChatContentFormatting | thin provider forwarders (TruncateForChatEntry, LooksLikeSystemControlNote, RepairContentBlockSeams, TruncateChatEvent) kept for existing test call sites; system-note, native tool, and flattened-history projection belongs to NativeToolProjector | content truncation and seam repair output is preserved byte-for-byte while tool identity/classification has one canonical owner | ContentBlockSeamRepairTests.RepairsKnownSeams | behavioral | when provider forwarders are removed and callers use focused owners directly |
| chat-metadata-store | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | live tool/attachment metadata dictionaries, scoped native-tool identity upsert, save locks/timers/versions, atomic JSON persistence, session eviction, and attachment-marker build/escape/rehydration | ChatMetadataStore | ChatConversationState supplies a typed session/reset/correlation write plan; provider retains the public static image-preview cache | metadata persistence, identity-strength upgrade, normalization, bounded eviction, marker security, and generation-aware idempotent reset eviction are owned under the metadata lock without raw attachment bytes on disk | ToolMetaCacheTests.CacheToolMeta_SameToolCallId_UpgradesSpecificIdentityWithoutDuplicate | behavioral | - |
| chat-state-persistence | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | persisted aborted-message IDs plus last-chat-state debounce/version/atomic save lifecycle | ChatStatePersistence | provider retains the nested LastChatState compatibility type and owns bridge history fetch orchestration | corrupted state fails closed, reset removes aborted IDs, stale reset generations cannot persist, and selected/snapshot state writes remain atomic | ChatStatePersistenceTests.ResetFence_RejectsStaleAbortedIds | behavioral | - |
| app-activation-router | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | deep-link/protocol/toast/forwarded activation normalization, current-user IPC, input guards, and confirmation decisions | ActivationRouter | App.ActivationRouter.cs implements IActivationPlanSink only and applies exactly one typed semantic plan through existing A2 owners and services | launch, protocol, toast, and forwarded activation resolve to the same routes; a no-argument secondary launch retries the existing IPC boundary and forwards the default Hub route; current-user IPC, oversized-payload rejection, and confirmation/redaction semantics are preserved | ActivationRouterTests.ForwardLaunchToPrimaryAsync_ListenerStartsLate_RetriesAndDispatchesDefaultHub | behavioral | - |
| app-activation-router-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | concrete deep-link IPC, toast argument routing, and single-instance forwarding production logic | ActivationRouter | App.ActivationRouter.cs implements IActivationPlanSink only, dispatching one typed plan per activation | App does not regain a parallel activation production path outside ActivationRouter | AppRefactorContractTests.ToastActivation_RoutesOnUiThread | source-shape | when App is replaced as the WinUI composition root |
| app-settings-change-coordinator | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | detached snapshot comparison, SettingsChangeClassifier use, concurrent save serialization, and the full post-save effect order | SettingsChangeCoordinator | App supplies the existing effects as delegates and triggers synchronous Apply from one explicit post-save call | browser proxy sync, reconnect, MCP, hotkey, autostart, telemetry, and surface notification order is preserved; MCP-only behavior and credential precedence are unaffected | SettingsChangeCoordinatorTests.Apply_GatewayUrlChange_PreparesBeforeReconnect | behavioral | - |
| app-settings-change-coordinator-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | OnSettingsSaved impact classification, reconnect switch, and inline effect ordering | SettingsChangeCoordinator | App.SettingsChangeCoordinator.cs wires effect delegates only; OnSettingsSaved forwards to Apply | App does not regain a parallel settings-change orchestration path outside SettingsChangeCoordinator | PresentationSeamContractTests.App_AppliesToolCallVisibilityFromPersistedSettings | source-shape | when App is replaced as the WinUI composition root |
| autostart-settings-applier | authoritative | src/OpenClaw.Tray.WinUI/App.SettingsChangeCoordinator.cs | post-save auto-start preference read and Windows write | AutoStartSettingsApplier | App supplies its shared mutation gate, live preference reader, OS setter, and background fault observer | ordinary settings-save effects read the current preference only after acquiring the toggle and reconciliation gate and hold it until the OS write completes; explicit valid fixture runs skip this background host refresh | AutoStartSettingsApplierTests.ApplyLatestAsync_QueuedSave_ReadsPreferenceAfterGateAcquisition | behavioral | - |
| autostart-settings-direct-write-closed | closed | src/OpenClaw.Tray.WinUI/App.SettingsChangeCoordinator.cs | direct ungated auto-start write from a saved SettingsData snapshot | AutoStartSettingsApplier | effect delegate wiring only; startup reconciliation and explicit toggles retain their existing shared gate | post-save effects cannot replay stale snapshots over newer toggle or reconciliation results | MsixDevelopmentSigningTests.SettingsSaveAutoStart_UsesSharedGateAndLivePreference | source-shape | when the WinUI adapter is exercised directly by behavioral tests |
| app-shutdown-coordinator | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | first-wins shared shutdown task, ordered step execution, and per-step log/catch/continue | AppShutdownCoordinator | App builds the immutable step plan from services it owns, including activation null-before-await and failure-safe captured-resource nulling, and constructs the BeginShutdown/ExitApplication actions | shutdown steps run in the same order exactly once even under concurrent callers; each step logs and continues past failure; Exit is called exactly once after all steps | AppShutdownCoordinatorTests.ShutdownAsync_RunsBeginStepsThenExit_InOrder | behavioral | - |
| app-shutdown-coordinator-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | the _isExiting bool guard, SafeShutdownStep/SafeShutdownStepAsync helpers, and inline ExitApplicationAsync body | AppShutdownCoordinator | App.AppShutdownCoordinator.cs builds the step plan only; ExitApplicationAsync forwards to ShutdownAsync | App does not regain a parallel exactly-once shutdown guard or step-execution loop outside AppShutdownCoordinator | AppRefactorContractTests.Shutdown_Order_PreservesAwaitedTeardownBeforeExit | source-shape | when App is replaced as the WinUI composition root |
| gateway-pending-requests | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs | request-id to method/completion tracking | PendingRequestRegistry | callers create request ids, choose timeout policy, parse and route responses, and use the transport | request ids do not leak after disconnect; the registry remains thread-safe with exactly one terminal completion | PendingRequestRegistryTests.ResponseVersusDrain_ExactlyOneTerminalOutcomeWins | behavioral | - |
| gateway-startup-rejection | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs | structured operator startup rejection and per-socket retry hint | GatewayStartupUnavailable + OpenClawGatewayClient + WebSocketClientBase | native setup retains its caller deadline and provenance checks | only correlated UNAVAILABLE/retryable/startup-sidecars consumes a bounded retry hint; auth, pairing, credentials and generation fences remain unchanged | GatewayProtocolLiveRoundTripTests.StartupUnavailable_RetriesFreshAuthorizedSocketsWithoutAuthOrPairingFailure | behavioral | - |
| gateway-handshake-observations | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs | safe operator handshake phase timing for native setup diagnostics | OpenClawGatewayClient.HandshakeObserved + NativeGatewaySetupConnection + NativeGatewaySetupSession + SetupLogger | WebSocketClientBase supplies source transport generations; NativeGatewaySetupHost selects the existing local sink | rejected pre-auth attempts retain transport identity; stale/canceled/disposed work emits nothing; only enums, counters, monotonic durations and bounded startup retry hints are logged, never general Shared logs or wire data; credentials, authorization and deadlines are unchanged | GatewayHandshakeObservationTests.SupersededAuthorization_CannotEmitSuccessOrFailure | behavioral | - |
| connect-envelope | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs + src/OpenClaw.Shared/WindowsNodeClient.cs | connect envelope wire shape, auth field mapping, and v3/v2 signing arguments | ConnectEnvelopeBuilder | callers explicitly select role, scopes, credential profile, and lifecycle/fallback state | the builder cannot infer credential precedence; exact v3/v2 signing bytes and protocol 3/4 remain unchanged | ConnectEnvelopeBuilderTests.Build_CompleteProfileMatrix_PreservesWireShapeAndSigningArguments | golden | - |
| gateway-connect-inline-closed | closed | src/OpenClaw.Shared/OpenClawGatewayClient.cs + src/OpenClaw.Shared/WindowsNodeClient.cs | anonymous connect envelope, auth dictionary, and direct signature/payload construction | ConnectEnvelopeBuilder | explicit role/scope/credential profile selection, lifecycle/fallback state and persistence, redacted logging, transport send | both clients delegate connect construction without moving credential precedence into the builder | GatewayProtocolCoreClosureTests.GatewayClients_DoNotReintroduce_InlineConnectEnvelopeConstruction | source-shape | when both clients are removed or no longer initiate gateway connect handshakes |
| gateway-pending-inline-closed | closed | src/OpenClaw.Shared/OpenClawGatewayClient.cs | pending maps and locks plus Track-Take-Clear and chat-send helper families | PendingRequestRegistry | request-id creation, timeout policy, response parsing/routing, transport | the client delegates registration, take, removal, and disconnect drain so request ids cannot leak and only one completion wins | GatewayProtocolCoreClosureTests.OpenClawGatewayClient_DoesNotReintroduce_InlinePendingRequestTracking | source-shape | when OpenClawGatewayClient is removed or no longer issues correlated requests |
| gateway-protocol-contract | authoritative | ConnectEnvelopeBuilder + src/OpenClaw.Shared/OpenClawGatewayClient.cs + src/OpenClaw.Shared/WindowsNodeClient.cs | duplicated wire-version range, ad hoc successful hello acceptance, and raw mismatch interpretation | GatewayProtocolContract + GatewayProtocolCompatibility | the builder retains exact envelope construction; clients retain credential precedence, signature fallback, generation fencing, and role-specific success side effects | Windows advertises Gateway protocols 3 through 4 and validates the minimal hello-ok shape before success side effects; after the Gateway accepts that range, an integer hello-ok protocol at or above 3 is accepted because it reports the Gateway current constant rather than a negotiated selection; structured mismatch details remain finite and sanitized relative to the advertised range | GatewayProtocolContractTests.SupportedRange_IsThreeThroughFour | behavioral | - |
| interactive-client-identity | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | operator wire identity chosen by individual callers | GatewayClientFactory.ClientIdentity + ConnectEnvelopeBuilder (OperatorClientIdentity) | only the tray composition root opts in to gateway-client/ui; the signed payload and serialized client use the same identity |
CLI, setup, and validator clients stay cli/cli; role, scopes, credentials, and node connections are unchanged |
ConnectEnvelopeBuilderTests.OperatorIdentity_SignedAndSerializedIdentityMatch_WithoutChangingOtherFields | behavioral | - |
| presence-disconnect-classification | authoritative | src/OpenClaw.Shared/InstanceMerger.cs | treating a fresh disconnect beacon as active or letting operator presence claim a node that shares its device identity | InstanceMerger | live beacons claim nodes before disconnect beacons; mode=node presence claims shared device identities before operator presence; the node list stays authoritative for a connected node | disconnect beacons are offline unless their node is still online, and shared identities attach management actions to the node presence row | InstanceMergerTests.NodePresence_PrefersSharedDeviceIdOverEarlierOperatorPresence | behavioral | - |
| gateway-protocol-literals-closed | closed | ConnectEnvelopeBuilder | private minProtocol and maxProtocol numeric literals | GatewayProtocolContract | the builder serializes its existing envelopes using the shared constants | operator and node connect envelopes advertise the same 3-through-4 protocol range | GatewayProtocolContractTests.Clients_use_shared_contract_for_protocol_range | source-shape | when connect envelopes no longer carry a Gateway protocol range |
| ui-dispatcher | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | UI-thread marshaling abstraction for presentation code | IUiDispatcher | App and existing WinUI code may call DispatcherQueue directly until the view-model migration | presentation view models depend on IUiDispatcher not a concrete DispatcherQueue | UiDispatcherContractTests.PageViewModel_ReceivesRegisteredDispatcher | behavioral | - |
| navigation-scope | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs | page view-model activation/deactivation and disposal lifetime | NavigationScopeManager | SettingsShellView keeps frame navigation and rail selection; WorkspaceWindow resets the scope on leaving Settings and on close | transient page view models are activated on navigation and deactivated then disposed on navigate-away | NavigationScopeManagerTests.NavigatingAway_DeactivatesAndDisposesPreviousViewModel | behavioral | - |
| composition-root | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | presentation-layer service construction and wiring | AppServiceRegistration | App remains the composition root and owns non-DI service lifetimes | one validated root ServiceProvider; App-owned singletons registered as instances are never disposed by the container | AppServiceRegistrationTests.Dispose_DoesNotDisposeAppOwnedInstanceSingletons | behavioral | - |
| node-summary-text | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | node-summary clipboard text formatting | NodeSummaryText | App keeps the clipboard side effect (building the DataPackage and setting clipboard content) | copied node-summary text is projected only by NodeSummaryText.Build (online/offline state, display-name fallback, short id, detail text, newline join) | NodeSummaryTextTests.Build_MultipleNodes_OneLinePerNodeJoinedByNewline | behavioral | - |
| reactor-chat-timeline | authoritative | removed legacy FunctionalUI chat timeline | production chat message virtualization, row realization, and imperative scroll follow | ReactorChatTimeline through OpenClawReactorChatRoot and ReactorHostControl | - | Workspace's ChatPage mounts one direct ReactorHostControl; Reactor owns stable-key ItemsView and ItemContainer realization without a custom native list, collection reconciler, or scroll-layout mutation | ChatTimelinePresentationTests.ReactorTimeline_UsesNonSelectableItemsViewContainersAndAnnotatedScrollBar | source-shape | when ReactorChatTimeline is replaced as the production virtualization owner |
| chat-tail-reflow-budget | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | bounded correction eligibility after viewport reflow or streaming extent growth | TailReflowCorrection, with exact landing geometry from TailNavigationPolicy.IsAtBottom | InitialTailPositioner owns native layout/render/input subscriptions and discrete tail requests; ReactorChatTimeline supplies the immutable Entries revision | one correction per viewport change or growing content revision, only while following away from the tail and never while initial positioning is pending; absolute bottom error rejects overshoot without changing follow intent; cancellation rejects late extent changes and same-revision rerenders; native remeasurement cannot replenish the growth budget; a correction that lands short of a moved tail re-corrects at most twice per content revision, and transient views before it completes do not end follow; no continuous extent chasing | ChatTimelinePresentationTests.TailReflowCorrection_OvershootUsesOnlyTheArmedCorrectionWithoutBypassingReaderOrInitialGates | behavioral | - |
| chat-tail-content-anchor | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | native scrollbar-end landing after virtualized rows remeasure | InitialTailPositioner.TailAnchorRatio | initial/jump correction and keyboard-reader handoff retain their existing owners | default and restored anchoring use the nearest interior point below 1, keeping content bottom alignment without WinUI's extent-edge mode; no new scroll requests, retry budget or ViewChanged anchoring loop; streaming still reaches the exact bottom and reader position is preserved | GatewayFixtureUiTests.SidebarSwitchesRealHistoriesAndShowsMessage240AtBothWidths | behavioral | - |
| chat-tail-reflow-follow-admission | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | stale reflow correction after a reader scrolls away | TailNavigationPolicy.CanDispatch, applied in InitialTailPositioner.DispatchTailRequest | initial history positioning retains its layout gate; pointer, keyboard, controller and keyboard-focus cancellation recompute follow from the current position; programmatic realization focus does not cancel navigation | reflow correction rechecks follow, generation, tail identity and current scroll view before an offset-only ScrollTo against the current extent, without synchronous item realization; initial positioning remains index-based and is never follow-gated | ChatTimelinePresentationTests.ReactorTimeline_ReflowDispatchRechecksFollowEligibility | source-shape | when native reflow tests reliably detect synchronous item-realization hangs |
| chat-reader-anchor-handoff | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | far-edge anchoring retaining a keyboard reader's pending native bring | InitialTailPositioner.OnBringingIntoView | native input and virtualization still own movement; initial positioning and explicit/follow/reflow tail requests retain their existing owners; the two-width ConversationFeedback proof retains exact top, reader position, jump, streaming and draft assertions | an uncancelled bring for the currently keyboard-focused control outside the follow range relinquishes following and switches to top anchoring before native movement; no-motion, programmatic and initial-tail brings do not yield. Only the matching reader completion may restore following when it lands near the tail; new tail navigation, replacement and disposal clear the reader correlation. No extra scroll, realization or layout call | ChatTimelinePresentationTests.ReactorTimeline_KeyboardReaderBringYieldsEdgeAnchorWithoutAddingNavigation | source-shape | retire source guard when mounted tests directly cover cancellation and every native bring route |
| chat-tail-live-dispatch | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | stale initial, reflow, or explicit-jump tail coordinates across dispatcher handoff | InitialTailNavigationRequest, applied in InitialTailPositioner.DispatchTailRequest | native layout, render, follow and input gates remain in InitialTailPositioner | requests retain the originating generation and resolve live tail coordinates inside dispatch; initial and explicit-jump navigation realize through ItemsRepeater, wait for stable rendered geometry, and revalidate the row before a direct element bring; resize correction remains offset-only | ChatTimelinePresentationTests.ReactorTimeline_InitialTailResolvesLiveCoordinatesAfterLayoutAndDispatch | source-shape | when InitialTailPositioner no longer owns queued native tail navigation |
| chat-synchronous-item-bring-closed | closed | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | synchronous ItemsView realization/layout followed by the recycled-container ancestor loop | InitialTailPositioner stages supported repeater realization and direct element bring | Reactor remains the collection, layout and virtualization owner | no ItemsView.StartBringItemIntoView or forced layout; bounded natural-layout observation, item identity and generation fencing, and reader cancellation | ChatTimelinePresentationTests.ReactorTimeline_NeverUsesSynchronousItemsViewBring | source-shape | when the supported runtime includes upstream microsoft-ui-xaml#12320 and unchanged native navigation proofs establish safe replacement |
| chat-initial-tail-retry-dispatch | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | reentrant native bring during an initial landing render callback | InitialTailPositioner and InitialTailConfirmation | confirmation keeps its bounded retry policy; input, unload, disposal, and replacement invalidate queued retries | a rendering callback only schedules a retry; the dispatcher resolves the current tail after generation checks and starts the native bring outside rendering | ChatTimelinePresentationTests.ReactorTimeline_DoesNotStartATailRetryDuringRendering | source-shape | when a native behavioral test reliably detects rendering reentrancy |
| chat-initial-tail-completion | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | initial-tail retry admission while a native bring is in flight | InitialTailConfirmation and InitialTailPositioner | native scroll events are matched to the current tail item and scroll view; normal follow cannot interrupt initial positioning | correlated completion and stable layout precede retry; absent events and failed landings remain bounded | ChatTimelinePresentationTests.InitialTailConfirmation_DoesNotInterruptAnIdleButInFlightBring | behavioral | - |
| chat-initial-tail-recovery | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | indexed history bring completes without landing | InitialTailConfirmation selects correction; InitialTailPositioner resolves the live ScrollView extent inside the guarded retry dispatcher | ordinary initial/follow requests remain row-targeted; viewport reflow retains its separate bounded correction; user input, replaced targets and generations cannot inherit an old correction | only a settled completed attempt for the same target may use this ScrollTo; an interior native anchor pins the revalidated current tail row without realizing it; completion, cancellation and detachment remove the callback and restore normal anchoring; correlation and landing stay within the existing three-retry/120-frame budget, never from ViewChanged or continuous extent chasing | ChatTimelinePresentationTests.InitialTailConfirmation_OffsetCorrectionDoesNotExtendTheRetryBudget | behavioral | - |
| chat-initial-tail-rearm | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | initial positioning after rows or the native scroll view temporarily disappear | InitialTailPositioner | input cancellation still clears pending initial navigation | cleared rows invalidate old work and rearm when rows return; a replaced scroll view returns to the layout gate | ChatTimelinePresentationTests.ReactorTimeline_ClearingRowsDuringInitialPositioningRearmsWhenRowsReturn | source-shape | when mounted lifecycle tests reliably cover both rearm paths |
| chat-initial-tail-verification | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorItemsViewScrollController.cs | a confirmed initial landing left behind when a later projection of the same request grows the tail and the unverified follow or reflow path does not reach it | InitialTailVerification decides; InitialTailPositioner observes the settled view and re-issues its existing staged tail bring | initial confirmation, follow and reflow admission keep their existing owners; the window only adds re-issues after their work has settled | one bounded window per confirmed landing (120 frames) with a fixed budget of two re-issues that self-induced layout or extent changes never replenish; a re-issue needs tail growth after the landing, and arrival at the tail spends that growth and revokes any queued or realizing re-issue, so a following reader position near the tail is left alone; it waits for an idle view, unchanged geometry and no owned layout, render, confirmation, realization, queued follow or undelivered bring, and rechecks that admission at dispatch, so it never chases a moving extent; reader input, history navigation, loss of following, row clearing, a new request, scroll-view replacement, unload and disposal end the window at once and revoke its queued dispatch and its own unfinished realization; it never resumes; exhaustion logs a warning and leaves Jump to latest visible; reader positions are never captured or restored | ChatTimelinePresentationTests.InitialTailVerification_BudgetIsFixedAndSelfInducedChangesNeverReplenishIt | behavioral | - |
| chat-tool-activity-renderer | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | production standalone tool-call and grouped activity presentation, summaries, disclosures, and detail rendering | ChatToolActivityPresentation + ToolCallCardRenderer | ReactorChatTimeline projects rows and delegates realization only | consecutive invocation grouping preserves source chronology; completed dashboard work uses supplied phase/source facts and terminal-answer keys without rewriting stored entries; confirmed handoffs prevent rollup; durations require an exact session/terminal-run match; selectable output remains capped at 240px | ChatToolActivityPresentationTests.Dashboard_CompletedWorkUsesLastUnphasedReplyWithoutChangingStoredEntries | behavioral | - |
| chat-running-text-lifetime | authoritative | ChatVisuals native Unloaded-only shimmer cleanup | running-label animation ownership across Reactor unmount and control reuse | ChatVisuals.WithTextShimmer + ToolCallCardRenderer | tool and thinking renderers supply active state; run-progress token and clock text remain static beside the animated claw | unmount cleanup stops the sweep and restores foreground before native text reuse; the renderer also cleans the Expander header slot omitted by Reactor preview.16 traversal; animation cannot leak into finished labels or message footers; the complete running label remains painted in Light and Dark | ReactorToolActivityProofTests.RunningTool_UnmountStopsShimmerBeforeItsTextControlCanBeReused | behavioral | - |
| chat-composition-motion-lifetime | authoritative | per-renderer ad hoc entrances and implicit transitions | one-shot chat entrances, disclosure turns, disclosure height reveal and close shrink (details below a header-only Expander), label cross-fades, reader-initiated transcript row reflow (FLIP), side panel and tab reveals, the jump-to-latest reveal and the welcome composer slide, and their cleanup across Reactor unmount and control reuse | ChatMotion, ChatTranscriptReflow | renderers decide when motion is admitted (new rows appended at the tail via ChatToolActivityMotionState, reader show or hide tools and collapse-all for reflow, user-opened and user-closed details, new questions); ReactorRunProgress keeps its own status swap and entrance; Reactor Transition keeps owning fades it already declares | motion is render-only and never moves layout, scroll or focus; message arrival animates only newly admitted rows, not the existing transcript; reader input and disabling Windows animations stop an active reflow; motion runs on ChatMotionHost, a type Reactor never pools, through XAML Translation, Opacity and Rotation with implicit transitions; pooled layout controls and buttons never carry app-set transitions or GetElementVisual calls; only elements whose visual a Reactor Transition already owns (and keeps unpooled) get a composition rise; removed list children carry no mount or unmount actions; unmount stops in-flight motion | ReactorToolActivityProofTests.ChatMotion_UnmountRestoresNeutralStateBeforeAControlCanBeReused | behavioral | - |
| chat-tool-input-syntax | authoritative | ToolCallCardRenderer's plain input runs | inert syntax coloring of sanitized PowerShell and JSON display input | ChatToolInputSyntax | ToolCallCardRenderer owns section order, divider, output tone and disclosure; NativeToolProjector retains redaction and display bounds | syntax parsing never executes input or changes selectable text; unknown languages remain literal; native theme-bound runs adapt to Light, Dark and high contrast; output reuses no input colors; parser regex matches have a bounded deadline | ChatToolInputSyntaxTests.ToolCard_ColorsPowerShellInputButKeepsOutputLiteralWithPrimaryBlend | behavioral | - |
| chat-conversation-details-slot | authoritative | native conversation side panel | slot reuse, scoped tool identity, close, split layout and focus | ChatConversationPanelState + ChatToolDetailRequest + ReactorConversationPanelHost | OpenClawReactorChatRoot binds current snapshot/source and composes; ToolCallCardRenderer remains the sole detail renderer and reuses ChatToolOutputOperation for explicit saved-result recovery | opening a different tool reuses Details; no payload cache or new RPC; navigation/replay/source retirement rejects captured opens; the composer remains mounted and ChatComposerSession intersects conversation, host and composer visibility before allowing capture | ChatConversationPanelStateTests.OpenAnotherTool_ReusesTheDetailsSlotAndReplacesOnlyItsIdentity | behavioral | - |
| chat-conversation-files-slot | authoritative | native conversation side panel Files tab and pill | session file list reads, file count and stale-result rejection | ChatSessionFilesState + ReactorChatFiles + ReactorChatFilesPill | OpenClawReactorChatRoot binds session, connection, timeline generation, history revision and run state, and passes the pill its bound admission revision; ChatConversationPanelState admits the tab with the Subagents connection check and retires it, like Subagents, on connection, reset or history replacement (the Dashboard tab follows the session instead); WorkspaceFilesModel remains the sessions.files projection and OpenClawGatewayClient.ListSessionFilesAsync the reader, reached through GatewayClientChatBridge | read-only existing sessions.files.list only, and only when the Gateway advertises it; one read per selected session, connection, reset generation and history revision, after a run ends and on refresh, with one trailing read when triggered mid-read; replaced-source results are discarded; only files the session edited or read are listed and counted, never untouched entries from the response's workspace-root listing; an unsupported answer is not re-read on the same connection except by refresh, including reads queued during that answer; state changes advance a version the root passes to the pill and tab, so a read that completes during the root's render still redraws them; unsupported or failed reads never invent files, and a failure keeps the same session's last list | ChatConversationPanelStateTests.SessionFiles_CountsOnlySessionFilesNotTheWorkspaceRootListing | behavioral | - |
| chat-tool-file-preview | authoritative | chat tool-row file targets and read-only file preview | safe target resolution, bounded file reads and preview lifetime | ChatToolRowLinks + ChatConversationPanelState + ReactorChatWorkspaceFile + OpenClawChatDataProvider | the root wires existing authenticated Gateway reads; the Files list keeps its separate owner and refresh policy | only workspace-relative non-escaping paths; no multi-file or moved patch target; one cancellable connection-fenced read per explicit open or retry; secrets redacted before display; preview survives history replacement but retires on connection/session replacement | ChatConversationPanelStateTests.FilesListAndFilePreviewKeepDistinctHistoryAndConnectionLifetimes | behavioral | - |
| chat-details-profile-revalidation | authoritative | native Details availability | distinguishing same-profile edits from account replacement | ChatToolDetailsProfile using the existing users.self parser and connection-bound request | GatewayClientChatBridge distinguishes explicit profile invalidation from connection/bootstrap refresh and forwards disposal; no profile display or avatar ownership moves here | initial identity and each revalidation are epoch/device fenced; same ID restores availability, changed ID or explicit profile invalidation before a verified baseline retires until reconnect; ordinary bootstrap retries can establish identity, stale completions cannot reopen content, failures report a bounded category | ChatToolDetailsProfileTests.ProfileInvalidationBeforeFirstReadCompletes_RetiresUntilReconnect | behavioral | - |
| chat-details-profile-admission | authoritative | native Details open callbacks | profile-revision retirement before and after the next render | OpenClawReactorChatRoot live snapshot check + ChatConversationPanelState admission revision | verified same-account refresh may retain the tab, never an old open callback | the root compares the captured opaque profile snapshot to the live provider and binds its revision; availability alone cannot re-admit old callbacks after refresh | ChatConversationPanelStateTests.RootAdmission_UsesLiveProfileSnapshotAsWellAsBindingRevision | source-shape | when mounted real-provider proof covers a delayed open across profile revalidation |
| chat-details-pointer-routing | authoritative | native Details divider | pointer class-handling admission and teardown | ReactorConversationPanelHost.PanelResize | native Button and its existing keyboard focus remain | pointer press/move/end handlers observe handled events with matching removal, so ButtonBase cannot swallow drag admission | ChatConversationPanelStateTests.PointerDivider_ObservesButtonHandledEventsAndRemovesItsHandlers | source-shape | when mounted pointer-input proof covers native Button class handling and detach |
| chat-conversation-dashboard-slot | authoritative | native conversation side panel | session dashboard tab beside chat: automatic reveal, dismissal, explicit Dashboards-page handoff | ChatConversationPanelState dashboard slot + ChatDashboardBinding (connection, board probe, pending open) | ReactorBoardView (Embedded) remains the sole board renderer; DashboardsPage only queues App.PendingChatDashboardSessionKey beside the existing pending chat key | the tab follows the session, not history; automatic reveals are passive (no selection change, focus move or narrow takeover) and stop after the user closes the tab; explicit opens select it and show a minimized panel; automatic reveals leave a minimized panel minimized | ChatConversationPanelStateTests.AutomaticReveal_IsPassiveAndNeverReplacesTheCurrentSelection | behavioral | - |
| chat-history-replay-projection | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | array-valued history content ordering projection | ChatHistoryReplayProjection | provider applies projected text and tool parts to the reducer | interleaved text, calls, and results replay in source order without clearing active tool correlation | OpenClawChatDataProviderTests.LoadHistoryAsync_InterleavedContentParts_PreserveChronologyAndCorrelation | behavioral | - |
| assistant-media-protocol-projection | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs | structured assistant media content parsing and assistant-only legacy MEDIA directive redaction/projection | AssistantMediaDirectiveParser + ChatMediaContentInfo | gateway client preserves ordered typed media while tray presentation receives only safe filenames and metadata | user text never activates media directives; accepted local sources never enter visible assistant text or notifications; media-only messages survive live and history parsing | AssistantMediaDirectiveParserTests.Project_AssistantAbsolutePath_ProducesMediaWithoutExposingPath | behavioral | - |
| assistant-media-resolver | authoritative | src/OpenClaw.Shared/OpenClawGatewayClient.cs | authenticated structured artifact and legacy assistant-media byte retrieval | OpenClawGatewayClient.AssistantMedia | chat bridge exposes only lease-bound typed resolution results; renderer never receives credentials, tickets, or arbitrary URLs | accepts only current-connection results, matching media MIME families, managed ticket paths, and payloads within the 12 MiB image or 16 MiB playback caps | OpenClawGatewayClientAssistantMediaTests.ResolveLegacyMedia_UsesBearerMetadataAndSourceBoundTicket | behavioral | - |
| assistant-file-download | authoritative | src/OpenClaw.Tray.WinUI/Chat/ChatAssistantMediaRenderer.cs | resolving a structured file attachment's ticketed Gateway download URL and launching the default browser | GatewayClientChatBridge.DownloadAssistantFileAsync through AssistantFileDownloadLauncher | renderer, timeline context, and provider pass only the typed AssistantFileDownloadStatus | the ticketed URL is resolved by the internal OpenClawGatewayClient.ResolveAssistantFileDownloadUriAsync and launched inside the bridge; it never reaches presentation code | AssistantFileDownloadLauncherTests.FileDownloadPresentationPath_NeverReceivesTicketedUris | source-shape | when browser-launched file downloads leave the chat bridge |
| provider-assistant-media-parsing-closed | closed | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | parsing legacy MEDIA directives or structured Gateway media blocks | AssistantMediaDirectiveParser + OpenClawGatewayClient | provider owns message identity, streaming reconciliation, timeline application, and safe presentation metadata orchestration | provider consumes typed content parts and never reparses model text or exposes raw media sources | ChatAssistantContentPresentationTests.Project_UsesSafeFilenameWithoutExposingLegacySource | behavioral | when assistant message ingestion leaves OpenClawChatDataProvider |
| assistant-media-renderer | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | assistant media card presentation, bounded image decode, retry, and row cancellation | ChatAssistantMediaRenderer | ReactorChatTimeline owns row placement and delegates media realization | at most four images render inline per message; unsupported or unresolved typed media remains visible as an accessible safe unavailable card; raw Gateway sources are never rendered | ChatAssistantContentPresentationTests.BuildRenderPlan_CapsImagesWithoutReorderingOtherMedia | behavioral | - |
| gateway-media-message-projection | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | gateway media-envelope parsing, safe filename/MIME normalization, attachment signatures, and provenance-safe attachment descriptors | GatewayMediaMessageProjection + ChatAttachmentPresentation | provider applies the projection to live, reset, backfill, and history ingress and owns stateful echo correlation | gateway text never becomes a private marker; gateway descriptors have no preview key; only local opaque preview keys can access image bytes | GatewayMediaMessageProjectionTests.ValidEnvelope_ProjectsSafeDescriptorAndCleanProse | behavioral | - |
| provider-gateway-media-parsing-closed | closed | src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs | private gateway media-envelope parsing or descriptor construction | GatewayMediaMessageProjection | provider retains stateful pending-echo queues, reset gates, sidecar matching, and reducer application | all user ingress paths call the focused projection and do not independently parse gateway media text | review-only | review-only | when user-message ingestion leaves OpenClawChatDataProvider |
| reactor-tool-rendering-closed | closed | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | per-tool and grouped activity summary/detail rendering implementation | ToolCallCardRenderer | row projection, virtualization, hover state, assistant runs, and renderer delegation only | ReactorChatTimeline contains no tool detail renderer and delegates both standalone and grouped tool rows | ChatTimelinePresentationTests.ReactorTimeline_DelegatesToolAndActivityRenderingToFocusedOwner | source-shape | when ReactorChatTimeline is replaced as the production virtualization owner |
| functional-chat-default-mount | closed | src/OpenClaw.Tray.WinUI/Chat/ReactorChatHostExtensions.cs | mounting the FunctionalUI chat tree as the default chat surface (the former ChatWindow popup is retired) | ReactorChatHostExtensions and OpenClawReactorChatRoot | - | Workspace's ChatPage mounts the Reactor root directly into its ChatHost Border through ReactorChatHostExtensions | ChatToolCallsToggleContractTests.WorkspaceChatPage_MountsReactorRoot | source-shape | when ReactorChatHostExtensions is replaced as the authoritative production chat mount owner |
| settings-store | authoritative | settings and permission UI surfaces | direct SettingsManager mutation and blanket self-write suppression | ISettingsStore | non-permission legacy surfaces may read SettingsManager until migrated; direct saves publish origin null | every save publishes one versioned event; only the matching writer ignores its own origin while all other active consumers refresh | SettingsSharedStateContractTests.TwoActiveSettingsPageViewModels_IgnoreOnlyOwnWrites_InBothDirections | behavioral | when every settings surface reads and writes through ISettingsStore |
| settings-page-vm | authoritative | src/OpenClaw.Tray.WinUI/Pages/SettingsPage.xaml.cs | General load, persist, echo-guard, and auto-save wiring, including notification preferences | SettingsPageViewModel | General keeps notification controls, managed-Gateway setup/removal and saved-indicator rendering; AboutPage owns app/Gateway info, update, and migration UI | each settings control persists its field through the store preserving mutate-save-notify order and does not re-persist on external change | SettingsPageViewModelTests.ExternalChange_ReloadsWithoutRePersisting | behavioral | when General holds no settings persistence logic in code-behind |
| exec-approvals-store | authoritative | src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs | direct exec-approvals.json snapshot, CAS persistence, file observation, and mutable policy cache | ExecApprovalsStore through IExecApprovalsPresentationStore | SystemCapability and NodeService consume the same App-owned concrete store for runtime enforcement | pure reads create nothing; CAS rejects stale hashes; one store-owned observer publishes each distinct external replacement once and retains the last valid presentation snapshot on typed failure | ExecApprovalsStoreTests.Changed_ExternalCorruptThenValid_RaisesFailureThenRecovery | behavioral | - |
| permissions-page-vm | authoritative | src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs | permission settings state, exec-approvals mutations, node/MCP/voice status decisions, and lifecycle subscriptions | PermissionsPageViewModel plus PermissionsPageRuntimeSource | code-behind keeps exact WinUI row/card construction, localization application, colors, visibility, clipboard/token reads, privacy launch, and save-hint timer | activation is pure; field-scoped settings writes preserve save-then-notify; V2 mutations preserve unrelated fields through CAS retry; deactivate/dispose releases subscriptions | PermissionsPageViewModelTests.ExternalValidChange_UpdatesOnce_AndCorruptRetainsLastValidDisplay | behavioral | - |
| permissions-page-direct-owners-closed | closed | src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs | direct SettingsManager, ConnectionManager, and ExecApprovalsStore ownership or subscriptions | PermissionsPageViewModel plus authoritative stores | WinUI-only rendering and platform actions listed in permissions-page-vm | the page applies semantic state only; the view model is WinUI/App/SettingsManager/file-IO free and never creates a parallel mutable domain cache | PermissionsPageContractTests.PermissionsPageViewModel_StaysWinUiAndAppFree | source-shape | when PermissionsPage is replaced by a different view technology |
| shared-mutable-domain-owner | authoritative | presentation pages and view models | backing-file or concrete-manager ownership, per-VM observers, and independent mutable copies of persisted domains | one observable service/store per shared mutable domain | immutable view state projected from authoritative snapshots | different active consumers converge through versioned origin-aware events or CAS snapshots without echo storms, stale whole-snapshot replay, or lost unrelated updates | SettingsSharedStateContractTests.PermissionsPageViewModel_ReceivesOneExternalUpdate_PerDistinctAppSurfaceOrigin | behavioral | - |
| exec-reusable-binding | authoritative | src/OpenClaw.Shared/ExecApprovals/ExecCommandResolution.cs | deriving durable allowlist identities and Allow Always patterns from multi-segment shell resolution | ExecReusableCommandBinder | ExecCommandResolver.Resolve stays the singular resolution used by the state machine and prompt display | at most one identity may be durably authorized per request and it is a fully qualified existing .exe image whose arguments are pinned by the generated rule |
ExecReusableCommandBinderTests.MultiElementCarrierTail_Binds | behavioral | - |
| exec-multi-segment-allowlist-closed | closed | src/OpenClaw.Shared/ExecApprovals/ExecCommandResolution.cs | ResolveForAllowlist and ResolveAllowAlwaysPatterns feeding allowlist matching or Allow Always patterns | ExecReusableCommandBinder | the two methods remain compiled with their historical tests until removed but have no production callers | the approval pipeline derives AllowlistResolutions and AllowAlwaysPatterns only from ExecReusableCommandBinder.TryBind | ExecApprovalV2NormalizationPipelineOwnershipTests.Normalizer_DerivesDurableIdentity_OnlyFromReusableBinder | source-shape | when ResolveForAllowlist and ResolveAllowAlwaysPatterns are deleted |
| canonical-cmd-carrier | authoritative | src/OpenClaw.Shared/Mxc/MxcRequestBuilder.cs | recognizing the cmd.exe /d /s /c carrier and extracting its command payload | CanonicalCmdCarrier | MxcRequestBuilder keeps cmd command-mode switch detection and Win32 command-line rendering | the approvals binder and typed SDK builder agree on canonical carrier recognition and preserve its approved payload; no in-band environment bootstrap remains | CanonicalCmdCarrierTests.BinderAndMxcBuilder_AgreeOnCarrierRecognition | behavioral | - |
| exec-carrier-transport-identity | authoritative | src/OpenClaw.Shared/ExecApprovals/ExecApprovalsCoordinator.cs | deciding what a trusted canonical cmd carrier executes once its inner payload is durably authorized | ExecReusableCommandBinder builds the execution argv; CanonicalCmdCarrier.PinnedCarrierMatchesRequest enforces it | the coordinator owns prompt, policy and persistence; SDK/Windows owns the default child environment without shell rewriting | a carrier keeps its approved shell transport with exactly two pinned tokens: the trusted system cmd image and the resolved payload image. Every other token and interior spacing remains ordinal-identical. Adoption of SDK environment support does not silently rewrite a shell request into an unrelated execution | ExecReusableCommandBinderTests.TrustedCarrier_KeepsTransportSeparateFromIdentity | behavioral | - |
| cmd-payload-tokenization | authoritative | src/OpenClaw.Shared/ExecApprovals/ExecReusableCommandBinder.cs | parsing a cmd payload into tokens and rewriting its executable token | CmdPayloadTokenizer | ExecReusableCommandBinder.TryTokenizeStaticCmdPayload remains as a delegating wrapper for existing callers and tests | a payload rewrite is built from parsed token spans and is accepted only after re-parsing proves the argument list is unchanged except for the pinned executable | ExecReusableCommandBinderTests.PinnedCarrier_DoesNotRewriteArgumentsThatRepeatTheExecutableText | behavioral | - |
| exec-carrier-cwd-ambiguity-check | closed | src/OpenClaw.Shared/ExecApprovals/ExecReusableCommandBinder.cs | deciding whether a carrier payload may be durably approved when the working directory could shadow it | CanonicalCmdCarrier.TryBuildPinnedCarrier (payload executable pinning) | - | the approval-time working-directory check is deleted, not merely bypassed: ExecCommandResolver exposes no HasCurrentDirectoryCandidate, a trusted carrier's payload executable is pinned to its resolved absolute path so cmd has nothing to search for, and a post-approval shadow cannot win | ExecReusableCommandBinderTests.PinnedCarrier_IgnoresShadowInsertedAfterApproval | behavioral | - |
| exec-legacy-host-quarantine | authoritative | src/OpenClaw.Shared/ExecApprovals/ExecCommandToken.cs | deciding whether a provenance-less path-only allowlist entry authorizes an interpreter or code host | ExecAllowlistMatcher.MatchInternal via ExecCommandToken.IsLegacyQuarantinedHost | argument binding remains the security boundary for every rule this node generates | an allowlist entry with no source and no argPattern is inert when its resolved target is a command host the previous model refused, is never deleted or migrated, and is superseded only by an explicit allow-always sibling carrying source and argPattern | ExecAllowlistArgBindingTests.LegacyPathOnlyEntryForACommandHost_IsInert | behavioral | - |
| app-ssh-restart-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs and ConnectionPage.xaml.cs | stopping, starting, reconnecting, and declaring success for a user-requested SSH tunnel restart | GatewayConnectionManager.RestartSshTunnelAsync | App and ConnectionPage invoke the manager and present the result | a restart succeeds only after a fresh generation-bound hello-ok and current registry, config, tunnel generation, and owned listener verification | AppRefactorContractTests.UserSshRestart_StaysDelegatedToConnectionManager | source-shape | when App no longer owns any SSH tunnel UI actions |
| hub-page-registry | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs and GatewayNavVisibilityDebouncePolicy | navigation aliases, page mapping, legacy command metadata and gateway-page classification | HubPageRegistry | SettingsShellView keeps native Frame/NavigationView application; HubSearch ranks new navigation-only search items; WorkspaceNavigationHistory keeps the single back-stack; GatewayNavVisibilityDebouncePolicy keeps disconnect timing | direct, legacy and agent-scoped routes, legacy command metadata and gateway prune set remain stable; new search caps and ranking are tested at HubSearch | HubPageRegistryTests.BuildCommands_PreservesBaseOrderActionsIconsAndResourceKeys | behavioral | - |
| unified-search-input-closed | closed | WorkspaceWindow.xaml.cs and SettingsShellView.xaml.cs | duplicated input filtering, suggestion handlers and search result dispatch | SearchHost + HubSearchController + HubSearch | shells keep icons, anchors, modal/load deferral and native navigation application | neither shell regains its own search predicate or suggestion list; opening search does not navigate or mutate settings | PermissionSettingsWriterRoutingTests.MainAndSettingsSearch_ShareCatalogExecutorAndLabel_WithoutChangingTheVisibleSurface | source-shape | when the Workspace/Settings search entry surfaces are replaced |
| hub-page-registry-closed | closed | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs and GatewayNavVisibilityDebouncePolicy | private tag/page switches, command catalogs or search predicates, and gateway-page tag lists | HubPageRegistry + HubSearch | view-only navigation application and debounce timing listed in hub-page-registry | SettingsShellView and the debounce policy do not regain catalog or page-classification copies | HubPresentationContractTests.HubPageRegistry_OwnsMappingsCommandsAndGatewayClassification | source-shape | when SettingsShellView is replaced by a different shell and GatewayNavVisibilityDebouncePolicy is retired |
| settings-navigation-groups | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml | native Settings group layout and visibility application | SettingsShellView | HubPageRegistry retains route and disconnect policy ownership; notification-preferences normalizes to General's settings route | Gateway starts with always-reachable Connection, followed by Systems, Automations, Usage and Config without an Advanced group; its header remains visible offline, and headers alone separate the groups (DiagnosticsPageContractTests.SettingsNavigation_SeparatesSectionsWithHeadersOnly). Agents and Tools contains Agents, Sessions, Models and Local AI. Agents/Sessions retain Gateway availability gates; Models/Local AI remain reachable offline. System contains General, Diagnostics and About; every System SVG entry has a High Contrast glyph fallback | DiagnosticsPageContractTests.SettingsNavigation_ExposesGatewayWorkAsDirectEntries_WithItsExistingVisibilityGate | source-shape | when SettingsShellView no longer owns native NavigationView grouping |
| app-notification-infobar-presentation | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs | banner severity filtering, selected-banner fallback, notification action versus Show more, and action enabled state | AppNotificationInfoBarPresenter | SettingsShellView keeps banner subscription and WinUI control assignment; action clicks use AppNotificationService navigation admission | Warning and Error banners retain priority and hiding semantics while action projection stays WinUI-free | AppNotificationInfoBarPresenterTests.Present_ActionableNotificationWinsOverShowMore | behavioral | - |
| shell-flyout-content | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs | Inbox list reconciliation and gateway/operator/node flyout control application | InboxView + GatewayStatusContent | WorkspacePaneFooter owns each bell flyout's placement and binding; WorkspaceWindow owns account menus, the shared status flyout, badge/status application, and route/reconnect callbacks | Workspace bell preserves chat/history; every footer's account menu reaches the shared status flyout from its Gateway submenu status row, which uses the existing connection projection | WorkspaceWindowProofTests.SidebarSessions_SelectOriginalKeys_AndKeepCompanionDraft | behavioral | - |
| inbox-clock-lifecycle | authoritative | src/OpenClaw.Tray.WinUI/Controls/InboxView.xaml.cs | relative-age refresh lifecycle for the bell and full Inbox page | InboxView + InboxItemViewModel | WorkspacePaneFooter and NotificationsPage retain binding lifetime | active rows refresh in place; unbind and empty tabs stop the clock | DiagnosticsPageContractTests.InboxClock_RefreshesRowsOnlyWhileTheHostIsBound | source-shape | when mounted Inbox clock tests cover ticking, empty tabs and close/reopen through both hosting surfaces |
| shell-flyout-content-closed | closed | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml.cs and WorkspaceWindow.xaml.cs | bell list reconciliation and duplicate gateway flyout row application | InboxView + GatewayStatusContent | banner and sidebar application; popup lifetime and action callbacks | the view and Workspace do not regain flyout lists, row projection, or independent gateway clients | DiagnosticsPageContractTests.ShellFlyoutContent_HasFocusedOwners | source-shape | when both surfaces retire these flyout entry points |
| notification-action-admission | authoritative | src/OpenClaw.Tray.WinUI/Services/AppNotificationService.cs | reminder lifetime after navigation | AppNotificationService.NavigateActionAsync | Shared InboxView (through InboxFeed where present) and banner supply the reminder id; existing navigation owners retain all modal/history ownership | Opening never dismisses a reminder, regardless of native admission, browser success, refusal, exception, modal deferral or replacement; explicit dismissal and source lifecycle remain separate; no approval or abort is performed | AppNotificationServiceTests.NavigateAction_RetainsCurrentAndQueuedRemindersUntilExplicitDismissal | behavioral | - |
| notification-action-dashboard-admission | authoritative | src/OpenClaw.Tray.WinUI/Services/WindowManager.cs | asynchronous result for retired Channels and activity routes | WorkspaceNavigation.DispatchAsync + GatewayDashboardLauncher | App composes the existing credential resolver, browser launcher and failure presentation | Retired routes keep their Dashboard destination and wait for the browser launch result without dismissing reminders on success or failure | AppNotificationServiceTests.NavigateAction_DashboardWaitsForBrowserResultWithoutConsumingReminder | behavioral | - |
| notification-action-native-admission | authoritative | src/OpenClaw.Tray.WinUI/Windows/WorkspaceWindow.xaml.cs | navigation admission across native window and section lifetime | WindowManager.TryShowHubAsync + WorkspaceWindow.TryNavigate | Existing views apply controls; inbox and banner share AppNotificationService.NavigateActionAsync instead of dismissing unconditionally or publishing ambient chat intent | Deferred, redirected, unmounted and closed destinations cannot report synchronous admission; About keeps its own section identity; shared Inbox host forwarding is additionally checked by HubPresentationContractTests.InboxHosts_ForwardAdmissionResultsAndRequestLocalChatKeys | HubPresentationContractTests.NotificationAdmission_PreservesAboutIdentityAndAwaitsDashboardLaunchResult | source-shape | when authorized mounted inbox/banner tests cover setup refusal, modal deferral, closed windows, About and section fallback |
| dashboards-surface | authoritative | src/OpenClaw.Tray.WinUI/Dashboards and src/OpenClaw.Tray.WinUI/Pages/DashboardsPage.xaml.cs | native board reader: dashboard gallery paging, authoritative session invalidation, board loading, board.changed/board.command refresh, ticket renewal, tab selection, widget authorization retries, read-only progress-card refresh, and web Dashboards handoff |
DashboardGalleryModel + BoardDocumentModel over IBoardGatewayClient; DashboardsRoute for the hub tag and the Control UI gallery path; DashboardsPageState for route/agent precedence and handoff actions | DashboardsPage applies hub navigation inputs, connection, and the existing GatewayDashboardLauncher path; Reactor components render immutable snapshots only | the gallery reads every dashboard page for one agent scope and never loads a board before one opens; operator-owned SessionsUpdated and board.changed coalesce gallery reloads with generation and disposal fences, while detached gallery reads publish no session event; an explicit route agent selects that scope, otherwise page selection survives route reopen until the hub agent changes; refresh failures keep rendered rows and boards and reject only widgets still waiting for a ticket; board document events refresh only their own board; tickets renew before expiry; active-tab progress widgets use the separately authorized progressCard.get read keyed by the Gateway's scoped session key, with progressCard.changed as an invalidation hint, sessions.changed reset/delete and denied reads clearing the card, and stale-result fencing; web handoff opens the Control UI gallery, never a guessed exact-board path; no board mutation, grant, or bridge request is sent |
DashboardWidgetCellTests.ProgressWidget_ReadsItsSessionCardAndRefreshesOnInvalidation | behavioral | - |
| dashboards-in-page-return | authoritative | Pages/DashboardsPage.xaml.cs, Controls/SettingsShellView.xaml.cs and Windows/WorkspaceWindow.xaml.cs | returning from an open board to its gallery without creating another navigation stack | DashboardsPageState owns the open board; DashboardsPage applies the gallery return | SettingsShellView exposes the current page action and state-change callback; WorkspaceWindow owns Back buttons and tries this action before WorkspaceNavigationHistory | an open board enables the existing Back action; returning to the gallery preserves the single Workspace history and never restores a Settings Frame back-stack | GatewayFixtureUiTests.DashboardsRenderNativeReportsTabsAndFailureStates | behavioral | - |
| dashboards-settings-entry | closed | Controls/SettingsShellView.xaml | exposing Dashboards in the Settings section list | PinnedPages catalog and WorkspaceDestination standalone page presentation | the retained host still mounts the reader, without Settings chrome; session and command routes preserve board identity | Dashboards is pinnable and default-pinned only for scopes without a saved choice; it never reappears as a Settings navigation item | PinnedPagesTests.Dashboards_IsPinnableButItsSettingsNavigationEntryRemainsClosed | source-shape | when the native Settings-absence and default-pin fixture proof is mandatory in local closeout |
| board-widget-accessibility | authoritative | src/OpenClaw.Tray.WinUI/Dashboards/ReactorBoardWidgets.cs | named whole-widget automation group | ReactorBoardWidgetCell uses the installed Reactor SemanticPanel group peer with the existing localized name, stable identity and card chrome | decorative Border retains rendering only; native report text and links keep their own peers | each card is discoverable with positive full-card bounds without adding a tab stop or Invoke/SelectionItem behavior; child content and actions remain reachable | DashboardWidgetCellTests.NativeReportCard_IsAnAccessibleGroupWithFullBoundsAndReachableChildren | behavioral | - |
| board-widget-hosting | authoritative | src/OpenClaw.Tray.WinUI/Dashboards/BoardWidgetWebHost.cs | isolated hosting of untrusted board HTML widget documents: WebView2 environment and profile, relay page, sandbox proxy handshake, ticketed document fetch, and theme tokens | BoardWidgetWebHost with BoardWidgetRetryPolicy, BoardWidgetHostPage, BoardWidgetUrlPolicy, BoardWidgetDocumentLoader, and BoardWebViewEnvironment (Shared policies are WinUI-free) | the Dashboards Reactor tree owns layout and native chrome; session:website widgets are validated browser links, not hosted pages; gallery cards host no web content; MCP app hosting is deferred |
documents load only from the active Gateway's ticketed board route into the Gateway sandbox proxy on a distinct origin; loopback document transport bypasses inherited process proxies, remote Gateway routing is preserved, and both deny redirects and cookies; only the relay page reaches native code; every offered bridge port is closed; navigation, popups, downloads, and device permissions are denied; repeated-crash and sandbox-unreachable terminal paths close the WebView; crashes never count as sandbox failures | BrowserProxyCapabilityTests.TicketedLoopbackTransport_ProcessProxyRouting_IsIsolated | behavioral | - |
| board-widget-render-deadline | authoritative | src/OpenClaw.Tray.WinUI/Dashboards/BoardWidgetRenderDeadline.cs | acknowledgement lifetime for each delivered HTML document | BoardWidgetRenderDeadline | BoardWidgetWebHost keeps proxy startup, HTTP retries, native timers, WebView transport and localized state application | delivery starts a fresh existing timeout budget; only its render id can acknowledge; cancellation, replacement and expiry fence queued ticks and late acknowledgements; terminal render timeout tears down the WebView | BoardWidgetRenderDeadlineTests.LateDocumentRecoveryWithoutAcknowledgementGetsAFullDeliveryDeadline | behavioral | - |
| board-widget-startup-render-deadline | closed | src/OpenClaw.Tray.WinUI/Dashboards/BoardWidgetWebHost.cs | using proxy startup elapsed time as the document render budget | BoardWidgetRenderDeadline | proxy startup retains its own timer and retry policy | DeliverDocument arms the render owner immediately before posting HTML; teardown cancels its wait | BoardWidgetRenderDeadlineTests.NativeHostArmsAtDeliveryAndInvalidatesWaitsAtTeardown | source-shape | when mandatory native late-fetch and acknowledgement tests cover host-to-deadline wiring |
| workspace-account-menu-accessibility | authoritative | src/OpenClaw.Tray.WinUI/Windows/WorkspaceWindow.xaml.cs and Controls/AccountMenuItem.cs | menu-item metadata presentation and active-Gateway accessibility state | WorkspaceWindow + AccountMenuItem | WorkspaceAccountMenu retains projection and GatewayConnectionManager retains switching | hosts, versions and status labels use Metadata, never the UIA shortcut slot; active Gateway rows expose localized current state without a radio/check column | WorkspaceNavigationTests.AccountMenuMetadata_IsNotExposedAsKeyboardShortcuts | source-shape | retire source guards when mounted account-menu tests cover current/inactive Gateways and every metadata-only row's AcceleratorKey |
| workspace-pane-footer | authoritative | src/OpenClaw.Tray.WinUI/Controls/SettingsShellView.xaml and Windows/WorkspaceWindow.xaml | per-host account, contextual Dashboard, bell and connection-status footer controls | WorkspacePaneFooter + WorkspaceFooterPlacement; HubSearchCatalog owns verified Dashboard counterpart and exact session URL policy | WorkspaceWindow applies identity, status, badge, account menu and contextual Dashboard command to every instance; SettingsShellView only selects Expanded or Rail layout | Chat and Settings end with the same account, contextual Dashboard and bell footer; only verified current page/session routes are used, otherwise Dashboard home opens; Settings has no status pill or footer routes; title-bar actions show only while the Chat pane is hidden | DiagnosticsPageContractTests.WorkspaceAndSettings_ShareOnePaneFooter_AndDiagnosticsLivesInSystem | source-shape | when Chat and Settings no longer use separate NavigationView panes |
| tray-menu-presentation | authoritative | TrayMenuStateBuilder and src/OpenClaw.Tray.WinUI/App.xaml.cs | tray row and flyout presence, ordering, text, formatting, icon identity, action, checked and enabled state, accelerator, accessibility names, and connection-toggle projection | TrayMenuPresenter + ConnectionTogglePresenter | App captures immutable input and owns semantic callbacks, persistence, and reconnect policy; TrayController applies live projection; TrayMenuRenderer builds WinUI controls; TrayMenuWindow owns popup mechanics | equal immutable snapshots project equal complete menus; connected and disconnected compositions, all nine permission toggles, and transient connection states preserve behavior | TrayMenuPresenterTests.Connected_ProjectsExactTopLevelAndNestedOrder | behavioral | - |
| tray-menu-state-builder-closed | closed | TrayMenuStateBuilder and src/OpenClaw.Tray.WinUI/App.xaml.cs | snapshot interpretation, semantic menu construction, and duplicated connection-toggle decisions | TrayMenuPresenter + ConnectionTogglePresenter | mechanical rendering, immutable snapshot capture, action dispatch, persistence callbacks, TrayController weak control references, and TrayMenuWindow native popup behavior | presentation owners stay WinUI/App/concrete-settings free and the renderer and controller do not interpret runtime snapshots | TrayMenuPresentationContractTests.PresentationFiles_AreWinUiAppAndConcreteSettingsFree | source-shape | when the tray menu no longer uses WinUI rendering |
| node-connection-coordinator | authoritative | src/OpenClaw.Connection/GatewayConnectionManager.cs | node generation, cancellation, start guard, connect ordering, classified token recovery, connector events, and node telemetry | NodeConnectionCoordinator | manager public node façade; node-only operator/lifecycle/tunnel preparation; typed lifecycle/state/security ports; one event-forwarding subscription set | a superseded lifecycle or node generation cannot write node snapshot state | NodeConnectionCoordinatorTests.SupersededGeneration_DoesNotWriteSnapshot | behavioral | - |
| native-gateway-runtime | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs and src/OpenClaw.Connection/GatewayConnectionManager.cs | native Gateway package resolution, process launch, job ownership, and listener verification | NativeGatewayRuntime and NativeGatewayEndpointSecurity | App composes one runtime with its registry and installed-package resolver; manager delegates start/retry authorization, explicit disconnect and switch stop, and shutdown disposal | native credentials require runtime-owned endpoint proof for both roles; no WSL or remote exemption; reconnect preserves healthy native runtime and starts a crashed owned runtime | GatewayConnectionManagerTests.NativeGateway_ReconnectRestartsCrashWithoutStoppingHealthyRuntime | behavioral | - |
| gateway-manager-node-owner-closed | closed | src/OpenClaw.Connection/GatewayConnectionManager.cs | private node generation/CTS/start workflow/recovery/telemetry implementation | NodeConnectionCoordinator | public node façade; node-only operator/lifecycle/tunnel preparation; typed lifecycle/state/security ports; one event-forwarding subscription set | the manager has no node generation, node CTS, combined node-attempt predicate, node connect core, or node telemetry names | ConnectionDomainOwnerClosureTests.GatewayConnectionManager_DoesNotReintroduceNodeGenerationOrTelemetryOwnership | source-shape | when GatewayConnectionManager no longer composes NodeConnectionCoordinator directly |
| bootstrap-token-lifecycle | authoritative | src/OpenClaw.Connection/GatewayConnectionManager.cs | bootstrap selection and durable clear timing, device-token persistence handoff, post-bootstrap reconnect, and operator token recovery | BootstrapTokenLifecycle | manager public setup/shared-token façade and save-failure rollback; operator event forwarding; typed lifecycle lease, endpoint-security, reconnect, and v2 persistence ports | bootstrap clears only after canonical operator and node role tokens are both durably readable | BootstrapTokenLifecycleTests.ClearsBootstrap_OnlyWhenBothRoleTokensDurable | behavioral | - |
| gateway-manager-bootstrap-owner-closed | closed | src/OpenClaw.Connection/GatewayConnectionManager.cs | bootstrap timing flags, durable-token clear helper, post-bootstrap scheduling, and operator mismatch recovery | BootstrapTokenLifecycle | public setup/shared-token façade and save-failure rollback; one-shot shared-token validation; operator event forwarding; typed lifecycle/reconnect/v2 ports | stale token events cannot restore timing flags, clear a newer record, or schedule an untyped reconnect callback | ConnectionDomainOwnerClosureTests.GatewayConnectionManager_DoesNotReintroduceBootstrapTimingOwnership | source-shape | when GatewayConnectionManager no longer composes BootstrapTokenLifecycle directly |
| device-pair-approval-coordinator | authoritative | src/OpenClaw.Connection/GatewayConnectionManager.cs | device role-upgrade approval, confirmation, dedupe, and one-in-flight plus one-queued bounded reconnect | DevicePairApprovalCoordinator | manager pairing-event forwarding and generation-bound operator gateway lease source | post-approval node reconnect is bounded to two attempts per request and reacquires the current operator gateway | DevicePairApprovalCoordinatorTests.PostApproveReconnect_IsBounded | behavioral | - |
| gateway-manager-device-pair-owner-closed | closed | src/OpenClaw.Connection/GatewayConnectionManager.cs | device-pair approve RPC, success dedupe, reconnect attempts, and queued retry state | DevicePairApprovalCoordinator | pairing-event forwarding, node snapshot application, and generation-bound operator gateway lease source | manager cannot regain device-pair workflow fields or approve/reconnect methods | ConnectionDomainOwnerClosureTests.GatewayConnectionManager_DoesNotReintroduceDevicePairWorkflowOwnership | source-shape | when GatewayConnectionManager no longer composes DevicePairApprovalCoordinator directly |
| chat-composer-view-model | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs (nested ReactorChatComposer) | draft text/revision, pending attachment identities/presentation, slash UI state, composer busy flags, selector/queue projections, and derived enablement in the root/nested composer Reactor hooks | ChatComposerViewModel | ReactorChatComposer (view) reads projected values and applies immutable ChatComposerInputs from the root in a stable-source post-commit effect; ChatComposerViewModel never subscribes to IChatDataProvider | every observable mutation is dispatched through IUiDispatcher, ChatComposerInputs accepts only increasing revisions and semantically changed projections, rejected inputs do not notify, and no mutation is accepted after Dispose | ChatComposerViewModelTests.ApplyInputs_RejectsOutOfOrderRevision | behavioral | - |
| chat-composer-controller | authoritative | src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs (root SendAsync/OnStop and composer callback closures) | send/stop/reset-confirmation/queue-cancel/model-set-clear/thinking/catalog/attachment-ingress-remove/paste-image/voice workflow and cancellation | ChatComposerController over IChatComposerRuntimePort and ChatComposerHostActions | root session selection (SelectThread) and view event forwarding; provider queue admission remains authoritative, while an accepted Gateway receipt remains accepted even if a reconnect fences its timeline commit | draft revision and attachment reference identities are snapshotted at operation start and cleared only when the accepted result still matches; each unchanged draft payload reuses its Gateway idempotency key within the same known session incarnation, while a changed known incarnation gets a new key; unknown-to-known identity retains the original key but an uncertain request dispatched without a physical session id is never replayed; draft admission verifies the captured session identity atomically; stale-session uncertainty retires only its owned local turn; confirmed late acknowledgments retain echo correlation; definitive rejection clears uncertain draft state; operations are fenced by a generation bumped on Dispose so late completions cannot mutate a disposed/superseded controller | ChatComposerControllerTests.SendAsync_EditDuringDelayedSend_DoesNotClearTheEditedDraft | behavioral | - |
| chat-first-turn-placement | authoritative | new native new-chat location selection | environment/project catalogs, Gateway folder browsing, Gateway-scoped local draft/options/location intent and first-turn preparation | ChatPage retains drafts only for the same Gateway client; ChatComposerController applies confirmed draft options; ChatPlacementController + GatewayChatPlacementClient own location discovery/preparation | Workspace New Chat queues a local draft through ChatPage without a creation RPC; roots project saved draft choices; an unselected local draft may create at the Gateway default on first send when optional location discovery is unavailable; non-default location intent never falls back; agentless Gateway-default compatibility still requires agents.list to be explicitly unsupported; native picker owns selection visuals |
discovery and selection never mutate the Gateway; unsent drafts create no Gateway sessions; first-send option patches require a response on the current connection epoch; location controls remain fenced through send dispatch; losing empty eligibility cancels later requests without implying rollback of admitted mutations; an uncertain session create remains blocked after catalog recovery; retries of an unchanged draft payload reuse its Gateway idempotency key, while changed payloads get a new key; navigation/remounts on the same Gateway retain draft intent, while Gateway changes discard it; failed/stale preparation preserves draft and attachments; forks remain explicit server operations | ChatPlacementControllerTests.LocalDraft_UncertainDefaultCreationStaysBlockedAfterCatalogRecovery | behavioral | - |
| chat-composer-host-lifetime | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatHostExtensions.cs | ad hoc per-render HostCallbacks assignment and no explicit composer session lifetime | IChatComposerFactory + ChatComposerSession, owned/disposed exactly once by MountedReactorChat | Workspace's ChatPage receives one composer session per mounted host over the app-owned provider; the factory is a stateless singleton with no constructor-started work; ChatComposerSession intersects retained-host visibility with the committed composer projection | disposing a MountedReactorChat disposes its ChatComposerSession (controller then view model) exactly once; failed mounts dispose the session before returning an error, and repeated Dispose calls are a no-op; hidden-host capture cannot restart from a later render, and resuming never starts capture automatically | MountedReactorChatDisposalProofTests.FailedMount_DisposesSessionAndLeavesExistingContent | behavioral | - |
| chat-sandbox-status | authoritative | native chat composer | SDK availability and Sandbox settings navigation | SandboxStatusStore publishes existing App/SandboxPage probe results; ISettingsStore supplies the system-tools switch; ChatComposerSession owns both subscriptions; ChatComposerViewModel owns version-fenced projection | ReactorChatComposer renders the icon/flyout; ChatPage supplies the sandbox companion route | opening the flyout never probes or mutates policy; availability is not a per-command receipt; updates preserve drafts and attachments; disposal detaches both listeners | ChatComposerSessionTests.SandboxSettings_RefreshBothSessionsAndStopAfterDisposal | behavioral | - |
| reactor-chat-root-composer-closed | closed | src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs | composer draft/attachment/slash/voice/send mutable state and direct composer send/model/thinking/catalog/queue-cancel provider calls | ChatComposerViewModel + ChatComposerController | provider subscription, initial load, immutable snapshot, selected/materialized/compose-only thread selection, timeline/generation/metadata projection, permission-card forwarding, checkpoint routing, #1089 scroll/follow tokens, root composition, and construction of one immutable ChatComposerInputs projection per render | the root holds no composer UseState/refs and calls no composer provider API directly; it builds ChatComposerInputs, forwards them to ReactorChatComposer for post-commit application, and binds the SelectThread handoff | ChatRootComposerClosureTests.Root_DoesNotReintroduceComposerMutableState | source-shape | when OpenClawReactorChatRoot is replaced by a different root/composer boundary |
| sensitive-capture-guard | authoritative | src/OpenClaw.Tray.WinUI/Services/NodeService.cs | ordering of consent, visible per-use indication, and sensor access for instantaneous screen, camera, and location captures | SensitiveCaptureExecutor + SensitiveCapturePlans | NodeService supplies the consent prompt, localized notification, and platform sensor delegates | every sensitive instant capture completes consent and visible indication before its sensor delegate can run; denied consent never reaches the sensor | SensitiveCaptureExecutorTests.ExecuteAsync_RequiresConsentAndIndicatorBeforeSensorAccess | behavioral | - |
| inno-migration-startup | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | migration record parsing and completed-handoff admission | MigrationRecordCodec + InnoMigrationStartupGuard | App invokes the guard before ordinary startup; explicit destructive CLI uninstall remains separate | completed migration prevents normal unpackaged startup before settings or activation; development and packaged apps are unaffected | InnoMigrationContractTests.CompletedMigrationGuard_PrecedesSettingsAndActivation | source-shape | when packaged/unpackaged migration startup is fully hosted outside App |
| store-migration-startup | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | Inno discovery, pending-record inspection, and Store migration admission policy | InnoInstallationDetector + MigrationStartupRecordReader + StoreMigrationStartupCoordinator + StoreMigrationStartupGuard | App calls the compile-time-gated adapter before instance forwarding and normal services | disabled builds perform no migration inspection; preview admission never mutates source state or enables normal startup for pending migration | StoreMigrationStartupCoordinatorTests.Disabled_DoesNotInspectInstallationOrRecords | behavioral | - |
| store-migration-startup-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | direct registry discovery and migration startup policy | StoreMigrationStartupGuard + StoreMigrationStartupCoordinator | one adapter invocation after explicit CLI uninstall and before protocol processing and instance forwarding | App does not regain installation discovery, record parsing, or admission decisions | InnoMigrationContractTests.StorePreviewGuard_PrecedesInstanceForwardingAndNormalServices | source-shape | when packaged migration bootstrap is hosted outside App |
| store-migration-workflow | authoritative | StoreMigrationStartupGuard | native message-box consent loop and inline adoption composition | StoreMigrationWorkflow + StoreMigrationOperations + StoreMigrationWindow | guard gates bootstrap and owns the pre-services window lifetime only | UI actions are serialized; explicit consent precedes shutdown and validation; only verified finalization permits normal startup | StoreMigrationWorkflowTests.ExplicitConfirmation_RecordsConsentBeforeGracefulShutdownAndCompletion | behavioral | - |
| inno-migration-handoff | authoritative | AboutPage + App activation composition | explicit consent, Store listing policy, and migration shutdown authorization | InnoMigrationHandoff + InnoMigrationConsentStore + StoreMigrationListing | About forwards the action and displays its result; App supplies its existing shutdown callback | only configured production Release or explicit preview builds expose handoff; Dev stays isolated; exact same-user Inno and protected consent precede canonical graceful exit; inventory never means consent | InnoMigrationContractTests.InnoPreview_GatesHandoffAndUsesCanonicalShutdown | source-shape | when migration handoff is retired |
| migration-build-policy | authoritative | OpenClaw.Tray.WinUI.csproj | shared Inno/Store compile-time activation and fixed source floor | Migration.Build.props | the tray project imports one policy for packaged and unpackaged publishing | production requires a pinned nonzero source floor and supported Release RID; Debug and Dev cannot inherit production activation | MigrationBuildConfigurationTests.Production_InnoAndStoreShareThePinnedReleasePolicy | behavioral | - |
| migration-consent-locking | authoritative | InnoMigrationConsentStore | protected consent publication and inspection while source is running | MigrationOperationLock + InnoMigrationConsentStore | consent uses a shared preparation lease and a separate exclusive writer lock | consent remains compatible with Inno runtime readers but cannot overlap exclusive Store mutation; finalization removes the writer lock before deleting the completion receipt | InnoMigrationConsentStoreTests.RuntimeReadLease_AllowsExplicitGrantAndInspection | behavioral | - |
| chat-markdown-presentation | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | paragraph and heading typography, literal code-frame presentation and Copy | ChatMarkdownPresentation | timeline keeps sanitization, parser flags and inert links/images; Reactor owns default list wrapping | presentation uses public MarkdownOptions callbacks; code content is never truncated or parsed as markup | ReactorChatLayoutProofTests.CodeBlock_PreservesLiteralContentAndCopiesExactText | behavioral | - |
| chat-markdown-disclosures | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | allowlisted Markdown disclosure parsing and native expansion state | ChatMarkdownDisclosures + ChatMarkdownPresentation | timeline sanitizes before parsing; disclosure bodies use the existing safe Markdown renderer | only balanced, allowlisted block wrappers become native Expanders; unsupported wrappers remain inert Markdown; a reader-toggled header is the timeline's scroll anchor, so details grow downward inside tall messages | ChatMarkdownDisclosureTests.CommonWrappers_KeepBodyMarkdownAndSurroundingOrder | behavioral | - |
| chat-markdown-selection-integration | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | per-message selection opt-in, custom disclosure/code surfaces and localized copy-result feedback | ChatMarkdownMessageView + ChatMarkdownPresentation | Microsoft.UI.Reactor.Markdown owns selection document, geometry, input, scrolling, clipboard write and UI Automation | one Scope shares options across all Markdown fragments; collapsed bodies and chrome are excluded; OnCopyResult never writes clipboard | ReactorChatMarkdownContractTests.MarkdownSelection_UsesOneReactorScopeAndFeedbackOnlyCopyResults | source-shape | when native message-boundary and copy-result acceptance fully replaces the integration source guard |
| reactor-markdown-list-layout | closed | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | preview.12 ListItem layout replacement and StackElement shape assumption | Microsoft.UI.Reactor.Advanced default Markdown list layout (preview.16, upstream #1197) | timeline keeps sanitizer, parser safety and block presentation callbacks | ordered/unordered, nested and loose list content wraps in an Auto/Star Grid without an application-side ListItem override | ReactorChatMarkdownContractTests.AssistantMessages_UseSanitizedGitHubFlavoredMarkdown | source-shape | when upstream Markdown list layout is replaced |
| chat-model-picker-presentation | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatComposer.cs, then custom Button rows in ChatModelPicker | catalog search, provider groups, native row interaction states and model metadata presentation | NativeChatModelPicker through a generated Reactor wrapper | ChatModelPicker owns flyout lifetime; composer controller owns model mutation and authorization | native single-selection navigation never writes a model until explicit activation; filtering and resizing preserve raw provider-qualified identities | ReactorChatLayoutProofTests.ModelMenu_UsesNativeSelectionStatesAndPreservesNavigationDuringResize | behavioral | - |
| chat-model-picker-button-rows-closed | closed | src/OpenClaw.Tray.WinUI/Chat/ChatModelPicker.cs | hand-built Button rows, custom selected fill/checkmark and search-box styling | NativeChatModelPicker | declarative trigger and flyout lifetime only | native AutoSuggestBox/ListView own search and row interaction visuals; no duplicate hand-styled selection path | ReactorChatLayoutProofTests.ModelMenu_UsesNativeSelectionStatesAndPreservesNavigationDuringResize | behavioral | - |
| chat-thinking-profile | authoritative | static levels in ReactorChatComposer | advertised reasoning-profile precedence and exact identity/runtime matching | ChatThinkingProfile over immutable ThinkingContext/ThinkingProfile values | ThinkingMetadata parses and scope-fences gateway metadata; client retains session-cache ownership; ChatSnapshotProjector carries it; composer controller gates selections and clears overrides | no provider/model heuristics, missing differs from empty, unknown saved values remain truthful, and Default is explicit null | ChatThinkingProfileTests.Priority_FirstCandidateWithAnyMetadataOwnsEvenEmptyOrDefaultOnly | behavioral | - |
| reactor-markdown-presentation-closed | closed | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs | inline custom typography and code-frame construction | ChatMarkdownPresentation | timeline owns sanitizer and parser safety options and public callback registration; Reactor owns default list wrapping | custom block presentation is delegated, with no parser or list-measurement fork | ReactorChatMarkdownContractTests.AssistantMessages_UseSanitizedGitHubFlavoredMarkdown | source-shape | when the public MarkdownOptions presentation seam is replaced |
| chat-copy-feedback | authoritative | src/OpenClaw.Tray.WinUI/Chat/ReactorChatTimeline.cs and ChatMarkdownPresentation.cs | copy invocation status, temporary success/failure announcement and reset lifetime | ChatCopyButton with ClipboardHelper.TryCopyText | renderers pass immutable text/identity and keep parser, metadata and workflow ownership | only confirmed clipboard writes show Copied; content changes, repeated clicks and unmount cancel stale resets | ReactorChatLayoutProofTests.CopyFeedback_ResetsRepeatedClicksContentIdentityAndDisposal | behavioral | - |
| chat-transcript-notice-metadata | authoritative | display text and emoji in chat history/live rows | typed skill-change, model-fallback, run-failure, plugin-steering and internal-system notice facts | OpenClawGatewayClient.ReadChatPresentation into ChatMessagePresentation | ChatHistoryLoader and OpenClawChatDataProvider route notices into ChatConversationState.ApplyNotice, which dedups by Gateway identity or notice fact and retires a matching live run-error row | rows are never classified by English text or emoji; unknown or malformed metadata stays an ordinary message | OpenClawGatewayClientTests.StructuredNotice_SkillChangesRejectWholeNoticeForAnyMalformedSkill | behavioral | - |
| chat-transcript-notice-presentation | authoritative | generic Dim status rows for Gateway notices | notice kind, web labels, system-context collapse and run-failure streak folding | ChatNoticePresentation (pure) + ReactorChatNotices (Reactor applicator) | ReactorChatTimeline.BuildStatus dispatches typed notices and keeps the generic status row for everything else; compaction reuses the shared SystemLine | hidden notices (source tool restart, empty internal context) never render; restart-sentinel remains visible; consecutive identical run failures render once with a repeat count |
ChatNoticePresentationTests.Classify_IgnoresNoticeLikeTextWithoutTypedFacts | behavioral | - |
| chat-system-notice-turn-boundary | authoritative | ChatHistoryLoader and ChatConversationState clearing active row IDs | semantic user-turn boundaries for system notices rendered as status rows | ChatTimelineReducer via ChatStatusEvent.StartsTurn and ChatTimelineItem.StartsTurn | ChatNoticePresentation classifies which notices start turns; history and live routes pass the fact to the reducer | turn-starting notices retire prior streaming/tool state and bound assistant reconciliation without admitting a live run; injected/plugin notices remain within their turn | OpenClawChatDataProviderTests.TypedSystemNotices_PreserveTurnBoundariesInHistoryAndLive | behavioral | - |
| chat-transcript-failure-reconciliation | authoritative | live terminal errors and durable failure notices | run-scoped terminal error replacement in either delivery order | ChatConversationState | existing lifecycle settlement still completes the run; notice arrival only changes presentation | only the error whose LiveRunId matches the notice's RunId is removed; an earlier notice suppresses the matching later error without suppressing terminal settlement | OpenClawChatDataProviderTests.RunFailureNotice_ReplacesOnlyItsTerminalErrorInEitherArrivalOrder | behavioral | - |
| chat-skill-workshop-undo | authoritative | web Control UI only | learned-skill Undo admission, single-flight request and sticky outcome | ChatSkillUndoTracker over IChatGatewayBridge.UndoSkillChangesAsync and OpenClawGatewayClient.UndoSkillWorkshopReviewAsync | ReactorSkillLearnedNotice renders Idle, Pending, Undone and Failed; OpenClawChatDataProvider owns the tracker lifetime | Undo is offered only while skills.workshop.undo is advertised and the connection holds operator.admin; requests are connection-epoch fenced, never retried automatically, and only undone/already-undone replies count as success |
OpenClawGatewayClientTests.SkillWorkshopUndo_AcceptsOnlyConfirmedUndoReplies | behavioral | - |
| chat-effort-picker-presentation | authoritative | ReactorChatComposer's native reasoning menu | compact Effort row and native advertised-choice menu | ChatReasoningPicker | ChatThinkingProfile resolves advertised options; ChatComposerController validates and performs mutations; ChatModelPicker hosts the row below the model list in one flyout | opening a popover never writes a setting, only advertised IDs are selected, inherited defaults may be checked without an override, no reset is exposed, and the model trigger retains the current reasoning in its accessible name | ReactorChatLayoutProofTests.ReasoningPicker_UsesConcreteWireValuesWithoutDefaultReset | behavioral | - |
| chat-composer-button-chrome | authoritative | ReactorChatComposer's duplicated per-button resource overrides | shared idle, hover and pressed toolbar resource overrides | ChatVisuals.ToolbarButtonResources | composer constructs the controls and applies the shared resources; native templates retain disabled and keyboard-focus behavior | the combined model trigger stays transparent at rest and matches neighboring toolbar states across resize without replacing native templates | ReactorChatLayoutProofTests.CombinedModelTrigger_PreservesTransparentChromeAndCenteredContent | behavioral | - |
| chat-system-color-refresh | authoritative | ChatMarkdownPresentation's private contrast watcher | mounted chat subscriptions to system color and contrast changes | ChatThemeChanges | Markdown, composer placeholder and transcript fade retain their own styling policies | callbacks run on each element's UI thread and cannot revive an unmounted or replaced subscription; last unmount releases the system event | ReactorChatLayoutProofTests.ComposerContrast_UpdatesMountedSurfacesAndClearsPooledPlaceholder | behavioral | - |
| setup-interactive-flow | authoritative | src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs | interactive installation-step selection and required AI setup decision | OnboardingFlowPolicy | ProgressPage applies progress events and navigation; SetupWindow supplies the selected route to the progress indicator | interactive install never runs the classic wizard or workspace finalization; Local AI still requires exact-model verification when SkipWizard is set; headless step order is unchanged | OnboardingFlowPolicyTests.InteractiveInstallation_DefersWizardAndWorkspaceFinalization | behavioral | - |
| setup-page-flow-closed | closed | src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs | private copy of default installation filtering and implicit post-install milestone gating | OnboardingFlowPolicy | BuildSteps delegates to the policy and success applies its AI setup decision | UI must not recreate the default pipeline selection or require an extra milestone click on successful modern setup | OnboardingPresentationContractTests.SuccessfulInstallation_UsesAiSetupWithoutAMilestoneClick | source-shape | when ProgressPage no longer hosts the interactive installation pipeline |
| setup-gateway-session | authoritative | src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs | temporary setup operator client construction, registry identity, endpoint resolution, and reconnect provenance | SetupGatewaySession | setup pages own their session lifetime and render protocol state; GatewayConnectionManager still owns the normal app connection | setup uses the active registry record and SSH-resolved endpoint with device-token precedence and managed-local provenance before sending strong credentials | AppRefactorContractTests.WizardConnect_UsesActiveGatewayRecordUrl | source-shape | when setup reuses the normal connection manager rather than a temporary operator session |
| setup-page-client-construction-closed | closed | src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs | private gateway-client constructor and duplicated endpoint/credential resolution | SetupGatewaySession | ConnectClientAsync forwards to the shared setup owner and keeps the returned host-access plan | classic and focused setup cannot diverge in endpoint or credential selection | AppRefactorContractTests.WizardConnect_UsesActiveGatewayRecordUrl | source-shape | when the classic gateway wizard is removed |
| connection-validation-client | authoritative | src/OpenClaw.Connection/GatewayConnectionManager.cs | one-shot validation client construction and credential persistence policy | GatewayConnectionValidator | manager retains shared-token replacement workflow and endpoint authorization callback | validation denies reconnect, pins SSH ownership, and cannot persist handshake tokens | GatewayConnectionValidatorTests.ValidationClient_DisablesHandshakeTokenPersistence | behavioral | - |
| connection-validation-construction-closed | closed | src/OpenClaw.Connection/GatewayConnectionManager.cs | private validation-client constructor policy | GatewayConnectionValidator | CreateSharedTokenValidationClient delegates to the focused owner for compatibility | native setup and shared-token replacement share the same one-shot client policy | GatewayConnectionValidatorTests.ValidationClient_DisablesHandshakeTokenPersistence | behavioral | - |
| setup-native-transaction | authoritative | src/OpenClaw.SetupEngine.UI/Pages/AdvancedSetupPage.xaml.cs | native connection checks and commit orchestration | SetupNativeConnectionHost + GatewayDirectConnectService | SetupNativeConnectionPage edits immutable draft and renders results; WindowManager injects the existing transaction owner | Check cannot write saved gateway or live connection state; Next revalidates and cancellation restores previous state | GatewayDirectConnectServiceTests.NativeNext_CancelAfterHandshakeRestoresPreviousIdentityAndLiveConnection | behavioral | - |
| setup-native-identity-promotion | authoritative | src/OpenClaw.Tray.WinUI/Services/GatewayDirectConnectService.cs | native setup identity promotion and compare-and-swap rollback without gateway-ID replacement | DeviceIdentity.ReplaceValidatedIdentity + DeviceIdentity.RestoreValidatedIdentity | direct-connect owner sequences disconnect, promotion, registry/settings commit and rollback | same-realm setup retains logical gateway ID and sidecars; a newer credential writer is preserved and surfaced as incomplete rollback | GatewayDirectConnectServiceTests.NativeNext_ManagedGatewayRetainsLogicalIdAndLocalAiOwnership | behavioral | - |
| setup-local-ai-route | authoritative | src/OpenClaw.Tray.WinUI/Services/WindowManager.cs | Local AI Gateway inspection and first-install or recovery route resolution | LocalAiSetupRouteResolver + LocalAiSetupRoutePolicy | WindowManager composes the resolver and retains Settings window lifetime; SetupLocalAiHost consumes its same typed target | first install without a receipt uses recovery only after unique app-owned Gateway proof; ambiguous and remote targets cannot receive Windows loopback configuration | LocalAiOnboardingTests.Host_FirstInstallWithoutReceipt_AdmitsSameGatewayWithoutRuntimeMutation | behavioral | - |
| setup-local-ai-mutation-drain | authoritative | src/OpenClaw.SetupEngine.UI/Pages/AiSetupPage.xaml.cs | treating local mutation as a bounded observation request | LocalAiOnboardingUse | page cancels requests and awaits actual local mutation drain before CloseAsync completes | runtime rollback must finish before the setup lock is released; uncertain outcomes retain the exact Gateway and model without replay | LocalAiOnboardingUseTests.CancelledUse_DrainRetainsOwnershipUntilActualRollbackEnds | behavioral | - |
| setup-local-ai-registry-handoff | authoritative | src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs | stale live registry after separate-instance pipeline writes and rollback | SetupPipeline.RunWithSettlementAsync + SetupLocalAiHost + GatewayRegistry.ReconcileSetupOutcome | settlement precedes closed-page early return and setup-lock release; notifications are outside locks | all outcomes adopt only known operation output against admitted memory; concurrent edits require explicit recovery, and stale connections are conditionally disconnected | SetupPipelineSettlementTests.FailedOrCancelledPipelineSettlesBeforeClosedOwnerFinishes | behavioral | - |
| setup-local-ai-route-inline-closed | closed | src/OpenClaw.Tray.WinUI/Services/WindowManager.cs | private Local AI route detection algorithm | LocalAiSetupRouteResolver | constructor/delegate composition and failure notification only | Settings and onboarding cannot grow divergent Gateway ownership admission | WindowManagerTests.LocalAiSetup_ChoosesRecoveryOnlyAfterManagedGatewayProof | source-shape | when both Settings and onboarding route admission have mounted host tests |
| setup-local-ai-observation | authoritative | src/OpenClaw.SetupEngine.UI/Pages/AiSetupPage.xaml.cs | hardware, receipt, runtime and ownership observation or mutation policy | LocalAiOnboardingObservation + LocalAiOnboardingSnapshot + SetupLocalAiHost | page applies localized state and forwards explicit actions; SetupWindow alone navigates existing review and recovery pipeline | observation is independent from Gateway discovery and never starts, publishes, grants consent, migrates or writes; stale and closed callbacks are discarded | LocalAiOnboardingTests.Observation_CancelsRefreshAndDiscardsStaleCallbacks | behavioral | - |
| setup-local-ai-host-boundary | closed | src/OpenClaw.SetupEngine.UI/Pages/AiSetupPage.xaml.cs | opening a second setup window or constructing a parallel Local AI runtime and provider-registration owner | ISetupLocalAiHost + SetupWindow | explicit review callback, cancellation and exact-model verification | Local AI review stays under the existing setup lock, preserves access/startup choices and verifies the exact model before completion | LocalAiOnboardingOwnershipTests.AiPage_UsesTypedSameWindowHostAndNeverOwnsRuntimeOrGatewayRegistration | source-shape | when mounted same-window Local AI navigation tests replace source guards |
| setup-ai-completion-intent | authoritative | src/OpenClaw.SetupEngine.UI/Pages/AiSetupPage.xaml.cs | implicit destination from discovery or authentication success | GatewayAiSetupClient + GatewayAiSetupCompletion | page forwards a current verified receipt; intent remains activation provenance, not the native destination | only exact main-model verification yields a completion; focused completion offers only Chat and cannot fall back to browser completion | GatewayAiSetupClientTests.Completion_UsesExplicitActivationKind_NotSetupComplete | behavioral | - |
| setup-native-final-choice | authoritative | src/OpenClaw.SetupEngine.UI/SetupReadyWindow.cs | multiple post-restart destinations or setup mutation after publication | SetupReadyCoordinator + SetupNativeReadyBinding | SetupWindow owns pre-restart preparation and finalization; SetupReadyWindow mounts only Chat and rechecks the captured binding before navigation | showing Ready performs no setup finalization; the explicit Chat action can only navigate to the verified main session | NativeCompletionPresentationTests.FinishingAndReadyHaveLocalizedCopyAndNoFinalizationEntryAfterRestart | source-shape | when mounted Ready-window tests replace source guards |
| setup-native-operator-connection | authoritative | src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs | native operator construction, exact pairing retry and credential handoff authorization | NativeGatewaySetupConnection + NativeGatewaySetupSession | pages drain their operator socket; the window retains the staged runtime and profile | focused and compatibility setup share per-handshake/request provenance, pinned signing identity and canonical agent/session; lost identities cannot be recreated mid-flow | NativeGatewaySetupConnectionTests.EveryRequestAndReconnect_RechecksNativeOwnership | behavioral | - |
| setup-native-page-client-closed | closed | src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs | native client construction and parallel handshake policy | NativeGatewaySetupConnection | classic wizard retains only compatibility RPC/rendering | pages cannot bypass the native owner with a generic loopback session or duplicate pairing policy | NativeGatewaySetupUxContractTests.NativeWizard_UsesSharedPageAndRpc_WithFailClosedStagedAuthorization | source-shape | when compatibility onboarding is removed |
| setup-native-ai-finalization | authoritative | src/OpenClaw.SetupEngine/SetupCompletionPreparation.cs | classic-wizard-only admission to registry publication | SetupCompletionPreparation + NativeGatewaySetupSession.CompleteVerifiedAsync | SetupWindow composes prior-page drain, proof verification, once-only finalization and restart-preparation publication; classic completion stays separate | exact model/agent/session/identity is verified before finalization and reverified after the owned runtime restart before registry publication; unrelated records survive, occupied draft IDs fail | NativeGatewaySetupConnectionTests.FocusedAiPreparation_PublishesOnlyAfterRestartVerification | behavioral | - |
| setup-native-finalization-deadline | authoritative | src/OpenClaw.SetupEngine/SetupCompletionPreparation.cs | unbounded production finalization/publication wait | SetupCompletionPreparation | SetupWindow supplies existing finalization/publication hooks and retains cleanup before releasing its session and setup lock | one execution deadline survives retries; timeout/cancellation cannot abandon admitted work or duplicate mutation/publication | SetupCompletionAuthorityTests.FinalizationAndPublicationWaitsAreFiniteButRetainAdmittedWork | behavioral | - |
| setup-native-finalization-back-guard | authoritative | src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs | Back navigation while timed-out finalization still owns admitted work | SetupCompletionPreparation.HasPendingWork + SetupWindow.CanReturnFromFinishing | window applies existing recovery actions and retains cleanup before releasing the session | a settled presentation wait cannot enable Back while retained work is pending or the Gateway is published | NativeCompletionPresentationTests.FinishingAndReadyHaveLocalizedCopyAndNoFinalizationEntryAfterRestart | source-shape | when SetupWindow has mounted completion-timeout navigation coverage |
| setup-native-restart-verification | authoritative | src/OpenClaw.SetupEngine/SetupNativeCompletionVerifier.cs | generic native loopback verification after restart | GatewayAiSetupTransport.BorrowNativeAsync + GatewayConnectionManager.RequireNativeSetupClientAsync | App only supplies the manager; verifier never disposes the borrowed client or owns a runtime | native provenance is inspected for every request and receipt drift is rejected before navigation | NativeGatewaySetupConnectionTests.PostRestartVerification_BorrowsNormalOwnerAndRejectsUnownedOrReplacedAuthority | behavioral | - |
| setup-native-pending-launch | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | processing already-issued legacy destination receipts | SetupNativeHandoffLauncher + SetupNativeNavigationRequest + SetupDashboardHandoffStore | App supplies composition callbacks; WindowManager mounts verified Chat, while WhatsApp, Telegram, and Channels receipts open the Gateway Dashboard's channels path; retired Skills receipts are rejected |
supported legacy receipts retain exact Gateway/agent/model/session and an exclusive lease; failed opens require explicit retry, successful opens consume | SetupNativeHandoffTests.NativeOpenVerifiesBeforeNavigationAndKeepsFailedLaunchForExplicitRetryOnly | behavioral | - |
| dashboard-launch-owner | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | ordinary Dashboard endpoint construction, credential export policy and browser result handling | GatewayDashboardLauncher + GatewayDashboardUrlBuilder + DashboardBrowser | App supplies credential, tunnel and failure delegates plus the Windows launch that DashboardBrowser wraps; legacy WhatsApp, Telegram, and Channels receipts open the Dashboard channels path with their verified completion and recheck authority immediately before browser dispatch |
only shared credentials enter fragment auth; replaced Gateway or revoked identity is rejected before dispatch; browser failure retains the setup receipt for explicit retry | SetupNativeChatPresentationTests.SetupDashboardDispatchRequiresTheOriginalGatewayAndIdentity | behavioral | when mounted dashboard dispatch coverage also exercises Gateway replacement and the final dispatch authorizer (the GatewayFixtureUiTests LegacyChannelsReceipt cases already mount identity revocation and browser retry) |
| app-dashboard-launch-closed | closed | src/OpenClaw.Tray.WinUI/App.xaml.cs | inline Dashboard URL construction, silent Process.Start failure handling and a Dashboard browser launch that bypasses DashboardBrowser | GatewayDashboardLauncher + DashboardBrowser | composition delegates and normal Dashboard entry forwarding only | App does not regain a parallel Dashboard URL or credential policy or a direct browser launch; explicit retries keep the requested path | AppRefactorContractTests.Dashboard_SurfacesSshTunnelConfigurationFailure | source-shape | when the WinUI Dashboard adapter has injected mounted lifecycle coverage |
| dashboard-browser-fixture-guard | authoritative | src/OpenClaw.Tray.WinUI/App.xaml.cs | handing a Dashboard URL straight to Windows even when the app runs under the gateway fixture | DashboardBrowser | App supplies the Windows launch and logger delegates | outside fixture mode the exact URL goes to Windows; under OPENCLAW_GATEWAY_FIXTURE the launch is suppressed and only the redacted target is logged; a one-shot dashboard-browser-failure.once marker simulates one browser failure; an invalid fixture context fails closed | DashboardBrowserTests.FixtureRun_NeverReachesWindowsAndLogsOnlyTheRedactedUrl | behavioral | - |
| setup-session-captured-authority | authoritative | src/OpenClaw.SetupEngine/SetupGatewaySession.cs | deriving client authority from a later active registry record | SetupGatewaySessionBinding | session reloads registry only to validate captured identity at admission, handshake, reconnect and request boundaries | a socket opened for Gateway A cannot be reported as Gateway B; same-ID endpoint and SSH changes fail while connection timestamps remain valid | SetupGatewaySessionBindingTests.ChangedRegistryDuringConnect_CannotRelabelAlreadyCreatedClient | behavioral | - |
| setup-dashboard-pending-proof | authoritative | src/OpenClaw.Tray.WinUI/Services/SetupDashboardHandoff.cs | accepting external serialized completion JSON as verified proof | SetupDashboardHandoffStore + SetupNativeHandoffLauncher | activation parser admits only an opaque native handle; WindowManager rechecks current observations with SetupDashboardLiveFacts | a short-lived local pending record is exclusively leased, consumed on successful native presentation and retained only for explicit failed-launch retry; unknown, expired, forged, consumed and in-flight replay fail visibly; old generation numbers are not live authority | SetupDashboardHandoffStoreTests.ForgedShapeAndUnknownHandle_AreNotVerificationAuthority | behavioral | - |
DeviceIdentityBuilder and SetupContextBuilder are intentionally not in
OpenClaw.TestSupport yet. DeviceIdentity is a stateful Ed25519 key/file
service (not a value type) and SetupContext needs setup logger/journal/command-runner
fakes. Both will be added alongside their subsystem PRs (gateway protocol and
SetupEngine, respectively) so OpenClaw.TestSupport does not take a heavy
dependency on OpenClaw.SetupEngine prematurely.