docs: fold Craig's cj comments into the network module spec

Set the notification format (title "Networking", label then string), add VPN kill-switch detection and correction off the deferred-vpn branch, and make the no-terminal rule absolute for the module UX. Filed a VERIFY for the one tension: the dead-GUI console-recovery path versus no terminals.

1 files changed, 55 insertions, 4 deletions

diff --git a/docs/design/2026-06-29-waybar-network-module-spec.org b/docs/design/2026-06-29-waybar-network-module-spec.org
index 298ebe6..0af9342 100644
--- a/docs/design/2026-06-29-waybar-network-module-spec.org
+++ b/docs/design/2026-06-29-waybar-network-module-spec.org
@@ -1,5 +1,5 @@
 #+TITLE: Waybar Network Module — Design Spec
-#+AUTHOR: Craig Jennings & Claude
+#+AUTHOR: Craig Jennings
 #+DATE: 2026-06-29
 
 * Status
@@ -383,7 +383,8 @@ there's one source of truth.
 Per-surface rendering of the canonical string:
 - *Indicator* — the matching glyph + CSS class; the string is the tooltip
   (untruncated).
-- *Notification* (=notify=) — title = the failure label, body = the string.
+- *Notification* (=notify=) — title = "Networking"; body = the failure label on
+  its own line, then the canonical string.
 - *CLI* — the string on stderr; =--json= puts it in =error.message= with the
   evidence in =error.detail= and a stable =error.code=.
 - *Panel* — the string as the section banner, with the diagnostic step's evidence
@@ -435,6 +436,31 @@ portal tokens never).
 - *DNS override cleanup unverified* — "Couldn't confirm DNS was restored after the
   test" → evidence: iface, attempted revert → revert DNS manually
   (=resolvectl revert <iface>=).
+- *VPN kill-switch blocking* — "A VPN kill-switch is blocking all traffic, and the
+  VPN itself is down" → evidence: a block artifact present with no tunnel up → bring
+  the VPN back, or clear the kill-switch (the exact root command surfaced, not
+  auto-run).
+
+*VPN kill-switch detection + correction.* A kill-switch blocks all non-VPN egress when
+the tunnel drops, so the link looks up (wifi, IP, gateway) but nothing reaches the
+internet. This extends the =deferred-vpn= branch: when a VPN is active and the probe
+fails, run a rootless cascade to tell a working tunnel from a kill-switch that's
+blocking because the tunnel is down —
+- =ip rule= for wg-quick's =not fwmark 0xca6c= + =suppress_prefixlength 0= (and the
+  PostUp =REJECT ! -o %i= rule that makes it leak-proof);
+- =wg show= for an up tunnel interface;
+- =nmcli connection show= for Proton's =pvpn-killswitch= / =pvpn-ipv6leak-protection=
+  (device =pvpnksintrf0=);
+- =nft list ruleset= / =iptables -S OUTPUT= for a drop/reject table (=killswitch=,
+  =protonvpn=, =oifname != "wg0" ... drop=);
+- =nmcli -f connection.zone= for a firewalld =drop= zone.
+Classify *kill-switch-blocking* only when a block artifact exists AND no tunnel
+interface is up — that's what distinguishes it from a healthy VPN. Correction is tiered
+by artifact and every option needs root, so surface the exact command rather than
+auto-running it: =wg-quick down <iface>=, =nmcli connection delete pvpn-killswitch
+pvpn-ipv6leak-protection=, =nft delete table inet killswitch=, or =nmcli connection
+modify <con> connection.zone ''=. (Sits alongside the Phase 5 VPN work; detection can
+land earlier since =deferred-vpn= already exists.)
 
 Each message names whether the system was left unchanged, partially changed (with
 what), or fully changed, so the user knows the residue.
@@ -1067,8 +1093,12 @@ a *coverage-gap pass*, not just a percentage:
 V2 redesign decisions (Craig, 2026-06-30):
 
 15. *No terminals anywhere in the module* — =net-popup= is removed; every action and
-    result renders in the panel. Reverses the part of decision 11 that ran privileged
-    repairs in a terminal "so sudo/polkit can prompt".
+    result renders in the panel. No terminal is ever used to report information to the
+    user or to collect input from them: every prompt, confirmation, repair stream, and
+    result lives in the panel UI (Craig, cj, 2026-06-30). Reverses the part of decision
+    11 that ran privileged repairs in a terminal "so sudo/polkit can prompt". (Unrelated
+    to the doctor's "terminal states" — that word means a final outcome, not a tty. The
+    one open question is the dead-GUI console-recovery path; see the VERIFY in todo.org.)
 16. *Passwordless privileged path* — a root-owned helper + a narrow NOPASSWD sudoers
     rule scoped to it, archsetup-installed, run as =sudo <helper> <verb>=. This gates
     decision 15 (a worker thread can't prompt). Absorbs the earlier DoT-toggle
@@ -2036,3 +2066,24 @@ is already failing.
 - *Artifacts:* Findings 32-40 completed in place with dispositions; the modify reason
   on the speed-test finding. New "V2 panel UX" section under Panel. todo.org redesign
   task updated to point the V2 build at the dispositioned design.
+
+** 2026-07-01 Wed @ 10:43:18 -0400 — Claude Code (archsetup) — responder (cj comments)
+
+- *What changed:* Folded in Craig's three cj comments from his review. (1) Notification
+  rendering: title = "Networking", body = the failure label on its own line then the
+  canonical string. (2) VPN kill-switch: added a "kill-switch blocking" failure state
+  plus a detection-and-correction strategy off the =deferred-vpn= branch (rootless
+  cascade over =ip rule= fwmark 0xca6c / =wg show= / Proton =pvpn-*= NM connections /
+  =nft=/=iptables= drop tables / firewalld =drop= zone; classify blocking only when a
+  block artifact exists AND no tunnel is up; correction surfaces the exact root command
+  per artifact). (3) Terminals: strengthened decision 15 to "no terminal ever reports
+  to or collects input from the user", disambiguated from the doctor's "terminal
+  states" wording.
+- *Why:* Craig's review annotations. The kill-switch closes a real gap in the
+  VPN-routed classification; the terminal directive makes the no-terminal rule
+  absolute for the module UX.
+- *Artifacts:* Three cj blocks removed. VPN research subagent cited wg-quick man page,
+  Pro Custodibus, System76/Proton killswitch docs, and local =doctor.py:42= /
+  =classify.py:60= / =USNY.conf:15=. One open tension filed as a VERIFY in todo.org:
+  the dead-GUI console-recovery path (=make online= from a TTY) vs the no-terminal
+  directive.