pv status and pv doctor report healthy PF redirects as unreadable without sudo

[munezaclovis]

Summary

After a successful pv ports:install, normal pv status and pv doctor can still report the active PF redirects as unreadable and fail overall health because inspecting /dev/pf requires root privileges.

At the same time, pv ports:status reports the prepared/system files as current but does not inspect loaded rules. The three diagnostic surfaces therefore disagree on a working machine.

Verified reproduction

After the user repaired the incident with pv ports:install:

• default and forced-IPv4 https://ai.test returned HTTP 200 through 127.0.0.1:443;
• direct Gateway HTTPS on 48443 also returned 200;
• pv ports:status reported every prepared/system PF file as current;
• pv status --json reported "ports":"unreadable";
• pv doctor failed with active pf redirects could not be inspected and suggested running pv ports:install again.

The host behavior is deterministic:

$ /sbin/pfctl -s nat
pfctl: /dev/pf: Permission denied

$ sudo -n /sbin/pfctl -s nat
sudo: a password is required

$ ls -l /dev/pf
crw-------  root wheel  /dev/pf

Current code paths

• pv status invokes active PF inspection after file state is current: status.rs.
• Active inspection tries pfctl, then non-interactive sudo -n: pf.rs.
• An inspection error becomes ports: unreadable and a system failure: status.rs.
• Doctor fails the same state and recommends reinstalling: doctor.rs.
• pv ports:status inspects only files and always exits success: ports.rs.

Expected behavior

Read-only diagnostics should provide a reliable, non-interactive health classification without depending on a warm sudo credential. Lack of permission to enumerate PF rules must not make a verified-working route look broken or recommend repeating an already-successful install.

The exact fallback mechanism requires a design decision; status/doctor must remain non-mutating and must not prompt for authentication.

Acceptance criteria

• pv status, pv doctor, and pv ports:status agree about healthy, inactive, stale, and genuinely uninspectable routing states.
• A normal user with no cached sudo authentication can obtain useful status without a prompt.
• A working end-to-end low-port route is not reported as failed solely because /dev/pf is unreadable.
• An inactive/missing route is still reported as repair-required with pv ports:install.
• JSON output distinguishes verified health from any intentionally unknown/uninspectable state.
• Add coverage for permission-denied PF inspection with both working and broken low-port routing.
• Keep mutating PF operations foreground-only.

Related

• pv update incurs a 10-second launchd throttle after switching app binary #300
• Full incident evidence

[pullfrog]

Assessment

This is actionable. The owned PF files are readable and sufficient to detect missing, stale, and conflicting configuration, but they cannot prove that rules are loaded. Active-rule inspection in crates/platform/src/pf.rs requires /dev/pf; when both direct pfctl and sudo -n fail, status.rs and doctor.rs treat the inspection failure as broken routing while ports.rs never inspects active behavior. DESIGN.md requires read-only PF diagnostics but does not define the unprivileged fallback, so that contract should be made explicit before changing classification.

The minimal reliable fallback is a data-path check rather than assuming current files imply current rules. When rule enumeration is unavailable, first probe the expected low-port Gateway route. A successful public-port probe verifies routing. If it fails, probe the corresponding high Gateway endpoint: high-port success isolates the failure to low-port routing and warrants pv ports:install; failure at both endpoints leaves PF genuinely unknown because diagnostics cannot distinguish an unloaded redirect from a down Gateway. That unknown state should not itself recommend reinstalling PF, while the existing Gateway diagnostics report the underlying availability problem.

Plan

1. Update the low-port diagnostics contract in DESIGN.md with a shared state model: file drift remains repair-required; matching enumerated rules are current; a successful end-to-end low-port probe is separately identified as route-verified; a failed low-port probe with a healthy matching high-port endpoint is inactive; and unavailable rule inspection plus inconclusive probes is unknown, non-mutating, and does not carry a false repair command.
2. Add a bounded, read-only Gateway route probe behind the CLI Environment seam, using the expected PF destination ports and an existing configured Project hostname/TLS trust when available. Probe the public endpoint first, then the matching high endpoint only to isolate public-route failure; never prompt, invoke interactive sudo, or mutate PF/Gateway state.
3. Centralize PF health classification in the CLI and use it from pv ports:status, pv status, and pv doctor. Preserve exact active-rule inspection when available, add explicit verified/unknown output labels so status --json does not conflate evidence levels, make inactive routing fail with pv ports:install, and render inconclusive inspection as a warning/unknown state rather than a PF failure.
4. Extend the existing snapshot-style CLI integration tests in crates/cli/tests/ports.rs, status.rs, and doctor.rs for permission-denied inspection with a working public route, a broken public route with a healthy high-port Gateway, and inconclusive public/high-port probes. Assert consistent labels, exit behavior, repair guidance, JSON classification, no authentication prompt, and no filesystem/state mutation; retain coverage for directly enumerated current and inactive rules.
5. Verify with cargo nextest run -p cli --test ports --test status --test doctor --locked, then cargo fmt --all --check and cargo clippy --workspace --all-targets --all-features --locked -- -D warnings.

Task list (3/3 completed)

• Read issue discussion, repository guidance, and diagnostics learnings
• Trace PF redirect health checks and relevant integration tests
• Determine actionability and publish an implementation plan or analysis

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}