docs/LAUNCHER_COORDINATOR.md

# Launcher Coordinator

LanMountainDesktop Launcher uses a per-user coordinator to prevent duplicate host startup.

## Rules

- A Launcher reserves `%LocalAppData%\LanMountainDesktop\.launcher\state\startup-attempt.json` before starting the host.
- The active record stores coordinator pid, coordinator pipe name, heartbeat, host pid, Public IPC state, and shell status.
- Only the active coordinator may start the host process.
- Secondary Launchers attach to the coordinator and request desktop activation.
- A coordinator is considered live while its pid exists and its heartbeat is newer than `10s`.
- Normal launch probes Host Public IPC first; if the host is already running, Launcher activates it and exits.

## Tray And Taskbar

- Tray icon and tray menu are mandatory and are not controlled by user settings.
- Tray watchdog starts with the shell and runs until process exit.
- `ShowInTaskbar=true` affects only the main-window taskbar entry.
- When `ShowInTaskbar=true`, background mode uses a minimized taskbar entry while keeping tray visible.
- Pure `TrayOnly` is allowed only when `ShowInTaskbar=false` and tray is ready.

## Public Shell IPC

Launcher and external callers can use:

- `GetShellStatusAsync()`
- `ActivateMainWindowWithStatusAsync()`
- `EnsureTrayReadyAsync()`
- `EnsureTaskbarEntryAsync()`

These APIs report process, shell, tray, taskbar, and activation state separately so callers do not infer health from window visibility alone.
Add launcher coordinator IPC and startup reservation Introduce a launcher coordinator to reserve startup ownership and prevent duplicate host launches. Adds a NamedPipe-based IPC server/client (LauncherCoordinatorIpcServer/Client), coordinator messages/models, and PublicShellStatus/activation types for richer shell reporting. Enhances StartupAttemptRecord and StartupAttemptRegistry to track coordinator pid/pipe, heartbeat, reserved-before-host-start, and public IPC status, plus new reservation/heartbeat APIs and takeover logic. Wire coordinator into App and LauncherFlowCoordinator to attach secondary launchers, publish coordinator status, probe existing hosts, and include more detailed launch result details. Also adds unit tests and docs describing coordinator and startup visuals behavior. 2026-04-23 09:45:05 +08:00			`# Launcher Coordinator`

			`LanMountainDesktop Launcher uses a per-user coordinator to prevent duplicate host startup.`

			`## Rules`

			- A Launcher reserves `%LocalAppData%\LanMountainDesktop\.launcher\state\startup-attempt.json` before starting the host.
			`- The active record stores coordinator pid, coordinator pipe name, heartbeat, host pid, Public IPC state, and shell status.`
			`- Only the active coordinator may start the host process.`
			`- Secondary Launchers attach to the coordinator and request desktop activation.`
			- A coordinator is considered live while its pid exists and its heartbeat is newer than `10s`.
			`- Normal launch probes Host Public IPC first; if the host is already running, Launcher activates it and exits.`

			`## Tray And Taskbar`

			`- Tray icon and tray menu are mandatory and are not controlled by user settings.`
			`- Tray watchdog starts with the shell and runs until process exit.`
			- `ShowInTaskbar=true` affects only the main-window taskbar entry.
			- When `ShowInTaskbar=true`, background mode uses a minimized taskbar entry while keeping tray visible.
			- Pure `TrayOnly` is allowed only when `ShowInTaskbar=false` and tray is ready.

			`## Public Shell IPC`

			`Launcher and external callers can use:`

			- `GetShellStatusAsync()`
			- `ActivateMainWindowWithStatusAsync()`
			- `EnsureTrayReadyAsync()`
			- `EnsureTaskbarEntryAsync()`

			`These APIs report process, shell, tray, taskbar, and activation state separately so callers do not infer health from window visibility alone.`