ui: start the main loop just-in-time

[mjcheetham]

On macOS, GCM hangs if it shows any UI before an interactive Entra sign-in that uses the broker. Cloning a repository that prompts for a credential and then needs broker authentication is enough to reproduce it. The process never exits and Git waits on it forever.

Why it happens

GCM keeps the process entry thread free so that platform APIs which insist on "thread 1" can be served, and runs the application itself on a second thread. Two features need that thread, for unrelated reasons:

• macOS requires UI controls to be created on the entry thread.
• The macOS MSAL broker requires a running NSApplication.

Avalonia satisfied the first by posting its main loop to our dispatcher as a job. That job never returns, so from the moment a window was shown the dispatcher's queue stopped being drained. Anything posted afterwards — such as the broker call marshalling itself to the main thread — queued up behind a job that would never finish.

There is a second, less obvious half to this. MSAL decides once per process whether it is a "console app", by testing whether NSApplication is running, and caches the answer for the lifetime of the process:

// DesktopOsHelper.cs, MSAL 4.85.2
private static readonly Lazy<bool> _isMacConsoleApp =
    new Lazy<bool>(() => !LibObjc.IsNsApplicationRunning());

Without NSApplication it requires interactive calls to run on managed thread 1 and then takes that thread over with its own Thread.Sleep(10) polling loop, which cannot coexist with a UI main loop. With NSApplication running it requires neither. So whichever of UI and broker happened to run first silently decided whether the second could work at all — and the "broker first, UI later, broker again" ordering would have frozen the UI even once the queue starvation was fixed.

The fix

Ownership of the entry thread moves into the dispatcher, which now starts the main loop lazily, on the first job posted, and hands the thread over to it.

Needing the main thread therefore implies a running main loop, and because the hand-over completes before any job can be dispatched, every job is guaranteed to run with NSApplication already up. MSAL always sees a GUI app. There is no "start the UI first" call for a caller to forget, and no ordering left to get wrong: UI and broker can now be used in either order, both, or neither.

Startup cost is unchanged for the common case. An invocation that shows no UI and does not use the broker posts no jobs at all: the thread parks on the job queue and shuts down again without ever initialising Avalonia. The silent and default-account authentication probes deliberately stay off the dispatcher for the same reason — only interactive calls decide MSAL's mode, so routing the silent ones through it would pay for Avalonia startup and buy nothing.

Series

Reviewing commit by commit is recommended; each builds and tests green.

• 1-4 fix pre-existing dispatcher defects that the rework would otherwise have built on. All four predate this work and are independently backportable: jobs that threw left their caller awaiting forever, continuations resumed inline on the dispatcher thread, shutting down before Run() was reached threw on the application thread, and async work handed back a task that completed at its first await rather than at completion.
• 5 is the change described above.
• 6 corrects the comment explaining the macOS broker's requirement. It claimed the broker needs the main thread "to display UI", which sends a reader looking for a window parenting problem that does not exist.

Testing

src/Core.Tests/UI/DispatcherTests.cs covers the hand-over and the shutdown paths through a fake main loop: shutting down before Run(), with no work posted, while the loop is running, and with work still outstanding. The last of these pins down the deliberate decision to abandon pending work at shutdown rather than drain it — draining would deadlock the obvious case, where a window is shown without anyone awaiting it and so nothing ever completes the work being waited on.

Notes for reviewers

Tip

Read the "docs/dispatcher.md" documentation (rendered) about how the dispatcher works first as this will help understand the design and operation at a higher level.

Important

The MSAL behaviour this depends on is version-specific. The call sites that evaluate the console/GUI decision are noted in a comment against 4.85.2; DesktopOsHelper.IsMacConsoleApp is worth re-checking on an MSAL upgrade.

• One behavioural consequence worth being aware of: the avn_init Trace2 region is now recorded on the main thread rather than on the calling thread, because initialisation no longer has a caller to attribute it to.

• Windows and Linux are unaffected. Their brokers never used the dispatcher, and the only other consumer of it is the UI, which needs the main loop regardless.

[Copilot]

🟡 Changes recommended

Handed-off jobs can remain incomplete if the platform main loop fails before executing them.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Moves platform main-loop ownership into the dispatcher to prevent macOS UI/broker deadlocks.

Changes:

• Starts Avalonia lazily when dispatcher work first arrives.
• Routes UI and interactive macOS broker work through the dispatcher.
• Adds dispatcher lifecycle and shutdown tests.

File summaries

File	Description
src/Core/UI/IMainLoop.cs	Defines the platform-loop abstraction.
src/Core/UI/Dispatcher.cs	Implements lazy handoff, async jobs, and shutdown.
src/Core/UI/AvaloniaUi.cs	Routes window creation through the dispatcher.
src/Core/UI/AvaloniaMainLoop.cs	Implements the Avalonia-backed main loop.
src/Core/Authentication/Entra/EntraAuthentication.PublicClient.cs	Dispatches interactive macOS broker authentication.
src/Core.Tests/UI/DispatcherTests.cs	Tests startup and shutdown behavior.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.