@@ -118,5 +118,19 @@ if ([NSThread isMainThread]) {
 }
 ```
 
-Use `dispatch_sync` when the caller needs the result, and `dispatch_async` for
-UI updates and other non-blocking work.
+Use `dispatch_async` for UI updates and other work the caller does not wait
+for.
+
+When a Go thread needs a result from the main thread, run the work inline if
+the caller is already on the main thread. Otherwise `dispatch_async` it to the
+main queue and wait on a semaphore with a timeout. A Go thread must never block
+on the main queue without a bound, because the main thread may be busy, or not
+running its loop at all, and the IPC or reload goroutine waiting on it would
+hang too. On timeout, leave the work queued and return an answer the caller
+can report as unknown or pending. Never run it on the calling thread instead,
+since the work is main-thread-only. `NeruSetReferenceKeyboardLayout` and
+`NeruCopyKeyboardLayouts` in `keymap_darwin.m` do this with a 500ms bound.
+
+Never `dispatch_sync` onto the main queue from the main thread, because
+libdispatch traps it. The alert and overlay bridges still `dispatch_sync` for
+work the caller has to wait out, such as a modal alert.
@@ -93,25 +93,28 @@ func SetReferenceKeyboardLayout(inputSourceID string) bool {
 // find, which it decides itself because it also accepts localized names. It is
 // also true when the layout it found is no longer enabled, because the
 // resolver keeps its match after the user removes that layout.
+//
+// KeyboardLayouts reads the layouts on the main thread, because TIS must run
+// there. When the main queue does not answer within 500ms it returns no names
+// and no reference. The last result is then whether the resolver last failed
+// to find the configured layout, and false while an apply for another layout
+// is still queued, since that one has not been resolved yet.
 func KeyboardLayouts() ([]string, string, bool) {
-	var names []string
-
-	if cIDs := C.NeruCopyKeyboardLayoutIDs(); cIDs != nil {
-		if ids := C.GoString(cIDs); ids != "" {
-			names = strings.Split(ids, "\n")
-		}
+	var cIDs, cReference *C.char
+	var cResolved C.int
 
-		C.free(unsafe.Pointer(cIDs))
-	}
+	C.NeruCopyKeyboardLayouts(&cIDs, &cReference, &cResolved)
+	defer C.free(unsafe.Pointer(cIDs))
+	defer C.free(unsafe.Pointer(cReference))
 
-	var reference string
-
-	if cReference := C.NeruCopyReferenceKeyboardLayoutID(); cReference != nil {
-		reference = C.GoString(cReference)
-		C.free(unsafe.Pointer(cReference))
+	var names []string
+	if ids := C.GoString(cIDs); ids != "" {
+		names = strings.Split(ids, "\n")
 	}
 
-	unmatched := C.NeruReferenceKeyboardLayoutResolved() == 0 || !slices.Contains(names, reference)
+	// With no names listed, only the resolver can say the layout is missing.
+	reference := C.GoString(cReference)
+	unmatched := cResolved == 0 || (len(names) > 0 && !slices.Contains(names, reference))
 
 	return names, reference, unmatched
 }
@@ -196,17 +196,16 @@ void NeruRefreshKeyboardLayoutMaps(void);
 /// applies once the main run loop runs it, logging a warning if it is missing.
 int NeruSetReferenceKeyboardLayout(const char *inputSourceID);
 
-/// NeruCopyKeyboardLayoutIDs returns the input source IDs of the enabled
-/// keyboard layouts, one per line, or NULL. The caller frees it.
-char *NeruCopyKeyboardLayoutIDs(void);
-
-/// NeruCopyReferenceKeyboardLayoutID returns the input source ID keys are
-/// named in, or NULL. The caller frees it.
-char *NeruCopyReferenceKeyboardLayoutID(void);
-
-/// NeruReferenceKeyboardLayoutResolved returns 0 when kb_layout_to_use names a
-/// layout the resolver could not find, and 1 otherwise.
-int NeruReferenceKeyboardLayoutResolved(void);
+/// NeruCopyKeyboardLayouts reads the keyboard layouts through TIS on the main
+/// thread. It sets layoutIDsOut to the input source IDs of the enabled layouts,
+/// one per line, and referenceIDOut to the ID keys are named in. Either is NULL
+/// when unknown, and the caller frees both. resolvedOut is 0 when
+/// kb_layout_to_use names a layout the resolver could not find, and 1 otherwise.
+/// Off the main thread the call reads on the main queue. When that queue does
+/// not answer within 500ms the call leaves both IDs NULL and sets resolvedOut
+/// to what the main thread last recorded, or to 1 while a
+/// NeruSetReferenceKeyboardLayout apply for another layout is still queued.
+void NeruCopyKeyboardLayouts(char **layoutIDsOut, char **referenceIDOut, int *resolvedOut);
 
 /// Callback type invoked after keyboard layout maps are rebuilt.
 typedef void (*KeymapLayoutChangeCallback)(void);
 
@@ -35,6 +35,9 @@
 static BOOL gUsesCurrentLayoutFallback = NO;
 /// whether the configured layout ID was resolved successfully (or no explicit ID was set)
 static BOOL gConfiguredInputSourceResolved = YES;
+/// layout ID the latest NeruSetReferenceKeyboardLayout call asked for, recorded
+/// before its apply is queued, so it can differ from gConfiguredInputSourceID
+static NSString *gRequestedInputSourceID = nil;
 
 /// cached keycode-to-char maps for common modifier combinations (shift, caps, shift+caps)
 /// to avoid UCKeyTranslate calls during key event handling
@@ -1201,54 +1204,81 @@ void NeruRefreshKeyboardLayoutMaps(void) {
 	}
 }
 
-char *NeruCopyKeyboardLayoutIDs(void) {
-	@autoreleasepool {
-		NSDictionary *filter =
-		    @{(__bridge NSString *)kTISPropertyInputSourceType : (__bridge NSString *)kTISTypeKeyboardLayout};
-		CFArrayRef inputSourceList = TISCreateInputSourceList((__bridge CFDictionaryRef)filter, false);
-		if (!inputSourceList) {
-			return NULL;
-		}
+void NeruCopyKeyboardLayouts(char **layoutIDsOut, char **referenceIDOut, int *resolvedOut) {
+	*layoutIDsOut = NULL;
+	*referenceIDOut = NULL;
 
-		NSMutableArray<NSString *> *ids = [NSMutableArray array];
-		CFIndex sourceCount = CFArrayGetCount(inputSourceList);
-		for (CFIndex i = 0; i < sourceCount; i++) {
-			TISInputSourceRef source = (TISInputSourceRef)CFArrayGetValueAtIndex(inputSourceList, i);
-			NSString *sourceID = (__bridge NSString *)TISGetInputSourceProperty(source, kTISPropertyInputSourceID);
-			if (sourceID && inputSourceHasUnicodeLayoutData(source)) {
-				[ids addObject:sourceID];
+	__block NSString *layoutIDs = nil;
+	__block NSString *referenceID = nil;
+	__block BOOL resolved = YES;
+
+	void (^readLayouts)(void) = ^{
+		@autoreleasepool {
+			NSDictionary *filter =
+			    @{(__bridge NSString *)kTISPropertyInputSourceType : (__bridge NSString *)kTISTypeKeyboardLayout};
+			CFArrayRef inputSourceList = TISCreateInputSourceList((__bridge CFDictionaryRef)filter, false);
+			if (inputSourceList) {
+				NSMutableArray<NSString *> *ids = [NSMutableArray array];
+				CFIndex sourceCount = CFArrayGetCount(inputSourceList);
+				for (CFIndex i = 0; i < sourceCount; i++) {
+					TISInputSourceRef source = (TISInputSourceRef)CFArrayGetValueAtIndex(inputSourceList, i);
+					NSString *sourceID =
+					    (__bridge NSString *)TISGetInputSourceProperty(source, kTISPropertyInputSourceID);
+					if (sourceID && inputSourceHasUnicodeLayoutData(source)) {
+						[ids addObject:sourceID];
+					}
+				}
+				CFRelease(inputSourceList);
+				layoutIDs = [ids componentsJoinedByString:@"\n"];
+			}
+
+			TISInputSourceRef reference = copyResolvedReferenceInputSource(&resolved, NULL);
+			if (reference) {
+				referenceID =
+				    [(__bridge NSString *)TISGetInputSourceProperty(reference, kTISPropertyInputSourceID) copy];
+				CFRelease(reference);
 			}
 		}
-		CFRelease(inputSourceList);
+	};
 
-		return strdup([[ids componentsJoinedByString:@"\n"] UTF8String]);
-	}
-}
+	if ([NSThread isMainThread]) {
+		readLayouts();
+	} else {
+		// TIS must run on the main thread, so the read never falls back to
+		// this one. A main queue that does not answer in time leaves the read
+		// queued, and nobody reads its late results. The resolved flag the main
+		// thread last recorded needs no TIS, so the call still reports it.
+		dispatch_semaphore_t completed = dispatch_semaphore_create(0);
+		dispatch_async(dispatch_get_main_queue(), ^{
+			readLayouts();
+			dispatch_semaphore_signal(completed);
+		});
 
-int NeruReferenceKeyboardLayoutResolved(void) {
-	@autoreleasepool {
-		BOOL resolved = YES;
-		TISInputSourceRef source = copyResolvedReferenceInputSource(&resolved, NULL);
-		if (source) {
-			CFRelease(source);
-		}
+		dispatch_time_t timeout = dispatch_time(DISPATCH_TIME_NOW, (int64_t)(500 * NSEC_PER_MSEC));
+		if (dispatch_semaphore_wait(completed, timeout) != 0) {
+			NeruLog(NeruLogLevelWarn, @"Timed out waiting for the main queue, keyboard layouts not read", @"500ms");
+
+			// The flag belongs to the configured layout. While an apply for
+			// another layout is still queued it says nothing about the one
+			// requested, so the call reports that one as not unmatched.
+			[gKeymapLock lock];
+			BOOL applied = gRequestedInputSourceID == gConfiguredInputSourceID ||
+			               [gRequestedInputSourceID isEqualToString:gConfiguredInputSourceID];
+			*resolvedOut = (!applied || gConfiguredInputSourceResolved) ? 1 : 0;
+			[gKeymapLock unlock];
 
-		return resolved ? 1 : 0;
+			return;
+		}
 	}
-}
 
-char *NeruCopyReferenceKeyboardLayoutID(void) {
 	@autoreleasepool {
-		TISInputSourceRef source = copyResolvedReferenceInputSource(NULL, NULL);
-		if (!source) {
-			return NULL;
+		if (layoutIDs) {
+			*layoutIDsOut = strdup([layoutIDs UTF8String]);
 		}
-
-		NSString *sourceID = (__bridge NSString *)TISGetInputSourceProperty(source, kTISPropertyInputSourceID);
-		char *copied = sourceID ? strdup([sourceID UTF8String]) : NULL;
-		CFRelease(source);
-
-		return copied;
+		if (referenceID) {
+			*referenceIDOut = strdup([referenceID UTF8String]);
+		}
+		*resolvedOut = resolved ? 1 : 0;
 	}
 }
 
@@ -1265,11 +1295,15 @@ int NeruSetReferenceKeyboardLayout(const char *inputSourceID) {
 		}
 	}
 
+	initializeKeyMaps();
+
+	[gKeymapLock lock];
+	gRequestedInputSourceID = [trimmedInputSourceID copy];
+	[gKeymapLock unlock];
+
 	__block BOOL configuredResolved = YES;
 
 	void (^applyReferenceLayout)(void) = ^{
-		initializeKeyMaps();
-
 		[gKeymapLock lock];
 		gConfiguredInputSourceID = [trimmedInputSourceID copy];
 		clearResolvedReferenceInputSourceLocked();
 
@@ -152,18 +152,27 @@ func TestKeyboardLayouts_ListsTheEnabledLayoutsAndTheReference(t *testing.T) {
 // the main queue stalls. Resolving the layout calls TIS, which must run on the
 // main thread, so the apply waits in the queue and runs once the main thread
 // is free. The call returns true meanwhile, because a layout not yet applied
-// has not failed to resolve. An ID no layout has makes the apply visible on
-// any machine, since it flips the unmatched flag KeyboardLayouts reports.
+// has not failed to resolve. KeyboardLayouts reports the queued layout as not
+// unmatched too. The previous layout's outcome would fail doctor for a valid
+// replacement, and an outcome for the new one would mean TIS ran off the main
+// thread. An ID no layout has makes either mistake visible on any machine,
+// since it flips the unmatched flag KeyboardLayouts reports.
 func TestSetReferenceKeyboardLayout_LeavesTheApplyQueuedWhenTheMainQueueIsBlocked(t *testing.T) {
 	const missingLayout = "com.example.keylayout.NoSuchLayout"
 
+	_, enabledLayout, _ := darwin.KeyboardLayouts()
+	if enabledLayout == "" {
+		t.Fatal("KeyboardLayouts named no reference layout")
+	}
+
 	tests := []struct {
 		name  string
 		prior string
 		next  string
 	}{
 		{name: "missing layout after auto", prior: "", next: missingLayout},
 		{name: "auto after missing layout", prior: missingLayout, next: ""},
+		{name: "enabled layout after missing layout", prior: missingLayout, next: enabledLayout},
 	}
 
 	for _, test := range tests {
@@ -172,9 +181,8 @@ func TestSetReferenceKeyboardLayout_LeavesTheApplyQueuedWhenTheMainQueueIsBlocke
 
 			darwin.SetReferenceKeyboardLayout(test.prior)
 
-			_, _, priorUnmatched := darwin.KeyboardLayouts()
-			if priorUnmatched != (test.prior != "") {
-				t.Fatalf("unmatched is %v after setting %q", priorUnmatched, test.prior)
+			if _, _, unmatched := darwin.KeyboardLayouts(); unmatched != (test.prior == missingLayout) {
+				t.Fatalf("unmatched is %v after setting %q", unmatched, test.prior)
 			}
 
 			release := darwin.BlockMainQueueForTesting()
@@ -194,24 +202,99 @@ func TestSetReferenceKeyboardLayout_LeavesTheApplyQueuedWhenTheMainQueueIsBlocke
 				t.Fatalf("SetReferenceKeyboardLayout waited %v for the blocked main queue", elapsed)
 			}
 
-			if _, _, unmatched := darwin.KeyboardLayouts(); unmatched != priorUnmatched {
-				t.Fatal("layout was applied off the main thread while the main queue was blocked")
+			if _, _, unmatched := darwin.KeyboardLayouts(); unmatched {
+				t.Fatal("KeyboardLayouts reported a layout still queued as unmatched")
 			}
 
 			release()
 
+			// A read that lists layouts ran on the main queue after the apply
+			// queued before it, so its unmatched flag is the applied outcome.
 			deadline := time.Now().Add(5 * time.Second)
 			for {
-				if _, _, unmatched := darwin.KeyboardLayouts(); unmatched != priorUnmatched {
+				names, _, unmatched := darwin.KeyboardLayouts()
+				if len(names) != 0 {
+					if want := test.next == missingLayout; unmatched != want {
+						t.Fatalf(
+							"unmatched is %v after %q applied, want %v",
+							unmatched,
+							test.next,
+							want,
+						)
+					}
+
 					return
 				}
 
 				if time.Now().After(deadline) {
-					t.Fatal("queued layout was never applied after the main queue drained")
+					t.Fatal("KeyboardLayouts read nothing after the main queue was released")
 				}
 
 				time.Sleep(50 * time.Millisecond)
 			}
 		})
 	}
 }
+
+// TestKeyboardLayouts_ReadsNothingOffTheMainThreadWhenTheMainQueueIsBlocked
+// pins that a caller off the main thread never reads the layouts through TIS
+// itself, which must run on the main thread. neru doctor and the health check
+// call it from the IPC goroutine. While the main queue is blocked it returns no
+// names and no reference, which doctor shows as not read yet. The unmatched
+// flag is the one the resolver last recorded. Only a TIS call produces the
+// names, so an empty list shows none ran here. Once the test releases the
+// queue, KeyboardLayouts reads the layouts again.
+func TestKeyboardLayouts_ReadsNothingOffTheMainThreadWhenTheMainQueueIsBlocked(t *testing.T) {
+	_, _, wantUnmatched := darwin.KeyboardLayouts()
+
+	release := darwin.BlockMainQueueForTesting()
+	t.Cleanup(release)
+
+	type layouts struct {
+		names     []string
+		reference string
+		unmatched bool
+	}
+
+	result := make(chan layouts, 1)
+
+	go func() {
+		names, reference, unmatched := darwin.KeyboardLayouts()
+		result <- layouts{names: names, reference: reference, unmatched: unmatched}
+	}()
+
+	var blocked layouts
+
+	select {
+	case blocked = <-result:
+	case <-time.After(2 * time.Second):
+		t.Fatal("KeyboardLayouts waited for the blocked main queue")
+	}
+
+	if len(blocked.names) != 0 || blocked.reference != "" {
+		t.Fatalf(
+			"KeyboardLayouts read %v and %q off the main thread",
+			blocked.names,
+			blocked.reference,
+		)
+	}
+
+	if blocked.unmatched != wantUnmatched {
+		t.Fatalf(
+			"unmatched is %v while the main queue is blocked, want %v",
+			blocked.unmatched,
+			wantUnmatched,
+		)
+	}
+
+	release()
+
+	names, reference, _ := darwin.KeyboardLayouts()
+	if len(names) == 0 {
+		t.Fatal("KeyboardLayouts read nothing after the main queue was released")
+	}
+
+	if !slices.Contains(names, reference) {
+		t.Fatalf("reference layout %q is not among the enabled layouts %v", reference, names)
+	}
+}
@@ -282,6 +282,12 @@ func capabilityStatusSupported(status string) bool {
 // layout kb_layout_to_use names, which is a typo neru doctor should catch.
 func keyboardLayoutsStatus(layouts ports.KeyboardLayouts, requested string) (string, bool) {
 	if len(layouts.Names) == 0 {
+		// The platform may know the layout is missing without listing any,
+		// as macOS does when its main thread is too busy to list them.
+		if requested != "" && layouts.Unmatched {
+			return "not found: " + requested + " (layouts not read)", false
+		}
+
 		// Doctor cannot check a forced layout here, so it does not call it ok.
 		// It does not fail on it either, because the keymap may still arrive.
 		if requested != "" {