Put a window on screen while it starts, and refuse the second one

Two things a desktop application is expected to do and this one did not.

◆ THREE SECONDS OF NOTHING.

Measured on a debug build against a cold profile: the main window arrives 3.1
seconds after the executable does. Nothing was on screen for any of it — the icon
had been double-clicked and the desktop looked unchanged.

The main window cannot come sooner. It needs a view model, and the view model needs
composition to have opened the SQLite cache, bound the terminal's loopback socket,
asked the platform about a TPM and read the install layout off disk. Its own
IsStarting card already narrates what happens after it appears; this is the part
before, which no arrangement of that window can cover.

So SplashWindow, and it is measurably the point: 668 ms to the splash, 3.1 s to the
window that replaces it.

Two mechanics are load-bearing rather than incidental.

The splash *is* desktop.MainWindow for a moment. The lifetime shows whatever that
property holds once OnFrameworkInitializationCompleted returns; a window merely
Show()n there would have no lifetime attached, and under
ShutdownMode.OnLastWindowClose the first close of anything would end the process.
Handing the property over is one assignment and Avalonia reads it lazily.

And composition is posted at DispatcherPriority.Background rather than called. It
is synchronous and slow — which is the entire argument for a splash — so running it
inline would block the very dispatcher turn that has to paint the thing.

The window is SizeToContent="Height", which is about the failure and not the
splash: CouldNotStart carries an exception's own message, and inside a fixed height
a long one would wrap and be clipped at exactly the moment that text is all the
window is for. A composition that throws is caught rather than left to the
dispatcher, for the same reason — before this there was nothing on screen to
abandon, and now there is, so an escaping exception would leave a window saying
"Starting…" over a process that had stopped. Escape closes it, and only then.

◆ AND ONE INSTANCE.

Claimed in Main before Avalonia is configured, so a second launch starts nothing at
all: no toolkit, no window, no splash flashing up before it thinks better of it.

Exclusion is an exclusive handle on instance.lock inside the profile directory, and
that location settles two questions at once. A nightly and a release build do not
exclude each other — separate profiles, ADR 0013 — and two people signed in to one
machine each get their own instance. A global mutex would have had to re-derive
both from somewhere.

A file handle rather than a named mutex because the kernel releases it however the
process ends. There is no such thing as a stale lock here, which is a state a
named mutex makes both platforms model differently and neither model simply.

The second launch is not silent. Somebody who double-clicks an icon and sees
nothing has been told the application is broken, so it rings a named pipe — named
from a digest of the profile path, so it is scoped exactly as the lock is — and the
running instance un-minimises and activates. Activate is a request and not a
guarantee: Windows refuses the foreground to a process that did not receive the
input, and the flashing taskbar button that results is still an answer.

Three seconds of retrying when the lock is held by something that does not answer
its pipe, and that window has one job. Velopack's apply ends this process and its
updater starts the new build; the two are ordered, but a lock held a moment too
long would make the successor refuse itself and vanish — an update that looked like
an uninstall. The doorbell is disposed before Shutdown for the same reason, so the
pipe name is free before the process is.

◆ VERIFIED BY RUNNING IT, WHICH IS THE ONLY WAY EITHER OF THESE COULD BE.

Two launches of the built executable: the first stayed up with instance.lock in the
profile, the second exited. Window sizes over time are where the two timings above
come from — 420x160 then 1196x776.

SingleInstanceTests covers what a single process can reach: the lock, its release
by disposal, the doorbell answering more than once, and two profiles not excluding
each other. SplashCardTests measures the one thing the splash can get wrong, which
is a failure message long enough to need the height the window is willing to give
it. Checks 1.12 and 16.11 are what needs a second executable and a real screen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/DodoSSH.Client.App.Tests/SingleInstanceTests.cs

@@ -0,0 +1,182 @@
+using DodoSSH.Client.App.Platform;
+using DodoSSH.Client.Session;
+
+namespace DodoSSH.Client.App.Tests;
+
+/// <summary>
+/// One desktop instance per profile, and what the second launch does instead of starting.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Both halves are real here: a real lock file in a real temporary profile, and a real named pipe. Neither
+/// is worth faking — the whole claim being made is about what the operating system does with an exclusive
+/// handle and a pipe name, and a fake of either would be a test of the fake.
+/// </para>
+/// <para>
+/// What is <em>not</em> reachable from here is a second process. Every test below runs in one, so the lock
+/// is proved against a second <em>handle</em> rather than a second executable, and the window that comes
+/// forward is a delegate rather than a window. <c>docs/manual-checks.md</c> 16.11 is the other side of that
+/// line.
+/// </para>
+/// </remarks>
+public sealed class SingleInstanceTests : IDisposable
+{
+    /// <summary>
+    /// A profile of its own per test, which is what makes these safe to run beside a real installation.
+    /// </summary>
+    /// <remarks>
+    /// The pipe name is derived from this directory — see <c>SingleInstance.PipeNameFor</c> — so a unique
+    /// directory is also a unique pipe. Without that, a test here would ring the doorbell of whatever
+    /// DodoSSH the developer happens to have running.
+    /// </remarks>
+    private readonly ClientPaths paths =
+        new(Path.Combine(Path.GetTempPath(), $"dodossh-instance-{Guid.CreateVersion7():N}"));
+
+    /// <summary>
+    /// No patience at all, which is what every test here wants.
+    /// </summary>
+    /// <remarks>
+    /// The shipped three seconds exist for a lock held by a process on its way out — an update relaunching
+    /// itself, above all — and nothing here is on its way anywhere. Passing zero takes the give-up decision
+    /// on the first attempt, so a refusal costs a millisecond rather than three seconds of the suite.
+    /// </remarks>
+    private static readonly TimeSpan Impatient = TimeSpan.Zero;
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        if (Directory.Exists(paths.DataDirectory))
+        {
+            Directory.Delete(paths.DataDirectory, recursive: true);
+        }
+    }
+
+    [Fact]
+    public void TheFirstLaunchClaimsTheProfile()
+    {
+        using var claim = SingleInstance.Claim(paths, Impatient);
+
+        claim.ShouldNotBeNull();
+        File.Exists(paths.InstanceLockFile).ShouldBeTrue("the claim is a handle on a real file");
+    }
+
+    /// <remarks>
+    /// The point of the whole exercise. Nobody is listening in this test, so the second claim takes the
+    /// give-up path rather than the ask-and-leave one — which is why it is handed no patience at all.
+    /// </remarks>
+    [Fact]
+    public void ASecondLaunchIsRefused()
+    {
+        using var first = SingleInstance.Claim(paths, Impatient);
+        first.ShouldNotBeNull();
+
+        SingleInstance.Claim(paths, Impatient).ShouldBeNull();
+    }
+
+    /// <remarks>
+    /// ◆ There is no such thing as a stale lock here, and this is what says so. The handle is closed by the
+    /// runtime when it is disposed and by the kernel when the process ends however it ends — which is the
+    /// reason this is a file rather than a named mutex, whose abandonment is a state to be handled.
+    /// </remarks>
+    [Fact]
+    public void TheProfileIsClaimableAgainOnceTheFirstInstanceLetsGo()
+    {
+        var first = SingleInstance.Claim(paths, Impatient);
+        first.ShouldNotBeNull();
+        first.Dispose();
+
+        using var second = SingleInstance.Claim(paths, Impatient);
+
+        second.ShouldNotBeNull("the lock went with the handle");
+    }
+
+    /// <remarks>
+    /// The other half: a refused launch is not a silent one. Somebody who double-clicks the icon and sees
+    /// nothing has been told the application is broken, so the running instance is asked to come forward.
+    /// </remarks>
+    [Fact]
+    public async Task ARefusedLaunchAsksTheRunningInstanceToComeForward()
+    {
+        using var first = SingleInstance.Claim(paths, Impatient);
+        first.ShouldNotBeNull();
+
+        var asked = new TaskCompletionSource();
+
+        await using var doorbell = SingleInstance.Listen(paths, () => asked.TrySetResult());
+
+        SingleInstance.Claim(paths, Impatient).ShouldBeNull("the profile is taken");
+
+        // Awaited rather than polled: the callback comes off a thread pool thread, and the test's own
+        // cancellation is what bounds a doorbell that never rings.
+        await asked.Task.WaitAsync(TestContext.Current.CancellationToken);
+    }
+
+    /// <remarks>
+    /// A third and a fourth launch work as well as the second, which is what the accept loop is for: a
+    /// <c>NamedPipeServerStream</c> that has served one client cannot serve another, so a doorbell that
+    /// forgot to go round again would answer exactly one refused launch and then leave every later one to
+    /// exit in silence.
+    /// </remarks>
+    [Fact]
+    public async Task TheDoorbellAnswersMoreThanOnce()
+    {
+        using var first = SingleInstance.Claim(paths, Impatient);
+        first.ShouldNotBeNull();
+
+        var rings = 0;
+        var twice = new TaskCompletionSource();
+
+        await using var doorbell = SingleInstance.Listen(
+            paths,
+            () =>
+            {
+                if (Interlocked.Increment(ref rings) == 2)
+                {
+                    twice.TrySetResult();
+                }
+            });
+
+        SingleInstance.AskTheRunningOneToComeForward(paths).ShouldBeTrue();
+        SingleInstance.AskTheRunningOneToComeForward(paths).ShouldBeTrue();
+
+        await twice.Task.WaitAsync(TestContext.Current.CancellationToken);
+    }
+
+    /// <remarks>
+    /// What the give-up path turns on. A lock held by something that is not listening — a process still
+    /// starting, or one on its way out — answers no, and that is what makes <c>Claim</c> wait and try the
+    /// lock again rather than concluding anything from the silence.
+    /// </remarks>
+    [Fact]
+    public void AskingWithNobodyListening_SaysSo()
+    {
+        SingleInstance.AskTheRunningOneToComeForward(paths).ShouldBeFalse();
+    }
+
+    /// <remarks>
+    /// Two profiles, because a nightly and a release build are installed side by side on purpose and must
+    /// not exclude each other — ADR 0013. The lock file is inside the profile and the pipe name is derived
+    /// from it, so both halves are scoped by the one decision <c>ClientPaths.ForChannel</c> already made.
+    /// </remarks>
+    [Fact]
+    public void TwoProfilesDoNotExcludeEachOther()
+    {
+        var other = new ClientPaths(paths.DataDirectory + ".Nightly");
+
+        try
+        {
+            using var release = SingleInstance.Claim(paths, Impatient);
+            using var nightly = SingleInstance.Claim(other, Impatient);
+
+            release.ShouldNotBeNull();
+            nightly.ShouldNotBeNull("a second profile is a second application");
+        }
+        finally
+        {
+            if (Directory.Exists(other.DataDirectory))
+            {
+                Directory.Delete(other.DataDirectory, recursive: true);
+            }
+        }
+    }
+}