Merge nucleic/vivid-glass-urchin-xoym into main

docs/setup.md

@@ -461,6 +461,13 @@ gitea-macos-runner permissions status   # what is configured, and what to do abo
 gitea-macos-runner permissions grant    # configure it
 ```
 
+One asymmetry to know about before reading any of this output: the allowlist is written as root and
+lands in `/var/root/Library/Preferences/`, which is mode 700. An ordinary login cannot read it back —
+so `permissions status` and `doctor` report `no allowlist visible`, which means *not visible*, not
+*not set*. `sudo gitea-macos-runner permissions status` answers definitively. `permissions grant`
+does not have this problem: it re-reads the file with the sudo credentials it just used, so it
+confirms its own write.
+
 `grant` has two methods. Both are one command; neither needs anything pasted.
 
 **`--method allowlist` (the default) is what a CI host wants.** It writes a subnet allowlist — the
@@ -478,7 +485,8 @@ configured while silently blocking every guest — and the failure surfaces as `
 (errno 65) on the SSH connection, not as a permission error. `192.168.64.0/18` spans
 `192.168.64.0`–`192.168.127.255`, which is the narrowest entry that covers the drift. `doctor`
 reports `local network access` as a **pass** once it sees an allowlist covering that span, and as a
-**warning** when an allowlist exists but does not. Both keys are documented by Apple in
+**warning** when an allowlist exists but does not — but only when it can see it at all, which means
+running under `sudo` or straight after a grant. Both keys are documented by Apple in
 [TN3179](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy).
 
 **`--method prompt` takes effect immediately, with no reboot**, and is the better choice on a Mac