@@ -24,25 +24,40 @@ namespace SharpAstro.AppShell;
 public static partial class ForegroundActivation
 {
     /// <summary>
-    /// Grant <paramref name="processId"/> the right to bring its window to the front. Best-effort:
-    /// a false return from the OS is not actionable and is not reported, because the fallback (a
-    /// flashing taskbar button) is already the behaviour we are trying to improve on.
+    /// Grant <paramref name="processId"/> the right to bring its window to the front. Returns
+    /// whether the grant was made, which is NOT the same question as whether the window then came
+    /// forward.
+    ///
+    /// <para>The distinction is the whole reason this reports anything. The OS refuses the grant
+    /// when the CALLER does not itself hold the foreground right -- which is normal for a process
+    /// started by a script rather than by a user's double-click. Without this return value, that
+    /// case and a genuinely broken raise are indistinguishable: both look like a window that
+    /// flashed its taskbar button and stayed put.</para>
+    ///
+    /// <para>Always true off Windows, where nothing needs granting; a false is never fatal, because
+    /// the fallback is the taskbar flash this is trying to improve on.</para>
     /// </summary>
-    public static void AllowFor(int processId)
+    public static bool AllowFor(int processId)
     {
-        if (processId <= 0 || !OperatingSystem.IsWindows())
+        if (processId <= 0)
         {
-            return;
+            return false;
+        }
+
+        if (!OperatingSystem.IsWindows())
+        {
+            return true;
         }
 
         try
         {
-            _ = AllowSetForegroundWindow((uint)processId);
+            return AllowSetForegroundWindow((uint)processId);
         }
         catch (Exception)
         {
             // A missing entry point on some future Windows edition must not break a hand-off whose
             // payload has not been sent yet.
+            return false;
         }
     }
 
 
@@ -195,7 +195,16 @@ public static bool TryHandOff(string channel, string payload, TimeSpan timeout,
                 return false;
             }
 
-            ForegroundActivation.AllowFor(BitConverter.ToInt32(header));
+            var holderPid = BitConverter.ToInt32(header);
+            var granted = ForegroundActivation.AllowFor(holderPid);
+            if (!granted)
+            {
+                // Logged rather than swallowed: the hand-off will still deliver and the document
+                // will still open, but the window will flash its taskbar button instead of coming
+                // forward, and this line is the only way to tell that apart from a broken raise.
+                log?.LogDebug("Foreground grant to process {Pid} was refused; this process may not hold "
+                    + "the foreground right (normal when launched by a script rather than the shell)", holderPid);
+            }
 
             var bytes = Encoding.UTF8.GetBytes(payload);
             if (bytes.Length > MaxPayloadBytes)
Original file line number	Diff line number	Diff line change
`@@ -24,25 +24,40 @@ namespace SharpAstro.AppShell;`
`24`	`24`	`public static partial class ForegroundActivation`
`25`	`25`	`{`
`26`	`26`	`/// <summary>`
`27`		`- /// Grant <paramref name="processId"/> the right to bring its window to the front. Best-effort:`
`28`		`- /// a false return from the OS is not actionable and is not reported, because the fallback (a`
`29`		`- /// flashing taskbar button) is already the behaviour we are trying to improve on.`
	`27`	`+ /// Grant <paramref name="processId"/> the right to bring its window to the front. Returns`
	`28`	`+ /// whether the grant was made, which is NOT the same question as whether the window then came`
	`29`	`+ /// forward.`
	`30`	`+ ///`
	`31`	`+ /// <para>The distinction is the whole reason this reports anything. The OS refuses the grant`
	`32`	`+ /// when the CALLER does not itself hold the foreground right -- which is normal for a process`
	`33`	`+ /// started by a script rather than by a user's double-click. Without this return value, that`
	`34`	`+ /// case and a genuinely broken raise are indistinguishable: both look like a window that`
	`35`	`+ /// flashed its taskbar button and stayed put.</para>`
	`36`	`+ ///`
	`37`	`+ /// <para>Always true off Windows, where nothing needs granting; a false is never fatal, because`
	`38`	`+ /// the fallback is the taskbar flash this is trying to improve on.</para>`
`30`	`39`	`/// </summary>`
`31`		`- public static void AllowFor(int processId)`
	`40`	`+ public static bool AllowFor(int processId)`
`32`	`41`	`{`
`33`		`- if (processId <= 0 \|\| !OperatingSystem.IsWindows())`
	`42`	`+ if (processId <= 0)`
`34`	`43`	`{`
`35`		`- return;`
	`44`	`+ return false;`
	`45`	`+ }`
	`46`	`+`
	`47`	`+ if (!OperatingSystem.IsWindows())`
	`48`	`+ {`
	`49`	`+ return true;`
`36`	`50`	`}`
`37`	`51`
`38`	`52`	`try`
`39`	`53`	`{`
`40`		`- _ = AllowSetForegroundWindow((uint)processId);`
	`54`	`+ return AllowSetForegroundWindow((uint)processId);`
`41`	`55`	`}`
`42`	`56`	`catch (Exception)`
`43`	`57`	`{`
`44`	`58`	`// A missing entry point on some future Windows edition must not break a hand-off whose`
`45`	`59`	`// payload has not been sent yet.`
	`60`	`+ return false;`
`46`	`61`	`}`
`47`	`62`	`}`
`48`	`63`