macOS updates replace PV's pf.conf reference and break .test routing

[munezaclovis]

Summary

A macOS point update can replace /etc/pf.conf with Apple's stock template and remove PV's managed rdr-anchor / load anchor reference. The separate PV anchor file may remain on disk, but without the main-ruleset reference it is never evaluated. All normal http://*.test and https://*.test URLs then stop reaching the unprivileged Gateway.

This is distinct from #300's launchd throttle. It was the root cause of the later live ai.test outage documented in the incident investigation.

Verified incident

Environment:

• macOS 26.5.1 → 26.5.2 (25F84)
• PV 0.2.2
• Gateway backend listeners: 127.0.0.1:48080 and 127.0.0.1:48443

Evidence:

• macOS 26.5.2 installed July 24 at 12:47:58 EDT.
• Apple's package receipt identifies /private/etc/pf.conf as owned by com.apple.files.data-template version 26.5.2 with install time July 24 at 12:54:47 EDT.
• Before repair, the live pf.conf had Apple's stock-template contents and that exact ctime.
• /etc/pf.anchors/com.prvious.pv still contained the correct 80 → 48080 and 443 → 48443 rules.
• ai.test resolved correctly and the Gateway/backend were healthy, but ports 80/443 refused connections.
• Bypassing the low-port path and connecting directly to 48443 returned HTTP 200.
• Running pv ports:install restored the two main-ruleset references, reloaded PF, and immediately restored HTTP 200 over IPv4.

Design constraint

PV deliberately uses PF for low-port routing (DESIGN.md). The background daemon may detect privileged drift but must not prompt or mutate privileged system configuration (DESIGN.md).

Apple also documents PF as an unsupported product API and warns that its rules can conflict with system services or other software: TN3165: Packet Filter is not API.

The supported recovery strategy therefore needs an explicit design decision; this issue should not silently introduce background privileged repair.

Expected behavior

A supported macOS update must not leave users with an unexplained all-Projects outage. PV should reliably detect the missing system reference, make the cause and focused foreground repair discoverable, and verify that routing is restored after the repair. Any longer-term replacement for PF must be decided explicitly.

Acceptance criteria

• Document the supported post-macOS-update recovery strategy in DESIGN.md.
• Add integration coverage that replaces a current PV-managed pf.conf with the stock Apple form while leaving the PV anchor file present.
• Detect that state as privileged routing drift rather than Gateway/backend failure.
• Surface a focused pv ports:install recovery path through relevant PV diagnostics/commands without silently prompting from the daemon.
• Preserve non-PV pf.conf content and continue refusing unsafe ownership conflicts.
• Verify the foreground repair restores the main-ruleset reference and active low-port routing.
• Keep pv update incurs a 10-second launchd throttle after switching app binary #300's launchd binary-switch behavior out of scope.

Related

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

[pullfrog]

This is actionable. The safe foreground repair already exists, but the daemon’s Gateway readiness fallback can mistake a prepared anchor for an active redirect after macOS replaces /etc/pf.conf, causing the privileged routing outage to appear as a Gateway failure.

Plan

1. Document the supported recovery contract in DESIGN.md. State that macOS updates may replace /etc/pf.conf; PV detects the missing managed reference read-only; the daemon never prompts or repairs privileged configuration; and the supported foreground recovery is pv ports:install. Keep PF replacement and pv update incurs a 10-second launchd throttle after switching app binary #300’s launchd behavior out of scope.

2. Separate confirmed redirect absence from inspection failure in Gateway readiness. Refine crates/daemon/src/gateway.rs so a successful PF inspection reporting no matching active redirects uses the high backend ports for Gateway health, even when the prepared anchor remains. Preserve the prepared-config fallback only when active PF inspection is unavailable, avoiding the existing macOS hang risk when redirects may actually be loaded. Add focused tests for active, confirmed-missing, unavailable-with-current-prepared-config, and no-prepared-config cases. This keeps the Gateway healthy while diagnostics identify the privileged routing drift.

3. Make the drift and repair path explicit in foreground diagnostics. Add CLI integration/snapshot coverage for the exact state: prepared config current, system anchor current, stock Apple-style /etc/pf.conf with no PV reference, and inactive redirects. Ensure pv status reports ports as repair-required/prepared-only without attributing the outage to the Gateway, while pv doctor and pv ports:status identify the missing system pf.conf reference and direct the user to pv ports:install. These paths remain read-only and never invoke sudo.

4. Add a privileged macOS regression scenario. Extend scripts/ci/privileged-macos-rc.sh to capture the runner’s pre-setup stock /etc/pf.conf, install PV, restore that stock file while leaving /etc/pf.anchors/com.prvious.pv present, and reload PF. Assert diagnostics identify port-routing drift, run pv ports:install, then verify the managed rdr-anchor/load anchor references, active redirects, and HTTP/HTTPS .test routing are restored. Compare non-PV content against the captured stock file after removing only PV-managed lines, and retain coverage that unowned PV directives remain a conflict rather than being overwritten.

5. Verify the change. Run the targeted daemon, CLI status/doctor/ports, platform PF, and release workflow-default tests; run shellcheck scripts/ci/privileged-macos-rc.sh; then run formatting and workspace Clippy. The privileged routing restoration itself is verified by the macOS RC workflow.

Task list (3/3 completed)

• Read issue details, repository guidance, and relevant learnings
• Trace pf.conf installation, repair, and macOS update behavior in code and tests
• Draft and publish an actionable implementation plan

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