feat(panel): add per-bot image updates and panel self-update

- Add strict image pulls (`require_fresh_image`) for panel self-update so GHCR outages cannot arm a swap onto stale cached tags
- Add `local_image_digests` to compare running containers against registry digests without pulling on every status poll
- Add `schedule_image_swap` to arm panel self-update by creating a replacement container and spawning a short-lived Docker CLI helper to finish the swap after the panel process exits
- Resolve docker socket paths through container mounts in the helper bind so custom socket paths (not just `/var/run/docker.sock`) work correctly
- Add Update button for eligible bots that pulls `STITCH_PANEL_BOT_IMAGE` (resolving pinned sha-* tags to `:latest`) and recreates that bot only, preserving config and keys
- Restrict Update to bots on the configured image channel and migrated to per-bot directory layout (flat layout would lose the in-container nonce ledger on recreate)
- Add `switch_corridor` to replace stitch.toml with a new corridor preset while keeping the signer, stopping the bot so tokens can be re-approved
- Add `/api/updates` endpoint that checks registry digests (cached ~15 minutes) for newer bot and panel images, with `?refresh=1` to force recheck
- Expand `SettingsForm` desktop field set to corridor, signer, spreads, taker, endpoints and simplify mobile form
- Add Update panel button in header and per-bot Update / Recreate buttons on bot detail pages
- Expand `install-panel.md` with image update workflow, self-update behavior, and hardening notes on pinning and ACLs

Author: bnolens

.textile-monorepo-source

@@ -1 +1 @@
-caf6045aec73fef8ea0875b561562a8fe5ff10df
+4e22252d80b6447d234bc7018eddc6198f960dd0

.textile-stitch-release-version

@@ -1 +1 @@
-0.1.109
+0.1.110

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "stitch-bot"
-version = "0.1.109"
+version = "0.1.110"
 edition = "2021"
 description = "Stitch — Textile filler-network operator bot; market-makes the filler order book with signed UniswapX limit orders."
 license = "AGPL-3.0-or-later"

Cargo.toml

@@ -331,7 +331,8 @@ it; the compose export is there for when you want to go back.
 | Permit2 approve | `docker compose run --rm bot1 stitch approve …` | Approve allowances, output streamed |
 | Dry run | same, with `--dry-run` | Dry run button |
 | Logs | `docker compose logs -f bot1` | live tail with level colouring |
-| Upgrade a bot | edit the image tag, `up -d` | Recreate, on the panel's configured image |
+| Upgrade a bot | edit the image tag, `up -d` | **Update** when a newer digest is available (pulls `STITCH_PANEL_BOT_IMAGE` and recreates that bot). **Recreate** still rebuilds on the configured image for recovery. |
+| Upgrade the panel | `docker compose pull && up -d` | **Update panel** in the header when a newer `textile-stitch-panel` digest is published |
 
 **Approve needs the operator wallet to itself.** It runs in a throwaway container
 with its own copy of the key, and it broadcasts. So does a bot's taker or closer
@@ -497,14 +498,35 @@ Check you're browsing the `ts.net` URL rather than an IP, that your device isn't
 tagged, and that your login is spelled exactly as it appears in the Tailscale
 console.
 
+## Image updates
+
+The panel checks the registry (GHCR) for newer digests of the configured bot
+image and of its own panel image. Results are cached for about 15 minutes; pass
+`?refresh=1` on `/api/updates` (or use the UI after an update) to force a recheck.
+
+- **Per-bot Update** pulls `STITCH_PANEL_BOT_IMAGE` and recreates that bot only.
+  Config and key stay on disk. Expect a brief gap in quoting. If the bot still
+  uses the flat layout, migrate first so the nonce ledger isn't lost on recreate.
+- **Recreate** is the same Docker action without the "you're behind" nudge — use
+  it for recovery (missing container, stuck state).
+- **Update panel** pulls a newer `textile-stitch-panel` image (pinned `sha-*`
+  tags resolve to `:latest` of the same repo) and schedules a self-recreate via a
+  short-lived helper on the Docker socket. The UI disconnects briefly; bots keep
+  running. Local-only images (`stitch-panel` with no registry path) can't
+  self-update — rebuild or set `PANEL_IMAGE` to the published GHCR image.
+
+Offline or private registries that reject anonymous pulls soft-fail: the UI
+simply doesn't show an update, rather than erroring the fleet page.
+
 ## Hardening, once it works
 
 - **Tag the panel node.** Define a tag in your tailnet policy file, then set
   `TS_EXTRA_ARGS=--advertise-tags=tag:stitch-panel` in `.env` and recreate the
   sidecar. Tagged nodes don't expire keys, and ACLs can restrict who reaches the
   panel at the network level as well as at the allowlist.
 - **Pin the bot image.** `STITCH_PANEL_BOT_IMAGE` to a `sha-*` tag, so a restart
-  can't change the bot binary under you.
+  can't change the bot binary under you. The Update button still offers a move to
+  a newer publish when one appears.
 - **Restrict at the ACL level too.** The allowlist is the panel's own check;
   a tailnet ACL means an unlisted device can't even open a connection.
 - **Don't use Funnel.** It strips identity headers and publishes the panel to the

docs/install-panel.md

@@ -144,6 +144,9 @@ impl DockerApi for BollardDocker {
             // that same anonymous pull. Failing here would strand a bot on an image
             // that is right there on the host, so warn and use it. With nothing local
             // there is nothing to fall back to, so the pull error stands.
+            //
+            // Panel self-update must NOT use this fallback — see
+            // [`DockerApi::require_fresh_image`].
             Err(e) if present => {
                 tracing::warn!(
                     "couldn't refresh {image}, using the copy already on the host: {e:#}"
@@ -154,6 +157,138 @@ impl DockerApi for BollardDocker {
         }
     }
 
+    async fn require_fresh_image(&self, image: &str) -> Result<()> {
+        self.pull_image(image).await.with_context(|| {
+            format!("pulling {image} — refusing to continue on a possibly stale local copy")
+        })
+    }
+
+    async fn local_image_digests(&self, image: &str) -> Result<Vec<String>> {
+        match self.docker.inspect_image(image).await {
+            Ok(info) => Ok(info.repo_digests.unwrap_or_default()),
+            // Not on the host yet — an empty list means "nothing to match against",
+            // which the update check treats as unknown rather than "behind".
+            Err(_) => Ok(Vec::new()),
+        }
+    }
+
+    async fn schedule_image_swap(
+        &self,
+        name: &str,
+        new_image: &str,
+        docker_socket: &Path,
+    ) -> Result<()> {
+        // Strict pull — never fall back to a cached local tag. ensure_image's
+        // refresh path tolerates pull failure when a local copy exists (bot
+        // Recreate), but self-update must not restart the panel onto a stale
+        // `:latest` after GHCR/auth/rate-limit failures.
+        self.require_fresh_image(new_image).await?;
+
+        let inspect = self
+            .docker
+            .inspect_container(name, None)
+            .await
+            .with_context(|| format!("inspecting {name} for a self-update"))?;
+        let config = inspect
+            .config
+            .context("the container has no Config — cannot clone it for an update")?;
+        let host_config = inspect.host_config.unwrap_or_default();
+
+        let next = format!("{name}-next");
+        // A leftover from a previous failed swap must not block this one.
+        let _ = self
+            .docker
+            .remove_container(
+                &next,
+                Some(RemoveContainerOptionsBuilder::default().force(true).build()),
+            )
+            .await;
+
+        let body = ContainerCreateBody {
+            image: Some(new_image.to_string()),
+            env: config.env.clone(),
+            cmd: config.cmd.clone(),
+            entrypoint: config.entrypoint.clone(),
+            working_dir: config.working_dir.clone(),
+            user: config.user.clone(),
+            labels: config.labels.clone(),
+            // HostConfig.port_bindings alone is not enough — Docker only publishes
+            // a host port when the create Config also exposes the container port.
+            // The password-only install snippet binds 127.0.0.1:8420:8420; dropping
+            // exposed_ports here would leave the UI unreachable after self-update.
+            exposed_ports: config.exposed_ports.clone(),
+            host_config: Some(host_config),
+            stop_timeout: config.stop_timeout.or(Some(STOP_GRACE_SECS)),
+            ..Default::default()
+        };
+        let options = CreateContainerOptionsBuilder::default().name(&next).build();
+        self.docker
+            .create_container(Some(options), body)
+            .await
+            .with_context(|| format!("creating the replacement container {next}"))?;
+
+        // The panel process lives inside `name`. Stopping it from here would kill
+        // the task mid-swap, so a short-lived helper on the docker socket finishes
+        // the rename after we return. CreateContainer bind sources are host paths:
+        // resolve STITCH_PANEL_DOCKER_SOCKET (in-container) through this container's
+        // mounts to the host source, then mount that onto the helper's default path.
+        let mounts: Vec<crate::panel::docker::MountInfo> = inspect
+            .mounts
+            .as_ref()
+            .map(|m| m.iter().map(to_mount_info).collect())
+            .unwrap_or_default();
+        let host_socket = crate::panel::docker::host_docker_socket_bind(&mounts, docker_socket);
+        let socket = host_socket
+            .to_str()
+            .ok_or_else(|| anyhow::anyhow!("docker socket path is not valid UTF-8"))?;
+        anyhow::ensure!(
+            !socket.contains(':'),
+            "docker socket path {socket} contains a colon, which Docker cannot express in a bind mount"
+        );
+        const HELPER_IMAGE: &str = "docker:27-cli";
+        self.ensure_image(HELPER_IMAGE, false).await?;
+        let script = format!(
+            "sleep 2 && docker stop -t 30 {name} && docker rm -f {name} && \
+             docker rename {next} {name} && docker start {name}"
+        );
+        let helper_name = format!("{name}-updater");
+        let _ = self
+            .docker
+            .remove_container(
+                &helper_name,
+                Some(RemoveContainerOptionsBuilder::default().force(true).build()),
+            )
+            .await;
+        let helper_body = ContainerCreateBody {
+            image: Some(HELPER_IMAGE.into()),
+            cmd: Some(vec!["sh".into(), "-c".into(), script]),
+            host_config: Some(HostConfig {
+                binds: Some(vec![format!("{socket}:/var/run/docker.sock")]),
+                auto_remove: Some(true),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+        let helper_opts = CreateContainerOptionsBuilder::default()
+            .name(&helper_name)
+            .build();
+        let helper = self
+            .docker
+            .create_container(Some(helper_opts), helper_body)
+            .await
+            .context("creating the panel self-update helper")?;
+        self.docker
+            .start_container(&helper.id, None)
+            .await
+            .context("starting the panel self-update helper")?;
+        tracing::info!(
+            container = %name,
+            new_image,
+            "armed panel image swap; helper will recreate the container shortly"
+        );
+        Ok(())
+    }
+
     async fn create(&self, spec: &CreateSpec) -> Result<String> {
         let binds = spec
             .binds
@@ -632,6 +767,7 @@ fn to_container_info(s: &ContainerSummary) -> ContainerInfo {
             .map(|n| n.trim_start_matches('/').to_string())
             .unwrap_or_default(),
         image: s.image.clone().unwrap_or_default(),
+        image_id: s.image_id.clone().unwrap_or_default(),
         state: s
             .state
             .as_ref()

src/panel/docker/bollard_api.rs

@@ -31,6 +31,12 @@ pub enum Call {
         image: String,
         refresh: bool,
     },
+    LocalImageDigests(String),
+    ScheduleImageSwap {
+        name: String,
+        new_image: String,
+        docker_socket: String,
+    },
     Create(String),
     Start(String),
     Stop {
@@ -115,6 +121,10 @@ struct FakeState {
     /// a handler that re-reads the fleet after acting needs its first read to succeed
     /// and a later one to fail. `None` never fails.
     list_calls_left: Option<usize>,
+    /// Digests `local_image_digests` returns for a given image reference.
+    image_digests: HashMap<String, Vec<String>>,
+    /// When set, `schedule_image_swap` fails with this message.
+    swap_error: Option<String>,
 }
 
 impl FakeDocker {
@@ -183,6 +193,20 @@ impl FakeDocker {
         self.state.lock().unwrap().image_error = Some(message.to_string());
     }
 
+    /// Seed the digests a local image reports, for update-detection tests.
+    pub fn set_image_digests(&self, image: &str, digests: Vec<String>) {
+        self.state
+            .lock()
+            .unwrap()
+            .image_digests
+            .insert(image.to_string(), digests);
+    }
+
+    /// Make `schedule_image_swap` fail.
+    pub fn fail_swap(&self, message: &str) {
+        self.state.lock().unwrap().swap_error = Some(message.to_string());
+    }
+
     /// Let the next `allowed` calls to `list_all` succeed, then fail every one after.
     /// Stands in for the daemon going unreachable partway through a handler.
     pub fn fail_list_after(&self, allowed: usize) {
@@ -271,6 +295,51 @@ impl DockerApi for FakeDocker {
         }
     }
 
+    async fn require_fresh_image(&self, image: &str) -> Result<()> {
+        // Same failure surface as a hard pull — the fake has no local-fallback
+        // path to model separately.
+        self.ensure_image(image, true).await
+    }
+
+    async fn local_image_digests(&self, image: &str) -> Result<Vec<String>> {
+        let mut st = self.state.lock().unwrap();
+        st.calls.push(Call::LocalImageDigests(image.to_string()));
+        Ok(st.image_digests.get(image).cloned().unwrap_or_default())
+    }
+
+    async fn schedule_image_swap(
+        &self,
+        name: &str,
+        new_image: &str,
+        docker_socket: &std::path::Path,
+    ) -> Result<()> {
+        // Mirror production: strict pull before arming the swap.
+        self.require_fresh_image(new_image).await?;
+        let mut st = self.state.lock().unwrap();
+        let host_socket = st
+            .containers
+            .iter()
+            .find(|c| c.name == name)
+            .map(|c| crate::panel::docker::host_docker_socket_bind(&c.mounts, docker_socket))
+            .unwrap_or_else(|| docker_socket.to_path_buf());
+        st.calls.push(Call::ScheduleImageSwap {
+            name: name.to_string(),
+            new_image: new_image.to_string(),
+            docker_socket: host_socket.display().to_string(),
+        });
+        if let Some(msg) = st.swap_error.clone() {
+            bail!(msg);
+        }
+        // Stand in for a successful swap: the container is now on the new image.
+        if let Some(c) = st.containers.iter_mut().find(|c| c.name == name) {
+            c.image = new_image.to_string();
+            c.image_id = format!("sha256:swapped-{new_image}");
+        } else {
+            bail!("No such container: {name}");
+        }
+        Ok(())
+    }
+
     async fn create(&self, spec: &CreateSpec) -> Result<String> {
         let mut st = self.state.lock().unwrap();
         Self::check_failure(&mut st)?;
@@ -289,6 +358,7 @@ impl DockerApi for FakeDocker {
             id: id.clone(),
             name: spec.name.clone(),
             image: spec.image.clone(),
+            image_id: format!("sha256:fake-{}", spec.name),
             state: ContainerState::Created,
             status: "Created".to_string(),
             created_unix: 0,
@@ -442,6 +512,7 @@ pub fn container(name: &str, state: ContainerState) -> ContainerInfo {
         id: format!("id-{name}"),
         name: name.to_string(),
         image: "ghcr.io/textile-protocol/textile-stitch:latest".to_string(),
+        image_id: format!("sha256:id-{name}"),
         state,
         status: state.as_str().to_string(),
         created_unix: 1_700_000_000,