Make Gateway restarts explicit, consent-based, and progress-aware

[boycez]

Summary

Make every Gateway restart explicit and predictable in the app. Planned restarts should require informed user consent before the app becomes unavailable, and all restarts should use a consistent progress experience that clearly communicates what is happening, why it is happening, and when the app is ready again.

Problem

Several settings changes and product actions currently restart the Gateway automatically. During a restart, core app functionality is unavailable for a noticeable amount of time, but users are not consistently warned before the interruption and do not receive a unified indication of restart progress.

This can make the app appear frozen, disconnected, or broken. It can also interrupt an in-progress chat or other work without giving the user an opportunity to finish, defer the restart, or understand which action caused it.

Known restart-triggering scenarios include model configuration changes, skill configuration changes, sandbox changes, WeChat login or disconnection, agent roster fallback, startup plugin activation, and automatic Gateway recovery. The experience is currently implemented differently across these paths.

Desired Experience

Introduce one shared Gateway restart UX pattern and route every restart through it.

Planned restarts

For restarts caused by a user-initiated setting change or action:

• Tell the user before committing the action that a Gateway restart is required.
• Explain why the restart is needed and that core app functionality will be temporarily unavailable.
• Require explicit consent before starting the restart.
• Where technically safe, offer clear choices such as Restart now, Restart later, and Cancel.
• Preserve unsent chat drafts, navigation state, and completed configuration changes across the restart.
• Do not silently trigger a second restart when multiple pending changes can be applied together.

Restart progress

Once a restart begins:

• Show a consistent, prominent progress surface across the app.
• Indicate meaningful states such as preparing, stopping the Gateway, starting the Gateway, reconnecting, and ready.
• Prevent actions that cannot succeed during the restart, while preserving access to any UI that remains safe to use.
• Clearly announce completion and restore the app to an interactive state.
• Support keyboard navigation, screen readers, localization, and reduced-motion settings.

Recovery and failure

• Define the UX policy for unplanned recovery restarts, where waiting for consent may leave the app unusable. At minimum, tell the user immediately why recovery is happening and show the same progress surface.
• If restart fails or times out, show an actionable error with Retry, diagnostics or log access, and a safe exit path.
• Deduplicate concurrent restart requests and communicate when another change has been folded into an already pending restart.

Design Questions

• Which restart causes may safely support Restart later, and which must block completion of the initiating action?
• Should pending restart-required changes be represented by a persistent banner or status center?
• Which progress phases can be reported reliably by the current Gateway lifecycle?
• How should active chats, tool executions, permission prompts, and remote channel sessions be handled before restart?
• What policy should distinguish consent-based planned restarts from automatic crash or health recovery?
• Should the first startup plugin-activation restart remain visible, or should startup be restructured to avoid it?

Acceptance Criteria

• All Gateway restart entry points use a centralized restart coordinator and shared UX pattern.
• Every planned restart identifies its cause and requires user consent before the Gateway is stopped.
• Restart-required settings clearly communicate the requirement before the user applies the change.
• Users receive continuous, accessible progress feedback until the Gateway is usable again.
• Conflicting actions and message sends are safely handled while restart is in progress.
• Multiple simultaneous restart requests are coalesced rather than restarting repeatedly.
• Unsent user input and relevant UI state survive a successful restart.
• Recovery restarts are immediately visible and explain why they were necessary.
• Failed or timed-out restarts provide retry and diagnostic actions without leaving the app in an ambiguous state.
• The pattern is validated across model, skills, sandbox, channel, agent, startup, manual, and automatic recovery restart paths.