feat(install): phase-based progress bar replaces unparseable pull bytes

Podman emits zero parseable progress when stderr is piped (no TTY), so
the old byte-counter regex never matched in real installs. Users saw
0% for the whole pull, then a jump to 95%, then silence through
create-container, health-check, and post-install hooks.

Replace with 7 explicit lifecycle phases wired through install.rs and
update.rs: Preparing (5%), PullingImage (20%), CreatingContainer (70%),
StartingContainer (80%), WaitingHealthy (88%), PostInstall (95%),
Done (100%). Each maps to a fixed UI progress and status message.

Frontend PHASE_INFO mapper in stores/server.ts prioritizes phase when
present, falls back to byte-counter for legacy. A Math.max forward-only
guard ensures the bar never regresses. Deleted the duplicate watcher
in Discover.vue that was fighting the store's watcher with stale byte
logic. Added shimmer CSS on the fill (with prefers-reduced-motion
opt-out) so the bar looks alive during long phases.

core/archipelago/src/api/rpc/package/install.rs

@@ -9,6 +9,7 @@ use super::dependencies::{
 use super::progress::parse_pull_progress;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
+use crate::data_model::InstallPhase;
 use anyhow::{Context, Result};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tracing::{debug, info, warn};
@@ -96,6 +97,9 @@ impl RpcHandler {
             return self.install_indeedhub_stack().await;
         }
 
+        // Phase: Preparing — validating deps and configs before any slow I/O.
+        self.set_install_phase(package_id, InstallPhase::Preparing).await;
+
         // Dependency checks
         let deps = detect_running_deps().await?;
         check_install_deps(package_id, &deps)?;
@@ -181,12 +185,21 @@ impl RpcHandler {
             package_id, docker_image
         ))
         .await;
+        // Phase: PullingImage — the longest phase. Podman doesn't emit
+        // parseable progress on a piped stderr, so the UI shows an
+        // indeterminate "Downloading image…" at this fixed percentage
+        // until pull completes.
+        self.set_install_phase(package_id, InstallPhase::PullingImage).await;
         let has_local_fallback = self.pull_or_verify_image(package_id, docker_image).await?;
         install_log(&format!(
             "INSTALL PULL OK: {} — image ready (local_fallback={})",
             package_id, has_local_fallback
         ))
         .await;
+        // Phase: CreatingContainer — image is local, now writing configs,
+        // data directories, chowning to container UID, building the run
+        // argv. Fast (sub-second to a few seconds).
+        self.set_install_phase(package_id, InstallPhase::CreatingContainer).await;
 
         // Normalize container name for legacy aliases
         let container_name = match package_id {
@@ -436,9 +449,19 @@ impl RpcHandler {
         ))
         .await;
 
+        // Phase: StartingContainer — podman run accepted. Next we poll
+        // inspect until State.Status == running (up to 60s).
+        self.set_install_phase(package_id, InstallPhase::StartingContainer).await;
+
         // Post-start health verification: wait up to 60s for container to be running
         let mut container_running = false;
         for i in 0..12u32 {
+            // After the first poll, flip the UI to WaitingHealthy — the
+            // container hasn't come up yet, so the phase label changes
+            // from "Starting container" to "Waiting for healthy".
+            if i == 1 {
+                self.set_install_phase(package_id, InstallPhase::WaitingHealthy).await;
+            }
             tokio::time::sleep(std::time::Duration::from_secs(5)).await;
             let status = tokio::process::Command::new("podman")
                 .args(["inspect", container_name, "--format", "{{.State.Status}}"])
@@ -498,6 +521,11 @@ impl RpcHandler {
             ));
         }
 
+        // Phase: PostInstall — container is up and running. Now any
+        // app-specific post-install (chain init, wallet setup, waiting
+        // for a first block). Varies by app; some are no-ops.
+        self.set_install_phase(package_id, InstallPhase::PostInstall).await;
+
         // Post-install hooks — await completion before returning success
         self.run_post_install_hooks(package_id).await;
 

core/archipelago/src/api/rpc/package/progress.rs

@@ -2,12 +2,17 @@
 
 use crate::api::rpc::RpcHandler;
 use crate::data_model::{
-    Description, InstallProgress, Manifest, PackageDataEntry, PackageState, StaticFiles,
+    Description, InstallPhase, InstallProgress, Manifest, PackageDataEntry, PackageState,
+    StaticFiles,
 };
 
 impl RpcHandler {
     /// Set install progress for a package and broadcast the update.
     /// Creates a minimal package entry if one doesn't exist yet.
+    ///
+    /// Prefer `set_install_phase` — this byte-counter API is kept for
+    /// the rare case where the pull stream actually parses, but podman
+    /// almost never emits parseable progress on a piped stderr.
     pub(super) async fn set_install_progress(&self, package_id: &str, downloaded: u64, size: u64) {
         let (mut data, _rev) = self.state_manager.get_snapshot().await;
         let entry = data
@@ -15,7 +20,45 @@ impl RpcHandler {
             .entry(package_id.to_string())
             .or_insert_with(|| create_installing_entry(package_id));
         entry.state = PackageState::Installing;
-        entry.install_progress = Some(InstallProgress { size, downloaded });
+        let existing_phase = entry
+            .install_progress
+            .as_ref()
+            .and_then(|p| p.phase);
+        entry.install_progress = Some(InstallProgress {
+            size,
+            downloaded,
+            phase: existing_phase,
+        });
+        self.state_manager.update_data(data).await;
+    }
+
+    /// Set the install pipeline phase and broadcast. This is the
+    /// primary progress signal — the UI maps each phase to a
+    /// percentage and a user-facing label. Byte counters are retained
+    /// for the rare case podman emits parseable progress.
+    pub(super) async fn set_install_phase(&self, package_id: &str, phase: InstallPhase) {
+        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        let entry = data
+            .package_data
+            .entry(package_id.to_string())
+            .or_insert_with(|| create_installing_entry(package_id));
+        // Preparing / PullingImage / CreatingContainer / StartingContainer /
+        // WaitingHealthy / PostInstall all map to the Installing state.
+        // Updates use Updating state — the wrapper has already flipped
+        // state to Updating, so don't clobber it.
+        if entry.state != PackageState::Updating {
+            entry.state = PackageState::Installing;
+        }
+        let (size, downloaded) = entry
+            .install_progress
+            .as_ref()
+            .map(|p| (p.size, p.downloaded))
+            .unwrap_or((0, 0));
+        entry.install_progress = Some(InstallProgress {
+            size,
+            downloaded,
+            phase: Some(phase),
+        });
         self.state_manager.update_data(data).await;
     }
 
@@ -52,9 +95,14 @@ impl RpcHandler {
             .package_data
             .entry(package_id.to_string())
             .or_insert_with(|| create_installing_entry(package_id));
+        let existing_phase = entry
+            .install_progress
+            .as_ref()
+            .and_then(|p| p.phase);
         entry.install_progress = Some(InstallProgress {
             size: total,
             downloaded,
+            phase: existing_phase,
         });
         state_manager.update_data(data).await;
     }

core/archipelago/src/api/rpc/package/update.rs

@@ -11,7 +11,7 @@ use super::runtime::stop_timeout_secs;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
 use crate::container::image_versions;
-use crate::data_model::PackageState;
+use crate::data_model::{InstallPhase, PackageState};
 use anyhow::{Context, Result};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tracing::{error, info, warn};
@@ -96,6 +96,10 @@ impl RpcHandler {
         containers: &[String],
         images_to_pull: &[(String, String)],
     ) -> Result<()> {
+        // Phase: Preparing — about to stop the running container(s) so
+        // we can swap images. Fast.
+        self.set_install_phase(package_id, InstallPhase::Preparing).await;
+
         // 1. Graceful stop all containers (reverse order for dependencies)
         info!(
             "Update {}: stopping {} containers",
@@ -125,6 +129,9 @@ impl RpcHandler {
             }
         }
 
+        // Phase: PullingImage — about to fetch each pinned image in turn.
+        self.set_install_phase(package_id, InstallPhase::PullingImage).await;
+
         // 2. Pull new images with progress
         info!(
             "Update {}: pulling {} images",
@@ -168,6 +175,10 @@ impl RpcHandler {
             }
         }
 
+        // Phase: CreatingContainer — about to recreate each container
+        // via reconcile-containers.sh with the new image.
+        self.set_install_phase(package_id, InstallPhase::CreatingContainer).await;
+
         // 4. Recreate via reconcile script (single source of truth for container specs)
         info!("Update {}: recreating containers via reconcile", package_id);
         for name in containers {
@@ -200,6 +211,10 @@ impl RpcHandler {
             tokio::time::sleep(std::time::Duration::from_secs(2)).await;
         }
 
+        // Phase: WaitingHealthy — reconcile has started every container,
+        // now verifying each reached running state.
+        self.set_install_phase(package_id, InstallPhase::WaitingHealthy).await;
+
         // 5. Verify containers reached running state
         tokio::time::sleep(std::time::Duration::from_secs(5)).await;
         for name in containers {

core/archipelago/src/data_model.rs

@@ -245,6 +245,38 @@ pub enum ServiceStatus {
 pub struct InstallProgress {
     pub size: u64,
     pub downloaded: u64,
+    /// High-level pipeline phase. Preferred by the UI over the byte
+    /// counters (podman pull doesn't emit parseable progress on a piped
+    /// stderr, so `size`/`downloaded` are often 0). Each phase maps to
+    /// a fixed UI percentage and a descriptive label.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub phase: Option<InstallPhase>,
+}
+
+/// Phases of the install / update pipeline, surfaced to the UI so users
+/// see where the pipeline is rather than a stuck 0% bar.
+///
+/// Ordered so each variant's index roughly corresponds to pipeline time.
+/// Serialized as kebab-case: "preparing", "pulling-image", …
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum InstallPhase {
+    /// Validating params, checking deps, writing dynamic configs.
+    Preparing,
+    /// `podman pull` in progress (the longest phase — up to several
+    /// minutes for large images on slow networks).
+    PullingImage,
+    /// Creating data directories, writing app-specific configs
+    /// (bitcoin.conf, lnd.conf, searxng settings.yml, chown).
+    CreatingContainer,
+    /// `podman run` has returned; container is transitioning to running.
+    StartingContainer,
+    /// Post-start loop waiting up to 60s for `State.Status == running`.
+    WaitingHealthy,
+    /// Running post-install hooks (chain init, wallet setup, …).
+    PostInstall,
+    /// Pipeline finished successfully. Terminal phase, UI clears entry.
+    Done,
 }
 
 /// WebSocket message sent to clients