4.5 KiB
Observe system proxy differences and repair explicitly
Status: accepted on 2026-10-01; implemented in commit 4a0a72c for Issue #73. Hostless tests and fixture-based card rendering were verified; real-host system proxy writes, approval, and observation notifications were not validated.
Automatic reapplication after passive network changes can overwrite another application's deliberate proxy settings. Replace that policy with read-only observation of current semantic differences and an explicit repair action, while retaining automatic application after the user saves relevant settings and automatic suspension/recovery when the background runtime or the current mode's exit becomes unavailable/available. This balances user control over external edits with avoiding an unusable local proxy endpoint.
The agent and system proxy switches express persisted intent, independent of runtime health and observed configuration. Failure, external changes, and suspension do not turn either intent off. Explicitly turning off the agent still cascades an enabled system proxy intent to off, clears settings, and then stops the listeners.
Enabling system proxy applies the desired values to all services in the active network location once the runtime is ready. Saving app settings that change desired proxy values also applies automatically when enabled and usable. Passive proxy, service, location, and network-path events only re-read settings. A healthy GUI launch only checks differences; an enabled but unusable runtime at launch requests cleanup. A subsequent unusable-to-usable transition applies automatically while intent remains enabled. Ordinary loss of network connectivity alone is not runtime failure; rule/global modes require an available active target, while direct mode does not.
Both explicit switch-off and enabled-state runtime/exit failure request the existing unconditional cleanup across all network locations and services. Cleanup removes the complete proxy dictionaries, regardless of their source. Successful health-driven cleanup suspends system proxy use without changing intent; failed cleanup remains a visible failure. Recovery and app-setting application can overwrite external values, including changes made while suspended. A failed operation is not automatically retried; a new health-recovery event remains an independent automatic application trigger.
Repair re-reads the current location and applies only to currently differing services, including disconnected services. Compare only app-managed fields, ignore equivalent writes and unmodeled fields, and preserve unmodeled fields during apply/repair. This narrows repair scope; other application triggers retain all-service scope in the active location. There is no prior-value restoration, exclusive ownership claim, or source attribution. Notices disappear as services become consistent and distinguish changed settings from services that have not received the current settings.
Observation and health-driven system proxy actions run only while the GUI process is running, including when its workspace window is closed. This decision does not add observation to the background agent or privileged helper. Quitting the GUI leaves those actions unavailable until the next launch.
Operation results and actionable blockers are separate presentation facts: helper approval must remain visible alongside apply, repair, or cleanup failure. Approval resumes an initial enable request that has not executed, but does not retry an already failed operation. After approval, show the corresponding repair or cleanup retry action. Read failures offer a read-only check action and cannot establish that settings are applied.
This decision supersedes ADR-0019's external-change suppression and passive reapplication and ADR-0020's network/launch application, health-gate preservation, cleanup-only-on-intent-off, and all-service scope for repair. ADR-0020's privileged helper boundary, registration, typed configuration, field preservation, and unconditional cleanup mechanism remain. The accepted UI states, copy, and review scenarios are recorded in System proxy runtime control.
ADR-0049 narrows steady-state runtime failure observation to Agent-confirmed deployment failures, with a five-second read-only poll. It removes periodic inbound connections and independent receipt/PID failure inference; explicit deployment readiness and successful convergence remain responsible for recovery.