feat(helper)!: wire reconciliation into startup and apply

Apply chooses between the helper and the administrator-password prompt
before any bytes reach the helper, from reconciled service state, and
reports every refusal instead of substituting a prompt. The permission
row, Grant and Disable all derive from one reconciliation run.

- delete the App Management bypass: skipping the helper for applies that
  touch managed app bundles was a silent password substitution while an
  enabled registration could still admit sync-agent work
- delete the status-probe admission gate and the pre-dispatch error
  fallback, both of which could select the password path after an
  exchange had been attempted
- offer Disable in every state, so a registration waiting for approval
  can be removed
- drop the folded service status readout; its responding flag was the
  last thing an admission check could be re-derived from

BREAKING CHANGE: helperRegister and helperUnregister are replaced by
helperGrant and helperDisable; helperStatus returns the reconciliation
report.

Author: alex-sparus

apps/native/src-tauri/src/commands/permissions.rs

@@ -26,8 +26,9 @@ pub async fn refresh_permissions(app: AppHandle) -> Result<(), String> {
 /// For manual permissions (full-disk), this opens System Settings.
 #[tauri::command]
 pub async fn permissions_request(
+    app: AppHandle,
     permission_id: String,
 ) -> Result<shared_types::Permission, String> {
-    permissions::request_permission(&permission_id)
+    permissions::request_permission(&app, &permission_id)
         .map_err(|e| capture_err("permissions_request", e))
 }

apps/native/src-tauri/src/main.rs

@@ -726,6 +726,21 @@ fn run_gui_mode(
                 }
             });
 
+            // Reconcile the installed privileged helper with this build. This is
+            // the only actor in an upgrade: a Finder replacement and the
+            // updater's relaunch both converge here, on the new GUI's ordinary
+            // startup, and the old one prepares nothing.
+            //
+            // Off the main thread, and off the startup path: the run makes
+            // ServiceManagement calls *on* the main queue and awaits them, and it
+            // waits — legitimately, for as long as it takes — on an activation a
+            // previous build's helper is still running. It reports through the
+            // permission row; nothing here waits for it.
+            let helper_handle = handle.clone();
+            tauri::async_runtime::spawn_blocking(move || {
+                system::helper_permission::observe(&helper_handle);
+            });
+
             // Background initialize the nix-darwin docs index once at startup for fast option-shape lookup.
             let docs_handle = handle.clone();
             tauri::async_runtime::spawn_blocking(move || {

apps/native/src-tauri/src/orpc/darwin.rs

@@ -3,14 +3,14 @@
 use super::{OrpcCtx, helpers::internal_err};
 use crate::commands::{apply, evolve, rollback};
 use crate::privileged_helper::{
-    protocol::{HelperServiceStatus, SyncAgentLaunchConfig},
-    service,
+    protocol::SyncAgentLaunchConfig,
     sync_agent::{self, SyncAgentStatus},
 };
 use crate::shared_types::{
     AppManagementCheckResult, BuildCheckResult, EtcClobberCheckResult, EvolveCancelResult,
     OkResult, RebuildStatus, RollbackResult,
 };
+use crate::system::helper_permission;
 use orpc::*;
 use serde::{Deserialize, Serialize};
 use specta::Type;
@@ -68,6 +68,28 @@ struct InstallSyncAgentInput {
     config: Option<SyncAgentLaunchConfig>,
 }
 
+/// What one reconciliation run found, for a client that only has to display it:
+/// whether the helper is installed and answering at this build, and the sentence
+/// that says what else is true.
+#[derive(Debug, Deserialize, Serialize, Type)]
+#[serde(rename_all = "camelCase")]
+struct HelperReport {
+    at_this_build: bool,
+    detail: String,
+}
+
+impl HelperReport {
+    fn of(report: &crate::privileged_helper::reconcile::Reconciled) -> Self {
+        Self {
+            at_this_build: matches!(
+                report,
+                crate::privileged_helper::reconcile::Reconciled::AtThisBuild
+            ),
+            detail: helper_permission::describe(report),
+        }
+    }
+}
+
 #[derive(Debug, Deserialize, Serialize, Type)]
 #[serde(rename_all = "camelCase")]
 struct AdoptManualChangesResult {
@@ -193,16 +215,25 @@ async fn rebuild_status(ctx: OrpcCtx, _input: ()) -> Result<RebuildStatus, ORPCE
         .map_err(|error| internal_err("darwin.rebuildStatus", error))
 }
 
-async fn helper_status(_ctx: OrpcCtx, _input: ()) -> Result<HelperServiceStatus, ORPCError> {
-    Ok(service::status())
+/// One run of the reconciliation function, reported. It decides nothing about
+/// the goal and never resolves the stored decision; it is the same run a status
+/// refresh makes. It can open Login Items in exactly one case — when it is the
+/// run that answers a Grant click that was told `Busy`.
+async fn helper_status(ctx: OrpcCtx, _input: ()) -> Result<HelperReport, ORPCError> {
+    Ok(HelperReport::of(&helper_permission::observe(&ctx.app)))
 }
 
-async fn helper_register(_ctx: OrpcCtx, _input: ()) -> Result<HelperServiceStatus, ORPCError> {
-    service::register().map_err(|error| internal_err("darwin.helperRegister", error))
+/// The explicit Grant action. Grant is the only action that may open Login
+/// Items; `permissions.request("privileged-helper")` is the same action reached
+/// from the permission row.
+async fn helper_grant(ctx: OrpcCtx, _input: ()) -> Result<HelperReport, ORPCError> {
+    Ok(HelperReport::of(&helper_permission::grant(&ctx.app)))
 }
 
-async fn helper_unregister(_ctx: OrpcCtx, _input: ()) -> Result<HelperServiceStatus, ORPCError> {
-    service::unregister().map_err(|error| internal_err("darwin.helperUnregister", error))
+/// The explicit Disable action: retire a running helper, unregister it, and
+/// register nothing. No later automatic run overrides it.
+async fn helper_disable(ctx: OrpcCtx, _input: ()) -> Result<HelperReport, ORPCError> {
+    Ok(HelperReport::of(&helper_permission::disable(&ctx.app)))
 }
 
 async fn sync_agent_status(_ctx: OrpcCtx, _input: ()) -> Result<SyncAgentStatus, ORPCError> {
@@ -278,14 +309,14 @@ pub fn routes() -> Router<OrpcCtx> {
             .output(orpc_specta::specta::<RebuildStatus>())
             .handler(rebuild_status),
         "helperStatus" => os::<OrpcCtx>()
-            .output(orpc_specta::specta::<HelperServiceStatus>())
+            .output(orpc_specta::specta::<HelperReport>())
             .handler(helper_status),
-        "helperRegister" => os::<OrpcCtx>()
-            .output(orpc_specta::specta::<HelperServiceStatus>())
-            .handler(helper_register),
-        "helperUnregister" => os::<OrpcCtx>()
-            .output(orpc_specta::specta::<HelperServiceStatus>())
-            .handler(helper_unregister),
+        "helperGrant" => os::<OrpcCtx>()
+            .output(orpc_specta::specta::<HelperReport>())
+            .handler(helper_grant),
+        "helperDisable" => os::<OrpcCtx>()
+            .output(orpc_specta::specta::<HelperReport>())
+            .handler(helper_disable),
         "syncAgentStatus" => os::<OrpcCtx>()
             .output(orpc_specta::specta::<SyncAgentStatus>())
             .handler(sync_agent_status),

apps/native/src-tauri/src/orpc/permissions.rs

@@ -25,8 +25,8 @@ async fn refresh(ctx: OrpcCtx, _input: ()) -> Result<(), ORPCError> {
         .map_err(|e| internal_err("permissions.refresh", e))
 }
 
-async fn request(_ctx: OrpcCtx, input: RequestInput) -> Result<Permission, ORPCError> {
-    cmd::permissions_request(input.permission_id)
+async fn request(ctx: OrpcCtx, input: RequestInput) -> Result<Permission, ORPCError> {
+    cmd::permissions_request(ctx.app, input.permission_id)
         .await
         .map_err(|e| internal_err("permissions.request", e))
 }

apps/native/src-tauri/src/privileged_helper/client.rs

@@ -7,6 +7,14 @@ use std::os::unix::net::UnixStream;
 use std::time::Duration;
 
 const CLIENT_TIMEOUT: Duration = Duration::from_secs(30);
+/// The one generous bound in this client, and deliberately not one of the short
+/// leashes above: an activation legitimately runs for many minutes, so nothing
+/// shorter can be put here without turning ordinary long applies into lost
+/// results. Half an hour is the accepted ceiling. An activation still running
+/// when it expires is reported as an unknown outcome by an apply and as a
+/// deferral by the sync agent — neither compensates for it, and the activation
+/// itself keeps running. Do not reuse this on `Status` or `Retire`, and do not
+/// shorten it to match them.
 const ACTIVATION_TIMEOUT: Duration = Duration::from_secs(30 * 60);
 /// Status probes back the permissions UI; a wedged helper must not stall a
 /// permissions refresh, so they get a short leash instead of CLIENT_TIMEOUT.
@@ -82,6 +90,11 @@ pub enum AssessedExchange {
     Unidentified(String),
 }
 
+/// Whether the socket path exists. Diagnostic only — it proves nothing about a
+/// helper, which is why nothing in the app reads it: the sync agent's no-config
+/// mode prints it, and every decision comes from an authenticated exchange or
+/// from the absence window in `socket_probe`.
+#[allow(dead_code)] // Used by the sync agent binary this module is shared into.
 pub fn socket_available() -> bool {
     std::path::Path::new(HELPER_SOCKET_PATH).exists()
 }
@@ -205,13 +218,6 @@ fn exchange_on(
     })
 }
 
-/// Sends `Status`. GUI-only by protocol policy: the sync agent has no
-/// lifecycle role and the helper refuses every request from it but
-/// `TryActivate`.
-pub fn status() -> Result<HelperExchange, HelperClientError> {
-    exchange(&HelperRequest::Status, STATUS_PROBE_TIMEOUT)
-}
-
 /// Sends `Status`, keeping the peer assessment. Reconciliation's discovery
 /// exchange: it works against a helper of any build, and what it may do about
 /// one it cannot talk to depends on which way the assessment went.

apps/native/src-tauri/src/privileged_helper/mod.rs

@@ -9,10 +9,6 @@ pub mod client;
 pub mod helper_runtime;
 pub mod peer_auth;
 pub mod protocol;
-// Complete and unreachable from production: nothing calls the reconciliation
-// function yet. The change that wires it into startup, the grant and disable
-// actions, apply, and the updater removes this.
-#[allow(dead_code)]
 pub mod reconcile;
 pub mod root_activation;
 pub mod service;

apps/native/src-tauri/src/privileged_helper/protocol.rs

@@ -20,36 +20,6 @@ pub const HELPER_SOCKET_DIR: &str = "/var/run/nixmac";
 pub const BUILD_ID: &str = env!("NIXMAC_BUILD_ID");
 const DEFAULT_SYNC_AGENT_INTERVAL_SECONDS: u32 = 900;
 
-#[derive(Debug, Clone, Serialize, Deserialize, Type, PartialEq, Eq)]
-#[serde(rename_all = "camelCase")]
-pub struct HelperServiceStatus {
-    pub label: String,
-    pub available: bool,
-    pub registered: bool,
-    pub authorized: bool,
-    pub socket_available: bool,
-    /// The daemon answered an authenticated `Status` round-trip naming a
-    /// state: the client validated the daemon's signature and the daemon
-    /// accepted this client. A typed refusal or an unparseable reply never
-    /// sets this.
-    pub responding: bool,
-    pub detail: Option<String>,
-}
-
-impl HelperServiceStatus {
-    pub fn unavailable(detail: impl Into<String>) -> Self {
-        Self {
-            label: HELPER_LABEL.to_string(),
-            available: false,
-            registered: false,
-            authorized: false,
-            socket_available: false,
-            responding: false,
-            detail: Some(detail.into()),
-        }
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Requests.
 //

apps/native/src-tauri/src/privileged_helper/reconcile.rs

@@ -192,7 +192,8 @@ pub enum Stopped {
 // The sentences the permissions UI shows. Written here, next to the variants
 // they explain, because that is where this app already puts helper detail text
 // (`system::permissions` composes the same kind of string and the panel renders
-// it verbatim). No caller until the change that wires the report into the UI.
+// it verbatim). `system::helper_permission` is what turns one of these into the
+// row's detail.
 
 impl std::fmt::Display for Displacement {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
@@ -537,7 +538,11 @@ mod evidence {
     }
 }
 
-use evidence::{Committed, RetiredHelper};
+// `Committed` is nameable outside this module because the environment methods
+// that demand one are; minting one is not — `Committed::checked` stays visible
+// only in here, so the register step remains the only place one comes from.
+pub use evidence::Committed;
+use evidence::RetiredHelper;
 
 /// Which of the three rules authorizes one unregister.
 ///
@@ -584,8 +589,12 @@ pub enum PeerReply<C> {
 /// Everything a run observes or does, injected so the decisions above can be
 /// driven through every case without a helper, a bundle, or a settings store.
 ///
-/// Only observations and effects live here. No method decides anything, and
-/// none of them can open System Settings.
+/// Only observations and effects live here, and no method decides anything about
+/// the goal or the helper. Nothing this function does asks for System Settings
+/// either: the GUI's `reported` opens Login Items only when a Grant click is
+/// waiting for an answer, so what opens it is that click and never a report this
+/// function produced. A run that no click is waiting on — startup, a status
+/// refresh — therefore opens nothing, whatever it observes.
 pub trait Environment {
     /// An answered connection, held open. Opaque: the only thing done with one
     /// is asking whether its peer is still there.
@@ -720,9 +729,7 @@ impl<R: Runtime> Environment for LiveEnvironment<'_, R> {
     }
 
     fn unregister(&self) -> Result<(), String> {
-        service::unregister()
-            .map(|_status| ())
-            .map_err(|error| format!("{error:#}"))
+        service::unregister().map_err(|error| format!("{error:#}"))
     }
 
     fn replace_helper(
@@ -1293,7 +1300,11 @@ impl<E: Environment> Run<'_, E> {
 /// Re-evaluated before each one rather than once per pass: both facts can
 /// change while a pass runs — an app can be moved, and a bundle can be
 /// replaced by an update — and what they guard is destructive.
-fn gates<E: Environment>(env: &E) -> Result<(), Reconciled> {
+///
+/// Public for one reason: Apply asks the same question before deciding whether
+/// it may touch a helper, and a second implementation of it could disagree with
+/// this one.
+pub fn gates<E: Environment>(env: &E) -> Result<(), Reconciled> {
     // Canonical install. A copy running from anywhere else observes and
     // reports only: it may not even ask a helper to retire.
     if let InstallLocation::Elsewhere(observed) = env.install_location() {
@@ -2439,7 +2450,10 @@ mod tests {
             ..World::default()
         });
 
-        assert_eq!(reconciled(&fake), stopped(Stopped::NoLongerGrantedDuringRun));
+        assert_eq!(
+            reconciled(&fake),
+            stopped(Stopped::NoLongerGrantedDuringRun)
+        );
         assert_eq!(
             fake.mutations(),
             vec![Event::ReplacementUnregistered { holding: 1 }]
@@ -2574,7 +2588,10 @@ mod tests {
         // verification that reused those numbers would judge this helper missing
         // and report a failure on a fresh install that in fact worked.
         let waits = socket_probe::ABSENCE_ATTEMPTS as usize + 1;
-        assert!(waits < VERIFY_LISTEN_ATTEMPTS as usize, "the delay is reachable");
+        assert!(
+            waits < VERIFY_LISTEN_ATTEMPTS as usize,
+            "the delay is reachable"
+        );
         let fake = Fake::new(World {
             preference: HelperPreference::Granted,
             starts_answering_after: waits,