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

docs/troubleshooting.md

@@ -108,10 +108,14 @@ prompt**: a LaunchAgent that was never granted permission (or was denied) cannot
 2. No entry at all: check and fix the permission.
 
    ```sh
-   gitea-macos-runner permissions status
-   gitea-macos-runner permissions grant     # then reboot when it offers
+   sudo gitea-macos-runner permissions status   # sudo: the allowlist lives in root's preferences
+   gitea-macos-runner permissions grant         # then reboot when it offers
    ```
 
+   Without `sudo`, `status` reports `no allowlist visible` on every host — it is written as root into
+   `/var/root/Library/Preferences/`, which an ordinary login cannot read. That is not evidence the
+   grant is missing. `grant` itself does not have the problem: it verifies its own write.
+
    `grant` pre-authorizes the VM subnets and offers to reboot, which is required — the allowlist is
    read at boot. It grants all of RFC 1918 by default; `--subnet` narrows it, but nothing narrower
    than `192.168.64.0/18` is safe, because the NAT subnet is chosen at runtime and slides to the next