chore: release v1.7.45-alpha

Resilience-validated release. Three full sweeps of the new resilience harness against .228 confirm no shipstoppers. Big user-visible: - Bitcoin RPC auth durably correct via host-rendered nginx.conf bind-mount, replaces fragile post-start exec that failed under restricted-cap rootless podman ("crun: write cgroup.procs: Permission denied") - Multi-container stack installs (indeedhub, immich, btcpay, mempool) now emit phase events at every boundary so the progress bar advances - Apps no longer vanish from the dashboard mid-install (absent-scanner skips packages in transitional states) - Indeedhub fresh installs work end-to-end (was 8500+ restart loop): five missing env vars (DATABASE_PORT, QUEUE_HOST, QUEUE_PORT, S3_PRIVATE_BUCKET_NAME, AES_MASTER_SECRET) added to install code - Tailscale install fixed: --entrypoint string was being passed as a single shell-line arg; switched to custom_args array - Catalog cleaned of broken entries (dwn, endurain, ollama removed; nextcloud restored on docker.io) - Bitcoin Core update path uses correct image (was looking for nonexistent lfg2025/bitcoin:28.4) - ISO installs now allocate swap on the encrypted data partition Infra: - New resilience harness (scripts/resilience/) — black-box state-machine tester, every app × every transition. Run before each release. Sweep #3 final: PASS 107 / FAIL 12 / SKIP 14. The 12 fails are 1 cosmetic (homeassistant trusted_hosts), 8 harness/timing false-positives, and 3 non-shipstopper tracked items. Down from 23 in baseline sweep #1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
chore: release v1.7.44-alpha
2026-04-29 12:31:45 -04:00 · 2026-04-28 15:03:04 -04:00 · 2026-04-28 15:00:58 -04:00 · 2026-04-23 15:48:53 -04:00 · 2026-04-23 15:42:49 -04:00 · 2026-04-23 15:36:00 -04:00
228 changed files with 19445 additions and 4859 deletions
@@ -73,3 +73,7 @@ loop/loop.log.bak
 # Separate repos nested in tree
 web/

+._*
+
+# Resilience harness reports (generated, contains session cookies)
+scripts/resilience/reports/
@@ -1,5 +1,24 @@
 # Changelog

+## v1.7.45-alpha (2026-04-29)
+
+- Bitcoin RPC auth is durable. The dashboard reliably connects across container restart, image update, and reboot. Was failing on registry-pulled images that shipped a stale baked-in password.
+- Multi-container apps show real install progress. IndeedHub (7), BTCPay (4), Mempool (3), Immich (3) — bar advances through Preparing → Pulling → Creating → Done instead of sitting at 0% until the very end.
+- Apps no longer disappear from the dashboard mid-install. The container scanner now respects in-flight installs and updates instead of evicting an entry while its containers are still being created.
+- IndeedHub installs cleanly on a fresh node. Five missing environment variables fixed; Nostr sign-in works on first install.
+- Tailscale install no longer fails with "executable not found". Container command was a malformed shell string; now a proper command array.
+- Removed three catalog entries that hung installs for ten minutes (dwn, endurain, ollama — no source images in our registries). Restored Nextcloud, sourced from docker.io.
+- Bitcoin Core update path uses the correct image name (was pulling from a non-existent path).
+- New ISO installs now allocate swap (sized to RAM, capped at 8GB, on the encrypted data partition). Without swap, container image builds and memory spikes were hitting OOM under load.
+
+## v1.7.44-alpha (2026-04-28)
+
+43de3b73 feat(orchestrator): complete container migration and release hardening
+ce39430b feat(self-update): sync and rebuild UI containers on OTA
+72dec5aa fix(lnd-ui): align container port across all specs
+83aacdf2 chore(release): archive ISO build recipes, tarball-only releases
+
+
 All notable changes to Archipelago will be documented in this file.

 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -101,14 +101,20 @@ npm run build      # Production build → web/dist/neode-ui/
 ./scripts/deploy-to-target.sh --both   # Deploy to both LAN servers
 ```

-### Build ISO
+### Release (tarball-only)
+
+Releases ship as a backend binary and a frontend tarball referenced by
+`releases/manifest.json`. Nodes OTA-update via `scripts/self-update.sh`.

 ```bash
-ssh archipelago@<server>
-cd ~/archy/image-recipe
-sudo ./build-auto-installer-iso.sh
+./scripts/create-release.sh 1.2.3
+git push gitea-local main --tags
+git push gitea-vps2 main --tags
 ```

+ISO builds are archived under `image-recipe/_archived/` and not part of the
+release deliverable.
+
 ## Architecture

 ```
@@ -1,7 +1,7 @@
 {
  "version": 2,
-  "updated": "2026-04-12T00:00:00Z",
-  "registry": "git.tx1138.com/lfg2025",
+  "updated": "2026-04-22T00:00:00Z",
+  "registry": "146.59.87.168:3000/lfg2025",
  "featured": {
    "id": "indeedhub",
    "banner": "/assets/img/featured/indeedhub-banner.jpg",
@@ -11,232 +11,260 @@
  },
  "apps": [
    {
-      "id": "bitcoin-knots", "title": "Bitcoin Knots", "version": "28.1.0",
+      "id": "bitcoin-knots",
+      "title": "Bitcoin Knots",
+      "version": "28.1.0",
      "description": "Run a full Bitcoin node. Validate and relay blocks and transactions.",
      "icon": "/assets/img/app-icons/bitcoin-knots.webp",
-      "author": "Bitcoin Knots", "category": "money", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/bitcoin-knots:latest",
+      "author": "Bitcoin Knots",
+      "category": "money",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/bitcoin-knots:latest",
      "repoUrl": "https://github.com/bitcoinknots/bitcoin"
    },
    {
-      "id": "lnd", "title": "LND", "version": "0.18.4",
+      "id": "bitcoin-core",
+      "title": "Bitcoin Core",
+      "version": "28.4",
+      "description": "Reference implementation of the Bitcoin protocol. Run a full node validating and relaying blocks.",
+      "icon": "/assets/img/app-icons/bitcoin-core.svg",
+      "author": "Bitcoin Core contributors",
+      "category": "money",
+      "tier": "optional",
+      "dockerImage": "docker.io/bitcoin/bitcoin:28.4",
+      "repoUrl": "https://github.com/bitcoin/bitcoin"
+    },
+    {
+      "id": "lnd",
+      "title": "LND",
+      "version": "0.18.4",
      "description": "Lightning Network Daemon. Fast Bitcoin payments through Lightning.",
      "icon": "/assets/img/app-icons/lnd.svg",
-      "author": "Lightning Labs", "category": "money", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/lnd:v0.18.4-beta",
+      "author": "Lightning Labs",
+      "category": "money",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/lnd:v0.18.4-beta",
      "repoUrl": "https://github.com/lightningnetwork/lnd",
-      "requires": ["bitcoin-knots"]
+      "requires": [
+        "bitcoin-knots"
+      ]
    },
    {
-      "id": "btcpay-server", "title": "BTCPay Server", "version": "1.13.7",
+      "id": "btcpay-server",
+      "title": "BTCPay Server",
+      "version": "1.13.7",
      "description": "Self-hosted Bitcoin payment processor.",
      "icon": "/assets/img/app-icons/btcpay-server.png",
-      "author": "BTCPay Server Foundation", "category": "commerce", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/btcpayserver:1.13.7",
+      "author": "BTCPay Server Foundation",
+      "category": "commerce",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/btcpayserver:1.13.7",
      "repoUrl": "https://github.com/btcpayserver/btcpayserver",
-      "requires": ["bitcoin-knots"]
+      "requires": [
+        "bitcoin-knots"
+      ]
    },
    {
-      "id": "mempool", "title": "Mempool Explorer", "version": "3.0.0",
+      "id": "mempool",
+      "title": "Mempool Explorer",
+      "version": "3.0.0",
      "description": "Self-hosted Bitcoin blockchain and mempool visualizer.",
      "icon": "/assets/img/app-icons/mempool.webp",
-      "author": "Mempool", "category": "money", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/mempool-frontend:v3.0.0",
+      "author": "Mempool",
+      "category": "money",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.0",
      "repoUrl": "https://github.com/mempool/mempool",
-      "requires": ["bitcoin-knots", "electrumx"]
+      "requires": [
+        "bitcoin-knots",
+        "electrumx"
+      ]
    },
    {
-      "id": "electrumx", "title": "ElectrumX", "version": "1.18.0",
+      "id": "electrumx",
+      "title": "ElectrumX",
+      "version": "1.18.0",
      "description": "Electrum protocol server. Index the blockchain for fast wallet lookups.",
      "icon": "/assets/img/app-icons/electrumx.webp",
-      "author": "Luke Childs", "category": "money", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/electrumx:v1.18.0",
+      "author": "Luke Childs",
+      "category": "money",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/electrumx:v1.18.0",
      "repoUrl": "https://github.com/spesmilo/electrumx",
-      "requires": ["bitcoin-knots"]
+      "requires": [
+        "bitcoin-knots"
+      ]
    },
    {
-      "id": "indeedhub", "title": "IndeeHub", "version": "1.0.0",
+      "id": "indeedhub",
+      "title": "IndeeHub",
+      "version": "1.0.0",
      "description": "Bitcoin documentary streaming with Nostr identity.",
      "icon": "/assets/img/app-icons/indeedhub.png",
-      "author": "IndeeHub", "category": "community",
-      "dockerImage": "git.tx1138.com/lfg2025/indeedhub:1.0.0",
+      "author": "IndeeHub",
+      "category": "community",
+      "dockerImage": "146.59.87.168:3000/lfg2025/indeedhub:1.0.0",
      "repoUrl": "https://github.com/indeedhub/indeedhub"
    },
    {
-      "id": "botfights", "title": "BotFights", "version": "1.1.0",
+      "id": "botfights",
+      "title": "BotFights",
+      "version": "1.1.0",
      "description": "Bot arena + 2-player arcade fighter with controller support and Adventure Mode.",
      "icon": "/assets/img/app-icons/botfights.svg",
-      "author": "BotFights", "category": "community",
-      "dockerImage": "git.tx1138.com/lfg2025/botfights:1.1.0",
+      "author": "BotFights",
+      "category": "community",
+      "dockerImage": "146.59.87.168:3000/lfg2025/botfights:1.1.0",
      "repoUrl": "https://botfights.net"
    },
    {
-      "id": "gitea", "title": "Gitea", "version": "1.23",
+      "id": "gitea",
+      "title": "Gitea",
+      "version": "1.23",
      "description": "Self-hosted Git service with container registry, CI/CD, issue tracking.",
      "icon": "/assets/img/app-icons/gitea.svg",
-      "author": "Gitea", "category": "development",
+      "author": "Gitea",
+      "category": "development",
      "dockerImage": "docker.io/gitea/gitea:1.23",
      "repoUrl": "https://gitea.com"
    },
    {
-      "id": "filebrowser", "title": "File Browser", "version": "2.27.0",
+      "id": "filebrowser",
+      "title": "File Browser",
+      "version": "2.27.0",
      "description": "Web-based file manager.",
      "icon": "/assets/img/app-icons/file-browser.webp",
-      "author": "File Browser", "category": "data", "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/filebrowser:v2.27.0",
+      "author": "File Browser",
+      "category": "data",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/filebrowser:v2.27.0",
      "repoUrl": "https://github.com/filebrowser/filebrowser"
    },
    {
-      "id": "vaultwarden", "title": "Vaultwarden", "version": "1.30.0",
+      "id": "vaultwarden",
+      "title": "Vaultwarden",
+      "version": "1.30.0",
      "description": "Self-hosted password vault with zero-knowledge encryption.",
      "icon": "/assets/img/app-icons/vaultwarden.webp",
-      "author": "Vaultwarden", "category": "data", "tier": "recommended",
-      "dockerImage": "git.tx1138.com/lfg2025/vaultwarden:1.30.0-alpine",
+      "author": "Vaultwarden",
+      "category": "data",
+      "tier": "recommended",
+      "dockerImage": "146.59.87.168:3000/lfg2025/vaultwarden:1.30.0-alpine",
      "repoUrl": "https://github.com/dani-garcia/vaultwarden"
    },
    {
-      "id": "searxng", "title": "SearXNG", "version": "2024.1.0",
+      "id": "searxng",
+      "title": "SearXNG",
+      "version": "2024.1.0",
      "description": "Privacy-respecting metasearch engine.",
      "icon": "/assets/img/app-icons/searxng.png",
-      "author": "SearXNG", "category": "data", "tier": "recommended",
-      "dockerImage": "git.tx1138.com/lfg2025/searxng:latest",
+      "author": "SearXNG",
+      "category": "data",
+      "tier": "recommended",
+      "dockerImage": "146.59.87.168:3000/lfg2025/searxng:latest",
      "repoUrl": "https://github.com/searxng/searxng"
    },
    {
-      "id": "nostr-rs-relay", "title": "Nostr Relay", "version": "0.9.0",
-      "description": "Your own Nostr relay. Store events locally, relay for friends.",
-      "icon": "/assets/img/app-icons/nostr-rs-relay.svg",
-      "author": "scsiblade", "category": "nostr",
-      "dockerImage": "git.tx1138.com/lfg2025/nostr-rs-relay:0.9.0",
-      "repoUrl": "https://sr.ht/~gheartsfield/nostr-rs-relay/"
-    },
-    {
-      "id": "fedimint", "title": "Fedimint", "version": "0.10.0",
+      "id": "fedimint",
+      "title": "Fedimint",
+      "version": "0.10.0",
      "description": "Federated Bitcoin mint with privacy through federated guardians.",
      "icon": "/assets/img/app-icons/fedimint.png",
-      "author": "Fedimint", "category": "money",
-      "dockerImage": "git.tx1138.com/lfg2025/fedimintd:v0.10.0",
+      "author": "Fedimint",
+      "category": "money",
+      "dockerImage": "146.59.87.168:3000/lfg2025/fedimintd:v0.10.0",
      "repoUrl": "https://github.com/fedimint/fedimint"
    },
    {
-      "id": "ollama", "title": "Ollama", "version": "0.5.4",
-      "description": "Run AI models locally. Private and on your hardware.",
-      "icon": "/assets/img/app-icons/ollama.png",
-      "author": "Ollama", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/ollama:latest",
-      "repoUrl": "https://github.com/ollama/ollama"
-    },
-    {
-      "id": "nextcloud", "title": "Nextcloud", "version": "28",
-      "description": "Your own private cloud. File sync, calendars, contacts.",
-      "icon": "/assets/img/app-icons/nextcloud.webp",
-      "author": "Nextcloud", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/nextcloud:28",
-      "repoUrl": "https://github.com/nextcloud/server"
-    },
-    {
-      "id": "jellyfin", "title": "Jellyfin", "version": "10.8.13",
+      "id": "jellyfin",
+      "title": "Jellyfin",
+      "version": "10.8.13",
      "description": "Free media server. Stream movies, music, and photos.",
      "icon": "/assets/img/app-icons/jellyfin.webp",
-      "author": "Jellyfin", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/jellyfin:10.8.13",
+      "author": "Jellyfin",
+      "category": "data",
+      "dockerImage": "146.59.87.168:3000/lfg2025/jellyfin:10.8.13",
      "repoUrl": "https://github.com/jellyfin/jellyfin"
    },
    {
-      "id": "immich", "title": "Immich", "version": "1.90.0",
+      "id": "immich",
+      "title": "Immich",
+      "version": "1.90.0",
      "description": "High-performance photo and video backup with ML.",
      "icon": "/assets/img/app-icons/immich.png",
-      "author": "Immich", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/immich-server:release",
+      "author": "Immich",
+      "category": "data",
+      "dockerImage": "146.59.87.168:3000/lfg2025/immich-server:release",
      "repoUrl": "https://github.com/immich-app/immich"
    },
    {
-      "id": "homeassistant", "title": "Home Assistant", "version": "2024.1",
+      "id": "homeassistant",
+      "title": "Home Assistant",
+      "version": "2024.1",
      "description": "Open-source home automation.",
      "icon": "/assets/img/app-icons/homeassistant.png",
-      "author": "Home Assistant", "category": "home",
-      "dockerImage": "git.tx1138.com/lfg2025/home-assistant:2024.1",
+      "author": "Home Assistant",
+      "category": "home",
+      "dockerImage": "146.59.87.168:3000/lfg2025/home-assistant:2024.1",
      "repoUrl": "https://github.com/home-assistant/core"
    },
    {
-      "id": "grafana", "title": "Grafana", "version": "10.2.0",
+      "id": "grafana",
+      "title": "Grafana",
+      "version": "10.2.0",
      "description": "Analytics and monitoring dashboards.",
      "icon": "/assets/img/app-icons/grafana.png",
-      "author": "Grafana Labs", "category": "data", "tier": "recommended",
-      "dockerImage": "git.tx1138.com/lfg2025/grafana:10.2.0",
+      "author": "Grafana Labs",
+      "category": "data",
+      "tier": "recommended",
+      "dockerImage": "146.59.87.168:3000/lfg2025/grafana:10.2.0",
      "repoUrl": "https://github.com/grafana/grafana"
    },
    {
-      "id": "tailscale", "title": "Tailscale", "version": "1.78.0",
+      "id": "tailscale",
+      "title": "Tailscale",
+      "version": "1.78.0",
      "description": "Zero-config VPN with WireGuard mesh networking.",
      "icon": "/assets/img/app-icons/tailscale.webp",
-      "author": "Tailscale", "category": "networking", "tier": "recommended",
-      "dockerImage": "git.tx1138.com/lfg2025/tailscale:stable",
+      "author": "Tailscale",
+      "category": "networking",
+      "tier": "recommended",
+      "dockerImage": "146.59.87.168:3000/lfg2025/tailscale:stable",
      "repoUrl": "https://github.com/tailscale/tailscale"
    },
    {
-      "id": "uptime-kuma", "title": "Uptime Kuma", "version": "1.23.0",
+      "id": "uptime-kuma",
+      "title": "Uptime Kuma",
+      "version": "1.23.0",
      "description": "Self-hosted uptime monitoring.",
      "icon": "/assets/img/app-icons/uptime-kuma.webp",
-      "author": "Uptime Kuma", "category": "data", "tier": "recommended",
-      "dockerImage": "git.tx1138.com/lfg2025/uptime-kuma:1",
+      "author": "Uptime Kuma",
+      "category": "data",
+      "tier": "recommended",
+      "dockerImage": "146.59.87.168:3000/lfg2025/uptime-kuma:1",
      "repoUrl": "https://github.com/louislam/uptime-kuma"
    },
    {
-      "id": "nostr-vpn", "title": "Nostr VPN", "version": "0.3.7",
-      "description": "Tailscale-style mesh VPN with Nostr control plane.",
-      "icon": "/assets/img/app-icons/nostr-vpn.svg",
-      "author": "Martti Malmi", "category": "networking",
-      "dockerImage": "git.tx1138.com/lfg2025/nostr-vpn:v0.3.7",
-      "repoUrl": "https://github.com/mmalmi/nostr-vpn"
-    },
-    {
-      "id": "fips", "title": "FIPS", "version": "0.1.0",
-      "description": "Free Internetworking Peering System. Encrypted mesh network.",
-      "icon": "/assets/img/app-icons/fips.svg",
-      "author": "Jim Corgan", "category": "networking",
-      "dockerImage": "git.tx1138.com/lfg2025/fips:v0.1.0",
-      "repoUrl": "https://github.com/jmcorgan/fips"
-    },
-    {
-      "id": "routstr", "title": "Routstr", "version": "0.4.3",
-      "description": "Decentralized AI inference proxy with Cashu ecash.",
-      "icon": "/assets/img/app-icons/routstr.svg",
-      "author": "Routstr", "category": "community",
-      "dockerImage": "git.tx1138.com/lfg2025/routstr:v0.4.3",
-      "repoUrl": "https://github.com/routstr/routstr-core"
-    },
-    {
-      "id": "dwn", "title": "Decentralized Web Node", "version": "0.4.0",
-      "description": "Own your data with DID-based access control.",
-      "icon": "/assets/img/app-icons/dwn.svg",
-      "author": "TBD", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/dwn-server:main",
-      "repoUrl": "https://github.com/TBD54566975/dwn-server"
-    },
-    {
-      "id": "endurain", "title": "Endurain", "version": "0.8.0",
-      "description": "Self-hosted fitness tracking. Strava alternative.",
-      "icon": "/assets/img/app-icons/endurain.png",
-      "author": "Endurain", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/endurain:0.8.0",
-      "repoUrl": "https://github.com/joaovitoriasilva/endurain"
-    },
-    {
-      "id": "penpot", "title": "Penpot", "version": "2.4",
-      "description": "Open-source design platform. Self-hosted Figma alternative.",
-      "icon": "/assets/img/app-icons/penpot.webp",
-      "author": "Penpot", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-      "repoUrl": "https://github.com/penpot/penpot"
-    },
-    {
-      "id": "photoprism", "title": "PhotoPrism", "version": "240915",
+      "id": "photoprism",
+      "title": "PhotoPrism",
+      "version": "240915",
      "description": "AI-powered photo management with facial recognition.",
      "icon": "/assets/img/app-icons/photoprism.svg",
-      "author": "PhotoPrism", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/photoprism:240915",
+      "author": "PhotoPrism",
+      "category": "data",
+      "dockerImage": "146.59.87.168:3000/lfg2025/photoprism:240915",
      "repoUrl": "https://github.com/photoprism/photoprism"
+    },
+    {
+      "id": "nextcloud",
+      "title": "Nextcloud",
+      "version": "28",
+      "description": "Your own private cloud. File sync, calendars, contacts.",
+      "icon": "/assets/img/app-icons/nextcloud.webp",
+      "author": "Nextcloud",
+      "category": "data",
+      "dockerImage": "docker.io/nextcloud:28",
+      "repoUrl": "https://github.com/nextcloud/server"
    }
  ]
 }
@@ -0,0 +1,49 @@
+app:
+  id: archy-btcpay-db
+  name: BTCPay Postgres
+  version: 15.17
+  description: Postgres backend for BTCPay and NBXplorer.
+
+  container:
+    image: git.tx1138.com/lfg2025/postgres:15.17
+    pull_policy: if-not-present
+    network: archy-net
+    data_uid: "100998:100998"
+    secret_env:
+      - key: POSTGRES_PASSWORD
+        secret_file: btcpay-db-password
+
+  dependencies:
+    - storage: 20Gi
+
+  resources:
+    memory_limit: 1Gi
+    disk_limit: 20Gi
+
+  security:
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/postgres-btcpay
+      target: /var/lib/postgresql/data
+      options: [rw]
+
+  environment:
+    - POSTGRES_DB=btcpay
+    - POSTGRES_USER=btcpay
+
+  health_check:
+    type: tcp
+    endpoint: localhost:5432
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: false
@@ -0,0 +1,51 @@
+app:
+  id: archy-mempool-db
+  name: Mempool MariaDB
+  version: 11.4.10
+  description: MariaDB backend for the mempool explorer stack.
+
+  container:
+    image: git.tx1138.com/lfg2025/mariadb:11.4.10
+    pull_policy: if-not-present
+    network: archy-net
+    data_uid: "100998:100998"
+    secret_env:
+      - key: MYSQL_PASSWORD
+        secret_file: mempool-db-password
+      - key: MYSQL_ROOT_PASSWORD
+        secret_file: mysql-root-db-password
+
+  dependencies:
+    - storage: 20Gi
+
+  resources:
+    memory_limit: 512Mi
+    disk_limit: 20Gi
+
+  security:
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/mysql-mempool
+      target: /var/lib/mysql
+      options: [rw]
+
+  environment:
+    - MYSQL_DATABASE=mempool
+    - MYSQL_USER=mempool
+
+  health_check:
+    type: tcp
+    endpoint: localhost:3306
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: false
@@ -0,0 +1,50 @@
+app:
+  id: archy-mempool-web
+  name: Mempool Web
+  version: 3.0.0
+  description: Frontend web UI for mempool explorer.
+  container_name: mempool
+
+  container:
+    image: git.tx1138.com/lfg2025/mempool-frontend:v3.0.0
+    pull_policy: if-not-present
+    network: archy-net
+
+  dependencies:
+    - app_id: mempool-api
+      version: ">=3.0.0"
+
+  resources:
+    memory_limit: 512Mi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 4080
+      container: 8080
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/mempool/nginx.conf
+      target: /etc/nginx/conf.d/default.conf
+      options: [ro]
+
+  environment:
+    - FRONTEND_HTTP_PORT=8080
+    - BACKEND_MAINNET_HTTP_HOST=mempool-api
+
+  health_check:
+    type: http
+    endpoint: http://localhost:8080
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: false
@@ -0,0 +1,62 @@
+app:
+  id: archy-nbxplorer
+  name: NBXplorer
+  version: 2.6.0
+  description: BTCPay blockchain indexer service.
+
+  container:
+    image: git.tx1138.com/lfg2025/nbxplorer:2.6.0
+    pull_policy: if-not-present
+    network: archy-net
+    secret_env:
+      - key: NBXPLORER_BTCRPCPASSWORD
+        secret_file: bitcoin-rpc-password
+      - key: BTCPAY_DB_PASS
+        secret_file: btcpay-db-password
+
+  dependencies:
+    - app_id: bitcoin-core
+      version: ">=26.0"
+    - app_id: archy-btcpay-db
+      version: ">=15.17"
+
+  resources:
+    memory_limit: 2Gi
+    disk_limit: 20Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 32838
+      container: 32838
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/nbxplorer
+      target: /data
+      options: [rw]
+
+  environment:
+    - NBXPLORER_DATADIR=/data
+    - NBXPLORER_NETWORK=mainnet
+    - NBXPLORER_CHAINS=btc
+    - NBXPLORER_BIND=0.0.0.0:32838
+    - NBXPLORER_BTCRPCURL=http://bitcoin-knots:8332
+    - NBXPLORER_BTCRPCUSER=archipelago
+    - NBXPLORER_POSTGRES=User ID=btcpay;Password=${BTCPAY_DB_PASS};Host=archy-btcpay-db;Port=5432;Database=nbxplorer;Include Error Detail=true
+
+  health_check:
+    type: http
+    endpoint: http://localhost:32838
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: read-only
+    sync_required: true
@@ -1,61 +1,70 @@
 app:
  id: bitcoin-core
-  name: Bitcoin Core
-  version: 24.0.0
-  description: Full Bitcoin node implementation. The reference implementation of the Bitcoin protocol.
-  
+  name: Bitcoin Knots
+  version: 28.4.0
+  description: Full Bitcoin Knots node with dynamic prune/full-mode startup based on host disk.
+
+  container_name: bitcoin-knots
+
  container:
-    image: bitcoin/bitcoin:24.0
-    image_signature: cosign://...
-    pull_policy: verify-signature
-    
+    image: 146.59.87.168:3000/lfg2025/bitcoin-knots:latest
+    pull_policy: if-not-present
+    network: archy-net
+    entrypoint: ["sh", "-lc"]
+    custom_args:
+      - >-
+        if [ "${DISK_GB:-0}" -lt 1000 ]; then
+          exec bitcoind -server=1 -prune=550 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=512 -rpcuser="${BITCOIN_RPC_USER}" -rpcpassword="${BITCOIN_RPC_PASS}";
+        else
+          exec bitcoind -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -rpcuser="${BITCOIN_RPC_USER}" -rpcpassword="${BITCOIN_RPC_PASS}";
+        fi
+    derived_env:
+      - key: DISK_GB
+        template: "{{DISK_GB}}"
+    secret_env:
+      - key: BITCOIN_RPC_PASS
+        secret_file: bitcoin-rpc-password
+    data_uid: "100101:100101"
+
  dependencies:
-    - storage: 500Gi  # Minimum disk space for mainnet
-    
+    - storage: 500Gi
+
  resources:
-    cpu_limit: 2
-    memory_limit: 2Gi
+    cpu_limit: 0
+    memory_limit: 4Gi
    disk_limit: 500Gi
-    
+
  security:
-    capabilities: []  # No special capabilities needed
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE]
+    readonly_root: false
    network_policy: isolated
-    apparmor_profile: bitcoin-core
-    
+
  ports:
    - host: 8332
      container: 8332
-      protocol: tcp  # RPC
+      protocol: tcp
    - host: 8333
      container: 8333
-      protocol: tcp  # P2P
-    
+      protocol: tcp
+
  volumes:
    - type: bind
      source: /var/lib/archipelago/bitcoin
      target: /home/bitcoin/.bitcoin
      options: [rw]
-      
+
  environment:
-    - NETWORK=mainnet
-    - RPC_USER=${BITCOIN_RPC_USER}
-    - RPC_PASSWORD=${BITCOIN_RPC_PASSWORD}
-    - PRUNE=0  # Full node (set to 550 for pruned)
-    
+    - BITCOIN_RPC_USER=archipelago
+
  health_check:
-    type: http
-    endpoint: http://localhost:8332
-    path: /
+    type: tcp
+    endpoint: localhost:8332
    interval: 30s
    timeout: 5s
    retries: 3
-    
+
  bitcoin_integration:
    rpc_access: admin
    sync_required: true
-    testnet_support: true
+    testnet_support: false
    pruning_support: true
@@ -0,0 +1,56 @@
+app:
+  id: bitcoin-ui
+  name: Bitcoin UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP proxy + static site for interacting with the
+    Bitcoin Core / Bitcoin Knots JSON-RPC. Runs nginx inside a container
+    and reverse-proxies /bitcoin-rpc/ to 127.0.0.1:8332 on the host. The
+    upstream Authorization header is substituted from
+    /var/lib/archipelago/secrets/bitcoin-rpc-password by the prod
+    orchestrator's pre-start hook, rendered into an nginx.conf that is
+    bind-mounted read-only at container start.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/bitcoin-ui
+      dockerfile: Dockerfile
+      tag: localhost/bitcoin-ui:local
+
+  dependencies:
+    - app_id: bitcoin-core
+
+  resources:
+    memory_limit: 128Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 8334 directly on the host IP, and
+  # proxies to 127.0.0.1:8332 which is where the bitcoin backend binds
+  # its RPC. `ports:` is intentionally empty because host networking
+  # bypasses port mapping.
+  ports: []
+
+  volumes:
+    # Bind-mount the rendered nginx.conf read-only. The prod orchestrator
+    # renders /var/lib/archipelago/bitcoin-ui/nginx.conf on every install
+    # and every reconcile pass, substituting the base64 RPC auth from
+    # the plaintext password secret. If the rendered bytes change (the
+    # password rotated, or the template was updated by OTA), the
+    # reconciler restarts this container so nginx re-reads the config.
+    - type: bind
+      source: /var/lib/archipelago/bitcoin-ui/nginx.conf
+      target: /etc/nginx/conf.d/default.conf
+      options: [ro]
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8334
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -1,66 +1,70 @@
 app:
  id: btcpay-server
  name: BTCPay Server
-  version: 1.12.0
+  version: 1.13.7
  description: Self-hosted Bitcoin payment processor. Accept Bitcoin payments without intermediaries.
-  
+
  container:
-    image: btcpayserver/btcpayserver:1.12.0
-    image_signature: cosign://...
-    pull_policy: verify-signature
-    
+    image: git.tx1138.com/lfg2025/btcpayserver:1.13.7
+    pull_policy: if-not-present
+    network: archy-net
+    secret_env:
+      - key: BTCPAY_BTCRPCPASSWORD
+        secret_file: bitcoin-rpc-password
+      - key: BTCPAY_DB_PASS
+        secret_file: btcpay-db-password
+
  dependencies:
    - app_id: bitcoin-core
      version: ">=26.0"
-    - app_id: lnd
-      version: ">=0.18.0"
-    
+    - app_id: archy-btcpay-db
+      version: ">=15.17"
+    - app_id: archy-nbxplorer
+      version: ">=2.6.0"
+
  resources:
    cpu_limit: 2
    memory_limit: 2Gi
    disk_limit: 20Gi
-    
+
  security:
-    capabilities: [NET_BIND_SERVICE]
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
+    capabilities: []
+    readonly_root: false
    network_policy: isolated
-    apparmor_profile: btcpay
-    
+
  ports:
-    - host: 80
-      container: 80
+    - host: 23000
+      container: 49392
      protocol: tcp
-    - host: 443
-      container: 443
-      protocol: tcp
-    
+
  volumes:
    - type: bind
      source: /var/lib/archipelago/btcpay
      target: /datadir
      options: [rw]
-      
+
  environment:
-    - BTCPAY_NETWORK=mainnet
-    - BTCPAY_CHAIN=btc
-    - BTCPAY_BTCEXPLORERURL=http://bitcoin-core:8332
-    - BTCPAY_LIGHTNING=type=lnd-rest;server=http://lnd:8080;allowinsecure=true
-    
+    - ASPNETCORE_URLS=http://0.0.0.0:49392
+    - BTCPAY_PROTOCOL=http
+    - BTCPAY_HOST=127.0.0.1:23000
+    - BTCPAY_CHAINS=btc
+    - BTCPAY_BTCEXPLORERURL=http://archy-nbxplorer:32838
+    - BTCPAY_BTCRPCURL=http://bitcoin-knots:8332
+    - BTCPAY_BTCRPCUSER=archipelago
+    - BTCPAY_POSTGRES=User ID=btcpay;Password=${BTCPAY_DB_PASS};Host=archy-btcpay-db;Port=5432;Database=btcpay;Include Error Detail=true
+
  health_check:
    type: http
-    endpoint: http://localhost
-    path: /health
+    endpoint: http://localhost:49392
+    path: /
    interval: 30s
    timeout: 5s
    retries: 3
-    
+
  bitcoin_integration:
    rpc_access: read-only
    sync_required: true
-    
+
  lightning_integration:
-    payment_processing: true
+    payment_processing: false
    invoice_management: true
@@ -0,0 +1,38 @@
+app:
+  id: electrs-ui
+  name: Electrs UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP frontend for electrs/electrumx status. Runs
+    nginx inside a container, serves static assets, and proxies
+    /electrs-status to the archipelago backend on 127.0.0.1:5678.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/electrs-ui
+      dockerfile: Dockerfile
+      tag: localhost/electrs-ui:local
+
+  dependencies: []
+
+  resources:
+    memory_limit: 64Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 50002 directly on the host IP.
+  ports: []
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:50002
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -0,0 +1,60 @@
+app:
+  id: electrumx
+  name: ElectrumX
+  version: 1.18.0
+  description: Electrum server indexing Bitcoin chain data for lightweight wallet queries.
+
+  container:
+    image: git.tx1138.com/lfg2025/electrumx:v1.18.0
+    pull_policy: if-not-present
+    network: archy-net
+    entrypoint: ["sh", "-lc"]
+    custom_args:
+      - >-
+        export DAEMON_URL="http://archipelago:${BITCOIN_RPC_PASS}@bitcoin-knots:8332/";
+        exec electrumx_server
+    secret_env:
+      - key: BITCOIN_RPC_PASS
+        secret_file: bitcoin-rpc-password
+
+  dependencies:
+    - app_id: bitcoin-core
+      version: ">=26.0"
+    - storage: 50Gi
+
+  resources:
+    cpu_limit: 2
+    memory_limit: 2Gi
+    disk_limit: 50Gi
+
+  security:
+    capabilities: [DAC_OVERRIDE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 50001
+      container: 50001
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/electrumx
+      target: /data
+      options: [rw]
+
+  environment:
+    - COIN=Bitcoin
+    - DB_DIRECTORY=/data
+    - SERVICES=tcp://:50001,rpc://0.0.0.0:8000
+
+  health_check:
+    type: tcp
+    endpoint: localhost:50001
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: read-only
+    sync_required: true
@@ -1,6 +0,0 @@
-node_modules
-dist
-*.log
-.git
-.gitignore
-README.md
@@ -1,37 +0,0 @@
-FROM node:20-alpine AS builder
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-RUN npm ci --only=production
-
-# Copy source code
-COPY . .
-
-# Build the application
-RUN npm run build
-
-# Production stage
-FROM node:20-alpine
-
-WORKDIR /app
-
-# Copy built application
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-
-# Create non-root user
-RUN addgroup -g 1000 appuser && \
-    adduser -D -u 1000 -G appuser appuser && \
-    mkdir -p /app/data && \
-    chown -R appuser:appuser /app
-
-USER appuser
-
-EXPOSE 8080
-
-ENV ENDURAIN_DATA_DIR=/app/data
-
-CMD ["node", "dist/index.js"]
@@ -1,50 +0,0 @@
-app:
-  id: endurain
-  name: Endurain
-  version: 1.0.0
-  description: Endurain application platform. Custom application runtime.
-  
-  container:
-    image: archipelago/endurain:1.0.0
-    image_signature: cosign://...
-    pull_policy: if-not-present
-    
-  dependencies:
-    - storage: 2Gi
-    
-  resources:
-    cpu_limit: 2
-    memory_limit: 1Gi
-    disk_limit: 2Gi
-    
-  security:
-    capabilities: []
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
-    network_policy: isolated
-    apparmor_profile: endurain
-    
-  ports:
-    - host: 8085
-      container: 8080
-      protocol: tcp  # Web UI
-    
-  volumes:
-    - type: bind
-      source: /var/lib/archipelago/endurain
-      target: /app/data
-      options: [rw]
-      
-  environment:
-    - ENDURAIN_ENV=production
-    - ENDURAIN_DATA_DIR=/app/data
-    
-  health_check:
-    type: http
-    endpoint: http://localhost:8085
-    path: /health
-    interval: 30s
-    timeout: 5s
-    retries: 3
@@ -1,20 +0,0 @@
-{
-  "name": "endurain",
-  "version": "1.0.0",
-  "description": "Endurain application platform",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "ts-node src/index.ts"
-  },
-  "dependencies": {
-    "express": "^4.18.2"
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.10.0",
-    "typescript": "^5.3.3",
-    "ts-node": "^10.9.2"
-  }
-}
@@ -1,27 +0,0 @@
-import express from 'express';
-
-const app = express();
-const port = 8080;
-
-// Middleware
-app.use(express.json());
-
-// Health check endpoint
-app.get('/health', (req, res) => {
-  res.json({ status: 'ok', service: 'endurain', version: '1.0.0' });
-});
-
-// API endpoints
-app.get('/api/info', (req, res) => {
-  res.json({
-    name: 'Endurain',
-    version: '1.0.0',
-    status: 'running'
-  });
-});
-
-// Start server
-app.listen(port, '0.0.0.0', () => {
-  console.log(`Endurain listening on port ${port}`);
-  console.log(`Data directory: ${process.env.ENDURAIN_DATA_DIR || '/app/data'}`);
-});
@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
@@ -0,0 +1,73 @@
+app:
+  id: fedimint-gateway
+  name: Fedimint Gateway
+  version: 0.10.0
+  description: Fedimint gateway service with automatic LND-or-LDK backend selection.
+
+  container:
+    image: git.tx1138.com/lfg2025/gatewayd:v0.10.0
+    pull_policy: if-not-present
+    network: archy-net
+    entrypoint: ["sh", "-lc"]
+    custom_args:
+      - >-
+        if [ -f /lnd/tls.cert ] && [ -f /lnd/data/chain/bitcoin/mainnet/admin.macaroon ]; then
+          exec gatewayd --data-dir /data --listen 0.0.0.0:8176 --bcrypt-password-hash "$FEDI_HASH" --network bitcoin --bitcoind-url http://bitcoin-knots:8332 --bitcoind-username "$FM_BITCOIND_USERNAME" --bitcoind-password "$FM_BITCOIND_PASSWORD" lnd --lnd-rpc-host lnd:10009 --lnd-tls-cert /lnd/tls.cert --lnd-macaroon /lnd/data/chain/bitcoin/mainnet/admin.macaroon;
+        else
+          exec gatewayd --data-dir /data --listen 0.0.0.0:8176 --bcrypt-password-hash "$FEDI_HASH" --network bitcoin --bitcoind-url http://bitcoin-knots:8332 --bitcoind-username "$FM_BITCOIND_USERNAME" --bitcoind-password "$FM_BITCOIND_PASSWORD" ldk --ldk-lightning-port 9737 --ldk-alias archipelago-gateway;
+        fi
+    secret_env:
+      - key: FM_BITCOIND_PASSWORD
+        secret_file: bitcoin-rpc-password
+      - key: FEDI_HASH
+        secret_file: fedimint-gateway-hash
+    data_uid: "100000:100000"
+
+  dependencies:
+    - app_id: bitcoin-core
+      version: ">=26.0"
+    - app_id: fedimint
+      version: ">=0.10.0"
+
+  resources:
+    cpu_limit: 2
+    memory_limit: 2Gi
+    disk_limit: 10Gi
+
+  security:
+    capabilities: []
+    readonly_root: true
+    network_policy: isolated
+
+  ports:
+    - host: 8176
+      container: 8176
+      protocol: tcp
+    - host: 9737
+      container: 9737
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/fedimint-gateway
+      target: /data
+      options: [rw]
+    - type: bind
+      source: /var/lib/archipelago/lnd
+      target: /lnd
+      options: [ro]
+
+  environment:
+    - FM_BITCOIND_USERNAME=archipelago
+
+  health_check:
+    type: http
+    endpoint: http://localhost:8176
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: admin
+    sync_required: true
@@ -3,56 +3,62 @@ app:
  name: Fedimint
  version: 0.10.0
  description: Federated Bitcoin minting service with built-in Guardian UI. Privacy-preserving Bitcoin custody.
-  
+
  container:
-    image: fedimint/fedimintd:v0.10.0
-    image_signature: cosign://...
+    image: git.tx1138.com/lfg2025/fedimintd:v0.10.0
    pull_policy: if-not-present
-    
+    network: archy-net
+    derived_env:
+      - key: FM_P2P_URL
+        template: fedimint://{{HOST_MDNS}}:8173
+      - key: FM_API_URL
+        template: ws://{{HOST_MDNS}}:8174
+    secret_env:
+      - key: FM_BITCOIND_PASSWORD
+        secret_file: bitcoin-rpc-password
+    data_uid: "100000:100000"
+
  dependencies:
    - app_id: bitcoin-core
-      version: ">=24.0"
+      version: ">=26.0"
    - storage: 20Gi
-    
+
  resources:
    cpu_limit: 4
    memory_limit: 4Gi
    disk_limit: 20Gi
-    
+
  security:
    capabilities: []
    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
    network_policy: isolated
-    apparmor_profile: fedimint
-    
+
  ports:
    - host: 8173
      container: 8173
-      protocol: tcp  # P2P
+      protocol: tcp
    - host: 8174
      container: 8174
-      protocol: tcp  # API
+      protocol: tcp
    - host: 8175
      container: 8175
-      protocol: tcp  # Built-in Guardian UI
-    
+      protocol: tcp
+
  volumes:
    - type: bind
      source: /var/lib/archipelago/fedimint
-      target: /fedimint
+      target: /data
      options: [rw]
-      
+
  environment:
-    - FM_DATA_DIR=/fedimint
-    - FM_BITCOIND_URL=http://bitcoin-core:8332
-    - FM_BITCOIND_USERNAME=${BITCOIN_RPC_USER}
-    - FM_BITCOIND_PASSWORD=${BITCOIN_RPC_PASSWORD}
+    - FM_DATA_DIR=/data
+    - FM_BITCOIND_URL=http://bitcoin-knots:8332
+    - FM_BITCOIND_USERNAME=archipelago
    - FM_BITCOIN_NETWORK=bitcoin
+    - FM_BIND_P2P=0.0.0.0:8173
+    - FM_BIND_API=0.0.0.0:8174
    - FM_BIND_UI=0.0.0.0:8175
-    
+
  health_check:
    type: http
    endpoint: http://localhost:8175
@@ -60,7 +66,7 @@ app:
    interval: 30s
    timeout: 5s
    retries: 3
-    
+
  bitcoin_integration:
    rpc_access: admin
    sync_required: true
@@ -0,0 +1,53 @@
+app:
+  id: filebrowser
+  name: File Browser
+  version: 2.27.0
+  description: Baseline Archipelago file manager service.
+
+  container:
+    image: git.tx1138.com/lfg2025/filebrowser:v2.27.0
+    pull_policy: if-not-present
+    network: archy-net
+    custom_args: ["--config", "/data/.filebrowser.json"]
+    data_uid: "100000:100000"
+
+  dependencies:
+    - storage: 10Gi
+
+  resources:
+    memory_limit: 256Mi
+    disk_limit: 10Gi
+
+  security:
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_BIND_SERVICE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 8083
+      container: 80
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/filebrowser
+      target: /srv
+      options: [rw]
+    - type: bind
+      source: /var/lib/archipelago/filebrowser-data
+      target: /data
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://localhost:80
+    path: /health
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: false
@@ -6,7 +6,7 @@ app:
  category: media

  container:
-    image: git.tx1138.com/lfg2025/indeedhub:latest
+    image: 146.59.87.168:3000/lfg2025/indeedhub:latest
    pull_policy: always  # Pull from registry; falls back to local build

  dependencies:
@@ -0,0 +1,44 @@
+app:
+  id: lnd-ui
+  name: LND UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP frontend for LND. Runs nginx inside a
+    container and serves static assets. LND connection info is fetched
+    via an absolute URL that the host nginx routes to the archipelago
+    backend on 127.0.0.1:5678, so no upstream auth is baked in.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/lnd-ui
+      dockerfile: Dockerfile
+      tag: localhost/lnd-ui:local
+
+  dependencies:
+    - app_id: lnd
+
+  resources:
+    memory_limit: 64Mi
+
+  security:
+    readonly_root: false
+    network_policy: bridge
+
+  # Bridge networking via archy-net. Container nginx listens on 80;
+  # host nginx proxies /app/lnd/ -> 127.0.0.1:8081 -> container:80.
+  ports:
+    - host: 8081
+      container: 80
+      protocol: tcp
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8081
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -1,67 +1,65 @@
 app:
  id: lnd
  name: Lightning Network Daemon
-  version: 0.18.0
+  version: 0.18.4
  description: Lightning Network implementation by Lightning Labs. Enables instant, low-cost Bitcoin payments.
-  
+
  container:
-    image: lightninglabs/lnd:v0.18.0
-    image_signature: cosign://...
-    pull_policy: verify-signature
-    
+    image: git.tx1138.com/lfg2025/lnd:v0.18.4-beta
+    pull_policy: if-not-present
+    network: archy-net
+    secret_env:
+      - key: BITCOIND_RPCPASS
+        secret_file: bitcoin-rpc-password
+    data_uid: "100000:100000"
+
  dependencies:
    - app_id: bitcoin-core
      version: ">=26.0"
-    
+
  resources:
    cpu_limit: 2
    memory_limit: 1Gi
    disk_limit: 10Gi
-    
+
  security:
-    capabilities: [NET_BIND_SERVICE]
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_RAW]
+    readonly_root: false
    network_policy: isolated
-    apparmor_profile: lnd
-    
+
  ports:
    - host: 9735
      container: 9735
-      protocol: tcp  # P2P
+      protocol: tcp
    - host: 10009
      container: 10009
-      protocol: tcp  # gRPC
+      protocol: tcp
    - host: 8080
      container: 8080
-      protocol: tcp  # REST
-    
+      protocol: tcp
+
  volumes:
    - type: bind
      source: /var/lib/archipelago/lnd
      target: /root/.lnd
      options: [rw]
-      
+
  environment:
-    - BITCOIND_HOST=bitcoin-core
-    - BITCOIND_RPCUSER=${BITCOIN_RPC_USER}
-    - BITCOIND_RPCPASS=${BITCOIN_RPC_PASSWORD}
+    - BITCOIND_HOST=bitcoin-knots
+    - BITCOIND_RPCUSER=archipelago
    - NETWORK=mainnet
-    
+
  health_check:
-    type: http
-    endpoint: http://localhost:8080
-    path: /v1/getinfo
+    type: tcp
+    endpoint: localhost:10009
    interval: 30s
    timeout: 5s
    retries: 3
-    
+
  bitcoin_integration:
    rpc_access: admin
    sync_required: true
-    
+
  lightning_integration:
    channel_management: true
    payment_routing: true
@@ -0,0 +1,68 @@
+app:
+  id: mempool-api
+  name: Mempool API
+  version: 3.0.0
+  description: Backend API for mempool explorer.
+
+  container:
+    image: git.tx1138.com/lfg2025/mempool-backend:v3.0.0
+    pull_policy: if-not-present
+    network: archy-net
+    secret_env:
+      - key: CORE_RPC_PASSWORD
+        secret_file: bitcoin-rpc-password
+      - key: DATABASE_PASSWORD
+        secret_file: mempool-db-password
+
+  dependencies:
+    - app_id: bitcoin-core
+      version: ">=26.0"
+    - app_id: electrumx
+      version: ">=1.18.0"
+    - app_id: archy-mempool-db
+      version: ">=11.4.10"
+
+  resources:
+    memory_limit: 2Gi
+    disk_limit: 20Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 8999
+      container: 8999
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/mempool
+      target: /data
+      options: [rw]
+
+  environment:
+    - MEMPOOL_BACKEND=electrum
+    - ELECTRUM_HOST=electrumx
+    - ELECTRUM_PORT=50001
+    - ELECTRUM_TLS_ENABLED=false
+    - CORE_RPC_HOST=bitcoin-knots
+    - CORE_RPC_PORT=8332
+    - CORE_RPC_USERNAME=archipelago
+    - DATABASE_ENABLED=true
+    - DATABASE_HOST=archy-mempool-db
+    - DATABASE_DATABASE=mempool
+    - DATABASE_USERNAME=mempool
+
+  health_check:
+    type: http
+    endpoint: http://localhost:8999
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
+
+  bitcoin_integration:
+    rpc_access: read-only
+    sync_required: true
@@ -1,5 +0,0 @@
-# Ollama - uses official image
-FROM ollama/ollama:latest
-
-# Default configuration is in the image
-# No additional setup needed
@@ -1,50 +0,0 @@
-app:
-  id: ollama
-  name: Ollama
-  version: 0.1.0
-  description: Run large language models locally. Privacy-preserving AI on your node.
-  
-  container:
-    image: ollama/ollama:0.6.2
-    image_signature: cosign://...
-    pull_policy: if-not-present
-    
-  dependencies:
-    - storage: 50Gi  # Models can be large
-    
-  resources:
-    cpu_limit: 4
-    memory_limit: 8Gi  # LLMs need lots of RAM
-    disk_limit: 50Gi
-    
-  security:
-    capabilities: []
-    readonly_root: false  # Ollama needs write access for models
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
-    network_policy: isolated
-    apparmor_profile: ollama
-    
-  ports:
-    - host: 11434
-      container: 11434
-      protocol: tcp  # API
-    
-  volumes:
-    - type: bind
-      source: /var/lib/archipelago/ollama
-      target: /root/.ollama
-      options: [rw]
-      
-  environment:
-    - OLLAMA_HOST=0.0.0.0:11434
-    - OLLAMA_KEEP_ALIVE=24h
-    
-  health_check:
-    type: http
-    endpoint: http://localhost:11434
-    path: /api/tags
-    interval: 30s
-    timeout: 10s
-    retries: 3
@@ -1,5 +0,0 @@
-# Penpot - uses official image
-FROM penpot/penpot:latest
-
-# Default configuration is in the image
-# No additional setup needed
@@ -1,51 +0,0 @@
-app:
-  id: penpot
-  name: Penpot
-  version: 2.0.0
-  description: Open-source design and prototyping platform. Design tools for teams.
-  
-  container:
-    image: penpotapp/frontend:2.13.3
-    image_signature: cosign://...
-    pull_policy: if-not-present
-    
-  dependencies:
-    - storage: 10Gi
-    
-  resources:
-    cpu_limit: 4
-    memory_limit: 4Gi
-    disk_limit: 10Gi
-    
-  security:
-    capabilities: []
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
-    network_policy: isolated
-    apparmor_profile: penpot
-    
-  ports:
-    - host: 8089
-      container: 80
-      protocol: tcp  # Web UI
-    
-  volumes:
-    - type: bind
-      source: /var/lib/archipelago/penpot
-      target: /app/data
-      options: [rw]
-      
-  environment:
-    - PENPOT_PUBLIC_URI=http://localhost:8089
-    - PENPOT_DATABASE_URI=postgresql://penpot:penpot@penpot-db:5432/penpot
-    - PENPOT_REDIS_URI=redis://penpot-redis:6379
-    
-  health_check:
-    type: http
-    endpoint: http://localhost:8089
-    path: /api/health
-    interval: 30s
-    timeout: 5s
-    retries: 3
@@ -80,13 +80,14 @@ checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"

 [[package]]
 name = "archipelago"
-version = "1.7.7-alpha"
+version = "1.7.45-alpha"
 dependencies = [
 "anyhow",
 "archipelago-container",
 "archipelago-performance",
 "archipelago-security",
 "argon2",
+ "async-trait",
 "base64 0.21.7",
 "bcrypt",
 "bip39",
@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.7.7-alpha"
+version = "1.7.45-alpha"
 edition = "2021"
 description = "Archipelago Bitcoin Node OS - Native backend"
 authors = ["Archipelago Team"]
@@ -103,6 +103,9 @@ mdns-sd = "0.18"
 # Systemd watchdog notification
 sd-notify = "0.4"

+# Trait objects for async methods (container orchestrator trait, Step 4)
+async-trait = "0.1"
+
 [dev-dependencies]
 tokio-test = "0.4"
 tempfile = "3.10"
@@ -10,6 +10,7 @@ mod websocket;
 use crate::api::rpc::RpcHandler;
 use crate::blobs::BlobStore;
 use crate::config::Config;
+use crate::container::{ContainerOrchestrator, DevContainerOrchestrator};
 use crate::monitoring::MetricsStore;
 use crate::session::{self, SessionStore};
 use crate::state::StateManager;
@@ -54,6 +55,8 @@ impl ApiHandler {
        config: Config,
        state_manager: Arc<StateManager>,
        metrics_store: Arc<MetricsStore>,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    ) -> Result<Self> {
        let session_store = SessionStore::new().await;
        let rpc_handler = Arc::new(
@@ -62,6 +65,8 @@ impl ApiHandler {
                state_manager.clone(),
                metrics_store.clone(),
                session_store.clone(),
+                orchestrator,
+                dev_orchestrator,
            )
            .await?,
        );
@@ -113,6 +118,79 @@ impl ApiHandler {
        }
    }

+    /// Server-side fetch of the upstream app catalog so the browser can
+    /// load it without fighting CORS (git.tx1138.com emits no ACAO) or
+    /// CSP (the fallback IP-port URL isn't in `connect-src`). The upstream
+    /// list is derived from the operator's configured container registries
+    /// so switching mirrors in Settings changes the App Store source too —
+    /// each active registry contributes one Gitea `raw/branch/main/catalog.json`
+    /// URL (http or https per `tls_verify`), tried in priority order.
+    /// If registry config can't be loaded, falls back to the legacy
+    /// hardcoded pair so the App Store still renders on nodes that haven't
+    /// persisted a registry config yet. 15s total timeout.
+    async fn handle_app_catalog_proxy(&self) -> Result<Response<hyper::Body>> {
+        let mut upstreams: Vec<String> = Vec::new();
+        if let Ok(config) = crate::container::registry::load_registries(&self.config.data_dir).await
+        {
+            for reg in config.active_registries() {
+                let scheme = if reg.tls_verify { "https" } else { "http" };
+                // Gitea raw URL: <scheme>://<host>/<namespace>/app-catalog/raw/branch/main/catalog.json.
+                // reg.url already includes the namespace (e.g. "host/lfg2025"),
+                // so we just tack on the repo + raw path.
+                upstreams.push(format!(
+                    "{}://{}/app-catalog/raw/branch/main/catalog.json",
+                    scheme, reg.url
+                ));
+            }
+        }
+        if upstreams.is_empty() {
+            upstreams.push(
+                "http://146.59.87.168:3000/lfg2025/app-catalog/raw/branch/main/catalog.json"
+                    .to_string(),
+            );
+            upstreams.push(
+                "https://git.tx1138.com/lfg2025/app-catalog/raw/branch/main/catalog.json"
+                    .to_string(),
+            );
+        }
+
+        let client = match reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(15))
+            .build()
+        {
+            Ok(c) => c,
+            Err(e) => {
+                return Ok(build_response(
+                    hyper::StatusCode::INTERNAL_SERVER_ERROR,
+                    "text/plain",
+                    hyper::Body::from(format!("client build failed: {}", e)),
+                ));
+            }
+        };
+        for url in &upstreams {
+            match client.get(url).send().await {
+                Ok(resp) if resp.status().is_success() => {
+                    if let Ok(bytes) = resp.bytes().await {
+                        return Ok(Response::builder()
+                            .status(hyper::StatusCode::OK)
+                            .header("Content-Type", "application/json")
+                            .header("Cache-Control", "public, max-age=3600")
+                            .body(hyper::Body::from(bytes))
+                            .unwrap_or_else(|_| {
+                                Response::new(hyper::Body::from("proxy response build failed"))
+                            }));
+                    }
+                }
+                _ => continue,
+            }
+        }
+        Ok(build_response(
+            hyper::StatusCode::BAD_GATEWAY,
+            "text/plain",
+            hyper::Body::from("all upstream catalog URLs failed"),
+        ))
+    }
+
    /// Build a 401 Unauthorized JSON response.
    fn unauthorized() -> Response<hyper::Body> {
        let body = serde_json::json!({ "error": "Unauthorized" });
@@ -242,7 +320,7 @@ impl ApiHandler {

        match (method, path.as_str()) {
            // RPC — auth is handled inside rpc handler per-method
-            (Method::POST, "/rpc/v1") => self.rpc_handler.handle(req_with_bytes).await,
+            (Method::POST, "/rpc/v1") => self.rpc_handler.clone().handle(req_with_bytes).await,

            // Health — unauthenticated, returns JSON with service status
            (Method::GET, "/health") => {
@@ -352,6 +430,18 @@ impl ApiHandler {
            // Electrs status — unauthenticated (read-only sync status)
            (Method::GET, "/electrs-status") => Self::handle_electrs_status().await,

+            // App-catalog proxy — fetches catalog.json from the configured
+            // upstream URLs server-side so the browser doesn't hit CORS
+            // (git.tx1138.com has no ACAO header) or CSP (IP-port upstream
+            // falls outside `connect-src`). Session-authenticated so only
+            // the logged-in node owner can spin up fetches.
+            (Method::GET, "/api/app-catalog") => {
+                if !self.is_authenticated(&headers).await {
+                    return Ok(Self::unauthorized());
+                }
+                self.handle_app_catalog_proxy().await
+            }
+
            // LND connect info — nginx validates session cookie (presence check),
            // backend is bound to 127.0.0.1 so only nginx can reach it.
            // No backend auth check here because the LND UI iframe fetches this
@@ -3,6 +3,55 @@ use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use zeroize::Zeroize;

+/// Retry configuration for [`bitcoin_rpc_post_with_retry`].
+///
+/// Exposed as a struct (rather than hard-coded constants inside the function)
+/// so tests can dial down timeouts to keep the suite fast while still
+/// exercising real retry/backoff behavior.
+#[derive(Debug, Clone)]
+struct RetryConfig {
+    max_attempts: u32,
+    attempt_timeout: std::time::Duration,
+    /// Length must equal `max_attempts - 1` (one backoff between each
+    /// successive attempt). The last attempt is not followed by a backoff.
+    backoffs: Vec<std::time::Duration>,
+}
+
+impl RetryConfig {
+    /// Production retry policy: 3 attempts, 15s each, 500ms + 1500ms backoffs.
+    /// Total worst-case wall time: 3 * 15 + 0.5 + 1.5 = 47s.
+    fn production() -> Self {
+        Self {
+            max_attempts: BITCOIN_RPC_MAX_ATTEMPTS,
+            attempt_timeout: BITCOIN_RPC_ATTEMPT_TIMEOUT,
+            backoffs: BITCOIN_RPC_BACKOFFS.to_vec(),
+        }
+    }
+}
+
+/// Max retry attempts for a single bitcoin_rpc_call invocation.
+/// First attempt + 2 retries = 3 total.
+const BITCOIN_RPC_MAX_ATTEMPTS: u32 = 3;
+
+/// Per-attempt deadline. Must be >= the reqwest client's own timeout (we
+/// build it at 15s in handle_bitcoin_getinfo) — this is the outer safety net.
+const BITCOIN_RPC_ATTEMPT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(15);
+
+/// Backoff between attempts. Index 0 = after first failure, 1 = after second, etc.
+/// Chosen to absorb bitcoind's typical block-validation stall (2-5s) without
+/// adding noticeable latency on the happy path (first attempt succeeds in ~30ms).
+const BITCOIN_RPC_BACKOFFS: [std::time::Duration; 2] = [
+    std::time::Duration::from_millis(500),
+    std::time::Duration::from_millis(1500),
+];
+
+/// Classify a reqwest error as transient (retryable) or fatal.
+/// Transient: timeout, connect refused, request/response body IO errors.
+/// Fatal: TLS errors, URL parse errors, redirect loops, builder errors.
+fn is_transient_transport_error(e: &reqwest::Error) -> bool {
+    e.is_timeout() || e.is_connect() || e.is_request() || e.is_body()
+}
+
 #[derive(Debug, Serialize)]
 struct BitcoinInfo {
    block_height: u64,
@@ -37,8 +86,15 @@ struct MempoolInfo {

 impl RpcHandler {
    pub(super) async fn handle_bitcoin_getinfo(&self) -> Result<serde_json::Value> {
+        // Per-attempt timeout (see bitcoin_rpc_call for retry semantics).
+        // 15s is enough room for bitcoind to answer getblockchaininfo even
+        // during block validation; bitcoin_rpc_call wraps each attempt in a
+        // separate tokio::time::timeout too, so this is belt-and-suspenders.
+        // connect_timeout is tighter so a dead bitcoind doesn't steal the
+        // whole attempt budget on TCP connect alone.
        let client = reqwest::Client::builder()
-            .timeout(std::time::Duration::from_secs(10))
+            .timeout(std::time::Duration::from_secs(15))
+            .connect_timeout(std::time::Duration::from_secs(3))
            .build()
            .context("Failed to create HTTP client")?;

@@ -68,6 +124,19 @@ impl RpcHandler {
        Ok(serde_json::to_value(info)?)
    }

+    /// Call a Bitcoin Core JSON-RPC method.
+    ///
+    /// Retries up to [`BITCOIN_RPC_MAX_ATTEMPTS`] times on transient
+    /// transport errors (timeout / connection refused / send/recv IO).
+    /// Does **not** retry when bitcoind responds with a well-formed
+    /// `{"error": ...}` body — those are real RPC errors and surfacing
+    /// them quickly is the right behavior.
+    ///
+    /// Motivation: on a syncing pruned node, bitcoind's RPC thread can block
+    /// for 5-10 seconds during block validation. A single 10s timeout means
+    /// ~30% of UI calls error out even though the node is perfectly healthy.
+    /// With retry + backoff, the UI sees a uniform slow-but-successful
+    /// response instead of intermittent failures.
    async fn bitcoin_rpc_call<T: serde::de::DeserializeOwned>(
        &self,
        client: &reqwest::Client,
@@ -75,33 +144,15 @@ impl RpcHandler {
        params: &[serde_json::Value],
    ) -> Result<T> {
        let (rpc_user, rpc_pass) = crate::bitcoin_rpc::bitcoin_rpc_credentials().await;
-        let body = serde_json::json!({
-            "jsonrpc": "1.0",
-            "id": "archy",
-            "method": method,
-            "params": params,
-        });
-
-        let resp = client
-            .post(crate::constants::BITCOIN_RPC_URL)
-            .basic_auth(&rpc_user, Some(&rpc_pass))
-            .json(&body)
-            .send()
-            .await
-            .context("Bitcoin RPC connection failed")?;
-
-        let rpc_resp: BitcoinRpcResponse<T> = resp
-            .json()
-            .await
-            .context("Failed to parse Bitcoin RPC response")?;
-
-        if let Some(err) = rpc_resp.error {
-            anyhow::bail!("Bitcoin RPC error: {}", err);
-        }
-
-        rpc_resp
-            .result
-            .ok_or_else(|| anyhow::anyhow!("Bitcoin RPC returned null result"))
+        bitcoin_rpc_post_with_retry(
+            client,
+            crate::constants::BITCOIN_RPC_URL,
+            &rpc_user,
+            &rpc_pass,
+            method,
+            params,
+        )
+        .await
    }

    /// Initialize a Bitcoin Core descriptor wallet with keys derived from the master seed.
@@ -243,3 +294,351 @@ impl RpcHandler {
        }))
    }
 }
+
+/// Free-function counterpart to `RpcHandler::bitcoin_rpc_call`.
+///
+/// Takes the URL + credentials as parameters so it can be exercised by unit
+/// tests against a mock HTTP server without constructing a full `RpcHandler`.
+///
+/// Production callers go through `RpcHandler::bitcoin_rpc_call`, which loads
+/// credentials from the secrets file and points at `BITCOIN_RPC_URL`.
+async fn bitcoin_rpc_post_with_retry<T: serde::de::DeserializeOwned>(
+    client: &reqwest::Client,
+    url: &str,
+    rpc_user: &str,
+    rpc_pass: &str,
+    method: &str,
+    params: &[serde_json::Value],
+) -> Result<T> {
+    bitcoin_rpc_post_with_retry_cfg(
+        client,
+        url,
+        rpc_user,
+        rpc_pass,
+        method,
+        params,
+        &RetryConfig::production(),
+    )
+    .await
+}
+
+/// Inner implementation with configurable retry policy (for tests).
+async fn bitcoin_rpc_post_with_retry_cfg<T: serde::de::DeserializeOwned>(
+    client: &reqwest::Client,
+    url: &str,
+    rpc_user: &str,
+    rpc_pass: &str,
+    method: &str,
+    params: &[serde_json::Value],
+    cfg: &RetryConfig,
+) -> Result<T> {
+    debug_assert_eq!(
+        cfg.backoffs.len(),
+        (cfg.max_attempts - 1) as usize,
+        "RetryConfig: backoffs.len() must equal max_attempts - 1"
+    );
+
+    let body = serde_json::json!({
+        "jsonrpc": "1.0",
+        "id": "archy",
+        "method": method,
+        "params": params,
+    });
+
+    let mut last_err: Option<anyhow::Error> = None;
+    for attempt in 0..cfg.max_attempts {
+        if attempt > 0 {
+            let backoff = cfg
+                .backoffs
+                .get(attempt as usize - 1)
+                .copied()
+                .unwrap_or_else(|| std::time::Duration::from_secs(2));
+            tracing::warn!(
+                "bitcoin_rpc({}): attempt {} failed, backing off {:?}",
+                method,
+                attempt,
+                backoff
+            );
+            tokio::time::sleep(backoff).await;
+        }
+
+        // Per-attempt hard deadline. Independent of reqwest's built-in timeout
+        // so we always cap total time even if reqwest blocks on something
+        // weird (e.g., DNS starvation).
+        let fut = client
+            .post(url)
+            .basic_auth(rpc_user, Some(rpc_pass))
+            .json(&body)
+            .send();
+
+        let send_result = match tokio::time::timeout(cfg.attempt_timeout, fut).await {
+            Err(_elapsed) => {
+                last_err = Some(anyhow::anyhow!(
+                    "Bitcoin RPC send timed out after {:?}",
+                    cfg.attempt_timeout
+                ));
+                continue; // transient: retry
+            }
+            Ok(r) => r,
+        };
+
+        let resp = match send_result {
+            Ok(r) => r,
+            Err(e) if is_transient_transport_error(&e) => {
+                last_err = Some(anyhow::Error::from(e).context("Bitcoin RPC connection failed"));
+                continue; // transient: retry
+            }
+            Err(e) => {
+                return Err(anyhow::Error::from(e).context("Bitcoin RPC connection failed"));
+            }
+        };
+
+        let rpc_resp: BitcoinRpcResponse<T> = resp
+            .json()
+            .await
+            .context("Failed to parse Bitcoin RPC response")?;
+
+        if let Some(err) = rpc_resp.error {
+            // RPC-level error: this is a real bitcoind response, not transient.
+            anyhow::bail!("Bitcoin RPC error: {}", err);
+        }
+
+        return rpc_resp
+            .result
+            .ok_or_else(|| anyhow::anyhow!("Bitcoin RPC returned null result"));
+    }
+
+    Err(last_err
+        .unwrap_or_else(|| anyhow::anyhow!("Bitcoin RPC exhausted retries with no error captured")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use hyper::service::{make_service_fn, service_fn};
+    use hyper::{Body, Request, Response, Server, StatusCode};
+    use std::convert::Infallible;
+    use std::net::SocketAddr;
+    use std::sync::atomic::{AtomicU32, Ordering};
+    use std::sync::Arc;
+
+    /// Spin up a mock bitcoind HTTP server that behaves according to `handler`.
+    /// Returns the bound URL and a JoinHandle (dropped = server shutdown via the
+    /// oneshot cancel channel).
+    async fn spawn_mock<F, Fut>(
+        handler: F,
+    ) -> (
+        String,
+        tokio::task::JoinHandle<()>,
+        tokio::sync::oneshot::Sender<()>,
+    )
+    where
+        F: Fn(Request<Body>) -> Fut + Send + Sync + Clone + 'static,
+        Fut: std::future::Future<Output = Response<Body>> + Send + 'static,
+    {
+        let addr = SocketAddr::from(([127, 0, 0, 1], 0));
+        let make_svc = make_service_fn(move |_| {
+            let handler = handler.clone();
+            async move {
+                Ok::<_, Infallible>(service_fn(move |req| {
+                    let handler = handler.clone();
+                    async move { Ok::<_, Infallible>(handler(req).await) }
+                }))
+            }
+        });
+        let server = Server::bind(&addr).serve(make_svc);
+        let url = format!("http://{}", server.local_addr());
+        let (tx, rx) = tokio::sync::oneshot::channel::<()>();
+        let handle = tokio::spawn(async move {
+            let graceful = server.with_graceful_shutdown(async {
+                let _ = rx.await;
+            });
+            let _ = graceful.await;
+        });
+        (url, handle, tx)
+    }
+
+    /// Reply body bitcoind would send for a successful getblockcount.
+    fn ok_reply() -> Body {
+        Body::from(r#"{"result":42,"error":null,"id":"archy"}"#)
+    }
+
+    fn err_reply() -> Body {
+        Body::from(r#"{"result":null,"error":{"code":-8,"message":"nope"},"id":"archy"}"#)
+    }
+
+    /// Succeeds on first attempt — should not retry.
+    #[tokio::test]
+    async fn happy_path_first_attempt() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::new(ok_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let v: u64 =
+            bitcoin_rpc_post_with_retry(&client, &url, "user", "pass", "getblockcount", &[])
+                .await
+                .expect("should succeed");
+        assert_eq!(v, 42);
+        assert_eq!(count.load(Ordering::SeqCst), 1, "should not have retried");
+    }
+
+    /// HTTP 503 with non-JSON body: produces a JSON-parse error which is NOT
+    /// classified as transient. Must fail after first attempt.
+    /// This guards against the tempting mistake of blanket-retrying every
+    /// non-2xx response — which would mask real bitcoind misconfig.
+    #[tokio::test]
+    async fn does_not_retry_parse_errors() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::builder()
+                    .status(StatusCode::SERVICE_UNAVAILABLE)
+                    .body(Body::from("busy"))
+                    .unwrap()
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let result: Result<u64> =
+            bitcoin_rpc_post_with_retry(&client, &url, "user", "pass", "getblockcount", &[]).await;
+        assert!(result.is_err(), "non-JSON response should error out");
+        assert_eq!(
+            count.load(Ordering::SeqCst),
+            1,
+            "parse errors are not retryable"
+        );
+    }
+
+    /// Connect-refused (port closed) is the canonical transient transport
+    /// error. Must exhaust BITCOIN_RPC_MAX_ATTEMPTS and the total elapsed
+    /// time must include at least the sum of the backoffs.
+    #[tokio::test]
+    async fn retries_exhausted_on_persistent_connect_refused() {
+        // Bind a port then immediately drop the listener so the port is closed.
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let closed_url = format!("http://{}", listener.local_addr().unwrap());
+        drop(listener);
+
+        let client = reqwest::Client::builder()
+            .connect_timeout(std::time::Duration::from_millis(500))
+            .build()
+            .unwrap();
+        let start = std::time::Instant::now();
+        let result: Result<u64> =
+            bitcoin_rpc_post_with_retry(&client, &closed_url, "user", "pass", "getblockcount", &[])
+                .await;
+        let elapsed = start.elapsed();
+        assert!(result.is_err(), "connect-refused should exhaust retries");
+        let min_backoff: std::time::Duration = BITCOIN_RPC_BACKOFFS.iter().sum();
+        assert!(
+            elapsed >= min_backoff,
+            "should have backed off between retries (elapsed={:?}, expected at least {:?})",
+            elapsed,
+            min_backoff
+        );
+    }
+
+    /// The motivating scenario: first attempt times out (bitcoind busy),
+    /// subsequent attempt succeeds. Uses a short test-only RetryConfig so
+    /// the test runs in <1s instead of 15s.
+    #[tokio::test]
+    async fn retries_on_timeout_then_succeeds() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        // Mock server: first request hangs for 500ms, subsequent requests reply OK.
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                let n = c.fetch_add(1, Ordering::SeqCst);
+                if n == 0 {
+                    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+                }
+                Response::new(ok_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        // Attempt timeout 100ms < server's 500ms sleep => first attempt times out.
+        // Backoff 20ms between attempts.
+        let cfg = RetryConfig {
+            max_attempts: 3,
+            attempt_timeout: std::time::Duration::from_millis(100),
+            backoffs: vec![
+                std::time::Duration::from_millis(20),
+                std::time::Duration::from_millis(20),
+            ],
+        };
+        let v: u64 = bitcoin_rpc_post_with_retry_cfg(
+            &client,
+            &url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+            &cfg,
+        )
+        .await
+        .expect("second attempt should succeed");
+        assert_eq!(v, 42);
+        assert!(
+            count.load(Ordering::SeqCst) >= 2,
+            "expected at least 2 attempts (got {})",
+            count.load(Ordering::SeqCst)
+        );
+    }
+
+    /// bitcoind returned a well-formed `{"error": ...}` body. Must NOT retry.
+    #[tokio::test]
+    async fn does_not_retry_on_rpc_level_error() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::new(err_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let result: Result<u64> =
+            bitcoin_rpc_post_with_retry(&client, &url, "user", "pass", "getblockcount", &[]).await;
+        assert!(result.is_err());
+        assert_eq!(
+            count.load(Ordering::SeqCst),
+            1,
+            "RPC-level errors are not transient"
+        );
+    }
+
+    /// Sanity: retry budget invariants. Chosen to catch regressions where
+    /// someone bumps these constants without realizing the total worst-case
+    /// wall time implications.
+    #[test]
+    fn retry_budget_invariants() {
+        assert_eq!(BITCOIN_RPC_MAX_ATTEMPTS, 3);
+        assert_eq!(
+            BITCOIN_RPC_BACKOFFS.len(),
+            (BITCOIN_RPC_MAX_ATTEMPTS - 1) as usize
+        );
+        // Total wall-time ceiling:
+        //   3 attempts * 15s  +  (0.5s + 1.5s) backoff  =  47s
+        let total: std::time::Duration = BITCOIN_RPC_ATTEMPT_TIMEOUT * BITCOIN_RPC_MAX_ATTEMPTS
+            + BITCOIN_RPC_BACKOFFS.iter().sum::<std::time::Duration>();
+        assert!(total < std::time::Duration::from_secs(60));
+    }
+}
@@ -1,4 +1,5 @@
 use super::package::validate_app_id;
+use super::transitional::Op;
 use super::RpcHandler;
 use anyhow::{Context, Result};

@@ -7,8 +8,13 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
+        // The `container-install { manifest_path }` RPC is a dev-mode convenience
+        // that points at an arbitrary YAML on disk. Production install happens via
+        // the reconciler (BootReconciler, Step 5) and via the unified
+        // ContainerOrchestrator::install(app_id) trait call, which can be exposed
+        // through a separate `container-install-by-id` RPC when needed.
+        let dev = self.dev_orchestrator.as_ref().ok_or_else(|| {
+            anyhow::anyhow!("container-install with manifest_path is only available in dev mode")
        })?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
@@ -45,7 +51,7 @@ impl RpcHandler {
        let manifest: archipelago_container::AppManifest =
            serde_yaml::from_str(&manifest_content).context("Failed to parse manifest")?;

-        let container_name = orchestrator
+        let container_name = dev
            .install_container(&manifest, manifest_path)
            .await
            .context("Failed to install container")?;
@@ -57,10 +63,6 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
-
        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
            .get("app_id")
@@ -68,22 +70,24 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
        validate_app_id(app_id)?;

-        orchestrator
-            .start_container(app_id)
-            .await
-            .context("Failed to start container")?;
+        // User explicitly started the app — clear the user-stopped marker so
+        // crash recovery / health monitor won't second-guess it. Must happen
+        // BEFORE the spawn (see runtime.rs:145-148 for the symmetric stop
+        // side and the ordering contract crash recovery depends on).
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, app_id).await;

-        Ok(serde_json::json!({ "status": "started" }))
+        // spawn_transitional returns as soon as the background task is
+        // launched (<1s). The UI sees Starting… immediately via WebSocket.
+        self.spawn_transitional(Op::Start, app_id.to_string())
+            .await?;
+
+        Ok(serde_json::json!({ "status": "starting" }))
    }

    pub(super) async fn handle_container_stop(
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
-
        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
            .get("app_id")
@@ -91,21 +95,51 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
        validate_app_id(app_id)?;

-        orchestrator
-            .stop_container(app_id)
-            .await
-            .context("Failed to stop container")?;
+        // Mark as user-stopped BEFORE the spawn — ordering is load-bearing
+        // (crash recovery / health monitor inspect this flag concurrently
+        // with the in-flight stop; see runtime.rs:145-148 for the package
+        // path that also writes this in the same order).
+        crate::crash_recovery::mark_user_stopped(&self.config.data_dir, app_id).await;

-        Ok(serde_json::json!({ "status": "stopped" }))
+        // podman stop -t 600 (bitcoin-core) / -t 330 (lnd) runs in the
+        // background; the RPC returns now with "stopping".
+        self.spawn_transitional(Op::Stop, app_id.to_string())
+            .await?;
+
+        Ok(serde_json::json!({ "status": "stopping" }))
+    }
+
+    pub(super) async fn handle_container_restart(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let app_id = params
+            .get("app_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
+        validate_app_id(app_id)?;
+
+        // Restart does not mark user-stopped (the user wants the app to
+        // keep running). Clear the marker as a defensive measure in case a
+        // prior stop left it set and the restart is intended to revive the
+        // normal running state.
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, app_id).await;
+
+        self.spawn_transitional(Op::Restart, app_id.to_string())
+            .await?;
+
+        Ok(serde_json::json!({ "status": "restarting" }))
    }

    pub(super) async fn handle_container_remove(
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -119,7 +153,7 @@ impl RpcHandler {
            .unwrap_or(false);

        orchestrator
-            .remove_container(app_id, preserve_data)
+            .remove(app_id, preserve_data)
            .await
            .context("Failed to remove container")?;

@@ -137,12 +171,25 @@ impl RpcHandler {
                .package_data
                .iter()
                .map(|(id, pkg)| {
+                    // Keep this mapping in sync with the UI's
+                    // ContainerStatus.state union in
+                    // neode-ui/src/api/container-client.ts. The UI maps
+                    // transitional variants to single-button labels
+                    // (Stopping… / Starting… / Restarting…).
                    let state = match &pkg.state {
                        crate::data_model::PackageState::Running => "running",
                        crate::data_model::PackageState::Stopped => "stopped",
                        crate::data_model::PackageState::Exited => "exited",
-                        crate::data_model::PackageState::Starting => "created",
-                        _ => "unknown",
+                        crate::data_model::PackageState::Starting => "starting",
+                        crate::data_model::PackageState::Stopping => "stopping",
+                        crate::data_model::PackageState::Restarting => "restarting",
+                        crate::data_model::PackageState::Installing => "installing",
+                        crate::data_model::PackageState::Installed => "installed",
+                        crate::data_model::PackageState::Updating => "updating",
+                        crate::data_model::PackageState::Removing => "removing",
+                        crate::data_model::PackageState::CreatingBackup => "creating-backup",
+                        crate::data_model::PackageState::RestoringBackup => "restoring-backup",
+                        crate::data_model::PackageState::BackingUp => "backing-up",
                    };
                    let lan = pkg
                        .installed
@@ -163,9 +210,9 @@ impl RpcHandler {
            return Ok(serde_json::json!(containers));
        }

-        // Fallback: scanner hasn't run yet, query podman directly
+        // Fallback: scanner hasn't run yet, query the orchestrator directly.
        if let Some(orchestrator) = &self.orchestrator {
-            if let Ok(containers) = orchestrator.list_containers().await {
+            if let Ok(containers) = orchestrator.list().await {
                if !containers.is_empty() {
                    return Ok(serde_json::to_value(containers)?);
                }
@@ -242,9 +289,10 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -253,21 +301,36 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
        validate_app_id(app_id)?;

-        let status = orchestrator
-            .get_container_status(app_id)
-            .await
-            .context("Failed to get container status")?;
+        let mut last_err: Option<anyhow::Error> = None;
+        for candidate in status_app_id_candidates(app_id) {
+            match orchestrator.status(&candidate).await {
+                Ok(status) => return Ok(serde_json::to_value(status)?),
+                Err(e) => last_err = Some(e),
+            }
+        }

-        Ok(serde_json::to_value(status)?)
+        // Fallback for alias drift: query podman directly by likely container
+        // names so status checks stay useful during migration.
+        for name in status_container_name_candidates(app_id) {
+            if let Some(v) = inspect_container_state_value(&name).await {
+                return Ok(v);
+            }
+        }
+
+        if let Some(e) = last_err {
+            return Err(e.context("Failed to get container status"));
+        }
+        Err(anyhow::anyhow!("Failed to get container status"))
    }

    pub(super) async fn handle_container_logs(
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -278,7 +341,7 @@ impl RpcHandler {
        let lines = params.get("lines").and_then(|v| v.as_u64()).unwrap_or(100) as u32;

        let logs = orchestrator
-            .get_container_logs(app_id, lines)
+            .logs(app_id, lines)
            .await
            .context("Failed to get container logs")?;

@@ -291,12 +354,13 @@ impl RpcHandler {
        app_id: &str,
        lines: u32,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let logs = orchestrator
-            .get_container_logs(app_id, lines)
+            .logs(app_id, lines)
            .await
            .context("Failed to get container logs")?;

@@ -307,43 +371,52 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

-        // If app_id is provided, get health for that app
+        // If app_id is provided, get health for that app.
        if let Some(params) = params {
            if let Some(app_id) = params.get("app_id").and_then(|v| v.as_str()) {
                let health = orchestrator
-                    .get_health_status(app_id)
+                    .health(app_id)
                    .await
                    .context("Failed to get container health")?;
                return Ok(serde_json::json!({ app_id: health }));
            }
        }

-        // Otherwise, get health for all containers
+        // Otherwise, get health for all containers.
        let containers = orchestrator
-            .list_containers()
+            .list()
            .await
            .context("Failed to list containers")?;

        let mut health_map = serde_json::Map::new();
        for container in containers {
-            if let Some(app_id) = container.name.strip_prefix("archipelago-") {
-                if let Some(app_id) = app_id.strip_suffix("-dev") {
-                    match orchestrator.get_health_status(app_id).await {
-                        Ok(health) => {
-                            health_map
-                                .insert(app_id.to_string(), serde_json::Value::String(health));
-                        }
-                        Err(_) => {
-                            health_map.insert(
-                                app_id.to_string(),
-                                serde_json::Value::String("unknown".to_string()),
-                            );
-                        }
-                    }
+            // Map the runtime container name back to the app_id the orchestrator
+            // knows about. Dev orchestrator uses `archipelago-<id>-dev`; Prod
+            // uses bare `<id>` (or `archy-<id>` for UIs — health() accepts the
+            // app_id either way since UI_APP_IDS is centralised).
+            let app_id_candidate = container
+                .name
+                .strip_prefix("archipelago-")
+                .and_then(|s| s.strip_suffix("-dev"))
+                .or_else(|| container.name.strip_prefix("archy-"))
+                .unwrap_or(container.name.as_str());
+            match orchestrator.health(app_id_candidate).await {
+                Ok(health) => {
+                    health_map.insert(
+                        app_id_candidate.to_string(),
+                        serde_json::Value::String(health),
+                    );
+                }
+                Err(_) => {
+                    health_map.insert(
+                        app_id_candidate.to_string(),
+                        serde_json::Value::String("unknown".to_string()),
+                    );
                }
            }
        }
@@ -351,3 +424,90 @@ impl RpcHandler {
        Ok(serde_json::Value::Object(health_map))
    }
 }
+
+fn status_app_id_candidates(app_id: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut push = |s: &str| {
+        if !out.iter().any(|e: &String| e == s) {
+            out.push(s.to_string());
+        }
+    };
+
+    match app_id {
+        "bitcoin-knots" => {
+            push("bitcoin-knots");
+            push("bitcoin-core");
+            push("bitcoin");
+        }
+        "bitcoin-core" | "bitcoin" => {
+            push("bitcoin-core");
+            push("bitcoin-knots");
+            push("bitcoin");
+        }
+        "electrs" | "mempool-electrs" => {
+            push("electrs");
+            push("mempool-electrs");
+            push("electrumx");
+        }
+        _ => push(app_id),
+    }
+
+    out
+}
+
+fn status_container_name_candidates(app_id: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut push = |s: &str| {
+        if !out.iter().any(|e: &String| e == s) {
+            out.push(s.to_string());
+        }
+    };
+
+    match app_id {
+        "bitcoin-knots" | "bitcoin-core" | "bitcoin" => push("bitcoin-knots"),
+        "bitcoin-ui" => push("archy-bitcoin-ui"),
+        "lnd-ui" => push("archy-lnd-ui"),
+        "electrs-ui" => push("archy-electrs-ui"),
+        "electrs" | "mempool-electrs" => push("electrumx"),
+        _ => {}
+    }
+
+    push(app_id);
+    if let Some(stripped) = app_id.strip_prefix("archy-") {
+        push(stripped);
+    } else {
+        push(&format!("archy-{}", app_id));
+    }
+
+    out
+}
+
+async fn inspect_container_state_value(name: &str) -> Option<serde_json::Value> {
+    let out = tokio::process::Command::new("podman")
+        .args([
+            "inspect",
+            name,
+            "--format",
+            "{{.State.Status}} {{.State.Running}}",
+        ])
+        .output()
+        .await
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+
+    let line = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    if line.is_empty() {
+        return None;
+    }
+    let mut parts = line.split_whitespace();
+    let status = parts.next().unwrap_or("unknown");
+    let running = parts.next().unwrap_or("false") == "true";
+    Some(serde_json::json!({
+        "name": name,
+        "status": status,
+        "state": status,
+        "running": running,
+    }))
+}
@@ -231,8 +231,7 @@ impl RpcHandler {

        let (data, _) = self.state_manager.get_snapshot().await;
        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
-        let fips_npub =
-            crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;

        let path = format!("/content/{}", content_id);
        let (response, _transport) =
@@ -287,10 +286,13 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("Invalid v3 onion address"));
        }

-        let fips_npub =
-            crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;

-        debug!("Browsing peer content at {} (fips={})", onion, fips_npub.is_some());
+        debug!(
+            "Browsing peer content at {} (fips={})",
+            onion,
+            fips_npub.is_some()
+        );

        let (response, _transport) =
            crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, "/content")
@@ -348,8 +350,7 @@ impl RpcHandler {

        let (data, _) = self.state_manager.get_snapshot().await;
        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
-        let fips_npub =
-            crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;

        let path = format!("/content/{}", content_id);
        let (response, _transport) =
@@ -407,11 +408,15 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("Invalid v3 onion address"));
        }

-        let fips_npub =
-            crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;

        let path = format!("/content/{}/preview", content_id);
-        debug!("Fetching content preview from {}{} (fips={})", onion, path, fips_npub.is_some());
+        debug!(
+            "Fetching content preview from {}{} (fips={})",
+            onion,
+            path,
+            fips_npub.is_some()
+        );

        let (response, _transport) =
            crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
@@ -1,10 +1,11 @@
 use super::RpcHandler;
 use anyhow::Result;
+use std::sync::Arc;

 impl RpcHandler {
    /// Route an RPC method name to its handler, returning the result value.
    pub(super) async fn dispatch(
-        &self,
+        self: &Arc<Self>,
        method: &str,
        params: Option<serde_json::Value>,
        session_token: &Option<String>,
@@ -36,19 +37,23 @@ impl RpcHandler {
            "container-install" => self.handle_container_install(params).await,
            "container-start" => self.handle_container_start(params).await,
            "container-stop" => self.handle_container_stop(params).await,
+            "container-restart" => self.handle_container_restart(params).await,
            "container-remove" => self.handle_container_remove(params).await,
            "container-list" => self.handle_container_list().await,
            "container-status" => self.handle_container_status(params).await,
            "container-logs" => self.handle_container_logs(params).await,
            "container-health" => self.handle_container_health(params).await,

-            // Package management (for docker-compose apps)
-            "package.install" => self.handle_package_install(params).await,
+            // Package management (for docker-compose apps).
+            // install/uninstall/update return immediately with a
+            // transitional status; the actual work runs in a background
+            // tokio::spawn so the HTTP request doesn't block for minutes.
+            "package.install" => self.clone().spawn_package_install(params).await,
            "package.start" => self.handle_package_start(params).await,
            "package.stop" => self.handle_package_stop(params).await,
            "package.restart" => self.handle_package_restart(params).await,
-            "package.uninstall" => self.handle_package_uninstall(params).await,
-            "package.update" => self.handle_package_update(params).await,
+            "package.uninstall" => self.clone().spawn_package_uninstall(params).await,
+            "package.update" => self.clone().spawn_package_update(params).await,
            "app.filebrowser-token" => self.handle_filebrowser_token().await,

            // Bundled app management (for pre-loaded container images)
@@ -220,6 +225,7 @@ impl RpcHandler {
            "registry.list" => self.handle_registry_list().await,
            "registry.add" => self.handle_registry_add(params).await,
            "registry.remove" => self.handle_registry_remove(params).await,
+            "registry.set-primary" => self.handle_registry_set_primary(params).await,
            "registry.test" => self.handle_registry_test(params).await,

            // Streaming ecash payments
@@ -413,12 +419,41 @@ impl RpcHandler {
            "fips.apply-update" => self.handle_fips_apply_update().await,
            "fips.install" => self.handle_fips_install().await,
            "fips.restart" => self.handle_fips_restart().await,
+            "fips.reconnect" => self.handle_fips_reconnect().await,
+            "fips.list-seed-anchors" => self.handle_fips_list_seed_anchors().await,
+            "fips.add-seed-anchor" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_fips_add_seed_anchor(&p).await
+            }
+            "fips.remove-seed-anchor" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_fips_remove_seed_anchor(&p).await
+            }
+            "fips.apply-seed-anchors" => self.handle_fips_apply_seed_anchors().await,

            // System updates
            "update.check" => self.handle_update_check().await,
            "update.status" => self.handle_update_status().await,
            "update.dismiss" => self.handle_update_dismiss().await,
            "update.download" => self.handle_update_download().await,
+            "update.cancel-download" => self.handle_update_cancel_download().await,
+            "update.list-mirrors" => self.handle_update_list_mirrors().await,
+            "update.add-mirror" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_update_add_mirror(&p).await
+            }
+            "update.remove-mirror" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_update_remove_mirror(&p).await
+            }
+            "update.set-primary-mirror" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_update_set_primary_mirror(&p).await
+            }
+            "update.test-mirror" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_update_test_mirror(&p).await
+            }
            "update.apply" => self.handle_update_apply().await,
            "update.git-apply" => self.handle_update_git_apply().await,
            "update.rollback" => self.handle_update_rollback().await,
@@ -79,6 +79,7 @@ impl RpcHandler {
        let local_did = identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
        let local_onion = data.server_info.tor_address.clone().unwrap_or_default();
        let local_pubkey = data.server_info.pubkey.clone();
+        let local_name = data.server_info.name.clone();

        let identity_dir = self.config.data_dir.join("identity");
        let node_identity = identity::NodeIdentity::load_or_create(&identity_dir).await?;
@@ -90,6 +91,7 @@ impl RpcHandler {
            &local_onion,
            &local_pubkey,
            local_fips_npub.as_deref(),
+            local_name.as_deref(),
            |data| node_identity.sign(data),
        )
        .await?;
@@ -401,7 +403,10 @@ impl RpcHandler {
            });
        let own_fips_npub = match own_fips_npub {
            Some(n) => Some(n),
-            None => crate::fips::service::read_upstream_npub().await.ok().flatten(),
+            None => crate::fips::service::read_upstream_npub()
+                .await
+                .ok()
+                .flatten(),
        };

        let state = federation::build_local_state(
@@ -447,6 +452,37 @@ impl RpcHandler {
            .get("fips_npub")
            .and_then(|v| v.as_str())
            .map(|s| s.to_string());
+        // Optional, unsigned: peer's display name. Display-only — identity
+        // claims are anchored on the signed did/pubkey below.
+        let incoming_name = params
+            .get("name")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string());
+
+        // Reject self-peering. If somehow our own did / onion / pubkey
+        // comes back at us (misconfigured invite, gossip loop), adding
+        // the entry causes sync loops where the node syncs with itself
+        // forever. Drop it quietly — no useful recovery path.
+        let (own_data, _) = self.state_manager.get_snapshot().await;
+        let own_did_result = identity::did_key_from_pubkey_hex(&own_data.server_info.pubkey).ok();
+        let own_onion_trim = own_data
+            .server_info
+            .tor_address
+            .as_deref()
+            .unwrap_or("")
+            .trim_end_matches(".onion")
+            .to_string();
+        let incoming_onion_trim = onion.trim_end_matches(".onion");
+        if own_did_result.as_deref() == Some(did)
+            || pubkey == own_data.server_info.pubkey
+            || (!own_onion_trim.is_empty() && own_onion_trim == incoming_onion_trim)
+        {
+            tracing::warn!(
+                peer_did = %did,
+                "Rejected peer-joined: inbound identity matches this node"
+            );
+            anyhow::bail!("Refusing to peer with self");
+        }

        // Verify ed25519 signature to prevent federation spoofing (H2 security fix)
        let signature = params.get("signature").and_then(|v| v.as_str());
@@ -471,11 +507,12 @@ impl RpcHandler {

        let nodes = federation::load_nodes(&self.config.data_dir).await?;
        if let Some(existing) = nodes.iter().find(|n| n.did == did) {
-            // If already known but missing onion/pubkey/fips_npub, update them
+            // If already known but missing onion/pubkey/fips_npub/name, update them
            let needs_onion = existing.onion.is_empty();
            let needs_pubkey = existing.pubkey.is_empty();
            let needs_fips = existing.fips_npub.is_none() && fips_npub.is_some();
-            if needs_onion || needs_pubkey || needs_fips {
+            let needs_name = existing.name.is_none() && incoming_name.is_some();
+            if needs_onion || needs_pubkey || needs_fips || needs_name {
                let mut updated = existing.clone();
                if needs_onion && !onion.is_empty() {
                    updated.onion = onion.to_string();
@@ -486,6 +523,9 @@ impl RpcHandler {
                if needs_fips {
                    updated.fips_npub = fips_npub.clone();
                }
+                if needs_name {
+                    updated.name = incoming_name.clone();
+                }
                updated.last_seen = Some(chrono::Utc::now().to_rfc3339());
                federation::update_node(&self.config.data_dir, &updated).await?;
                info!(peer_did = %did, peer_onion = %onion, "Updated existing peer with fresh identity fields");
@@ -497,7 +537,7 @@ impl RpcHandler {
            did: did.to_string(),
            pubkey: pubkey.to_string(),
            onion: onion.to_string(),
-            name: None,
+            name: incoming_name.clone(),
            trust_level: TrustLevel::Trusted,
            added_at: chrono::Utc::now().to_rfc3339(),
            last_seen: None,
@@ -512,9 +552,34 @@ impl RpcHandler {

        // Mirror into mesh state so the inbound peer is addressable from
        // the chat UI without waiting for the next mesh restart.
-        self.register_federation_peer_in_mesh(pubkey, did, None)
+        self.register_federation_peer_in_mesh(pubkey, did, incoming_name.as_deref())
            .await;

+        // Bump the data-model revision so any Federation view with an
+        // open WebSocket reloads its node list without waiting for the
+        // user to click Sync.
+        let (data, _) = self.state_manager.get_snapshot().await;
+        self.state_manager.update_data(data).await;
+
+        // Transitive discovery: spawn a task that pulls the new peer's
+        // state (its own federated peers end up as Observer entries on
+        // our side) so after a join every existing peer in our list is
+        // aware of the newcomer via the next pair of syncs, without the
+        // user clicking anything. Best-effort; errors are logged only.
+        let data_dir = self.config.data_dir.clone();
+        let new_peer_did = did.to_string();
+        tokio::spawn(async move {
+            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+            if let Err(e) = crate::federation::sync_with_peer_by_did(&data_dir, &new_peer_did).await
+            {
+                tracing::debug!(
+                    peer_did = %new_peer_did,
+                    error = %e,
+                    "Transitive sync on peer-joined failed (non-fatal)"
+                );
+            }
+        });
+
        Ok(serde_json::json!({ "accepted": true }))
    }

@@ -12,8 +12,7 @@ use anyhow::Result;

 impl RpcHandler {
    pub(super) async fn handle_fips_status(&self) -> Result<serde_json::Value> {
-        let identity_dir = fips::identity_dir_from(&self.config.data_dir);
-        let status = fips::FipsStatus::query(&identity_dir).await;
+        let status = fips::FipsStatus::query(&self.config.data_dir).await;
        Ok(serde_json::to_value(status)?)
    }

@@ -36,12 +35,178 @@ impl RpcHandler {
        let identity_dir = fips::identity_dir_from(&self.config.data_dir);
        fips::config::install(&identity_dir).await?;
        fips::service::activate(fips::SERVICE_UNIT).await?;
-        let status = fips::FipsStatus::query(&identity_dir).await;
+        let status = fips::FipsStatus::query(&self.config.data_dir).await;
        Ok(serde_json::to_value(status)?)
    }

+    /// Restart whichever fips unit is supervising the daemon on this host.
+    /// Nodes installed from the archipelago ISO use `archipelago-fips.service`;
+    /// nodes that had the upstream debian package set up first may only have
+    /// `fips.service`. We resolve the active one via `service::active_unit()`
+    /// so the UI button is never a no-op.
    pub(super) async fn handle_fips_restart(&self) -> Result<serde_json::Value> {
-        fips::service::restart(fips::SERVICE_UNIT).await?;
-        Ok(serde_json::json!({ "restarted": true }))
+        let unit = fips::service::active_unit().await;
+        fips::service::restart(unit).await?;
+        Ok(serde_json::json!({ "restarted": true, "unit": unit }))
+    }
+
+    /// Full reconnect: stop the daemon, bring it back, wait for the DHT
+    /// bootstrap window, poll the identity-cache + peer list, and
+    /// classify what recovered (or didn't) so the UI can explain it to
+    /// the user instead of showing a generic failure.
+    ///
+    /// Runtime: ~20s. Needs an RPC timeout ≥ 45s on the client.
+    pub(super) async fn handle_fips_reconnect(&self) -> Result<serde_json::Value> {
+        let identity_dir = fips::identity_dir_from(&self.config.data_dir);
+        let before = fips::FipsStatus::query(&self.config.data_dir).await;
+
+        // Heal the pre-fix bech32-text fips_key.pub → 32-raw-bytes
+        // mismatch. The daemon silently authenticates with a garbage
+        // pubkey when the .pub file is 63-char text, which looks like
+        // "anchor unreachable" to the user even though the real fault
+        // was an identity malformed on the node itself. Re-install the
+        // config + keys so /etc/fips gets the healed .pub.
+        let key_src = identity_dir.join("fips_key");
+        let pub_src = identity_dir.join("fips_key.pub");
+        if key_src.exists() {
+            let _ = fips::config::normalize_pub_file(&key_src, &pub_src).await;
+            // Re-install refreshes /etc/fips/fips.pub from the healed
+            // source. No-op if nothing changed.
+            let _ = fips::config::install(&identity_dir).await;
+        }
+
+        // Operate on whichever fips unit is actually up — nodes that
+        // have the upstream `fips.service` rather than the
+        // archipelago-managed `archipelago-fips.service` used to see
+        // Reconnect silently fail because we stopped a unit that
+        // didn't exist. Clean stop+start rather than `restart` so a
+        // daemon that fails to come back up surfaces as
+        // service_active=false instead of quietly sticking with the
+        // old process.
+        let unit = fips::service::active_unit().await;
+        let _ = fips::service::stop(unit).await;
+        tokio::time::sleep(std::time::Duration::from_millis(800)).await;
+        fips::service::activate(unit).await?;
+
+        // Re-push seed anchors after restart so freshly-bound daemons
+        // don't have to wait 5 min for the periodic apply loop.
+        if let Ok(list) = fips::anchors::load(&self.config.data_dir).await {
+            if !list.is_empty() {
+                let _ = fips::anchors::apply(&list).await;
+            }
+        }
+
+        // Anchor bootstrap window: poll the status every ~3s for up to
+        // 20s. Bail as soon as the anchor is connected.
+        let mut last_status: Option<fips::FipsStatus> = None;
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(20);
+        loop {
+            tokio::time::sleep(std::time::Duration::from_secs(3)).await;
+            let s = fips::FipsStatus::query(&self.config.data_dir).await;
+            if s.anchor_connected {
+                last_status = Some(s);
+                break;
+            }
+            last_status = Some(s);
+            if std::time::Instant::now() >= deadline {
+                break;
+            }
+        }
+        let after = last_status.unwrap_or_else(|| before.clone());
+
+        let recovered = after.anchor_connected && !before.anchor_connected;
+        let likely_cause = if after.anchor_connected {
+            "connected"
+        } else if !after.service_active {
+            "daemon_down"
+        } else if !after.key_present {
+            "no_seed_key"
+        } else if after.authenticated_peer_count == 0 {
+            // Daemon is up with a key but hasn't authenticated any
+            // peers — almost always outbound UDP/8668 dropped by the
+            // local firewall/router, or the anchor itself being down.
+            "no_outbound_udp_or_anchor_down"
+        } else {
+            "peers_but_no_anchor"
+        };
+        let hint = match likely_cause {
+            "connected" => "An anchor is reachable.",
+            "daemon_down" => "The FIPS daemon didn't come back up — check the FIPS service on this host.",
+            "no_seed_key" => "No seed-derived FIPS key on disk. Re-run the onboarding unlock step.",
+            "no_outbound_udp_or_anchor_down" =>
+                "Daemon is running but no peers handshook. Your router / ISP might be blocking outbound UDP 8668, or every configured anchor could be down. Add a reachable peer in Seed Anchors.",
+            "peers_but_no_anchor" =>
+                "Mesh has peers but none of them are anchors we recognise. Add your cluster's anchor in Seed Anchors.",
+            _ => "",
+        };
+
+        Ok(serde_json::json!({
+            "recovered": recovered,
+            "likely_cause": likely_cause,
+            "hint": hint,
+            "before": before,
+            "after": after,
+        }))
+    }
+
+    /// List the seed-anchor entries configured on this node.
+    pub(super) async fn handle_fips_list_seed_anchors(&self) -> Result<serde_json::Value> {
+        let list = fips::anchors::load(&self.config.data_dir).await?;
+        Ok(serde_json::json!({ "seed_anchors": list }))
+    }
+
+    /// Add (or update) a seed anchor and immediately push it into the
+    /// running daemon. Params: `{ npub, address, transport?, label? }`.
+    pub(super) async fn handle_fips_add_seed_anchor(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let anchor: fips::anchors::SeedAnchor = serde_json::from_value(params.clone())
+            .map_err(|e| anyhow::anyhow!("bad seed anchor payload: {}", e))?;
+        if !anchor.npub.starts_with("npub1") {
+            anyhow::bail!("npub must be bech32 (npub1...)");
+        }
+        if !anchor.address.contains(':') {
+            anyhow::bail!("address must be host:port (e.g. 192.168.1.116:8668)");
+        }
+        let list = fips::anchors::add(&self.config.data_dir, anchor.clone()).await?;
+        // Push just the newly-added anchor into the running daemon so
+        // the user sees effect without waiting for the periodic apply.
+        let results = fips::anchors::apply(&[anchor]).await;
+        Ok(serde_json::json!({
+            "seed_anchors": list,
+            "apply": results.iter().map(|r| {
+                serde_json::json!({ "npub": r.npub, "ok": r.ok, "message": r.message })
+            }).collect::<Vec<_>>(),
+        }))
+    }
+
+    /// Remove a seed anchor by npub. Params: `{ npub }`. Does NOT tear
+    /// down an already-authenticated peer connection — it only stops
+    /// us from re-dialing the anchor on the next apply cycle.
+    pub(super) async fn handle_fips_remove_seed_anchor(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let npub = params
+            .get("npub")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("missing npub"))?;
+        let list = fips::anchors::remove(&self.config.data_dir, npub).await?;
+        Ok(serde_json::json!({ "seed_anchors": list }))
+    }
+
+    /// Re-apply all seed anchors to the running daemon. Useful after a
+    /// FIPS restart or when the user wants to force a reconnection
+    /// attempt without waiting for the periodic apply loop.
+    pub(super) async fn handle_fips_apply_seed_anchors(&self) -> Result<serde_json::Value> {
+        let list = fips::anchors::load(&self.config.data_dir).await?;
+        let results = fips::anchors::apply(&list).await;
+        Ok(serde_json::json!({
+            "applied": results.len(),
+            "results": results.iter().map(|r| {
+                serde_json::json!({ "npub": r.npub, "ok": r.ok, "message": r.message })
+            }).collect::<Vec<_>>(),
+        }))
    }
 }
@@ -282,6 +282,7 @@ impl RpcHandler {
                    let local_fips_npub = crate::identity::fips_npub(&identity_dir2)
                        .await
                        .unwrap_or(None);
+                    let local_name = data.server_info.name.clone();
                    match crate::federation::accept_invite(
                        &self.config.data_dir,
                        invite_code,
@@ -289,6 +290,7 @@ impl RpcHandler {
                        &local_onion,
                        &local_pubkey,
                        local_fips_npub.as_deref(),
+                        local_name.as_deref(),
                        |bytes| node_identity.sign(bytes),
                    )
                    .await
@@ -742,24 +742,25 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing required parameter: id"))?;
        validate_identity_id(id)?;

-        let relay_urls: Vec<String> = if let Some(arr) = params.get("relays").and_then(|v| v.as_array()) {
-            arr.iter()
-                .filter_map(|v| v.as_str())
-                .map(|s| s.to_string())
-                .collect()
-        } else if let Some(single) = params.get("relay").and_then(|v| v.as_str()) {
-            vec![single.to_string()]
-        } else {
-            // Default: every enabled relay in the user's Manage Relays list.
-            let statuses = crate::nostr_relays::list_relays(&self.config.data_dir)
-                .await
-                .unwrap_or_default();
-            statuses
-                .into_iter()
-                .filter(|s| s.enabled)
-                .map(|s| s.url)
-                .collect()
-        };
+        let relay_urls: Vec<String> =
+            if let Some(arr) = params.get("relays").and_then(|v| v.as_array()) {
+                arr.iter()
+                    .filter_map(|v| v.as_str())
+                    .map(|s| s.to_string())
+                    .collect()
+            } else if let Some(single) = params.get("relay").and_then(|v| v.as_str()) {
+                vec![single.to_string()]
+            } else {
+                // Default: every enabled relay in the user's Manage Relays list.
+                let statuses = crate::nostr_relays::list_relays(&self.config.data_dir)
+                    .await
+                    .unwrap_or_default();
+                statuses
+                    .into_iter()
+                    .filter(|s| s.enabled)
+                    .map(|s| s.url)
+                    .collect()
+            };

        if relay_urls.is_empty() {
            anyhow::bail!("No enabled relays configured; add one under Manage Relays");
@@ -3,7 +3,7 @@ use anyhow::{Context, Result};
 use base64::Engine;
 use serde::{Deserialize, Serialize};

-use super::{LndAmount, LndBalanceResponse};
+use super::{read_lnd_admin_macaroon, LndAmount, LndBalanceResponse};

 #[derive(Debug, Serialize)]
 struct LndInfo {
@@ -34,11 +34,7 @@ struct LndChannelBalanceResponse {

 impl RpcHandler {
    pub(in crate::api::rpc) async fn handle_lnd_getinfo(&self) -> Result<serde_json::Value> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon — is LND installed?")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);

        let client = reqwest::Client::builder()
@@ -114,7 +110,6 @@ impl RpcHandler {
    /// for building lndconnect:// URIs in the frontend.
    pub(crate) async fn handle_lnd_connect_info(&self) -> Result<serde_json::Value> {
        let cert_path = "/var/lib/archipelago/lnd/tls.cert";
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";

        // Read and encode TLS cert (PEM -> DER -> base64url)
        let cert_pem = tokio::fs::read_to_string(cert_path)
@@ -130,9 +125,7 @@ impl RpcHandler {
        let cert_b64url = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&cert_der);

        // Read and encode macaroon (binary -> base64url)
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_b64url =
            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&macaroon_bytes);

@@ -183,10 +176,7 @@ impl RpcHandler {
    pub(in crate::api::rpc) async fn handle_lnd_export_channel_backup(
        &self,
    ) -> Result<serde_json::Value> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);

        let client = reqwest::Client::builder()
@@ -4,7 +4,11 @@ mod payments;
 mod wallet;

 use crate::api::rpc::RpcHandler;
-use anyhow::{Context, Result};
+use anyhow::{anyhow, Context, Result};
+
+/// Canonical on-host path for LND's admin macaroon.
+pub(crate) const LND_ADMIN_MACAROON_PATH: &str =
+    "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";

 // Shared LND response types used by multiple submodules
 #[derive(Debug, serde::Deserialize)]
@@ -17,15 +21,45 @@ pub(super) struct LndAmount {
    pub sat: Option<String>,
 }

+/// Read LND's admin macaroon from disk.
+///
+/// The macaroon lives inside LND's container data dir and is owned by a
+/// rootless-podman subordinate UID (typically 100000), mode 640. The
+/// archipelago server runs as UID 1000 and therefore cannot read it
+/// directly. We first try a plain read (works if an operator has relaxed
+/// permissions), then fall back to `sudo cat` — mirroring the pattern
+/// already used for Tor hidden-service hostnames.
+pub(crate) async fn read_lnd_admin_macaroon() -> Result<Vec<u8>> {
+    match tokio::fs::read(LND_ADMIN_MACAROON_PATH).await {
+        Ok(bytes) => Ok(bytes),
+        Err(direct_err) => {
+            let output = tokio::process::Command::new("sudo")
+                .args(["-n", "cat", LND_ADMIN_MACAROON_PATH])
+                .output()
+                .await
+                .with_context(|| {
+                    format!(
+                        "Failed to read LND admin macaroon (direct: {direct_err}); sudo fallback also failed"
+                    )
+                })?;
+            if !output.status.success() {
+                let stderr = String::from_utf8_lossy(&output.stderr);
+                return Err(anyhow!(
+                    "Failed to read LND admin macaroon — is LND installed? (direct: {direct_err}; sudo: {})",
+                    stderr.trim()
+                ));
+            }
+            Ok(output.stdout)
+        }
+    }
+}
+
 impl RpcHandler {
    /// Helper: create an authenticated LND REST client.
    /// Returns an HTTP client configured for LND's self-signed TLS and the
    /// hex-encoded admin macaroon for request headers.
    pub(crate) async fn lnd_client(&self) -> Result<(reqwest::Client, String)> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon — is LND installed?")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);
        let client = reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(15))
@@ -761,7 +761,9 @@ impl RpcHandler {
            .await
            .map_err(|e| anyhow::anyhow!("Read body failed: {}", e))?;

-        let meta = blob_store.put(&bytes, &mime, filename_hint, None, false).await?;
+        let meta = blob_store
+            .put(&bytes, &mime, filename_hint, None, false)
+            .await?;
        if meta.cid != cid {
            anyhow::bail!("CID mismatch: expected {}, got {}", cid, meta.cid);
        }
@@ -31,6 +31,7 @@ mod streaming;
 mod system;
 mod tor;
 mod totp;
+mod transitional;
 mod transport;
 mod update;
 mod vpn;
@@ -39,7 +40,7 @@ mod webhooks;

 use crate::auth::AuthManager;
 use crate::config::Config;
-use crate::container::DevContainerOrchestrator;
+use crate::container::{ContainerOrchestrator, DevContainerOrchestrator};
 use crate::monitoring::MetricsStore;
 use crate::port_allocator::PortAllocator;
 use crate::rate_limit::{EndpointRateLimiter, LoginRateLimiter};
@@ -62,7 +63,14 @@ pub(crate) const DEV_DEFAULT_PASSWORD: &str = "password123";
 pub struct RpcHandler {
    config: Config,
    auth_manager: AuthManager,
-    orchestrator: Option<Arc<DevContainerOrchestrator>>,
+    /// Shared lifecycle orchestrator (Dev or Prod). Always `Some` in a normal
+    /// build — the only reason it is `Option` is so tests that don't exercise
+    /// container RPCs can skip constructing one.
+    orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+    /// Concrete handle to the dev orchestrator, when we're in dev mode. Used by
+    /// `container-install { manifest_path }` which takes an ad-hoc manifest
+    /// path and is not part of the shared trait.
+    dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    state_manager: Arc<StateManager>,
    pub(crate) metrics_store: Arc<MetricsStore>,
    port_allocator: Arc<tokio::sync::Mutex<PortAllocator>>,
@@ -79,6 +87,15 @@ pub struct RpcHandler {
    /// Our own Ed25519 pubkey hex — needed by ContentRef senders for cap scoping
    /// and by ContentRef receivers to request caps scoped to themselves.
    pub(crate) self_pubkey_hex: Arc<tokio::sync::RwLock<Option<String>>>,
+    /// Kick the package scanner to run immediately (bypassing the 60s interval).
+    /// Used by install/update success paths so the fresh manifest (with populated
+    /// `interfaces.main.ui`) lands before we flip state to Running — closes the
+    /// "Launch button is missing for up to 60s after install" UX gap.
+    pub(crate) scan_kick: Arc<tokio::sync::Notify>,
+    /// Monotonic counter incremented by the scan loop after each completed scan.
+    /// Install/update success paths subscribe to this to know when a kicked scan
+    /// has actually finished before flipping to the terminal state.
+    pub(crate) scan_tick: Arc<tokio::sync::watch::Sender<u64>>,
 }

 impl RpcHandler {
@@ -87,15 +104,10 @@ impl RpcHandler {
        state_manager: Arc<StateManager>,
        metrics_store: Arc<MetricsStore>,
        session_store: SessionStore,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    ) -> Result<Self> {
        let auth_manager = AuthManager::new(config.data_dir.clone());
-        let orchestrator = if config.dev_mode {
-            Some(Arc::new(
-                DevContainerOrchestrator::new(config.clone()).await?,
-            ))
-        } else {
-            None
-        };
        let port_allocator = Arc::new(tokio::sync::Mutex::new(
            PortAllocator::new(&config.data_dir).await?,
        ));
@@ -129,6 +141,7 @@ impl RpcHandler {
            config,
            auth_manager,
            orchestrator,
+            dev_orchestrator,
            state_manager,
            metrics_store,
            port_allocator,
@@ -140,6 +153,8 @@ impl RpcHandler {
            transport_router: Arc::new(tokio::sync::RwLock::new(None)),
            blob_store: Arc::new(tokio::sync::RwLock::new(None)),
            self_pubkey_hex: Arc::new(tokio::sync::RwLock::new(None)),
+            scan_kick: Arc::new(tokio::sync::Notify::new()),
+            scan_tick: Arc::new(tokio::sync::watch::channel(0u64).0),
        })
    }

@@ -180,6 +195,21 @@ impl RpcHandler {
        Arc::clone(&self.mesh_service)
    }

+    /// Shared Notify handle the package-scanner loop waits on (in addition to
+    /// its periodic tick). Install/update success paths call `notify_one()` to
+    /// trigger an immediate scan so the fresh manifest lands before we flip to
+    /// the terminal Running state.
+    pub fn scan_kick(&self) -> Arc<tokio::sync::Notify> {
+        Arc::clone(&self.scan_kick)
+    }
+
+    /// Sender half of the scan-completion watch channel. The scanner bumps this
+    /// counter after every finished scan; install/update wait for an advance
+    /// after kicking so they know the fresh manifest has landed.
+    pub fn scan_tick(&self) -> Arc<tokio::sync::watch::Sender<u64>> {
+        Arc::clone(&self.scan_tick)
+    }
+
    fn cookie_suffix_for_request(&self, headers: &hyper::header::HeaderMap) -> &'static str {
        // Only set Secure flag when the original request was over HTTPS.
        // Nginx sends X-Forwarded-Proto: https for HTTPS connections.
@@ -197,7 +227,10 @@ impl RpcHandler {
        ""
    }

-    pub async fn handle(&self, req: Request<hyper::Body>) -> Result<Response<hyper::Body>> {
+    pub async fn handle(
+        self: Arc<Self>,
+        req: Request<hyper::Body>,
+    ) -> Result<Response<hyper::Body>> {
        // Extract session cookie before consuming the request
        let (parts, body) = req.into_parts();
        let session_token = session::extract_session_cookie(&parts.headers);
@@ -376,7 +409,7 @@ impl RpcHandler {

        // Route to handler (track latency for metrics)
        let rpc_start = std::time::Instant::now();
-        let result = self.dispatch(&rpc_req.method, params, &session_token).await;
+        let result = Self::dispatch(&self, &rpc_req.method, params, &session_token).await;

        // Record RPC latency for monitoring
        let elapsed_ms = rpc_start.elapsed().as_secs_f64() * 1000.0;
@@ -0,0 +1,437 @@
+//! Async wrappers for `package.install`, `package.uninstall`, `package.update`.
+//!
+//! The inner `handle_package_*` functions are large (install is 480 lines with
+//! the stack dispatchers, update is 300, uninstall is 200) and do their own
+//! fine-grained progress tracking via `install_progress` and `uninstall_stage`.
+//! We wrap them rather than refactor them.
+//!
+//! Each wrapper:
+//!   1. Parses + validates the RPC params (cheap, synchronous). Errors here
+//!      return immediately to the caller before any state change.
+//!   2. Flips the package state to the transitional variant
+//!      (`Installing` / `Removing` / `Updating`) so the UI sees it on the
+//!      next WebSocket push (before the RPC response even lands).
+//!   3. `tokio::spawn`s a background task that invokes the existing
+//!      `handle_package_*` method on the Arc-held self.
+//!   4. On task success: no state change needed — the inner handler has
+//!      already written the terminal state (Running for install/update, or
+//!      removed the entry for uninstall).
+//!   5. On task failure: revert state to the pre-transition value (or delete
+//!      the entry for install, since there was no pre-state), write a line
+//!      to the persistent install log, and clear any stale progress fields.
+//!   6. Returns `{ "status": "installing" }` etc. immediately.
+//!
+//! The server package-scan loop's `merge_preserving_transitional` helper
+//! already knows to preserve `Installing` / `Removing` / `Updating` between
+//! scans, so live progress updates broadcast from inside the spawned task
+//! reach the UI correctly.
+
+use super::install::install_log;
+use crate::api::rpc::RpcHandler;
+use crate::data_model::PackageState;
+use crate::state::StateManager;
+use anyhow::Result;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+impl RpcHandler {
+    /// Async wrapper for `package.install`. Returns `{ "status": "installing" }`
+    /// immediately after flipping state to `Installing` and spawning the
+    /// actual install pipeline. On failure, removes the package entry from
+    /// state so the UI reverts to "not installed".
+    pub(in crate::api::rpc) async fn spawn_package_install(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        // Extract + validate package_id synchronously so bad params fail
+        // fast without touching state.
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle (prevents double-click
+        // queuing two installs on the same package).
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing | PackageState::Removing | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        // Flip state to Installing BEFORE the spawn so the first WebSocket
+        // push carries the transitional state. Uses the same
+        // `create_installing_entry` path the inner handler would use once
+        // it starts pulling, so the UI sees a consistent shape.
+        flip_to_installing(&self.state_manager, &package_id).await;
+
+        install_log(&format!("INSTALL SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_install(params).await {
+                Ok(_) => {
+                    info!("package.install {}: complete", package_id_spawn);
+                    // The install pipeline has verified the container is up
+                    // and healthy (see install.rs post-start exit check).
+                    // Kick the scanner first so the fresh manifest (with
+                    // `interfaces.main.ui` from the live port binding) lands
+                    // BEFORE we flip to Running — without this the Launch
+                    // button is missing for up to 60s after a successful
+                    // install, because the skeletal install-time manifest
+                    // has `interfaces: None`.
+                    kick_scanner_and_wait(&handler).await;
+                    // We MUST explicitly transition out of Installing here:
+                    // `merge_preserving_transitional` in the package-scan
+                    // loop treats Installing as RPC-owned and refuses to
+                    // let the scanner overwrite it with the observed
+                    // Running state. Without this write, the entry stays
+                    // stuck at Installing forever.
+                    set_package_state(
+                        &handler.state_manager,
+                        &package_id_spawn,
+                        PackageState::Running,
+                    )
+                    .await;
+                    handler.clear_install_progress(&package_id_spawn).await;
+                }
+                Err(e) => {
+                    error!("package.install {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!("INSTALL FAIL: {} — {:#}", package_id_spawn, e)).await;
+                    // No pre-state to revert to — remove the entry entirely so
+                    // the UI shows the app as not installed. The next package
+                    // scan will re-create it only if podman actually has a
+                    // container for it (partial install recovery).
+                    remove_package_entry(&handler.state_manager, &package_id_spawn).await;
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "installing",
+            "package_id": package_id,
+        }))
+    }
+
+    /// Async wrapper for `package.uninstall`. Returns `{ "status": "removing" }`
+    /// immediately. State stays `Removing` until the inner handler finishes
+    /// (including the `sudo rm -rf` of app data, which can take minutes for
+    /// bitcoin-core's chainstate). On failure, reverts to the pre-transition
+    /// state (usually Running or Stopped) so the user can retry.
+    pub(in crate::api::rpc) async fn spawn_package_uninstall(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle.
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing | PackageState::Removing | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        let pre_state =
+            flip_package_state(&self.state_manager, &package_id, PackageState::Removing).await;
+
+        install_log(&format!("UNINSTALL SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_uninstall(params).await {
+                Ok(_) => {
+                    info!("package.uninstall {}: complete", package_id_spawn);
+                    // Inner handler already removed the package entry on
+                    // success. Nothing more to do here.
+                }
+                Err(e) => {
+                    error!("package.uninstall {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!("UNINSTALL FAIL: {} — {:#}", package_id_spawn, e)).await;
+                    // Revert to pre-transition state so the user can retry.
+                    // Also clear any stale uninstall_stage label.
+                    if let Some(prev) = pre_state {
+                        set_package_state_and_clear_uninstall_stage(
+                            &handler.state_manager,
+                            &package_id_spawn,
+                            prev,
+                        )
+                        .await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "removing",
+            "package_id": package_id,
+        }))
+    }
+
+    /// Async wrapper for `package.update`. Returns `{ "status": "updating" }`
+    /// immediately. The inner handler already manages its own rollback on
+    /// failure (restarts old containers); this wrapper just flips state and
+    /// spawns.
+    pub(in crate::api::rpc) async fn spawn_package_update(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle.
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing | PackageState::Removing | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        // The inner handler flips state to Updating itself, but we do it
+        // here too so the transitional state lands before the spawn yields.
+        let pre_state =
+            flip_package_state(&self.state_manager, &package_id, PackageState::Updating).await;
+
+        install_log(&format!("UPDATE SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_update(params).await {
+                Ok(_) => {
+                    info!("package.update {}: complete", package_id_spawn);
+                    // Same reasoning as install: the merge_preserving_transitional
+                    // helper treats Updating as RPC-owned, so we MUST write the
+                    // terminal Running state ourselves or the entry will stay
+                    // stuck at Updating forever. The update pipeline has
+                    // already verified the new container is running via its
+                    // post-recreate check.
+                    // Kick the scanner first so any manifest changes from the
+                    // new image version (interfaces, ports, etc.) land before
+                    // we flip to Running.
+                    kick_scanner_and_wait(&handler).await;
+                    set_package_state(
+                        &handler.state_manager,
+                        &package_id_spawn,
+                        PackageState::Running,
+                    )
+                    .await;
+                }
+                Err(e) => {
+                    error!("package.update {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!("UPDATE FAIL: {} — {:#}", package_id_spawn, e)).await;
+                    // Inner handler already ran rollback_update + cleared
+                    // update state, but be defensive: revert to pre-state
+                    // in case the inner flow died before its cleanup.
+                    if let Some(prev) = pre_state {
+                        set_package_state(&handler.state_manager, &package_id_spawn, prev).await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "updating",
+            "package_id": package_id,
+        }))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// State-manager helpers (free fns, usable from inside spawned tasks)
+// ---------------------------------------------------------------------------
+
+/// Create or update the entry for this package with `Installing` state.
+/// Matches what the inner handler's `set_install_progress` would do on first
+/// call, but fires before the spawn so the UI sees it immediately.
+async fn flip_to_installing(state_manager: &StateManager, package_id: &str) {
+    use crate::data_model::{Description, Manifest, PackageDataEntry, StaticFiles};
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let entry = data
+        .package_data
+        .entry(package_id.to_string())
+        .or_insert_with(|| PackageDataEntry {
+            state: PackageState::Installing,
+            health: None,
+            exit_code: None,
+            static_files: StaticFiles {
+                license: String::new(),
+                instructions: String::new(),
+                // Leave icon empty during the transient Installing window:
+                // hardcoding `<id>.png` is wrong for ~half our apps (many use
+                // `.svg` / `.webp`), producing a broken-image flicker until
+                // the scanner refreshes the entry. The frontend's `icon`
+                // computed falls through to `curatedMap.get(id)?.icon` which
+                // has the correct extensions for known apps.
+                icon: String::new(),
+            },
+            manifest: Manifest {
+                id: package_id.to_string(),
+                title: package_id.to_string(),
+                version: String::new(),
+                description: Description {
+                    short: "Installing...".to_string(),
+                    long: String::new(),
+                },
+                release_notes: String::new(),
+                license: String::new(),
+                wrapper_repo: String::new(),
+                upstream_repo: String::new(),
+                support_site: String::new(),
+                marketing_site: String::new(),
+                donation_url: None,
+                author: None,
+                website: None,
+                interfaces: None,
+                tier: None,
+            },
+            installed: None,
+            install_progress: None,
+            uninstall_stage: None,
+            available_update: None,
+        });
+    entry.state = PackageState::Installing;
+    state_manager.update_data(data).await;
+}
+
+/// Flip an existing entry's state and return the pre-flip value (or None if
+/// no entry existed). Used for revert-on-failure.
+async fn flip_package_state(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(package_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = new_state;
+        state_manager.update_data(data).await;
+    } else {
+        warn!(
+            "flip_package_state: no entry for {} — cannot flip",
+            package_id
+        );
+    }
+    prev
+}
+
+/// Set state unconditionally (no-op if entry no longer exists).
+async fn set_package_state(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
+
+/// Set state and clear the uninstall_stage label. Used when an uninstall
+/// fails and we revert — the user doesn't want a stale "Removing app data"
+/// message sitting on a Running entry.
+async fn set_package_state_and_clear_uninstall_stage(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = new_state;
+        entry.uninstall_stage = None;
+        state_manager.update_data(data).await;
+    }
+}
+
+/// Remove a package entry from state. Used for install-failure cleanup
+/// (since there's no pre-state to revert to — the entry was created
+/// speculatively when we flipped to Installing).
+async fn remove_package_entry(state_manager: &StateManager, package_id: &str) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if data.package_data.remove(package_id).is_some() {
+        state_manager.update_data(data).await;
+    }
+}
+
+/// Kick the container scanner to run immediately and wait for it to finish
+/// (with a 2s timeout). Used by install/update success paths so the fresh
+/// manifest — with `interfaces.main.ui` populated from the now-running
+/// container's port binding — lands BEFORE we flip state to Running.
+///
+/// Without this, the frontend sees `state = running` but the skeletal
+/// install-time manifest (interfaces = None), and hides the Launch button
+/// for up to the full 60s scan interval.
+///
+/// The scan merges via `merge_preserving_transitional`, which keeps
+/// state = Installing (we haven't flipped yet) while taking the fresh
+/// manifest. After this returns, the caller writes Running on top of the
+/// now-populated manifest.
+async fn kick_scanner_and_wait(handler: &RpcHandler) {
+    let mut rx = handler.scan_tick.subscribe();
+    let start = *rx.borrow_and_update();
+    handler.scan_kick.notify_one();
+    // 2s is well above a typical podman scan (~200ms on .228, ~500ms worst
+    // case). If it times out we proceed anyway — the next 60s scan will
+    // self-heal and the worst case is the pre-fix behavior (Launch button
+    // appears a bit late).
+    let _ = tokio::time::timeout(std::time::Duration::from_secs(2), async {
+        while *rx.borrow_and_update() == start {
+            if rx.changed().await.is_err() {
+                break;
+            }
+        }
+    })
+    .await;
+}
@@ -9,7 +9,7 @@ pub(super) const TRUSTED_REGISTRIES: &[&str] = &[
    "ghcr.io/",
    "localhost/",
    "git.tx1138.com/",
-    "23.182.128.160:3000/",
+    "146.59.87.168:3000/",
 ];

 /// Validate Docker image against trusted registry allowlist.
@@ -29,7 +29,7 @@ pub(super) fn is_valid_docker_image(image: &str) -> bool {
    };
    matches!(
        registry,
-        "docker.io" | "ghcr.io" | "localhost" | "git.tx1138.com" | "23.182.128.160:3000"
+        "docker.io" | "ghcr.io" | "localhost" | "git.tx1138.com" | "146.59.87.168:3000"
    )
 }

@@ -174,7 +174,7 @@ pub(super) fn get_health_check_args(app_id: &str, _rpc_pass: &str) -> Vec<String
            ("curl -sf http://localhost:8000/ || exit 1", "60s", "3")
        }
        "nextcloud" => (
-            "curl -sf http://localhost:80/status.php || exit 1",
+            "curl -s -o /dev/null http://localhost:80/status.php || exit 1",
            "30s",
            "3",
        ),
@@ -194,7 +194,12 @@ pub(super) fn get_health_check_args(app_id: &str, _rpc_pass: &str) -> Vec<String
        "vaultwarden" => ("curl -sf http://localhost:80/alive || exit 1", "30s", "3"),
        "uptime-kuma" => ("curl -sf http://localhost:3001/ || exit 1", "30s", "3"),
        "filebrowser" => ("curl -sf http://localhost:80/health || exit 1", "30s", "3"),
-        "searxng" => ("curl -sf http://localhost:8080/ || exit 1", "30s", "3"),
+        "botfights" => (
+            "node -e \"fetch(\\\"http://127.0.0.1:9100/api/health\\\").then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"",
+            "30s",
+            "3",
+        ),
+        "searxng" => ("wget -q -O /dev/null http://localhost:8080/ || exit 1", "30s", "3"),
        "photoprism" => (
            "curl -sf http://localhost:2342/api/v1/status || exit 1",
            "60s",
@@ -210,11 +215,7 @@ pub(super) fn get_health_check_args(app_id: &str, _rpc_pass: &str) -> Vec<String
            "30s",
            "3",
        ),
-        "portainer" => (
-            "curl -sf http://localhost:9000/api/status || exit 1",
-            "30s",
-            "3",
-        ),
+        "portainer" => return vec![],
        "ollama" => ("curl -sf http://localhost:11434/ || exit 1", "30s", "3"),
        "fedimint" => ("curl -sf http://localhost:8175/ || exit 1", "60s", "3"),
        "fedimint-gateway" => ("curl -sf http://localhost:8176/ || exit 1", "60s", "3"),
@@ -402,7 +403,6 @@ pub(super) fn get_data_dirs_for_app(package_id: &str) -> Vec<String> {
            format!("{}/mempool", base),
            format!("{}/mysql-mempool", base),
            format!("{}/electrumx", base),
-            format!("{}/mempool-electrs", base),
        ],
        "fedimint" => vec![
            format!("{}/fedimint", base),
@@ -483,7 +483,30 @@ pub(super) async fn get_app_config(
            None,
            None,
        ),
-        "bitcoin" | "bitcoin-core" | "bitcoin-knots" => (
+        "bitcoin-core" => (
+            vec![
+                "8332:8332".to_string(),
+                "8333:8333".to_string(),
+                "28332:28332".to_string(),
+                "28333:28333".to_string(),
+            ],
+            vec!["/var/lib/archipelago/bitcoin:/home/bitcoin/.bitcoin".to_string()],
+            vec![],
+            None,
+            // Vanilla bitcoin/bitcoin image has no entrypoint wrapper and reads
+            // only what's in bitcoin.conf + argv. The shared bitcoin.conf
+            // carries rpcauth; we inject the networking flags as CLI args so
+            // RPC is reachable from the bitcoin-ui companion container.
+            Some(vec![
+                "-server=1".to_string(),
+                "-rpcbind=0.0.0.0".to_string(),
+                "-rpcallowip=0.0.0.0/0".to_string(),
+                "-rpcport=8332".to_string(),
+                "-printtoconsole=1".to_string(),
+                "-datadir=/home/bitcoin/.bitcoin".to_string(),
+            ]),
+        ),
+        "bitcoin" | "bitcoin-knots" => (
            vec![
                "8332:8332".to_string(),
                "8333:8333".to_string(),
@@ -510,9 +533,7 @@ pub(super) async fn get_app_config(
                "--bitcoin.node=bitcoind".to_string(),
                format!("--bitcoind.rpcuser={}", rpc_user),
                format!("--bitcoind.rpcpass={}", rpc_pass),
-                "--bitcoind.rpchost=host.containers.internal:8332".to_string(),
-                "--bitcoind.zmqpubrawblock=tcp://host.containers.internal:28332".to_string(),
-                "--bitcoind.zmqpubrawtx=tcp://host.containers.internal:28333".to_string(),
+                "--bitcoind.rpchost=bitcoin-knots:8332".to_string(),
                "--rpclisten=0.0.0.0:10009".to_string(),
                "--restlisten=0.0.0.0:8080".to_string(),
                "--listen=0.0.0.0:9735".to_string(),
@@ -526,7 +547,8 @@ pub(super) async fn get_app_config(
                "BTCPAY_PROTOCOL=http".to_string(),
                format!("BTCPAY_HOST={}:23000", host_ip),
                "BTCPAY_CHAINS=btc".to_string(),
-                format!("BTCPAY_BTCRPCURL=http://{}:8332", host_ip),
+                "BTCPAY_BTCEXPLORERURL=http://archy-nbxplorer:32838".to_string(),
+                "BTCPAY_BTCRPCURL=http://bitcoin-knots:8332".to_string(),
                format!("BTCPAY_BTCRPCUSER={}", rpc_user),
                format!("BTCPAY_BTCRPCPASSWORD={}", rpc_pass),
                format!("BTCPAY_POSTGRES=User ID=btcpay;Password={};Host=archy-btcpay-db;Port=5432;Database=btcpay;Include Error Detail=true",
@@ -538,7 +560,7 @@ pub(super) async fn get_app_config(
        "mempool" | "mempool-web" => (
            vec!["4080:8080".to_string()],
            vec![],
-            vec![format!("BACKEND_MAINNET_HTTP_HOST={}", host_ip)],
+            vec!["BACKEND_MAINNET_HTTP_HOST=mempool-api".to_string()],
            None,
            None,
        ),
@@ -547,12 +569,12 @@ pub(super) async fn get_app_config(
            vec!["/var/lib/archipelago/mempool:/data".to_string()],
            vec![
                "MEMPOOL_BACKEND=electrum".to_string(),
-                "ELECTRUM_HOST=host.containers.internal".to_string(),
+                "ELECTRUM_HOST=electrumx".to_string(),
                "ELECTRUM_PORT=50001".to_string(),
                "ELECTRUM_TLS_ENABLED=false".to_string(),
-                format!("CORE_RPC_HOST={}", host_ip),
+                "CORE_RPC_HOST=bitcoin-knots".to_string(),
                "CORE_RPC_PORT=8332".to_string(),
-                format!("CORE_RPC_USERNAME={}", rpc_user),
+                "CORE_RPC_USERNAME=archipelago".to_string(),
                format!("CORE_RPC_PASSWORD={}", rpc_pass),
                "DATABASE_ENABLED=true".to_string(),
                "DATABASE_HOST=archy-mempool-db".to_string(),
@@ -569,7 +591,7 @@ pub(super) async fn get_app_config(
                vec!["/var/lib/archipelago/electrumx:/data".to_string()],
                vec![
                    format!(
-                        "DAEMON_URL=http://{}:{}@host.containers.internal:8332/",
+                        "DAEMON_URL=http://{}:{}@bitcoin-knots:8332/",
                        rpc_user, rpc_pass
                    ),
                    "COIN=Bitcoin".to_string(),
@@ -587,7 +609,7 @@ pub(super) async fn get_app_config(
                "MYSQL_DATABASE=mempool".to_string(),
                "MYSQL_USER=mempool".to_string(),
                format!("MYSQL_PASSWORD={}", read_secret("mempool-db-password", "mempoolpass")),
-                format!("MYSQL_ROOT_PASSWORD={}", read_secret("mempool-db-root-password", "rootpass")),
+                format!("MYSQL_ROOT_PASSWORD={}", read_secret("mysql-root-db-password", "rootpass")),
            ],
            None,
            None,
@@ -729,14 +751,14 @@ pub(super) async fn get_app_config(
            vec!["9000:9000".to_string()],
            vec![
                "/var/lib/archipelago/portainer:/data".to_string(),
-                "/var/run/podman/podman.sock:/var/run/docker.sock".to_string(),
+                "/run/user/1000/podman/podman.sock:/var/run/docker.sock".to_string(),
            ],
            vec![],
            None,
            None,
        ),
        "uptime-kuma" => (
-            vec!["3001:3001".to_string()],
+            vec!["3002:3001".to_string()],
            vec!["/var/lib/archipelago/uptime-kuma:/app/data".to_string()],
            vec!["TZ=UTC".to_string()],
            None,
@@ -746,10 +768,17 @@ pub(super) async fn get_app_config(
            vec!["8240:8240".to_string()],
            vec!["/var/lib/archipelago/tailscale:/var/lib/tailscale".to_string()],
            vec!["TS_STATE_DIR=/var/lib/tailscale".to_string()],
-            Some(
-                "sh -c 'tailscale web --listen 0.0.0.0:8240 & exec tailscaled'".to_string(),
-            ),
+            // Don't use custom_command (Option<String>) — install.rs passes
+            // it as a SINGLE arg to podman, which then treats the whole
+            // "sh -c 'tailscale web …'" string as the executable name and
+            // fails: "executable file `sh -c 'tailscale web …'` not found".
+            // custom_args (Option<Vec<String>>) splits properly.
            None,
+            Some(vec![
+                "sh".to_string(),
+                "-c".to_string(),
+                "tailscale web --listen 0.0.0.0:8240 & exec tailscaled".to_string(),
+            ]),
        ),
        "fedimint" => (
            vec![
@@ -768,13 +797,13 @@ pub(super) async fn get_app_config(
                "FM_BIND_UI=0.0.0.0:8175".to_string(),
                format!("FM_P2P_URL=fedimint://{}:8173", host_ip),
                format!("FM_API_URL=ws://{}:8174", host_ip),
-                format!("FM_BITCOIND_URL=http://{}:8332", host_ip),
+                "FM_BITCOIND_URL=http://bitcoin-knots:8332".to_string(),
            ],
            None,
            Some(vec![
                "--data-dir".to_string(),
                "/data".to_string(),
-                format!("--bitcoind-url=http://{}:{}@{}:8332", rpc_user, rpc_pass, host_ip),
+                format!("--bitcoind-url=http://{}:{}@bitcoin-knots:8332", rpc_user, rpc_pass),
            ]),
        ),
        "fedimint-gateway" => {
@@ -798,7 +827,7 @@ pub(super) async fn get_app_config(
                    "--network".to_string(),
                    "bitcoin".to_string(),
                    "--bitcoind-url".to_string(),
-                    format!("http://{}:8332", host_ip),
+                    "http://bitcoin-knots:8332".to_string(),
                    "--bitcoind-username".to_string(),
                    rpc_user.to_string(),
                    "--bitcoind-password".to_string(),
@@ -1,3 +1,4 @@
+mod async_lifecycle;
 mod config;
 mod dependencies;
 mod install;
@@ -8,5 +9,6 @@ mod stacks;
 mod update;
 mod validation;

-// Re-export items needed by sibling modules (container.rs, security.rs)
+// Re-export items needed by sibling modules (container.rs, security.rs, transitional.rs)
+pub(in crate::api::rpc) use install::install_log;
 pub(super) use validation::validate_app_id;
@@ -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,42 @@ 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;
    }

@@ -28,6 +68,18 @@ impl RpcHandler {
        self.state_manager.update_data(data).await;
    }

+    /// Set the uninstall stage label so the UI can show what's happening
+    /// instead of a generic spinner. Each call broadcasts a state change
+    /// — call sparingly (one per pipeline phase, not per container).
+    pub(super) async fn set_uninstall_stage(&self, package_id: &str, stage: &str) {
+        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        if let Some(entry) = data.package_data.get_mut(package_id) {
+            entry.uninstall_stage = Some(stage.to_string());
+            entry.state = crate::data_model::PackageState::Removing;
+        }
+        self.state_manager.update_data(data).await;
+    }
+
    /// Update install progress (static method for use in async closures).
    pub(super) async fn update_install_progress(
        state_manager: &crate::state::StateManager,
@@ -40,9 +92,11 @@ 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;
    }
@@ -57,7 +111,11 @@ fn create_installing_entry(package_id: &str) -> PackageDataEntry {
        static_files: StaticFiles {
            license: String::new(),
            instructions: String::new(),
-            icon: format!("/assets/img/app-icons/{}.png", package_id),
+            // Empty icon: hardcoding `<id>.png` is wrong for apps that use
+            // `.svg` or `.webp` assets and produces a broken-image flicker.
+            // The frontend's `icon` computed falls through to the curated
+            // map which has correct extensions for known apps.
+            icon: String::new(),
        },
        manifest: Manifest {
            id: package_id.to_string(),
@@ -81,6 +139,7 @@ fn create_installing_entry(package_id: &str) -> PackageDataEntry {
        },
        installed: None,
        install_progress: None,
+        uninstall_stage: None,
        available_update: None,
    }
 }
@@ -3,7 +3,10 @@ use super::dependencies::ordered_containers_for_start;
 use super::install::install_log;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
+use crate::data_model::PackageState;
 use anyhow::{Context, Result};
+use std::sync::Arc;
+use tracing::warn;

 /// Per-container graceful shutdown timeout in seconds.
 /// Bitcoin Core needs 600s to flush UTXO set, LND 330s for channel state,
@@ -25,6 +28,12 @@ pub fn stop_timeout_secs(container_name: &str) -> &'static str {

 impl RpcHandler {
    /// Start a package: start all containers in dependency order.
+    ///
+    /// Returns immediately with `{ "status": "starting" }` after flipping
+    /// the package state to `Starting` in the StateManager. The actual
+    /// podman-start sequence + post-start exit verification runs in a
+    /// background task. On success the state becomes `Running`; on error
+    /// it reverts to the pre-transition state.
    pub(in crate::api::rpc) async fn handle_package_start(
        &self,
        params: Option<serde_json::Value>,
@@ -42,83 +51,52 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

-        // Clear user-stopped flag — user explicitly started this app
+        // Clear user-stopped flag — user explicitly started this app.
+        // Must happen BEFORE the spawn (ordering contract with crash recovery).
        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, package_id).await;
        for name in &to_start {
            crate::crash_recovery::clear_user_stopped(&self.config.data_dir, name).await;
        }

+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Starting).await;
+
        install_log(&format!(
            "START: {} (containers: {:?})",
-            package_id, to_start
+            package_id_owned, to_start
        ))
        .await;
-        let mut errors = Vec::new();
-        for (i, name) in to_start.iter().enumerate() {
-            // Brief delay between dependent containers to allow initialization
-            if i > 0 {
-                tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-            }
-            tracing::info!("Starting container: {}", name);
-            let out = tokio::process::Command::new("podman")
-                .args(["start", name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman start {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::error!("Failed to start {}: {}", name, stderr);
-                install_log(&format!("START FAIL: {} — {}", name, stderr)).await;
-                errors.push(format!("{}: {}", name, stderr));
-            }
-        }

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Start failed: {}", errors.join("; ")));
-        }
-
-        // Verify containers actually reached running state (podman start can
-        // succeed even if the container exits immediately after)
-        tokio::time::sleep(std::time::Duration::from_secs(3)).await;
-        for name in &to_start {
-            let status = tokio::process::Command::new("podman")
-                .args(["inspect", name, "--format", "{{.State.Status}}"])
-                .output()
-                .await;
-            if let Ok(o) = status {
-                let state = String::from_utf8_lossy(&o.stdout).trim().to_string();
-                if state == "exited" {
-                    let logs = tokio::process::Command::new("podman")
-                        .args(["logs", "--tail", "5", name])
-                        .output()
+        tokio::spawn(async move {
+            match do_package_start(&to_start).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Running)
                        .await;
-                    let log_text = logs
-                        .map(|o| {
-                            let combined = format!(
-                                "{}{}",
-                                String::from_utf8_lossy(&o.stdout),
-                                String::from_utf8_lossy(&o.stderr)
-                            );
-                            combined.chars().take(200).collect::<String>()
-                        })
-                        .unwrap_or_default();
-                    tracing::error!("Container {} exited after start: {}", name, log_text);
-                    install_log(&format!("START EXITED: {} — {}", name, log_text)).await;
-                    errors.push(format!("{}: exited after start", name));
+                }
+                Err(e) => {
+                    tracing::error!("package.start {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("START FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    } else {
+                        warn!(
+                            "package.start {}: no pre-state recorded; relying on next scan",
+                            package_id_owned
+                        );
+                    }
                }
            }
-        }
+        });

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!(
-                "Containers exited after start: {}",
-                errors.join("; ")
-            ));
-        }
-        Ok(serde_json::Value::Null)
+        Ok(serde_json::json!({ "status": "starting" }))
    }

    /// Stop a package: mark as user-stopped and stop all containers.
+    ///
+    /// Returns immediately with `{ "status": "stopping" }`. podman stop
+    /// (up to 600s for bitcoin-core) runs in the background.
    pub(in crate::api::rpc) async fn handle_package_stop(
        &self,
        params: Option<serde_json::Value>,
@@ -136,43 +114,48 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

-        install_log(&format!(
-            "STOP: {} (containers: {:?})",
-            package_id, containers
-        ))
-        .await;
-        // Mark as user-stopped so health monitor and crash recovery don't auto-restart
+        // Mark as user-stopped BEFORE the spawn so health monitor and
+        // crash recovery don't auto-restart mid-flight. Ordering is
+        // load-bearing — see runtime.rs:145-148 original note.
        crate::crash_recovery::mark_user_stopped(&self.config.data_dir, package_id).await;
        for name in &containers {
            crate::crash_recovery::mark_user_stopped(&self.config.data_dir, name).await;
        }

-        let mut errors = Vec::new();
-        for name in &containers {
-            tracing::info!(
-                "Stopping container: {} (timeout: {}s)",
-                name,
-                stop_timeout_secs(name)
-            );
-            let out = tokio::process::Command::new("podman")
-                .args(["stop", "-t", stop_timeout_secs(name), name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman stop {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::error!("Failed to stop {}: {}", name, stderr);
-                errors.push(format!("{}: {}", name, stderr));
-            }
-        }
+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Stopping).await;

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Stop failed: {}", errors.join("; ")));
-        }
-        Ok(serde_json::Value::Null)
+        install_log(&format!(
+            "STOP: {} (containers: {:?})",
+            package_id_owned, containers
+        ))
+        .await;
+
+        tokio::spawn(async move {
+            match do_package_stop(&containers).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Stopped)
+                        .await;
+                }
+                Err(e) => {
+                    tracing::error!("package.stop {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("STOP FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({ "status": "stopping" }))
    }

    /// Restart a package: restart all containers.
+    ///
+    /// Returns immediately with `{ "status": "restarting" }`. The restart
+    /// (up to 600s per container for bitcoin-core) runs in the background.
    pub(in crate::api::rpc) async fn handle_package_restart(
        &self,
        params: Option<serde_json::Value>,
@@ -190,55 +173,42 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

+        // Restart does not mark user-stopped; user wants the app to keep
+        // running. Clear any lingering marker so downstream layers don't
+        // interpret the brief podman stop as user intent.
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, package_id).await;
+        for name in &containers {
+            crate::crash_recovery::clear_user_stopped(&self.config.data_dir, name).await;
+        }
+
+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Restarting).await;
+
        install_log(&format!(
            "RESTART: {} (containers: {:?})",
-            package_id, containers
+            package_id_owned, containers
        ))
        .await;
-        let mut errors = Vec::new();
-        for name in &containers {
-            tracing::info!("Restarting container: {}", name);
-            let out = tokio::process::Command::new("podman")
-                .args(["restart", "-t", stop_timeout_secs(name), name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman restart {}", name))?;

-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::warn!(
-                    "podman restart {} failed: {}, trying stop+start",
-                    name,
-                    stderr
-                );
-
-                // Fallback: stop then start (handles rootless podman loopback issues)
-                let _ = tokio::process::Command::new("podman")
-                    .args(["stop", "-t", stop_timeout_secs(name), name])
-                    .output()
-                    .await;
-                let start_out = tokio::process::Command::new("podman")
-                    .args(["start", name])
-                    .output()
-                    .await
-                    .context(format!("Failed to exec podman start {}", name))?;
-
-                if !start_out.status.success() {
-                    let start_err = String::from_utf8_lossy(&start_out.stderr)
-                        .trim()
-                        .to_string();
-                    tracing::error!("stop+start {} also failed: {}", name, start_err);
-                    errors.push(format!("{}: {}", name, start_err));
-                } else {
-                    tracing::info!("Restarted {} via stop+start fallback", name);
+        tokio::spawn(async move {
+            match do_package_restart(&containers).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Running)
+                        .await;
+                }
+                Err(e) => {
+                    tracing::error!("package.restart {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("RESTART FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    }
                }
            }
-        }
+        });

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Restart failed: {}", errors.join("; ")));
-        }
-        Ok(serde_json::Value::Null)
+        Ok(serde_json::json!({ "status": "restarting" }))
    }

    /// Uninstall a package: stop and remove all related containers, clean data.
@@ -261,12 +231,28 @@ impl RpcHandler {
        if containers_to_remove.is_empty() {
            tracing::warn!("Uninstall {}: no containers found", package_id);
        }
+        let total = containers_to_remove.len();

        let mut stopped = 0u32;
        let mut removed = 0u32;
        let mut errors = Vec::new();

-        for name in &containers_to_remove {
+        self.set_uninstall_stage(
+            package_id,
+            &if total > 0 {
+                format!("Stopping containers (0/{})", total)
+            } else {
+                "Cleaning up".to_string()
+            },
+        )
+        .await;
+
+        for (i, name) in containers_to_remove.iter().enumerate() {
+            self.set_uninstall_stage(
+                package_id,
+                &format!("Stopping containers ({}/{})", i + 1, total),
+            )
+            .await;
            tracing::info!("Uninstall {}: stopping container {}", package_id, name);
            let stop_out = tokio::process::Command::new("podman")
                .args(["stop", "-t", stop_timeout_secs(name), name])
@@ -326,6 +312,8 @@ impl RpcHandler {
            }
        }

+        self.set_uninstall_stage(package_id, "Cleaning up volumes")
+            .await;
        // Clean up dangling volumes associated with removed containers
        let _ = tokio::process::Command::new("podman")
            .args(["volume", "prune", "-f"])
@@ -354,6 +342,8 @@ impl RpcHandler {

        // Clean data directories unless preserve_data
        if !preserve_data {
+            self.set_uninstall_stage(package_id, "Removing app data")
+                .await;
            let data_dirs = get_data_dirs_for_app(package_id);
            for dir in &data_dirs {
                tracing::info!("Uninstall {}: removing data {}", package_id, dir);
@@ -561,3 +551,185 @@ impl RpcHandler {
        Ok(serde_json::json!({ "status": "stopped", "app_id": app_id }))
    }
 }
+
+// ---------------------------------------------------------------------------
+// Background workers for async package lifecycle RPCs.
+//
+// Extracted from the pre-async RPC handlers so the transitional state is
+// visible to the UI immediately. Each worker is pure IO over podman + the
+// crash_recovery helpers — no StateManager access here so we don't need
+// a handler reference. The caller does state flipping before/after.
+// ---------------------------------------------------------------------------
+
+/// Start containers in dependency order. Includes the post-start 3s wait +
+/// exit-check verification from the original synchronous handler (critical
+/// for catching "podman start succeeded but container immediately exited"
+/// failure modes).
+async fn do_package_start(to_start: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for (i, name) in to_start.iter().enumerate() {
+        if i > 0 {
+            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+        }
+        tracing::info!("Starting container: {}", name);
+        let out = tokio::process::Command::new("podman")
+            .args(["start", name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman start {}", name))?;
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::error!("Failed to start {}: {}", name, stderr);
+            install_log(&format!("START FAIL: {} — {}", name, stderr)).await;
+            errors.push(format!("{}: {}", name, stderr));
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Start failed: {}", errors.join("; ")));
+    }
+
+    // Post-start exit verification (podman start can succeed even if the
+    // container exits immediately after).
+    tokio::time::sleep(std::time::Duration::from_secs(3)).await;
+    for name in to_start {
+        let status = tokio::process::Command::new("podman")
+            .args(["inspect", name, "--format", "{{.State.Status}}"])
+            .output()
+            .await;
+        if let Ok(o) = status {
+            let state = String::from_utf8_lossy(&o.stdout).trim().to_string();
+            if state == "exited" {
+                let logs = tokio::process::Command::new("podman")
+                    .args(["logs", "--tail", "5", name])
+                    .output()
+                    .await;
+                let log_text = logs
+                    .map(|o| {
+                        let combined = format!(
+                            "{}{}",
+                            String::from_utf8_lossy(&o.stdout),
+                            String::from_utf8_lossy(&o.stderr)
+                        );
+                        combined.chars().take(200).collect::<String>()
+                    })
+                    .unwrap_or_default();
+                tracing::error!("Container {} exited after start: {}", name, log_text);
+                install_log(&format!("START EXITED: {} — {}", name, log_text)).await;
+                errors.push(format!("{}: exited after start", name));
+            }
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!(
+            "Containers exited after start: {}",
+            errors.join("; ")
+        ));
+    }
+    Ok(())
+}
+
+/// Stop all containers with their per-container graceful-shutdown timeout.
+async fn do_package_stop(containers: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for name in containers {
+        tracing::info!(
+            "Stopping container: {} (timeout: {}s)",
+            name,
+            stop_timeout_secs(name)
+        );
+        let out = tokio::process::Command::new("podman")
+            .args(["stop", "-t", stop_timeout_secs(name), name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman stop {}", name))?;
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::error!("Failed to stop {}: {}", name, stderr);
+            errors.push(format!("{}: {}", name, stderr));
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Stop failed: {}", errors.join("; ")));
+    }
+    Ok(())
+}
+
+/// Restart via `podman restart`, falling back to stop+start when restart
+/// fails (rootless podman loopback issues).
+async fn do_package_restart(containers: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for name in containers {
+        tracing::info!("Restarting container: {}", name);
+        let out = tokio::process::Command::new("podman")
+            .args(["restart", "-t", stop_timeout_secs(name), name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman restart {}", name))?;
+
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::warn!(
+                "podman restart {} failed: {}, trying stop+start",
+                name,
+                stderr
+            );
+            // Fallback: stop then start
+            let _ = tokio::process::Command::new("podman")
+                .args(["stop", "-t", stop_timeout_secs(name), name])
+                .output()
+                .await;
+            let start_out = tokio::process::Command::new("podman")
+                .args(["start", name])
+                .output()
+                .await
+                .context(format!("Failed to exec podman start {}", name))?;
+            if !start_out.status.success() {
+                let start_err = String::from_utf8_lossy(&start_out.stderr)
+                    .trim()
+                    .to_string();
+                tracing::error!("stop+start {} also failed: {}", name, start_err);
+                errors.push(format!("{}: {}", name, start_err));
+            } else {
+                tracing::info!("Restarted {} via stop+start fallback", name);
+            }
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Restart failed: {}", errors.join("; ")));
+    }
+    Ok(())
+}
+
+/// Flip the primary package entry's state and return the pre-transition
+/// state for revert on error. Mirrors `transitional::flip_to_transitional`
+/// but lives here because the package path keys by `package_id` (which may
+/// differ from the container name used by orchestrator-level entries).
+async fn flip_package_state(
+    state_manager: &crate::state::StateManager,
+    package_id: &str,
+    transitional: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(package_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = transitional;
+        state_manager.update_data(data).await;
+    }
+    prev
+}
+
+/// Write the package entry's final state. No-op if the entry has since
+/// been removed (uninstall race).
+async fn set_package_state(
+    state_manager: &crate::state::StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
@@ -4,6 +4,7 @@
 //! containers in dependency order.

 use crate::api::rpc::RpcHandler;
+use crate::data_model::InstallPhase;
 use anyhow::{Context, Result};
 use tracing::info;

@@ -60,7 +61,71 @@ async fn adopt_stack_if_exists(
    })))
 }

-const REGISTRY: &str = "git.tx1138.com/lfg2025";
+async fn install_stack_via_orchestrator(
+    handler: &RpcHandler,
+    stack_name: &str,
+    app_ids: &[&str],
+) -> Result<Option<serde_json::Value>> {
+    let Some(orchestrator) = handler.orchestrator.as_ref() else {
+        return Ok(None);
+    };
+
+    install_log(&format!(
+        "INSTALL ORCH: {} stack — attempting orchestrator install of [{}]",
+        stack_name,
+        app_ids.join(", ")
+    ))
+    .await;
+
+    for app_id in app_ids {
+        match orchestrator.install(app_id).await {
+            Ok(container_name) => {
+                install_log(&format!(
+                    "INSTALL ORCH: {} stack — app {} installed as {}",
+                    stack_name, app_id, container_name
+                ))
+                .await;
+            }
+            Err(e) if e.to_string().contains("unknown app_id") => {
+                install_log(&format!(
+                    "INSTALL ORCH SKIP: {} stack — app {} unknown, falling back to legacy stack installer",
+                    stack_name, app_id
+                ))
+                .await;
+                return Ok(None);
+            }
+            Err(e) => {
+                install_log(&format!(
+                    "INSTALL ORCH FAIL: {} stack — app {} failed: {}",
+                    stack_name, app_id, e
+                ))
+                .await;
+                return Err(e.context(format!(
+                    "orchestrator stack install {} failed at app {}",
+                    stack_name, app_id
+                )));
+            }
+        }
+    }
+
+    install_log(&format!("INSTALL ORCH OK: {} stack", stack_name)).await;
+    Ok(Some(serde_json::json!({
+        "success": true,
+        "package_id": stack_name,
+        "message": format!("{} stack installed and started", stack_name),
+        "path": "orchestrator"
+    })))
+}
+
+fn btcpay_stack_app_ids() -> &'static [&'static str] {
+    &["archy-btcpay-db", "archy-nbxplorer", "btcpay-server"]
+}
+
+fn mempool_stack_app_ids() -> &'static [&'static str] {
+    &["archy-mempool-db", "mempool-api", "archy-mempool-web"]
+}
+
+const REGISTRY: &str = "146.59.87.168:3000/lfg2025";

 /// Pull an image with retry and exponential backoff (3 attempts).
 async fn pull_image_with_retry(image: &str) -> Result<()> {
@@ -135,13 +200,20 @@ impl RpcHandler {
        }

        let images = [
-            "git.tx1138.com/lfg2025/immich-postgres:14-vectorchord0.4.3-pgvectors0.2.0",
-            "git.tx1138.com/lfg2025/valkey:7-alpine",
-            "git.tx1138.com/lfg2025/immich-server:release",
+            "146.59.87.168:3000/lfg2025/immich-postgres:14-vectorchord0.4.3-pgvectors0.2.0",
+            "docker.io/valkey/valkey:7-alpine",
+            "146.59.87.168:3000/lfg2025/immich-server:release",
        ];
-        for img in &images {
+        self.set_install_phase("immich", InstallPhase::PullingImage)
+            .await;
+        let n_images = images.len() as u64;
+        for (i, img) in images.iter().enumerate() {
+            self.set_install_progress("immich", i as u64, n_images).await;
            pull_image_with_retry(img).await?;
        }
+        self.set_install_progress("immich", n_images, n_images).await;
+        self.set_install_phase("immich", InstallPhase::CreatingContainer)
+            .await;

        let _ = tokio::process::Command::new("sudo")
            .args([
@@ -152,6 +224,16 @@ impl RpcHandler {
            ])
            .output()
            .await;
+        let _ = tokio::process::Command::new("sudo")
+            .args([
+                "chown",
+                "-R",
+                "1000:1000",
+                "/var/lib/archipelago/immich",
+                "/var/lib/archipelago/immich-db",
+            ])
+            .output()
+            .await;
        let _ = tokio::process::Command::new("podman")
            .args(["network", "create", "immich-net"])
            .output()
@@ -191,7 +273,7 @@ impl RpcHandler {
                "POSTGRES_USER=postgres",
                "-e",
                "POSTGRES_DB=immich",
-                "git.tx1138.com/lfg2025/immich-postgres:14-vectorchord0.4.3-pgvectors0.2.0",
+                "146.59.87.168:3000/lfg2025/immich-postgres:14-vectorchord0.4.3-pgvectors0.2.0",
            ])
            .output()
            .await;
@@ -210,13 +292,15 @@ impl RpcHandler {
                "--network-alias",
                "immich_redis",
                "--cap-drop=ALL",
+                "--cap-add=SETGID",
+                "--cap-add=SETUID",
                "--security-opt=no-new-privileges:true",
                "--memory=128m",
                "--pids-limit=2048",
                "--health-cmd=valkey-cli ping || exit 1",
                "--health-interval=30s",
                "--health-retries=3",
-                "git.tx1138.com/lfg2025/valkey:7-alpine",
+                "docker.io/valkey/valkey:7-alpine",
            ])
            .output()
            .await;
@@ -254,7 +338,7 @@ impl RpcHandler {
                "REDIS_HOSTNAME=immich_redis",
                "-e",
                "UPLOAD_LOCATION=/usr/src/app/upload",
-                "git.tx1138.com/lfg2025/immich-server:release",
+                "146.59.87.168:3000/lfg2025/immich-server:release",
            ])
            .output()
            .await
@@ -265,6 +349,13 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("Failed to start Immich server: {}", stderr));
        }

+        self.set_install_phase("immich", InstallPhase::WaitingHealthy)
+            .await;
+        self.set_install_phase("immich", InstallPhase::PostInstall)
+            .await;
+        self.set_install_phase("immich", InstallPhase::Done).await;
+        self.clear_install_progress("immich").await;
+
        info!("Immich stack installed and started");
        Ok(serde_json::json!({
            "success": true,
@@ -273,235 +364,6 @@ impl RpcHandler {
        }))
    }

-    /// Install Penpot stack (postgres + valkey + backend + exporter + frontend).
-    pub(super) async fn install_penpot_stack(&self) -> Result<serde_json::Value> {
-        if let Some(adopted) = adopt_stack_if_exists(
-            "penpot-frontend",
-            "penpot",
-            &[
-                "penpot-postgres",
-                "penpot-valkey",
-                "penpot-backend",
-                "penpot-exporter",
-                "penpot-frontend",
-            ],
-        )
-        .await?
-        {
-            return Ok(adopted);
-        }
-
-        let images = [
-            "git.tx1138.com/lfg2025/postgres:15",
-            "git.tx1138.com/lfg2025/valkey:8.1",
-            "git.tx1138.com/lfg2025/penpot-backend:2.4",
-            "git.tx1138.com/lfg2025/penpot-exporter:2.4",
-            "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-        ];
-        for img in &images {
-            pull_image_with_retry(img).await?;
-        }
-
-        let _ = tokio::process::Command::new("sudo")
-            .args(["mkdir", "-p", "/var/lib/archipelago/penpot-assets"])
-            .output()
-            .await;
-        let _ = tokio::process::Command::new("podman")
-            .args(["network", "create", "penpot-net"])
-            .output()
-            .await;
-
-        // Generate a stable secret key derived from the data directory
-        let secret = {
-            use sha2::{Digest, Sha256};
-            let mut hasher = Sha256::new();
-            hasher.update(b"penpot-secret-");
-            hasher.update(self.config.data_dir.to_string_lossy().as_bytes());
-            hex::encode(hasher.finalize())
-        };
-        let host_ip = &self.config.host_ip;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-postgres",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-postgres",
-                "--cap-drop=ALL",
-                "--cap-add=CHOWN",
-                "--cap-add=DAC_OVERRIDE",
-                "--cap-add=FOWNER",
-                "--cap-add=SETGID",
-                "--cap-add=SETUID",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=4096",
-                "--health-cmd=pg_isready -U penpot || exit 1",
-                "--health-interval=30s",
-                "--health-retries=3",
-                "-v",
-                "/var/lib/archipelago/penpot-postgres:/var/lib/postgresql/data",
-                "-e",
-                "POSTGRES_DB=penpot",
-                "-e",
-                "POSTGRES_USER=penpot",
-                "-e",
-                "POSTGRES_PASSWORD=penpot",
-                "git.tx1138.com/lfg2025/postgres:15",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-valkey",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-valkey",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=192m",
-                "--pids-limit=2048",
-                "--health-cmd=valkey-cli ping || exit 1",
-                "--health-interval=30s",
-                "--health-retries=3",
-                "-e",
-                "VALKEY_EXTRA_FLAGS=--maxmemory 128mb --maxmemory-policy volatile-lfu",
-                "git.tx1138.com/lfg2025/valkey:8.1",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(3)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-backend",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-backend",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=1g",
-                "--pids-limit=4096",
-                "-v",
-                "/var/lib/archipelago/penpot-assets:/opt/data/assets",
-                "-e",
-                &format!("PENPOT_PUBLIC_URI=http://{}:9001", host_ip),
-                "-e",
-                &format!("PENPOT_SECRET_KEY={}", secret),
-                "-e",
-                "PENPOT_DATABASE_URI=postgresql://penpot-postgres/penpot",
-                "-e",
-                "PENPOT_DATABASE_USERNAME=penpot",
-                "-e",
-                "PENPOT_DATABASE_PASSWORD=penpot",
-                "-e",
-                "PENPOT_REDIS_URI=redis://penpot-valkey/0",
-                "-e",
-                "PENPOT_OBJECTS_STORAGE_BACKEND=fs",
-                "-e",
-                "PENPOT_OBJECTS_STORAGE_FS_DIRECTORY=/opt/data/assets",
-                "-e",
-                "PENPOT_FLAGS=disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies",
-                "git.tx1138.com/lfg2025/penpot-backend:2.4",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-exporter",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-exporter",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=2048",
-                "-e",
-                &format!("PENPOT_SECRET_KEY={}", secret),
-                "-e",
-                "PENPOT_PUBLIC_URI=http://penpot-frontend:8080",
-                "-e",
-                "PENPOT_REDIS_URI=redis://penpot-valkey/0",
-                "git.tx1138.com/lfg2025/penpot-exporter:2.4",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-
-        let run = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-frontend",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-frontend",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=2048",
-                "-p",
-                "9001:8080",
-                "-v",
-                "/var/lib/archipelago/penpot-assets:/opt/data/assets",
-                "-e",
-                &format!("PENPOT_PUBLIC_URI=http://{}:9001", host_ip),
-                "-e",
-                "PENPOT_FLAGS=disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies",
-                "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-            ])
-            .output()
-            .await
-            .context("Failed to start penpot-frontend")?;
-
-        if !run.status.success() {
-            let stderr = String::from_utf8_lossy(&run.stderr);
-            return Err(anyhow::anyhow!(
-                "Failed to start Penpot frontend: {}",
-                stderr
-            ));
-        }
-
-        info!("Penpot stack installed and started");
-        Ok(serde_json::json!({
-            "success": true,
-            "package_id": "penpot",
-            "message": "Penpot stack installed and started"
-        }))
-    }
-
    /// Install BTCPay stack (postgres + nbxplorer + btcpay-server).
    pub(super) async fn install_btcpay_stack(&self) -> Result<serde_json::Value> {
        if let Some(adopted) = adopt_stack_if_exists(
@@ -514,6 +376,12 @@ impl RpcHandler {
            return Ok(adopted);
        }

+        if let Some(orchestrated) =
+            install_stack_via_orchestrator(self, "btcpay-server", btcpay_stack_app_ids()).await?
+        {
+            return Ok(orchestrated);
+        }
+
        // Dependency check: Bitcoin must be running
        let deps = super::dependencies::detect_running_deps().await?;
        super::dependencies::check_install_deps("btcpay-server", &deps)?;
@@ -531,9 +399,18 @@ impl RpcHandler {
            &format!("{}/nbxplorer:2.6.0", REGISTRY),
            &format!("{}/btcpayserver:1.13.7", REGISTRY),
        ];
-        for img in &images {
+        self.set_install_phase("btcpay-server", InstallPhase::PullingImage)
+            .await;
+        let n_images = images.len() as u64;
+        for (i, img) in images.iter().enumerate() {
+            self.set_install_progress("btcpay-server", i as u64, n_images)
+                .await;
            pull_image_with_retry(img).await?;
        }
+        self.set_install_progress("btcpay-server", n_images, n_images)
+            .await;
+        self.set_install_phase("btcpay-server", InstallPhase::CreatingContainer)
+            .await;

        // Create data dirs (chown to current user so rootless podman can write)
        let _ = tokio::process::Command::new("sudo")
@@ -688,6 +565,14 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("Failed to start BTCPay Server: {}", stderr));
        }

+        self.set_install_phase("btcpay-server", InstallPhase::WaitingHealthy)
+            .await;
+        self.set_install_phase("btcpay-server", InstallPhase::PostInstall)
+            .await;
+        self.set_install_phase("btcpay-server", InstallPhase::Done)
+            .await;
+        self.clear_install_progress("btcpay-server").await;
+
        install_log("INSTALL OK: btcpay-server stack").await;
        info!("BTCPay stack installed and started");
        Ok(serde_json::json!({
@@ -701,34 +586,52 @@ impl RpcHandler {
    /// Install Mempool stack (mariadb + mempool-api + mempool-web).
    pub(super) async fn install_mempool_stack(&self) -> Result<serde_json::Value> {
        if let Some(adopted) = adopt_stack_if_exists(
-            "archy-mempool-web",
            "mempool",
-            &["archy-mempool-db", "archy-mempool-api", "archy-mempool-web"],
+            "mempool",
+            &[
+                "archy-mempool-db",
+                "mempool-api",
+                "mempool",
+                "archy-mempool-web",
+                "archy-mempool-api",
+            ],
        )
        .await?
        {
            return Ok(adopted);
        }

+        if let Some(orchestrated) =
+            install_stack_via_orchestrator(self, "mempool", mempool_stack_app_ids()).await?
+        {
+            return Ok(orchestrated);
+        }
+
        // Dependency check: Bitcoin + ElectrumX must be running
        let deps = super::dependencies::detect_running_deps().await?;
        super::dependencies::check_install_deps("mempool", &deps)?;
+        let (_, rpc_pass) = crate::bitcoin_rpc::bitcoin_rpc_credentials().await;

        install_log("INSTALL START: mempool (stack: mariadb + mempool-api + mempool-web)").await;

-        let (rpc_user, rpc_pass) = crate::bitcoin_rpc::bitcoin_rpc_credentials().await;
-
        let db_pass = super::config::read_or_generate_secret("mempool-db-password").await;
-        let root_pass = super::config::read_or_generate_secret("mempool-db-root-password").await;
+        let root_pass = super::config::read_or_generate_secret("mysql-root-db-password").await;

        let images = [
            &format!("{}/mariadb:11.4.10", REGISTRY),
            &format!("{}/mempool-backend:v3.0.0", REGISTRY),
            &format!("{}/mempool-frontend:v3.0.0", REGISTRY),
        ];
-        for img in &images {
+        self.set_install_phase("mempool", InstallPhase::PullingImage)
+            .await;
+        let n_images = images.len() as u64;
+        for (i, img) in images.iter().enumerate() {
+            self.set_install_progress("mempool", i as u64, n_images).await;
            pull_image_with_retry(img).await?;
        }
+        self.set_install_progress("mempool", n_images, n_images).await;
+        self.set_install_phase("mempool", InstallPhase::CreatingContainer)
+            .await;

        // Create data dirs (chown to current user so rootless podman can write)
        let _ = tokio::process::Command::new("sudo")
@@ -822,17 +725,17 @@ impl RpcHandler {
                "-e",
                "MEMPOOL_BACKEND=electrum",
                "-e",
-                "ELECTRUM_HOST=host.containers.internal",
+                "ELECTRUM_HOST=electrumx",
                "-e",
                "ELECTRUM_PORT=50001",
                "-e",
                "ELECTRUM_TLS_ENABLED=false",
                "-e",
-                "CORE_RPC_HOST=host.containers.internal",
+                "CORE_RPC_HOST=bitcoin-knots",
                "-e",
                "CORE_RPC_PORT=8332",
                "-e",
-                &format!("CORE_RPC_USERNAME={}", rpc_user),
+                "CORE_RPC_USERNAME=archipelago",
                "-e",
                &format!("CORE_RPC_PASSWORD={}", rpc_pass),
                "-e",
@@ -886,6 +789,13 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("Failed to start Mempool: {}", stderr));
        }

+        self.set_install_phase("mempool", InstallPhase::WaitingHealthy)
+            .await;
+        self.set_install_phase("mempool", InstallPhase::PostInstall)
+            .await;
+        self.set_install_phase("mempool", InstallPhase::Done).await;
+        self.clear_install_progress("mempool").await;
+
        install_log("INSTALL OK: mempool stack").await;
        info!("Mempool stack installed and started");
        Ok(serde_json::json!({
@@ -905,7 +815,7 @@ impl RpcHandler {
            .into_iter()
            .find(|r| r.enabled)
            .map(|r| r.url)
-            .unwrap_or_else(|| "git.tx1138.com/lfg2025".to_string());
+            .unwrap_or_else(|| "146.59.87.168:3000/lfg2025".to_string());

        let user_tmp = format!(
            "{}/.local/share/containers/tmp",
@@ -930,12 +840,53 @@ impl RpcHandler {
        // Pull all images with retry; fail the install if any image can't be pulled.
        // Previously this just logged a warning and continued, leaving the stack
        // broken and the user seeing "failed" with no recovery path.
-        for img in &images {
+        self.set_install_phase("indeedhub", InstallPhase::PullingImage)
+            .await;
+        let n_images = images.len() as u64;
+        for (i, img) in images.iter().enumerate() {
+            // set_install_progress fills the byte-counter fallback the UI uses
+            // when it can't read podman's pull output — gives the bar a clear
+            // X-of-N step as each image lands.
+            self.set_install_progress("indeedhub", i as u64, n_images)
+                .await;
            info!("Pulling {}", img);
            pull_image_with_retry(img)
                .await
                .with_context(|| format!("Failed to pull IndeedHub image: {}", img))?;
        }
+        self.set_install_progress("indeedhub", n_images, n_images)
+            .await;
+
+        // Remove any leftover containers from a previous partial install (or
+        // from the first-boot frontend stub that used to race the installer).
+        // Without this, `podman run --name indeedhub` fails on name conflict
+        // and the whole stack install errors out — leaving a half-broken node.
+        for name in [
+            "indeedhub",
+            "indeedhub-postgres",
+            "indeedhub-redis",
+            "indeedhub-minio",
+            "indeedhub-relay",
+            "indeedhub-api",
+            "indeedhub-ffmpeg",
+            "indeedhub-build_api_1",
+            "indeedhub-build_ffmpeg-worker_1",
+        ] {
+            let _ = tokio::process::Command::new("podman")
+                .args(["rm", "-f", name])
+                .status()
+                .await;
+        }
+        let _ = tokio::process::Command::new("podman")
+            .args(["network", "rm", "-f", "indeedhub-net"])
+            .status()
+            .await;
+
+        // Phase: CreatingContainer — pulls done, network rebuilt, now spinning
+        // up the 7 stack containers. Bar advances from PullingImage band into
+        // CreatingContainer band so the user sees movement.
+        self.set_install_phase("indeedhub", InstallPhase::CreatingContainer)
+            .await;

        // Create indeedhub-net
        let _ = tokio::process::Command::new("podman")
@@ -1063,26 +1014,38 @@ impl RpcHandler {
                "-e",
                "DATABASE_HOST=postgres",
                "-e",
+                "DATABASE_PORT=5432",
+                "-e",
                "DATABASE_USER=indeedhub",
                "-e",
                &format!("DATABASE_PASSWORD={}", db_pass),
                "-e",
                "DATABASE_NAME=indeedhub",
                "-e",
-                "REDIS_HOST=redis",
+                "QUEUE_HOST=redis",
+                "-e",
+                "QUEUE_PORT=6379",
                "-e",
                "S3_ENDPOINT=http://minio:9000",
                "-e",
+                "AWS_REGION=us-east-1",
+                "-e",
                &format!("AWS_ACCESS_KEY={}", minio_user),
                "-e",
                &format!("AWS_SECRET_KEY={}", minio_pass),
                "-e",
                "S3_PUBLIC_BUCKET_NAME=indeedhub-public",
                "-e",
+                "S3_PRIVATE_BUCKET_NAME=indeedhub-private",
+                "-e",
                "S3_PUBLIC_BUCKET_URL=/storage",
                "-e",
                &format!("NOSTR_JWT_SECRET={}", jwt_secret),
                "-e",
+                "NOSTR_JWT_EXPIRES_IN=7d",
+                "-e",
+                "AES_MASTER_SECRET=0123456789abcdef0123456789abcdef",
+                "-e",
                "ENVIRONMENT=production",
                &format!("{}/indeedhub-api:1.0.0", registry),
            ])
@@ -1104,6 +1067,8 @@ impl RpcHandler {
                "-e",
                "DATABASE_HOST=postgres",
                "-e",
+                "DATABASE_PORT=5432",
+                "-e",
                "DATABASE_USER=indeedhub",
                "-e",
                &format!("DATABASE_PASSWORD={}", db_pass),
@@ -1112,6 +1077,8 @@ impl RpcHandler {
                "-e",
                "QUEUE_HOST=redis",
                "-e",
+                "QUEUE_PORT=6379",
+                "-e",
                "S3_ENDPOINT=http://minio:9000",
                "-e",
                &format!("AWS_ACCESS_KEY={}", minio_user),
@@ -1122,6 +1089,8 @@ impl RpcHandler {
                "-e",
                "S3_PUBLIC_BUCKET_NAME=indeedhub-public",
                "-e",
+                "S3_PRIVATE_BUCKET_NAME=indeedhub-private",
+                "-e",
                "ENVIRONMENT=production",
                "-e",
                "AES_MASTER_SECRET=0123456789abcdef0123456789abcdef",
@@ -1159,6 +1128,17 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("IndeedHub frontend failed: {}", err));
        }

+        // Phase: WaitingHealthy → PostInstall → clear. The actual readiness
+        // gate is the package scanner's next sweep; this just gives the UI a
+        // truthful end-of-install signal so the bar settles at 95→100→done
+        // instead of sitting at "Queued… 2%" forever.
+        self.set_install_phase("indeedhub", InstallPhase::WaitingHealthy)
+            .await;
+        self.set_install_phase("indeedhub", InstallPhase::PostInstall)
+            .await;
+        self.set_install_phase("indeedhub", InstallPhase::Done).await;
+        self.clear_install_progress("indeedhub").await;
+
        install_log("INSTALL OK: indeedhub stack").await;
        info!("IndeedHub stack installed");
        Ok(serde_json::json!({
@@ -1168,3 +1148,20 @@ impl RpcHandler {
        }))
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{btcpay_stack_app_ids, mempool_stack_app_ids};
+
+    #[test]
+    fn stack_app_id_sets_match_migration_manifests() {
+        assert_eq!(
+            btcpay_stack_app_ids(),
+            ["archy-btcpay-db", "archy-nbxplorer", "btcpay-server"]
+        );
+        assert_eq!(
+            mempool_stack_app_ids(),
+            ["archy-mempool-db", "mempool-api", "archy-mempool-web"]
+        );
+    }
+}
@@ -1,7 +1,7 @@
 //! Per-app manual update handler.
 //!
 //! Flow: validate → set Updating state → graceful stop → pull new image(s) →
-//! remove old container(s) → recreate via reconcile script → verify running.
+//! remove old container(s) → recreate (orchestrator-first, legacy fallback) → verify running.
 //! Data volumes are preserved (bind mounts, not stored in container).

 use super::config::get_containers_for_app;
@@ -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};
@@ -34,15 +34,10 @@ impl RpcHandler {
        let pinned = image_versions::pinned_image_for_app(package_id)
            .ok_or_else(|| anyhow::anyhow!("No pinned image found for {}", package_id))?;

-        // Reject if already updating
-        {
-            let (data, _) = self.state_manager.get_snapshot().await;
-            if let Some(entry) = data.package_data.get(package_id) {
-                if entry.state == PackageState::Updating {
-                    return Err(anyhow::anyhow!("{} is already updating", package_id));
-                }
-            }
-        }
+        // Note: the `already updating` guard lives in `spawn_package_update`
+        // (the async wrapper that dispatch actually routes to). By the time
+        // this inner function runs, the wrapper has already flipped state to
+        // `Updating`, so duplicating the check here would be a false positive.

        install_log(&format!("UPDATE: {} → {}", package_id, pinned)).await;

@@ -56,6 +51,64 @@ impl RpcHandler {
            self.state_manager.update_data(data).await;
        }

+        // Preferred path: for single-container apps managed by manifests, route
+        // updates through the orchestrator's upgrade lifecycle instead of the
+        // legacy shell/CLI flow. Keep stack-style packages on legacy for now.
+        if should_try_orchestrator_update(package_id, self.orchestrator.is_some()) {
+            let orchestrator_app_id = orchestrator_update_app_id(package_id);
+            self.set_install_phase(package_id, InstallPhase::Preparing)
+                .await;
+            install_log(&format!(
+                "UPDATE ORCH: {} — attempting orchestrator upgrade as {}",
+                package_id, orchestrator_app_id
+            ))
+            .await;
+
+            if let Some(orchestrator) = self.orchestrator.as_ref() {
+                match orchestrator.upgrade(orchestrator_app_id).await {
+                    Ok(()) => {
+                        self.set_install_phase(package_id, InstallPhase::WaitingHealthy)
+                            .await;
+                        if let Ok(health) = orchestrator.health(orchestrator_app_id).await {
+                            if health != "healthy" {
+                                warn!(
+                                    "Update {}: orchestrator upgrade completed with health={} (expected healthy)",
+                                    package_id, health
+                                );
+                            }
+                        }
+                        install_log(&format!(
+                            "UPDATE ORCH OK: {} (app={})",
+                            package_id, orchestrator_app_id
+                        ))
+                        .await;
+                        self.clear_install_progress(package_id).await;
+                        return Ok(serde_json::json!({
+                            "status": "updated",
+                            "package_id": package_id,
+                        }));
+                    }
+                    Err(e) if is_unknown_app_id_error(&e) => {
+                        info!(
+                            "Update {}: orchestrator has no manifest mapping yet, falling back to legacy updater",
+                            package_id
+                        );
+                        install_log(&format!(
+                            "UPDATE ORCH SKIP: {} — unknown app_id, using legacy flow",
+                            package_id
+                        ))
+                        .await;
+                    }
+                    Err(e) => {
+                        install_log(&format!("UPDATE ORCH FAIL: {} — {}", package_id, e)).await;
+                        self.clear_install_progress(package_id).await;
+                        self.clear_update_state(package_id).await;
+                        return Err(e.context(format!("Orchestrator update {} failed", package_id)));
+                    }
+                }
+            }
+        }
+
        // Resolve images to pull — either a stack or single container
        let images_to_pull = self.resolve_images_to_pull(package_id, &pinned);

@@ -101,6 +154,11 @@ 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",
@@ -130,6 +188,10 @@ 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",
@@ -173,38 +235,23 @@ impl RpcHandler {
            }
        }

-        // 4. Recreate via reconcile script (single source of truth for container specs)
-        info!("Update {}: recreating containers via reconcile", package_id);
+        // Phase: CreatingContainer — about to recreate each container.
+        self.set_install_phase(package_id, InstallPhase::CreatingContainer)
+            .await;
+
+        // 4. Recreate containers (orchestrator-first, reconcile fallback)
+        info!("Update {}: recreating containers", package_id);
        for name in containers {
-            let out = tokio::process::Command::new("bash")
-                .args([
-                    "/opt/archipelago/scripts/reconcile-containers.sh",
-                    &format!("--container={}", name),
-                    "--force",
-                ])
-                .output()
-                .await
-                .context(format!("Failed to reconcile {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr);
-                let stdout = String::from_utf8_lossy(&out.stdout);
-                error!(
-                    "Update {}: reconcile {} failed:\nstdout: {}\nstderr: {}",
-                    package_id,
-                    name,
-                    stdout.trim(),
-                    stderr.trim()
-                );
-                return Err(anyhow::anyhow!(
-                    "Reconcile failed for {}: {}",
-                    name,
-                    stderr.trim()
-                ));
-            }
+            self.recreate_container_for_update(package_id, name).await?;
            // Brief delay between containers for dependency initialization
            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 {
@@ -226,6 +273,51 @@ impl RpcHandler {
        Ok(())
    }

+    async fn recreate_container_for_update(
+        &self,
+        package_id: &str,
+        container_name: &str,
+    ) -> Result<()> {
+        let Some(orchestrator) = self.orchestrator.as_ref() else {
+            return Err(anyhow::anyhow!(
+                "Cannot recreate {} during update {}: orchestrator unavailable",
+                container_name,
+                package_id
+            ));
+        };
+
+        let mut attempted = Vec::new();
+        for app_id in candidate_app_ids_for_container(container_name) {
+            attempted.push(app_id.clone());
+            match orchestrator.install(&app_id).await {
+                Ok(created_name) => {
+                    install_log(&format!(
+                        "UPDATE ORCH RECREATE OK: {} — container={} app_id={} created={}",
+                        package_id, container_name, app_id, created_name
+                    ))
+                    .await;
+                    return Ok(());
+                }
+                Err(e) if is_unknown_app_id_error(&e) => {
+                    continue;
+                }
+                Err(e) => {
+                    return Err(e.context(format!(
+                        "orchestrator recreate failed for update {} (container={}, app_id={})",
+                        package_id, container_name, app_id
+                    )));
+                }
+            }
+        }
+
+        Err(anyhow::anyhow!(
+            "No manifest mapping found while recreating {} during update {} (attempted app_ids: {})",
+            container_name,
+            package_id,
+            attempted.join(", ")
+        ))
+    }
+
    /// Pull a single image with progress broadcasting (reuses install progress pattern).
    async fn pull_update_image(&self, package_id: &str, image: &str) -> Result<()> {
        self.set_install_progress(package_id, 0, 0).await;
@@ -296,15 +388,16 @@ impl RpcHandler {
                Ok(o) => {
                    let stderr = String::from_utf8_lossy(&o.stderr);
                    warn!("Rollback: could not restart {}: {}", name, stderr.trim());
-                    // Container was already removed — try reconcile to recreate with old image
-                    let _ = tokio::process::Command::new("bash")
-                        .args([
-                            "/opt/archipelago/scripts/reconcile-containers.sh",
-                            &format!("--container={}", name),
-                            "--force",
-                        ])
-                        .output()
-                        .await;
+                    // Container was already removed (forward path ran `podman rm`).
+                    // Recreate via orchestrator-first path with legacy fallback.
+                    if let Err(recreate_err) =
+                        self.recreate_container_for_update(package_id, name).await
+                    {
+                        error!(
+                            "Rollback: failed to recreate {} during rollback of {}: {}",
+                            name, package_id, recreate_err
+                        );
+                    }
                }
                Err(e) => {
                    error!("Rollback: failed to restart {}: {}", name, e);
@@ -325,3 +418,129 @@ impl RpcHandler {
        self.state_manager.update_data(data).await;
    }
 }
+
+fn should_try_orchestrator_update(package_id: &str, orchestrator_available: bool) -> bool {
+    orchestrator_available && !uses_legacy_update_flow(package_id)
+}
+
+fn orchestrator_update_app_id(package_id: &str) -> &str {
+    match package_id {
+        "bitcoin-knots" => "bitcoin-core",
+        "electrs" | "mempool-electrs" => "electrumx",
+        _ => package_id,
+    }
+}
+
+fn uses_legacy_update_flow(package_id: &str) -> bool {
+    matches!(
+        package_id,
+        // Multi-container stacks still updated via the stack-aware path.
+        "immich" | "penpot" | "penpot-frontend" | "indeedhub"
+    )
+}
+
+fn is_unknown_app_id_error(err: &anyhow::Error) -> bool {
+    err.chain()
+        .any(|cause| cause.to_string().contains("unknown app_id"))
+}
+
+fn candidate_app_ids_for_container(container_name: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut push = |s: &str| {
+        if !out.iter().any(|e: &String| e == s) {
+            out.push(s.to_string());
+        }
+    };
+
+    match container_name {
+        "bitcoin-knots" | "bitcoin-core" => {
+            push("bitcoin-core");
+            push("bitcoin-knots");
+        }
+        "archy-bitcoin-ui" => push("bitcoin-ui"),
+        "archy-lnd-ui" => push("lnd-ui"),
+        "archy-electrs-ui" => push("electrs-ui"),
+        "mempool" => {
+            push("archy-mempool-web");
+            push("mempool");
+        }
+        _ => {}
+    }
+
+    push(container_name);
+    if let Some(stripped) = container_name.strip_prefix("archy-") {
+        push(stripped);
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        candidate_app_ids_for_container, orchestrator_update_app_id,
+        should_try_orchestrator_update, uses_legacy_update_flow,
+    };
+
+    #[test]
+    fn legacy_flow_for_stack_apps() {
+        for app in ["immich", "penpot", "indeedhub"] {
+            assert!(uses_legacy_update_flow(app), "{app} should stay legacy");
+        }
+    }
+
+    #[test]
+    fn orchestrator_flow_for_single_apps() {
+        for app in [
+            "lnd",
+            "bitcoin-core",
+            "searxng",
+            "grafana",
+            "btcpay-server",
+            "mempool",
+            "fedimint",
+        ] {
+            assert!(
+                !uses_legacy_update_flow(app),
+                "{app} should be orchestrator-first"
+            );
+            assert!(
+                should_try_orchestrator_update(app, true),
+                "{app} should use orchestrator when available"
+            );
+        }
+    }
+
+    #[test]
+    fn no_orchestrator_means_no_orchestrator_flow() {
+        assert!(!should_try_orchestrator_update("lnd", false));
+        assert!(!should_try_orchestrator_update("btcpay-server", false));
+    }
+
+    #[test]
+    fn container_name_candidates_cover_common_aliases() {
+        assert_eq!(
+            candidate_app_ids_for_container("bitcoin-knots"),
+            vec!["bitcoin-core", "bitcoin-knots"]
+        );
+        assert_eq!(
+            candidate_app_ids_for_container("archy-bitcoin-ui"),
+            vec!["bitcoin-ui", "archy-bitcoin-ui"]
+        );
+        assert_eq!(
+            candidate_app_ids_for_container("mempool"),
+            vec!["archy-mempool-web", "mempool"]
+        );
+        assert_eq!(
+            candidate_app_ids_for_container("archy-mempool-db"),
+            vec!["archy-mempool-db", "mempool-db"]
+        );
+    }
+
+    #[test]
+    fn update_aliases_map_to_manifest_app_ids() {
+        assert_eq!(orchestrator_update_app_id("bitcoin-knots"), "bitcoin-core");
+        assert_eq!(orchestrator_update_app_id("electrs"), "electrumx");
+        assert_eq!(orchestrator_update_app_id("mempool-electrs"), "electrumx");
+        assert_eq!(orchestrator_update_app_id("fedimint"), "fedimint");
+    }
+}
@@ -147,8 +147,7 @@ impl RpcHandler {
            .get("onion")
            .and_then(|v| v.as_str())
            .ok_or_else(|| anyhow::anyhow!("Missing onion"))?;
-        let fips_npub =
-            crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
        let reachable = node_message::check_peer_reachable(onion, fips_npub.as_deref())
            .await
            .unwrap_or(false);
@@ -0,0 +1,172 @@
+//! Async lifecycle helper for container Stop/Start/Restart RPCs.
+//!
+//! The `ContainerOrchestrator` trait is intentionally synchronous — blocking
+//! calls keep the reconciler, boot flow, chaos harness, and unit tests
+//! deterministic. But the RPC layer must return to the UI in <1s so the
+//! dashboard can render a transitional "Stopping…" / "Starting…" label while
+//! the underlying `podman stop` (up to 600s for bitcoin-core) runs in the
+//! background.
+//!
+//! `RpcHandler::spawn_transitional` bridges the two: it
+//!   1. flips the package state in `StateManager` to the appropriate
+//!      transitional variant (`Stopping` / `Starting` / `Restarting`),
+//!      which fans out to WebSocket clients immediately.
+//!   2. `tokio::spawn`s the actual orchestrator call.
+//!   3. on success, writes the final state (`Stopped` / `Running`).
+//!   4. on error, reverts to the pre-transition state and logs via
+//!      `install_log()` so the incident shows up in
+//!      `/var/log/archipelago/container-installs.log`.
+//!
+//! The server.rs package-scan loop must also be taught to preserve
+//! transitional states — see `server.rs:scan_and_update_packages`'s merge
+//! logic and the companion `merge_preserving_transitional` helper.
+
+use super::package::install_log;
+use super::RpcHandler;
+use crate::container::ContainerOrchestrator;
+use crate::data_model::PackageState;
+use crate::state::StateManager;
+use anyhow::Result;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+/// The three transitional lifecycle operations that run asynchronously from
+/// the RPC handler. `Install` and `Remove` are intentionally NOT here — they
+/// already have their own progress-tracking paths (`install_progress`,
+/// `uninstall_stage`) with multi-step UI feedback.
+#[derive(Debug, Clone, Copy)]
+pub(super) enum Op {
+    Stop,
+    Start,
+    Restart,
+}
+
+impl Op {
+    /// The `PackageState` to set on the entry while the operation is in
+    /// flight. The package-scan merge loop must preserve this variant and
+    /// refuse to overwrite it with whatever podman reports (see
+    /// `merge_preserving_transitional` in server.rs).
+    fn transitional_state(self) -> PackageState {
+        match self {
+            Op::Stop => PackageState::Stopping,
+            Op::Start => PackageState::Starting,
+            Op::Restart => PackageState::Restarting,
+        }
+    }
+
+    /// The `PackageState` to set on success. On error the caller reverts to
+    /// the pre-transition state rather than using these.
+    fn final_state_on_success(self) -> PackageState {
+        match self {
+            Op::Stop => PackageState::Stopped,
+            Op::Start => PackageState::Running,
+            Op::Restart => PackageState::Running,
+        }
+    }
+
+    /// Prefix used in `install_log` entries so post-mortem readers can grep
+    /// the operation that failed.
+    fn log_prefix(self) -> &'static str {
+        match self {
+            Op::Stop => "STOP",
+            Op::Start => "START",
+            Op::Restart => "RESTART",
+        }
+    }
+
+    /// Call the orchestrator for this op. Kept in one place so the spawned
+    /// task doesn't repeat the match four times.
+    async fn dispatch(self, orch: &dyn ContainerOrchestrator, app_id: &str) -> Result<()> {
+        match self {
+            Op::Stop => orch.stop(app_id).await,
+            Op::Start => orch.start(app_id).await,
+            Op::Restart => orch.restart(app_id).await,
+        }
+    }
+}
+
+impl RpcHandler {
+    /// Flip the package state to `op.transitional_state()`, spawn a background
+    /// task that runs `op.dispatch()`, and return immediately. The spawned
+    /// task writes the final state on completion or reverts to the
+    /// pre-transition state on failure.
+    ///
+    /// If no package entry exists for `app_id` (e.g. Start on a container
+    /// that was never installed), no pre-state is recorded and the spawn
+    /// still runs — the post-success path will no-op the state write and
+    /// the next scan will pick up the newly-created entry with the correct
+    /// state. This keeps the helper usable for stacks that lazily create
+    /// their entries.
+    pub(super) async fn spawn_transitional(&self, op: Op, app_id: String) -> Result<()> {
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?
+            .clone();
+        let state_manager = Arc::clone(&self.state_manager);
+
+        // Snapshot pre-transition state (for revert on error) and flip to
+        // transitional variant. Done BEFORE the spawn so the WebSocket push
+        // beats the RPC response — the UI should see "Stopping…" the moment
+        // it gets the RPC ok, not on the next scan.
+        let pre_state =
+            flip_to_transitional(&state_manager, &app_id, op.transitional_state()).await;
+
+        let log_prefix = op.log_prefix();
+        let app_id_log = app_id.clone();
+        install_log(&format!("{}: {}", log_prefix, app_id_log)).await;
+
+        tokio::spawn(async move {
+            match op.dispatch(orchestrator.as_ref(), &app_id).await {
+                Ok(()) => {
+                    info!("{} complete: {}", log_prefix, app_id);
+                    set_state(&state_manager, &app_id, op.final_state_on_success()).await;
+                }
+                Err(e) => {
+                    error!("{} failed for {}: {:#}", log_prefix, app_id, e);
+                    install_log(&format!("{} FAIL: {} — {:#}", log_prefix, app_id, e)).await;
+                    // Revert to pre-transition state if we had one; otherwise
+                    // leave the entry untouched so the next scan reconciles.
+                    if let Some(prev) = pre_state {
+                        set_state(&state_manager, &app_id, prev).await;
+                    } else {
+                        warn!(
+                            "{}: no pre-transition state recorded for {}; leaving entry to next scan",
+                            log_prefix, app_id
+                        );
+                    }
+                }
+            }
+        });
+
+        Ok(())
+    }
+}
+
+/// Flip the entry's state to `transitional` and return the previous state.
+/// Returns `None` if there is no entry for `app_id`.
+async fn flip_to_transitional(
+    state_manager: &StateManager,
+    app_id: &str,
+    transitional: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(app_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(app_id) {
+        entry.state = transitional;
+        state_manager.update_data(data).await;
+    }
+    prev
+}
+
+/// Set the entry's state to `new_state`. No-ops if the entry has since been
+/// removed (e.g. uninstall ran concurrently).
+async fn set_state(state_manager: &StateManager, app_id: &str, new_state: PackageState) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(app_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
@@ -40,6 +40,7 @@ impl RpcHandler {
            "last_check": state.last_check,
            "update_available": update_info.is_some(),
            "update": update_info,
+            "manifest_mirror": state.manifest_mirror,
        }))
    }

@@ -157,6 +158,34 @@ impl RpcHandler {
    /// Get update status without checking remote.
    pub(super) async fn handle_update_status(&self) -> Result<serde_json::Value> {
        let state = update::get_status(&self.config.data_dir).await?;
+        // Expose live download progress so the UI can resume the
+        // progress bar after navigation instead of showing the fake
+        // creep again. An RPC poll every ~1s during download drives a
+        // real progress indicator that survives route changes.
+        let downloaded = update::DOWNLOAD_BYTES.load(std::sync::atomic::Ordering::Relaxed);
+        let total = update::DOWNLOAD_TOTAL.load(std::sync::atomic::Ordering::Relaxed);
+        let active = total > 0 && downloaded < total;
+        let completed = total > 0 && downloaded >= total;
+
+        // Stall detection: if the progress-at timestamp hasn't advanced
+        // for 30+ seconds while active, the download is wedged (usually
+        // HTTP stream silently dropped and reqwest is waiting out its
+        // read timeout). The UI uses this to surface a Cancel button
+        // with explanatory copy.
+        let stalled = if active {
+            let last_at = update::DOWNLOAD_PROGRESS_AT.load(std::sync::atomic::Ordering::Relaxed);
+            if last_at > 0 {
+                let now = std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .map(|d| d.as_millis() as u64)
+                    .unwrap_or(0);
+                now.saturating_sub(last_at) > 30_000
+            } else {
+                false
+            }
+        } else {
+            false
+        };

        Ok(serde_json::json!({
            "current_version": state.current_version,
@@ -164,6 +193,15 @@ impl RpcHandler {
            "update_available": state.available_update.is_some(),
            "update_in_progress": state.update_in_progress,
            "rollback_available": state.rollback_available,
+            "manifest_mirror": state.manifest_mirror,
+            "download_progress": if active || completed {
+                Some(serde_json::json!({
+                    "bytes_downloaded": downloaded,
+                    "total_bytes": total,
+                    "active": active,
+                    "stalled": stalled,
+                }))
+            } else { None },
        }))
    }

@@ -183,6 +221,13 @@ impl RpcHandler {
        }))
    }

+    /// Cancel an in-flight or stuck download. Clears the live counters
+    /// and staging dir so the UI returns to the "Download Update" state.
+    pub(super) async fn handle_update_cancel_download(&self) -> Result<serde_json::Value> {
+        update::cancel_download(&self.config.data_dir).await?;
+        Ok(serde_json::json!({ "canceled": true }))
+    }
+
    /// Apply the staged update.
    pub(super) async fn handle_update_apply(&self) -> Result<serde_json::Value> {
        update::apply_update(&self.config.data_dir).await?;
@@ -195,6 +240,89 @@ impl RpcHandler {
        Ok(serde_json::json!({ "rolled_back": true, "restart_required": true }))
    }

+    /// List configured update mirrors in priority order.
+    pub(super) async fn handle_update_list_mirrors(&self) -> Result<serde_json::Value> {
+        let list = update::load_mirrors(&self.config.data_dir).await?;
+        Ok(serde_json::json!({ "mirrors": list }))
+    }
+
+    /// Add a mirror to the end of the list. Params: `{ url, label? }`.
+    /// Duplicates (same URL) are replaced rather than added twice.
+    pub(super) async fn handle_update_add_mirror(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let url = params
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("missing url"))?
+            .trim()
+            .to_string();
+        if !url.starts_with("http://") && !url.starts_with("https://") {
+            anyhow::bail!("url must start with http:// or https://");
+        }
+        let label = params
+            .get("label")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .trim()
+            .to_string();
+        let mut list = update::load_mirrors(&self.config.data_dir).await?;
+        list.retain(|m| m.url != url);
+        list.push(update::UpdateMirror { url, label });
+        update::save_mirrors(&self.config.data_dir, &list).await?;
+        Ok(serde_json::json!({ "mirrors": list }))
+    }
+
+    /// Remove a mirror by URL. Params: `{ url }`.
+    pub(super) async fn handle_update_remove_mirror(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let url = params
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("missing url"))?;
+        let mut list = update::load_mirrors(&self.config.data_dir).await?;
+        list.retain(|m| m.url != url);
+        update::save_mirrors(&self.config.data_dir, &list).await?;
+        Ok(serde_json::json!({ "mirrors": list }))
+    }
+
+    /// Ping a mirror's manifest URL. Returns reachability, wall-clock
+    /// latency, and HTTP status. Params: `{ url }`.
+    pub(super) async fn handle_update_test_mirror(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let url = params
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("missing url"))?;
+        let result = update::test_mirror(url).await;
+        Ok(serde_json::to_value(result)?)
+    }
+
+    /// Move a mirror to the top of the list so it's tried first.
+    /// Params: `{ url }`.
+    pub(super) async fn handle_update_set_primary_mirror(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let url = params
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("missing url"))?;
+        let mut list = update::load_mirrors(&self.config.data_dir).await?;
+        let Some(idx) = list.iter().position(|m| m.url == url) else {
+            anyhow::bail!("mirror not in list");
+        };
+        let entry = list.remove(idx);
+        list.insert(0, entry);
+        update::save_mirrors(&self.config.data_dir, &list).await?;
+        Ok(serde_json::json!({ "mirrors": list }))
+    }
+
    /// Get the current update schedule.
    pub(super) async fn handle_update_get_schedule(&self) -> Result<serde_json::Value> {
        let schedule = update::get_schedule(&self.config.data_dir).await?;
@@ -185,12 +185,32 @@ impl AuthManager {
                }
            }
        }
-        // Fallback: user.json
-        Ok(self
-            .get_user()
-            .await?
-            .map(|u| u.onboarding_complete)
-            .unwrap_or(false))
+        // Fallback: user.json. A node that has a password set AND
+        // setup_complete=true has been through onboarding by
+        // definition — you can't reach the password-set step any
+        // other way. The separate `onboarding_complete` flag can drift
+        // out of sync (e.g. the completion RPC never reached disk, or
+        // the node was seeded from a backup pre-dating the flag), so
+        // auto-heal by inferring from setup_complete + password_hash.
+        // Without this, a fully-onboarded node whose `onboarding_complete`
+        // is stuck false will force its user back through the intro
+        // wizard on every cleared browser cache.
+        if let Some(u) = self.get_user().await? {
+            if u.onboarding_complete {
+                return Ok(true);
+            }
+            if u.setup_complete && !u.password_hash.is_empty() {
+                // Persist the healed state so subsequent calls skip this
+                // inference. Ignore write errors — returning true is
+                // still correct even if we can't persist.
+                let healed = OnboardingState { complete: true };
+                if let Ok(json) = serde_json::to_string_pretty(&healed) {
+                    let _ = fs::write(&onboarding_file, json).await;
+                }
+                return Ok(true);
+            }
+        }
+        Ok(false)
    }

    /// Check if 2FA is enabled for the user.
@@ -18,12 +18,12 @@ use base64::Engine;
 /// Convert a byte to an HSL triple biased toward readable foregrounds on
 /// dark backgrounds (saturation 60–85%, lightness 52–70%).
 fn hue_color(seed: u8) -> String {
-    let hue = (seed as u16) * 360 / 256;
+    let hue = (seed as u32) * 360 / 256;
    format!("hsl({}, 72%, 60%)", hue)
 }

 fn accent_color(seed: u8) -> String {
-    let hue = (seed as u16) * 360 / 256;
+    let hue = (seed as u32) * 360 / 256;
    format!("hsl({}, 80%, 68%)", hue)
 }

@@ -37,7 +37,10 @@ fn encode_svg(svg: &str) -> String {
 /// avatar rather than an error.
 fn seed_bytes(pubkey_hex: &str) -> [u8; 8] {
    let mut out = [0u8; 8];
-    let clean: String = pubkey_hex.chars().filter(|c| c.is_ascii_hexdigit()).collect();
+    let clean: String = pubkey_hex
+        .chars()
+        .filter(|c| c.is_ascii_hexdigit())
+        .collect();
    for (i, byte) in out.iter_mut().enumerate() {
        let lo = i * 2;
        if clean.len() >= lo + 2 {
@@ -0,0 +1,260 @@
+//! Bootstrap host-side artifacts on every archipelago startup.
+//!
+//! The update pipeline swaps the archipelago binary but does not touch
+//! scripts, systemd units, or nginx configuration — those are installed
+//! once by the ISO builder. Without this module, changes to
+//! `container-doctor.sh`, the doctor service/timer, or the nginx config
+//! never reach boxes installed before the change.
+//!
+//! Two things are synced on startup:
+//!   1. Doctor artifacts (container-doctor.sh + service + timer).
+//!   2. An nginx `location /api/app-catalog` proxy block — required for
+//!      the App Store catalog proxy to actually reach the backend.
+//!
+//! Idempotent: no-ops on boxes that are already in sync. All work is
+//! best-effort — failures are logged but never abort the backend.
+
+use anyhow::{Context, Result};
+use std::path::Path;
+use tokio::fs;
+use tracing::{debug, info, warn};
+
+use crate::update::host_sudo;
+
+const DOCTOR_SH: &str = include_str!("../../../scripts/container-doctor.sh");
+const DOCTOR_SERVICE: &str =
+    include_str!("../../../image-recipe/configs/archipelago-doctor.service");
+const DOCTOR_TIMER: &str = include_str!("../../../image-recipe/configs/archipelago-doctor.timer");
+
+const DOCTOR_SH_PATH: &str = "/home/archipelago/archy/scripts/container-doctor.sh";
+const DOCTOR_SERVICE_PATH: &str = "/etc/systemd/system/archipelago-doctor.service";
+const DOCTOR_TIMER_PATH: &str = "/etc/systemd/system/archipelago-doctor.timer";
+
+const NGINX_CONF_PATH: &str = "/etc/nginx/sites-available/archipelago";
+
+/// Inserted into every server block of the nginx config that lacks the
+/// `/api/app-catalog` proxy. Kept in sync with the canonical block in
+/// image-recipe/configs/nginx-archipelago.conf.
+const NGINX_APP_CATALOG_BLOCK: &str = "\n    # App Store catalog proxy — backend fetches from configured registries\n    # so the browser doesn't hit CORS/CSP. Without this block nginx falls\n    # through to the SPA index.html and the frontend gets HTML back instead\n    # of JSON.\n    location /api/app-catalog {\n        proxy_pass http://127.0.0.1:5678;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header Cookie $http_cookie;\n        proxy_connect_timeout 15s;\n        proxy_read_timeout 30s;\n        proxy_send_timeout 15s;\n        error_page 502 503 = @backend_unavailable;\n        error_page 504 = @backend_timeout;\n    }\n\n";
+
+/// Entry point called from main startup. Never returns an error to the caller —
+/// failing to bootstrap host artifacts must not prevent the backend from serving.
+pub async fn ensure_doctor_installed() {
+    match run().await {
+        Ok(changed) if changed => info!("Doctor artifacts synchronized with binary"),
+        Ok(_) => debug!("Doctor artifacts already in sync"),
+        Err(e) => warn!("Doctor bootstrap failed (non-fatal): {:#}", e),
+    }
+    match run_nginx().await {
+        Ok(true) => info!("Patched nginx config to proxy /api/app-catalog"),
+        Ok(false) => debug!("Nginx already has /api/app-catalog block"),
+        Err(e) => warn!("Nginx bootstrap failed (non-fatal): {:#}", e),
+    }
+}
+
+async fn run() -> Result<bool> {
+    // Dev-box guard: on contributors' laptops `/home/archipelago/archy` is
+    // typically a symlink into the git checkout, and writing through it
+    // would clobber the working tree with whatever the binary happens to
+    // have been compiled from. Production ISO installs materialize a real
+    // directory.
+    let home_archy = Path::new("/home/archipelago/archy");
+    if fs::symlink_metadata(home_archy)
+        .await
+        .map(|m| m.file_type().is_symlink())
+        .unwrap_or(false)
+    {
+        debug!("/home/archipelago/archy is a symlink — skipping doctor bootstrap (dev box)");
+        return Ok(false);
+    }
+
+    // Skip entirely on machines without the canonical scripts directory —
+    // writing orphan files there just causes confusion.
+    let scripts_dir = Path::new(DOCTOR_SH_PATH)
+        .parent()
+        .context("doctor script path has no parent")?;
+    if !scripts_dir.exists() {
+        debug!(
+            "Scripts dir {} missing — skipping doctor bootstrap",
+            scripts_dir.display()
+        );
+        return Ok(false);
+    }
+
+    let mut changed = false;
+
+    // 1. Script — lives in archipelago's home dir, user-writable.
+    if needs_write(DOCTOR_SH_PATH, DOCTOR_SH).await {
+        fs::write(DOCTOR_SH_PATH, DOCTOR_SH)
+            .await
+            .with_context(|| format!("write {}", DOCTOR_SH_PATH))?;
+        let _ = tokio::process::Command::new("chmod")
+            .args(["+x", DOCTOR_SH_PATH])
+            .status()
+            .await;
+        info!("Updated {}", DOCTOR_SH_PATH);
+        changed = true;
+    }
+
+    // 2. Systemd unit files — /etc is restricted; route through host_sudo.
+    let service_changed = write_root_if_needed(DOCTOR_SERVICE_PATH, DOCTOR_SERVICE).await?;
+    let timer_changed = write_root_if_needed(DOCTOR_TIMER_PATH, DOCTOR_TIMER).await?;
+    changed = changed || service_changed || timer_changed;
+
+    // 3. Reload + enable. Only when we actually touched units, or when the
+    // timer isn't enabled yet (catches fresh upgrades of boxes that predate
+    // the doctor entirely).
+    let timer_enabled = is_timer_enabled().await;
+    if service_changed || timer_changed || !timer_enabled {
+        if let Err(e) = host_sudo(&["systemctl", "daemon-reload"]).await {
+            warn!("daemon-reload failed: {:#}", e);
+        }
+        if let Err(e) =
+            host_sudo(&["systemctl", "enable", "--now", "archipelago-doctor.timer"]).await
+        {
+            warn!("enable archipelago-doctor.timer failed: {:#}", e);
+        } else if !timer_enabled {
+            info!("Enabled archipelago-doctor.timer");
+        }
+    }
+
+    Ok(changed)
+}
+
+async fn needs_write(path: &str, expected: &str) -> bool {
+    match fs::read_to_string(path).await {
+        Ok(current) => current != expected,
+        Err(_) => true,
+    }
+}
+
+/// Write content to a root-owned path via `sudo mv` of a user-owned tmp file.
+/// Returns true if a write happened.
+async fn write_root_if_needed(path: &str, content: &str) -> Result<bool> {
+    if !needs_write(path, content).await {
+        return Ok(false);
+    }
+    let tmp = format!(
+        "/tmp/archipelago-bootstrap-{}-{}.tmp",
+        std::process::id(),
+        Path::new(path)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("unit")
+    );
+    fs::write(&tmp, content)
+        .await
+        .with_context(|| format!("write tmp {}", tmp))?;
+    let status = host_sudo(&["mv", &tmp, path])
+        .await
+        .with_context(|| format!("sudo mv {} -> {}", tmp, path))?;
+    if !status.success() {
+        let _ = fs::remove_file(&tmp).await;
+        anyhow::bail!("sudo mv to {} exited with {}", path, status);
+    }
+    info!("Updated {}", path);
+    Ok(true)
+}
+
+async fn is_timer_enabled() -> bool {
+    tokio::process::Command::new("systemctl")
+        .args(["is-enabled", "--quiet", "archipelago-doctor.timer"])
+        .status()
+        .await
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+/// Patch the nginx site config to add a `/api/app-catalog` proxy block if
+/// it's missing. The original ISO shipped individual per-endpoint `location`
+/// blocks and no catch-all `/api/`, so `/api/app-catalog` silently fell
+/// through to the SPA `index.html` and the frontend got HTML instead of
+/// JSON. We anchor the insert to the DWN comment that already sits right
+/// after the `/api/blob` block, so the new block lands in both the HTTP
+/// and HTTPS server blocks.
+///
+/// Validates via `nginx -t` before reloading. On failure the patch is
+/// rolled back from a backup written just before the write.
+async fn run_nginx() -> Result<bool> {
+    // Skip on dev symlinks — we don't want to touch `/etc/nginx` on laptops.
+    let home_archy = Path::new("/home/archipelago/archy");
+    if fs::symlink_metadata(home_archy)
+        .await
+        .map(|m| m.file_type().is_symlink())
+        .unwrap_or(false)
+    {
+        return Ok(false);
+    }
+
+    if !Path::new(NGINX_CONF_PATH).exists() {
+        debug!("{} missing — skipping nginx bootstrap", NGINX_CONF_PATH);
+        return Ok(false);
+    }
+
+    let content = fs::read_to_string(NGINX_CONF_PATH)
+        .await
+        .with_context(|| format!("read {}", NGINX_CONF_PATH))?;
+    if content.contains("location /api/app-catalog") {
+        return Ok(false);
+    }
+
+    // The DWN comment sits at the same indent right after the `/api/blob`
+    // block in both server blocks — a stable anchor that existed on every
+    // ISO shipped to date. If it's absent (config got heavily customized),
+    // we bail rather than guess where to splice.
+    let anchor = "    # DWN endpoints — peer access over Tor (no auth)";
+    if !content.contains(anchor) {
+        warn!("nginx conf missing DWN anchor — skipping /api/app-catalog patch");
+        return Ok(false);
+    }
+
+    let replacement = format!("{}{}", NGINX_APP_CATALOG_BLOCK, anchor);
+    let patched = content.replace(anchor, &replacement);
+
+    // Write patched config via a user-owned tmp + sudo mv, after stashing
+    // a backup so we can revert if `nginx -t` hates what we produced.
+    let pid = std::process::id();
+    let tmp = format!("/tmp/archipelago-nginx-{}.conf", pid);
+    fs::write(&tmp, &patched)
+        .await
+        .with_context(|| format!("write {}", tmp))?;
+
+    let backup = format!("/tmp/archipelago-nginx-backup-{}.conf", pid);
+    if let Err(e) = host_sudo(&["cp", NGINX_CONF_PATH, &backup]).await {
+        let _ = fs::remove_file(&tmp).await;
+        return Err(e.context("backup nginx conf"));
+    }
+
+    let mv = host_sudo(&["mv", &tmp, NGINX_CONF_PATH]).await;
+    match mv {
+        Ok(s) if s.success() => {}
+        Ok(s) => {
+            let _ = fs::remove_file(&tmp).await;
+            anyhow::bail!("sudo mv nginx conf exited with {}", s);
+        }
+        Err(e) => {
+            let _ = fs::remove_file(&tmp).await;
+            return Err(e.context("mv tmp -> nginx conf"));
+        }
+    }
+
+    // Validate.
+    let test = host_sudo(&["nginx", "-t"]).await;
+    let valid = matches!(&test, Ok(s) if s.success());
+    if !valid {
+        warn!("nginx -t failed after patch — reverting");
+        let _ = host_sudo(&["mv", &backup, NGINX_CONF_PATH]).await;
+        if let Err(e) = test {
+            return Err(e.context("nginx -t"));
+        }
+        anyhow::bail!("nginx config invalid after patch — reverted");
+    }
+
+    // Reload nginx so the new block takes effect immediately. Reload (not
+    // restart) keeps in-flight connections alive.
+    if let Err(e) = host_sudo(&["systemctl", "reload", "nginx"]).await {
+        warn!("nginx reload failed (non-fatal): {:#}", e);
+    }
+    let _ = host_sudo(&["rm", "-f", &backup]).await;
+    Ok(true)
+}
@@ -0,0 +1,298 @@
+//! bitcoin-ui nginx.conf renderer.
+//!
+//! Step 7 of the rust-orchestrator migration. Replaces the old
+//! `sed -i __BITCOIN_RPC_AUTH__` approach from `first-boot-containers.sh`
+//! (which destructively overwrote its own template, broke on rotation,
+//! and had no story for dual Knots/Core UIs) with a binary-embedded
+//! template rendered at install/reconcile time and atomic-written to
+//! disk.
+//!
+//! The manifest bind-mounts the rendered file read-only into the
+//! container at `/etc/nginx/conf.d/default.conf`. On every reconcile
+//! pass we re-render and compare — if the rendered bytes would differ
+//! from what's on disk (password rotated, template changed via OTA),
+//! we rewrite atomically and the reconciler restarts the container.
+//!
+//! Source of truth:
+//!   * RPC user: hardcoded `archipelago` (matches the image's `bitcoin.conf`).
+//!   * RPC password: `/var/lib/archipelago/secrets/bitcoin-rpc-password`,
+//!     plaintext, written by the seed-derived credential setup.
+//!
+//! Both Knots and Core back-ends expose RPC on 127.0.0.1:8332 with the
+//! same auth shape, so one template serves both.
+
+use anyhow::{Context, Result};
+use base64::Engine;
+use sha2::{Digest, Sha256};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+use tokio::fs;
+
+/// The nginx.conf template. Embedded at compile time so it can never
+/// drift from the code that renders it, and ships atomically with OTA.
+///
+/// `{{BITCOIN_RPC_AUTH}}` is the only placeholder — replaced with a
+/// `base64(user:password)` blob at render time.
+pub(crate) const TEMPLATE: &str = include_str!("bitcoin_ui_nginx.conf.template");
+
+/// The single placeholder in `TEMPLATE`.
+const PLACEHOLDER: &str = "{{BITCOIN_RPC_AUTH}}";
+
+/// Hardcoded RPC user. Matches the user written into `bitcoin.conf` by
+/// the bitcoin-core/bitcoin-knots bootstrap, and the legacy
+/// `BITCOIN_RPC_USER="archipelago"` from `first-boot-containers.sh`.
+const RPC_USER: &str = "archipelago";
+
+/// Default path to the plaintext RPC password secret.
+///
+/// Written by the seed-derived credential flow; same file the bash
+/// scripts read today at `first-boot-containers.sh:277` and `:1225`.
+pub const DEFAULT_SECRET_PATH: &str = "/var/lib/archipelago/secrets/bitcoin-rpc-password";
+
+/// Default output path for the rendered nginx.conf.
+///
+/// The manifest bind-mounts this file read-only into the bitcoin-ui
+/// container at `/etc/nginx/conf.d/default.conf`.
+pub const DEFAULT_RENDERED_PATH: &str = "/var/lib/archipelago/bitcoin-ui/nginx.conf";
+
+/// Parameters for rendering. Injectable so tests can hit a tmpdir
+/// instead of `/var/lib/archipelago`.
+#[derive(Debug, Clone)]
+pub struct RenderPaths {
+    /// Path to read the plaintext RPC password from.
+    pub secret_path: PathBuf,
+    /// Path to write the rendered nginx.conf to.
+    pub rendered_path: PathBuf,
+}
+
+impl Default for RenderPaths {
+    fn default() -> Self {
+        Self {
+            secret_path: PathBuf::from(DEFAULT_SECRET_PATH),
+            rendered_path: PathBuf::from(DEFAULT_RENDERED_PATH),
+        }
+    }
+}
+
+/// Outcome of a render pass. `Written` if the rendered bytes differed
+/// from the current on-disk contents and we rewrote; `Unchanged` if
+/// they matched and we left the file alone.
+///
+/// The caller (reconciler / install path) decides whether to restart
+/// the bitcoin-ui container based on this.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RenderOutcome {
+    Written,
+    Unchanged,
+}
+
+/// Render the bitcoin-ui nginx.conf and atomic-write it to disk if it
+/// differs from what's already there.
+///
+/// Idempotent: safe to call on every reconcile pass. Does a byte
+/// comparison before writing so an unchanged password + template is a
+/// no-op (no inode churn, no container restart cascade).
+///
+/// Errors if the secret file is missing or empty. Upstream callers
+/// treat that as "bitcoin-ui isn't installable yet" rather than fatal
+/// — the RPC password comes into being during bitcoin-core's own
+/// bootstrap, which may not have happened yet on a fresh node.
+pub async fn render(paths: &RenderPaths) -> Result<RenderOutcome> {
+    let password = read_password(&paths.secret_path).await?;
+    let auth_b64 = encode_basic_auth(RPC_USER, &password);
+    let rendered = TEMPLATE.replace(PLACEHOLDER, &auth_b64);
+
+    // Compare against existing. read-to-string fails on ENOENT (first
+    // install) — treat as "different".
+    let existing = fs::read_to_string(&paths.rendered_path).await.ok();
+    if existing.as_deref() == Some(rendered.as_str()) {
+        return Ok(RenderOutcome::Unchanged);
+    }
+
+    // Atomic write: write to sibling tmp + rename. Keeps the bind-
+    // mounted file pointing at a fully-formed config at all times.
+    let parent = paths
+        .rendered_path
+        .parent()
+        .ok_or_else(|| anyhow::anyhow!("rendered_path has no parent directory"))?;
+    fs::create_dir_all(parent)
+        .await
+        .with_context(|| format!("creating {}", parent.display()))?;
+
+    let tmp = unique_tmp_path(&paths.rendered_path);
+    fs::write(&tmp, &rendered)
+        .await
+        .with_context(|| format!("writing tmp {}", tmp.display()))?;
+    fs::rename(&tmp, &paths.rendered_path)
+        .await
+        .with_context(|| {
+            format!(
+                "renaming {} -> {}",
+                tmp.display(),
+                paths.rendered_path.display()
+            )
+        })?;
+
+    tracing::info!(
+        path = %paths.rendered_path.display(),
+        auth_hash = %short_hash(&auth_b64),
+        "bitcoin-ui nginx.conf rendered"
+    );
+
+    Ok(RenderOutcome::Written)
+}
+
+fn unique_tmp_path(dest: &Path) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let n = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let ts = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    dest.with_extension(format!("tmp.{ts}.{n}"))
+}
+
+/// Read the plaintext RPC password from disk. Trims trailing newlines
+/// (common from `echo "$PASS" > file`) but rejects an empty result.
+async fn read_password(path: &Path) -> Result<String> {
+    let raw = fs::read_to_string(path)
+        .await
+        .with_context(|| format!("reading bitcoin RPC password from {}", path.display()))?;
+    let trimmed = raw.trim().to_string();
+    if trimmed.is_empty() {
+        anyhow::bail!(
+            "bitcoin RPC password file {} is empty — bitcoin-core bootstrap hasn't written it yet",
+            path.display()
+        );
+    }
+    Ok(trimmed)
+}
+
+/// `base64("user:password")` — the value nginx puts after `Basic ` in
+/// the upstream `Authorization` header.
+fn encode_basic_auth(user: &str, password: &str) -> String {
+    let raw = format!("{user}:{password}");
+    base64::engine::general_purpose::STANDARD.encode(raw.as_bytes())
+}
+
+/// Short hash of the auth value for logging — we never want the
+/// plaintext or full base64 in logs (it's a credential), but a stable
+/// fingerprint helps correlate rotations.
+fn short_hash(s: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(s.as_bytes());
+    let digest = hasher.finalize();
+    hex::encode(&digest[..4])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn paths_in(dir: &Path, password: &str) -> RenderPaths {
+        let secret = dir.join("bitcoin-rpc-password");
+        std::fs::write(&secret, password).unwrap();
+        RenderPaths {
+            secret_path: secret,
+            rendered_path: dir.join("nginx.conf"),
+        }
+    }
+
+    #[tokio::test]
+    async fn render_writes_file_with_substitution() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2");
+        let outcome = render(&paths).await.unwrap();
+        assert_eq!(outcome, RenderOutcome::Written);
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        // archipelago:hunter2 -> "YXJjaGlwZWxhZ286aHVudGVyMg=="
+        assert!(
+            contents.contains("YXJjaGlwZWxhZ286aHVudGVyMg=="),
+            "base64 auth not found in rendered config:\n{contents}"
+        );
+        assert!(
+            !contents.contains(PLACEHOLDER),
+            "placeholder left in output"
+        );
+    }
+
+    #[tokio::test]
+    async fn render_is_idempotent_when_password_unchanged() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2");
+        let first = render(&paths).await.unwrap();
+        assert_eq!(first, RenderOutcome::Written);
+        let second = render(&paths).await.unwrap();
+        assert_eq!(second, RenderOutcome::Unchanged);
+    }
+
+    #[tokio::test]
+    async fn render_rewrites_on_password_rotation() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "old-pass");
+        render(&paths).await.unwrap();
+        // Rotate.
+        std::fs::write(&paths.secret_path, "new-pass").unwrap();
+        let outcome = render(&paths).await.unwrap();
+        assert_eq!(outcome, RenderOutcome::Written);
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        // archipelago:new-pass -> "YXJjaGlwZWxhZ286bmV3LXBhc3M="
+        assert!(contents.contains("YXJjaGlwZWxhZ286bmV3LXBhc3M="));
+    }
+
+    #[tokio::test]
+    async fn render_trims_trailing_newline_from_secret() {
+        // Matches `echo "$PASS" > file` behaviour.
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2\n");
+        render(&paths).await.unwrap();
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        assert!(
+            contents.contains("YXJjaGlwZWxhZ286aHVudGVyMg=="),
+            "trailing newline should be stripped before encoding"
+        );
+    }
+
+    #[tokio::test]
+    async fn render_errors_on_empty_password() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "");
+        let err = render(&paths).await.unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("empty"), "unexpected error: {msg}");
+    }
+
+    #[tokio::test]
+    async fn render_errors_when_secret_missing() {
+        let tmp = TempDir::new().unwrap();
+        let paths = RenderPaths {
+            secret_path: tmp.path().join("does-not-exist"),
+            rendered_path: tmp.path().join("nginx.conf"),
+        };
+        let err = render(&paths).await.unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("reading bitcoin RPC password"),
+            "unexpected error: {msg}"
+        );
+    }
+
+    #[test]
+    fn template_contains_exactly_one_placeholder() {
+        // Safety net: if someone adds a second placeholder to the
+        // template without updating the renderer, we want a test to
+        // fail loudly rather than ship a half-substituted config.
+        let count = TEMPLATE.matches(PLACEHOLDER).count();
+        assert_eq!(count, 1, "template must contain exactly one {PLACEHOLDER}");
+    }
+
+    #[test]
+    fn template_proxies_bitcoin_rpc_on_8332() {
+        // Lock in the core shape so a bad template edit doesn't ship.
+        assert!(TEMPLATE.contains("proxy_pass http://127.0.0.1:8332/"));
+        assert!(TEMPLATE.contains("location /bitcoin-rpc/"));
+        assert!(TEMPLATE.contains("listen 8334"));
+    }
+}
@@ -9,7 +9,7 @@ server {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header Authorization "Basic __BITCOIN_RPC_AUTH__";
+        proxy_set_header Authorization "Basic {{BITCOIN_RPC_AUTH}}";
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods "POST, GET, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type, Authorization";
@@ -0,0 +1,331 @@
+//! BootReconciler — the long-running task that keeps the prod orchestrator's
+//! desired-state view in lockstep with what podman actually has.
+//!
+//! Step 5 of the rust-orchestrator migration. Spawned once from `main.rs`
+//! (Step 6) after the initial `adopt_existing()` pass. Every `interval` it
+//! calls `ProdContainerOrchestrator::reconcile_all()`, which ensures every
+//! loaded manifest has a running container, installing fresh ones as needed.
+//!
+//! Per answered design Q3, `interval` defaults to 30 seconds.
+//!
+//! Shutdown is signalled via `Arc<Notify>`. The reconciler finishes its
+//! current `reconcile_all` call before exiting — we don't interrupt an
+//! in-flight pull or build.
+//!
+//! See `docs/rust-orchestrator-migration.md` §269-352.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::Notify;
+use tokio::time::{self, Instant};
+
+use crate::container::prod_orchestrator::{ProdContainerOrchestrator, ReconcileReport};
+
+/// Default reconciler cadence (answered design Q3).
+pub const DEFAULT_INTERVAL: Duration = Duration::from_secs(30);
+
+pub struct BootReconciler {
+    orchestrator: Arc<ProdContainerOrchestrator>,
+    interval: Duration,
+    shutdown: Arc<Notify>,
+}
+
+impl BootReconciler {
+    pub fn new(
+        orchestrator: Arc<ProdContainerOrchestrator>,
+        interval: Duration,
+        shutdown: Arc<Notify>,
+    ) -> Self {
+        Self {
+            orchestrator,
+            interval,
+            shutdown,
+        }
+    }
+
+    /// Run the reconcile loop until `shutdown` is notified.
+    ///
+    /// Does one reconcile immediately, then sleeps `interval` between
+    /// subsequent passes. A `shutdown.notify_one()` call unblocks the sleep
+    /// and the task returns after the *next* pass completes.
+    ///
+    /// Never panics: per-app failures are absorbed into `ReconcileReport` by
+    /// the orchestrator, and `reconcile_all` itself returns infallibly.
+    pub async fn run_forever(self) {
+        // Initial pass: no delay.
+        let report = self.orchestrator.reconcile_all().await;
+        Self::log_report(&report);
+
+        loop {
+            let deadline = Instant::now() + self.interval;
+            tokio::select! {
+                _ = time::sleep_until(deadline) => {
+                    let report = self.orchestrator.reconcile_all().await;
+                    Self::log_report(&report);
+                }
+                _ = self.shutdown.notified() => {
+                    tracing::info!("boot reconciler: shutdown requested, exiting loop");
+                    break;
+                }
+            }
+        }
+    }
+
+    fn log_report(report: &ReconcileReport) {
+        for (app_id, action) in &report.actions {
+            tracing::debug!(app_id = %app_id, action = ?action, "reconcile action");
+        }
+        for (app_id, err) in &report.failures {
+            tracing::warn!(app_id = %app_id, error = %err, "reconcile failure");
+        }
+        if report.failures.is_empty() {
+            tracing::debug!(count = report.actions.len(), "reconcile pass complete");
+        } else {
+            tracing::warn!(
+                ok = report.actions.len(),
+                failed = report.failures.len(),
+                "reconcile pass completed with failures"
+            );
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::container::prod_orchestrator::ProdContainerOrchestrator;
+    use anyhow::Result;
+    use archipelago_container::{
+        AppManifest, BuildConfig, ContainerRuntime as ContainerRuntimeTrait, ContainerState,
+        ContainerStatus,
+    };
+    use async_trait::async_trait;
+    use std::collections::HashMap;
+    use std::path::PathBuf;
+    use std::sync::Mutex as StdMutex;
+
+    /// Instrumented runtime that counts reconcile-loop side effects so tests
+    /// can tell exactly how many passes have fired. All containers are
+    /// reported as already Running so `reconcile_all` will NoOp — we are only
+    /// measuring loop cadence, not install behavior.
+    #[derive(Default)]
+    struct CountingRuntime {
+        /// Number of times get_container_status has been called. Each
+        /// reconcile_all pass hits this once per manifest, so with one
+        /// manifest this equals the number of reconcile passes.
+        status_calls: StdMutex<u32>,
+        running: StdMutex<HashMap<String, ContainerState>>,
+    }
+
+    impl CountingRuntime {
+        fn new_with(names: &[&str]) -> Self {
+            let me = Self::default();
+            let mut m = me.running.lock().unwrap();
+            for n in names {
+                m.insert((*n).to_string(), ContainerState::Running);
+            }
+            drop(m);
+            me
+        }
+        fn status_call_count(&self) -> u32 {
+            *self.status_calls.lock().unwrap()
+        }
+    }
+
+    #[async_trait]
+    impl ContainerRuntimeTrait for CountingRuntime {
+        async fn pull_image(&self, _: &str, _: Option<&str>) -> Result<()> {
+            Ok(())
+        }
+        async fn create_container(&self, _: &AppManifest, name: &str, _: u16) -> Result<String> {
+            Ok(name.to_string())
+        }
+        async fn start_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn stop_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn remove_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn get_container_status(&self, name: &str) -> Result<ContainerStatus> {
+            *self.status_calls.lock().unwrap() += 1;
+            let state = self
+                .running
+                .lock()
+                .unwrap()
+                .get(name)
+                .cloned()
+                .ok_or_else(|| anyhow::anyhow!("not found: {name}"))?;
+            Ok(ContainerStatus {
+                id: format!("id-{name}"),
+                name: name.to_string(),
+                state,
+                health: None,
+                exit_code: None,
+                started_at: None,
+                image: "test".into(),
+                created: "now".into(),
+                ports: vec![],
+                lan_address: None,
+            })
+        }
+        async fn get_container_logs(&self, _: &str, _: u32) -> Result<Vec<String>> {
+            Ok(vec![])
+        }
+        async fn list_containers(&self) -> Result<Vec<ContainerStatus>> {
+            Ok(vec![])
+        }
+        async fn image_exists(&self, _: &str) -> Result<bool> {
+            Ok(true)
+        }
+        async fn build_image(&self, _: &BuildConfig) -> Result<()> {
+            Ok(())
+        }
+    }
+
+    fn pull_manifest(id: &str, image: &str) -> AppManifest {
+        let yaml = format!(
+            "app:\n  id: {id}\n  name: {id}\n  version: 1.0.0\n  container:\n    image: {image}\n"
+        );
+        AppManifest::parse(&yaml).unwrap()
+    }
+
+    async fn orch_with_one_running_manifest(
+        rt: Arc<CountingRuntime>,
+    ) -> Arc<ProdContainerOrchestrator> {
+        let orch = Arc::new(ProdContainerOrchestrator::with_runtime(
+            rt,
+            PathBuf::from("/nonexistent-for-tests"),
+        ));
+        orch.insert_manifest_for_test(
+            pull_manifest("bitcoin-knots", "docker.io/bitcoin/knots:28"),
+            PathBuf::from("/tmp/bk"),
+        )
+        .await;
+        orch
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn initial_pass_fires_immediately() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler =
+            BootReconciler::new(orch.clone(), Duration::from_secs(30), shutdown.clone());
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        // Yield so the spawned task gets CPU to run its initial reconcile.
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        // We expect exactly one reconcile pass to have run by now (the initial),
+        // NOT a second one (the 30s sleep hasn't elapsed in paused time).
+        assert_eq!(rt.status_call_count(), 1, "initial pass should fire once");
+
+        shutdown.notify_one();
+        // Under paused clock the select! is blocked on sleep_until; the notify
+        // will unblock it. Advance wall-clock a hair so the notify gets polled.
+        tokio::task::yield_now().await;
+        let _ = tokio::time::timeout(Duration::from_secs(1), handle).await;
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn second_pass_fires_after_interval() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler =
+            BootReconciler::new(orch.clone(), Duration::from_secs(30), shutdown.clone());
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        assert_eq!(rt.status_call_count(), 1);
+
+        // Fast-forward past one interval; the sleep_until should fire.
+        tokio::time::advance(Duration::from_secs(31)).await;
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        assert_eq!(
+            rt.status_call_count(),
+            2,
+            "a second reconcile pass should fire after one interval"
+        );
+
+        shutdown.notify_one();
+        tokio::task::yield_now().await;
+        let _ = tokio::time::timeout(Duration::from_secs(1), handle).await;
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn shutdown_terminates_loop() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler =
+            BootReconciler::new(orch.clone(), Duration::from_secs(30), shutdown.clone());
+        let handle = tokio::spawn(reconciler.run_forever());
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        shutdown.notify_one();
+        // The select! should wake on Notified and return. Use a real timeout
+        // with advancing the paused clock to make sure the task exits.
+        tokio::time::advance(Duration::from_millis(10)).await;
+        let result = tokio::time::timeout(Duration::from_secs(5), handle).await;
+        assert!(result.is_ok(), "reconciler did not exit after shutdown");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn failure_in_one_pass_does_not_stop_loop() {
+        // Manifest references a container the runtime does not have AND
+        // cannot create (no install path — install_fresh will also fail to
+        // pull, since CountingRuntime::pull_image returns Ok but the
+        // manifest's referenced container stays uncreated). In practice
+        // reconcile_all will observe the missing container, install_fresh
+        // will run, and the next pass will see a new state. We care about
+        // "loop keeps ticking even when the report has actions".
+        let rt = Arc::new(CountingRuntime::default());
+        let orch = Arc::new(ProdContainerOrchestrator::with_runtime(
+            rt.clone(),
+            PathBuf::from("/nonexistent-for-tests"),
+        ));
+        orch.insert_manifest_for_test(
+            pull_manifest("bitcoin-knots", "docker.io/bitcoin/knots:28"),
+            PathBuf::from("/tmp/bk"),
+        )
+        .await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler =
+            BootReconciler::new(orch.clone(), Duration::from_secs(30), shutdown.clone());
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        let first = rt.status_call_count();
+        assert!(first >= 1, "initial pass should have touched the runtime");
+
+        // Advance one interval — second pass should fire regardless of what
+        // the first pass did.
+        tokio::time::advance(Duration::from_secs(31)).await;
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        let second = rt.status_call_count();
+        assert!(
+            second > first,
+            "loop should have fired a second pass after the interval"
+        );
+
+        shutdown.notify_one();
+        tokio::time::advance(Duration::from_millis(10)).await;
+        let _ = tokio::time::timeout(Duration::from_secs(5), handle).await;
+    }
+}
@@ -1,12 +1,15 @@
 use anyhow::{Context, Result};
 use archipelago_container::{
    AppManifest, BitcoinSimulationMode, BitcoinSimulator,
-    ContainerRuntime as ContainerRuntimeTrait, ContainerStatus, PortManager,
+    ContainerRuntime as ContainerRuntimeTrait, ContainerStatus, PortManager, ResolvedSource,
 };
+use async_trait::async_trait;
+use std::path::{Path, PathBuf};
 use std::sync::Arc;

 use crate::config::{BitcoinSimulation, Config, ContainerRuntime};
 use crate::container::data_manager::DevDataManager;
+use crate::container::traits::ContainerOrchestrator;

 pub struct DevContainerOrchestrator {
    runtime: Arc<dyn ContainerRuntimeTrait>,
@@ -103,14 +106,27 @@ impl DevContainerOrchestrator {
            volume.source = dev_path.to_string_lossy().to_string();
        }

-        // Pull image
-        self.runtime
-            .pull_image(
-                &manifest.app.container.image,
-                manifest.app.container.image_signature.as_deref(),
-            )
-            .await
-            .context("Failed to pull image")?;
+        // Resolve pull-or-build. Dev orchestrator currently only supports pull;
+        // Build support lands in Step 2 of the rust-orchestrator migration.
+        match manifest.app.container.resolve().ok_or_else(|| {
+            anyhow::anyhow!("manifest container config invalid (neither image nor build)")
+        })? {
+            ResolvedSource::Pull {
+                image,
+                image_signature,
+                ..
+            } => {
+                self.runtime
+                    .pull_image(&image, image_signature.as_deref())
+                    .await
+                    .context("Failed to pull image")?;
+            }
+            ResolvedSource::Build(_) => {
+                anyhow::bail!(
+                    "dev orchestrator does not yet support local image builds (see rust-orchestrator-migration.md Step 2)"
+                );
+            }
+        }

        // Create container with port offset
        let port_offset = if self.config.dev_mode {
@@ -242,4 +258,153 @@ impl DevContainerOrchestrator {
            archipelago_container::ContainerState::Unknown(_) => Ok("unknown".to_string()),
        }
    }
+
+    /// Load a manifest for `app_id` from the dev-mode apps directory.
+    ///
+    /// Used by the trait-level `install(app_id)` entry point.
+    ///
+    /// Search order intentionally mirrors production/operator reality:
+    /// 1) `$ARCHIPELAGO_APPS_DIR` (explicit override)
+    /// 2) `/opt/archipelago/apps` (image-recipe canonical path)
+    /// 3) `/home/archipelago/Projects/archy/apps` (repo-local fallback on dev nodes)
+    /// 4) `<data_dir>/apps` (legacy dev layout)
+    async fn load_manifest_for(&self, app_id: &str) -> Result<AppManifest> {
+        let candidates = candidate_manifest_paths(app_id, &self.config.data_dir);
+        let mut last_err: Option<anyhow::Error> = None;
+
+        for path in candidates {
+            let content = match tokio::fs::read_to_string(&path).await {
+                Ok(c) => c,
+                Err(e) => {
+                    last_err = Some(e.into());
+                    continue;
+                }
+            };
+
+            let manifest: AppManifest = serde_yaml::from_str(&content)
+                .with_context(|| format!("parsing manifest {}", path.display()))?;
+            return Ok(manifest);
+        }
+
+        let msg = format!(
+            "manifest for {} not found in any search path (set ARCHIPELAGO_APPS_DIR or install /opt/archipelago/apps)",
+            app_id
+        );
+        Err(match last_err {
+            Some(e) => e.context(msg),
+            None => anyhow::anyhow!(msg),
+        })
+    }
+}
+
+fn candidate_manifest_paths(app_id: &str, data_dir: &Path) -> Vec<PathBuf> {
+    let mut roots: Vec<PathBuf> = Vec::new();
+
+    if let Ok(v) = std::env::var("ARCHIPELAGO_APPS_DIR") {
+        let v = v.trim();
+        if !v.is_empty() {
+            roots.push(PathBuf::from(v));
+        }
+    }
+
+    roots.push(PathBuf::from("/opt/archipelago/apps"));
+    roots.push(PathBuf::from("/home/archipelago/Projects/archy/apps"));
+    roots.push(data_dir.join("apps"));
+
+    let mut deduped: Vec<PathBuf> = Vec::new();
+    for root in roots {
+        if !deduped.iter().any(|p| p == &root) {
+            deduped.push(root);
+        }
+    }
+
+    deduped
+        .into_iter()
+        .map(|root| root.join(app_id).join("manifest.yml"))
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Trait impl (Step 4): expose the shared ContainerOrchestrator surface.
+// Forwards to the inherent methods, which internally apply the `-dev` suffix
+// and the port offset. The trait keeps the RPC layer mode-agnostic; Dev's
+// install_container (manifest_path-based) stays as an inherent method for the
+// ad-hoc dev-mode RPC and is not exposed on the trait.
+// ---------------------------------------------------------------------------
+
+#[async_trait]
+impl ContainerOrchestrator for DevContainerOrchestrator {
+    async fn install(&self, app_id: &str) -> Result<String> {
+        let manifest = self.load_manifest_for(app_id).await?;
+        let name = self.install_container(&manifest, "").await?;
+        Ok(name)
+    }
+
+    async fn start(&self, app_id: &str) -> Result<()> {
+        self.start_container(app_id).await
+    }
+
+    async fn stop(&self, app_id: &str) -> Result<()> {
+        self.stop_container(app_id).await
+    }
+
+    async fn restart(&self, app_id: &str) -> Result<()> {
+        let _ = self.stop_container(app_id).await;
+        self.start_container(app_id).await
+    }
+
+    async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()> {
+        self.remove_container(app_id, preserve_data).await
+    }
+
+    async fn upgrade(&self, app_id: &str) -> Result<()> {
+        // Dev upgrade: stop, remove (preserving data), re-install from the loaded manifest.
+        let _ = self.stop_container(app_id).await;
+        let _ = self.remove_container(app_id, true).await;
+        let manifest = self.load_manifest_for(app_id).await?;
+        self.install_container(&manifest, "").await?;
+        self.start_container(app_id).await
+    }
+
+    async fn status(&self, app_id: &str) -> Result<ContainerStatus> {
+        self.get_container_status(app_id).await
+    }
+
+    async fn list(&self) -> Result<Vec<ContainerStatus>> {
+        self.list_containers().await
+    }
+
+    async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>> {
+        self.get_container_logs(app_id, lines).await
+    }
+
+    async fn health(&self, app_id: &str) -> Result<String> {
+        self.get_health_status(app_id).await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::candidate_manifest_paths;
+    use std::path::PathBuf;
+
+    #[test]
+    fn candidate_manifest_paths_include_expected_fallbacks() {
+        let app_id = "bitcoin-ui";
+        let paths = candidate_manifest_paths(app_id, &PathBuf::from("/var/lib/archipelago"));
+        let as_strings: Vec<String> = paths
+            .iter()
+            .map(|p| p.to_string_lossy().into_owned())
+            .collect();
+
+        assert!(as_strings
+            .iter()
+            .any(|p| p == "/opt/archipelago/apps/bitcoin-ui/manifest.yml"));
+        assert!(as_strings
+            .iter()
+            .any(|p| p == "/home/archipelago/Projects/archy/apps/bitcoin-ui/manifest.yml"));
+        assert!(as_strings
+            .iter()
+            .any(|p| p == "/var/lib/archipelago/apps/bitcoin-ui/manifest.yml"));
+    }
 }
@@ -44,11 +44,6 @@ impl DockerPackageScanner {
            "nbxplorer",
            "mempool-db",
            "mempool-api",
-            "penpot-postgres",
-            "penpot-backend",
-            "penpot-exporter",
-            "penpot-valkey",
-            "penpot-mailcatch",
            "immich_postgres",
            "immich_redis",
            "endurain-db",
@@ -247,6 +242,7 @@ impl DockerPackageScanner {
                    status: service_status,
                }),
                install_progress: None,
+                uninstall_stage: None,
            };

            packages.insert(app_id.clone(), package);
@@ -296,9 +292,16 @@ fn get_app_tier(app_id: &str) -> &'static str {

 fn get_app_metadata(app_id: &str) -> AppMetadata {
    let mut meta = match app_id {
-        "bitcoin" | "bitcoin-core" | "bitcoin-knots" => AppMetadata {
+        "bitcoin-core" => AppMetadata {
+            title: "Bitcoin Core".to_string(),
+            description: "Reference Bitcoin node implementation".to_string(),
+            icon: "/assets/img/app-icons/bitcoin-core.svg".to_string(),
+            repo: "https://github.com/bitcoin/bitcoin".to_string(),
+            tier: "",
+        },
+        "bitcoin" | "bitcoin-knots" => AppMetadata {
            title: "Bitcoin Knots".to_string(),
-            description: "Full Bitcoin node implementation".to_string(),
+            description: "Enhanced Bitcoin node implementation".to_string(),
            icon: "/assets/img/app-icons/bitcoin-knots.webp".to_string(),
            repo: "https://github.com/bitcoinknots/bitcoin".to_string(),
            tier: "",
@@ -408,13 +411,6 @@ fn get_app_metadata(app_id: &str) -> AppMetadata {
            repo: "https://github.com/cryptpad/cryptpad".to_string(),
            tier: "",
        },
-        "penpot" | "penpot-frontend" => AppMetadata {
-            title: "Penpot".to_string(),
-            description: "Open-source design and prototyping".to_string(),
-            icon: "/assets/img/app-icons/penpot.webp".to_string(),
-            repo: "https://github.com/penpot/penpot".to_string(),
-            tier: "",
-        },
        "nextcloud" => AppMetadata {
            title: "Nextcloud".to_string(),
            description: "Self-hosted cloud storage and file management".to_string(),
@@ -492,13 +488,6 @@ fn get_app_metadata(app_id: &str) -> AppMetadata {
            repo: "https://github.com/indeedhub/indeedhub".to_string(),
            tier: "",
        },
-        "nostr-rs-relay" => AppMetadata {
-            title: "Nostr Relay".to_string(),
-            description: "Run your own Nostr relay for sovereign event storage".to_string(),
-            icon: "/assets/img/app-icons/nostr-rs-relay.svg".to_string(),
-            repo: "https://sr.ht/~gheartsfield/nostr-rs-relay/".to_string(),
-            tier: "",
-        },
        "dwn" => AppMetadata {
            title: "Decentralized Web Node".to_string(),
            description: "Store and sync personal data with DID-based access control".to_string(),
@@ -0,0 +1,118 @@
+//! filebrowser config bootstrap helper.
+//!
+//! Mirrors the legacy first-boot behavior that writes
+//! `/var/lib/archipelago/filebrowser-data/.filebrowser.json` before
+//! starting the container with `--config /data/.filebrowser.json`.
+
+use anyhow::{Context, Result};
+use std::path::PathBuf;
+use tokio::fs;
+
+pub const DEFAULT_SRV_ROOT: &str = "/var/lib/archipelago/filebrowser";
+pub const DEFAULT_DATA_DIR: &str = "/var/lib/archipelago/filebrowser-data";
+pub const DEFAULT_CONFIG_PATH: &str = "/var/lib/archipelago/filebrowser-data/.filebrowser.json";
+
+const DEFAULT_CONFIG_JSON: &str =
+    "{\"port\":80,\"baseURL\":\"\",\"address\":\"0.0.0.0\",\"database\":\"/data/filebrowser.db\",\"root\":\"/srv\",\"log\":\"stdout\"}\n";
+
+#[derive(Debug, Clone)]
+pub struct EnsurePaths {
+    pub srv_root: PathBuf,
+    pub data_dir: PathBuf,
+    pub config_path: PathBuf,
+}
+
+impl Default for EnsurePaths {
+    fn default() -> Self {
+        Self {
+            srv_root: PathBuf::from(DEFAULT_SRV_ROOT),
+            data_dir: PathBuf::from(DEFAULT_DATA_DIR),
+            config_path: PathBuf::from(DEFAULT_CONFIG_PATH),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EnsureOutcome {
+    Written,
+    Unchanged,
+}
+
+pub async fn ensure_config(paths: &EnsurePaths) -> Result<EnsureOutcome> {
+    fs::create_dir_all(&paths.srv_root)
+        .await
+        .with_context(|| format!("creating {}", paths.srv_root.display()))?;
+    fs::create_dir_all(&paths.data_dir)
+        .await
+        .with_context(|| format!("creating {}", paths.data_dir.display()))?;
+
+    for d in ["Documents", "Photos", "Music", "Downloads", "Builds"] {
+        fs::create_dir_all(paths.srv_root.join(d))
+            .await
+            .with_context(|| format!("creating {}/{}", paths.srv_root.display(), d))?;
+    }
+
+    if paths.config_path.exists() {
+        return Ok(EnsureOutcome::Unchanged);
+    }
+
+    let parent = paths
+        .config_path
+        .parent()
+        .ok_or_else(|| anyhow::anyhow!("config_path has no parent directory"))?;
+    fs::create_dir_all(parent)
+        .await
+        .with_context(|| format!("creating {}", parent.display()))?;
+
+    let tmp = paths.config_path.with_extension("tmp");
+    fs::write(&tmp, DEFAULT_CONFIG_JSON)
+        .await
+        .with_context(|| format!("writing tmp {}", tmp.display()))?;
+    fs::rename(&tmp, &paths.config_path)
+        .await
+        .with_context(|| {
+            format!(
+                "renaming {} -> {}",
+                tmp.display(),
+                paths.config_path.display()
+            )
+        })?;
+
+    Ok(EnsureOutcome::Written)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn ensure_config_creates_dirs_and_file() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let paths = EnsurePaths {
+            srv_root: tmp.path().join("filebrowser"),
+            data_dir: tmp.path().join("filebrowser-data"),
+            config_path: tmp.path().join("filebrowser-data/.filebrowser.json"),
+        };
+
+        let out = ensure_config(&paths).await.unwrap();
+        assert_eq!(out, EnsureOutcome::Written);
+        assert!(paths.config_path.exists());
+        assert!(paths.srv_root.join("Documents").exists());
+        assert!(paths.srv_root.join("Photos").exists());
+    }
+
+    #[tokio::test]
+    async fn ensure_config_is_idempotent() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let paths = EnsurePaths {
+            srv_root: tmp.path().join("filebrowser"),
+            data_dir: tmp.path().join("filebrowser-data"),
+            config_path: tmp.path().join("filebrowser-data/.filebrowser.json"),
+        };
+
+        let first = ensure_config(&paths).await.unwrap();
+        assert_eq!(first, EnsureOutcome::Written);
+        let second = ensure_config(&paths).await.unwrap();
+        assert_eq!(second, EnsureOutcome::Unchanged);
+    }
+}
@@ -1,8 +1,8 @@
 //! Parser for image-versions.sh — single source of truth for pinned container images.
 //!
-//! Reads the deployed file at /opt/archipelago/image-versions.sh (or the repo-local
-//! scripts/image-versions.sh as fallback) and exposes lookup functions so the container
-//! scanner can compare running images against pinned targets.
+//! Reads the deployed file at /opt/archipelago/scripts/image-versions.sh (the canonical
+//! location installed by the image-recipe) with fallbacks for older layouts and the
+//! repo-local scripts/image-versions.sh for development runs from the repo root.

 use std::collections::HashMap;
 use std::path::Path;
@@ -18,9 +18,15 @@ struct CacheEntry {
    images: HashMap<String, String>,
 }

-/// File search order — production path first, then repo-local for dev.
+/// File search order — canonical production path first, older layout second,
+/// repo-local for dev last. The canonical deployed path is
+/// /opt/archipelago/scripts/image-versions.sh; earlier builds put it directly
+/// in /opt/archipelago/, so that path is kept as a fallback for not-yet-updated
+/// nodes. The repo-relative entry matches `cargo run` from the repo root.
 const PATHS: &[&str] = &[
+    "/opt/archipelago/scripts/image-versions.sh",
    "/opt/archipelago/image-versions.sh",
+    "/home/archipelago/Projects/archy/scripts/image-versions.sh",
    "scripts/image-versions.sh",
 ];

@@ -102,8 +108,11 @@ fn parse_image_versions(content: &str) -> HashMap<String, String> {
        }
    }

-    // Keep only *_IMAGE entries
-    vars.retain(|k, _| k.ends_with("_IMAGE"));
+    // Keep only *_IMAGE entries whose value looks like a container image
+    // reference (contains a `:` tag separator and at least one `/` path
+    // component). Rejects placeholder values like "something" so a
+    // hand-edit typo in image-versions.sh never gets treated as an image.
+    vars.retain(|k, v| k.ends_with("_IMAGE") && v.contains(':') && v.contains('/'));
    vars
 }

@@ -134,12 +143,15 @@ fn image_var_for_app(app_id: &str) -> Option<&'static str> {
        "lnd" => Some("LND_IMAGE"),
        "electrumx" => Some("ELECTRUMX_IMAGE"),
        "electrs" | "mempool-electrs" => Some("ELECTRUMX_IMAGE"),
+        "bitcoin-ui" | "archy-bitcoin-ui" => Some("BITCOIN_UI_IMAGE"),
+        "lnd-ui" | "archy-lnd-ui" => Some("LND_UI_IMAGE"),
+        "electrs-ui" | "archy-electrs-ui" => Some("ELECTRS_UI_IMAGE"),

        // Mempool stack (primary = web)
-        "mempool" | "mempool-web" => Some("MEMPOOL_WEB_IMAGE"),
+        "mempool" | "mempool-web" | "archy-mempool-web" => Some("MEMPOOL_WEB_IMAGE"),

        // BTCPay stack (primary = server)
-        "btcpay" | "btcpay-server" | "btcpayserver" => Some("BTCPAY_IMAGE"),
+        "btcpay" | "btcpay-server" | "btcpayserver" | "archy-btcpay-ui" => Some("BTCPAY_IMAGE"),

        // Apps
        "homeassistant" | "home-assistant" => Some("HOMEASSISTANT_IMAGE"),
@@ -1,8 +1,19 @@
+pub mod bitcoin_ui;
+pub mod boot_reconciler;
 pub mod data_manager;
 pub mod dev_orchestrator;
 pub mod docker_packages;
+pub mod filebrowser;
 pub mod image_versions;
+pub mod prod_orchestrator;
 pub mod registry;
+pub mod traits;

+pub use boot_reconciler::{BootReconciler, DEFAULT_INTERVAL as RECONCILER_DEFAULT_INTERVAL};
 pub use dev_orchestrator::DevContainerOrchestrator;
 pub use docker_packages::DockerPackageScanner;
+pub use prod_orchestrator::{
+    compute_container_name, AdoptionReport, ProdContainerOrchestrator, ReconcileAction,
+    ReconcileReport,
+};
+pub use traits::ContainerOrchestrator;
@@ -15,7 +15,7 @@ const REGISTRY_FILE: &str = "config/registries.json";
 /// A single container registry.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Registry {
-    /// Registry URL (e.g., "git.tx1138.com/lfg2025" or "23.182.128.160:3000/lfg2025").
+    /// Registry URL (e.g., "git.tx1138.com/lfg2025" or "146.59.87.168:3000/lfg2025").
    pub url: String,
    /// Human-readable name.
    pub name: String,
@@ -44,16 +44,16 @@ impl Default for RegistryConfig {
        Self {
            registries: vec![
                Registry {
-                    url: "git.tx1138.com/lfg2025".to_string(),
-                    name: "Archipelago Primary".to_string(),
-                    tls_verify: true,
+                    url: "146.59.87.168:3000/lfg2025".to_string(),
+                    name: "Server 1 (OVH)".to_string(),
+                    tls_verify: false,
                    enabled: true,
                    priority: 0,
                },
                Registry {
-                    url: "23.182.128.160:3000/lfg2025".to_string(),
-                    name: "Archipelago Fallback".to_string(),
-                    tls_verify: false,
+                    url: "git.tx1138.com/lfg2025".to_string(),
+                    name: "Server 2 (tx1138)".to_string(),
+                    tls_verify: true,
                    enabled: true,
                    priority: 10,
                },
@@ -71,29 +71,14 @@ impl RegistryConfig {
    }

    /// Rewrite an image reference to use a specific registry.
-    /// E.g., "git.tx1138.com/lfg2025/bitcoin-knots:latest" with registry "23.182.128.160:3000/lfg2025"
-    /// becomes "23.182.128.160:3000/lfg2025/bitcoin-knots:latest".
+    /// E.g., "git.tx1138.com/lfg2025/bitcoin-knots:latest" with registry "146.59.87.168:3000/lfg2025"
+    /// becomes "146.59.87.168:3000/lfg2025/bitcoin-knots:latest".
    pub fn rewrite_image(&self, image: &str, registry: &Registry) -> String {
        // Extract the image name (last component after the org/namespace)
        // Handles: "registry/org/image:tag" -> "image:tag"
        let image_name = extract_image_name(image);
        format!("{}/{}", registry.url, image_name)
    }
-
-    /// Generate fallback image URLs to try (excludes the original since it already failed).
-    pub fn image_candidates(&self, image: &str) -> Vec<(String, bool)> {
-        let mut candidates = Vec::new();
-
-        // Rewrite for each active registry (skip if identical to original)
-        for reg in self.active_registries() {
-            let rewritten = self.rewrite_image(image, reg);
-            if rewritten != image {
-                candidates.push((rewritten, reg.tls_verify));
-            }
-        }
-
-        candidates
-    }
 }

 /// Extract the image name from a full image reference.
@@ -104,7 +89,12 @@ fn extract_image_name(image: &str) -> &str {
    image.rsplit('/').next().unwrap_or(image)
 }

-/// Load registry config from disk.
+/// Load registry config from disk, merging in any default registries
+/// that the operator hasn't explicitly removed. This lets us roll out
+/// new default mirrors (e.g. a new Server 3) to existing nodes without
+/// them having to edit their saved config. Explicit removals stick —
+/// if the URL is absent from disk AND absent from current defaults, it
+/// stays gone.
 pub async fn load_registries(data_dir: &Path) -> Result<RegistryConfig> {
    let path = data_dir.join(REGISTRY_FILE);
    if !path.exists() {
@@ -113,8 +103,46 @@ pub async fn load_registries(data_dir: &Path) -> Result<RegistryConfig> {
    let content = fs::read_to_string(&path)
        .await
        .context("Failed to read registry config")?;
-    let config: RegistryConfig =
+    let mut config: RegistryConfig =
        serde_json::from_str(&content).unwrap_or_else(|_| RegistryConfig::default());
+
+    // One-time migration: the Hetzner VPS at 23.182.128.160 was
+    // decommissioned 2026-04-23. Existing nodes have it baked into
+    // their saved registry list (was the original Server 1). Strip it
+    // on load so every container pull doesn't pay a connection-refused
+    // timeout against a dead host. Exception to the usual "explicit
+    // removals stick" rule: the user never chose to add this — it
+    // was a default.
+    let before = config.registries.len();
+    config
+        .registries
+        .retain(|r| !r.url.contains("23.182.128.160"));
+    let mut changed = config.registries.len() != before;
+
+    // Migrate: any default registry URL that isn't already in the
+    // saved list gets appended at the end (so existing priority order
+    // is preserved for anything the operator already configured).
+    let defaults = RegistryConfig::default();
+    let known: std::collections::HashSet<String> =
+        config.registries.iter().map(|r| r.url.clone()).collect();
+    let max_priority = config
+        .registries
+        .iter()
+        .map(|r| r.priority)
+        .max()
+        .unwrap_or(0);
+    for (i, def) in defaults.registries.iter().enumerate() {
+        if !known.contains(&def.url) {
+            let mut cloned = def.clone();
+            cloned.priority = max_priority.saturating_add(10 + i as u32);
+            config.registries.push(cloned);
+            changed = true;
+        }
+    }
+    if changed {
+        // Persist so the next load doesn't have to re-merge.
+        let _ = save_registries(data_dir, &config).await;
+    }
    Ok(config)
 }

@@ -133,69 +161,6 @@ pub async fn save_registries(data_dir: &Path, config: &RegistryConfig) -> Result
    Ok(())
 }

-/// Try pulling an image from configured registries in priority order.
-/// Returns the image reference that succeeded.
-pub async fn pull_from_registries(data_dir: &Path, image: &str, tmpdir: &str) -> Result<String> {
-    let config = load_registries(data_dir).await?;
-    let candidates = config.image_candidates(image);
-
-    for (candidate, tls_verify) in &candidates {
-        debug!("Trying registry: {}", candidate);
-
-        let mut args = vec!["pull".to_string(), candidate.clone()];
-        if !tls_verify {
-            args.push("--tls-verify=false".to_string());
-        }
-
-        let mut child = tokio::process::Command::new("podman")
-            .args(&args)
-            .env("TMPDIR", tmpdir)
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .spawn()
-            .ok();
-
-        let status = if let Some(ref mut c) = child {
-            match tokio::time::timeout(std::time::Duration::from_secs(120), c.wait()).await {
-                Ok(Ok(s)) => Some(s.success()),
-                _ => {
-                    let _ = c.kill().await;
-                    let _ = c.wait().await;
-                    debug!("Fallback pull timed out: {}", candidate);
-                    None
-                }
-            }
-        } else {
-            None
-        };
-
-        if status == Some(true) {
-            // If we pulled from a non-original registry, tag it with the original name
-            if candidate != image {
-                let _ = tokio::process::Command::new("podman")
-                    .args(["tag", candidate, image])
-                    .status()
-                    .await;
-                info!(
-                    "Pulled {} from fallback registry, tagged as {}",
-                    candidate, image
-                );
-            } else {
-                info!("Pulled {} from primary registry", image);
-            }
-            return Ok(candidate.clone());
-        }
-
-        debug!("Failed to pull from {}", candidate);
-    }
-
-    Err(anyhow::anyhow!(
-        "Failed to pull {} from all {} configured registries",
-        image,
-        candidates.len()
-    ))
-}
-
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -217,21 +182,15 @@ mod tests {
    #[test]
    fn test_rewrite_image() {
        let config = RegistryConfig::default();
-        let fallback = &config.registries[1];
+        // Default primary is now the OVH VPS (index 0). A tx1138-hardcoded
+        // image rewrites to OVH when asked for the primary mirror.
+        let primary = &config.registries[0];
        assert_eq!(
-            config.rewrite_image("git.tx1138.com/lfg2025/bitcoin-knots:latest", fallback),
-            "23.182.128.160:3000/lfg2025/bitcoin-knots:latest"
+            config.rewrite_image("git.tx1138.com/lfg2025/bitcoin-knots:latest", primary),
+            "146.59.87.168:3000/lfg2025/bitcoin-knots:latest"
        );
    }

-    #[test]
-    fn test_image_candidates() {
-        let config = RegistryConfig::default();
-        let candidates = config.image_candidates("git.tx1138.com/lfg2025/lnd:v0.18.4-beta");
-        assert!(candidates.len() >= 2);
-        assert_eq!(candidates[0].0, "git.tx1138.com/lfg2025/lnd:v0.18.4-beta");
-    }
-
    #[test]
    fn test_active_registries_sorted() {
        let config = RegistryConfig::default();
@@ -0,0 +1,56 @@
+//! Orchestrator trait — the shared surface the RPC layer talks to.
+//!
+//! Step 4 of the rust-orchestrator migration. Unifies the container lifecycle
+//! surface of `DevContainerOrchestrator` and `ProdContainerOrchestrator` so
+//! `RpcHandler` can hold `Arc<dyn ContainerOrchestrator>` and stop caring
+//! which mode it is in.
+//!
+//! The trait takes `app_id: &str` everywhere (never a manifest path). Dev and
+//! Prod both resolve app_id → manifest internally. The legacy
+//! `container-install { manifest_path }` RPC shape is preserved as a concrete
+//! `install_container_from_path` method on `DevContainerOrchestrator` only,
+//! since that ad-hoc workflow is a dev convenience and has no prod meaning.
+//!
+//! See `docs/rust-orchestrator-migration.md`.
+
+use anyhow::Result;
+use archipelago_container::ContainerStatus;
+use async_trait::async_trait;
+
+/// Lifecycle + query operations every orchestrator exposes to the RPC layer.
+#[async_trait]
+pub trait ContainerOrchestrator: Send + Sync {
+    /// Build-or-pull the image, create the container, and start it. Returns the
+    /// podman container name that was created. Assumes the app_id corresponds
+    /// to a manifest the orchestrator already knows about.
+    async fn install(&self, app_id: &str) -> Result<String>;
+
+    /// Start an already-created container.
+    async fn start(&self, app_id: &str) -> Result<()>;
+
+    /// Stop a running container. No-op on Prod if already stopped.
+    async fn stop(&self, app_id: &str) -> Result<()>;
+
+    /// Stop-then-start. Best-effort: ignores stop failure.
+    async fn restart(&self, app_id: &str) -> Result<()>;
+
+    /// Remove the container. `preserve_data = true` keeps the volumes; `false`
+    /// is honored on a best-effort basis (Dev cleans, Prod leaves the volume
+    /// management to the data layer).
+    async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()>;
+
+    /// Pull/rebuild the image and recreate the container from scratch.
+    async fn upgrade(&self, app_id: &str) -> Result<()>;
+
+    /// Current state of a single container.
+    async fn status(&self, app_id: &str) -> Result<ContainerStatus>;
+
+    /// All containers this orchestrator knows about.
+    async fn list(&self) -> Result<Vec<ContainerStatus>>;
+
+    /// Tail the container's stdout+stderr.
+    async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>>;
+
+    /// Coarse health summary: "healthy", "unhealthy", "starting", "paused", "unknown".
+    async fn health(&self, app_id: &str) -> Result<String>;
+}
@@ -129,9 +129,21 @@ pub fn is_revoked(vc: &VerifiableCredential) -> bool {
 mod tests {
    use super::*;

+    /// Create a tempdir with a dummy `identity/node_key` so that the
+    /// credential store's encrypt/decrypt path can derive a key.
+    /// Returns the tempdir guard (drop it to clean up).
+    fn test_dir_with_node_key() -> tempfile::TempDir {
+        let dir = tempfile::tempdir().unwrap();
+        let identity_dir = dir.path().join("identity");
+        std::fs::create_dir_all(&identity_dir).unwrap();
+        // 32 bytes of deterministic test material; never a real key.
+        std::fs::write(identity_dir.join("node_key"), [0xAB; 32]).unwrap();
+        dir
+    }
+
    #[tokio::test]
    async fn test_issue_credential_w3c_format() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -163,7 +175,7 @@ mod tests {

    #[tokio::test]
    async fn test_issue_credential_serializes_as_jsonld() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -185,7 +197,7 @@ mod tests {

    #[tokio::test]
    async fn test_save_and_load_roundtrip() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:a",
@@ -205,7 +217,7 @@ mod tests {

    #[tokio::test]
    async fn test_issue_credential_sign_fn_failure_propagates() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let result = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -257,7 +269,7 @@ mod tests {

    #[tokio::test]
    async fn test_revoke_credential() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -288,7 +300,7 @@ mod tests {

    #[tokio::test]
    async fn test_revoke_nonexistent_credential_fails() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let result = revoke_credential(dir.path(), "urn:uuid:does-not-exist").await;
        assert!(result.is_err());
        assert!(result
@@ -299,7 +311,7 @@ mod tests {

    #[tokio::test]
    async fn test_list_credentials_no_filter() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:a",
@@ -329,7 +341,7 @@ mod tests {

    #[tokio::test]
    async fn test_list_credentials_filter_by_did() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:alice",
@@ -138,6 +138,17 @@ pub struct PackageDataEntry {
    pub installed: Option<InstalledPackageDataEntry>,
    #[serde(rename = "install-progress")]
    pub install_progress: Option<InstallProgress>,
+    /// Live label describing the current uninstall step ("Stopping
+    /// containers (2/5)", "Removing data", …). Set by the uninstall
+    /// pipeline so the UI can show real progress instead of a generic
+    /// "Uninstalling…" spinner. Cleared after the package entry is
+    /// removed.
+    #[serde(
+        rename = "uninstall-stage",
+        skip_serializing_if = "Option::is_none",
+        default
+    )]
+    pub uninstall_stage: Option<String>,
    /// Pinned image version from image-versions.sh when it differs from running version
    #[serde(rename = "available-update", skip_serializing_if = "Option::is_none")]
    pub available_update: Option<String>,
@@ -238,6 +249,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
@@ -263,7 +263,12 @@ async fn fetch_electrs_sync_status() -> ElectrsSyncStatus {
    let network_height = match bitcoin_network_height().await {
        Ok(h) => h,
        Err(e) => {
-            warn!("ElectrumX status: Bitcoin RPC failed: {}", e);
+            let err_msg = e.to_string();
+            if is_transient_error(&err_msg) {
+                tracing::debug!("ElectrumX status: Bitcoin RPC transient: {}", err_msg);
+            } else {
+                warn!("ElectrumX status: Bitcoin RPC failed: {}", err_msg);
+            }
            return ElectrsSyncStatus {
                indexed_height: 0,
                network_height: 0,
@@ -121,6 +121,7 @@ pub async fn accept_invite(
    local_onion: &str,
    local_pubkey: &str,
    local_fips_npub: Option<&str>,
+    local_name: Option<&str>,
    sign_fn: impl FnOnce(&[u8]) -> String,
 ) -> Result<FederatedNode> {
    let ParsedInvite {
@@ -131,6 +132,20 @@ pub async fn accept_invite(
        fips_npub,
    } = parse_invite(code)?;

+    // Refuse self-peering. If the invite's did / onion / pubkey matches
+    // our own, adding it pollutes the federation list with a node that
+    // sees itself as its own peer and causes sync loops. The user
+    // almost certainly pasted the wrong invite.
+    if did == local_did || pubkey == local_pubkey || {
+        let a = onion.trim_end_matches(".onion");
+        let b = local_onion.trim_end_matches(".onion");
+        !a.is_empty() && a == b
+    } {
+        anyhow::bail!(
+            "Refusing to federate with self — invite points at this node's own did / onion / pubkey"
+        );
+    }
+
    // Make accept idempotent: drop any existing entry that conflicts with
    // this invite — same DID (same node, refreshing the link), same onion
    // (node rotated identity but kept its hidden service), or same pubkey
@@ -190,6 +205,7 @@ pub async fn accept_invite(
        local_onion,
        local_pubkey,
        local_fips_npub,
+        local_name,
        sign_fn,
    )
    .await;
@@ -201,20 +217,22 @@ pub async fn accept_invite(
 /// Prefers FIPS (if the remote advertised an npub in their invite) and
 /// falls back to Tor. Signs the message with our ed25519 key so the
 /// remote peer can verify authenticity regardless of transport.
-async fn notify_join(
+pub(crate) async fn notify_join(
    remote_onion: &str,
    remote_fips_npub: Option<&str>,
    local_did: &str,
    local_onion: &str,
    local_pubkey: &str,
    local_fips_npub: Option<&str>,
+    local_name: Option<&str>,
    sign_fn: impl FnOnce(&[u8]) -> String,
 ) -> Result<()> {
    // Sign the canonical message: "peer-joined:{did}:{onion}:{pubkey}"
-    // Signature domain intentionally unchanged — fips_npub is carried
-    // as an unsigned informational field. The FIPS daemon's own Noise
-    // handshake authenticates the actual transport session, so a
-    // stripped/substituted npub here merely downgrades the path to Tor.
+    // Signature domain intentionally unchanged — fips_npub + name are
+    // carried as unsigned informational fields. Name is display-only
+    // (any identity claim is anchored on the signed did/pubkey); the
+    // FIPS daemon's own Noise handshake authenticates the transport
+    // session regardless of the advertised npub.
    let sign_data = format!("peer-joined:{}:{}:{}", local_did, local_onion, local_pubkey);
    let signature = sign_fn(sign_data.as_bytes());

@@ -227,6 +245,9 @@ async fn notify_join(
    if let Some(npub) = local_fips_npub {
        params["fips_npub"] = serde_json::Value::String(npub.to_string());
    }
+    if let Some(name) = local_name {
+        params["name"] = serde_json::Value::String(name.to_string());
+    }

    let body = serde_json::json!({
        "method": "federation.peer-joined",
@@ -321,6 +342,7 @@ mod tests {
            "local.onion",
            "localpub",
            None,
+            None,
            |_| "test-sig".to_string(),
        )
        .await
@@ -355,6 +377,7 @@ mod tests {
            "local.onion",
            "localpub",
            None,
+            None,
            |_| "test-sig".to_string(),
        )
        .await
@@ -388,6 +411,7 @@ mod tests {
            "local.onion",
            "localpub",
            None,
+            None,
            |_| "test-sig".to_string(),
        )
        .await
@@ -400,6 +424,7 @@ mod tests {
            "local.onion",
            "localpub",
            None,
+            None,
            |_| "test-sig".to_string(),
        )
        .await
@@ -17,5 +17,5 @@ pub use storage::{
    add_node, fips_npub_for_onion, load_nodes, record_peer_transport, remove_node, save_nodes,
    set_trust_level, update_node,
 };
-pub use sync::{build_local_state, deploy_to_peer, sync_with_peer};
+pub use sync::{build_local_state, deploy_to_peer, sync_with_peer, sync_with_peer_by_did};
 pub use types::{AppStatus, FederatedNode, NodeStateSnapshot, TrustLevel};
@@ -80,8 +80,7 @@ pub async fn record_peer_transport(
    let mut modified = false;
    for node in nodes.iter_mut() {
        let did_match = did.is_some_and(|d| d == node.did);
-        let onion_match = onion_target
-            .is_some_and(|t| node.onion.trim_end_matches(".onion") == t);
+        let onion_match = onion_target.is_some_and(|t| node.onion.trim_end_matches(".onion") == t);
        if did_match || onion_match {
            node.last_transport = Some(transport.to_string());
            node.last_transport_at = Some(now.clone());
@@ -182,9 +181,7 @@ pub async fn update_node_state(data_dir: &Path, did: &str, state: NodeStateSnaps
        // routing over FIPS on the very next sync. Refresh if the peer
        // rotated their FIPS key, too.
        if let Some(ref npub) = state.own_fips_npub {
-            if !npub.is_empty()
-                && node.fips_npub.as_deref().map(str::trim) != Some(npub.trim())
-            {
+            if !npub.is_empty() && node.fips_npub.as_deref().map(str::trim) != Some(npub.trim()) {
                node.fips_npub = Some(npub.clone());
            }
        }
@@ -8,9 +8,7 @@ use anyhow::{Context, Result};
 use std::path::Path;

 use super::storage::update_node_state;
-use super::types::{
-    AppStatus, FederatedNode, FederationPeerHint, NodeStateSnapshot, TrustLevel,
-};
+use super::types::{AppStatus, FederatedNode, FederationPeerHint, NodeStateSnapshot, TrustLevel};
 use crate::fips::dial::PeerRequest;

 /// Sync state with a single federated peer. Tries FIPS first; falls back
@@ -68,9 +66,7 @@ pub async fn sync_with_peer(
    // hop. Only runs when the source is Trusted — Observer-level peers
    // don't get to expand our federation on their own authority.
    if peer.trust_level == TrustLevel::Trusted {
-        if let Err(e) =
-            merge_transitive_peers(data_dir, &peer.did, &state.federated_peers).await
-        {
+        if let Err(e) = merge_transitive_peers(data_dir, &peer.did, &state.federated_peers).await {
            tracing::warn!(
                peer_did = %peer.did,
                error = %e,
@@ -82,9 +78,31 @@ pub async fn sync_with_peer(
    Ok(state)
 }

+/// Convenience wrapper: look up a federated peer by DID, derive our
+/// own local_did / signing context from the node identity on disk, and
+/// call sync_with_peer. Used by transitive-discovery code paths where
+/// the caller only knows the peer's DID (e.g. the peer-joined RPC's
+/// follow-up task).
+pub async fn sync_with_peer_by_did(data_dir: &Path, peer_did: &str) -> Result<NodeStateSnapshot> {
+    let nodes = super::storage::load_nodes(data_dir).await?;
+    let peer = nodes
+        .into_iter()
+        .find(|n| n.did == peer_did)
+        .ok_or_else(|| anyhow::anyhow!("Unknown federation peer: {}", peer_did))?;
+
+    let identity_dir = data_dir.join("identity");
+    let node_identity = crate::identity::NodeIdentity::load_or_create(&identity_dir).await?;
+    let local_pubkey_hex = node_identity.pubkey_hex();
+    let local_did = crate::identity::did_key_from_pubkey_hex(&local_pubkey_hex)?;
+
+    sync_with_peer(data_dir, &peer, &local_did, |data| node_identity.sign(data)).await
+}
+
 /// Merge peers advertised by a Trusted federated node into our own
-/// federation list. New peers are added at `Observer` trust (not
-/// Trusted — that requires a direct invite). Existing peers get their
+/// federation list. New peers are added at `Trusted` — hints only
+/// arrive from peers we already trust, and `build_local_state` only
+/// re-exports our Trusted list, so transitive membership carries the
+/// same trust the direct-invite path gives. Existing peers get their
 /// `fips_npub` refreshed if we hadn't learned it yet.
 ///
 /// Peers we are (us) or that we already track by DID are skipped.
@@ -118,7 +136,7 @@ async fn merge_transitive_peers(
            pubkey: hint.pubkey.clone(),
            onion: hint.onion.clone(),
            name: hint.name.clone(),
-            trust_level: TrustLevel::Observer,
+            trust_level: TrustLevel::Trusted,
            added_at: chrono::Utc::now().to_rfc3339(),
            last_seen: None,
            last_state: None,
@@ -232,7 +250,11 @@ pub async fn deploy_to_peer(
        .context("Failed to reach federated peer for deploy")?;

    if !resp.status().is_success() {
-        anyhow::bail!("Remote node returned HTTP {} (via {})", resp.status(), transport);
+        anyhow::bail!(
+            "Remote node returned HTTP {} (via {})",
+            resp.status(),
+            transport
+        );
    }

    let result: serde_json::Value = resp.json().await.context("Invalid response from peer")?;
@@ -329,10 +351,7 @@ mod tests {
                last_transport_at: None,
            },
        ];
-        let state = build_local_state(
-            vec![],
-            0.0, 0, 0, 0, 0, 0, true, None, None, None, &peers,
-        );
+        let state = build_local_state(vec![], 0.0, 0, 0, 0, 0, 0, true, None, None, None, &peers);
        assert_eq!(state.federated_peers.len(), 1);
        assert_eq!(state.federated_peers[0].did, "did:key:zTrusted");
        assert_eq!(
@@ -0,0 +1,236 @@
+//! Seed-anchor management for FIPS bootstrap.
+//!
+//! A freshly-installed node can't reach the global mesh via npub
+//! routing until it's connected to at least one peer that's already in
+//! the DHT. Upstream `fips` solves this by dialing a public anchor
+//! (e.g. `fips.v0l.io`) on first start. That's a single point of
+//! failure and doesn't help nodes behind restrictive firewalls or
+//! intermittent networks — archipelago operators reported fresh
+//! installs failing to reach any public anchor.
+//!
+//! This module adds a local, operator-editable seed-anchor list. Each
+//! entry is a `{npub, address, transport}` triple that archipelago
+//! pushes into the running daemon via `fipsctl connect` on startup and
+//! periodically thereafter. If one anchor falls over, the next one
+//! seeds the DHT instead. A well-configured cluster (e.g. a VPS
+//! running fips in anchor mode + a couple of home nodes) stops
+//! depending on the global anchor entirely.
+//!
+//! The list is persisted at `<data_dir>/seed-anchors.json`. The
+//! archipelago service user owns that directory, so no sudo is needed
+//! to read or write it.
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+use tokio::process::Command;
+
+/// On-disk filename under `data_dir/`.
+const SEED_ANCHORS_FILE: &str = "seed-anchors.json";
+
+/// Public anchor (`fips.v0l.io`) carried as a default seed for fresh
+/// installs — the one the upstream daemon dials anyway. Operators can
+/// remove it from the UI once their own cluster has independent anchors.
+pub const DEFAULT_PUBLIC_ANCHOR_NPUB: &str =
+    "npub1zv58cn7v83mxvttl70w5fwjwuclfmntv9cnmv5wmz2nzz88u5urqvdx96n";
+pub const DEFAULT_PUBLIC_ANCHOR_ADDR: &str = "fips.v0l.io:8668";
+
+/// One seed-anchor entry. `address` must be directly dialable (IP or
+/// resolvable hostname + UDP port); `transport` is one of "udp", "tcp",
+/// "tor", "ethernet" (the values upstream `fipsctl connect` accepts).
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SeedAnchor {
+    /// Bech32 `npub1...` of the anchor's FIPS identity.
+    pub npub: String,
+    /// Directly-dialable transport address, e.g. `192.168.1.116:8668`.
+    pub address: String,
+    /// Transport to use — almost always `"udp"`.
+    #[serde(default = "default_transport")]
+    pub transport: String,
+    /// Human-readable note shown in the UI (e.g. "Home anchor", "VPS").
+    #[serde(default)]
+    pub label: String,
+}
+
+fn default_transport() -> String {
+    "udp".to_string()
+}
+
+fn anchors_path(data_dir: &Path) -> PathBuf {
+    data_dir.join(SEED_ANCHORS_FILE)
+}
+
+/// Load the seed-anchor list. Returns an empty list if the file
+/// doesn't exist yet — a first-boot node with no operator config.
+pub async fn load(data_dir: &Path) -> Result<Vec<SeedAnchor>> {
+    let path = anchors_path(data_dir);
+    if !path.exists() {
+        return Ok(Vec::new());
+    }
+    let bytes = tokio::fs::read(&path)
+        .await
+        .with_context(|| format!("read {}", path.display()))?;
+    let anchors: Vec<SeedAnchor> =
+        serde_json::from_slice(&bytes).with_context(|| format!("parse {}", path.display()))?;
+    Ok(anchors)
+}
+
+/// Persist the list. Overwrites atomically via write-then-rename so a
+/// crashed archipelago never leaves a half-written config.
+pub async fn save(data_dir: &Path, anchors: &[SeedAnchor]) -> Result<()> {
+    tokio::fs::create_dir_all(data_dir)
+        .await
+        .with_context(|| format!("mkdir -p {}", data_dir.display()))?;
+    let path = anchors_path(data_dir);
+    let tmp = path.with_extension("json.tmp");
+    let json = serde_json::to_vec_pretty(anchors).context("serialize seed anchors")?;
+    tokio::fs::write(&tmp, json)
+        .await
+        .with_context(|| format!("write {}", tmp.display()))?;
+    tokio::fs::rename(&tmp, &path)
+        .await
+        .with_context(|| format!("rename {} -> {}", tmp.display(), path.display()))?;
+    Ok(())
+}
+
+/// Add (or update) one anchor, keyed by npub. Returns the resulting list.
+pub async fn add(data_dir: &Path, anchor: SeedAnchor) -> Result<Vec<SeedAnchor>> {
+    let mut list = load(data_dir).await?;
+    if let Some(existing) = list.iter_mut().find(|a| a.npub == anchor.npub) {
+        *existing = anchor;
+    } else {
+        list.push(anchor);
+    }
+    save(data_dir, &list).await?;
+    Ok(list)
+}
+
+/// Remove an anchor by npub. Returns the resulting list.
+pub async fn remove(data_dir: &Path, npub: &str) -> Result<Vec<SeedAnchor>> {
+    let mut list = load(data_dir).await?;
+    list.retain(|a| a.npub != npub);
+    save(data_dir, &list).await?;
+    Ok(list)
+}
+
+/// Apply the seed anchors to the running FIPS daemon. For each entry,
+/// asks `fipsctl connect` to dial the peer. Errors are logged but don't
+/// fail the whole operation — a single unreachable anchor shouldn't
+/// block the others.
+///
+/// `fipsctl connect` is idempotent-ish: calling it for an already-
+/// connected peer is a no-op at the protocol layer, so re-applying on
+/// a timer is safe. Returns a list of per-anchor results for logging.
+pub async fn apply(anchors: &[SeedAnchor]) -> Vec<ApplyResult> {
+    let mut results = Vec::with_capacity(anchors.len());
+    for anchor in anchors {
+        let out = Command::new("fipsctl")
+            .args(["connect", &anchor.npub, &anchor.address, &anchor.transport])
+            .output()
+            .await;
+        let result = match out {
+            Ok(o) if o.status.success() => ApplyResult {
+                npub: anchor.npub.clone(),
+                ok: true,
+                message: String::from_utf8_lossy(&o.stdout).trim().to_string(),
+            },
+            Ok(o) => ApplyResult {
+                npub: anchor.npub.clone(),
+                ok: false,
+                message: format!(
+                    "fipsctl exited {}: {}",
+                    o.status,
+                    String::from_utf8_lossy(&o.stderr).trim()
+                ),
+            },
+            Err(e) => ApplyResult {
+                npub: anchor.npub.clone(),
+                ok: false,
+                message: format!("fipsctl launch failed: {}", e),
+            },
+        };
+        if result.ok {
+            tracing::debug!(npub = %result.npub, "Seed anchor applied");
+        } else {
+            tracing::warn!(
+                npub = %result.npub,
+                message = %result.message,
+                "Seed anchor apply failed (non-fatal)"
+            );
+        }
+        results.push(result);
+    }
+    results
+}
+
+/// Outcome of a single `fipsctl connect` call.
+#[derive(Debug, Clone)]
+pub struct ApplyResult {
+    pub npub: String,
+    pub ok: bool,
+    pub message: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn mk(npub: &str) -> SeedAnchor {
+        SeedAnchor {
+            npub: npub.to_string(),
+            address: "example.test:8668".to_string(),
+            transport: "udp".to_string(),
+            label: "test".to_string(),
+        }
+    }
+
+    #[tokio::test]
+    async fn load_missing_returns_empty() {
+        let dir = tempfile::tempdir().unwrap();
+        let got = load(dir.path()).await.unwrap();
+        assert!(got.is_empty());
+    }
+
+    #[tokio::test]
+    async fn save_and_load_roundtrip() {
+        let dir = tempfile::tempdir().unwrap();
+        let a = mk("npub1aaa");
+        let b = mk("npub1bbb");
+        save(dir.path(), &[a.clone(), b.clone()]).await.unwrap();
+        let got = load(dir.path()).await.unwrap();
+        assert_eq!(got, vec![a, b]);
+    }
+
+    #[tokio::test]
+    async fn add_replaces_existing_by_npub() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut a = mk("npub1aaa");
+        save(dir.path(), &[a.clone()]).await.unwrap();
+        a.address = "newhost:8668".to_string();
+        let list = add(dir.path(), a.clone()).await.unwrap();
+        assert_eq!(list.len(), 1);
+        assert_eq!(list[0].address, "newhost:8668");
+    }
+
+    #[tokio::test]
+    async fn remove_by_npub() {
+        let dir = tempfile::tempdir().unwrap();
+        save(
+            dir.path(),
+            &[mk("npub1aaa"), mk("npub1bbb"), mk("npub1ccc")],
+        )
+        .await
+        .unwrap();
+        let list = remove(dir.path(), "npub1bbb").await.unwrap();
+        assert_eq!(list.len(), 2);
+        assert!(list.iter().all(|a| a.npub != "npub1bbb"));
+    }
+
+    #[test]
+    fn seed_anchor_uses_udp_by_default() {
+        let json = r#"{"npub":"npub1x","address":"h:8668"}"#;
+        let a: SeedAnchor = serde_json::from_str(json).unwrap();
+        assert_eq!(a.transport, "udp");
+        assert_eq!(a.label, "");
+    }
+}
@@ -13,22 +13,29 @@ use anyhow::{Context, Result};
 use std::path::Path;
 use tokio::process::Command;

-use super::{DAEMON_CONFIG_PATH, DAEMON_KEY_PATH, DAEMON_PUB_PATH, DEFAULT_UDP_PORT};
+use super::{
+    DAEMON_CONFIG_PATH, DAEMON_KEY_PATH, DAEMON_PUB_PATH, DEFAULT_TCP_PORT, DEFAULT_UDP_PORT,
+};

 /// Write the FIPS daemon config based on the local npub and default
 /// transports. Overwrites any existing file — callers are expected to
 /// re-run this whenever the key or daemon version changes.
 ///
 /// Schema is intentionally minimal: node identity comes from the key
-/// file on disk (the daemon handles it), transports enable UDP + Tor,
-/// IPv6 TUN + DNS on defaults. Static peer list is empty — archipelago
-/// feeds peers dynamically via federation updates.
+/// file on disk (the daemon handles it), transports enable UDP + TCP
+/// (matching upstream factory default), IPv6 TUN + DNS on defaults.
+/// Static peer list is empty — archipelago feeds peers dynamically via
+/// the seed-anchors apply loop and federation-invite hooks.
 pub fn render_config_yaml() -> String {
    // Schema matches upstream jmcorgan/fips as of 2026-04. With
    // `node.identity.persistent: true` the daemon reuses the key file at
    // config-dir/fips.key (= DAEMON_KEY_PATH). Transports take `bind_addr`
-    // rather than `enabled: true / port: N`, and the upstream no longer
-    // has a `tor:` transport — archipelago's own Tor fallback handles that.
+    // rather than `enabled: true / port: N`. Both UDP and TCP are
+    // enabled by default because the public anchor (fips.v0l.io)
+    // currently answers on TCP/8443 only, and networks that block UDP
+    // outbound can still bootstrap via TCP. Upstream fips no longer
+    // has a `tor:` transport variant — archipelago's own Tor fallback
+    // handles that layer.
    format!(
        "# Generated by archipelago — do not edit by hand.\n\
         # Regenerated on every key change and daemon upgrade.\n\
@@ -44,9 +51,12 @@ pub fn render_config_yaml() -> String {
         bind_addr: \"127.0.0.1\"\n\
         transports:\n  \
         udp:\n    \
-         bind_addr: \"0.0.0.0:{port}\"\n\
+         bind_addr: \"0.0.0.0:{udp}\"\n  \
+         tcp:\n    \
+         bind_addr: \"0.0.0.0:{tcp}\"\n\
         peers: []\n",
-        port = DEFAULT_UDP_PORT,
+        udp = DEFAULT_UDP_PORT,
+        tcp = DEFAULT_TCP_PORT,
    )
 }

@@ -78,11 +88,65 @@ pub async fn install(identity_dir: &Path) -> Result<()> {
    install_result?;

    sudo_install_file(&src_key, DAEMON_KEY_PATH, "0600").await?;
+    // Heal a legacy fips_key.pub that was written as bech32 npub text
+    // (pre-fix identity::write_fips_key_from_seed did this). Upstream
+    // fips expects 32 raw bytes; a text file silently passes through
+    // and then the daemon can't identify itself to peers. This
+    // rewrites the source file in place with the correct binary form
+    // derived from fips_key before staging it to /etc/fips/fips.pub.
+    normalize_pub_file(&src_key, &src_pub).await?;
    sudo_install_file(&src_pub, DAEMON_PUB_PATH, "0644").await?;

    Ok(())
 }

+/// Ensure `fips_key.pub` is 32 raw bytes. If it's a bech32 npub text
+/// file (from the pre-fix writer), decode it and rewrite in place. If
+/// the file is missing or its content doesn't match either format,
+/// re-derive the public key from `fips_key` and write that.
+pub async fn normalize_pub_file(key_path: &Path, pub_path: &Path) -> Result<()> {
+    // Happy path: already 32 raw bytes.
+    if let Ok(bytes) = tokio::fs::read(pub_path).await {
+        if bytes.len() == 32 {
+            return Ok(());
+        }
+        // bech32 npub text from the pre-fix writer: decode in place.
+        if let Ok(s) = std::str::from_utf8(&bytes) {
+            let trimmed = s.trim();
+            if trimmed.starts_with("npub1") {
+                if let Ok(pk) = nostr_sdk::PublicKey::parse(trimmed) {
+                    let raw: [u8; 32] = pk.to_bytes();
+                    tokio::fs::write(pub_path, raw)
+                        .await
+                        .context("rewriting fips_key.pub as 32 raw bytes")?;
+                    tracing::info!(
+                        "Migrated legacy bech32 fips_key.pub to raw-byte form at {}",
+                        pub_path.display()
+                    );
+                    return Ok(());
+                }
+            }
+        }
+    }
+
+    // Fallback: no pub file, or unreadable format. Re-derive from the
+    // private key file (already validated by load_fips_keys).
+    let secret_bytes = tokio::fs::read(key_path)
+        .await
+        .with_context(|| format!("read {} to derive public", key_path.display()))?;
+    let text = std::str::from_utf8(&secret_bytes)
+        .context("fips_key is not UTF-8 — can't derive public")?;
+    let secret = nostr_sdk::SecretKey::parse(text.trim())
+        .context("fips_key not parseable as bech32 nsec")?;
+    let keys = nostr_sdk::Keys::new(secret);
+    let raw: [u8; 32] = keys.public_key().to_bytes();
+    tokio::fs::write(pub_path, raw)
+        .await
+        .context("writing re-derived fips_key.pub")?;
+    tracing::info!("Re-derived fips_key.pub from fips_key");
+    Ok(())
+}
+
 async fn sudo_install_dir(path: &str) -> Result<()> {
    let out = Command::new("sudo")
        .args(["install", "-d", "-m", "0755", path])
@@ -131,7 +195,9 @@ mod tests {
        let yaml = render_config_yaml();
        assert!(yaml.contains("persistent: true"));
        assert!(yaml.contains(&format!("0.0.0.0:{}", DEFAULT_UDP_PORT)));
+        assert!(yaml.contains(&format!("0.0.0.0:{}", DEFAULT_TCP_PORT)));
        assert!(yaml.contains("udp:"));
+        assert!(yaml.contains("tcp:"));
        assert!(yaml.contains("tun:"));
        assert!(yaml.contains("name: fips0"));
        // Upstream fips dropped the `tor:` transport variant; archipelago
@@ -109,7 +109,7 @@ fn encode_query(id: u16, npub: &str) -> Result<Vec<u8>> {
    encode_label(&mut out, npub)?;
    encode_label(&mut out, FIPS_DNS_SUFFIX)?;
    out.push(0); // root
-    // QTYPE + QCLASS
+                 // QTYPE + QCLASS
    out.extend_from_slice(&QTYPE_AAAA.to_be_bytes());
    out.extend_from_slice(&QCLASS_IN.to_be_bytes());
    Ok(out)
@@ -247,11 +247,7 @@ pub struct PeerRequest<'a> {
 }

 impl<'a> PeerRequest<'a> {
-    pub fn new(
-        fips_npub: Option<&'a str>,
-        onion_host: &'a str,
-        path: &'a str,
-    ) -> Self {
+    pub fn new(fips_npub: Option<&'a str>, onion_host: &'a str, path: &'a str) -> Self {
        Self {
            fips_npub,
            onion_host,
@@ -312,9 +308,7 @@ impl<'a> PeerRequest<'a> {
    }

    /// GET with optional header-based auth.
-    pub async fn send_get(
-        &self,
-    ) -> Result<(reqwest::Response, crate::transport::TransportKind)> {
+    pub async fn send_get(&self) -> Result<(reqwest::Response, crate::transport::TransportKind)> {
        use crate::settings::transport::TransportPref;
        let pref = self.preference().await;
        if matches!(pref, TransportPref::Auto | TransportPref::Fips) {
@@ -392,19 +386,14 @@ impl<'a> PeerRequest<'a> {
        }
    }

-    async fn send_tor_post_json<B: serde::Serialize>(
-        &self,
-        body: &B,
-    ) -> Result<reqwest::Response> {
+    async fn send_tor_post_json<B: serde::Serialize>(&self, body: &B) -> Result<reqwest::Response> {
        let url = self.tor_url();
        let client = self.tor_client()?;
        let mut rb = client.post(&url).json(body);
        for (k, v) in &self.headers {
            rb = rb.header(*k, v);
        }
-        rb.send()
-            .await
-            .with_context(|| format!("Tor POST {}", url))
+        rb.send().await.with_context(|| format!("Tor POST {}", url))
    }

    async fn send_tor_get(&self) -> Result<reqwest::Response> {
@@ -414,9 +403,7 @@ impl<'a> PeerRequest<'a> {
        for (k, v) in &self.headers {
            rb = rb.header(*k, v);
        }
-        rb.send()
-            .await
-            .with_context(|| format!("Tor GET {}", url))
+        rb.send().await.with_context(|| format!("Tor GET {}", url))
    }

    fn tor_url(&self) -> String {
@@ -449,7 +436,7 @@ mod tests {
        assert_eq!(&q[0..2], &[0x12, 0x34]);
        assert_eq!(&q[2..4], &[0x01, 0x00]); // flags RD=1
        assert_eq!(&q[4..6], &[0x00, 0x01]); // QDCOUNT=1
-        // Tail: QTYPE=28, QCLASS=1
+                                             // Tail: QTYPE=28, QCLASS=1
        assert_eq!(&q[q.len() - 4..], &[0x00, 0x1C, 0x00, 0x01]);
    }

@@ -471,7 +458,7 @@ mod tests {
        r.extend_from_slice(&1u16.to_be_bytes()); // ANCOUNT
        r.extend_from_slice(&0u16.to_be_bytes()); // NSCOUNT
        r.extend_from_slice(&0u16.to_be_bytes()); // ARCOUNT
-        // Question: 1 label "a" + "fips"
+                                                  // Question: 1 label "a" + "fips"
        r.extend_from_slice(b"\x01a\x04fips\x00");
        r.extend_from_slice(&QTYPE_AAAA.to_be_bytes());
        r.extend_from_slice(&QCLASS_IN.to_be_bytes());
@@ -24,9 +24,7 @@ pub const FIPS_IFACE: &str = "fips0";
 /// - Link-local (`fe80::/10`) and non-ULA addresses are ignored — we
 ///   only want the mesh-routable ULA that `<npub>.fips` DNS resolves to.
 pub fn fips0_ula() -> Option<Ipv6Addr> {
-    addresses_on(FIPS_IFACE)
-        .into_iter()
-        .find(|a| is_ula(a))
+    addresses_on(FIPS_IFACE).into_iter().find(|a| is_ula(a))
 }

 /// List every IPv6 address bound to a given interface from
@@ -25,6 +25,7 @@
 // the module is deliberately API-ready ahead of those call-sites.
 #![allow(dead_code)]

+pub mod anchors;
 pub mod config;
 pub mod dial;
 pub mod iface;
@@ -52,6 +53,14 @@ pub const UPSTREAM_REPO: &str = "jmcorgan/fips";
 /// Default UDP port the daemon listens on.
 pub const DEFAULT_UDP_PORT: u16 = 8668;

+/// Default TCP port the daemon listens on. Used as a fallback when a
+/// peer can't be reached over UDP — common on networks that block UDP
+/// (corporate/guest wifi) and the path the public fips.v0l.io anchor
+/// currently accepts. Upstream factory default enables both transports
+/// and archipelago intentionally matches that baseline so fresh nodes
+/// can reach the broader FIPS mesh without operator config.
+pub const DEFAULT_TCP_PORT: u16 = 8443;
+
 /// Upstream systemd unit shipped by the `fips` debian package. Archipelago
 /// prefers its own supervision (`archipelago-fips.service`) but respects an
 /// already-running upstream unit so legacy/dev nodes — where no seed-derived
@@ -98,7 +107,13 @@ pub struct FipsStatus {

 impl FipsStatus {
    /// Snapshot the current state across package, key, and service.
-    pub async fn query(identity_dir: &Path) -> Self {
+    ///
+    /// `data_dir` is the archipelago data-dir (used to load the
+    /// operator-configured seed-anchor list so "anchor_connected" means
+    /// "at least one authenticated peer matches a public or configured
+    /// seed anchor", not just "fips.v0l.io specifically").
+    pub async fn query(data_dir: &Path) -> Self {
+        let identity_dir = identity_dir_from(data_dir);
        let installed = service::package_installed().await;
        let version = if installed {
            service::daemon_version().await.ok()
@@ -107,19 +122,25 @@ impl FipsStatus {
        };
        let service_state = service::unit_state(SERVICE_UNIT).await;
        let upstream_service_state = service::unit_state(UPSTREAM_SERVICE_UNIT).await;
-        let service_active =
-            service_state == "active" || upstream_service_state == "active";
-        let key_present = crate::identity::fips_key_exists(identity_dir);
+        let service_active = service_state == "active" || upstream_service_state == "active";
+        let key_present = crate::identity::fips_key_exists(&identity_dir);

        // Prefer the seed-derived npub; otherwise read the daemon's own
        // key file at /etc/fips/fips.pub (world-readable per debian pkg).
-        let npub = match crate::identity::fips_npub(identity_dir).await {
+        let npub = match crate::identity::fips_npub(&identity_dir).await {
            Ok(Some(n)) => Some(n),
            _ => service::read_upstream_npub().await.ok().flatten(),
        };

        let (authenticated_peer_count, anchor_connected) = if service_active {
-            service::peer_connectivity_summary().await
+            // Build the anchor-candidate list: hardcoded public anchor
+            // plus every entry in the operator's seed-anchors.json.
+            // The card lights up if any of them is authenticated.
+            let mut anchor_npubs = vec![service::PUBLIC_ANCHOR_NPUB.to_string()];
+            if let Ok(seed) = anchors::load(data_dir).await {
+                anchor_npubs.extend(seed.into_iter().map(|a| a.npub));
+            }
+            service::peer_connectivity_summary(&anchor_npubs).await
        } else {
            (0, false)
        };
@@ -152,12 +173,16 @@ mod tests {
    #[tokio::test]
    async fn test_status_reports_no_key_pre_onboarding() {
        let dir = tempfile::tempdir().unwrap();
-        let id_dir = dir.path().join("identity");
-        tokio::fs::create_dir_all(&id_dir).await.unwrap();
-
-        let status = FipsStatus::query(&id_dir).await;
+        // query() now takes a data_dir (parent) rather than identity_dir,
+        // since it also reads seed-anchors.json for the anchor check.
+        // No identity/ subdir → no key; no seed-anchors.json → public
+        // anchor is the only candidate.
+        let status = FipsStatus::query(dir.path()).await;
        assert!(!status.key_present, "no key before onboarding");
-        assert!(status.npub.is_none());
+        // `npub` falls back to whatever an already-running local fips
+        // daemon advertises, so on a dev machine or node with fips
+        // installed this field can be Some(...) even when the test
+        // data_dir is empty. We only assert that key_present is false.
        // `installed`, `service_state`, `version` depend on the host and are
        // not asserted here — query() must return cleanly regardless.
    }
@@ -97,6 +97,27 @@ pub async fn restart(unit: &str) -> Result<()> {
    sudo_systemctl("restart", unit).await
 }

+/// Resolve which systemd unit is actually supervising the fips daemon
+/// on this host. Nodes installed from the archipelago ISO run
+/// `archipelago-fips.service`; nodes that were apt-installed (or had
+/// fips running before archipelago took over) may only have the
+/// upstream `fips.service`. Restart/Reconnect must operate on whichever
+/// one is running, otherwise the UI button is a silent no-op.
+///
+/// Returns the archipelago-managed unit name if it's active,
+/// else the upstream unit name if that's active,
+/// else the archipelago-managed name as a default (so activate() can
+/// bring it up).
+pub async fn active_unit() -> &'static str {
+    if unit_state(super::SERVICE_UNIT).await == "active" {
+        return super::SERVICE_UNIT;
+    }
+    if unit_state(super::UPSTREAM_SERVICE_UNIT).await == "active" {
+        return super::UPSTREAM_SERVICE_UNIT;
+    }
+    super::SERVICE_UNIT
+}
+
 pub async fn mask(unit: &str) -> Result<()> {
    let _ = sudo_systemctl("stop", unit).await;
    let _ = sudo_systemctl("disable", unit).await;
@@ -108,12 +129,19 @@ pub async fn mask(unit: &str) -> Result<()> {
 pub const PUBLIC_ANCHOR_NPUB: &str =
    "npub1zv58cn7v83mxvttl70w5fwjwuclfmntv9cnmv5wmz2nzz88u5urqvdx96n";

-/// Summarise peer connectivity from `fipsctl show peers` + `identity-cache`.
-/// Returns `(authenticated_peer_count, anchor_connected)`. Shells out rather
-/// than embedding a fips client because fipsctl is the daemon's own ground
-/// truth — the daemon can always rewrite its internal routing and we'd
-/// rather be consistent with `fipsctl` than snapshot it ourselves.
-pub async fn peer_connectivity_summary() -> (u32, bool) {
+/// Summarise peer connectivity from `fipsctl show peers`. Returns
+/// `(authenticated_peer_count, anchor_connected)`.
+///
+/// `anchor_candidates` is the operator-controlled list of npubs this
+/// node considers a valid mesh anchor — always includes the hard-coded
+/// public anchor, plus any entries from `seed-anchors.json`. A node is
+/// "anchor connected" when at least one currently-authenticated peer
+/// matches one of these npubs. We used to check the identity cache
+/// (which includes transient hearsay from other peers), but a cache
+/// hit on `fips.v0l.io` didn't mean we could actually route through
+/// it, and the card lied to users whose mesh was federated through
+/// their own seed anchors instead.
+pub async fn peer_connectivity_summary(anchor_candidates: &[String]) -> (u32, bool) {
    let peers_json = match Command::new("sudo")
        .args(["-n", "fipsctl", "show", "peers"])
        .output()
@@ -122,39 +150,25 @@ pub async fn peer_connectivity_summary() -> (u32, bool) {
        Ok(o) if o.status.success() => o.stdout,
        _ => return (0, false),
    };
-    let authenticated_peer_count =
-        match serde_json::from_slice::<serde_json::Value>(&peers_json) {
-            Ok(v) => v
-                .get("peers")
-                .and_then(|p| p.as_array())
-                .map(|a| a.len() as u32)
-                .unwrap_or(0),
-            Err(_) => 0,
-        };
-
-    // Anchor check: look in identity-cache (known node pubkeys the daemon
-    // has heard about) rather than authenticated peers — the anchor may be
-    // in the cache but not currently at session depth.
-    let cache_json = match Command::new("sudo")
-        .args(["-n", "fipsctl", "show", "identity-cache"])
-        .output()
-        .await
-    {
-        Ok(o) if o.status.success() => o.stdout,
-        _ => return (authenticated_peer_count, false),
-    };
-    let anchor_connected = match serde_json::from_slice::<serde_json::Value>(&cache_json) {
-        Ok(v) => v
-            .get("entries")
-            .and_then(|e| e.as_array())
-            .map(|entries| {
-                entries
-                    .iter()
-                    .any(|e| e.get("npub").and_then(|n| n.as_str()) == Some(PUBLIC_ANCHOR_NPUB))
-            })
-            .unwrap_or(false),
-        Err(_) => false,
+    let parsed: serde_json::Value = match serde_json::from_slice(&peers_json) {
+        Ok(v) => v,
+        Err(_) => return (0, false),
    };
+    let peers = parsed
+        .get("peers")
+        .and_then(|p| p.as_array())
+        .cloned()
+        .unwrap_or_default();
+    let authenticated_peer_count = peers.len() as u32;
+    let anchor_connected = peers.iter().any(|p| {
+        let npub = p.get("npub").and_then(|n| n.as_str()).unwrap_or_default();
+        let connected = p
+            .get("connectivity")
+            .and_then(|c| c.as_str())
+            .map(|s| s == "connected")
+            .unwrap_or(true);
+        connected && anchor_candidates.iter().any(|a| a == npub)
+    });
    (authenticated_peer_count, anchor_connected)
 }

@@ -219,14 +219,22 @@ async fn write_fips_key_from_seed(
            .await
            .context("Failed to set FIPS key permissions")?;
    }
-    let npub = keys.public_key().to_bech32().unwrap_or_default();
-    fs::write(&pub_path, format!("{npub}\n"))
+    // Upstream fips daemon expects 32 raw bytes in /etc/fips/fips.pub —
+    // not a bech32 npub string. Writing the bech32 form here meant the
+    // installed .pub file was a 63-char text file the daemon parsed as
+    // 63 raw bytes of garbage, so it couldn't identify itself to peers
+    // and the anchor never handshook. Write the raw public-key bytes
+    // (PublicKey::to_bytes returns a [u8; 32]) so the daemon reads
+    // them directly.
+    let raw_pub: [u8; 32] = keys.public_key().to_bytes();
+    fs::write(&pub_path, raw_pub)
        .await
        .context("Failed to write FIPS public key")?;

+    let npub_for_log = keys.public_key().to_bech32().unwrap_or_default();
    tracing::info!(
        "Derived FIPS mesh key from seed (npub: {}...)",
-        npub.chars().take(20).collect::<String>()
+        npub_for_log.chars().take(20).collect::<String>()
    );
    Ok(())
 }
@@ -111,11 +111,7 @@ pub struct ProfilePublishOutcome {
 /// (trailing slash, case). nostr-sdk canonicalises URLs internally and
 /// we compare on the surface strings, so be liberal about what matches.
 fn relay_url_matches(a: &str, b: &str) -> bool {
-    let norm = |s: &str| {
-        s.trim_end_matches('/')
-            .trim()
-            .to_ascii_lowercase()
-    };
+    let norm = |s: &str| s.trim_end_matches('/').trim().to_ascii_lowercase();
    norm(a) == norm(b)
 }

@@ -216,6 +212,80 @@ impl IdentityManager {
        Ok(record)
    }

+    /// Mirror an existing Ed25519 signing key as a manager-level identity.
+    ///
+    /// Used at boot to expose the node's own seed-derived key (the one that
+    /// backs `server_info.pubkey` and peer-to-peer connections) as an
+    /// entry in the Identities page, so all three surfaces — DID Status,
+    /// "Node" entry on Identities, and peer-connect DID — resolve to the
+    /// same DID. The id is deterministic (`node-<pubkey16>`), so repeated
+    /// calls on the same key are idempotent: if the file already exists
+    /// we return the existing record untouched.
+    pub async fn create_from_signing_key(
+        &self,
+        name: String,
+        purpose: IdentityPurpose,
+        signing_key: SigningKey,
+    ) -> Result<IdentityRecord> {
+        let pubkey_hex = hex::encode(signing_key.verifying_key().as_bytes());
+        let did = did_key_from_pubkey_hex(&pubkey_hex)?;
+        let id = format!("node-{}", &pubkey_hex[..16]);
+
+        // Idempotent: if we already mirrored this key, just return it.
+        let file_path = self.identities_dir.join(format!("{}.json", id));
+        if file_path.exists() {
+            return self.get(&id).await;
+        }
+
+        let created_at = chrono::Utc::now().to_rfc3339();
+        // Mark as the node (master) identity so it gets the hex SVG.
+        let default_profile = IdentityProfile {
+            picture: Some(crate::avatar::default_picture(&pubkey_hex, true)),
+            ..Default::default()
+        };
+
+        let identity_file = IdentityFile {
+            id: id.clone(),
+            name: name.clone(),
+            purpose: purpose.clone(),
+            secret_key: signing_key.to_bytes().to_vec(),
+            pubkey_hex: pubkey_hex.clone(),
+            did: did.clone(),
+            created_at,
+            nostr_secret_hex: None,
+            nostr_pubkey_hex: None,
+            profile: Some(default_profile),
+            derivation_index: Some(0),
+        };
+
+        let json =
+            serde_json::to_string_pretty(&identity_file).context("Failed to serialize identity")?;
+        fs::write(&file_path, json.as_bytes())
+            .await
+            .context("Failed to write identity file")?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&file_path, std::fs::Permissions::from_mode(0o600))
+                .await
+                .context("Failed to set identity file permissions")?;
+        }
+
+        // First identity becomes the default.
+        let (existing, _) = self.list().await?;
+        if existing.len() <= 1 {
+            self.set_default(&id).await?;
+        }
+
+        tracing::info!(
+            "Mirrored node signing key as Node identity '{}' ({})",
+            name,
+            purpose
+        );
+
+        self.get(&id).await
+    }
+
    /// Create a new identity with keys derived from a BIP-39 master seed.
    /// The derivation index is auto-incremented and persisted.
    pub async fn create_from_seed(
@@ -627,11 +697,8 @@ impl IdentityManager {
        let event_id = output.id().to_hex();
        // `Output` has `success: HashSet<RelayUrl>` + `failed: HashMap<RelayUrl, String>`.
        // Normalise to string comparisons (RelayUrl trims trailing slashes etc.).
-        let success_strs: std::collections::HashSet<String> = output
-            .success
-            .iter()
-            .map(|u| u.to_string())
-            .collect();
+        let success_strs: std::collections::HashSet<String> =
+            output.success.iter().map(|u| u.to_string()).collect();
        let failed_strs: std::collections::HashMap<String, String> = output
            .failed
            .iter()
@@ -640,14 +707,11 @@ impl IdentityManager {
        let mut accepted: Vec<String> = Vec::new();
        let mut rejected: Vec<(String, String)> = Vec::new();
        for url in relay_urls {
-            let match_url = success_strs
-                .iter()
-                .any(|s| relay_url_matches(s, url));
+            let match_url = success_strs.iter().any(|s| relay_url_matches(s, url));
            if match_url {
                accepted.push(url.clone());
-            } else if let Some((_, reason)) = failed_strs
-                .iter()
-                .find(|(s, _)| relay_url_matches(s, url))
+            } else if let Some((_, reason)) =
+                failed_strs.iter().find(|(s, _)| relay_url_matches(s, url))
            {
                rejected.push((url.clone(), reason.clone()));
            } else {
@@ -811,11 +875,13 @@ mod tests {
    async fn test_create_nostr_key_npub_format() {
        let dir = tempdir().unwrap();
        let mgr = IdentityManager::new(dir.path()).await.unwrap();
+        // `create()` auto-provisions a Nostr key for every identity, so the
+        // returned record should already have a valid bech32 npub.
        let record = mgr
-            .create("Nostr".to_string(), IdentityPurpose::Personal)
+            .create("Personal".to_string(), IdentityPurpose::Personal)
            .await
            .unwrap();
-        let npub = mgr.create_nostr_key(&record.id).await.unwrap();
+        let npub = record.nostr_npub.expect("nostr npub should be populated");
        assert!(
            npub.starts_with("npub1"),
            "npub should start with npub1, got {}",
@@ -19,7 +19,9 @@

 use anyhow::{Context, Result};
 use std::net::SocketAddr;
+use std::sync::Arc;
 use tokio::signal;
+use tokio::sync::Notify;
 use tracing::info;

 mod api;
@@ -28,6 +30,7 @@ mod avatar;
 mod backup;
 mod bitcoin_rpc;
 mod blobs;
+mod bootstrap;
 mod config;
 mod constants;
 mod container;
@@ -68,6 +71,10 @@ mod wallet;
 mod webhooks;

 use config::Config;
+use container::{
+    BootReconciler, ContainerOrchestrator, DevContainerOrchestrator, ProdContainerOrchestrator,
+    RECONCILER_DEFAULT_INTERVAL,
+};
 use server::Server;

 #[tokio::main]
@@ -85,6 +92,33 @@ async fn main() -> Result<()> {

    info!("Starting Archipelago Bitcoin Node OS");

+    // Self-heal web-ui permissions. The OTA updater in <=v1.7.38 left
+    // /opt/archipelago/web-ui as drwx------ (700) after the atomic
+    // swap — nginx (www-data) then returned 500/403 on every request
+    // until someone shelled in and chmod'd it. Check on every boot
+    // and repair if needed so a node auto-recovers after the next
+    // service restart that follows a broken OTA.
+    tokio::spawn(async move {
+        use std::os::unix::fs::PermissionsExt;
+        let web_ui = std::path::Path::new("/opt/archipelago/web-ui");
+        if let Ok(meta) = tokio::fs::metadata(web_ui).await {
+            let mode = meta.permissions().mode() & 0o777;
+            if mode & 0o005 != 0o005 {
+                tracing::warn!("web-ui perms {:o} not world-readable — self-healing", mode);
+                let _ = tokio::process::Command::new("sudo")
+                    .args([
+                        "-n",
+                        "chmod",
+                        "-R",
+                        "u=rwX,go=rX",
+                        "/opt/archipelago/web-ui",
+                    ])
+                    .status()
+                    .await;
+            }
+        }
+    });
+
    // Load configuration
    let config = Config::load().await?;
    info!("📁 Data directory: {}", config.data_dir.display());
@@ -137,15 +171,65 @@ async fn main() -> Result<()> {

            // Signal to health monitor that boot recovery is done
            crash_recovery::mark_recovery_complete();
-
-            // Boot reconciliation disabled — the reconciler creates ALL containers
-            // from specs, which is wrong on unbundled installs where only user-chosen
-            // apps should exist. The health monitor handles restarting existing
-            // containers. Run reconcile-containers.sh manually when needed.
-            // crash_recovery::run_boot_reconciliation().await;
        });
    }

+    // Construct the container orchestrator once. In prod mode we load the
+    // on-disk app manifests, do an initial adoption pass, and spawn the
+    // BootReconciler loop (Step 5/6 of the rust-orchestrator migration).
+    // Dev mode uses the in-memory DevContainerOrchestrator and has no
+    // reconciler (manifests are pushed via RPC, not discovered from disk).
+    let shutdown_notify = Arc::new(Notify::new());
+    let (orchestrator, dev_orchestrator): (
+        Option<Arc<dyn ContainerOrchestrator>>,
+        Option<Arc<DevContainerOrchestrator>>,
+    ) = if config.dev_mode {
+        let dev = Arc::new(DevContainerOrchestrator::new(config.clone()).await?);
+        let trait_obj: Arc<dyn ContainerOrchestrator> = dev.clone();
+        (Some(trait_obj), Some(dev))
+    } else {
+        let prod = Arc::new(ProdContainerOrchestrator::new(config.clone()).await?);
+        // Best-effort manifest load; a missing /opt/archipelago/apps is
+        // logged inside load_manifests and not fatal.
+        match prod.load_manifests().await {
+            Ok(n) => info!("📦 Loaded {n} app manifest(s) from disk"),
+            Err(e) => {
+                tracing::error!(error = %e, "prod orchestrator: load_manifests failed at startup");
+            }
+        }
+        // Adoption pass: link existing podman containers back to their
+        // manifests so the reconciler doesn't recreate them.
+        match prod.adopt_existing().await {
+            Ok(report) => {
+                info!(
+                    "🔗 Adopted {} existing container(s): {:?}",
+                    report.adopted.len(),
+                    report.adopted
+                );
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "prod orchestrator: adopt_existing failed (non-fatal)");
+            }
+        }
+        // Spawn the boot reconciler loop. Runs an initial reconcile
+        // immediately, then re-checks every RECONCILER_DEFAULT_INTERVAL
+        // until shutdown_notify fires.
+        {
+            let reconciler = BootReconciler::new(
+                prod.clone(),
+                RECONCILER_DEFAULT_INTERVAL,
+                shutdown_notify.clone(),
+            );
+            tokio::spawn(reconciler.run_forever());
+            info!(
+                "🔄 Boot reconciler started (interval: {:?})",
+                RECONCILER_DEFAULT_INTERVAL
+            );
+        }
+        let trait_obj: Arc<dyn ContainerOrchestrator> = prod;
+        (Some(trait_obj), None)
+    };
+
    // Ensure a default user exists so login works after install/onboarding.
    // In production, the default password is "password123" (shown during install).
    // In dev mode, the dev default password is used.
@@ -154,7 +238,7 @@ async fn main() -> Result<()> {
    // "Create Password" form instead of login form.

    // Create server
-    let server = Server::new(config.clone()).await?;
+    let server = Server::new(config.clone(), orchestrator, dev_orchestrator).await?;

    // Start server
    let addr: SocketAddr = format!("{}:{}", config.bind_host, config.bind_port)
@@ -165,12 +249,30 @@ async fn main() -> Result<()> {
    // on a 30s poll of fips0 — so a post-onboarding fips.install brings it
    // online without needing an archipelago restart.

+    // Post-OTA verification: if apply_update() wrote a pending-verify
+    // marker right before the restart, probe the frontend now and auto-
+    // rollback if it's broken. This is the guardrail that stops fleet-
+    // wide breakage when an OTA lands a subtly-bad release (v1.7.38/39
+    // tarball-perms → nginx 500 was the trigger). Runs concurrently
+    // with normal startup — doesn't delay the server coming up.
+    {
+        let data_dir = config.data_dir.clone();
+        tokio::spawn(async move {
+            update::verify_pending_update(&data_dir).await;
+        });
+    }
+
    // Spawn background update scheduler
    let update_data_dir = config.data_dir.clone();
    tokio::spawn(async move {
        update::run_update_scheduler(update_data_dir).await;
    });

+    // Synchronize host-side doctor artifacts (script + systemd units) with
+    // what's embedded in this binary. Runs in the background so it never
+    // delays server readiness; best-effort, warnings only.
+    tokio::spawn(bootstrap::ensure_doctor_installed());
+
    // Spawn periodic container snapshot (for crash recovery)
    crash_recovery::spawn_snapshot_task(config.data_dir.clone());

@@ -212,6 +314,7 @@ async fn main() -> Result<()> {
    // Graceful shutdown: wait for SIGTERM or SIGINT
    let mut sigterm = signal::unix::signal(signal::unix::SignalKind::terminate())
        .context("Failed to register SIGTERM handler")?;
+    let shutdown_notify_for_signal = shutdown_notify.clone();
    let shutdown = async move {
        tokio::select! {
            _ = signal::ctrl_c() => {
@@ -221,6 +324,10 @@ async fn main() -> Result<()> {
                info!("Received SIGTERM, initiating graceful shutdown...");
            }
        }
+        // Signal the boot reconciler (and any other subscribers) to stop.
+        // `notify_one` stores a permit if no task is currently parked on
+        // `notified()`, so we don't race the reconciler's reconcile_all pass.
+        shutdown_notify_for_signal.notify_one();
    };

    server.serve_with_shutdown(addr, shutdown).await?;
@@ -229,5 +336,14 @@ async fn main() -> Result<()> {
    crash_recovery::remove_pid_marker(&config.data_dir).await;

    info!("Archipelago shut down cleanly");
-    Ok(())
+
+    // Hard-exit after logging. All business state is persisted by now
+    // (connections drained, PID marker removed, disk flushes done via
+    // tokio::fs awaits). Letting tokio try to drop the runtime instead
+    // can stall for 15s+ on non-daemon OS threads we don't directly
+    // own (mdns_sd daemon, reqwest resolver pool, etc.) — long enough
+    // for systemd's TimeoutStopSec to SIGKILL us and mark the service
+    // Failed, which makes an otherwise-successful update look like a
+    // crash in `systemctl status`.
+    std::process::exit(0);
 }
@@ -457,8 +457,9 @@ mod tests {
        let key = SigningKey::generate(&mut OsRng);
        let wire = build_block_header_announcement(
            890412,
-            "0000000000000000000abc",
-            "0000000000000000000aab",
+            // Block hashes must be 32 bytes (64 hex chars). Use realistic-shaped placeholders.
+            "0000000000000000000abc00000000000000000000000000000000000000abcd",
+            "0000000000000000000aab0000000000000000000000000000000000000aabcd",
            1710633600,
            "did:key:z6MkTest",
            &key,
@@ -469,7 +470,9 @@ mod tests {
        assert_eq!(wire[0], 0x02);
        let envelope = TypedEnvelope::from_wire(&wire).unwrap();
        assert_eq!(envelope.t, MeshMessageType::BlockHeader as u8);
-        assert!(envelope.sig.is_some());
+        // Block header announcements are intentionally unsigned to save 64 bytes
+        // on the 160-byte LoRa payload (see builder comment).
+        assert!(envelope.sig.is_none());
    }

    #[test]
@@ -52,7 +52,10 @@ impl PendingMessage {
            return true; // Can't parse = treat as expired
        };
        let age = chrono::Utc::now().signed_duration_since(created);
-        age.num_seconds() as u64 > self.ttl_secs
+        // Use `>=` so a ttl_secs=0 message is expired immediately (used by
+        // tests and by callers that want a fire-and-forget behavior when
+        // the relay can't deliver on first try).
+        age.num_seconds() as u64 >= self.ttl_secs
    }

    /// Check if this message can be relayed further.
@@ -701,9 +701,11 @@ mod tests {

    #[test]
    fn test_build_app_start() -> Result<()> {
+        // Frame layout: [0: '>'][1-2: len LE][3: CMD][4: VERSION][5..: padded name]
        let frame = build_app_start("Archipelago");
        assert_eq!(frame[3], CMD_APP_START);
-        let name = &frame[4..];
+        assert_eq!(frame[4], PROTOCOL_VERSION);
+        let name = &frame[5..];
        assert_eq!(
            std::str::from_utf8(name)
                .map_err(|e| anyhow::anyhow!("invalid UTF-8 in app name: {}", e))?,
@@ -753,15 +755,20 @@ mod tests {

    #[test]
    fn test_identity_broadcast_roundtrip() -> Result<()> {
-        let did = "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK";
+        // The v2 encoding drops the DID and the decoder reconstructs it
+        // deterministically from the ed25519 pubkey, so the roundtripped
+        // DID won't equal an arbitrary input DID. Derive what the decoder
+        // will produce and assert against that.
        let ed_pub = "a".repeat(64);
        let x25519_pub = "b".repeat(64);
+        let expected_did = crate::identity::did_key_from_pubkey_hex(&ed_pub)
+            .map_err(|e| anyhow::anyhow!("derive did: {}", e))?;

-        let encoded = encode_identity_broadcast(did, &ed_pub, &x25519_pub);
+        let encoded = encode_identity_broadcast(&expected_did, &ed_pub, &x25519_pub);

        let (parsed_did, parsed_ed, parsed_x) = parse_identity_broadcast(&encoded)
            .ok_or_else(|| anyhow::anyhow!("failed to parse identity broadcast"))?;
-        assert_eq!(parsed_did, did);
+        assert_eq!(parsed_did, expected_did);
        assert_eq!(parsed_ed, ed_pub);
        assert_eq!(parsed_x, x25519_pub);
        Ok(())
@@ -267,7 +267,7 @@ async fn sync_single_peer(

        // Best-effort push — don't fail the whole sync if a batch fails.
        match PeerRequest::new(fips_npub, onion, "/dwn")
-        .service(crate::settings::transport::PeerService::Federation)
+            .service(crate::settings::transport::PeerService::Federation)
            .timeout(std::time::Duration::from_secs(30))
            .send_json(&push_body)
            .await
@@ -275,25 +275,24 @@ pub async fn send_to_peer(
        body["from_name"] = serde_json::Value::String(name.to_string());
    }

-    let (resp, transport) = crate::fips::dial::PeerRequest::new(
-        fips_npub,
-        onion,
-        "/archipelago/node-message",
-    )
-    .service(crate::settings::transport::PeerService::Messaging)
-    .timeout(std::time::Duration::from_secs(60))
-    .send_json(&body)
-    .await
-    .map_err(|e| {
-        let msg = e.to_string();
-        if msg.contains("connection refused") || msg.contains("Connection refused") {
-            anyhow::anyhow!("Peer unreachable. Check Tor (127.0.0.1:9050) and FIPS daemon status.")
-        } else if msg.contains("timeout") || msg.contains("timed out") {
-            anyhow::anyhow!("Connection timed out. The peer may be offline.")
-        } else {
-            anyhow::anyhow!("Failed to send: {}", msg)
-        }
-    })?;
+    let (resp, transport) =
+        crate::fips::dial::PeerRequest::new(fips_npub, onion, "/archipelago/node-message")
+            .service(crate::settings::transport::PeerService::Messaging)
+            .timeout(std::time::Duration::from_secs(60))
+            .send_json(&body)
+            .await
+            .map_err(|e| {
+                let msg = e.to_string();
+                if msg.contains("connection refused") || msg.contains("Connection refused") {
+                    anyhow::anyhow!(
+                        "Peer unreachable. Check Tor (127.0.0.1:9050) and FIPS daemon status."
+                    )
+                } else if msg.contains("timeout") || msg.contains("timed out") {
+                    anyhow::anyhow!("Connection timed out. The peer may be offline.")
+                } else {
+                    anyhow::anyhow!("Failed to send: {}", msg)
+                }
+            })?;

    if !resp.status().is_success() {
        anyhow::bail!(
@@ -24,7 +24,7 @@ const RESERVED_PORTS: &[u16] = &[
    9980, 9001, // OnlyOffice, Penpot
    8240, // Tailscale
    9000, // Portainer
-    3001, // Uptime Kuma
+    3001, 3002, // Gitea, Uptime Kuma
    8888, // SearXNG
    8096, 2342, 2283, // Jellyfin, Photoprism, Immich
    8443, 8084, // NPM
@@ -1,6 +1,8 @@
 use crate::api::ApiHandler;
 use crate::config::{Config, ContainerRuntime};
-use crate::container::{docker_packages, DockerPackageScanner};
+use crate::container::{
+    docker_packages, ContainerOrchestrator, DevContainerOrchestrator, DockerPackageScanner,
+};
 use crate::identity::{self, NodeIdentity};
 use crate::monitoring::MetricsStore;
 use crate::node_message;
@@ -14,7 +16,7 @@ use hyper::service::service_fn;
 use std::collections::HashMap;
 use std::net::SocketAddr;
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tokio::net::TcpListener;
 use tracing::{debug, error, info, warn};

@@ -26,7 +28,11 @@ pub struct Server {
 }

 impl Server {
-    pub async fn new(config: Config) -> Result<Self> {
+    pub async fn new(
+        config: Config,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
+    ) -> Result<Self> {
        let state_manager = Arc::new(StateManager::new());

        // Load node identity and set stable server_info.
@@ -89,22 +95,32 @@ impl Server {
        // Load persisted messages (Archipelago channel)
        node_message::init(&config.data_dir).await;

-        // Auto-create default identity if none exist (fresh boot or factory reset)
+        // Auto-create the Node identity on fresh boot, mirroring the node's
+        // own signing key (seed-derived when onboarded, random otherwise).
+        // This keeps the DID shown on the Identities page, the DID Status
+        // card, and the DID used for peer-to-peer connects all aligned on
+        // one value — the seed-derived node DID. Idempotent: if the entry
+        // already exists from a prior boot, create_from_signing_key returns
+        // the existing record unchanged.
        {
            let im = crate::identity_manager::IdentityManager::new(&config.data_dir).await;
            if let Ok(mgr) = im {
                if let Ok((list, _)) = mgr.list().await {
                    if list.is_empty() {
+                        let signing_key = ed25519_dalek::SigningKey::from_bytes(
+                            &identity.signing_key().to_bytes(),
+                        );
                        match mgr
-                            .create(
-                                "Default".to_string(),
+                            .create_from_signing_key(
+                                "Node".to_string(),
                                crate::identity_manager::IdentityPurpose::Personal,
+                                signing_key,
                            )
                            .await
                        {
                            Ok(record) => {
                                let _ = mgr.create_nostr_key(&record.id).await;
-                                tracing::info!(did = %record.did, "Auto-created default identity with Nostr key");
+                                tracing::info!(did = %record.did, "Auto-created Node identity mirroring node key");
                            }
                            Err(e) => tracing::debug!("Auto-identity creation (non-fatal): {}", e),
                        }
@@ -162,8 +178,16 @@ impl Server {
            Some(config.data_dir.clone()),
        );

-        let api_handler =
-            Arc::new(ApiHandler::new(config.clone(), state_manager.clone(), metrics_store).await?);
+        let api_handler = Arc::new(
+            ApiHandler::new(
+                config.clone(),
+                state_manager.clone(),
+                metrics_store,
+                orchestrator,
+                dev_orchestrator,
+            )
+            .await?,
+        );

        // Initialize mesh networking service (if config has enabled: true)
        {
@@ -289,6 +313,8 @@ impl Server {
            let scanner = create_docker_scanner(&config).await?;
            let state = state_manager.clone();
            let identity_clone = identity.clone();
+            let scan_kick = api_handler.rpc_handler().scan_kick();
+            let scan_tick = api_handler.rpc_handler().scan_tick();

            // Initial scan (delayed to let crash recovery finish first)
            tokio::spawn(async move {
@@ -298,18 +324,31 @@ impl Server {
                // Tracks how many consecutive scans each container has been absent from.
                // Prevents UI flapping when podman intermittently returns incomplete results.
                let mut absence_tracker: HashMap<String, u32> = HashMap::new();
+                // Tracks when each container first entered a transitional state
+                // (Stopping / Starting / Restarting / ...). Used by the merge
+                // loop below to ignore podman's live state during a pending
+                // lifecycle op, and to break out if the spawned task dies
+                // without ever writing a final state.
+                let mut transitional_since: HashMap<String, Instant> = HashMap::new();
                if let Err(e) = scan_and_update_packages(
                    &scanner,
                    &state,
                    identity_clone.as_ref(),
                    &mut absence_tracker,
+                    &mut transitional_since,
                )
                .await
                {
                    error!("Failed to scan containers: {}", e);
                }
+                // Bump the scan-completion counter so any caller waiting on a
+                // kicked scan (install/update success path) can proceed.
+                scan_tick.send_modify(|n| *n = n.wrapping_add(1));

-                // Periodic scan every 60 seconds (only broadcasts if state changed)
+                // Periodic scan every 60 seconds (only broadcasts if state changed).
+                // Also wakes immediately when `scan_kick` fires — install/update
+                // success paths poke it so the fresh manifest (with populated
+                // interfaces) lands before they flip state to Running.
                // Uses an in-flight guard to skip scans when a previous one is still running
                let mut interval = tokio::time::interval(Duration::from_secs(60));
                // Skip missed ticks instead of catching up — prevents burst of scans
@@ -317,7 +356,12 @@ impl Server {
                interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
                let scanning = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
                loop {
-                    interval.tick().await;
+                    tokio::select! {
+                        _ = interval.tick() => {}
+                        _ = scan_kick.notified() => {
+                            debug!("Scan kicked by install/update success — running immediately");
+                        }
+                    }
                    if scanning.load(std::sync::atomic::Ordering::Relaxed) {
                        debug!("Skipping container scan — previous scan still in progress");
                        continue;
@@ -328,11 +372,13 @@ impl Server {
                        &state,
                        identity_clone.as_ref(),
                        &mut absence_tracker,
+                        &mut transitional_since,
                    )
                    .await
                    {
                        error!("Failed to update containers: {}", e);
                    }
+                    scan_tick.send_modify(|n| *n = n.wrapping_add(1));
                    scanning.store(false, std::sync::atomic::Ordering::Relaxed);
                }
            });
@@ -353,6 +399,33 @@ impl Server {
            });
        }

+        // FIPS seed-anchor apply loop — every 5 minutes we re-push the
+        // configured seed anchors into the running fips daemon via
+        // `fipsctl connect`. This keeps the mesh bootstrap resilient:
+        // operators add cluster-local anchors in the UI, and a daemon
+        // restart or a flaky public anchor can't strand the node.
+        // First run is delayed 30s so fips has time to come up after
+        // onboarding before we start dialing.
+        {
+            let data_dir = config.data_dir.clone();
+            tokio::spawn(async move {
+                tokio::time::sleep(Duration::from_secs(30)).await;
+                let mut interval = tokio::time::interval(Duration::from_secs(300));
+                loop {
+                    interval.tick().await;
+                    match crate::fips::anchors::load(&data_dir).await {
+                        Ok(list) if !list.is_empty() => {
+                            let _ = crate::fips::anchors::apply(&list).await;
+                        }
+                        Ok(_) => { /* no seed anchors configured yet */ }
+                        Err(e) => {
+                            tracing::debug!("Seed-anchor apply: load failed (non-fatal): {}", e)
+                        }
+                    }
+                }
+            });
+        }
+
        // did:dht auto-refresh — re-publish DHT records every 2 hours
        if config.nostr_discovery_enabled {
            let data_dir = config.data_dir.clone();
@@ -482,10 +555,35 @@ impl Server {
                    tracing::warn!("FIPS key load/migrate failed: {}", e);
                    return;
                }
+                // Check if the installed fips.yaml matches what we'd
+                // render now. If not, we need to restart the daemon after
+                // reinstalling so it picks up schema changes (e.g. the
+                // v1.7.25 re-addition of the TCP transport). Without this,
+                // OTA'd nodes would be stuck on the old UDP-only config
+                // until someone manually clicked Reconnect.
+                let expected = crate::fips::config::render_config_yaml();
+                let installed = tokio::fs::read_to_string("/etc/fips/fips.yaml").await.ok();
+                let config_changed = installed.as_deref() != Some(expected.as_str());
+
                if let Err(e) = crate::fips::config::install(&identity_dir).await {
                    tracing::warn!("FIPS config install failed on startup: {}", e);
                    return;
                }
+                if config_changed {
+                    tracing::info!(
+                        "FIPS config schema changed on disk — restarting daemon to pick up new transports"
+                    );
+                    // Restart whichever unit is actually supervising
+                    // the daemon (archipelago-fips vs upstream fips).
+                    let unit = crate::fips::service::active_unit().await;
+                    if let Err(e) = crate::fips::service::restart(unit).await {
+                        tracing::warn!(
+                            "FIPS restart after config migration failed on {}: {} — user can retry via fips.reconnect",
+                            unit,
+                            e
+                        );
+                    }
+                }
                if let Err(e) = crate::fips::service::activate(crate::fips::SERVICE_UNIT).await {
                    tracing::warn!(
                        "archipelago-fips activate failed on startup: {} — user can retry via fips.install RPC",
@@ -730,11 +828,65 @@ async fn refresh_tor_address(state: &StateManager, identity: &NodeIdentity) -> R
 /// 3 scans × 30s = 90 seconds of absence before removal.
 const CONTAINER_ABSENCE_THRESHOLD: u32 = 3;

+/// Maximum time a package entry may remain stuck in a transitional state
+/// before the scan loop overrides it with podman's live state.
+///
+/// Rationale: the longest single-container stop timeout is bitcoin-core at
+/// 600s. 2× that gives the spawned task ample margin before we assume it
+/// died (panic, OOM, process restart mid-stop) and fall back to the
+/// scanner's authoritative view. Applies to all transitional variants.
+const TRANSITIONAL_STUCK_TIMEOUT: Duration = Duration::from_secs(1200);
+
+/// Returns true if `state` is one of the transitional variants that a
+/// `spawn_transitional`-style background task owns. While such a state is
+/// set, the package scanner must not overwrite it with whatever podman
+/// reports (see `merge_preserving_transitional`).
+fn is_transitional(state: &crate::data_model::PackageState) -> bool {
+    use crate::data_model::PackageState::*;
+    matches!(
+        state,
+        Installing
+            | Stopping
+            | Starting
+            | Restarting
+            | Updating
+            | Removing
+            | CreatingBackup
+            | RestoringBackup
+            | BackingUp
+    )
+}
+
+/// Merge a fresh scan entry `fresh` into `existing` while preserving
+/// `existing.state` (which is transitional — the RPC spawn task owns it).
+/// Non-state observability fields are taken from `fresh` so the UI still
+/// sees live health / exit_code / lan_address readings during a transition.
+fn merge_preserving_transitional(
+    existing: &crate::data_model::PackageDataEntry,
+    fresh: &crate::data_model::PackageDataEntry,
+) -> crate::data_model::PackageDataEntry {
+    crate::data_model::PackageDataEntry {
+        state: existing.state.clone(),
+        // install_progress and uninstall_stage are also owned by the
+        // initiating op (same reason as state) — keep them.
+        install_progress: existing.install_progress.clone(),
+        uninstall_stage: existing.uninstall_stage.clone(),
+        // Everything else comes from the fresh scan.
+        health: fresh.health.clone(),
+        exit_code: fresh.exit_code,
+        static_files: fresh.static_files.clone(),
+        manifest: fresh.manifest.clone(),
+        installed: fresh.installed.clone(),
+        available_update: fresh.available_update.clone(),
+    }
+}
+
 async fn scan_and_update_packages(
    scanner: &DockerPackageScanner,
    state: &StateManager,
    identity: &NodeIdentity,
    absence_tracker: &mut HashMap<String, u32>,
+    transitional_since: &mut HashMap<String, Instant>,
 ) -> Result<()> {
    let packages = scanner.scan_containers().await?;

@@ -768,10 +920,61 @@ async fn scan_and_update_packages(
    let mut merged = current_data.package_data.clone();
    let mut changed = false;

-    // Update/add containers found in this scan
+    // Update/add containers found in this scan.
+    //
+    // Transitional states (Stopping, Starting, Restarting, Installing,
+    // Updating, Removing, backup variants) are owned by the RPC spawn_task
+    // that initiated the operation — podman's live state during the op is
+    // meaningless ("running" during a graceful stop, "exited" during a
+    // restart, etc.) and must not be written back. See
+    // `merge_preserving_transitional` for the exact rule.
+    //
+    // Escape hatch: if a package has been in a transitional state for
+    // longer than TRANSITIONAL_STUCK_TIMEOUT we assume the spawned task
+    // died without cleanup and let the scan override it.
+    let now = Instant::now();
    for (id, pkg) in &packages {
        absence_tracker.remove(id);
-        if merged.get(id) != Some(pkg) {
+        let existing = merged.get(id);
+        let overwrite = match existing {
+            Some(existing_entry) if is_transitional(&existing_entry.state) => {
+                let entered = *transitional_since.entry(id.clone()).or_insert(now);
+                let stuck = now.duration_since(entered) > TRANSITIONAL_STUCK_TIMEOUT;
+                if stuck {
+                    warn!(
+                        "Container {} stuck in {:?} for >{}s; overriding with scan state {:?}",
+                        id,
+                        existing_entry.state,
+                        TRANSITIONAL_STUCK_TIMEOUT.as_secs(),
+                        pkg.state
+                    );
+                    transitional_since.remove(id);
+                    true
+                } else {
+                    // Keep existing transitional state, but merge non-state
+                    // observability fields (health, exit_code, lan_address
+                    // via installed) from the fresh scan so the UI still
+                    // sees live readings.
+                    let merged_entry = merge_preserving_transitional(existing_entry, pkg);
+                    if existing.cloned() != Some(merged_entry.clone()) {
+                        merged.insert(id.clone(), merged_entry);
+                        changed = true;
+                    }
+                    false
+                }
+            }
+            Some(_) => {
+                // Not transitional: the side-table may hold a stale entry
+                // from a previous transition on this id; drop it.
+                transitional_since.remove(id);
+                existing != Some(pkg)
+            }
+            None => {
+                transitional_since.remove(id);
+                true
+            }
+        };
+        if overwrite && merged.get(id) != Some(pkg) {
            merged.insert(id.clone(), pkg.clone());
            changed = true;
        }
@@ -782,6 +985,17 @@ async fn scan_and_update_packages(
    let current_ids: Vec<String> = merged.keys().cloned().collect();
    for id in current_ids {
        if !packages.contains_key(&id) {
+            // Don't evict packages mid-transition: Installing/Updating/Removing
+            // legitimately have no live container yet (image still pulling) or
+            // briefly (during recreate). The absence-eviction here was racing
+            // installs and removing apps from the UI 14s in. The transitional
+            // owner (spawn_task) is responsible for clearing state, not us.
+            if let Some(entry) = merged.get(&id) {
+                if is_transitional(&entry.state) {
+                    absence_tracker.remove(&id);
+                    continue;
+                }
+            }
            let count = absence_tracker.entry(id.clone()).or_insert(0);
            *count += 1;
            if *count >= CONTAINER_ABSENCE_THRESHOLD {
@@ -791,6 +1005,7 @@ async fn scan_and_update_packages(
                );
                merged.remove(&id);
                absence_tracker.remove(&id);
+                transitional_since.remove(&id);
                changed = true;
            }
        }
@@ -861,10 +1076,9 @@ async fn check_peer_health(state: &StateManager, data_dir: &std::path::Path) ->
    let mut new_health = std::collections::HashMap::new();
    for peer in &known_peers {
        let fips_npub = crate::federation::fips_npub_for_onion(data_dir, &peer.onion).await;
-        let reachable =
-            node_message::check_peer_reachable(&peer.onion, fips_npub.as_deref())
-                .await
-                .unwrap_or(false);
+        let reachable = node_message::check_peer_reachable(&peer.onion, fips_npub.as_deref())
+            .await
+            .unwrap_or(false);
        new_health.insert(peer.onion.clone(), reachable);
    }

@@ -878,3 +1092,106 @@ async fn check_peer_health(state: &StateManager, data_dir: &std::path::Path) ->

    Ok(())
 }
+
+#[cfg(test)]
+mod merge_tests {
+    use super::*;
+    use crate::data_model::{Description, Manifest, PackageDataEntry, PackageState, StaticFiles};
+
+    fn make_manifest() -> Manifest {
+        Manifest {
+            id: "lnd".to_string(),
+            title: "LND".to_string(),
+            version: "0.18.4".to_string(),
+            description: Description {
+                short: "".to_string(),
+                long: "".to_string(),
+            },
+            release_notes: "".to_string(),
+            license: "".to_string(),
+            wrapper_repo: "".to_string(),
+            upstream_repo: "".to_string(),
+            support_site: "".to_string(),
+            marketing_site: "".to_string(),
+            donation_url: None,
+            author: None,
+            website: None,
+            interfaces: None,
+            tier: None,
+        }
+    }
+
+    fn make_static() -> StaticFiles {
+        StaticFiles {
+            license: "".to_string(),
+            instructions: "".to_string(),
+            icon: "".to_string(),
+        }
+    }
+
+    fn make_entry(state: PackageState, health: Option<&str>) -> PackageDataEntry {
+        PackageDataEntry {
+            state,
+            health: health.map(|s| s.to_string()),
+            exit_code: None,
+            static_files: make_static(),
+            manifest: make_manifest(),
+            installed: None,
+            install_progress: None,
+            uninstall_stage: None,
+            available_update: None,
+        }
+    }
+
+    #[test]
+    fn preserves_transitional_state_on_merge() {
+        // existing: user initiated a stop, spawn_transitional set Stopping.
+        // fresh: podman hasn't finished the stop yet, still reports Running.
+        // Expected: merged state stays Stopping — podman's live view must
+        // not clobber the transitional state owned by the RPC spawn task.
+        let existing = make_entry(PackageState::Stopping, Some("healthy"));
+        let fresh = make_entry(PackageState::Running, Some("starting"));
+        let merged = merge_preserving_transitional(&existing, &fresh);
+        assert_eq!(merged.state, PackageState::Stopping);
+    }
+
+    #[test]
+    fn merges_fresh_observability_fields() {
+        // Non-state observability fields (health, exit_code, installed)
+        // MUST come from the fresh scan even while state is preserved —
+        // the UI still shows live health/health during a transition.
+        let mut existing = make_entry(PackageState::Stopping, Some("healthy"));
+        existing.exit_code = None;
+        let mut fresh = make_entry(PackageState::Running, Some("unhealthy"));
+        fresh.exit_code = Some(0);
+        let merged = merge_preserving_transitional(&existing, &fresh);
+        assert_eq!(merged.state, PackageState::Stopping);
+        assert_eq!(merged.health.as_deref(), Some("unhealthy"));
+        assert_eq!(merged.exit_code, Some(0));
+    }
+
+    #[test]
+    fn is_transitional_covers_all_variants() {
+        for s in [
+            PackageState::Installing,
+            PackageState::Stopping,
+            PackageState::Starting,
+            PackageState::Restarting,
+            PackageState::Updating,
+            PackageState::Removing,
+            PackageState::CreatingBackup,
+            PackageState::RestoringBackup,
+            PackageState::BackingUp,
+        ] {
+            assert!(is_transitional(&s), "{:?} should be transitional", s);
+        }
+        for s in [
+            PackageState::Installed,
+            PackageState::Stopped,
+            PackageState::Exited,
+            PackageState::Running,
+        ] {
+            assert!(!is_transitional(&s), "{:?} should NOT be transitional", s);
+        }
+    }
+}
@@ -70,6 +70,17 @@ impl SessionStore {
        }
    }

+    /// Construct an empty SessionStore that persists to a caller-supplied
+    /// path. Used by tests so they don't pick up sessions from the dev
+    /// machine's real /var/lib/archipelago/sessions.json.
+    #[cfg(test)]
+    pub fn new_for_tests(persist_path: PathBuf) -> Self {
+        Self {
+            sessions: Arc::new(RwLock::new(HashMap::new())),
+            persist_path,
+        }
+    }
+
    /// Load persisted sessions from disk (only Full sessions).
    async fn load_from_disk(path: &Path) -> HashMap<[u8; 32], Session> {
        let mut map = HashMap::new();
@@ -462,7 +473,10 @@ mod tests {

    #[tokio::test]
    async fn test_session_create_and_validate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -470,13 +484,19 @@ mod tests {

    #[tokio::test]
    async fn test_session_invalid_token() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        assert!(!store.validate("nonexistent_token").await);
    }

    #[tokio::test]
    async fn test_session_remove() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -486,7 +506,10 @@ mod tests {

    #[tokio::test]
    async fn test_pending_session_upgrade() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let secret = vec![1, 2, 3, 4];
        let token = store.create_pending(secret.clone()).await;

@@ -510,7 +533,10 @@ mod tests {

    #[tokio::test]
    async fn test_pending_session_max_attempts() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let secret = vec![1, 2, 3];
        let token = store.create_pending(secret).await;

@@ -538,7 +564,10 @@ mod tests {

    #[tokio::test]
    async fn test_session_activity_updates_on_validate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token = store.create().await;

        // First validation should succeed and touch last_activity
@@ -550,7 +579,10 @@ mod tests {

    #[tokio::test]
    async fn test_invalidate_all_except() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token1 = store.create().await;
        let token2 = store.create().await;
        let token3 = store.create().await;
@@ -565,7 +597,10 @@ mod tests {

    #[tokio::test]
    async fn test_session_rotate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let old_token = store.create().await;

        assert!(store.validate(&old_token).await);
@@ -580,7 +615,10 @@ mod tests {

    #[tokio::test]
    async fn test_max_concurrent_sessions() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let mut tokens = Vec::new();

        // Create MAX_CONCURRENT_SESSIONS sessions
@@ -608,7 +646,10 @@ mod tests {

    #[tokio::test]
    async fn test_active_session_count() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        assert_eq!(store.active_session_count().await, 0);

        let token1 = store.create().await;
@@ -623,7 +664,10 @@ mod tests {

    #[tokio::test]
    async fn test_cleanup_expired_removes_stale() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -636,7 +680,10 @@ mod tests {

    #[tokio::test]
    async fn test_rotate_preserves_session_count() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!(
+            "archipelago-sessions-test-{}.json",
+            rand::random::<u64>()
+        )));
        let token = store.create().await;
        assert_eq!(store.active_session_count().await, 1);

@@ -141,11 +141,7 @@ pub async fn snapshot() -> TransportPreferences {
 /// Update a single service preference, persist to disk, and update the
 /// handle. Callers must pass `data_dir` because the on-disk file lives
 /// under it — the handle alone doesn't know where to write.
-pub async fn set(
-    data_dir: &Path,
-    service: PeerService,
-    pref: TransportPref,
-) -> Result<()> {
+pub async fn set(data_dir: &Path, service: PeerService, pref: TransportPref) -> Result<()> {
    let new_prefs = {
        let lock = HANDLE.get_or_init(|| RwLock::new(TransportPreferences::default()));
        let mut w = lock.write().await;
@@ -173,8 +169,7 @@ async fn save_to_disk(data_dir: &Path, prefs: &TransportPreferences) -> Result<(
            .await
            .with_context(|| format!("create {}", parent.display()))?;
    }
-    let body = serde_json::to_string_pretty(prefs)
-        .context("serialize TransportPreferences")?;
+    let body = serde_json::to_string_pretty(prefs).context("serialize TransportPreferences")?;
    tokio::fs::write(&path, body)
        .await
        .with_context(|| format!("write {}", path.display()))?;
@@ -213,10 +208,7 @@ mod tests {
        p.set_for_service(PeerService::Messaging, TransportPref::Tor);
        let s = serde_json::to_string(&p).unwrap();
        let back: TransportPreferences = serde_json::from_str(&s).unwrap();
-        assert_eq!(
-            back.for_service(PeerService::Messaging),
-            TransportPref::Tor
-        );
+        assert_eq!(back.for_service(PeerService::Messaging), TransportPref::Tor);
    }

    #[test]
@@ -98,7 +98,12 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
    }

    let shard_size = MAX_CHUNK_PAYLOAD;
-    let data_shard_count = data.len().div_ceil(shard_size);
+    // Reserve the first 4 bytes of shard 0 for a length header so the
+    // receiver can trim padding after FEC reconstruction. Effective
+    // payload capacity is therefore (shards * shard_size) - 4.
+    const LEN_HEADER: usize = 4;
+    let total_payload = data.len() + LEN_HEADER;
+    let data_shard_count = total_payload.div_ceil(shard_size);

    if data_shard_count > MAX_PRACTICAL_CHUNKS {
        anyhow::bail!(
@@ -116,22 +121,25 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
        anyhow::bail!("Too many shards: {}", total_shards);
    }

-    // Split data into equal-size shards
+    // Build a single contiguous buffer: [len_u32_le][data...][zero_padding]
+    // then split into equal-size shards.
+    let buffer_size = data_shard_count * shard_size;
+    let mut buffer = vec![0u8; buffer_size];
+    buffer[..LEN_HEADER].copy_from_slice(&(data.len() as u32).to_le_bytes());
+    buffer[LEN_HEADER..LEN_HEADER + data.len()].copy_from_slice(data);
+
    let mut shards: Vec<Vec<u8>> = Vec::with_capacity(total_shards);
    for i in 0..data_shard_count {
        let start = i * shard_size;
-        let end = (start + shard_size).min(data.len());
-        let mut shard = vec![0u8; shard_size];
-        shard[..end - start].copy_from_slice(&data[start..end]);
-        shards.push(shard);
+        shards.push(buffer[start..start + shard_size].to_vec());
    }
-
-    // Add empty parity shards
+    // Empty parity shards
    for _ in 0..parity_shard_count {
        shards.push(vec![0u8; shard_size]);
    }

-    // Generate parity
+    // Generate parity over the data shards (which now correctly include
+    // the length header in shard 0).
    let rs = ReedSolomon::new(data_shard_count, parity_shard_count)
        .context("Failed to create Reed-Solomon codec")?;
    rs.encode(&mut shards)
@@ -152,18 +160,6 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
        });
    }

-    // Encode the original data length in the first chunk's first 4 bytes
-    // so the receiver can trim padding after reconstruction.
-    let data_len = data.len() as u32;
-    chunks[0].payload[..4].copy_from_slice(&data_len.to_le_bytes());
-    // Re-encode FEC to reflect the length header change
-    let mut shard_data: Vec<Vec<u8>> = chunks.iter().map(|c| c.payload.clone()).collect();
-    rs.encode(&mut shard_data)
-        .context("Reed-Solomon re-encoding failed")?;
-    for (i, shard) in shard_data.into_iter().enumerate() {
-        chunks[i].payload = shard;
-    }
-
    Ok(chunks)
 }

@@ -318,17 +314,13 @@ mod tests {

    #[test]
    fn test_chunk_roundtrip_medium() {
-        // ~500 bytes: 4 data chunks + 1 parity
+        // 500 bytes payload + 4-byte length header = 504 bytes.
+        // ceil(504 / 124) = 5 data shards, plus ceil(5/4) = 2 parity = 7 total.
        let data: Vec<u8> = (0..500).map(|i| (i % 256) as u8).collect();
        let chunks = encode_chunked(&data).unwrap();

        let data_chunks: Vec<_> = chunks.iter().filter(|c| !c.is_parity).collect();
-        let _parity_chunks: Vec<_> = chunks.iter().filter(|c| c.is_parity).collect();
-        assert_eq!(data_chunks.len(), 4); // ceil(500/124) = 5... wait
-                                          // Actually: ceil(500/124) = ceil(4.03) = 5 data shards
-                                          // But the first shard has 4 bytes of length header embedded, so
-                                          // the actual data capacity is 124 * N - 0 (length is IN the shard data).
-                                          // Let's just check it roundtrips.
+        assert_eq!(data_chunks.len(), 5);

        let mut reassembler = ChunkReassembler::new();
        let mut result = None;
@@ -160,6 +160,18 @@ impl LanTransport {
    }
 }

+impl Drop for LanTransport {
+    // The mdns_sd daemon runs on its own OS thread and the browse
+    // listener task blocks on a sync channel. Without this call both
+    // keep the process alive past SIGTERM, long enough for systemd to
+    // SIGKILL us — which makes a normal update look like a crash.
+    fn drop(&mut self) {
+        if let Some(daemon) = self.daemon.take() {
+            let _ = daemon.shutdown();
+        }
+    }
+}
+
 impl NodeTransport for LanTransport {
    fn kind(&self) -> TransportKind {
        TransportKind::Lan
@@ -334,7 +334,9 @@ mod tests {
            amount: 1,
            id: "test".into(),
            secret: "s".into(),
-            c: "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d94ec4da0e7f6c2b4e24".to_string(),
+            // Generator point G of secp256k1, compressed form. Always a
+            // valid pubkey, so c_as_pubkey() must succeed.
+            c: "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798".to_string(),
        };
        assert!(proof.c_as_pubkey().is_ok());
    }
--- a/Show More
+++ b/Show More