close sprint two blockers

Status	File	+	-
M	`README.md`	1	0
M	`examples/config.toml`	4	0
A	`examples/sprint-02-validation-report-2026-02-18.md`	46	0
M	`examples/sprint-02-validation.md`	17	0
M	`examples/validate-sprint-02.sh`	14	10
M	`garcard/src/agent.rs`	110	19
M	`garcard/src/config.rs`	39	0
M	`garcard/src/daemon.rs`	67	0

README.mdmodified


 7. `GARCARD_POLKIT_HELPER_SOCKET`
 8. `GARCARD_PROMPT_COMMAND`
 9. `GARCARD_PROMPT_TIMEOUT_SECS`
+10. `GARCARD_BACKEND_HEALTHCHECK_SECS`
 
 See `examples/config.toml` for a starter file.
 

examples/config.tomlmodified

  # Locale sent to polkit authority registration.
  locale = "en_US.UTF-8"
++
++# Backend health check interval in seconds.
++# Failed checks trigger a reconnect attempt for the selected auth backend.
++backend_healthcheck_secs = "5"

examples/sprint-02-validation-report-2026-02-18.mdadded

++# Sprint 02 Validation Report (2026-02-18)
++
++## Environment
++1. Host: `mizu` (NixOS)
++2. Daemon run mode: `GARCARD_AGENT_BACKEND=polkit`
++3. Socket: `/run/user/1000/garcard.sock`
++
++## Baseline Checks
++1. `garcardctl ping` -> success.
++2. `garcardctl status` -> running with `agent_backend: polkit`.
++3. `garcardctl auth-summary` -> `idle`.
++
++## Live Policy Checks
++1. `pkcheck --allow-user-interaction --process $$ --action-id org.freedesktop.login1.power-off`
++Result:
++1. Exit code `0`.
++2. No challenge emitted (policy already authorized in this session context).
++
++2. `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run`
++Result:
++1. Exit code `1` (`Not authorized.`).
++2. Daemon logs showed live challenge callback:
++   - `Started active polkit auth request ...`
++   - `Processing polkit auth request ...`
++   - `Starting helper authentication dialog ...`
++3. `garcardctl auth-summary` after call -> `timeout`.
++
++## Reconnect Validation
++1. `kill -HUP <garcard-pid>` (forced reconnect path).
++2. Daemon logs:
++   - `Received SIGHUP; forcing backend reconnect`
++   - `Unregistered polkit authentication agent`
++   - `Registered polkit authentication agent`
++3. Post-check:
++   - `garcardctl status` remained responsive.
++   - `garcardctl auth-summary` remained consistent.
++
++## Optional Root-Level Disruption Check
++1. Attempted `systemctl restart polkit`.
++2. Result: `Access denied` (no root/system permission from this validation context).
++3. Root-level service restart scenario remains for host-owner execution if desired.
++
++## Conclusion
++1. Sprint 02 auth callback path is live and receiving real polkit challenge requests.
++2. Timeout state is observable and propagated through IPC summary.
++3. Backend reconnect behavior is validated through forced reconnect workflow.

examples/sprint-02-validation.mdmodified

 . One active request at a time.
 . Additional requests queue and process FIFO.
 . No deadlock after cancel/failure/success.
++
++## Backend Reconnect (Bus/Authority Disruption)
++1. Start daemon with visible logs:
++   - `RUST_LOG=garcard=debug cargo run -p garcard -- daemon`
++2. In another terminal, capture status:
++   - `cargo run -q -p garcardctl -- status`
++3. Force reconnect path without root:
++   - `kill -HUP <garcard-pid>`
++4. Wait at least one health interval (default 5s), then check status and logs.
++5. Optional root-level disruption check:
++   - `sudo systemctl restart polkit`
++
++Expected:
++1. Log shows forced reconnect path (`Received SIGHUP; forcing backend reconnect`).
++2. Backend re-registers without daemon process restart.
++3. `garcardctl status` remains responsive during/after reconnect attempt.
++4. Optional root-level disruption should trigger maintenance reconnect attempts.

examples/validate-sprint-02.shmodified

  ACTION_ID="${1:-org.freedesktop.login1.power-off}"
--if ! command -v garcardctl >/dev/null 2>&1; then
--  echo "garcardctl not found in PATH"
--  echo "Run from this repo with: cargo run -p garcardctl -- <command>"
--  exit 1
--fi
--
  if ! command -v pkcheck >/dev/null 2>&1; then
    echo "pkcheck not found; install polkit tools to run live auth validation"
    exit 1
  fi
++if command -v garcardctl >/dev/null 2>&1; then
++  GARCARDCTL=(garcardctl)
++else
++  GARCARDCTL=(cargo run -q -p garcardctl --)
++fi
++
++run_garcardctl() {
++  "${GARCARDCTL[@]}" "$@"
++}
++
  echo "[1/5] Check daemon connectivity"
--garcardctl ping
++run_garcardctl ping
  echo "[2/5] Check daemon status"
--garcardctl status
++run_garcardctl status
  echo "[3/5] Check pre-auth summary"
--garcardctl auth-summary
++run_garcardctl auth-summary
  echo "[4/5] Trigger interactive policy check"
  echo "Action ID: ${ACTION_ID}"
  echo "pkcheck exit code: ${PKCHECK_RC}"
  echo "[5/5] Check post-auth summary"
--garcardctl auth-summary
++run_garcardctl auth-summary
  cat <<'EOF'
  Exit code hints:

garcard/src/agent.rsmodified

      fn name(&self) -> &'static str;
      fn register(&mut self) -> Result<()>;
      fn unregister(&mut self) -> Result<()>;
++    fn maintain(&mut self) -> Result<()> {
++        Ok(())
++    }
+ }
  /// Placeholder backend used during Sprint 01 scaffolding.
          )?;
          Ok(proxy)
+     }
++
++    fn peer_proxy(connection: &Connection) -> Result<Proxy<'_>> {
++        let proxy = Proxy::new(
++            connection,
++            "org.freedesktop.PolicyKit1",
++            "/org/freedesktop/PolicyKit1/Authority",
++            "org.freedesktop.DBus.Peer",
++        )?;
++        Ok(proxy)
++    }
++
++    fn ping_authority(connection: &Connection) -> Result<()> {
++        let _: () = Self::peer_proxy(connection)?.call("Ping", &())?;
++        Ok(())
++    }
+ }
  impl AuthAgentBackend for PolkitAgent {
                  &(
                      &self.subject,
                      self.locale.as_str(),
--                    self.object_path.clone(),
++                    self.object_path.to_string(),
                  ),
              )?;
              Ok(())
+         }
          if let Some(connection) = &self.connection {
--            match Self::proxy(connection)?.call::<_, _, ()>(
++            match Self::proxy(connection) {
++                Ok(proxy) => match proxy.call::<_, _, ()>(
                      "UnregisterAuthenticationAgent",
--                &(
++                    &(&self.subject, self.object_path.to_string()),
--                    &self.subject,
--                    self.locale.as_str(),
--                    self.object_path.clone(),
--                ),
                  ) {
                      Ok(()) => {
                          tracing::info!(
                          );
+                     }
                      Err(err) => {
--                    tracing::warn!(error = %err, "Failed to unregister polkit authentication agent");
++                        tracing::warn!(
++                            error = %err,
++                            "Failed to unregister polkit authentication agent"
++                        );
++                    }
++                },
++                Err(err) => {
++                    tracing::warn!(
++                        error = %err,
++                        "Failed to create polkit authority proxy during unregister"
++                    );
+                 }
+             }
          self.connection = None;
          Ok(())
+     }
++
++    fn maintain(&mut self) -> Result<()> {
++        if !self.registered {
++            return self.register();
++        }
++
++        let is_healthy = self
++            .connection
++            .as_ref()
++            .map(|connection| Self::ping_authority(connection).is_ok())
++            .unwrap_or(false);
++        if is_healthy {
++            return Ok(());
++        }
++
++        tracing::warn!(
++            backend = self.name(),
++            "Polkit backend health check failed; attempting reconnect"
++        );
++        let _ = self.unregister();
++        self.register()
++    }
+ }
  fn build_subject() -> Subject {
++    if let Some(session_id) = current_session_id() {
++        let mut details = HashMap::new();
++        let value = zbus::zvariant::Value::from(session_id.as_str());
++        if let Ok(session_value) = OwnedValue::try_from(value) {
++            details.insert("session-id".to_string(), session_value);
++            return ("unix-session".to_string(), details);
++        }
++    }
++
      let mut details = HashMap::new();
      details.insert("pid".to_string(), OwnedValue::from(std::process::id()));
      details.insert(
          "uid".to_string(),
          OwnedValue::from(nix::unistd::geteuid().as_raw()),
      );
++    if let Some(start_time) = process_start_time_ticks() {
++        details.insert("start-time".to_string(), OwnedValue::from(start_time));
++    } else {
++        tracing::warn!("Unable to determine process start-time for polkit subject");
++    }
      ("unix-process".to_string(), details)
+ }
++fn process_start_time_ticks() -> Option<u64> {
++    let stat = std::fs::read_to_string("/proc/self/stat").ok()?;
++    let (_head, tail) = stat.rsplit_once(") ")?;
++    let mut fields = tail.split_whitespace();
++    fields.nth(19)?.parse::<u64>().ok()
++}
++
++fn current_session_id() -> Option<String> {
++    if let Ok(raw) = std::env::var("XDG_SESSION_ID") {
++        let trimmed = raw.trim();
++        if !trimmed.is_empty() {
++            return Some(trimmed.to_string());
++        }
++    }
++
++    let raw = std::fs::read_to_string("/proc/self/sessionid").ok()?;
++    let trimmed = raw.trim();
++    if trimmed.is_empty() || trimmed == "4294967295" {
++        return None;
++    }
++
++    Some(trimmed.to_string())
++}
++
  #[cfg(test)]
  mod tests {
      use super::*;
      #[test]
      fn subject_uses_unix_process_kind() {
          let subject = build_subject();
--        assert_eq!(subject.0, "unix-process");
++        match subject.0.as_str() {
++            "unix-session" => assert!(subject.1.contains_key("session-id")),
++            "unix-process" => {
                  assert!(subject.1.contains_key("pid"));
                  assert!(subject.1.contains_key("uid"));
++                assert!(subject.1.contains_key("start-time"));
++            }
++            other => panic!("unexpected subject kind: {other}"),
++        }
+     }
      #[test]

garcard/src/config.rsmodified

      pub agent_backend: AgentBackendMode,
      pub polkit_object_path: String,
      pub locale: String,
++    pub backend_healthcheck_secs: u64,
  }
  impl Default for Config {
              agent_backend: AgentBackendMode::Auto,
              polkit_object_path: "/org/gardesk/Garcard/AuthAgent".to_string(),
              locale: std::env::var("LANG").unwrap_or_else(|_| "en_US.UTF-8".to_string()),
++            backend_healthcheck_secs: 5,
          }
      }
  }
          if let Some(raw_locale) = std::env::var_os("GARCARD_LOCALE") {
              cfg.locale = raw_locale.to_string_lossy().to_string();
          }
++        if let Some(raw_interval) = std::env::var_os("GARCARD_BACKEND_HEALTHCHECK_SECS") {
++            cfg.backend_healthcheck_secs = parse_positive_secs(&raw_interval.to_string_lossy())
++                .with_context(|| {
++                    "Invalid GARCARD_BACKEND_HEALTHCHECK_SECS (expected positive integer seconds)"
++                })?;
++        }
          Ok(cfg)
      }
          if let Some(locale) = file_cfg.locale {
              self.locale = locale;
          }
++        if let Some(backend_healthcheck_secs) = file_cfg.backend_healthcheck_secs {
++            self.backend_healthcheck_secs = parse_positive_secs(&backend_healthcheck_secs)
++                .with_context(|| {
++                "Invalid backend_healthcheck_secs in config file (expected positive integer seconds)"
++            })?;
++        }
          Ok(())
      }
      agent_backend: Option<String>,
      polkit_object_path: Option<String>,
      locale: Option<String>,
++    backend_healthcheck_secs: Option<String>,
  }
  fn config_path() -> Option<PathBuf> {
      Ok(mode)
  }
++fn parse_positive_secs(raw: &str) -> Result<u64> {
++    let trimmed = raw.trim();
++    let secs = trimmed
++        .parse::<u64>()
++        .with_context(|| format!("failed to parse seconds value: {trimmed}"))?;
++    if secs == 0 {
++        anyhow::bail!("seconds must be greater than zero");
++    }
++    Ok(secs)
++}
++
  #[cfg(test)]
  mod tests {
      use super::*;
  agent_backend = "stub"
  polkit_object_path = "/org/gardesk/Garcard/TestAgent"
  locale = "C"
++backend_healthcheck_secs = "7"
  "#,
          )
          .expect("parse file config");
              Some("/org/gardesk/Garcard/TestAgent")
          );
          assert_eq!(parsed.locale.as_deref(), Some("C"));
++        assert_eq!(parsed.backend_healthcheck_secs.as_deref(), Some("7"));
      }
      #[test]
          let err = AgentBackendMode::from_str("bad").expect_err("should fail");
          assert!(err.to_string().contains("unsupported backend mode"));
      }
++
++    #[test]
++    fn parse_positive_secs_rejects_zero() {
++        let err = parse_positive_secs("0").expect_err("zero should fail");
++        assert!(err.to_string().contains("greater than zero"));
++    }
++
++    #[test]
++    fn parse_positive_secs_accepts_positive_integer() {
++        assert_eq!(parse_positive_secs("9").expect("valid"), 9);
++    }
  }

garcard/src/daemon.rsmodified

  use std::os::unix::fs::PermissionsExt;
  use std::path::{Path, PathBuf};
  use std::sync::Arc;
++use std::time::Duration;
  use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
  use tokio::net::{UnixListener, UnixStream};
  use tokio::sync::mpsc;
          .context("Failed to register SIGTERM handler")?;
      let mut sigint = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
          .context("Failed to register SIGINT handler")?;
++    let mut sighup = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::hangup())
++        .context("Failed to register SIGHUP handler")?;
++    let mut backend_maintenance =
++        tokio::time::interval(Duration::from_secs(config.backend_healthcheck_secs));
++    backend_maintenance.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
      tracing::info!(
          socket = %config.socket_path.display(),
          pid = state.status().pid,
          backend = backend.name(),
++        backend_healthcheck_secs = config.backend_healthcheck_secs,
          "garcard daemon started"
      );
      loop {
          tokio::select! {
++            _ = backend_maintenance.tick() => {
++                if let Err(err) = backend.maintain() {
++                    tracing::warn!(
++                        error = %err,
++                        backend = backend.name(),
++                        "Backend maintenance check failed"
++                    );
++                }
++            }
++            _ = sighup.recv() => {
++                tracing::info!("Received SIGHUP; forcing backend reconnect");
++                if let Err(err) = reconnect_backend(backend.as_mut()) {
++                    tracing::warn!(error = %err, backend = backend.name(), "Forced backend reconnect failed");
++                }
++            }
              _ = sigterm.recv() => {
                  tracing::info!("Received SIGTERM");
                  break;
      Ok(())
+ }
++fn reconnect_backend(backend: &mut dyn AuthAgentBackend) -> Result<()> {
++    backend.unregister()?;
++    backend.register()?;
++    Ok(())
++}
++
  fn init_backend(config: &Config, auth_state: Arc<AuthState>) -> Result<Box<dyn AuthAgentBackend>> {
      match config.agent_backend {
          AgentBackendMode::Stub => {
  #[cfg(test)]
  mod tests {
      use super::*;
++    use anyhow::Result as AnyResult;
++    use std::sync::Arc;
++    use std::sync::atomic::{AtomicUsize, Ordering};
      fn fake_state() -> RuntimeState {
          RuntimeState::new("/tmp/garcard-test.sock".to_string(), "test-backend")
              agent_backend: AgentBackendMode::Auto,
              polkit_object_path: "invalid path".to_string(),
              locale: "C".to_string(),
++            backend_healthcheck_secs: 5,
          };
          let backend = init_backend(&config, Arc::new(AuthState::default()))
              .expect("auto mode should fall back");
          assert_eq!(backend.name(), "stub-polkit-agent");
+     }
++
++    struct TrackingBackend {
++        unregister_calls: Arc<AtomicUsize>,
++        register_calls: Arc<AtomicUsize>,
++    }
++
++    impl AuthAgentBackend for TrackingBackend {
++        fn name(&self) -> &'static str {
++            "tracking-backend"
++        }
++
++        fn register(&mut self) -> AnyResult<()> {
++            self.register_calls.fetch_add(1, Ordering::Relaxed);
++            Ok(())
++        }
++
++        fn unregister(&mut self) -> AnyResult<()> {
++            self.unregister_calls.fetch_add(1, Ordering::Relaxed);
++            Ok(())
++        }
++    }
++
++    #[test]
++    fn reconnect_backend_calls_unregister_then_register() {
++        let unregister_calls = Arc::new(AtomicUsize::new(0));
++        let register_calls = Arc::new(AtomicUsize::new(0));
++        let mut backend = TrackingBackend {
++            unregister_calls: Arc::clone(&unregister_calls),
++            register_calls: Arc::clone(&register_calls),
++        };
++
++        reconnect_backend(&mut backend).expect("reconnect");
++        assert_eq!(unregister_calls.load(Ordering::Relaxed), 1);
++        assert_eq!(register_calls.load(Ordering::Relaxed), 1);
++    }
+ }

gardesk/garcard / `37b841d`

8 changed files

`@@ -25,6 +25,7 @@` Environment overrides:
25	7. `GARCARD_POLKIT_HELPER_SOCKET`	25	7. `GARCARD_POLKIT_HELPER_SOCKET`
26	8. `GARCARD_PROMPT_COMMAND`	26	8. `GARCARD_PROMPT_COMMAND`
27	9. `GARCARD_PROMPT_TIMEOUT_SECS`	27	9. `GARCARD_PROMPT_TIMEOUT_SECS`
		28	+10. `GARCARD_BACKEND_HEALTHCHECK_SECS`
28		29
29	See `examples/config.toml` for a starter file.	30	See `examples/config.toml` for a starter file.
30		31