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

docs/DESIGN.md

@@ -612,7 +612,7 @@ adopting it would require per-slot saved states and a careful look at DHCP lease
 reuse — not a drop-in optimization.
 
 **16. macOS 15+ Local Network privacy can block host→guest connections, and
-there is no reliable way to grant it interactively here.** Per
+granting it interactively takes deliberate work.** Per
 [TN3179](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)
 it is not TCC — the check is a Network Extension packet filter, so it is absent
 from `TCC.db`, cannot be queried, cannot be reset, and it "uses your main
@@ -628,8 +628,30 @@ rebuild.
 (`com.apple.network.local-network`, keys `AllowedEthernetLocalNetworkAddresses`
 and `AllowedWiFiLocalNetworkAddresses`), which is keyed on the network rather
 than the app and is read at boot — so it needs a reboot, not a service restart.
-`Doctor.checkLocalNetwork` reads those keys and requires coverage of
+`LocalNetworkPolicy` owns the arithmetic and requires coverage of
 `192.168.64.0/18`, not a single /24, because the NAT subnet is chosen at runtime
-and slides to the next free /24. `SSHExec.localNetworkHint` appends the same
-guidance to connection failures, since errno 65 gives the operator nothing to go
-on by itself.
+and slides to the next free /24; `Doctor.localNetworkNote` and
+`SSHExec.localNetworkHint` both report against it, since errno 65 gives the
+operator nothing to go on by itself.
+
+→ *Consequence:* both routes are commands rather than documentation.
+`permissions grant` writes the allowlist and verifies it read back (`sudo
+defaults write` lands in root's or the invoking user's preferences depending on
+whether sudo preserved `HOME`, so where it went is not assumable).
+`permissions grant --method prompt` addresses the attribution problem head-on:
+launching the installed bundle through LaunchServices (`open -n -b …`) makes the
+app its **own** responsible process, so the prompt and the Settings row belong to
+it rather than to Terminal — and because the LaunchAgent runs the same signed
+identity, the grant carries. That only became worth building once the bundle was
+Developer ID signed; under ad-hoc signing the UUID churn withdraws it on the next
+rebuild, which is why `permissions status` reports code identity alongside the
+allowlist.
+
+→ *Consequence:* the prompt route is best-effort and says so. Observed on a host
+where the decision was already recorded: `UserEventAgent` resolves the flow to
+the bundle ID on every attempt — so the attribution works — but presents no
+alert, because macOS asks once per app identity and then answers from that
+record, silently, forever. There is no supported reset. So `--method prompt`
+verifies by *probing* rather than by trusting the launch, and on a denial says
+plainly that it did not take and points at the allowlist, which is not subject
+to the per-app check at all. The allowlist stays the recommendation.