chore: prepare 1.8.22-alpha release candidate

fix: probe Angor IPv4 health endpoint inside the actual image
fix: prevent NPM tunnel collisions and false app health restarts
2026-09-30 16:45:43 -04:00 · 2026-09-30 16:40:16 -04:00 · 2026-09-30 16:30:40 -04:00 · 2026-09-30 16:12:04 -04:00 · 2026-09-30 13:46:50 -04:00 · 2026-09-30 13:46:16 -04:00
67 changed files with 4437 additions and 570 deletions
@@ -1,6 +1,28 @@
 # Changelog

-## Unreleased
+## v1.8.22-alpha (2026-09-30)
+
+- Fixed Angor Indexer health checks choosing IPv6 localhost for an IPv4 listener and unnecessarily restarting the working service.
+
+- Prevented false app restarts by probing each published port at its actual bind address; Nginx Proxy Manager now checks its internal admin API.
+- Added a backed-up migration for the recognized legacy Nginx Proxy Manager tunnel/LND port conflict in both OTA and ISO startup paths.
+
+- Checked Bitcoin and Electrum companion dashboards instead of backend protocol ports, preserving dashboard access during initial sync.
+- Removed web-interface waiting messages from headless services such as Phoenixd and clarified which interface is unavailable for launchable apps.
+
+- Finished runtime app-file promotion before manifest loading, preventing startup catalog refresh from forgetting disk-only apps.
+
+- Named the app in compact readiness messages and kept app-card actions aligned at the bottom.
+- Removed duplicate Mempool cards caused by frontend container aliases in restored inventory.
+
+- Kept installed apps visible through restarts and hard refreshes, and delayed app launches until their web interface is ready.
+- Made Bitcoin version selection readable and usable in the ThinkPad kiosk, above the pruning settings.
+- Restored GitWorkshop build files in installation/update payloads and made slow image-pull progress clearer.
+- Fixed same-node Gitea access from Portainer, with persistent runtime migration, state backups and recovery after failed restarts.
+- Preserved Gitea configuration and SSH operation during fresh setup and upgrades.
+- Improved paid-file delivery, saved-file permissions and repeat-download compatibility; verified Tor-only payment with change, rejection refunds and free repeat downloads.
+- Added a headless Angor Indexer service using the existing Mempool/ElectrumX stack, and an optional separate Angor relay.
+- Prevented manifest command arguments containing apostrophes from being corrupted in generated services.

 ## v1.8.21-alpha (2026-09-30)

@@ -644,6 +644,35 @@
          "/var/lib/archipelago/vaultwarden:/data"
        ]
      }
+    },
+    {
+      "id": "angor-indexer",
+      "title": "Angor Indexer",
+      "version": "1.0.1",
+      "description": "Headless Bitcoin indexer endpoint for Angor. Reuses this node’s Mempool and Electrum index; requires a synced, unpruned Bitcoin node. Add this service’s address as the custom indexer in Angor settings. A relay is optional and installed separately.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-indexer:1.0.1",
+      "author": "Angor / Archipelago",
+      "requires": [
+        "Mempool API",
+        "Unpruned Bitcoin"
+      ],
+      "category": "money",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/block-core/angor"
+    },
+    {
+      "id": "angor-relay",
+      "title": "Angor Relay",
+      "version": "1.1.2",
+      "description": "Optional dedicated Nostr relay for Angor project metadata. Separate storage and access settings keep the node’s internal relay private. Add this service’s address to Angor’s relay settings; use WSS for browser clients.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-relay:1.1.2",
+      "author": "Angor / Archipelago",
+      "requires": [],
+      "category": "nostr",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/hoytech/strfry"
    }
  ]
 }
@@ -0,0 +1,57 @@
+# Angor Indexer
+
+Headless mainnet API endpoint for Angor. The service reuses this node's Mempool
+backend and Electrum index instead of creating a second blockchain database.
+An unpruned, fully synced Bitcoin node is required. Installing against a pruned
+node must show the existing archival-node requirement; it must never silently
+unprune or replace its Bitcoin data.
+
+## Connect Angor
+
+Install **Angor Indexer** in the store. Its API appears under **Services**.
+In Angor settings, use `http://<node-address>:8998/` as the custom indexer origin.
+The `/health` endpoint reports readiness against Mempool's indexed block height;
+it returns 503 while that backend is unavailable. Index building may take time.
+
+Browser clients require a reachable HTTPS origin with a trusted certificate.
+Configure your HTTPS reverse proxy to forward to port 8998, then use that HTTPS
+origin in Angor. Do not disable browser TLS checks. The API supports both
+`/api/v1/` and `/api/` paths, transaction broadcast, and CORS without cookies.
+
+This endpoint intentionally exposes public blockchain queries and transaction
+broadcast through the app gate without dashboard-cookie login. It has no Bitcoin
+RPC password, wallet keys, or persistent wallet data. The backend stays on the
+managed container network; its private port does not become publicly exposed.
+You can change network access using the node's normal access controls.
+
+## Relay
+
+A relay is optional. Angor can continue using its configured external relays.
+Install **Angor Relay** separately to host project metadata locally, then add
+`ws://<node-address>:8091/` in Angor, or a trusted `wss://` proxy origin for browser
+clients. Its storage and configuration are separate from the node's internal
+relay; installing or uninstalling it does not change the internal relay.
+
+## Packaging
+
+Build the pinned image with:
+
+```
+podman build -t source.archipelago-foundation.org/chaum/angor-indexer:1.0.1 apps/angor-indexer/container
+```
+
+The image runs as UID 101 with a read-only root filesystem and no capabilities.
+Only temporary nginx state is writable. Runtime DNS is read from resolv.conf so
+Mempool recreation does not require editing IP addresses or restarting this app.
+No app-specific Rust installer is required.
+
+Source documentation: [Angor's official deployment guide](https://github.com/block-core/angor/blob/869dd43cf38332dd7128a284a6bf4c1cac44c1a7/docker/DEPLOY-INDEXER-AND-RELAY.md).
+The app icon is based on [Angor’s dark-mode app icon](https://angor.io/images/app-icon-dark-mode.png), retrieved 2026-09-30. At the operator’s request, the outer corners use the same green as the background. The built-in imagegen edit preserved the black mark and filled the square green; the project asset is `neode-ui/public/assets/img/app-icons/angor-green.png`.
+
+Tests and release acceptance are recorded in the next-release checklist. The
+health probe establishes backend availability, not a guarantee that every
+address query is indexed at the latest Bitcoin tip.
+
+Install Mempool Explorer first. The declarative `install_prerequisites` check
+refuses a new adapter installation if its Mempool API component is absent, before
+creating an installed-app record. It does not install or resync Bitcoin for you.
@@ -0,0 +1,6 @@
+FROM docker.io/library/nginx:1.31.3-alpine@sha256:1d40e3eb3bf4f138de1d67193f2aa5309fcaf343eb5ffadbf5e9439de1eb1ebb
+COPY nginx.conf /etc/angor-nginx.conf.template
+COPY entrypoint.sh /usr/local/bin/angor-indexer
+USER 101:101
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/angor-indexer"]
@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+# Resolve through the container runtime's DNS, including after dependency
+# recreation. Never bake a container IP into the indexer endpoint.
+DNS_RESOLVER=$(awk '/^nameserver[[:space:]]/ {print $2; exit}' /etc/resolv.conf)
+case "$DNS_RESOLVER" in
+  ''|*[!0-9a-fA-F.:]*) echo 'Container DNS resolver is unavailable' >&2; exit 1 ;;
+esac
+case "$DNS_RESOLVER" in *:*) DNS_RESOLVER="[$DNS_RESOLVER]" ;; esac
+export DNS_RESOLVER
+envsubst '${DNS_RESOLVER}' < /etc/angor-nginx.conf.template > /tmp/nginx.conf
+exec nginx -c /tmp/nginx.conf -g 'daemon off;'
@@ -0,0 +1,63 @@
+worker_processes 1;
+pid /tmp/nginx.pid;
+error_log /dev/stderr warn;
+events { worker_connections 512; }
+http {
+    access_log off;
+    server_tokens off;
+    client_body_temp_path /tmp/client_temp;
+    proxy_temp_path /tmp/proxy_temp;
+    fastcgi_temp_path /tmp/fastcgi_temp;
+    uwsgi_temp_path /tmp/uwsgi_temp;
+    scgi_temp_path /tmp/scgi_temp;
+    resolver ${DNS_RESOLVER} valid=10s ipv6=off;
+    upstream mempool_backend {
+        zone mempool_backend 64k;
+        server mempool-api:8999 resolve;
+    }
+    server {
+        listen 8080;
+        client_max_body_size 4m;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 30s;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header Connection "";
+        proxy_set_header Authorization "";
+        proxy_set_header Cookie "";
+        proxy_hide_header Access-Control-Allow-Origin;
+        add_header Access-Control-Allow-Origin '*' always;
+        add_header Access-Control-Allow-Methods 'GET, HEAD, POST, OPTIONS' always;
+        add_header Access-Control-Allow-Headers 'Content-Type' always;
+        add_header Cache-Control 'no-store' always;
+        if ($request_method = OPTIONS) { return 204; }
+        # Mempool's backend uses /api/v1. Match its frontend's shorter /api
+        # surface too, without doubling already-versioned Angor URLs.
+        rewrite ^/api/(?!v1/)(.*)$ /api/v1/$1 last;
+        location = / {
+            default_type application/json;
+            return 200 '{"service":"Angor Indexer","network":"mainnet","api":"/api/v1","health":"/health"}\n';
+        }
+        # Readiness checks the indexing backend, not this gateway's process.
+        location = /health {
+            limit_except GET { deny all; }
+            proxy_pass http://mempool_backend/api/v1/blocks/tip/height;
+            proxy_intercept_errors on;
+            error_page 500 502 503 504 =503 @waiting;
+        }
+        location @waiting {
+            default_type application/json;
+            return 503 '{"status":"waiting","message":"Waiting for Bitcoin and Mempool indexing"}\n';
+        }
+        location ~ ^/api/(v1/)?tx$ {
+            limit_except GET POST { deny all; }
+            proxy_pass http://mempool_backend;
+        }
+        location /api/ {
+            limit_except GET { deny all; }
+            proxy_pass http://mempool_backend;
+        }
+        location / { return 404; }
+    }
+}
@@ -0,0 +1,68 @@
+app:
+  id: angor-indexer
+  name: Angor Indexer
+  version: 1.0.1
+  description: Headless Bitcoin indexer endpoint for Angor. Reuses this node’s Mempool
+    and Electrum index; requires a synced, unpruned Bitcoin node. Add this service’s
+    address as the custom indexer in Angor settings. A relay is optional and installed
+    separately.
+  category: money
+  install_prerequisites:
+  - mempool-api
+  upstream:
+    kind: github
+    repo: block-core/angor
+  container:
+    image: source.archipelago-foundation.org/chaum/angor-indexer:1.0.1
+    pull_policy: if-not-present
+    network: archy-net
+  dependencies:
+  - app_id: mempool-api
+    version: '>=3.0.0'
+  - bitcoin:archival
+  resources:
+    cpu_limit: 1
+    memory_limit: 128Mi
+    disk_limit: 128Mi
+  security:
+    capabilities: []
+    readonly_root: true
+    no_new_privileges: true
+    user: 101
+    network_policy: isolated
+  ports:
+  - host: 8998
+    container: 8080
+    protocol: tcp
+    bind: 127.0.0.1
+    auth: open
+    auth_rationale: Public Bitcoin chain-data API and validated transaction broadcast for Angor clients; no wallet keys or node RPC credentials are exposed. Browser cookie login would break machine clients.
+  interfaces:
+    main:
+      name: Angor Indexer API
+      description: Use this origin as Angor’s custom mainnet indexer URL. HTTPS is
+        required for browser clients.
+      type: api
+      port: 8998
+      protocol: http
+      path: /
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8080
+    path: /health
+    interval: 30s
+    timeout: 8s
+    retries: 3
+  bitcoin_integration:
+    rpc_access: none
+    sync_required: true
+    pruning_support: false
+  metadata:
+    icon: /assets/img/app-icons/angor-green.png
+    tier: optional
+    repo: https://github.com/block-core/angor
+    features:
+    - Angor mainnet API
+    - Reuses existing Mempool indexing
+    - No separate blockchain database
+    - Optional independent relay
@@ -0,0 +1,21 @@
+# Angor Relay
+
+Optional standalone strfry relay for Angor's public project metadata. See
+[Angor Indexer setup](../angor-indexer/README.md) for client URLs and HTTPS/WSS.
+
+The gate exposes port 8091 for Nostr clients. strfry validates event signatures;
+this is a public relay, not a private messaging archive. It mounts only
+`/var/lib/archipelago/angor-relay` and its separate configuration directory.
+It never opens, reconfigures or shares the node's internal strfry database.
+
+The configuration is seeded only when absent, preserving operator changes.
+Stop the service before making a consistent backup of its event database.
+Ordinary start/restart/recreation preserves both mounts. Use the standard app
+lifecycle; do not manually recreate a systemd-managed container.
+
+## Image provenance
+
+Mirrored from `docker.io/dockurr/strfry:1.1.2`, upstream manifest digest
+`sha256:e81d238db13507f6ef24c49d47cd0b0ea58ff207961f10581fa2a7c901054df4`.
+The public Angor policy is supplied by this app's own configuration; it does not
+reuse the internal relay's event whitelist.
@@ -0,0 +1,223 @@
+app:
+  id: angor-relay
+  name: Angor Relay
+  version: 1.1.2
+  upstream:
+    kind: github
+    repo: hoytech/strfry
+  description: Optional dedicated Nostr relay for Angor project metadata. Separate
+    storage and access settings keep the node’s internal relay private. Add this service’s
+    address to Angor’s relay settings; use WSS for browser clients.
+  container:
+    image: source.archipelago-foundation.org/chaum/angor-relay:1.1.2
+    pull_policy: if-not-present
+  dependencies:
+  - storage: 5Gi
+  resources:
+    cpu_limit: 1
+    memory_limit: 512Mi
+    disk_limit: 5Gi
+  security:
+    capabilities: []
+    readonly_root: true
+    no_new_privileges: true
+    seccomp_profile: default
+    network_policy: isolated
+    apparmor_profile: nostr-relay
+  ports:
+  - host: 8091
+    container: 7777
+    protocol: tcp
+    bind: 127.0.0.1
+    auth: open
+    auth_rationale: Dedicated public Nostr relay for Angor project metadata; strfry verifies event signatures. It has separate storage from the private node relay and no wallet or node credentials.
+  volumes:
+  - type: bind
+    source: /var/lib/archipelago/angor-relay
+    target: /app/strfry-db
+    options:
+    - rw
+  - type: bind
+    source: /var/lib/archipelago/angor-relay-config/angor-relay.conf
+    target: /etc/strfry.conf
+    options:
+    - ro
+  files:
+  - path: /var/lib/archipelago/angor-relay-config/angor-relay.conf
+    overwrite: false
+    content: |
+      ##
+      ## Default strfry config
+      ##
+
+      # Directory that contains the strfry LMDB database (restart required)
+      db = "./strfry-db/"
+
+      dbParams {
+          # Maximum number of threads/processes that can simultaneously have LMDB transactions open (restart required)
+          maxreaders = 256
+
+          # Size of mmap() to use when loading LMDB (default is 10TB, does *not* correspond to disk-space used) (restart required)
+          mapsize = 10995116277760
+
+          # Disables read-ahead when accessing the LMDB mapping. Reduces IO activity when DB size is larger than RAM. (restart required)
+          noReadAhead = false
+      }
+
+      events {
+          # Maximum size of normalised JSON, in bytes
+          maxEventSize = 65536
+
+          # Events newer than this will be rejected
+          rejectEventsNewerThanSeconds = 900
+
+          # Events older than this will be rejected
+          rejectEventsOlderThanSeconds = 94608000
+
+          # Ephemeral events older than this will be rejected
+          rejectEphemeralEventsOlderThanSeconds = 60
+
+          # Ephemeral events will be deleted from the DB when older than this
+          ephemeralEventsLifetimeSeconds = 300
+
+          # Maximum number of tags allowed
+          maxNumTags = 2000
+
+          # Maximum size for tag values, in bytes
+          maxTagValSize = 1024
+      }
+
+      relay {
+          # Interface to listen on. Use 0.0.0.0 to listen on all interfaces (restart required)
+          bind = "0.0.0.0"
+
+          # Port to open for the nostr websocket protocol (restart required)
+          port = 7777
+
+          # Set OS-limit on maximum number of open files/sockets (if 0, don't attempt to set) (restart required)
+          nofiles = 0
+
+          # HTTP header that contains the client's real IP, before reverse proxying (ie x-real-ip) (MUST be all lower-case)
+          realIpHeader = ""
+
+          info {
+              # NIP-11: Name of this server. Short/descriptive (< 30 characters)
+              name = "Angor Relay"
+
+              # NIP-11: Detailed information about relay, free-form
+              description = "Dedicated public relay for Angor project metadata."
+
+              # NIP-11: Administrative nostr pubkey, for contact purposes
+              pubkey = ""
+
+              # NIP-11: Alternative administrative contact (email, website, etc)
+              contact = ""
+
+              # NIP-11: URL pointing to an image to be used as an icon for the relay
+              icon = ""
+
+              # List of supported lists as JSON array, or empty string to use default. Example: "[1,2]"
+              nips = ""
+          }
+
+          # Maximum accepted incoming websocket frame size (should be larger than max event) (restart required)
+          maxWebsocketPayloadSize = 131072
+
+          # Maximum number of filters allowed in a REQ
+          maxReqFilterSize = 200
+
+          # Websocket-level PING message frequency (should be less than any reverse proxy idle timeouts) (restart required)
+          autoPingSeconds = 55
+
+          # If TCP keep-alive should be enabled (detect dropped connections to upstream reverse proxy)
+          enableTcpKeepalive = false
+
+          # How much uninterrupted CPU time a REQ query should get during its DB scan
+          queryTimesliceBudgetMicroseconds = 10000
+
+          # Maximum records that can be returned per filter
+          maxFilterLimit = 500
+
+          # Maximum number of subscriptions (concurrent REQs) a connection can have open at any time
+          maxSubsPerConnection = 20
+
+          writePolicy {
+              # If non-empty, path to an executable script that implements the writePolicy plugin logic
+              plugin = ""
+          }
+
+          compression {
+              # Use permessage-deflate compression if supported by client. Reduces bandwidth, but slight increase in CPU (restart required)
+              enabled = true
+
+              # Maintain a sliding window buffer for each connection. Improves compression, but uses more memory (restart required)
+              slidingWindow = true
+          }
+
+          logging {
+              # Dump all incoming messages
+              dumpInAll = false
+
+              # Dump all incoming EVENT messages
+              dumpInEvents = false
+
+              # Dump all incoming REQ/CLOSE messages
+              dumpInReqs = false
+
+              # Log performance metrics for initial REQ database scans
+              dbScanPerf = false
+
+              # Log reason for invalid event rejection? Can be disabled to silence excessive logging
+              invalidEvents = true
+          }
+
+          numThreads {
+              # Ingester threads: route incoming requests, validate events/sigs (restart required)
+              ingester = 3
+
+              # reqWorker threads: Handle initial DB scan for events (restart required)
+              reqWorker = 3
+
+              # reqMonitor threads: Handle filtering of new events (restart required)
+              reqMonitor = 3
+
+              # negentropy threads: Handle negentropy protocol messages (restart required)
+              negentropy = 2
+          }
+
+          negentropy {
+              # Support negentropy protocol messages
+              enabled = true
+
+              # Maximum records that sync will process before returning an error
+              maxSyncEvents = 1000000
+          }
+      }
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:7777
+    path: /health
+    interval: 30s
+    timeout: 5s
+    retries: 3
+  nostr_integration:
+    relay_type: public
+    monetization_enabled: false
+  category: nostr
+  interfaces:
+    main:
+      name: Angor Relay
+      description: Nostr WebSocket endpoint; use ws:// for LAN or wss:// through your
+        HTTPS domain.
+      type: api
+      port: 8091
+      protocol: http
+      path: /
+  metadata:
+    icon: /assets/img/app-icons/angor-green.png
+    tier: optional
+    repo: https://github.com/hoytech/strfry
+    features:
+    - Angor project metadata
+    - Separate from the node relay
+    - Persistent Nostr event storage
@@ -15,6 +15,9 @@ app:
    image: source.archipelago-foundation.org/lfg2025/gitea:1.27.3
    pull_policy: if-not-present

+  # Preserve repositories, database, keys and configuration during runtime repairs.
+  backup_before_runtime_change: true
+
  dependencies:
    # Source history, LFS objects, release artifacts and OCI layers all share
    # this persistent store. 500Mi was only suitable for an empty demo node.
@@ -25,7 +28,7 @@ app:
    disk_limit: 50Gi

  security:
-    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_BIND_SERVICE]
+    capabilities: [CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE, NET_BIND_SERVICE, SYS_CHROOT]
    readonly_root: false
    no_new_privileges: false
    network_policy: bridge
@@ -62,6 +65,17 @@ app:
      target: /etc/gitea
      options: [rw]

+  # Seed a fresh installation with the same origin advertised by the app gate.
+  # Existing app.ini (including custom HTTPS/domain settings) is never replaced.
+  files:
+    - path: /var/lib/archipelago/gitea/data/gitea/conf/app.ini
+      overwrite: false
+      content: |
+        [server]
+        DOMAIN = {{HOST_IP}}
+        SSH_DOMAIN = {{HOST_IP}}
+        ROOT_URL = http://{{HOST_IP}}:3001/
+
  environment:
    - GITEA__database__DB_TYPE=sqlite3
    - GITEA__server__SSH_PORT=2222
@@ -106,10 +120,3 @@ app:
      - Issue tracking and pull requests
      - CI/CD via Gitea Actions
      - Lightweight SQLite deployment
-
-  nginx_proxy:
-    listen: 3000
-    proxy_pass: http://127.0.0.1:3001
-    extra_headers:
-      - proxy_hide_header X-Frame-Options
-      - proxy_hide_header Content-Security-Policy
@@ -64,9 +64,11 @@ app:

  environment: []

+  # Probe the admin API inside the container, independent of optional
+  # tunnel listeners. This also verifies the Node backend is ready.
  health_check:
-    type: tcp
-    endpoint: localhost:81
+    type: http
+    endpoint: http://127.0.0.1:81/api/
    interval: 30s
    timeout: 5s
    retries: 3
@@ -14,8 +14,16 @@ app:
  container:
    image: source.archipelago-foundation.org/lfg2025/portainer:2.45.0
    pull_policy: if-not-present
+    # Portainer fetches Git sources and images from services on this same node.
+    # Rootless pasta copies the host LAN address into its namespace, so a LAN
+    # URL points back at Portainer itself. Give it a private address with the
+    # supported rootless slirp backend; public app URLs still traverse the gate.
+    network: slirp4netns
    data_uid: "1000:1000"

+  # Snapshot state before an upgrade recreates this app with new networking.
+  backup_before_runtime_change: true
+
  dependencies:
    - storage: 1Gi

@@ -104,7 +104,7 @@ dependencies = [

 [[package]]
 name = "archipelago"
-version = "1.8.21-alpha"
+version = "1.8.22-alpha"
 dependencies = [
 "anyhow",
 "archipelago-container",
@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.8.21-alpha"
+version = "1.8.22-alpha"
 edition = "2021"
 license.workspace = true
 description = "Archipelago Bitcoin Node OS - Native backend"
@@ -162,11 +162,33 @@ impl ApiHandler {
                    r#"{"error":"This file is shared with the host's federation peers only. Federate with that node (exchange invites) so it recognizes you, then try again."}"#,
                ),
            )),
-            Ok(content_server::ServeResult::NotFound) | Err(_) => Ok(build_response(
+            Ok(content_server::ServeResult::Unavailable) => Ok(build_response(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "application/json",
+                hyper::Body::from(
+                    r#"{"error":"The seller's node can't read this file right now. This request did not redeem an ecash payment."}"#,
+                ),
+            )),
+            Ok(content_server::ServeResult::RangeNotSatisfiable(total)) => Ok(Response::builder()
+                .status(StatusCode::RANGE_NOT_SATISFIABLE)
+                .header("Content-Range", format!("bytes */{total}"))
+                .body(hyper::Body::empty())
+                .unwrap()),
+            Ok(content_server::ServeResult::NotFound) => Ok(build_response(
                StatusCode::NOT_FOUND,
                "text/plain",
                hyper::Body::from("Content not found"),
            )),
+            // Not a 404: a paid request may already have been charged by the
+            // time this fails, and "not found" hid the real error entirely.
+            Err(e) => {
+                tracing::error!("Serving content {content_id} failed: {e:#}");
+                Ok(build_response(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "text/plain",
+                    hyper::Body::from("Failed to serve content"),
+                ))
+            }
        }
    }

@@ -43,6 +43,25 @@ async fn reclaim_spent_ecash(data_dir: &std::path::Path, token: &str, backend: &
    }
 }

+/// Only pass through the peer's bounded, printable explanation; refund status
+/// is always determined locally and must never come from the peer's wording.
+fn seller_error_message(status: reqwest::StatusCode, body: &str) -> String {
+    let reason = serde_json::from_str::<serde_json::Value>(body)
+        .ok()
+        .and_then(|v| v.get("error").and_then(|e| e.as_str()).map(str::to_owned));
+    match reason {
+        Some(reason) if !reason.trim().is_empty() => {
+            let clean: String = reason
+                .chars()
+                .filter(|c| !c.is_control())
+                .take(240)
+                .collect();
+            format!("Seller response ({status}): {clean}")
+        }
+        _ => format!("Peer returned an error ({status})."),
+    }
+}
+
 /// Keep first purchases and cached repeats compatible with both existing clients.
 fn paid_content_response(bytes: &[u8], mime: &str, paid_sats: u64) -> serde_json::Value {
    use base64::Engine;
@@ -54,13 +73,9 @@ fn paid_content_response(bytes: &[u8], mime: &str, paid_sats: u64) -> serde_json
    })
 }

-/// FileBrowser owns its files through a rootless UID mapping. Use its authenticated
-/// API rather than writing host paths with the backend's unrelated UID. Its
-/// override=false upload atomically refuses existing names, including races.
+/// File purchases through an atomic no-clobber write in Files' own namespace.
 async fn file_purchase_in_files(
-    client: &reqwest::Client,
-    base_url: &str,
-    token: &str,
+    data_dir: &std::path::Path,
    filename: &str,
    mime: &str,
    bytes: &[u8],
@@ -72,59 +87,24 @@ async fn file_purchase_in_files(
    } else {
        "Documents"
    };
-    let mut folder_url = reqwest::Url::parse(base_url)?;
-    folder_url
-        .path_segments_mut()
-        .map_err(|_| anyhow::anyhow!("Invalid Files URL"))?
-        .extend(["api", "resources", folder, ""]);
-    let response = client
-        .get(folder_url.clone())
-        .header("X-Auth", token)
-        .send()
-        .await?;
-    if response.status() == reqwest::StatusCode::NOT_FOUND {
-        let response = client
-            .post(folder_url.clone())
-            .header("X-Auth", token)
-            .send()
-            .await?;
-        if response.status() != reqwest::StatusCode::CONFLICT {
-            response.error_for_status()?;
-        }
-    } else {
-        response.error_for_status()?;
-    }
-    let base = std::path::Path::new(filename)
+    let root = data_dir.join("filebrowser");
+    anyhow::ensure!(
+        tokio::fs::metadata(&root).await?.is_dir(),
+        "Files storage is unavailable"
+    );
+    let name = std::path::Path::new(filename)
        .file_name()
        .and_then(|n| n.to_str())
        .filter(|n| !n.is_empty())
        .unwrap_or("download");
-    let (stem, extension) = match base.rsplit_once('.') {
-        Some((stem, ext)) if !stem.is_empty() => (stem, format!(".{ext}")),
-        _ => (base, String::new()),
-    };
-    for attempt in 1..=100 {
-        let name = if attempt == 1 {
-            base.to_string()
-        } else {
-            format!("{stem} ({attempt}){extension}")
-        };
-        let mut url = folder_url.clone();
-        url.path_segments_mut().unwrap().pop_if_empty().push(&name);
-        url.query_pairs_mut().append_pair("override", "false");
-        let response = client
-            .post(url)
-            .header("X-Auth", token)
-            .body(bytes.to_vec())
-            .send()
-            .await?;
-        if response.status() == reqwest::StatusCode::CONFLICT {
-            continue;
-        }
-        response.error_for_status()?;
-        return Ok(format!("{folder}/{name}"));
-    }
-    anyhow::bail!("Too many existing copies; purchased file remains in the purchase cache")
+    let path =
+        crate::container::filebrowser::save_new_file(&root.join(folder), name, bytes).await?;
+    Ok(format!(
+        "{folder}/{}",
+        path.file_name()
+            .and_then(|n| n.to_str())
+            .context("Invalid Files name")?
+    ))
 }

 impl RpcHandler {
@@ -623,13 +603,14 @@ impl RpcHandler {

        let path = format!("/content/{}", content_id);
        // Surface a real reason instead of the generic sanitized error (#30):
-        // the dial already tries FIPS/mesh then falls back to Tor, so a failure
-        // here means the peer is genuinely unreachable on both transports.
+        // A bearer token must not be replayed after an ambiguous delivery.
+        // A transport error can mean the seller received it without replying.
        let (response, transport) =
            match crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
                .service(crate::settings::transport::PeerService::PeerFiles)
                .header("X-Federation-DID", local_did)
                .header("X-Payment-Token", token_str.clone())
+                .single_delivery()
                .timeout(std::time::Duration::from_secs(900))
                .send_get()
                .await
@@ -642,7 +623,7 @@ impl RpcHandler {
                    let refund =
                        reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
                    return Ok(serde_json::json!({
-                        "error": format!("Could not reach the peer over mesh or Tor. {refund}")
+                        "error": format!("The purchase could not be completed. {refund}")
                    }));
                }
            };
@@ -679,7 +660,7 @@ impl RpcHandler {
            tracing::warn!("paid download: seller {onion} returned {status}: {body}");
            let refund = reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
            return Ok(serde_json::json!({
-                "error": format!("Peer returned an error ({status}). {refund}")
+                "error": format!("{} {refund}", seller_error_message(status, &body))
            }));
        }

@@ -693,10 +674,17 @@ impl RpcHandler {
            .filter(|s| !s.is_empty())
            .unwrap_or_else(|| "application/octet-stream".to_string());

-        let bytes = response
-            .bytes()
-            .await
-            .context("Failed to read response body")?;
+        let bytes = match response.bytes().await {
+            Ok(bytes) => bytes,
+            Err(error) => {
+                tracing::warn!("paid download: response body failed: {error}");
+                let refund =
+                    reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
+                return Ok(serde_json::json!({
+                    "error": format!("The file transfer was interrupted after payment was sent. {refund}")
+                }));
+            }
+        };

        // Persist the purchase so it "stays unlocked" for this buyer: cache the
        // bytes + metadata keyed by (onion, content_id). The gallery then renders
@@ -728,28 +716,8 @@ impl RpcHandler {

        // The durable purchased-content cache above is primary. A Files copy
        // remains optional: a stopped FileBrowser must not undo a paid download.
-        let filed = async {
-            let auth = self.handle_filebrowser_token().await?;
-            let token = auth
-                .get("token")
-                .and_then(|v| v.as_str())
-                .context("FileBrowser omitted its authentication token")?;
-            let client = reqwest::Client::builder()
-                .no_proxy()
-                .redirect(reqwest::redirect::Policy::none())
-                .timeout(std::time::Duration::from_secs(30))
-                .build()?;
-            file_purchase_in_files(
-                &client,
-                "http://127.0.0.1:8083",
-                token,
-                &filename,
-                &mime_type,
-                &bytes,
-            )
-            .await
-        }
-        .await;
+        let filed =
+            file_purchase_in_files(&self.config.data_dir, &filename, &mime_type, &bytes).await;
        match filed {
            Ok(path) => tracing::info!("paid download: filed into Files/{path}"),
            Err(error) => tracing::warn!(
@@ -1,69 +1,4 @@
 use super::*;
-use hyper::{
-    service::{make_service_fn, service_fn},
-    Body, Response, Server,
-};
-use std::{
-    collections::VecDeque,
-    convert::Infallible,
-    sync::{Arc, Mutex},
-};
-
-struct FilesApi {
-    url: String,
-    seen: Arc<Mutex<Vec<(String, String, Vec<u8>)>>>,
-    task: tokio::task::JoinHandle<()>,
-}
-impl Drop for FilesApi {
-    fn drop(&mut self) {
-        self.task.abort();
-    }
-}
-fn files_api(statuses: Vec<u16>) -> FilesApi {
-    let statuses = Arc::new(Mutex::new(VecDeque::from(statuses)));
-    let seen = Arc::new(Mutex::new(Vec::new()));
-    let history = seen.clone();
-    let server = Server::bind(&([127, 0, 0, 1], 0).into());
-    let address = server.local_addr();
-    let service = make_service_fn(move |_| {
-        let statuses = statuses.clone();
-        let seen = history.clone();
-        async move {
-            Ok::<_, Infallible>(service_fn(move |request: hyper::Request<Body>| {
-                let statuses = statuses.clone();
-                let seen = seen.clone();
-                async move {
-                    assert_eq!(request.headers().get("X-Auth").unwrap(), "test-session");
-                    let method = request.method().to_string();
-                    let uri = request.uri().to_string();
-                    let body = hyper::body::to_bytes(request.into_body())
-                        .await
-                        .unwrap()
-                        .to_vec();
-                    seen.lock().unwrap().push((method, uri, body));
-                    let status = statuses
-                        .lock()
-                        .unwrap()
-                        .pop_front()
-                        .expect("unexpected extra Files request");
-                    Ok::<_, Infallible>(
-                        Response::builder()
-                            .status(status)
-                            .body(Body::empty())
-                            .unwrap(),
-                    )
-                }
-            }))
-        }
-    });
-    FilesApi {
-        url: format!("http://{address}"),
-        seen,
-        task: tokio::spawn(async move {
-            server.serve(service).await.unwrap();
-        }),
-    }
-}

 #[test]
 fn first_and_cached_paid_downloads_have_the_same_client_payload_contract() {
@@ -85,80 +20,54 @@ fn first_and_cached_paid_downloads_have_the_same_client_payload_contract() {
 }

 #[tokio::test]
-async fn files_copy_uses_authenticated_api_and_preserves_existing_names() {
-    let api = files_api(vec![200, 409, 200]);
-    let client = reqwest::Client::new();
-    let path = file_purchase_in_files(
-        &client,
-        &api.url,
-        "test-session",
-        "../my #file?.txt",
-        "text/plain",
-        b"paid bytes",
-    )
+async fn files_copy_routes_media_and_sanitizes_the_filename() {
+    let dir = tempfile::tempdir().unwrap();
+    tokio::fs::create_dir(dir.path().join("filebrowser"))
        .await
        .unwrap();
-    assert_eq!(path, "Documents/my #file? (2).txt");
-    let seen = api.seen.lock().unwrap();
-    assert_eq!(seen[0].0, "GET");
-    assert_eq!(seen[0].1, "/api/resources/Documents/");
-    assert_eq!(seen.len(), 3);
-    for (_, uri, body) in &seen[1..] {
-        assert!(uri.contains("override=false"));
-        assert!(uri.contains("%23file%3F"));
-        assert!(!uri.contains("../"));
-        assert_eq!(body, b"paid bytes");
-    }
-}
-
-#[tokio::test]
-async fn files_copy_creates_missing_media_folder() {
    for (mime, folder) in [
        ("image/png", "Photos"),
        ("video/mp4", "Photos"),
-        ("audio/ogg", "Music"),
+        ("audio/mpeg", "Music"),
+        ("text/plain", "Documents"),
    ] {
-        let api = files_api(vec![404, 200, 200]);
-        let path = file_purchase_in_files(
-            &reqwest::Client::new(),
-            &api.url,
-            "test-session",
-            "file",
-            mime,
-            b"bytes",
-        )
+        let relative = file_purchase_in_files(dir.path(), "../name #?.bin", mime, b"paid")
            .await
            .unwrap();
-        assert_eq!(path, format!("{folder}/file"));
-        let seen = api.seen.lock().unwrap();
-        assert_eq!(seen[1].0, "POST");
-        assert!(seen[1].1.ends_with('/'));
-        assert!(seen[1].2.is_empty());
-        assert_eq!(seen[2].2, b"bytes");
+        assert!(relative.starts_with(&format!("{folder}/name #?")));
+        assert_eq!(
+            tokio::fs::read(dir.path().join("filebrowser").join(relative))
+                .await
+                .unwrap(),
+            b"paid"
+        );
    }
 }

 #[tokio::test]
-async fn files_copy_fails_without_overwriting_or_claiming_success_on_errors() {
-    for statuses in [
-        vec![401],
-        vec![503],
-        vec![404, 500],
-        vec![200, 507],
-        vec![200, 403],
-    ] {
-        let expected = statuses.len();
-        let api = files_api(statuses);
-        assert!(file_purchase_in_files(
-            &reqwest::Client::new(),
-            &api.url,
-            "test-session",
-            "file.txt",
-            "text/plain",
-            b"bytes"
-        )
+async fn unavailable_files_storage_is_reported_without_creating_a_fake_installation() {
+    let dir = tempfile::tempdir().unwrap();
+    assert!(
+        file_purchase_in_files(dir.path(), "name", "text/plain", b"bytes")
            .await
-        .is_err());
-        assert_eq!(api.seen.lock().unwrap().len(), expected);
+            .is_err()
+    );
+    assert!(!dir.path().join("filebrowser").exists());
+}
+
+#[test]
+fn seller_errors_are_bounded_printable_and_identified_as_peer_text() {
+    let status = reqwest::StatusCode::SERVICE_UNAVAILABLE;
+    let message = seller_error_message(status, r#"{"error":"Cannot read file\n\u0000"}"#);
+    assert!(message.starts_with("Seller response (503"));
+    assert!(message.ends_with("Cannot read file"));
+    assert!(!message.contains('\n') && !message.contains('\0'));
+    let body = serde_json::json!({"error": "é".repeat(1000)}).to_string();
+    assert!(seller_error_message(status, &body).chars().count() < 300);
+    for body in ["not JSON", r#"{"error": 7}"#, r#"{"error":"   "}"#] {
+        assert_eq!(
+            seller_error_message(status, body),
+            "Peer returned an error (503 Service Unavailable)."
+        );
    }
 }
@@ -22,6 +22,18 @@ const ARCHIVAL_BITCOIN_DEPENDENCY: &str = "bitcoin:archival";
 /// hardcoded id list below — a new app just declares the dependency instead
 /// of needing a code change here.
 fn manifest_declares_archival_bitcoin(package_id: &str) -> bool {
+    // Registry-only apps need the same guard as OTA-bundled manifests. Honor
+    // the verified catalog's effective manifest before the disk fallback.
+    if let Some((_, value)) = crate::container::app_catalog::catalog_manifest_values()
+        .into_iter()
+        .find(|(id, _)| id == package_id)
+    {
+        if let Some(manifest) =
+            crate::container::app_catalog::catalog_manifest_overlay(package_id, value)
+        {
+            return dependency_list_declares_archival_bitcoin(&manifest.app.dependencies);
+        }
+    }
    for apps_dir in manifest_apps_dirs() {
        let path = apps_dir.join(package_id).join("manifest.yml");
        let Ok(contents) = std::fs::read_to_string(&path) else {
@@ -1055,6 +1067,14 @@ mod tests {
        // edit to `requires_unpruned_bitcoin`.
        assert!(manifest_declares_archival_bitcoin("electrumx"));
        assert!(manifest_declares_archival_bitcoin("mempool"));
+        let angor = archipelago_container::AppManifest::parse(include_str!(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../apps/angor-indexer/manifest.yml"
+        )))
+        .unwrap();
+        assert!(dependency_list_declares_archival_bitcoin(
+            &angor.app.dependencies
+        ));
        // An app whose manifest exists but never declares the marker.
        assert!(!manifest_declares_archival_bitcoin("bitcoin-knots"));
        // An id with no manifest on disk at all.
@@ -573,6 +573,9 @@ impl RpcHandler {
                            "message": format!("Package {} installed and started", package_id)
                        }));
                    }
+                    Err(e) if e.downcast_ref::<crate::container::prod_orchestrator::InstallPrerequisiteError>().is_some() => {
+                        return Err(super::dependencies::DependencyGateError(e.to_string()).into());
+                    }
                    Err(e) if is_unknown_app_id_error(&e) => {
                        info!(
                            "Install {}: orchestrator has no manifest mapping yet, falling back to legacy installer",
@@ -1699,32 +1702,10 @@ autopilot.active=false\n",
            patch_indeedhub_nostr_provider().await;
        }

-        // Gitea: keep it on its native host port (3001). The UI opens Gitea
-        // in a new tab on that direct port so absolute asset URLs must be
-        // rooted at the host port rather than Archipelago's /app/gitea/ path.
-        if package_id == "gitea" {
-            let _ = tokio::fs::remove_file("/etc/nginx/conf.d/gitea-iframe.conf").await;
-
-            // Set ROOT_URL to the direct launch route so links/assets stay
-            // anchored under the same origin Gitea is launched from.
-            let host_ip = &self.config.host_ip;
-            let _ = tokio::process::Command::new("podman")
-                .args(["exec", "gitea", "sh", "-c",
-                       &format!("grep -q ROOT_URL /data/gitea/conf/app.ini && sed -i 's|ROOT_URL.*|ROOT_URL = http://{}:3001/|' /data/gitea/conf/app.ini || true", host_ip)])
-                .output()
-                .await;
-            // Also ensure X_FRAME_OPTIONS is empty so Gitea doesn't send the header
-            let _ = tokio::process::Command::new("podman")
-                .args(["exec", "gitea", "sh", "-c",
-                       "grep -q X_FRAME_OPTIONS /data/gitea/conf/app.ini && sed -i 's|X_FRAME_OPTIONS.*|X_FRAME_OPTIONS =|' /data/gitea/conf/app.ini || sed -i '/^\\[security\\]/a X_FRAME_OPTIONS =' /data/gitea/conf/app.ini"])
-                .output()
-                .await;
-
-            info!(
-                "Gitea: ROOT_URL set to http://{}:3001/, X_FRAME_OPTIONS cleared",
-                host_ip
-            );
-        }
+        // Gitea owns its public URL and security settings in app.ini, including
+        // values chosen in its first-run setup. Do not rewrite operator values
+        // or claim success from best-effort grep/sed commands. The app gate
+        // fronts its declared HTTP port and handles frame headers separately.

        if package_id == "nextcloud" {
            let host_ip = &self.config.host_ip;
@@ -138,6 +138,44 @@ const NGINX_FEDIMINT_NEW: &str = "        sub_filter_types text/css application/
 const NGINX_FEDIMINT_SNIPPET_ANCHOR: &str = "proxy_pass http://127.0.0.1:8175/;";
 const NGINX_FEDIMINT_SNIPPET_INSERT: &str = "proxy_pass http://127.0.0.1:8175/;\n    proxy_set_header Accept-Encoding \"\";\n    sub_filter_types text/css application/javascript application/json;\n    sub_filter_once off;\n    sub_filter 'href=\"/' 'href=\"/app/fedimint/';\n    sub_filter 'src=\"/' 'src=\"/app/fedimint/';\n    sub_filter \"href='/\" \"href='/app/fedimint/\";\n    sub_filter \"src='/\" \"src='/app/fedimint/\";\n    sub_filter 'url(\"/' 'url(\"/app/fedimint/';\n    sub_filter \"url('/\" \"url('/app/fedimint/\";\n    sub_filter '</head>' '<script src=\"/nostr-provider.js\"></script></head>';";

+/// Finish manifest promotion before constructing the orchestrator or starting
+/// catalog refresh/reconciliation. Replacing the app tree in the background
+/// could let a reload observe its temporary empty state and forget disk-only apps.
+pub async fn ensure_runtime_assets_ready() {
+    match run_runtime_assets().await {
+        Ok(changed) if changed => info!("Runtime assets synchronized from OTA payload"),
+        Ok(_) => debug!("No OTA runtime payload to synchronize"),
+        Err(e) => warn!("Runtime asset bootstrap failed (non-fatal): {:#}", e),
+    }
+    // Repair the narrowly recognized legacy NPM tunnel override before app
+    // reconciliation. The embedded script ships in both OTA and ISO binaries.
+    // It preserves native wallet services and refuses unknown custom routing.
+    match tokio::process::Command::new("python3")
+        .arg("-c")
+        .arg(include_str!("../../../scripts/repair-npm-tunnel.py"))
+        .output()
+        .await
+    {
+        Ok(output) if output.status.success() => {
+            if !output.stdout.is_empty() {
+                info!("{}", String::from_utf8_lossy(&output.stdout).trim());
+            }
+        }
+        Ok(output) => warn!(
+            "NPM tunnel migration needs attention: {}",
+            String::from_utf8_lossy(&output.stderr).trim()
+        ),
+        Err(error) => warn!("NPM tunnel migration could not run: {error}"),
+    }
+    match run_apps_dir_repair().await {
+        Ok(true) => {
+            info!("Populated /opt/archipelago/apps from installer copy at /etc/archipelago/apps")
+        }
+        Ok(false) => debug!("/opt/archipelago/apps already populated (or no installer copy)"),
+        Err(e) => warn!("Apps dir repair failed (non-fatal): {:#}", e),
+    }
+}
+
 /// 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() {
@@ -146,11 +184,6 @@ pub async fn ensure_doctor_installed() {
        Ok(false) => debug!("No stale Archipelago dev-mode service override found"),
        Err(e) => warn!("Service override repair failed (non-fatal): {:#}", e),
    }
-    match run_runtime_assets().await {
-        Ok(changed) if changed => info!("Runtime assets synchronized from OTA payload"),
-        Ok(_) => debug!("No OTA runtime payload to synchronize"),
-        Err(e) => warn!("Runtime asset bootstrap failed (non-fatal): {:#}", e),
-    }
    match run().await {
        Ok(changed) if changed => info!("Doctor artifacts synchronized with binary"),
        Ok(_) => debug!("Doctor artifacts already in sync"),
@@ -168,13 +201,6 @@ pub async fn ensure_doctor_installed() {
        Ok(false) => debug!("No stale bitcoin.conf found"),
        Err(e) => warn!("Bitcoin RPC repair failed (non-fatal): {:#}", e),
    }
-    match run_apps_dir_repair().await {
-        Ok(true) => {
-            info!("Populated /opt/archipelago/apps from installer copy at /etc/archipelago/apps")
-        }
-        Ok(false) => debug!("/opt/archipelago/apps already populated (or no installer copy)"),
-        Err(e) => warn!("Apps dir repair failed (non-fatal): {:#}", e),
-    }
    match run_tor_helper_sync().await {
        Ok(true) => info!("tor-helper.sh synchronized with binary"),
        Ok(false) => debug!("tor-helper.sh already current"),
@@ -102,6 +102,31 @@ pub struct AppCatalogEntry {
    /// `docs/registry-manifest-design.md`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub manifest: Option<serde_json::Value>,
+    /// Backward-compatible catalog rollout: old daemons ignore these and keep
+    /// the base manifest. New daemons choose only variants they can safely apply.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub manifest_variants: Vec<CatalogManifestVariant>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CatalogManifestVariant {
+    pub requires: Vec<String>,
+    pub manifest: serde_json::Value,
+}
+
+fn selected_manifest(entry: AppCatalogEntry) -> Option<serde_json::Value> {
+    // Never let an unknown future requirement become an unsafe partial match.
+    for variant in entry.manifest_variants.into_iter().rev() {
+        if !variant.requires.is_empty()
+            && variant
+                .requires
+                .iter()
+                .all(|capability| capability == "runtime-migration-backup-v1")
+        {
+            return Some(variant.manifest);
+        }
+    }
+    entry.manifest
 }

 /// One selectable version in an app's `versions[]` list. The catalog carries a
@@ -234,7 +259,7 @@ pub fn catalog_manifest_values() -> Vec<(String, serde_json::Value)> {
    load_catalog()
        .apps
        .into_iter()
-        .filter_map(|(id, e)| e.manifest.map(|m| (id, m)))
+        .filter_map(|(id, e)| selected_manifest(e).map(|m| (id, m)))
        .collect()
 }

@@ -557,6 +582,32 @@ fn write_cache(data_dir: &Path, body: &str) -> anyhow::Result<bool> {
 mod tests {
    use super::*;

+    #[test]
+    fn catalog_migration_variant_is_compatible_with_old_and_future_daemons() {
+        let raw = serde_json::json!({
+            "version": "2.45.0", "manifest": {"app": {"id": "portainer", "container": {}}},
+            "manifest_variants": [{"requires": ["runtime-migration-backup-v1"],
+                "manifest": {"app": {"id": "portainer", "container": {"network": "slirp4netns"}, "backup_before_runtime_change": true}}}]
+        });
+        #[derive(Deserialize)]
+        struct OldEntry {
+            manifest: serde_json::Value,
+        }
+        let old: OldEntry = serde_json::from_value(raw.clone()).unwrap();
+        assert!(old.manifest["app"]["container"].get("network").is_none());
+        let current: AppCatalogEntry = serde_json::from_value(raw.clone()).unwrap();
+        let chosen = selected_manifest(current).unwrap();
+        assert_eq!(chosen["app"]["container"]["network"], "slirp4netns");
+        assert_eq!(chosen["app"]["backup_before_runtime_change"], true);
+        let mut future = raw;
+        future["manifest_variants"][0]["requires"]
+            .as_array_mut()
+            .unwrap()
+            .push(serde_json::json!("unknown-next-capability"));
+        let chosen = selected_manifest(serde_json::from_value(future).unwrap()).unwrap();
+        assert!(chosen["app"]["container"].get("network").is_none());
+    }
+
    #[test]
    fn parses_and_ignores_unknown_fields() {
        let json = r#"{
@@ -16,6 +16,16 @@ use crate::data_model::{
    PackageDataEntry, PackageState, ServiceStatus, StaticFiles,
 };

+/// One displayed package for each known container/manifest alias. Keep the
+/// stopped-app restoration path in agreement with live-container discovery.
+fn canonical_package_id(name: &str) -> &str {
+    match name.strip_prefix("archy-").unwrap_or(name) {
+        "immich_server" => "immich",
+        "mempool-web" | "mempool-frontend" => "mempool",
+        name => name,
+    }
+}
+
 pub struct DockerPackageScanner {
    runtime: Arc<dyn ContainerRuntimeTrait>,
 }
@@ -99,24 +109,8 @@ impl DockerPackageScanner {
        debug!("Found {} UI containers", ui_containers.len());

        for container in containers {
-            // Extract app ID from container name
-            // Support both archy-* containers (docker-compose) and plain names (manual)
-            let app_id = if container.name.starts_with("archy-") {
-                container
-                    .name
-                    .strip_prefix("archy-")
-                    .unwrap_or(&container.name)
-                    .to_string()
-            } else {
-                // Use the container name as-is for manually started containers
-                container.name.clone()
-            };
-
-            // Normalize multi-container app IDs to their canonical names
-            let app_id = match app_id.as_str() {
-                "immich_server" => "immich".to_string(),
-                _ => app_id,
-            };
+            // Use the same alias mapping as stopped-app restoration.
+            let app_id = canonical_package_id(&container.name).to_owned();

            // Skip backend services (databases, APIs, etc.)
            if excluded_services.contains(&app_id.as_str()) {
@@ -178,13 +172,11 @@ impl DockerPackageScanner {
            } else {
                // Prefer the known web UI port over arbitrary first binding
                // (for example Gitea exposes SSH on 2222 before web on 3001).
-                let candidate = if uses_allocated_launch_port(&app_id) {
-                    extract_lan_address(&container.ports)
-                        .or_else(|| PodmanClient::lan_address_for(&app_id))
-                } else {
-                    PodmanClient::lan_address_for(&app_id)
-                        .or_else(|| extract_lan_address(&container.ports))
-                };
+                let candidate = package_launch_candidate(
+                    &app_id,
+                    &container.ports,
+                    PodmanClient::lan_address_for(&app_id),
+                );
                reachable_lan_address(&app_id, candidate).await
            };

@@ -388,21 +380,16 @@ fn restore_absent_installed(
    installed: &std::collections::HashSet<String>,
    uninstalled: &std::collections::HashSet<String>,
 ) {
-    fn canonical(name: &str) -> &str {
-        let name = name.strip_prefix("archy-").unwrap_or(name);
-        match name {
-            "immich_server" => "immich",
-            _ => name,
-        }
-    }
    let mut present: std::collections::HashSet<String> = containers
        .iter()
-        .map(|c| canonical(&c.name).to_owned())
+        .map(|c| canonical_package_id(&c.name).to_owned())
+        .collect();
+    let removed: std::collections::HashSet<_> = uninstalled
+        .iter()
+        .map(|id| canonical_package_id(id))
        .collect();
-    let removed: std::collections::HashSet<_> =
-        uninstalled.iter().map(|id| canonical(id)).collect();
    for name in installed {
-        let id = canonical(name);
+        let id = canonical_package_id(name);
        if removed.contains(id) || !present.insert(id.to_owned()) {
            continue;
        }
@@ -475,6 +462,33 @@ mod lifecycle_regression_tests {
        assert_eq!(containers[0].state, ContainerState::Running);
    }

+    #[test]
+    fn mempool_frontend_inventory_alias_does_not_create_a_second_package() {
+        let installed = ["mempool", "archy-mempool-web", "mempool-web"]
+            .into_iter()
+            .map(str::to_owned)
+            .collect();
+        let mut containers = Vec::new();
+        restore_absent_installed(&mut containers, &installed, &Default::default());
+        assert_eq!(containers.len(), 1);
+        assert_eq!(containers[0].name, "mempool");
+        containers[0].id = "live-frontend".into();
+        containers[0].state = ContainerState::Running;
+        restore_absent_installed(&mut containers, &installed, &Default::default());
+        assert_eq!(containers.len(), 1);
+        assert_eq!(containers[0].id, "live-frontend");
+        assert_eq!(containers[0].state, ContainerState::Running);
+        assert_eq!(canonical_package_id("archy-mempool-web"), "mempool");
+        assert_eq!(canonical_package_id("mempool-api"), "mempool-api");
+        containers.clear();
+        restore_absent_installed(
+            &mut containers,
+            &installed,
+            &["mempool".into()].into_iter().collect(),
+        );
+        assert!(containers.is_empty());
+    }
+
    #[tokio::test]
    async fn readiness_rejects_startup_errors_and_accepts_auth_and_redirects() {
        for (status, expected) in [
@@ -1089,6 +1103,23 @@ fn companion_lan_address(app_id: &str) -> Option<String> {
    }
 }

+/// Companion dashboards remain usable while their backend is syncing. Never
+/// probe a Bitcoin RPC or Electrum protocol socket as dashboard readiness.
+fn package_launch_candidate(
+    app_id: &str,
+    ports: &[String],
+    known: Option<String>,
+) -> Option<String> {
+    if let Some(companion) = companion_lan_address(app_id) {
+        return Some(companion);
+    }
+    if uses_allocated_launch_port(app_id) {
+        extract_lan_address(ports).or(known)
+    } else {
+        known.or_else(|| extract_lan_address(ports))
+    }
+}
+
 fn uses_allocated_launch_port(app_id: &str) -> bool {
    matches!(
        app_id,
@@ -1173,7 +1204,42 @@ mod tor_service_name_tests {

 #[cfg(test)]
 mod extract_lan_address_tests {
-    use super::extract_lan_address;
+    use super::{extract_lan_address, package_launch_candidate};
+
+    #[test]
+    fn companion_dashboard_wins_over_backend_protocol_ports() {
+        for id in ["bitcoin", "bitcoin-core", "bitcoin-knots"] {
+            assert_eq!(
+                package_launch_candidate(
+                    id,
+                    &["127.0.0.1:8332->8332/tcp".into()],
+                    Some("http://localhost:8332".into())
+                )
+                .as_deref(),
+                Some("http://localhost:8334")
+            );
+        }
+        for id in ["electrumx", "electrs", "mempool-electrs"] {
+            assert_eq!(
+                package_launch_candidate(
+                    id,
+                    &["127.0.0.1:50001->50001/tcp".into()],
+                    Some("http://localhost:50001".into())
+                )
+                .as_deref(),
+                Some("http://localhost:50002")
+            );
+        }
+        assert_eq!(
+            package_launch_candidate(
+                "filebrowser",
+                &["127.0.0.1:19080->80/tcp".into()],
+                Some("http://localhost:8080".into())
+            )
+            .as_deref(),
+            Some("http://localhost:19080")
+        );
+    }

    #[test]
    fn skips_ssh_port_when_web_port_is_published() {
@@ -5,7 +5,7 @@
 //! starting the container with `--config /data/.filebrowser.json`.

 use anyhow::{Context, Result};
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use tokio::fs;

 use crate::update::host_sudo;
@@ -117,6 +117,197 @@ fn shell_quote(s: &str) -> String {
    s.replace('\'', "'\\''")
 }

+/// Save a complete purchase without overwriting any existing directory entry.
+/// Both host and rootless-namespace paths publish with a no-clobber hard link.
+pub async fn save_new_file(dir: &Path, name: &str, bytes: &[u8]) -> Result<PathBuf> {
+    save_new_file_with(dir, name, bytes, write_via_userns).await
+}
+
+fn validate_filename(name: &str) -> Result<()> {
+    anyhow::ensure!(
+        !name.is_empty()
+            && name != "."
+            && name != ".."
+            && !name.contains(['/', '\\', '\0'])
+            && name.len() <= 255,
+        "Invalid purchased filename"
+    );
+    Ok(())
+}
+
+async fn save_new_file_with<F, Fut>(
+    dir: &Path,
+    name: &str,
+    bytes: &[u8],
+    fallback: F,
+) -> Result<PathBuf>
+where
+    F: FnOnce(PathBuf, String, Vec<u8>) -> Fut,
+    Fut: std::future::Future<Output = Result<PathBuf>>,
+{
+    validate_filename(name)?;
+    // Never follow a user-created destination directory symlink.
+    match fs::symlink_metadata(dir).await {
+        Ok(meta) => anyhow::ensure!(meta.is_dir(), "Files destination is not a directory"),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        Err(error) => return Err(error.into()),
+    }
+    save_after_direct_result(
+        write_direct(dir, name, bytes).await,
+        dir,
+        name,
+        bytes,
+        fallback,
+    )
+    .await
+}
+
+async fn save_after_direct_result<F, Fut>(
+    result: std::io::Result<PathBuf>,
+    dir: &Path,
+    name: &str,
+    bytes: &[u8],
+    fallback: F,
+) -> Result<PathBuf>
+where
+    F: FnOnce(PathBuf, String, Vec<u8>) -> Fut,
+    Fut: std::future::Future<Output = Result<PathBuf>>,
+{
+    match result {
+        Ok(path) => Ok(path),
+        Err(error) if error.kind() == std::io::ErrorKind::PermissionDenied => {
+            fallback(dir.to_owned(), name.to_owned(), bytes.to_vec())
+                .await
+                .context("Saving purchase in Files user namespace")
+        }
+        Err(error) => Err(error).context("Saving purchase in Files"),
+    }
+}
+
+fn numbered_name(name: &str, attempt: usize) -> String {
+    if attempt == 1 {
+        return name.to_owned();
+    }
+    match name.rsplit_once('.') {
+        Some((stem, extension)) if !stem.is_empty() => format!("{stem} ({attempt}).{extension}"),
+        _ => format!("{name} ({attempt})"),
+    }
+}
+
+struct PendingFile(PathBuf);
+impl Drop for PendingFile {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_file(&self.0);
+    }
+}
+
+async fn write_direct(dir: &Path, name: &str, bytes: &[u8]) -> std::io::Result<PathBuf> {
+    use std::os::unix::fs::PermissionsExt;
+    use tokio::io::AsyncWriteExt;
+    fs::create_dir_all(dir).await?;
+    let temp_path = dir.join(format!(".archy-saving-{}", uuid::Uuid::new_v4()));
+    let mut file = fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(&temp_path)
+        .await?;
+    let temp = PendingFile(temp_path);
+    file.write_all(bytes).await?;
+    file.set_permissions(std::fs::Permissions::from_mode(0o644))
+        .await?;
+    file.sync_all().await?;
+    for attempt in 1..=100 {
+        let target = dir.join(numbered_name(name, attempt));
+        match fs::hard_link(&temp.0, &target).await {
+            Ok(()) => return Ok(target),
+            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+            Err(error) => return Err(error),
+        }
+    }
+    Err(std::io::Error::new(
+        std::io::ErrorKind::AlreadyExists,
+        "Too many existing copies; purchase cache retained",
+    ))
+}
+
+// Positional arguments carry all user-controlled text. mktemp prevents temp-name
+// collisions; ln -T refuses files, symlinks and directories, including races.
+const WRITE_VIA_USERNS: &str = r#"set -eu
+dir=$1
+name=$2
+expected=$3
+[ ! -L "$dir" ] || exit 1
+if [ ! -d "$dir" ]; then
+    mkdir -p -- "$dir"
+    chown --reference="$(dirname -- "$dir")" -- "$dir"
+fi
+tmp=$(mktemp "$dir/.archy-saving.XXXXXXXXXX")
+trap 'rm -f -- "$tmp"' EXIT HUP INT TERM
+cat > "$tmp"
+[ "$(wc -c < "$tmp")" -eq "$expected" ] || exit 1
+chown --reference="$dir" -- "$tmp"
+chmod 0644 -- "$tmp"
+sync -f -- "$tmp"
+stem=$name
+ext=
+case "$name" in
+    *.*) prefix=${name%.*}; if [ -n "$prefix" ]; then stem=$prefix; ext=.${name##*.}; fi ;;
+esac
+n=1
+while [ "$n" -le 100 ]; do
+    candidate=$name
+    if [ "$n" -gt 1 ]; then candidate="$stem ($n)$ext"; fi
+    dst="$dir/$candidate"
+    if ln -T -- "$tmp" "$dst" 2>/dev/null; then
+        printf '%s' "$candidate"
+        exit 0
+    fi
+    # A conflict may be a dangling symlink; never follow it or overwrite it.
+    if [ ! -e "$dst" ] && [ ! -L "$dst" ]; then exit 1; fi
+    n=$((n + 1))
+done
+exit 1
+"#;
+
+async fn write_via_userns(dir: PathBuf, name: String, bytes: Vec<u8>) -> Result<PathBuf> {
+    use tokio::io::AsyncWriteExt;
+    let mut child = tokio::process::Command::new("podman")
+        .args(["unshare", "sh", "-c", WRITE_VIA_USERNS, "sh"])
+        .arg(&dir)
+        .arg(&name)
+        .arg(bytes.len().to_string())
+        .kill_on_drop(true)
+        .stdin(std::process::Stdio::piped())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .spawn()
+        .context("Starting Files namespace writer")?;
+    let mut stdin = child.stdin.take().context("Files writer stdin missing")?;
+    let operation = async {
+        let fed = stdin.write_all(&bytes).await;
+        drop(stdin);
+        let output = child.wait_with_output().await?;
+        anyhow::ensure!(
+            output.status.success(),
+            "Files namespace writer failed: {}",
+            output.status
+        );
+        fed.context("Sending purchase bytes to Files")?;
+        let chosen =
+            String::from_utf8(output.stdout).context("Files writer returned an invalid name")?;
+        validate_filename(&chosen)?;
+        anyhow::ensure!(
+            (1..=100).any(|n| numbered_name(&name, n) == chosen),
+            "Files writer returned an unexpected name"
+        );
+        Ok(dir.join(chosen))
+    };
+    tokio::time::timeout(std::time::Duration::from_secs(120), operation)
+        .await
+        .context("Files namespace writer timed out")?
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -152,3 +343,231 @@ mod tests {
        assert_eq!(second, EnsureOutcome::Unchanged);
    }
 }
+
+#[cfg(test)]
+mod purchase_write_tests {
+    use super::*;
+    use std::{
+        collections::HashSet,
+        os::unix::fs::{symlink, PermissionsExt},
+    };
+
+    fn no_temps(dir: &Path) {
+        assert!(std::fs::read_dir(dir).unwrap().all(|e| !e
+            .unwrap()
+            .file_name()
+            .to_string_lossy()
+            .starts_with(".archy-saving")));
+    }
+
+    #[tokio::test]
+    async fn direct_write_uses_complete_bytes_and_preserves_originals() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join("song.mp3"), b"original")
+            .await
+            .unwrap();
+        let target = save_new_file(dir.path(), "song.mp3", b"new").await.unwrap();
+        assert_eq!(target.file_name().unwrap(), "song (2).mp3");
+        assert_eq!(fs::read(target).await.unwrap(), b"new");
+        assert_eq!(
+            fs::read(dir.path().join("song.mp3")).await.unwrap(),
+            b"original"
+        );
+        no_temps(dir.path());
+    }
+
+    #[tokio::test]
+    async fn simultaneous_saves_publish_unique_complete_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut tasks = Vec::new();
+        for n in 0..24u8 {
+            let dir = dir.path().to_owned();
+            tasks.push(tokio::spawn(async move {
+                let bytes = vec![n; 32768];
+                let path = save_new_file(&dir, "same.bin", &bytes).await.unwrap();
+                assert_eq!(fs::read(&path).await.unwrap(), bytes);
+                path
+            }));
+        }
+        let mut paths = HashSet::new();
+        for task in tasks {
+            assert!(paths.insert(task.await.unwrap()));
+        }
+        assert_eq!(paths.len(), 24);
+        no_temps(dir.path());
+    }
+
+    #[tokio::test]
+    async fn existing_directories_and_dangling_symlinks_are_conflicts() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::create_dir(dir.path().join("name")).await.unwrap();
+        symlink("missing", dir.path().join("name (2)")).unwrap();
+        let path = save_new_file(dir.path(), "name", b"new").await.unwrap();
+        assert_eq!(path.file_name().unwrap(), "name (3)");
+        assert!(dir.path().join("name").is_dir());
+        assert!(fs::symlink_metadata(dir.path().join("name (2)"))
+            .await
+            .unwrap()
+            .is_symlink());
+        no_temps(dir.path());
+    }
+
+    #[tokio::test]
+    async fn invalid_names_and_symlink_destination_are_refused() {
+        let dir = tempfile::tempdir().unwrap();
+        for name in [
+            "",
+            ".",
+            "..",
+            "../escape",
+            "/absolute",
+            "a/b",
+            "a\\b",
+            "a\0b",
+        ] {
+            assert!(save_new_file(dir.path(), name, b"bytes").await.is_err());
+        }
+        let outside = tempfile::tempdir().unwrap();
+        symlink(outside.path(), dir.path().join("Music")).unwrap();
+        assert!(save_new_file(&dir.path().join("Music"), "song", b"bytes")
+            .await
+            .is_err());
+        assert_eq!(std::fs::read_dir(outside.path()).unwrap().count(), 0);
+    }
+
+    #[tokio::test]
+    async fn collision_limit_preserves_all_files_and_cleans_temporary_data() {
+        let dir = tempfile::tempdir().unwrap();
+        for n in 1..=100 {
+            fs::write(dir.path().join(numbered_name("a.txt", n)), b"keep")
+                .await
+                .unwrap();
+        }
+        assert!(save_new_file(dir.path(), "a.txt", b"new").await.is_err());
+        for n in 1..=100 {
+            assert_eq!(
+                fs::read(dir.path().join(numbered_name("a.txt", n)))
+                    .await
+                    .unwrap(),
+                b"keep"
+            );
+        }
+        no_temps(dir.path());
+    }
+
+    #[tokio::test]
+    async fn permission_fallback_is_exercised_without_skipping_as_root() {
+        let dir = tempfile::tempdir().unwrap();
+        let result = save_after_direct_result(
+            Err(std::io::ErrorKind::PermissionDenied.into()),
+            dir.path(),
+            "a",
+            b"abc",
+            |dir, name, bytes| async move {
+                assert_eq!(bytes, b"abc");
+                Ok(dir.join(name))
+            },
+        )
+        .await
+        .unwrap();
+        assert_eq!(result, dir.path().join("a"));
+        assert!(save_after_direct_result(
+            Err(std::io::ErrorKind::PermissionDenied.into()),
+            dir.path(),
+            "a",
+            b"abc",
+            |_, _, _| async { anyhow::bail!("namespace unavailable") }
+        )
+        .await
+        .unwrap_err()
+        .to_string()
+        .contains("namespace"));
+        assert!(save_after_direct_result(
+            Err(std::io::ErrorKind::StorageFull.into()),
+            dir.path(),
+            "a",
+            b"abc",
+            |_, _, _| async { panic!("disk full must not trigger permission fallback") }
+        )
+        .await
+        .is_err());
+    }
+
+    async fn run_script(
+        dir: &Path,
+        name: &str,
+        bytes: &[u8],
+        expected: usize,
+    ) -> std::process::Output {
+        use tokio::io::AsyncWriteExt;
+        let mut child = tokio::process::Command::new("sh")
+            .args(["-c", WRITE_VIA_USERNS, "sh"])
+            .arg(dir)
+            .arg(name)
+            .arg(expected.to_string())
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .spawn()
+            .unwrap();
+        let mut input = child.stdin.take().unwrap();
+        input.write_all(bytes).await.unwrap();
+        drop(input);
+        child.wait_with_output().await.unwrap()
+    }
+
+    #[tokio::test]
+    async fn namespace_script_preserves_names_bytes_modes_and_existing_entries() {
+        let dir = tempfile::tempdir().unwrap();
+        let folder = dir.path().join("Music");
+        let name = "song ' $() ; #.mp3";
+        for n in 1..=2 {
+            let output = run_script(&folder, name, b"abc", 3).await;
+            assert!(
+                output.status.success(),
+                "{}",
+                String::from_utf8_lossy(&output.stderr)
+            );
+            let chosen = String::from_utf8(output.stdout).unwrap();
+            assert_eq!(chosen, numbered_name(name, n));
+            let path = folder.join(chosen);
+            assert_eq!(fs::read(&path).await.unwrap(), b"abc");
+            assert_eq!(
+                fs::metadata(path).await.unwrap().permissions().mode() & 0o777,
+                0o644
+            );
+        }
+        no_temps(&folder);
+    }
+
+    #[tokio::test]
+    async fn namespace_script_refuses_truncated_input_and_cleans_up() {
+        let dir = tempfile::tempdir().unwrap();
+        let output = run_script(dir.path(), "never.bin", b"partial", 100).await;
+        assert!(!output.status.success());
+        assert!(!dir.path().join("never.bin").exists());
+        no_temps(dir.path());
+    }
+
+    #[tokio::test]
+    async fn namespace_script_does_not_link_inside_existing_directory() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::create_dir(dir.path().join("name")).await.unwrap();
+        symlink("missing", dir.path().join("name (2)")).unwrap();
+        let output = run_script(dir.path(), "name", b"abc", 3).await;
+        assert!(output.status.success());
+        assert_eq!(output.stdout, b"name (3)");
+        assert_eq!(
+            std::fs::read_dir(dir.path().join("name")).unwrap().count(),
+            0
+        );
+        no_temps(dir.path());
+    }
+
+    #[test]
+    fn names_keep_extensions_and_dotfiles() {
+        assert_eq!(numbered_name("a.tar.gz", 2), "a.tar (2).gz");
+        assert_eq!(numbered_name(".hidden", 2), ".hidden (2)");
+        assert_eq!(numbered_name("README", 2), "README (2)");
+    }
+}
@@ -0,0 +1,254 @@
+//! Consistent, private snapshots for declaratively opted-in runtime migrations.
+use anyhow::{bail, Context, Result};
+use archipelago_container::AppManifest;
+use std::os::unix::fs::PermissionsExt;
+use std::path::{Path, PathBuf};
+
+pub fn enabled(manifest: &AppManifest) -> Result<bool> {
+    match manifest.app.extensions.get("backup_before_runtime_change") {
+        None => Ok(false),
+        Some(value) => value
+            .as_bool()
+            .context("backup_before_runtime_change must be boolean"),
+    }
+}
+
+fn relative_sources(manifest: &AppManifest, data_dir: &Path) -> Result<Vec<PathBuf>> {
+    let mut sources = Vec::new();
+    for volume in &manifest.app.volumes {
+        if volume.options.iter().any(|v| v == "ro") || volume.volume_type == "tmpfs" {
+            continue;
+        }
+        // A runtime socket is a connection, not application state.
+        if volume.source == "/run/user/1000/podman/podman.sock" {
+            continue;
+        }
+        if volume.volume_type != "bind" {
+            bail!("runtime migration backup requires bind-mounted persistent state");
+        }
+        let path = Path::new(&volume.source);
+        let relative = path
+            .strip_prefix(data_dir)
+            .context("runtime migration state must be inside the node data directory")?;
+        if relative.starts_with("migration-backups") {
+            bail!("migration backup cannot include its own archive directory");
+        }
+        if relative.as_os_str().is_empty()
+            || relative
+                .components()
+                .any(|c| !matches!(c, std::path::Component::Normal(_)))
+        {
+            bail!("invalid runtime migration state path");
+        }
+        sources.push(relative.to_path_buf());
+    }
+    sources.sort();
+    sources.dedup();
+    let mut roots: Vec<PathBuf> = Vec::new();
+    for source in sources {
+        if !roots.iter().any(|root| source.starts_with(root)) {
+            roots.push(source);
+        }
+    }
+    if roots.is_empty() {
+        bail!("runtime migration backup has no persistent state mounts");
+    }
+    Ok(roots)
+}
+
+/// Caller must gracefully stop the app before this function, and resume the old
+/// service if it fails. No source files are changed or deleted by this operation.
+pub async fn snapshot(
+    manifest: &AppManifest,
+    data_dir: &Path,
+    previous_unit: Option<&[u8]>,
+) -> Result<PathBuf> {
+    let mut command = tokio::process::Command::new("podman");
+    command.args(["unshare", "tar"]);
+    snapshot_with_command(manifest, data_dir, previous_unit, command).await
+}
+
+async fn snapshot_with_command(
+    manifest: &AppManifest,
+    data_dir: &Path,
+    previous_unit: Option<&[u8]>,
+    mut command: tokio::process::Command,
+) -> Result<PathBuf> {
+    let sources = relative_sources(manifest, data_dir)?;
+    let canonical_root = tokio::fs::canonicalize(data_dir).await?;
+    for source in &sources {
+        let path = data_dir.join(source);
+        if tokio::fs::symlink_metadata(&path)
+            .await?
+            .file_type()
+            .is_symlink()
+        {
+            bail!("runtime migration state mount is a symlink; explicit backup required");
+        }
+        let canonical = tokio::fs::canonicalize(&path).await?;
+        if !canonical.starts_with(&canonical_root) {
+            bail!("runtime migration state path resolves outside node data directory");
+        }
+    }
+    let root = data_dir.join("migration-backups");
+    tokio::fs::create_dir_all(&root).await?;
+    tokio::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).await?;
+    let dir = root.join(uuid::Uuid::new_v4().to_string());
+    tokio::fs::create_dir(&dir).await?;
+    tokio::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).await?;
+    if let Some(unit) = previous_unit {
+        let path = dir.join("previous.container");
+        tokio::fs::write(&path, unit).await?;
+        tokio::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).await?;
+        tokio::fs::File::open(&path).await?.sync_all().await?;
+    }
+    let partial = dir.join("state.tar.partial");
+    let archive = dir.join("state.tar");
+    let output = command
+        .args([
+            "--create",
+            "--numeric-owner",
+            "--acls",
+            "--xattrs",
+            "--file",
+        ])
+        .arg(&partial)
+        .arg("--directory")
+        .arg(data_dir)
+        .arg("--")
+        .args(&sources)
+        .output()
+        .await
+        .context("start rootless migration snapshot")?;
+    if !output.status.success() {
+        // No tar stderr in public logs: it can contain private filenames.
+        let _ = tokio::fs::remove_file(&partial).await;
+        bail!("persistent-state snapshot failed; original state was left intact");
+    }
+    tokio::fs::set_permissions(&partial, std::fs::Permissions::from_mode(0o600)).await?;
+    tokio::fs::File::open(&partial).await?.sync_all().await?;
+    tokio::fs::rename(&partial, &archive).await?;
+    let metadata = serde_json::json!({"app": manifest.app.id, "version": manifest.app.version,
+        "network": manifest.app.container.network, "capabilities": manifest.app.security.capabilities, "sources": sources});
+    tokio::fs::write(
+        dir.join("metadata.json"),
+        serde_json::to_vec_pretty(&metadata)?,
+    )
+    .await?;
+    tokio::fs::File::open(&dir).await?.sync_all().await?;
+    Ok(archive)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn portainer() -> AppManifest {
+        AppManifest::parse(include_str!("../../../../apps/portainer/manifest.yml")).unwrap()
+    }
+    #[tokio::test]
+    async fn stopped_state_archive_round_trips_database_compose_and_old_unit() {
+        let dir = tempfile::tempdir().unwrap();
+        let state = dir.path().join("portainer");
+        tokio::fs::create_dir_all(state.join("compose"))
+            .await
+            .unwrap();
+        tokio::fs::write(state.join("portainer.db"), b"fixture database")
+            .await
+            .unwrap();
+        tokio::fs::write(state.join("compose/stack.yml"), b"services: {}\n")
+            .await
+            .unwrap();
+        let mut m = portainer();
+        m.app.volumes[0].source = state.display().to_string();
+        m.app.volumes[1].source = state.join("compose").display().to_string();
+        let archive = snapshot_with_command(
+            &m,
+            dir.path(),
+            Some(b"old unit"),
+            tokio::process::Command::new("tar"),
+        )
+        .await
+        .unwrap();
+        assert_eq!(
+            std::fs::metadata(&archive).unwrap().permissions().mode() & 0o777,
+            0o600
+        );
+        assert_eq!(
+            tokio::fs::read(archive.parent().unwrap().join("previous.container"))
+                .await
+                .unwrap(),
+            b"old unit"
+        );
+        let restored = tempfile::tempdir().unwrap();
+        assert!(tokio::process::Command::new("tar")
+            .arg("-xf")
+            .arg(archive)
+            .arg("-C")
+            .arg(restored.path())
+            .status()
+            .await
+            .unwrap()
+            .success());
+        assert_eq!(
+            tokio::fs::read(restored.path().join("portainer/portainer.db"))
+                .await
+                .unwrap(),
+            b"fixture database"
+        );
+        assert_eq!(
+            tokio::fs::read(restored.path().join("portainer/compose/stack.yml"))
+                .await
+                .unwrap(),
+            b"services: {}\n"
+        );
+        assert_eq!(
+            tokio::fs::read(state.join("portainer.db")).await.unwrap(),
+            b"fixture database"
+        );
+    }
+
+    #[tokio::test]
+    async fn failed_snapshot_never_publishes_archive_or_changes_original_state() {
+        let dir = tempfile::tempdir().unwrap();
+        let state = dir.path().join("portainer");
+        tokio::fs::create_dir_all(state.join("compose"))
+            .await
+            .unwrap();
+        tokio::fs::write(state.join("portainer.db"), b"unchanged")
+            .await
+            .unwrap();
+        let mut m = portainer();
+        m.app.volumes[0].source = state.display().to_string();
+        m.app.volumes[1].source = state.join("compose").display().to_string();
+        assert!(
+            snapshot_with_command(&m, dir.path(), None, tokio::process::Command::new("false"))
+                .await
+                .is_err()
+        );
+        assert_eq!(
+            tokio::fs::read(state.join("portainer.db")).await.unwrap(),
+            b"unchanged"
+        );
+        for entry in std::fs::read_dir(dir.path().join("migration-backups")).unwrap() {
+            assert!(!entry.unwrap().path().join("state.tar").exists());
+        }
+    }
+
+    #[test]
+    fn backup_covers_all_portainer_state_once_and_excludes_runtime_socket() {
+        let m = portainer();
+        assert!(enabled(&m).unwrap());
+        assert_eq!(
+            relative_sources(&m, Path::new("/var/lib/archipelago")).unwrap(),
+            vec![PathBuf::from("portainer")]
+        );
+    }
+    #[test]
+    fn backup_refuses_unknown_state_locations_instead_of_silently_omitting_them() {
+        let mut m = portainer();
+        m.app.volumes[0].source = "/other/operator/state".into();
+        assert!(relative_sources(&m, Path::new("/var/lib/archipelago")).is_err());
+        m.app.volumes[0].source = "/var/lib/archipelago/../secret".into();
+        assert!(relative_sources(&m, Path::new("/var/lib/archipelago")).is_err());
+    }
+}
@@ -12,6 +12,7 @@ pub mod hooks;
 pub mod image_policy;
 pub mod image_versions;
 pub mod lnd;
+pub mod migration_backup;
 pub mod prod_orchestrator;
 pub mod quadlet;
 pub mod registry;
@@ -36,6 +36,11 @@ use std::sync::Arc;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::sync::{Mutex, RwLock};

+/// Refusal before installation has created state or changed any dependency.
+#[derive(Debug, thiserror::Error)]
+#[error("{0}")]
+pub struct InstallPrerequisiteError(pub String);
+
 use crate::config::{Config, ContainerRuntime as ConfigContainerRuntime};
 use crate::container::bitcoin_ui;
 use crate::container::quadlet;
@@ -91,6 +96,23 @@ fn is_builtin_network_mode(network: &str) -> bool {
    )
 }

+// Only an explicitly selected rootless mode establishes drift. An omitted
+// network delegates to Podman and must not recreate unrelated installed apps.
+fn rootless_network_mode_drifted(expected: Option<&str>, actual: &str) -> bool {
+    matches!(expected, Some("slirp4netns" | "pasta"))
+        && !actual.trim().is_empty()
+        && actual.trim().split(':').next() != expected
+}
+
+fn missing_declared_capability(expected: &[String], actual: &[String]) -> bool {
+    expected.iter().any(|required| {
+        let required = required.strip_prefix("CAP_").unwrap_or(required);
+        !actual
+            .iter()
+            .any(|cap| cap.strip_prefix("CAP_").unwrap_or(cap) == required)
+    })
+}
+
 fn uses_pasta_network(manifest: &AppManifest) -> bool {
    manifest.app.container.network.as_deref() == Some("pasta")
 }
@@ -2464,6 +2486,8 @@ impl ProdContainerOrchestrator {
                            .await
                        {
                            tracing::info!(app_id = %app_id, container = %name, "container published-port drift detected — recreating");
+                            self.backup_runtime_change(&name, &resolved_manifest)
+                                .await?;
                            let _ = self.runtime.stop_container(&name).await;
                            let _ = self.runtime.remove_container(&name).await;
                            self.install_fresh(lm).await?;
@@ -2499,6 +2523,8 @@ impl ProdContainerOrchestrator {
                                return Ok(ReconcileAction::NoOp);
                            }
                            tracing::info!(app_id = %app_id, container = %name, "container env drift detected — recreating");
+                            self.backup_runtime_change(&name, &resolved_manifest)
+                                .await?;
                            let _ = self.runtime.stop_container(&name).await;
                            let _ = self.runtime.remove_container(&name).await;
                            self.install_fresh(lm).await?;
@@ -2555,6 +2581,8 @@ impl ProdContainerOrchestrator {
                                .await
                        {
                            tracing::info!(app_id = %app_id, container = %name, "stopped container env/port drift detected — recreating");
+                            self.backup_runtime_change(&name, &resolved_manifest)
+                                .await?;
                            let _ = self.runtime.remove_container(&name).await;
                            self.install_fresh(lm).await?;
                            return Ok(ReconcileAction::Installed);
@@ -2611,6 +2639,8 @@ impl ProdContainerOrchestrator {
                        self.prepare_for_start(&resolved_manifest).await?;
                        if self.container_env_drifted(&name, &resolved_manifest).await {
                            tracing::info!(app_id = %app_id, container = %name, "created container env drift detected — recreating");
+                            self.backup_runtime_change(&name, &resolved_manifest)
+                                .await?;
                            let _ = self.runtime.remove_container(&name).await;
                            self.install_fresh(lm).await?;
                            return Ok(ReconcileAction::Installed);
@@ -3080,13 +3110,9 @@ impl ProdContainerOrchestrator {
    /// app is a companion (companion.rs owns those units), or when no
    /// unit file exists yet (install_via_quadlet handles first-write).
    ///
-    /// We DON'T restart the .service when content changes — running
-    /// containers keep their current config until an operator-initiated
-    /// restart picks up the new file. That's the right tradeoff: file
-    /// updates are cheap and non-destructive; service restarts are
-    /// destructive (the SIGKILL cascade we're trying to eliminate).
-    /// systemctl --user daemon-reload runs only when content actually
-    /// changed, so steady-state reconcile ticks pay just one fs read.
+    /// Ordinary metadata changes wait for an operator restart. Runtime-affecting
+    /// changes restart the service and retain a durable pending marker until
+    /// that succeeds, including across daemon restarts and failed reloads.
    async fn sync_quadlet_unit(&self, lm: &LoadedManifest, name: &str) -> Result<()> {
        // Companions: same reasoning as migrate_to_quadlet_if_needed —
        // companion.rs renders these units with a different shape, syncing
@@ -3106,7 +3132,7 @@ impl ProdContainerOrchestrator {
        }
        let old_body = tokio::fs::read_to_string(&unit_path)
            .await
-            .unwrap_or_default();
+            .with_context(|| format!("read existing quadlet for {name}"))?;
        let restart_required = quadlet::contains_stale_health_gate(&old_body);

        let mut resolved = lm.manifest.clone();
@@ -3122,49 +3148,49 @@ impl ProdContainerOrchestrator {
            quadlet::network_aliases_changed(&old_body, &new_body);
        let restart_for_exec_change = quadlet::exec_changed(&old_body, &new_body);
        let restart_for_health_change = quadlet::health_cmd_changed(&old_body, &new_body);
-        let changed = quadlet::write_if_changed(&unit, &unit_dir)
-            .await
-            .with_context(|| format!("drift-sync quadlet unit for {name}"))?;
-        if changed {
-            quadlet::daemon_reload_user()
-                .await
-                .context("systemctl --user daemon-reload after drift-syncing quadlet unit")?;
-            tracing::info!(
-                app_id = %lm.manifest.app.id,
-                container = %name,
-                "Quadlet unit drift-synced — file rewritten, .service NOT restarted (operator restart picks up new config)"
-            );
-        }
-        if changed
-            && (restart_required
+        let restart_for_security_change = quadlet::security_changed(&old_body, &new_body);
+        let needs_restart = restart_required
            || restart_for_port_change
            || restart_for_network_alias_change
            || restart_for_exec_change
-                || restart_for_health_change)
-        {
+            || restart_for_health_change
+            || restart_for_security_change;
+        // Record the obligation BEFORE replacing the unit. A failed reload or
+        // restart must not become a no-op on the next tick just because the
+        // generated file already matches the manifest.
+        let pending = quadlet::RestartObligation::prepare(&unit_path, needs_restart).await?;
+        if pending.is_pending() {
            self.ensure_resolved_source_available(lm).await?;
+        }
+        if needs_restart {
+            self.backup_runtime_change(name, &resolved).await?;
+        }
+        let changed = quadlet::write_if_changed(&unit, &unit_dir)
+            .await
+            .with_context(|| format!("drift-sync quadlet unit for {name}"))?;
+        if changed || pending.is_pending() {
+            quadlet::daemon_reload_user()
+                .await
+                .context("systemctl --user daemon-reload after drift-syncing quadlet unit")?;
+        }
+        if pending.is_pending() {
            let service = unit.service_name();
-            let reason = if restart_required {
-                "stale health gate"
-            } else if restart_for_port_change {
-                "port binding drift"
-            } else if restart_for_network_alias_change {
-                "network alias drift"
-            } else if restart_for_health_change {
-                "health command drift"
-            } else {
-                "exec drift"
-            };
            tracing::info!(
                app_id = %lm.manifest.app.id,
                container = %name,
                service = %service,
-                reason = reason,
-                "Quadlet unit rewrite requires service restart"
+                "Applying pending Quadlet runtime change"
            );
            quadlet::restart_service(&service)
                .await
                .with_context(|| format!("restart drifted quadlet service {service}"))?;
+            pending.complete().await?;
+        } else if changed {
+            tracing::info!(
+                app_id = %lm.manifest.app.id,
+                container = %name,
+                "Quadlet metadata updated; operator restart will apply it"
+            );
        }
        Ok(())
    }
@@ -3866,6 +3892,77 @@ impl ProdContainerOrchestrator {
        Ok(())
    }

+    async fn backup_runtime_change(&self, name: &str, manifest: &AppManifest) -> Result<()> {
+        if !crate::container::migration_backup::enabled(manifest)? {
+            return Ok(());
+        }
+        // A persistent disk/permission failure must not repeatedly stop a
+        // working old service. Reuse the reconciler's bounded repair budget.
+        if !self.should_attempt_repair(name).await {
+            anyhow::bail!("runtime migration retry budget exhausted; original service retained, inspect backup failure before retrying");
+        }
+        // Called only before a known runtime change. No app-specific commands;
+        // opted-in manifests identify their persistent state through bind mounts.
+        let output = tokio::process::Command::new("podman")
+            .args(["inspect", name, "--format", "{{.HostConfig.NetworkMode}}"])
+            .output()
+            .await
+            .context("inspect network before migration backup")?;
+        let present = if output.status.success() {
+            true
+        } else {
+            // A crash after gracefully stopping a --rm Quadlet container can
+            // leave only its data and old unit. Prove absence before snapshotting
+            // stopped state; an inspect/Podman failure is not proof of absence.
+            let exists = tokio::process::Command::new("podman")
+                .args(["container", "exists", name])
+                .status()
+                .await?;
+            if exists.code() != Some(1) {
+                anyhow::bail!("cannot verify existing container before runtime migration backup");
+            }
+            false
+        };
+        let service = format!("{name}.service");
+        let managed = quadlet::unit_exists(name).await;
+        let previous_unit = if managed {
+            Some(
+                tokio::fs::read(quadlet::unit_dir().await?.join(format!("{name}.container")))
+                    .await?,
+            )
+        } else {
+            None
+        };
+        if managed {
+            quadlet::stop_service(&service).await?;
+        } else if present {
+            self.runtime.stop_container(name).await?;
+        }
+        match crate::container::migration_backup::snapshot(
+            manifest,
+            &self.data_dir,
+            previous_unit.as_deref(),
+        )
+        .await
+        {
+            Ok(archive) => {
+                tracing::info!(container = %name, backup = %archive.display(), "Persistent state saved before runtime migration");
+                Ok(())
+            }
+            Err(error) => {
+                // The unit has not been rewritten yet. Restore its previous
+                // service on backup failure and report the migration failure.
+                let restored = if managed {
+                    quadlet::enable_now(&service).await
+                } else {
+                    self.runtime.start_container(name).await
+                };
+                restored.context("restore original app after failed migration snapshot")?;
+                Err(error)
+            }
+        }
+    }
+
    async fn container_env_drifted(&self, name: &str, manifest: &AppManifest) -> bool {
        if cfg!(test) {
            return false;
@@ -3875,6 +3972,52 @@ impl ProdContainerOrchestrator {
            return true;
        }

+        // Generated-unit drift handles managed services; preserve deliberate
+        // systemd drop-in overrides instead of recreating them every tick.
+        let unmanaged = !quadlet::unit_exists(name).await;
+        // Podman's effective bounding set, not Docker-compatible CapAdd (which
+        // can be empty even when Quadlet supplied capabilities).
+        if unmanaged && !manifest.app.security.capabilities.is_empty() {
+            if let Ok(output) = tokio::process::Command::new("podman")
+                .args(["inspect", name, "--format", "{{json .BoundingCaps}}"])
+                .output()
+                .await
+            {
+                if output.status.success() {
+                    if let Ok(actual) = serde_json::from_slice::<Vec<String>>(&output.stdout) {
+                        if missing_declared_capability(&manifest.app.security.capabilities, &actual)
+                        {
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+
+        // Quadlet handles declarative Network= drift above. Legacy rootless
+        // Podman containers need the same convergence when no unit owns them.
+        if unmanaged
+            && matches!(
+                manifest.app.container.network.as_deref(),
+                Some("slirp4netns" | "pasta")
+            )
+        {
+            if let Ok(output) = tokio::process::Command::new("podman")
+                .args(["inspect", name, "--format", "{{.HostConfig.NetworkMode}}"])
+                .output()
+                .await
+            {
+                if output.status.success()
+                    && rootless_network_mode_drifted(
+                        manifest.app.container.network.as_deref(),
+                        &String::from_utf8_lossy(&output.stdout),
+                    )
+                {
+                    return true;
+                }
+            }
+        }
+
        let inspect = tokio::process::Command::new("podman")
            .args([
                "inspect",
@@ -4441,6 +4584,45 @@ impl ContainerOrchestrator for ProdContainerOrchestrator {
    }

    async fn install(&self, app_id: &str) -> Result<String> {
+        let lm = self.loaded(app_id).await?;
+        // Optional shared-service preconditions are checked before recording
+        // installation or creating anything. A headless adapter must not claim
+        // successful installation against a missing indexing stack.
+        if let Some(required) = lm
+            .manifest
+            .app
+            .extensions
+            .get("install_prerequisites")
+            .and_then(|value| value.as_sequence())
+        {
+            let present = self
+                .runtime
+                .list_containers()
+                .await
+                .context("check installed prerequisite services")?;
+            for id in required.iter().filter_map(|value| value.as_str()) {
+                let dependency = self.loaded(id).await.map_err(|_| InstallPrerequisiteError(
+                    format!("Required app {id} is unavailable. Refresh the app catalog before installing {}.",
+                        lm.manifest.app.name)))?;
+                let name = compute_container_name(&dependency.manifest);
+                if !present
+                    .iter()
+                    .any(|container| container.name.trim_start_matches('/') == name)
+                {
+                    let owner = crate::app_ops::owning_package(id);
+                    let title = self
+                        .loaded(owner)
+                        .await
+                        .map(|app| app.manifest.app.name)
+                        .unwrap_or(dependency.manifest.app.name);
+                    return Err(InstallPrerequisiteError(format!(
+                        "Install {title} first, then install {}.",
+                        lm.manifest.app.name
+                    ))
+                    .into());
+                }
+            }
+        }
        {
            let mut state = self.state.write().await;
            state.disabled.remove(app_id);
@@ -4467,7 +4649,6 @@ impl ContainerOrchestrator for ProdContainerOrchestrator {
        // health verification (the .228 "running but unreachable" failure
        // mode). Routing every install through here means the orchestrator
        // is the one source of truth for what "installed" means.
-        let lm = self.loaded(app_id).await?;
        let name = compute_container_name(&lm.manifest);
        // ensure_running takes the per-app lock itself; release the install
        // path lock first if we hold one (we don't — install is the entry
@@ -4917,6 +5098,78 @@ mod tests {
    /// recovered when its siblings have live containers (the stack is
    /// installed), and left alone when the whole stack is gone or the app
    /// is not a stack member at all.
+    #[tokio::test]
+    async fn gitea_fresh_url_seed_preserves_operator_config_and_reports_write_failure() {
+        let manifest =
+            AppManifest::parse(include_str!("../../../../apps/gitea/manifest.yml")).unwrap();
+        let seed = &manifest.app.files[0];
+        assert!(!seed.overwrite);
+        let content = seed.content.replace("{{HOST_IP}}", "192.0.2.1");
+        assert!(content.contains("ROOT_URL = http://192.0.2.1:3001/"));
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("fresh/app.ini");
+        assert_eq!(
+            ensure_rendered_file(path.to_str().unwrap(), &content, seed.overwrite)
+                .await
+                .unwrap(),
+            HookOutcome::Rewritten
+        );
+        assert!(tokio::fs::read_to_string(&path)
+            .await
+            .unwrap()
+            .contains("ROOT_URL"));
+        let custom =
+            "[server]\nROOT_URL = https://git.example.test/\n[database]\nDB_TYPE = postgres\n";
+        tokio::fs::write(&path, custom).await.unwrap();
+        assert_eq!(
+            ensure_rendered_file(path.to_str().unwrap(), &content, seed.overwrite)
+                .await
+                .unwrap(),
+            HookOutcome::Unchanged
+        );
+        assert_eq!(tokio::fs::read_to_string(&path).await.unwrap(), custom);
+        let impossible = path.join("app.ini");
+        assert!(
+            ensure_rendered_file(impossible.to_str().unwrap(), &content, seed.overwrite)
+                .await
+                .is_err()
+        );
+    }
+
+    #[test]
+    fn ssh_sandbox_capability_repair_uses_bounding_set_and_preserves_extra_overrides() {
+        let required = vec!["CHOWN".into(), "SYS_CHROOT".into()];
+        assert!(missing_declared_capability(
+            &required,
+            &["CAP_CHOWN".into()]
+        ));
+        assert!(!missing_declared_capability(
+            &required,
+            &["CAP_CHOWN".into(), "CAP_SYS_CHROOT".into()]
+        ));
+        assert!(!missing_declared_capability(
+            &required,
+            &["CHOWN".into(), "SYS_CHROOT".into(), "CAP_KILL".into()]
+        ));
+    }
+
+    #[test]
+    fn explicit_rootless_network_change_converges_without_guessing_defaults() {
+        assert!(rootless_network_mode_drifted(Some("slirp4netns"), "pasta"));
+        assert!(rootless_network_mode_drifted(Some("slirp4netns"), "bridge"));
+        assert!(!rootless_network_mode_drifted(
+            Some("slirp4netns"),
+            "slirp4netns"
+        ));
+        assert!(!rootless_network_mode_drifted(
+            Some("slirp4netns"),
+            "slirp4netns:allow_host_loopback=true"
+        ));
+        assert!(!rootless_network_mode_drifted(None, "pasta"));
+        assert!(!rootless_network_mode_drifted(Some("slirp4netns"), ""));
+        assert!(!rootless_network_mode_drifted(Some("archy-net"), "bridge"));
+    }
+
    #[test]
    fn absent_stack_member_recovery_requires_a_live_sibling() {
        let present: HashSet<String> = ["indeedhub-redis", "indeedhub-relay", "indeedhub"]
@@ -5598,6 +5851,38 @@ app:
        orch
    }

+    #[tokio::test]
+    async fn missing_install_prerequisite_refuses_without_inventory_or_container_mutation() {
+        let rt = Arc::new(MockRuntime::default());
+        let orch = orch_with(rt.clone()).await;
+        let mut app = pull_manifest("indexer-adapter", "docker.io/library/alpine:3.20");
+        app.app.extensions.insert(
+            "install_prerequisites".into(),
+            serde_yaml::to_value(vec!["shared-index"]).unwrap(),
+        );
+        orch.insert_manifest_for_test(app, PathBuf::from("/tmp"))
+            .await;
+        orch.insert_manifest_for_test(
+            pull_manifest("shared-index", "index:1"),
+            PathBuf::from("/tmp"),
+        )
+        .await;
+        let error = orch.install("indexer-adapter").await.unwrap_err();
+        assert!(error.downcast_ref::<InstallPrerequisiteError>().is_some());
+        assert!(!crate::crash_recovery::load_installed_apps(&orch.data_dir)
+            .await
+            .contains("indexer-adapter"));
+        assert_eq!(rt.calls(), vec!["list_containers"]);
+        // An installed prerequisite satisfies the guard; it is never recreated
+        // or reconfigured as part of installing this adapter.
+        rt.set_state("shared-index", ContainerState::Running);
+        orch.install("indexer-adapter").await.unwrap();
+        assert!(!rt
+            .calls()
+            .iter()
+            .any(|c| c.starts_with("create_container:shared-index")));
+    }
+
    fn pull_manifest_with_dynamic_env(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    derived_env:\n      - key: FM_API_URL\n        template: \"ws://{{{{HOST_MDNS}}}}:8174\"\n    secret_env:\n      - key: FM_BITCOIND_PASSWORD\n        secret_file: bitcoin-rpc-password\n  environment:\n    - STATIC=1\n"
@@ -390,7 +390,10 @@ fn shell_join(parts: &[String]) -> String {
        .iter()
        .map(|p| {
            let p = p.replace(['\r', '\n'], " ").replace('%', "%%");
-            if p.is_empty() || p.chars().any(|c| c.is_whitespace() || "\"\\$`".contains(c)) {
+            if p.is_empty()
+                || p.chars()
+                    .any(|c| c.is_whitespace() || "'\"\\$`".contains(c))
+            {
                let escaped = p
                    .replace('\\', "\\\\")
                    .replace('"', "\\\"")
@@ -410,7 +413,7 @@ fn quote_environment(env: &str) -> String {
    if env.is_empty()
        || env
            .chars()
-            .any(|c| c.is_whitespace() || "\"\\$`".contains(c))
+            .any(|c| c.is_whitespace() || "'\"\\$`".contains(c))
    {
        let escaped = env
            .replace('\\', "\\\\")
@@ -938,12 +941,77 @@ pub fn health_cmd_changed(old_body: &str, new_body: &str) -> bool {
            != directive_values(new_body, "HealthRetries=")
 }

+/// A unit rewrite and a successful systemd restart are separate operations.
+/// Keep the restart obligation across errors or a management-daemon restart.
+pub struct RestartObligation {
+    marker: PathBuf,
+    pending: bool,
+}
+
+impl RestartObligation {
+    pub async fn prepare(unit_path: &Path, newly_required: bool) -> Result<Self> {
+        let marker = unit_path.with_extension("restart-pending");
+        if newly_required {
+            // Contents contain no manifest environment or credentials. sync_all
+            // makes the obligation durable before the subsequent unit rename.
+            let file = tokio::fs::OpenOptions::new()
+                .write(true)
+                .create(true)
+                .truncate(false)
+                .open(&marker)
+                .await
+                .context("record pending Quadlet restart")?;
+            file.sync_all().await?;
+            if let Some(parent) = marker.parent() {
+                tokio::fs::File::open(parent).await?.sync_all().await?;
+            }
+        }
+        let pending = tokio::fs::try_exists(&marker).await?;
+        Ok(Self { marker, pending })
+    }
+
+    pub fn is_pending(&self) -> bool {
+        self.pending
+    }
+
+    /// Call only after systemd accepted the replacement service successfully.
+    pub async fn complete(self) -> Result<()> {
+        if self.pending {
+            tokio::fs::remove_file(&self.marker)
+                .await
+                .context("clear completed Quadlet restart")?;
+            if let Some(parent) = self.marker.parent() {
+                tokio::fs::File::open(parent).await?.sync_all().await?;
+            }
+        }
+        Ok(())
+    }
+}
+
 pub fn publish_ports_changed(old_body: &str, new_body: &str) -> bool {
    let old_ports = directive_values(old_body, "PublishPort=");
    let new_ports = directive_values(new_body, "PublishPort=");
    old_ports != new_ports
 }

+pub fn security_changed(old_body: &str, new_body: &str) -> bool {
+    [
+        "AddCapability=",
+        "DropCapability=",
+        "NoNewPrivileges=",
+        "ReadOnly=",
+        "User=",
+    ]
+    .iter()
+    .any(|directive| {
+        let mut old = directive_values(old_body, directive);
+        let mut new = directive_values(new_body, directive);
+        old.sort();
+        new.sort();
+        old != new
+    })
+}
+
 pub fn network_aliases_changed(old_body: &str, new_body: &str) -> bool {
    let old_network = directive_values(old_body, "Network=");
    let new_network = directive_values(new_body, "Network=");
@@ -1329,6 +1397,18 @@ app:
        );
    }

+    #[test]
+    fn apostrophes_survive_quadlet_argument_and_environment_parsing() {
+        // A whitespace-free Node script reproduced this in a real Quadlet:
+        // unquoted apostrophes were consumed by the parser, changing JS strings
+        // into identifiers and preventing the app from starting.
+        assert_eq!(
+            shell_join(&["require('http')".into()]),
+            "\"require('http')\""
+        );
+        assert_eq!(quote_environment("NAME=O'Brien"), "\"NAME=O'Brien\"");
+    }
+
    #[test]
    fn quote_environment_quotes_values_with_spaces() {
        assert_eq!(
@@ -1541,6 +1621,26 @@ app:
        assert!(!s.contains("Network=host"));
    }

+    #[test]
+    fn portainer_catalog_network_repairs_same_node_routing_without_exposing_backend() {
+        let manifest = AppManifest::parse(include_str!("../../../../apps/portainer/manifest.yml"))
+            .expect("shipped Portainer manifest must parse");
+        let new = QuadletUnit::from_manifest(&manifest, "portainer").render();
+        assert!(new.contains("Network=slirp4netns\n"));
+        assert!(!new.contains("NetworkAlias="));
+        assert!(new.contains("PublishPort=127.0.0.1:9000:9000/tcp"));
+        assert!(!new.contains("PublishPort=0.0.0.0"));
+        // The upgrade changes networking only: retain both state mounts and the
+        // existing rootless socket, without an app.ini or repository rewrite.
+        assert!(new.contains("Volume=/var/lib/archipelago/portainer:/data"));
+        assert!(new.contains("Volume=/var/lib/archipelago/portainer/compose:/data/compose"));
+        assert!(new.contains("Volume=/run/user/1000/podman/podman.sock:/var/run/docker.sock"));
+        let old = new.replace("Network=slirp4netns\n", "");
+        assert!(network_aliases_changed(&old, &new));
+        assert!(!network_aliases_changed(&new, &new));
+        assert!(!publish_ports_changed(&old, &new));
+    }
+
    #[test]
    fn from_manifest_slirp4netns_omits_network_alias() {
        let yaml = r#"
@@ -1891,6 +1991,59 @@ app:
        assert!(!network_aliases_changed(new, new));
    }

+    #[tokio::test]
+    async fn failed_runtime_change_remains_pending_when_unit_already_matches() {
+        let dir = tempfile::tempdir().unwrap();
+        let unit = dir.path().join("portainer.container");
+        tokio::fs::write(&unit, "[Container]\n").await.unwrap();
+        let pending = RestartObligation::prepare(&unit, true).await.unwrap();
+        assert!(pending.is_pending());
+        tokio::fs::write(&unit, "[Container]\nNetwork=slirp4netns\n")
+            .await
+            .unwrap();
+        // Simulate systemctl failure or daemon interruption after unit rewrite.
+        drop(pending);
+        let retry = RestartObligation::prepare(&unit, false).await.unwrap();
+        assert!(
+            retry.is_pending(),
+            "matching unit must not discard failed restart"
+        );
+        retry.complete().await.unwrap();
+        assert!(!RestartObligation::prepare(&unit, false)
+            .await
+            .unwrap()
+            .is_pending());
+    }
+
+    #[tokio::test]
+    async fn pending_runtime_change_errors_are_not_reported_as_success() {
+        let dir = tempfile::tempdir().unwrap();
+        let missing = dir.path().join("missing/app.container");
+        assert!(RestartObligation::prepare(&missing, true).await.is_err());
+        let unit = dir.path().join("app.container");
+        let pending = RestartObligation::prepare(&unit, true).await.unwrap();
+        tokio::fs::remove_file(unit.with_extension("restart-pending"))
+            .await
+            .unwrap();
+        assert!(pending.complete().await.is_err());
+    }
+
+    #[test]
+    fn gitea_ssh_sandbox_capability_is_applied_as_a_runtime_change() {
+        let manifest =
+            AppManifest::parse(include_str!("../../../../apps/gitea/manifest.yml")).unwrap();
+        manifest.validate().unwrap();
+        let new = QuadletUnit::from_manifest(&manifest, "gitea").render();
+        assert!(new.contains("AddCapability=SYS_CHROOT\n"));
+        let old = new.replace("AddCapability=SYS_CHROOT\n", "");
+        assert!(security_changed(&old, &new));
+        assert!(!security_changed(&new, &new));
+        assert!(!security_changed(
+            "AddCapability=CHOWN\nAddCapability=SETUID\n",
+            "AddCapability=SETUID\nAddCapability=CHOWN\n"
+        ));
+    }
+
    #[test]
    fn network_aliases_changed_detects_network_mode_drift() {
        let old = "[Container]\nNetwork=slirp4netns\n";
@@ -238,6 +238,11 @@ pub enum ServeResult {
    Forbidden,
    /// Content not found.
    NotFound,
+    /// The catalog entry and file exist but this node can't read the file.
+    /// Returned before any payment is taken.
+    Unavailable,
+    /// Requested byte range cannot be served; no payment was taken.
+    RangeNotSatisfiable(u64),
 }

 /// Serve a content item by ID with access control and optional range request.
@@ -252,6 +257,39 @@ pub async fn serve_content(
    range: Option<ByteRange>,
    owner_session: bool,
 ) -> Result<ServeResult> {
+    serve_content_with(
+        data_dir,
+        id,
+        payment_token,
+        invoice_hash,
+        peer_did,
+        range,
+        owner_session,
+        |path, range, mime| prepare_content(data_dir, path, range, mime),
+        |token, amount| async move { verify_payment_token(data_dir, &token, amount).await },
+    )
+    .await
+}
+
+// Inject only the read and payment boundaries, so tests can prove ordering
+// without mint access, file-permission assumptions or privileged commands.
+async fn serve_content_with<R, RF, V, VF>(
+    data_dir: &Path,
+    id: &str,
+    payment_token: Option<&str>,
+    invoice_hash: Option<&str>,
+    peer_did: Option<&str>,
+    range: Option<ByteRange>,
+    owner_session: bool,
+    read: R,
+    verify: V,
+) -> Result<ServeResult>
+where
+    R: FnOnce(PathBuf, Option<ByteRange>, String) -> RF,
+    RF: std::future::Future<Output = Result<ServeResult>>,
+    V: FnOnce(String, u64) -> VF,
+    VF: std::future::Future<Output = bool>,
+{
    let catalog = load_catalog(data_dir).await?;
    let item = match catalog.items.iter().find(|i| i.id == id) {
        Some(i) => i,
@@ -314,6 +352,29 @@ pub async fn serve_content(
        return Ok(ServeResult::NotFound);
    }

+    // Refuse unauthorized viewers before opening or reading any bytes.
+    if !owner_session && matches!(item.access, AccessControl::PeersOnly) && !is_known_peer {
+        return Ok(ServeResult::Forbidden);
+    }
+    if !owner_session {
+        if let AccessControl::Paid { price_sats, .. } = &item.access {
+            if payment_token.is_none() && invoice_hash.is_none() {
+                return Ok(ServeResult::PaymentRequired(*price_sats));
+            }
+        }
+    }
+
+    // Finish all file I/O before consuming bearer payment. Merely opening then
+    // reopening after charging still lost payments on read errors or deletion.
+    let prepared = match read(file_path, range, item.mime_type.clone()).await {
+        Ok(result @ (ServeResult::Ok(..) | ServeResult::Partial { .. })) => result,
+        Ok(other) => return Ok(other),
+        Err(error) => {
+            warn!(content_id = %id, "Cannot prepare shared content: {error:#}");
+            return Ok(ServeResult::Unavailable);
+        }
+    };
+
    // Check access control
    if !owner_session {
        match &item.access {
@@ -331,7 +392,7 @@ pub async fn serve_content(
                        "fedimint"
                    };
                    if method_accepted(&item.access, method)
-                        && verify_payment_token(data_dir, token, *price_sats).await
+                        && verify(token.to_owned(), *price_sats).await
                    {
                        authorized = true;
                    }
@@ -358,55 +419,127 @@ pub async fn serve_content(
        }
    }

-    let metadata = fs::metadata(&file_path)
-        .await
-        .context("Failed to read file metadata")?;
-    let total_size = metadata.len();
-
-    // Handle range request for streaming
-    if let Some(range) = range {
-        let start = range.start.min(total_size.saturating_sub(1));
-        let end = range
-            .end
-            .map(|e| e.min(total_size - 1))
-            .unwrap_or(total_size - 1);
-
-        if start > end || start >= total_size {
-            return Ok(ServeResult::NotFound);
+    Ok(prepared)
 }

-        let len = (end - start + 1) as usize;
+async fn prepare_content(
+    data_dir: &Path,
+    path: PathBuf,
+    range: Option<ByteRange>,
+    mime: String,
+) -> Result<ServeResult> {
    use tokio::io::{AsyncReadExt, AsyncSeekExt};
-        let mut file = tokio::fs::File::open(&file_path)
+    let mut file = match fs::OpenOptions::new()
+        .read(true)
+        .custom_flags(libc::O_NONBLOCK)
+        .open(&path)
        .await
-            .context("Failed to open content file")?;
-        file.seek(std::io::SeekFrom::Start(start))
+    {
+        Ok(file) => file,
+        Err(error) if error.kind() == std::io::ErrorKind::PermissionDenied => {
+            let bytes = read_filebrowser_via_userns(data_dir, &path).await?;
+            return slice_prepared_content(bytes, range, mime);
+        }
+        Err(error) => return Err(error).context("Opening shared content"),
+    };
+    let metadata = file.metadata().await?;
+    anyhow::ensure!(metadata.is_file(), "Shared content is not a regular file");
+    let total = metadata.len();
+    if let Some(range) = range {
+        let Some((start, end)) = checked_range(&range, total) else {
+            return Ok(ServeResult::RangeNotSatisfiable(total));
+        };
+        file.seek(std::io::SeekFrom::Start(start)).await?;
+        let len = usize::try_from(end - start + 1).context("Content range is too large")?;
+        let mut bytes = vec![0; len];
+        file.read_exact(&mut bytes)
            .await
-            .context("Failed to seek")?;
-        let mut buf = vec![0u8; len];
-        file.read_exact(&mut buf)
-            .await
-            .context("Failed to read range")?;
-
-        debug!(
-            "Serving content '{}' range {}-{}/{} ({} bytes)",
-            id, start, end, total_size, len
-        );
+            .context("Reading shared content range")?;
        return Ok(ServeResult::Partial {
-            bytes: buf,
-            mime_type: item.mime_type.clone(),
+            bytes,
+            mime_type: mime,
            start,
            end,
-            total: total_size,
+            total,
        });
    }
-
-    let bytes = fs::read(&file_path)
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes)
        .await
-        .context("Failed to read content file")?;
+        .context("Reading shared content")?;
+    Ok(ServeResult::Ok(bytes, mime))
+}

-    debug!("Serving content '{}' ({} bytes)", id, bytes.len());
-    Ok(ServeResult::Ok(bytes, item.mime_type.clone()))
+fn checked_range(range: &ByteRange, total: u64) -> Option<(u64, u64)> {
+    let last = total.checked_sub(1)?;
+    let end = range.end.unwrap_or(last).min(last);
+    (range.start <= end && range.start < total).then_some((range.start, end))
+}
+
+fn slice_prepared_content(
+    bytes: Vec<u8>,
+    range: Option<ByteRange>,
+    mime: String,
+) -> Result<ServeResult> {
+    let total = bytes.len() as u64;
+    match range {
+        None => Ok(ServeResult::Ok(bytes, mime)),
+        Some(range) => match checked_range(&range, total) {
+            Some((start, end)) => Ok(ServeResult::Partial {
+                bytes: bytes[start as usize..=end as usize].to_vec(),
+                mime_type: mime,
+                start,
+                end,
+                total,
+            }),
+            None => Ok(ServeResult::RangeNotSatisfiable(total)),
+        },
+    }
+}
+
+/// Read only an explicitly shared, regular file within FileBrowser storage.
+/// Do not change its mode or grant world-readable access to paid/private data.
+async fn filebrowser_read_path(data_dir: &Path, path: &Path) -> Result<PathBuf> {
+    let root = fs::canonicalize(data_dir.join("filebrowser")).await?;
+    let target = fs::canonicalize(path).await?;
+    anyhow::ensure!(
+        target.starts_with(&root) && target != root,
+        "Shared file is outside Files storage"
+    );
+    anyhow::ensure!(
+        fs::metadata(&target).await?.is_file(),
+        "Shared content is not a regular file"
+    );
+    Ok(target)
+}
+
+async fn read_filebrowser_via_userns(data_dir: &Path, path: &Path) -> Result<Vec<u8>> {
+    let path = filebrowser_read_path(data_dir, path).await?;
+    // Tests exercise the boundary explicitly; they never launch the host Podman.
+    #[cfg(test)]
+    {
+        let _ = path;
+        anyhow::bail!("Files namespace read disabled in unit tests")
+    }
+    #[cfg(not(test))]
+    {
+        let output = tokio::time::timeout(
+            std::time::Duration::from_secs(900),
+            tokio::process::Command::new("podman")
+                .args(["unshare", "cat", "--"])
+                .arg(path)
+                .kill_on_drop(true)
+                .output(),
+        )
+        .await
+        .context("Files namespace read timed out")??;
+        anyhow::ensure!(
+            output.status.success(),
+            "Files namespace read failed: {}",
+            output.status
+        );
+        Ok(output.stdout)
+    }
 }

 /// Result of attempting to serve a preview.
@@ -729,3 +862,301 @@ mod prune_missing_content_tests {
        assert_eq!(reloaded.items[0].id, "present-item");
    }
 }
+
+#[cfg(test)]
+mod paid_read_order_tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    async fn fixture(bytes: &[u8]) -> tempfile::TempDir {
+        let dir = tempfile::tempdir().unwrap();
+        fs::create_dir_all(dir.path().join("content/files"))
+            .await
+            .unwrap();
+        fs::write(dir.path().join("content/files/test.bin"), bytes)
+            .await
+            .unwrap();
+        save_catalog(
+            dir.path(),
+            &ContentCatalog {
+                items: vec![ContentItem {
+                    id: "paid".into(),
+                    filename: "test.bin".into(),
+                    mime_type: "application/octet-stream".into(),
+                    size_bytes: bytes.len() as u64,
+                    description: String::new(),
+                    access: AccessControl::Paid {
+                        price_sats: 10,
+                        accepted: vec!["ecash".into()],
+                    },
+                    availability: Availability::AllPeers,
+                    added_at: "2026-09-30".into(),
+                }],
+            },
+        )
+        .await
+        .unwrap();
+        dir
+    }
+
+    #[tokio::test]
+    async fn all_read_failures_precede_redemption_even_as_root() {
+        for kind in [
+            std::io::ErrorKind::PermissionDenied,
+            std::io::ErrorKind::UnexpectedEof,
+            std::io::ErrorKind::NotFound,
+            std::io::ErrorKind::Other,
+        ] {
+            let dir = fixture(b"abc").await;
+            let charged = AtomicUsize::new(0);
+            let result = serve_content_with(
+                dir.path(),
+                "paid",
+                Some("cashuBtest"),
+                None,
+                None,
+                None,
+                false,
+                |_, _, _| async move { Err(std::io::Error::from(kind).into()) },
+                |_, _| async {
+                    charged.fetch_add(1, Ordering::SeqCst);
+                    true
+                },
+            )
+            .await
+            .unwrap();
+            assert!(matches!(result, ServeResult::Unavailable));
+            assert_eq!(charged.load(Ordering::SeqCst), 0);
+            assert_eq!(load_catalog(dir.path()).await.unwrap().items.len(), 1);
+        }
+    }
+
+    #[tokio::test]
+    async fn deletion_during_payment_cannot_lose_prepared_bytes() {
+        let dir = fixture(b"original").await;
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            Some("cashuBtest"),
+            None,
+            None,
+            None,
+            false,
+            |path, range, mime| prepare_content(dir.path(), path, range, mime),
+            |_, amount| {
+                assert_eq!(amount, 10);
+                async {
+                    fs::remove_file(dir.path().join("content/files/test.bin"))
+                        .await
+                        .unwrap();
+                    true
+                }
+            },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::Ok(bytes, _) if bytes == b"original"));
+    }
+
+    #[tokio::test]
+    async fn empty_out_of_bounds_and_reversed_ranges_never_charge() {
+        for (bytes, start, end) in [
+            (b"".as_slice(), 0, None),
+            (b"abc".as_slice(), 3, None),
+            (b"abc".as_slice(), 2, Some(1)),
+        ] {
+            let dir = fixture(bytes).await;
+            let result = serve_content_with(
+                dir.path(),
+                "paid",
+                Some("cashuBtest"),
+                None,
+                None,
+                Some(ByteRange { start, end }),
+                false,
+                |path, range, mime| prepare_content(dir.path(), path, range, mime),
+                |_, _| async { panic!("invalid range reached payment") },
+            )
+            .await
+            .unwrap();
+            assert!(
+                matches!(result, ServeResult::RangeNotSatisfiable(n) if n == bytes.len() as u64)
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn prepared_range_survives_file_change_while_payment_is_verified() {
+        let dir = fixture(b"abcdef").await;
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            Some("cashuBtest"),
+            None,
+            None,
+            Some(ByteRange {
+                start: 2,
+                end: Some(999),
+            }),
+            false,
+            |path, range, mime| prepare_content(dir.path(), path, range, mime),
+            |_, _| async {
+                fs::write(dir.path().join("content/files/test.bin"), b"x")
+                    .await
+                    .unwrap();
+                true
+            },
+        )
+        .await
+        .unwrap();
+        assert!(
+            matches!(result, ServeResult::Partial { bytes, start: 2, end: 5, total: 6, .. } if bytes == b"cdef")
+        );
+    }
+
+    #[tokio::test]
+    async fn payment_denial_never_returns_prepared_content() {
+        let dir = fixture(b"secret").await;
+        let charged = AtomicUsize::new(0);
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            Some("cashuBtest"),
+            None,
+            None,
+            None,
+            false,
+            |path, range, mime| prepare_content(dir.path(), path, range, mime),
+            |_, _| async {
+                charged.fetch_add(1, Ordering::SeqCst);
+                false
+            },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::PaymentRequired(10)));
+        assert_eq!(charged.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn missing_payment_and_peer_restrictions_precede_file_reads() {
+        let dir = fixture(b"secret").await;
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            None,
+            None,
+            None,
+            None,
+            false,
+            |_, _, _| async { panic!("unauthorized file read") },
+            |_, _| async { panic!("unexpected payment") },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::PaymentRequired(10)));
+        let mut catalog = load_catalog(dir.path()).await.unwrap();
+        catalog.items[0].access = AccessControl::PeersOnly;
+        save_catalog(dir.path(), &catalog).await.unwrap();
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            None,
+            None,
+            None,
+            None,
+            false,
+            |_, _, _| async { panic!("unauthorized file read") },
+            |_, _| async { panic!("unexpected payment") },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::Forbidden));
+    }
+
+    #[tokio::test]
+    async fn owner_reads_paid_content_without_redemption() {
+        let dir = fixture(b"own file").await;
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            None,
+            None,
+            None,
+            None,
+            true,
+            |path, range, mime| prepare_content(dir.path(), path, range, mime),
+            |_, _| async { panic!("owner charged") },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::Ok(bytes, _) if bytes == b"own file"));
+    }
+
+    #[tokio::test]
+    async fn directory_in_place_of_file_does_not_charge() {
+        let dir = fixture(b"abc").await;
+        let path = dir.path().join("content/files/test.bin");
+        fs::remove_file(&path).await.unwrap();
+        fs::create_dir(&path).await.unwrap();
+        let result = serve_content_with(
+            dir.path(),
+            "paid",
+            Some("cashuBtest"),
+            None,
+            None,
+            None,
+            false,
+            |path, range, mime| prepare_content(dir.path(), path, range, mime),
+            |_, _| async { panic!("directory charged") },
+        )
+        .await
+        .unwrap();
+        assert!(matches!(result, ServeResult::Unavailable));
+    }
+
+    #[tokio::test]
+    async fn files_namespace_read_is_scoped_to_regular_files_and_keeps_mode() {
+        use std::os::unix::fs::{symlink, PermissionsExt};
+        let dir = fixture(b"outside").await;
+        let root = dir.path().join("filebrowser");
+        fs::create_dir(&root).await.unwrap();
+        let inside = root.join("song");
+        fs::write(&inside, b"song").await.unwrap();
+        fs::set_permissions(&inside, std::fs::Permissions::from_mode(0o640))
+            .await
+            .unwrap();
+        assert_eq!(
+            filebrowser_read_path(dir.path(), &inside).await.unwrap(),
+            inside
+        );
+        assert_eq!(
+            fs::metadata(&inside).await.unwrap().permissions().mode() & 0o777,
+            0o640
+        );
+        let outside = dir.path().join("content/files/test.bin");
+        symlink(&outside, root.join("escape")).unwrap();
+        for path in [outside, root.join("escape"), root.clone()] {
+            assert!(filebrowser_read_path(dir.path(), &path).await.is_err());
+        }
+    }
+
+    #[test]
+    fn user_namespace_bytes_use_the_same_range_rules() {
+        assert!(matches!(
+            slice_prepared_content(
+                vec![],
+                Some(ByteRange {
+                    start: 0,
+                    end: None
+                }),
+                "x".into()
+            )
+            .unwrap(),
+            ServeResult::RangeNotSatisfiable(0)
+        ));
+        assert!(
+            matches!(slice_prepared_content(b"abc".to_vec(), Some(ByteRange { start: 1, end: None }), "x".into()).unwrap(), ServeResult::Partial { bytes, start: 1, end: 2, total: 3, .. } if bytes == b"bc")
+        );
+    }
+}
@@ -5,8 +5,45 @@
 //! are reachable over the mesh; ports of apps that aren't installed have
 //! no listener, so allowing them is inert.

+#[rustfmt::skip]
 pub const APP_LAUNCH_PORTS: &[u16] = &[
-    2283, 2342, 3000, 3001, 3002, 4080, 5180, 7778, 8080, 8081, 8082, 8083, 8084, 8085, 8087, 8090,
-    8096, 8123, 8175, 8176, 8187, 8240, 8334, 8336, 8337, 8888, 8999, 9000, 9100, 10380, 11434,
-    18081, 18083, 18091, 23000, 32838, 50002,
+    2283,
+    2342,
+    3000,
+    3001,
+    3002,
+    4080,
+    5180,
+    7778,
+    8080,
+    8081,
+    8082,
+    8083,
+    8084,
+    8085,
+    8087,
+    8090,
+    8091,
+    8096,
+    8123,
+    8175,
+    8176,
+    8187,
+    8240,
+    8334,
+    8336,
+    8337,
+    8888,
+    8998,
+    8999,
+    9000,
+    9100,
+    10380,
+    11434,
+    18081,
+    18083,
+    18091,
+    23000,
+    32838,
+    50002,
 ];
@@ -46,6 +46,25 @@ fn fips_should_fall_back(status: reqwest::StatusCode) -> bool {
    status == reqwest::StatusCode::NOT_FOUND || status.is_server_error()
 }

+/// Is this FIPS answer the final one, or should the request go again over
+/// Tor? A single-delivery request already reached the peer, so any answer
+/// is final: a Tor replay would carry the same (possibly spent) payload.
+fn fips_answer_is_final(
+    pref: crate::settings::transport::TransportPref,
+    single_delivery: bool,
+    status: reqwest::StatusCode,
+) -> bool {
+    pref == crate::settings::transport::TransportPref::Fips
+        || single_delivery
+        || !fips_should_fall_back(status)
+}
+
+/// May a failed FIPS attempt be sent again? Only a failed connect proves the
+/// peer never saw it; a timeout can land after the request was delivered.
+fn fips_retryable(single_delivery: bool, e: &reqwest::Error) -> bool {
+    e.is_connect() || (!single_delivery && e.is_timeout())
+}
+
 /// DNS suffix appended to a peer's bech32 npub.
 pub const FIPS_DNS_SUFFIX: &str = "fips";

@@ -113,7 +132,21 @@ pub fn client() -> reqwest::Client {
 /// before the Tor fallback ever gets a chance. The generous `connect_timeout`
 /// is preserved so a cold hole-punched path still gets time to establish.
 pub fn client_with_timeout(timeout: Duration) -> reqwest::Client {
+    client_with_delivery_policy(timeout, false)
+}
+
+fn delivery_redirect_policy(single: bool) -> reqwest::redirect::Policy {
+    if single {
+        reqwest::redirect::Policy::none()
+    } else {
+        reqwest::redirect::Policy::default()
+    }
+}
+
+fn client_with_delivery_policy(timeout: Duration, single: bool) -> reqwest::Client {
    reqwest::Client::builder()
+        .no_proxy()
+        .redirect(delivery_redirect_policy(single))
        .timeout(timeout)
        .connect_timeout(Duration::from_secs(8))
        .user_agent("archipelago-fips/1")
@@ -130,10 +163,18 @@ pub fn client_with_timeout(timeout: Duration) -> reqwest::Client {
 /// robust". Only connect/timeout errors are retried (a real HTTP response,
 /// including 4xx/5xx, is returned as-is for the caller to interpret).
 async fn send_with_retry(rb: reqwest::RequestBuilder) -> Result<reqwest::Response, reqwest::Error> {
+    send_with_retry_if(rb, |e| e.is_connect() || e.is_timeout()).await
+}
+
+/// [`send_with_retry`], retrying only on errors `retryable` accepts.
+async fn send_with_retry_if(
+    rb: reqwest::RequestBuilder,
+    retryable: impl Fn(&reqwest::Error) -> bool,
+) -> Result<reqwest::Response, reqwest::Error> {
    let retry = rb.try_clone();
    match rb.send().await {
        Ok(resp) => Ok(resp),
-        Err(e) if (e.is_connect() || e.is_timeout()) && retry.is_some() => {
+        Err(e) if retryable(&e) && retry.is_some() => {
            // Brief pause so the hole-punch packets from the first attempt can
            // traverse before we re-dial onto the warmed path.
            tokio::time::sleep(Duration::from_millis(600)).await;
@@ -350,6 +391,9 @@ pub struct PeerRequest<'a> {
    /// the per-peer FIPS/Tor badge reflects reality. Opt-in because not
    /// every caller has a data dir in scope.
    pub record_data_dir: Option<std::path::PathBuf>,
+    /// The request carries something that must reach the peer at most once
+    /// (a bearer ecash token). See [`PeerRequest::single_delivery`].
+    pub single_delivery: bool,
 }

 impl<'a> PeerRequest<'a> {
@@ -363,9 +407,25 @@ impl<'a> PeerRequest<'a> {
            fips_timeout: None,
            service: None,
            record_data_dir: None,
+            single_delivery: false,
        }
    }

+    /// Never send this request twice. A paid download carries a bearer ecash
+    /// token that the seller redeems on first sight; replaying it over Tor
+    /// after FIPS already delivered it hands the seller a spent token, so the
+    /// buyer is charged and gets a 402 instead of the file (2026-09-29: FIPS
+    /// answered 404 after the seller redeemed, the Tor retry got 402).
+    ///
+    /// With this set, whatever FIPS answers is final, the FIPS retry fires
+    /// only when the first attempt never connected, and Tor is used only when
+    /// FIPS could not have delivered the request. An attempt that may have
+    /// been delivered but timed out is an error, not a fallback.
+    pub fn single_delivery(mut self) -> Self {
+        self.single_delivery = true;
+        self
+    }
+
    /// Record the transport that serves this request into federation storage
    /// (matched by this request's onion host). Best-effort, off the hot path.
    pub fn record_transport(mut self, data_dir: impl Into<std::path::PathBuf>) -> Self {
@@ -442,7 +502,7 @@ impl<'a> PeerRequest<'a> {
                    // Use the FIPS reply unless it's one a Tor retry could
                    // fix (404 path-not-served / 5xx) and we're allowed to
                    // fall back. FIPS-only never falls back.
-                    if pref == TransportPref::Fips || !fips_should_fall_back(resp.status()) {
+                    if fips_answer_is_final(pref, self.single_delivery, resp.status()) {
                        telemetry::record_fips_ok();
                        self.spawn_record(crate::transport::TransportKind::Fips);
                        return Ok((resp, crate::transport::TransportKind::Fips));
@@ -481,7 +541,7 @@ impl<'a> PeerRequest<'a> {
        if matches!(pref, TransportPref::Auto | TransportPref::Fips) {
            match self.try_fips_get().await? {
                Some(resp) => {
-                    if pref == TransportPref::Fips || !fips_should_fall_back(resp.status()) {
+                    if fips_answer_is_final(pref, self.single_delivery, resp.status()) {
                        telemetry::record_fips_ok();
                        self.spawn_record(crate::transport::TransportKind::Fips);
                        return Ok((resp, crate::transport::TransportKind::Fips));
@@ -551,13 +611,21 @@ impl<'a> PeerRequest<'a> {
        } else {
            budget
        };
-        let c = client_with_timeout(per_attempt);
+        let c = client_with_delivery_policy(per_attempt, self.single_delivery);
        let mut rb = c.post(&url).json(body);
        for (k, v) in &self.headers {
            rb = rb.header(*k, v);
        }
-        match tokio::time::timeout(budget, send_with_retry(rb)).await {
+        let single = self.single_delivery;
+        let attempt = send_with_retry_if(rb, |e| fips_retryable(single, e));
+        match tokio::time::timeout(budget, attempt).await {
            Ok(Ok(r)) => Ok(Some(r)),
+            Ok(Err(e)) if single && !e.is_connect() => Err(anyhow::anyhow!(
+                "FIPS POST failed after possible delivery; not replaying: {e}"
+            )),
+            Err(_) if single => Err(anyhow::anyhow!(
+                "FIPS POST exceeded its budget after possible delivery; not replaying"
+            )),
            Ok(Err(e)) => {
                telemetry::record_fallback(FallbackReason::ConnectFail);
                tracing::info!(
@@ -612,13 +680,28 @@ impl<'a> PeerRequest<'a> {
        } else {
            budget
        };
-        let c = client_with_timeout(per_attempt);
+        let c = client_with_delivery_policy(per_attempt, self.single_delivery);
        let mut rb = c.get(&url);
        for (k, v) in &self.headers {
            rb = rb.header(*k, v);
        }
-        match tokio::time::timeout(budget, send_with_retry(rb)).await {
+        let single = self.single_delivery;
+        let attempt = send_with_retry_if(rb, |e| fips_retryable(single, e));
+        match tokio::time::timeout(budget, attempt).await {
            Ok(Ok(r)) => Ok(Some(r)),
+            // Anything but a failed connect may have reached the peer.
+            Ok(Err(e)) if single && !e.is_connect() => Err(anyhow::anyhow!(
+                "FIPS GET {} failed after the request may have been delivered \
+                 (not retrying over Tor): {}",
+                self.path,
+                e
+            )),
+            Err(_) if single => Err(anyhow::anyhow!(
+                "FIPS GET {} exceeded its {:?} budget after the request may have \
+                 been delivered (not retrying over Tor)",
+                self.path,
+                budget
+            )),
            Ok(Err(e)) => {
                telemetry::record_fallback(FallbackReason::ConnectFail);
                tracing::info!(
@@ -676,6 +759,7 @@ impl<'a> PeerRequest<'a> {
            .context("Invalid Tor SOCKS proxy URL")?;
        reqwest::Client::builder()
            .proxy(proxy)
+            .redirect(delivery_redirect_policy(self.single_delivery))
            .timeout(self.timeout)
            .build()
            .context("Build Tor HTTP client")
@@ -759,4 +843,181 @@ mod tests {
        let err = decode_response(0xAABB, &r, "x").unwrap_err();
        assert!(err.to_string().contains("no AAAA"));
    }
+
+    #[test]
+    fn a_single_delivery_answer_is_final_whatever_its_status() {
+        use crate::settings::transport::TransportPref;
+        use reqwest::StatusCode;
+        // Regression (2026-09-29): the seller redeemed a paid download's
+        // token, answered 404, and the Tor fallback replayed the spent token.
+        for status in [
+            StatusCode::NOT_FOUND,
+            StatusCode::INTERNAL_SERVER_ERROR,
+            StatusCode::SERVICE_UNAVAILABLE,
+            StatusCode::OK,
+        ] {
+            assert!(fips_answer_is_final(TransportPref::Auto, true, status));
+        }
+        // Everything else keeps the existing fallback rules.
+        assert!(!fips_answer_is_final(
+            TransportPref::Auto,
+            false,
+            StatusCode::NOT_FOUND
+        ));
+        assert!(!fips_answer_is_final(
+            TransportPref::Auto,
+            false,
+            StatusCode::BAD_GATEWAY
+        ));
+        assert!(fips_answer_is_final(
+            TransportPref::Auto,
+            false,
+            StatusCode::PAYMENT_REQUIRED
+        ));
+        assert!(fips_answer_is_final(
+            TransportPref::Fips,
+            false,
+            StatusCode::NOT_FOUND
+        ));
+    }
+
+    /// A listener that accepts connections and never answers, counting them.
+    async fn silent_peer() -> (String, std::sync::Arc<std::sync::atomic::AtomicUsize>) {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let seen = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+        let counter = seen.clone();
+        tokio::spawn(async move {
+            let mut held = Vec::new();
+            while let Ok((stream, _)) = listener.accept().await {
+                counter.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                held.push(stream); // keep it open, never reply
+            }
+        });
+        (format!("http://{addr}/content/x"), seen)
+    }
+
+    #[tokio::test]
+    async fn a_single_delivery_request_is_not_resent_after_a_timeout() {
+        let (url, seen) = silent_peer().await;
+        let c = client_with_timeout(Duration::from_millis(300));
+        let err = send_with_retry_if(c.get(&url), |e| fips_retryable(true, e))
+            .await
+            .expect_err("peer never answers");
+        assert!(err.is_timeout());
+        assert_eq!(seen.load(std::sync::atomic::Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn an_ordinary_request_is_still_retried_once_after_a_timeout() {
+        let (url, seen) = silent_peer().await;
+        let c = client_with_timeout(Duration::from_millis(300));
+        let _ = send_with_retry_if(c.get(&url), |e| fips_retryable(false, e)).await;
+        assert_eq!(seen.load(std::sync::atomic::Ordering::SeqCst), 2);
+    }
+
+    #[tokio::test]
+    async fn a_single_delivery_request_still_retries_a_refused_connect() {
+        // Nothing listening: the peer provably never saw the request.
+        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+        let addr = listener.local_addr().unwrap();
+        drop(listener);
+        let c = client_with_timeout(Duration::from_millis(500));
+        let err = send_with_retry_if(c.get(format!("http://{addr}/")), |e| {
+            fips_retryable(true, e)
+        })
+        .await
+        .expect_err("nothing listening");
+        assert!(err.is_connect());
+        assert!(fips_retryable(true, &err));
+    }
+}
+
+#[cfg(test)]
+mod delivery_redirect_tests {
+    use super::*;
+    use hyper::{
+        service::{make_service_fn, service_fn},
+        Body, Response, Server,
+    };
+    use std::{
+        convert::Infallible,
+        sync::{
+            atomic::{AtomicUsize, Ordering},
+            Arc,
+        },
+    };
+
+    #[tokio::test]
+    async fn paid_bearer_request_does_not_follow_redirects_but_normal_get_does() {
+        let seen = Arc::new(AtomicUsize::new(0));
+        let counter = seen.clone();
+        let server = Server::bind(&([127, 0, 0, 1], 0).into());
+        let address = server.local_addr();
+        let service = make_service_fn(move |_| {
+            let counter = counter.clone();
+            async move {
+                Ok::<_, Infallible>(service_fn(move |request: hyper::Request<Body>| {
+                    let counter = counter.clone();
+                    async move {
+                        counter.fetch_add(1, Ordering::SeqCst);
+                        let response = if request.uri().path() == "/first" {
+                            Response::builder()
+                                .status(302)
+                                .header("Location", "/replay")
+                                .body(Body::empty())
+                                .unwrap()
+                        } else {
+                            Response::new(Body::from("replayed"))
+                        };
+                        Ok::<_, Infallible>(response)
+                    }
+                }))
+            }
+        });
+        let task = tokio::spawn(server.serve(service));
+        let url = format!("http://{address}/first");
+        let response = client_with_delivery_policy(Duration::from_secs(2), true)
+            .get(&url)
+            .header("X-Payment-Token", "dummy-test-token")
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(response.status(), reqwest::StatusCode::FOUND);
+        assert_eq!(seen.load(Ordering::SeqCst), 1);
+        let response = client_with_delivery_policy(Duration::from_secs(2), false)
+            .get(url)
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(response.status(), reqwest::StatusCode::OK);
+        assert_eq!(seen.load(Ordering::SeqCst), 3);
+        task.abort();
+    }
+
+    #[tokio::test]
+    async fn paid_request_is_not_resent_when_peer_disconnects_after_reading_it() {
+        use tokio::io::AsyncReadExt;
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let address = listener.local_addr().unwrap();
+        let seen = Arc::new(AtomicUsize::new(0));
+        let counter = seen.clone();
+        let task = tokio::spawn(async move {
+            while let Ok((mut stream, _)) = listener.accept().await {
+                let mut buf = [0; 4096];
+                let _ = stream.read(&mut buf).await;
+                counter.fetch_add(1, Ordering::SeqCst);
+                drop(stream);
+            }
+        });
+        let c = client_with_delivery_policy(Duration::from_secs(2), true);
+        let error = send_with_retry_if(c.get(format!("http://{address}/")), |e| {
+            fips_retryable(true, e)
+        })
+        .await
+        .unwrap_err();
+        assert!(!error.is_connect());
+        assert_eq!(seen.load(Ordering::SeqCst), 1);
+        task.abort();
+    }
 }
@@ -501,12 +501,12 @@ async fn check_containers() -> Vec<ContainerHealth> {
    out
 }

-fn host_tcp_ports_from_container(c: &serde_json::Value) -> Vec<u16> {
+fn host_tcp_ports_from_container(c: &serde_json::Value) -> Vec<std::net::SocketAddr> {
    let Some(ports) = c.get("Ports").and_then(|v| v.as_array()) else {
        return Vec::new();
    };

-    let mut out: Vec<u16> = ports
+    let mut out: Vec<std::net::SocketAddr> = ports
        .iter()
        .filter(|p| {
            p.get("protocol")
@@ -515,9 +515,19 @@ fn host_tcp_ports_from_container(c: &serde_json::Value) -> Vec<u16> {
                .eq_ignore_ascii_case("tcp")
        })
        .filter_map(|p| {
-            p.get("host_port")
-                .and_then(|v| v.as_u64())
-                .and_then(|port| u16::try_from(port).ok())
+            let port = p.get("host_port")?.as_u64()?;
+            let port = u16::try_from(port).ok().filter(|port| *port != 0)?;
+            let bind = p.get("host_ip").and_then(|v| v.as_str()).unwrap_or("");
+            // Wildcard listeners are reachable through the corresponding
+            // loopback family. Explicit binds must be probed at that address:
+            // probing a WireGuard-only port on 127.0.0.1 creates false failures
+            // and endlessly restarts an otherwise healthy app.
+            let address: std::net::IpAddr = match bind {
+                "" | "0.0.0.0" => "127.0.0.1".parse().ok()?,
+                "::" => "::1".parse().ok()?,
+                explicit => explicit.parse().ok()?,
+            };
+            Some(std::net::SocketAddr::new(address, port))
        })
        .collect();
    out.sort_unstable();
@@ -525,11 +535,11 @@ fn host_tcp_ports_from_container(c: &serde_json::Value) -> Vec<u16> {
    out
 }

-async fn host_ports_ready(ports: &[u16]) -> bool {
+async fn host_ports_ready(ports: &[std::net::SocketAddr]) -> bool {
    for port in ports {
        let ready = tokio::time::timeout(
            std::time::Duration::from_secs(2),
-            tokio::net::TcpStream::connect(("127.0.0.1", *port)),
+            tokio::net::TcpStream::connect(*port),
        )
        .await
        .is_ok_and(|r| r.is_ok());
@@ -1662,4 +1672,51 @@ mod tests {
            "Prefetcher:catching up to daemon height 953,480"
        ));
    }
+    #[test]
+    fn published_port_probes_preserve_explicit_bind_addresses() {
+        let c = serde_json::json!({"Ports": [
+            {"host_ip":"127.0.0.1","host_port":8081,"protocol":"tcp"},
+            {"host_ip":"10.77.0.2","host_port":18081,"protocol":"tcp"},
+            {"host_ip":"10.77.0.2","host_port":18443,"protocol":"tcp"},
+            {"host_ip":"::1","host_port":8082,"protocol":"tcp"}
+        ]});
+        let targets = host_tcp_ports_from_container(&c);
+        for target in [
+            "127.0.0.1:8081",
+            "10.77.0.2:18081",
+            "10.77.0.2:18443",
+            "[::1]:8082",
+        ] {
+            assert!(targets.contains(&target.parse().unwrap()));
+        }
+        assert!(!targets.contains(&"127.0.0.1:18081".parse().unwrap()));
+    }
+
+    #[test]
+    fn published_port_probes_normalize_wildcards_and_ignore_invalid_entries() {
+        let c = serde_json::json!({"Ports": [
+            {"host_ip":"0.0.0.0","host_port":8080},
+            {"host_ip":"","host_port":8080},
+            {"host_ip":"::","host_port":8080},
+            {"host_ip":"10.0.0.1","host_port":53,"protocol":"udp"},
+            {"host_ip":"bad","host_port":8080},
+            {"host_port":0}, {"host_port":65536}, {"container_port":80}
+        ]});
+        let targets = host_tcp_ports_from_container(&c);
+        assert_eq!(targets.len(), 2);
+        assert!(targets.contains(&"127.0.0.1:8080".parse().unwrap()));
+        assert!(targets.contains(&"[::1]:8080".parse().unwrap()));
+    }
+
+    #[tokio::test]
+    async fn health_probe_reaches_non_default_loopback_and_detects_closed_port() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.2:0").await.unwrap();
+        let address = listener.local_addr().unwrap();
+        assert!(host_ports_ready(&[address]).await);
+        // Same port, wrong local address reproduces the former false failure.
+        let wrong = std::net::SocketAddr::new("127.0.0.1".parse().unwrap(), address.port());
+        assert!(!host_ports_ready(&[wrong]).await);
+        drop(listener);
+        assert!(!host_ports_ready(&[address]).await);
+    }
 }
@@ -256,6 +256,10 @@ async fn main() -> Result<()> {
            boot_report.recovered, boot_report.total, boot_report.failed
        );
    }
+    // Disk manifests must be stable before the initial load and all later
+    // catalog reloads. Do not move this into the background doctor bootstrap.
+    bootstrap::ensure_runtime_assets_ready().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).
@@ -989,6 +989,24 @@ impl AppManifest {
        validate_security(&self.app.security)?;
        validate_ports(&self.app.ports)?;
        validate_interfaces(&self.app.interfaces)?;
+        if let Some(value) = self.app.extensions.get("install_prerequisites") {
+            let items = value.as_sequence().ok_or_else(|| {
+                ManifestError::Invalid("install_prerequisites must be a list of app ids".into())
+            })?;
+            for item in items {
+                let id = item.as_str().unwrap_or_default();
+                if id.is_empty()
+                    || id == self.app.id
+                    || !id
+                        .bytes()
+                        .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+                {
+                    return Err(ManifestError::Invalid(
+                        "install_prerequisites must contain valid other app ids".into(),
+                    ));
+                }
+            }
+        }
        validate_environment(&self.app.environment)?;
        validate_devices(&self.app.devices)?;

@@ -1074,6 +1092,14 @@ impl AppManifest {
        // `..` copy sources). See docs/manifest-hooks-design.md.
        self.app.hooks.validate()?;

+        if let Some(value) = self.app.extensions.get("backup_before_runtime_change") {
+            if value.as_bool().is_none() {
+                return Err(ManifestError::Invalid(
+                    "backup_before_runtime_change must be boolean".into(),
+                ));
+            }
+        }
+
        Ok(())
    }
 }
@@ -1111,6 +1137,7 @@ fn validate_security(policy: &SecurityPolicy) -> Result<(), ManifestError> {
        "SETGID",
        "SETUID",
        "SYS_ADMIN",
+        "SYS_CHROOT",
    ];
    let mut seen = HashSet::new();
    for cap in &policy.capabilities {
@@ -1746,40 +1773,48 @@ app:
            }
        }
        exempt.sort();
-        // 28 as of 2026-08-23: the 26 below plus cuprate's two exemptions —
-        // 18183 (Monero p2p gossip, same reasoning as bitcoin's 8333) and
-        // 18090 (host mapping for Monero's canonical 18089 restricted RPC,
-        // upstream's own safe-for-public
-        // subset that wallets connect to directly as a "remote node" over
-        // plain HTTP JSON-RPC — same reasoning as electrumx's 50001).
-        // cuprate's unrestricted RPC (full node control) stays loopback-only
-        // (auth: local), not in this set.
-        //
-        // 26 as of 2026-08-16: the 25 below plus phoenixd 9740, a
-        // loopback-only JSON API whose own generated http password
-        // authenticates every request (added with the phoenixd onboarding,
-        // which did not update this count — exactly the drift this test
-        // exists to catch).
-        //
-        // 25 as of the v1.7.123 port-policy round: bitcoin p2p (8333 ×2),
-        // core-lightning 9736/9835, electrumx 50001, fedimint 8173/8174,
-        // fedimint-gateway 8176/9737, gitea ssh 2222, lightning-stack
-        // 8091/9738/10010, lnd 9735/10009/18080, netbird 3478/8086/8087,
-        // pine TLS 10381 + the three voice ports (10200/10300/10400 — the
-        // disclosed known gap), router SSDP/mDNS 1900/5353. Every one is a
-        // deliberate, rationale-carrying exemption; the release-gate test
-        // stage timed out that cycle, so the count here lagged at 17.
+        // Reviewed 2026-09-30: lightning-stack's three retired endpoints
+        // disappeared; Cuprate restricted RPC moved from none to gate-open.
+        // Compare exact endpoints, not just a count that can hide substitutions.
+        let expected = [
+            ("bitcoin-core", 8333),
+            ("bitcoin-knots", 8333),
+            ("core-lightning", 9736),
+            ("core-lightning", 9835),
+            ("cuprate", 18183),
+            ("electrumx", 50001),
+            ("fedimint", 8173),
+            ("fedimint", 8174),
+            ("fedimint-gateway", 8176),
+            ("fedimint-gateway", 9737),
+            ("gitea", 2222),
+            ("lnd", 9735),
+            ("lnd", 10009),
+            ("lnd", 18080),
+            ("netbird", 8087),
+            ("netbird-server", 3478),
+            ("netbird-server", 8086),
+            ("phoenixd", 9740),
+            ("pine", 10381),
+            ("pine-openwakeword", 10400),
+            ("pine-piper", 10200),
+            ("pine-whisper", 10300),
+            ("router", 1900),
+            ("router", 5353),
+        ]
+        .into_iter()
+        .map(|(id, port)| (id.to_owned(), port))
+        .collect::<Vec<_>>();
        assert_eq!(
-            exempt.len(),
-            28,
-            "unauthenticated port set changed — review before updating this count: {exempt:?}"
+            exempt, expected,
+            "unauthenticated endpoint set changed; review each exemption"
        );
    }

    /// `auth: open` ports are served by the gate WITHOUT its login challenge,
    /// so they are the second unauthenticated-by-the-gate surface and get the
-    /// same review guard as `auth: none`. Each one must be an app that
-    /// enforces a real login of its own.
+    /// same review guard as `auth: none`. Each must enforce its own login or
+    /// have an explicitly reviewed public protocol purpose.
    #[test]
    fn gate_open_ports_are_all_accounted_for() {
        let apps = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../apps");
@@ -1801,6 +1836,8 @@ app:
            }
        }
        open.sort();
+        // Cuprate 18090 is its deliberately public restricted RPC subset;
+        // unrestricted node-control RPC remains container-loopback-only.
        // Gitea 3001 (git clients speak basic-auth, not browser cookies),
        // BTCPay 23000 (checkout/invoice/webhook endpoints must be reachable
        // by anonymous payers), and — since the v1.8.7 platform round — the
@@ -1808,18 +1845,35 @@ app:
        // nginx-proxy-manager 8081 (NPM admin accounts), tailscale 8240
        // (tailnet login on the web console). Both enforce their own login,
        // and an operator can re-gate either from Settings → Access control.
+        // Angor's indexer exposes public chain data/transaction broadcast;
+        // its optional standalone relay accepts signed public Nostr events.
+        // Neither mounts credentials or the node's internal relay database.
        assert_eq!(
            open,
            vec![
+                ("angor-indexer".to_string(), 8998u16),
+                ("angor-relay".to_string(), 8091u16),
                ("btcpay-server".to_string(), 23000u16),
+                ("cuprate".to_string(), 18090u16),
                ("gitea".to_string(), 3001u16),
                ("nginx-proxy-manager".to_string(), 8081u16),
                ("tailscale".to_string(), 8240u16),
            ],
-            "gate-open port set changed — every entry must be an app with its own login"
+            "gate-open port set changed — review login or intentional public protocol purpose"
        );
    }

+    #[test]
+    fn invalid_install_prerequisites_are_rejected() {
+        for value in ["not-a-list", "[demo]", "['../other']", "[false]", "['']"] {
+            let yaml = format!("app:\n  id: demo\n  name: Demo\n  version: 1.0.0\n  container:\n    image: docker.io/library/alpine:3.20\n  install_prerequisites: {value}\n");
+            assert!(AppManifest::parse(&yaml)
+                .unwrap_err()
+                .to_string()
+                .contains("install_prerequisites"));
+        }
+    }
+
    #[test]
    fn an_undeclared_port_classifies_as_session_but_is_not_declared() {
        // Two different questions, and conflating them caused both gate
@@ -310,59 +310,7 @@ impl PodmanClient {
                );
                continue;
            }
-            // Honour the manifest's protocol (default tcp). netbird's STUN port
-            // is 3478/udp; forcing tcp here would publish the wrong protocol and
-            // silently break relay discovery.
-            let protocol = match port.protocol.to_ascii_lowercase().as_str() {
-                "udp" => "udp",
-                "sctp" => "sctp",
-                _ => "tcp",
-            };
-            // Effective bind. A gated port with no declared bind would
-            // publish 0.0.0.0 — the app would own every host address, which
-            // is both the exposure itself and the reason the daemon's app
-            // gate cannot bind those addresses to authenticate them. Pin it
-            // to loopback so the gate can take the external addresses.
-            //
-            // Doing it HERE, at container creation, is the point: the pin and
-            // the gate's takeover then both come from the daemon and cannot
-            // disagree. The earlier attempt put this decision in manifest
-            // data instead, and a node whose manifests lagged the binary
-            // published Bitcoin's loopback-only RPC across the LAN
-            // (test node, 2026-08-03).
-            //
-            // A port that already declares a bind is never overridden — that
-            // is exactly what keeps `bind: 127.0.0.1` ports host-local and
-            // leaves `auth: none` protocol ports (LND gRPC/REST, electrum)
-            // published as they are, so remote wallets keep working.
-            // NOTE: the daemon deliberately does NOT rewrite this. Pinning a
-            // published port to loopback is how an app hands its external
-            // addresses to the gate, but it belongs in the manifest, not in
-            // daemon-side inference:
-            //
-            //   * `bind` is already honoured by every publish path (here and
-            //     in package::install), so a manifest edit needs no code.
-            //   * inference here would cover only THIS path — proven on
-            //     a test node, where a recreate went through another one and
-            //     the pin never applied.
-            //   * and inferring from an ABSENT field is what republished
-            //     Bitcoin's loopback RPC across the LAN, and came within one
-            //     container-recreate of pinning LND's gRPC/REST and breaking
-            //     every remote wallet.
-            //
-            // So the migration ships as `bind: 127.0.0.1` in the signed
-            // catalog. Verified 2026-08-03 that a disk-only manifest edit is
-            // overridden by the catalog, which is precisely why the catalog is
-            // the right and only place to carry it.
-            let mut mapping = serde_json::json!({
-                "container_port": port.container,
-                "host_port": port.host,
-                "protocol": protocol,
-            });
-            if !port.bind.is_empty() {
-                mapping["host_ip"] = serde_json::json!(port.bind);
-            }
-            port_mappings.push(mapping);
+            port_mappings.push(podman_publish_mapping(port));
        }

        let mut mounts = Vec::new();
@@ -751,6 +699,25 @@ pub fn image_uses_insecure_registry(image: &str) -> bool {
        .is_some_and(|host| INSECURE_REGISTRY_HOSTS.contains(&host))
 }

+// Keep the explicitly declared bind and transport identical to Quadlet. The
+// app gate owns external listeners; container publication must not bypass it.
+fn podman_publish_mapping(port: &crate::manifest::PortMapping) -> serde_json::Value {
+    let protocol = match port.protocol.to_ascii_lowercase().as_str() {
+        "udp" => "udp",
+        "sctp" => "sctp",
+        _ => "tcp",
+    };
+    let mut mapping = serde_json::json!({
+        "container_port": port.container,
+        "host_port": port.host,
+        "protocol": protocol,
+    });
+    if !port.bind.is_empty() {
+        mapping["host_ip"] = serde_json::json!(port.bind);
+    }
+    mapping
+}
+
 fn podman_network_settings(
    network: Option<&str>,
    network_policy: &str,
@@ -1110,6 +1077,24 @@ mod tests {
        ));
    }

+    #[test]
+    fn portainer_manifest_keeps_private_network_and_loopback_api_publication() {
+        let m = AppManifest::parse(include_str!("../../../apps/portainer/manifest.yml")).unwrap();
+        assert_eq!(
+            podman_network_settings(
+                m.app.container.network.as_deref(),
+                &m.app.security.network_policy
+            ),
+            ("slirp4netns", None)
+        );
+        assert_eq!(
+            podman_publish_mapping(&m.app.ports[0]),
+            serde_json::json!({
+                "container_port": 9000, "host_port": 9000, "protocol": "tcp", "host_ip": "127.0.0.1"
+            })
+        );
+    }
+
    #[test]
    fn podman_network_settings_uses_networks_map_for_custom_networks() {
        assert_eq!(
@@ -618,6 +618,46 @@ impl DockerRuntime {
    }
 }

+// Docker is a development fallback. Refuse Podman-only network modes instead
+// of silently installing a different topology; still honor binds for other apps.
+fn docker_network_and_ports(manifest: &AppManifest, offset: u16) -> Result<Vec<String>> {
+    let network = manifest
+        .app
+        .container
+        .network
+        .as_deref()
+        .filter(|v| !v.is_empty())
+        .unwrap_or(&manifest.app.security.network_policy);
+    if matches!(network, "slirp4netns" | "pasta") {
+        anyhow::bail!("this app requires rootless Podman networking ({network})");
+    }
+    let mut args = Vec::new();
+    if !network.is_empty() && network != "isolated" {
+        args.extend(["--network".to_owned(), network.to_owned()]);
+    }
+    for port in &manifest.app.ports {
+        let host = port
+            .host
+            .checked_add(offset)
+            .context("published port offset overflow")?;
+        let bind = if port.bind.is_empty() {
+            String::new()
+        } else {
+            format!("{}:", port.bind)
+        };
+        let protocol = if port.protocol.is_empty() {
+            "tcp"
+        } else {
+            &port.protocol
+        };
+        args.extend([
+            "-p".to_owned(),
+            format!("{bind}{host}:{}/{protocol}", port.container),
+        ]);
+    }
+    Ok(args)
+}
+
 #[async_trait]
 impl ContainerRuntime for DockerRuntime {
    async fn pull_image(&self, image: &str, signature: Option<&str>) -> Result<()> {
@@ -657,25 +697,7 @@ impl ContainerRuntime for DockerRuntime {
            cmd.arg("--read-only");
        }

-        match manifest.app.security.network_policy.as_str() {
-            "host" => {
-                cmd.arg("--network").arg("host");
-            }
-            "isolated" => {
-                // Docker uses bridge network by default
-            }
-            _ => {
-                cmd.arg("--network")
-                    .arg(&manifest.app.security.network_policy);
-            }
-        }
-
-        // Port mappings with offset
-        for port in &manifest.app.ports {
-            let host_port = port.host + port_offset;
-            cmd.arg("-p")
-                .arg(format!("{}:{}", host_port, port.container));
-        }
+        cmd.args(docker_network_and_ports(manifest, port_offset)?);

        // Volumes
        for volume in &manifest.app.volumes {
@@ -1035,6 +1057,21 @@ mod tests {
    use super::*;
    use std::collections::HashMap;

+    #[test]
+    fn docker_fallback_rejects_rootless_only_topology_and_preserves_bind_protocol() {
+        let mut m =
+            AppManifest::parse(include_str!("../../../apps/portainer/manifest.yml")).unwrap();
+        assert!(docker_network_and_ports(&m, 0).is_err());
+        m.app.container.network = Some("bridge".into());
+        m.app.ports[0].protocol = "udp".into();
+        let args = docker_network_and_ports(&m, 1).unwrap();
+        assert_eq!(
+            args,
+            vec!["--network", "bridge", "-p", "127.0.0.1:9001:9000/udp"]
+        );
+        assert!(docker_network_and_ports(&m, u16::MAX).is_err());
+    }
+
    #[test]
    fn missing_container_classifier_covers_podman5_phrasings() {
        // podman 5.x `inspect` phrasing for a missing container.
@@ -14,6 +14,8 @@ doc. See [`ROADMAP.md`](ROADMAP.md) for the curated, public-facing direction.

 ## Next release after 1.8.21 — reported 2026-09-30

+Release status and acceptance gates: [execution checklist](next-release-20260930.md).
+
 - [ ] **Release blocker: Gitea → Portainer repository integration.** Diagnose
  smart-HTTP reachability from Portainer's actual request namespace, then provide
  one declarative topology and idempotent migration for fresh installs and
@@ -36,8 +38,11 @@ doc. See [`ROADMAP.md`](ROADMAP.md) for the curated, public-facing direction.
  documentation establishes a UI. Verify Bitcoin/Mempool requirements, decide
  whether an existing first-class relay meets Angor's requirements or a relay
  must be packaged with the indexer, and use the Angor logo from angor.io for its
-  service icon. The mentioned setup-documentation link was not included; asked
-  the operator for it. Include this service in the next-release scope.
+  service icon. Official current deployment documentation located and reviewed: stock Mempool
+  plus an optional strfry relay. Both headless services and the dependency guard
+  are implemented; API outage/recovery and five relay lifecycle cycles passed.
+  Final candidate install/lifecycle checks and signed delivery remain pending.
+  Install on the development box; Bitcoin must finish syncing for indexed queries.

 - [ ] **App lifecycle: keep installed apps visible through restart and hard
  refresh; gate embedded/browser launches on actual web and listener readiness.**
@@ -52,11 +57,14 @@ doc. See [`ROADMAP.md`](ROADMAP.md) for the curated, public-facing direction.
  rootless file permissions in disposable scratch storage. Combined result:
  1,585 passed, zero failed, four existing tests ignored. See the
  [review evidence and remaining acceptance work](pr-review-20260930.md).
- [ ] Integrate the reviewed PR branches into the next release and run funded
+- [x] Integrate the reviewed PR branches into the next release and run funded
  candidate acceptance, including Tor-only transport and payments with change.
  Operator authorized completing the normal merge/closure workflow on
  2026-09-30. Both PRs are now merged and closed through Gitea; integrate
-  local repair commits and sync git/ngit before release. The reviewed code has not yet been deployed to live wallets.
+  local repair commits and sync git/ngit before release. The combined candidate
+  is deployed on both test endpoints. Funded Tor-only purchase with change,
+  confirmed refund, exact Files bytes and zero-cost repeat delivery passed.
+  The updated source still needs inclusion in signed OTA/ISO artifacts.
 - [ ] Design durable recovery for an accepted payment whose response is lost.
  Preserve the truthful unconfirmed-refund warning and prevent automatic
  duplicate payment while that recovery work is outstanding.
@@ -765,3 +765,13 @@ Every supported app must satisfy the lifecycle contract:
 For apps with special dependencies, launch must explain dependency wait states instead of showing a dead iframe. Examples include Bitcoin sync/IBD, Lightning wallet readiness, Nostr signer bridge injection, Tailscale login/auth, and app-specific setup screens.

 Runtime changes should be validated with focused tests first, then the release lifecycle harness on the validation host when host access is intentionally resumed.
+
+### Adapters for shared services
+
+A service that reuses an installed stack can declare `install_prerequisites`
+with the required component app ids and keep the runtime relationship in
+`dependencies`. This refuses an incomplete installation before creating the
+adapter instead of reporting a successful installation with no usable backend.
+For example, Angor Indexer requires `mempool-api` (shown to users as its owning
+Mempool app), shares that index and declares only an `api` interface. API-only
+interfaces belong in Services and do not generate browser launch buttons.
@@ -290,3 +290,35 @@ app:
 Validate with `scripts/validate-app-manifest.sh` and regenerate the catalog
 with `scripts/generate-app-catalog.py` (drift-checked in CI by
 `scripts/check-app-catalog-drift.py`).
+
+### Persistent-state backup for runtime repairs
+
+`app.backup_before_runtime_change: true` opts an app into a stopped-state snapshot
+before reconciliation changes a service’s network, ports, security settings,
+command or health configuration. Image-upgrade backup policy remains separate. The orchestrator
+archives writable persistent bind mounts under the node data directory, collapses
+nested mounts, excludes the runtime Podman socket, and preserves the previous
+Quadlet definition for rollback. Named volumes, outside-data-root state and
+symlinked mount roots fail closed rather than silently producing an incomplete
+backup. A failed snapshot resumes the original service and leaves migration
+pending. Private archives are retained under `migration-backups/`; fresh installs
+and unchanged runtime configurations do not create migration snapshots.
+
+Catalog generation preserves the previously published base manifest for older
+daemons and puts opted-in network changes in a signed `manifest_variants` entry
+requiring `runtime-migration-backup-v1`. New runtimes select only variants whose
+complete requirement list they support. Supply `BASE_CATALOG` when generating
+against a different reviewed pre-migration catalog. This keeps catalog refresh
+from applying a migration before the matching OTA code is installed.
+
+### Existing shared-service prerequisites
+
+`app.install_prerequisites` is an optional list of existing app ids, for example
+`[mempool-api]` for a headless indexer adapter. The runtime checks their manifest
+container names before recording installation or changing any dependency. If one
+is missing, installation refuses with its owning app's title and removes the
+optimistic install tile. Runtime observation errors fail closed. This does not
+automatically install dependencies, alter Bitcoin pruning, or require a synced
+backend merely to recognize an already-installed service. Declare ongoing
+relationships separately in `dependencies`; use the app health check for actual
+API readiness. Self-dependencies and malformed ids are invalid.
@@ -0,0 +1,167 @@
+# Same-node Gitea sources in Portainer
+
+Status: root cause reproduced and network repair verified in disposable and actual
+production Portainer instances; final migration integration and release acceptance remain in progress.
+This change belongs to the next signed catalog, OTA and ISO. It does not modify
+published 1.8.21 artifacts.
+
+## Confirmed cause
+
+On the affected X250, Gitea 1.27.3 and Portainer 2.45.0 run in rootless Podman
+5.4.2, managed by user Quadlet services. Gitea publishes HTTP on loopback and the
+Archipelago app gate serves its public port. Gitea's public ROOT_URL already
+matches that gate URL.
+
+Portainer had no explicit network selection and Podman selected pasta. Its
+network namespace contained the host's LAN address. A Git request to that same
+LAN address therefore reached Portainer's namespace rather than the host gate:
+connection refused before authentication. The exact smart-HTTP request from the
+host returned 200 with `application/x-git-upload-pack-advertisement`. From
+Portainer's actual namespace the LAN request was refused, while its host mapping
+returned a Git advertisement and the expected branch tip. Direct container-IP
+requests timed out. Container health and host-only HTTP checks missed the defect.
+
+A disposable Portainer using `slirp4netns` successfully created a Source through
+Portainer's own API, using the original LAN clone URL. Returning that fixture to
+pasta reproduced the refusal; recreating with slirp repaired it while preserving
+its account and saved Source. Restart also passed. The requested branch tip and
+Compose file were read from that actual Portainer network namespace. No user
+stack was deployed. Deployment addresses and repository details are kept outside
+this public record.
+
+## Source changes
+
+- Declare Portainer's rootless `slirp4netns` mode in its manifest. No shared static
+  container IP, host networking, all-interface backend publication or auth bypass.
+- Keep Gitea's loopback HTTP backend and gate port; machine Git uses Gitea's
+  authentication. Remove obsolete port-3000 nginx metadata/template and the old
+  best-effort installer commands which silently rewrote app.ini and falsely
+  claimed success. Gitea owns first-run setup and operator configuration.
+- Gitea SSH also failed before authentication: OpenSSH logged a denied
+  `chroot("/var/empty")` because the manifest dropped `SYS_CHROOT`. Add that
+  specific sandbox capability and reconcile security-directive changes. A
+  disposable fixture then passed SSH clone/push with host-key checking enabled.
+- Existing Quadlet reconciliation applies Network= drift. Record a durable
+  pending restart before updating the unit and clear it only after a successful
+  restart, so failed reloads/restarts and management interruptions retry.
+- Detect explicit rootless network-mode drift in the older Podman runtime too.
+  Unspecified networks do not trigger inferred changes to unrelated apps.
+- Portainer and Gitea opt into `backup_before_runtime_change`. Before recreation, gracefully
+  stop the app and archive its writable persistent bind mounts, including nested
+  Compose state, once each. Runtime sockets are excluded. Save the previous
+  Quadlet definition, where present. Archives live under the node data directory's
+  private `migration-backups/<id>/` directory; state is never deleted. Backup
+  failures resume the original service and fail the migration visibly.
+- Keep Podman API and Quadlet bind/network behavior covered by actual-manifest
+  tests. Docker remains a development fallback: it now preserves bind/protocol
+  declarations and rejects Podman-only networking instead of silently changing it.
+
+## Operator use and diagnostics
+
+Use Gitea's advertised HTTP(S) clone URL in Portainer Sources, with the Gitea
+username and token in the credential fields. On first-run Gitea setup, the public
+base URL must match the origin opened through Archipelago (including its port).
+Keep a deliberately configured HTTPS/domain origin when one exists. Do not use a
+container IP or put a token into the URL. A private repository requires repository
+read permission. A successful Source check fetches Git refs; it does not deploy
+a stack or establish that a Compose build uses a desired application revision.
+
+`scripts/check-portainer-git-source.py` calls Portainer's own read-only Source
+connection test. Supply a private mode-600 JSON credential file containing
+`api_key` or `jwt`, and optionally `git: {username, password}`. Pass
+`--portainer-url`, `--repository-url` and `--credentials-file`. It does not create
+Sources or stacks and prints no credentials or raw server errors. It distinguishes
+Portainer login/API failures from Git connection refusal, timeout, DNS/TLS
+failure, HTML/login interception and repository authentication failure. TLS
+verification stays enabled and API redirects are refused.
+
+## Upgrade and rollback
+
+The signed catalog embeds manifests and overrides installed disk copies.
+Capability-gated manifest variants keep the previous Portainer manifest as the
+base for older daemons; only daemons supporting `runtime-migration-backup-v1`
+select the network repair. This prevents catalog refresh from triggering an
+unbacked recreation before the OTA is installed. A disk
+edit alone cannot deliver this fix. Publish the matching catalog with the tested
+runtime, then verify the generated unit, actual network mode and Source API.
+Expect a Portainer interruption while the snapshot and recreation run; duration
+depends on its saved state size.
+The Portainer routing repair does not require a Gitea configuration change.
+The separate SSH capability repair does recreate Gitea, preserving and snapshotting
+both data/config mounts first. Supported systemd drop-in overrides remain intact.
+
+Keep the previous trusted catalog/runtime for rollback. Restore that catalog
+before restoring the saved `previous.container`, reloading user systemd and
+starting Portainer; otherwise reconciliation will correctly reapply the new
+manifest. The archive is a stopped-state emergency backup, not an instruction to
+roll back a live database automatically. Restore it only with Portainer stopped
+and after preserving any newer state. Do not replace Gitea data/config, keys,
+repositories or the production Portainer database with disposable test data.
+
+## Validation and remaining gates
+
+- Disposable X250 Portainer Source API: old mode refuses; repaired mode succeeds;
+  saved account/Source survive recreation; restart succeeds.
+- Invalid Git credentials produce a repository-authentication error, distinct
+  from TCP refusal. Requested branch and Compose file read from Portainer context.
+- Combined backend suite including the reviewed paid-download PRs and catalog
+  rollout guard: 1,605 passed, zero failed, four existing ignored
+  tests, including stopped-state archive round trips and failure preservation. Container runtime suite: 78 passed.
+  Five diagnostic regression tests passed; catalog regeneration is idempotent
+  and the generated catalog has zero manifest metadata drift.
+- Fresh managed Gitea and Portainer fixtures: authenticated private Source
+  creation, invalid-token rejection, workstation clone/push and exact branch
+  lookup from Portainer namespace passed. LFS batch/upload/download and OCI
+  registry authentication/blob/manifest round trips passed. Desktop and mobile
+  login/private-repository/assets/hard-refresh checks passed.
+- Still required before release: live automatic migration with the new runtime,
+  snapshot/rollback verification and reversed install-order acceptance,
+  lifecycle/reboot convergence, and signed-catalog delivery to the existing app.
+  Record LFS/registry/SSH/browser checks and actual hardware/runtime coverage.
+
+### Affected X250: production routing repair verified
+
+Applied the tested rootless network setting to the actual installed Portainer
+through a persistent Quadlet drop-in, after gracefully stopping it and creating a
+private archive of its database and Compose directory. Compared the archive
+against the stopped original before changing configuration; retained the original
+unit and a rollback path. A verification helper initially compared mount list
+order rather than mount identity and safely rolled back; the corrected check
+compares sorted source/destination/write-mode tuples and passed.
+
+The actual production Portainer namespace reproduced connection refusal before
+repair. After repair it received a Git smart-HTTP advertisement, fetched the
+requested branch at its current tip and read its Compose file. Repeating these
+checks after restarting the managed Portainer service passed. All original data
+and socket mounts and the loopback-only HTTP binding are retained. Gitea,
+Bitcoin and the wallet container IDs and start times were unchanged. No stack
+was deployed and no repository credential was changed.
+
+This establishes the routing repair on the affected hardware. A logged-in
+production Portainer Source UI/API acceptance has not yet been recorded; the
+corresponding API checks passed on disposable instances as documented above.
+The installed-node drop-in persists through service restart/reboot but is not the
+fleet delivery mechanism. Automatic migration and signed catalog/OTA/ISO release
+validation remain pending; the source manifest declares the same network mode.
+Private deployment addresses, branch details and state archives are not committed.
+
+### Managed automatic migration and archive restore
+
+The new runtime candidate migrated an existing managed fixture from pasta to
+slirp without a manual unit edit. It preserved the account, saved Source and
+mount set, saved a private stopped-state archive plus the previous unit, restored
+Source API access, and cleared the pending restart marker. A management-service
+restart preserved the new container identity/start time and did not create
+another archive. The archive extracted into an isolated scratch directory and
+compared cleanly, including the database and Compose directory. Rootless archive
+ownership required scratch cleanup inside `podman unshare`; no production data
+was overwritten. Native Bitcoin and LND IDs/start times remained unchanged.
+
+This optimized candidate predates the final bounded backup-retry guard; that
+latest source passed the isolated 1,605-test suite and must also be exercised in
+the final release build. A fixture-only systemd start failure was then injected during a security
+directive migration. The failure retained the durable restart marker. After
+removing the injected failure, the reconciler restarted the service without a
+manual container start, restored Source API access and cleared the marker.
+Reverse install order, final-build retry-budget coverage, full reboot and
+signed delivery remain open.
@@ -0,0 +1,336 @@
+# Next OTA and raw ISO after 1.8.21
+
+**Status: implementation and acceptance in progress; NOT ready to release.**
+
+This is the consolidated execution checklist for the operator's chat requests.
+A targeted node repair is not completion of the release. Finish the remaining
+acceptance gates, preserve live wallets and app data, and publish both artifacts
+through git and ngit. No universal absence of future failures is claimed.
+
+## Changes already shipped in 1.8.21 or earlier
+
+Keep these fixes in the next build and include relevant regressions:
+
+- Mempool image/catalog version agreement and update-button behavior.
+- Minibits integration; Framework automatic LND startup and safe unavailable
+  balances. Framework incident closed with operator acceptance.
+- Shorter, single-column ecash backup messaging.
+- AIUI transparent background on desktop/mobile.
+- Cashu paid-file keyset/mint/error/refund corrections, with live purchases.
+- mempool.space explorer fallback, preserving local/custom explorer settings.
+- Bitcoin install pruning choice and matching automatic-pruning behavior.
+- Friendly Bitcoin warmup and LND install/start/sync waiting states.
+- Raw ISO publishing and upload support.
+
+The Primal automatic LNURL comment problem was traced to sender behavior and
+Minibits metadata. The user accepted clearing the sender's automatic comment;
+no unsupported local metadata rewrite or wallet-identity replacement is planned.
+See the Framework incident and 1.8.21 execution records for evidence/limits.
+
+## New release scope and gates
+
+| Task | Implemented/verified | Remaining before release |
+| --- | --- | --- |
+| X250 Bitcoin picker | Inline choices; actual Chromium kiosk selection, readability and pruning layout passed | Include in final UI/build checks |
+| App disappearance/readiness | Durable inventory and safe lifecycle repair; delayed HTTP and desktop/mobile hard-refresh checks passed | Final lifecycle/reboot gate on candidate |
+| X250 GitWorkshop/Nginx | Missing build contexts restored, dependency/build checks and live UI passed; Nginx slow pull diagnosed; truthful progress label | Verify both artifact payloads contain all build contexts |
+| PRs 161/162 | Reviewed, repaired, merged/closed normally; combined regression suite passed | Funded Tor-only candidate purchase, retained change, refund, Files bytes and cached repeat passed; include in signed artifacts |
+| Gitea/Portainer | Root cause confirmed; source network/backup/retry/catalog changes; real X250 routing repair and restart verified; private Git, SSH, LFS, registry and browser fixture checks passed | Automatic migration, scratch restore, failed-start recovery and reverse installation order passed. Operator confirms production site works through Portainer; production host reboot also preserved network/Git/Compose access; final candidate delivery and release checks remain |
+| Angor headless store service | Implemented standard Mempool adapter and separate optional relay, official logo, headless store entries and declarative dependency guard. API security/outage/DNS tests and five relay lifecycle cycles passed | Final candidate prerequisite/install acceptance, management restart/reboot checks and signed catalog delivery; real indexing on dev waits for Bitcoin sync |
+
+Durable payment receipts after a lost seller response remain a separately
+recorded design follow-up. Preserve the truthful unconfirmed-refund warning and
+prevent duplicate automatic payment; do not describe an unconfirmed refund as
+completed. See PR review for the accepted scope and coverage limits.
+
+## Final release checklist
+
+- [ ] Finish all new-scope implementation and specific acceptance above.
+- [x] Remove disposable fixtures and temporary test overrides; verify native
+      Bitcoin/LND identity and start-state baselines remain protected.
+- [x] Commit and push completed source changes to git and ngit.
+- [ ] Run final backend/UI/regression/release gates on the final source; inspect
+      skipped tests and report actual hardware/runtime coverage.
+- [ ] Prepare compatible signed app catalog; old runtimes must not apply a
+      migration before they have backup/recovery support.
+- [ ] Version/changelog and OTA payload prepared, validated and signed by user.
+- [ ] Raw ISO built; payload hashes/content verified; installer boot tested.
+- [ ] User signs ISO checksums; publish OTA and ISO plus verification files on
+      git and ngit; independently read back hashes and update discovery.
+- [ ] Provide LAN scp command for the new raw ISO.
+
+Latest backend source verification: 1,609 passed, zero failed, four existing
+ignored tests. This is one layer of evidence, not a substitute for live gates.
+
+## Angor verification — 2026-09-30
+
+- Isolated backend suite: 1,606 passed, four existing ignored; container suite:
+  79 passed. Frontend: 140 files / 1,130 tests passed; production build passed.
+- Disposable rootless API gateway: versioned and legacy API paths, query/body
+  forwarding, transaction-only POST, method/body limits, CORS, removal of
+  dashboard credentials, read-only non-root operation, truthful backend outage
+  and DNS recovery after backend recreation passed. No real transaction broadcast.
+- Dedicated relay: NIP-11, signed event publish/read, invalid signature rejection
+  and event/config persistence across five managed stop/start/restart cycles
+  passed. Internal relay identity and start time stayed unchanged. Follow-up
+  acknowledgement samples were 2–9 ms through both backend and app gate.
+- Published adapter 1.0.1 and relay 1.1.2 to the authenticated maintainer namespace.
+  Anonymous registry readback succeeded. Adapter digest:
+  `sha256:997be611700b55c521ad801fa92daaca2ae6951ac71407434c85eb9603f77c38`;
+  relay mirror digest:
+  `sha256:80444ad1304a0e504948b48ea1550c091b18b9f10757f07ce9a68fc261b8f6c1`.
+- Delivery target is the development box, as clarified by the operator. Do not
+  install Angor on the separate Portainer node. Full indexer availability still
+  requires the dev box's Bitcoin sync and Mempool/Electrum indexing to finish.
+- Funded PR acceptance passed after the operator funded the dev Cashu wallet
+  with 16 sats. Exact net payment was 1 sat; underpayment refunded in full;
+  repeat delivery cost zero. Both endpoints ran the combined candidate.
+  No spent proofs were reactivated and no native Bitcoin/LND funds were moved.
+
+## Development candidate and cleanup
+
+The combined optimized backend and production UI are deployed on the development
+box with a private rollback copy. Native Bitcoin/LND containers were unchanged
+during deployment. The operator separately uninstalled/reinstalled Bitcoin Core
+to select an unpruned node; RPC confirmed `pruned=false`, and a separate baseline
+was recorded after that operator action. Do not compare subsequent checks with
+the pre-reinstall container start times.
+
+Completed Gitea setup/private-repository and Portainer integration fixtures were
+uninstalled through the supported lifecycle and removed from installed inventory.
+Their private evidence/data were retained outside the active manifests. The old
+Cuprate UI review container was also removed. Active Angor acceptance fixtures
+must be removed on completion; the requested Angor services remain installed.
+
+Funded acceptance used Tor-only peer-file transport, verified exact delivery
+bytes and compatibility response fields, and read the result back through
+FileBrowser. The original transport preference was restored, and temporary
+seller catalog entries/files and the exact buyer test document were removed.
+Financial receipt history was retained.
+
+The final managed-install fixture exposed a separate Quadlet quoting defect:
+whitespace-free command arguments containing apostrophes lost those characters
+in the generated service. The renderer now quotes these arguments and
+environment values; the updated isolated backend suite passed (1,607 passed, four opt-in tests
+ignored), and the final candidate rebuild is in progress. Do not tag a release before this live regression is verified.
+
+The production Portainer host subsequently rebooted after the routing repair.
+A post-boot probe from the actual Portainer namespace again verified the Git
+smart-HTTP response type, current branch ref and Compose contents. Its
+slirp4netns route and all production app containers survived. The temporary
+Portainer fixture was absent. This verifies the repaired production route
+across reboot; it does not substitute for final new-runtime delivery checks.
+
+## Follow-up acceptance: app cards and Angor icon
+
+- Mempool duplicate traced to `archy-mempool-web` durable inventory alias being
+  restored beside the real `mempool` frontend. Shared scanner canonicalization
+  fixes live and absent-container paths without deleting installed markers.
+  Frontend suppresses aliases only while a canonical tile exists.
+- Readiness text names the app and condition: “Web UI not ready: Gitea”. It shares the status row,
+  with full text available through its title; card actions use bottom alignment.
+- Angor uses the operator-supplied dark-mode icon with green outer corners.
+  Built-in imagegen prompt: fill transparent/white corners with the existing
+  flat green, preserve the black symbol, square opaque PNG, no added details.
+- Backend alias suite: 1608 passed, 4 ignored. Focused readiness/frame UI tests:
+  30 passed. Production UI build passed and is live on dev. Browser checks at
+  1440 and 1024 pixels verified named waiting text, bottom-aligned actions,
+  equal row heights, no overflow and one Mempool card after hard refresh.
+  The 390-pixel mobile icon layout also passed hard refresh. Final-source
+  isolated Mempool alias regression passed after the scanner simplification.
+- Managed Angor adapter acceptance: five stop/start/restart cycles, missing
+  prerequisite refusal, management restart and cleanup all passed. Both temporary
+  fixtures and their network were removed. Actual dev API verification remains
+  pending after removing an incomplete legacy-created adapter.
+
+## Startup manifest reload race
+
+Live Angor acceptance exposed a separate startup race: runtime asset bootstrap
+cleared and copied `/opt/archipelago/apps` in the background while the startup
+catalog refresh reloaded it. The daemon logged 62 loaded manifests followed by
+54 and then rejected the new disk-only app as unknown. A stable manifest snapshot
+confirmed the diagnosis: supported uninstall/reinstall produced the correct
+rootless Quadlet service with its declared port and network.
+
+Runtime promotion and the legacy installer-directory repair now finish before
+orchestrator construction. The background doctor no longer changes that tree.
+The final source backend suite passed 1,608 tests (four existing opt-in tests
+ignored). Optimized build and normal-path live startup/restart verification have now passed (see final follow-up below).
+
+Actual dev Angor acceptance passed managed service identity, no capabilities,
+UID 101:101, archy-net, public block height, CORS and both fee URL forms. During
+Bitcoin initial sync, the real Mempool fee API returns 503; the adapter faithfully
+returns the same status and body. Full-sync fee availability remains unverified;
+ready-backend API and failure/recovery behavior passed the isolated live fixture.
+The temporary `/run/archy-candidate-manifests` snapshot override and snapshot
+are now removed; normal startup/reload verification passed.
+
+The latest complete UI suite passed 140 files / 1,132 tests. Release preflight
+passed all static, manifest, catalog, type and UI gates. The requested named
+waiting message, compact card layout and green Angor icon are deployed to dev;
+desktop 1440/1024 and mobile 390 browser checks passed after hard refresh.
+The startup-order optimized build and normal-path startup checks are complete.
+The later dashboard-address candidate is now deployed with rollback; see the
+final live follow-up below. Do not rerun the earlier deployment helper: its
+temporary override has already been removed. No new release version/tag, OTA
+or ISO has been created.
+
+## Mempool and dashboard follow-up
+
+- Deployed the Mempool alias and runtime-promotion-order backend to dev. Real
+  server state contains one healthy `mempool`; the stale `mempool-web` record
+  is gone. Real-data browser checks at 1440/390 pixels found exactly one tile
+  before and after hard refresh. Bitcoin/LND identities/start times unchanged.
+- Removed the candidate manifest override. Normal management startup passed
+  two full cycles with 62 manifests retained through both initial catalog
+  refreshes. The next cycle hit a single readiness assertion; a subsequent
+  read-only check found Angor healthy and the manifest count intact. Remaining
+  repeat coverage should use bounded polling to distinguish transient request
+  failures from loss of app definitions; do not report five cycles passed yet.
+- Bitcoin Core's dashboard was serving HTTP 200 on 8334 while readiness checked
+  RPC 8332. Companion URL selection now takes priority over protocol sockets
+  for Core/Knots and Electrum aliases, with a regression preserving allocated
+  UI ports for other apps. Backend suite: 1,609 passed, four opt-in ignored.
+  Optimized build is `/tmp/archy-dashboard-address-build.log`; deployment and
+  live IBD verification helper: `/tmp/archy-dashboard-address-deploy.py`.
+- Phoenixd has no browser UI. Headless services now omit web-readiness messages;
+  actual browser apps name their web interface rather than waiting for
+  themselves. Focused 23 UI tests and production build passed; deployed to dev.
+
+## Final live follow-up: all three reported readiness/display defects fixed
+
+- Final optimized backend is deployed on dev. Bitcoin Core's launch address is
+  `http://localhost:8334` and `ui-ready` is true during initial block download.
+  Live verification recorded height 293,855 with `initialblockdownload=true`.
+  Chromium at 1440 and 390 pixels opened the embedded dashboard, read a numeric
+  current block height, and repeated that check after hard refresh.
+- One healthy Mempool remains in server state and in desktop/mobile My Apps
+  after hard refresh. Its durable install markers were preserved.
+- Phoenixd remains a running headless service without a web launcher or false
+  web-readiness message. Desktop/mobile browser checks passed. For actual web
+  apps, the compact copy is “Web UI not ready: [app]”; the reason comes first so
+  narrower cards do not truncate it into a misleading self-dependency.
+- Five normal management startup and managed Angor restart cycles passed
+  across the two acceptance logs. The retry harness uses bounded readiness
+  polling; it does not accept a running container alone as API readiness.
+  Disk + catalog manifest count remained 62 across startup refreshes, replacing
+  the previous 62-to-54 failure. Temporary override and snapshot are removed.
+- Final backend tests: 1,609 passed, zero failed, four existing opt-in ignored.
+  Final UI tests: 140 files / 1,133 passed. Production UI build passed and is live.
+  Bitcoin/LND container identities and start timestamps stayed unchanged.
+- Evidence: `/tmp/archy-dashboard-address-deploy.log`,
+  `/tmp/archy-bitcoin-ibd-browser.log`, `/tmp/archy-mempool-live-browser.log`,
+  `/tmp/archy-service-readiness-browser.log`,
+  `/tmp/archy-runtime-order-remaining-cycles.log`, and
+  `/tmp/archy-readiness-final-ui-tests.log`.
+- These are live development fixes. The new signed catalog, versioned OTA and
+  raw ISO still need preparation, artifact verification, signing and publication.
+
+### X250 Nginx Proxy Manager tunnel repair (2026-09-30)
+
+A further live report was a real startup failure, separate from the earlier slow
+image pull. An operator-specific Quadlet `web-tunnel.conf` published NPM's HTTP
+listener on tunnel port 18080. LND subsequently occupied 18080 on all addresses;
+pasta failed before NPM could start, with more than 1,400 systemd retries. The
+standard NPM manifest only publishes admin port 8081 and did not introduce this
+extra mapping. Changing the standard manifest would not repair this override.
+
+The node's override now uses free tunnel-local port 18081. Its persistent nftables
+configuration redirects only HTTP arriving from the configured WireGuard peer on
+the original tunnel destination to that port. The peer/public routing is unchanged;
+the input rule accepts the translated port and retains the existing interface,
+peer and forwarding restrictions. LND's REST port and native processes were not
+changed. This deployment-specific topology must not be copied into global app
+manifests or applied indiscriminately to other nodes.
+
+An abandoned certificate request also left an unreferenced database record and
+a temporary nginx challenge server for the same hostname. After backing up the
+entire NPM data directory and both configuration files, the unused failed record
+was soft-deleted and the stale challenge file archived. The referenced, valid
+certificate, proxy host, keys and user accounts were preserved.
+
+Live checks: NPM admin and API HTTP 200; nginx configuration validation with no
+duplicate-host warning; public HTTP redirects to HTTPS; valid public TLS reaches
+the site's existing authentication response, matching its direct upstream. NPM
+starts with zero automatic restarts and no missing-certificate renewal error.
+Bitcoin, LND and the production site container identities/start times were
+unchanged by the port repair. Rollback copies and the data archive are retained
+in the node's private support directory. No global OTA or ISO was published by
+this repair; the remaining release gates above still apply.
+
+#### Follow-up: fleet delivery and false health failures
+
+A longer observation exposed a second, generic defect after the port conflict
+was repaired: the health monitor probed all published ports at `127.0.0.1`,
+including NPM's tunnel-only listeners. Every monitor interval could therefore
+restart a healthy app. The short initial restart check did not catch this.
+
+The next backend now probes the actual `host_ip` from Podman; only wildcard
+addresses map to the corresponding loopback family. Regression tests cover
+explicit IPv4/IPv6 binds, wildcards, UDP/unpublished/invalid entries, and a real
+listener on a different loopback address. NPM's manifest now checks its internal
+admin HTTP API. The same check is deployed as a persistent Quadlet drop-in on
+the affected node so its older backend stops making false recovery attempts.
+
+The backend embeds `scripts/repair-npm-tunnel.py` and runs it before app
+reconciliation, after runtime asset promotion. This makes the targeted legacy
+port migration available to both OTA and ISO installations without relying on
+an independently installed script. Standard fresh installs are a no-op. Only
+the recognized legacy tunnel/firewall profile is migrated; unknown operator
+routing, occupied replacement ports and live-only firewall changes fail closed
+with a startup warning. Configuration backups, an interrupted-migration journal,
+atomic nft transactions and rollback protect the existing routing. Native wallet
+services and certificate databases are never modified by this fleet migration.
+
+The Python migration tests run in the release gate. The unsigned next catalog
+was regenerated successfully with the new NPM HTTP health check. These changes
+are prepared for the next release; existing published OTA/ISO artifacts remain
+unchanged and the new signed artifacts still require the release gates above.
+
+Verification for this follow-up: 18 migration tests passed; 43 health-monitor
+backend tests passed through the isolated runner. A disposable network-namespace
+regression exercised actual peer traffic through the nft redirect while a
+separate simulated LND listener retained port 18080. The generated rules also
+passed nft validation and atomic replacement. Run that regression with
+`sudo unshare --net python3 tests/regression/npm-tunnel-network.py`; it refuses
+to run in the host network namespace. The migration is a verified no-op on the
+already repaired node and on a standard development install without the override.
+
+After deploying the API health check, a 270-second live observation crossed
+multiple health-monitor intervals: NPM stayed healthy with the same container
+ID/start time, every API probe returned success, and Bitcoin/LND/production-site
+container IDs/start times were unchanged. This supersedes the initial short
+restart-only acceptance recorded above. The generic backend fix is committed
+for release, while the live node uses the equivalent internal NPM health check.
+
+### Final-gate Angor health-check correction
+
+Final release observation found the adapter healthy over IPv4 but marked
+unhealthy by its in-container BusyBox wget: `localhost` resolved to `::1`, where
+nginx does not listen. Its manifest now explicitly probes `127.0.0.1`. The live
+managed service was refreshed and its real Podman health check passed. The
+rootless gateway integration now runs the manifest's health check inside the
+actual image, in addition to endpoint/security/outage/DNS recovery assertions;
+all passed. A metadata regression covers the address-family requirement. Test
+containers and their network were removed by the fixture cleanup.
+
+## 1.8.22-alpha release preparation
+
+Final implementation gate passed: 1,612 isolated backend tests, zero failures,
+four existing opt-in tests ignored; 140 frontend files / 1,133 tests; frontend
+type check and production build; static/catalog/trust/build-context checks.
+The four exclusions require external AI backends, Reticulum subprocess/live
+transport, physical RNode hardware, or creation of a live Minibits profile.
+They are not claimed as executed by the isolated suite. Existing funded
+Cashu/Minibits and Framework acceptance remains recorded above.
+
+The real dev Angor stack now returns HTTP 200 fee estimates through both API
+forms; Bitcoin is still in initial sync, so full-chain completion remains an
+operational prerequisite rather than a completed test. The image-level health
+probe, outage/recovery and live native-state preservation checks passed after
+reloading the corrected manifest. Production Portainer again fetched the exact
+repository branch and Compose content from its own network namespace.
+
+Version preparation is 1.8.22-alpha. No new release tag or fleet-visible update
+manifest is published by the version commit. Optimized candidate deployment,
+artifact inspection, ISO smoke/boot checks and offline signatures follow.
@@ -6,8 +6,8 @@ Reviewed both open PRs from the repository pull-request list: [#161](https://sou
 and [#162](https://source.archipelago-foundation.org/lfg2025/archy/pulls/162).
 Both branches were updated from main, repaired and tested independently and
 together. Their existing remote branches were advanced without rewriting the
-contributors' history. They remain open for integration into the release after
-1.8.21; no reviewed code was merged into main or deployed to a live wallet.
+contributors' history. Both were subsequently merged and closed and are now
+integrated on main. Candidate live-wallet acceptance remains pending.
 The signed 1.8.21 artifacts are unchanged.

 | Candidate | Tested commit | Isolated backend result |
@@ -95,8 +95,8 @@ Logs on the development box:

 ## Next-release acceptance and limits

- Integrate the reviewed branches and repeat the release gates against the
-  final release commit if additional code changes land.
+- Both reviewed branches are integrated on main alongside the lifecycle fixes.
+  Repeat release gates against the final release commit after remaining changes.
 - Perform funded peer-to-peer acceptance on the candidate build, including a
  Tor-only purchase and a purchase requiring change, before the next release.
  The new review branches were not deployed to funded live wallets here.
@@ -109,8 +109,8 @@ Logs on the development box:
  ordinary write failures and truncated input are tested to clean up. The final
  filename is published only after complete input, and existing files remain
  protected.
- The separately reported X250 kiosk version-selector rendering issue remains
-  open in `TODO.md` and requires validation on the actual kiosk.
+- The separately reported X250 kiosk selector is fixed and verified on the
+  actual kiosk; see the lifecycle evidence and consolidated release checklist.

 ## Authorized merge — 2026-09-30

@@ -122,6 +122,5 @@ Gitea normal merges completed and read-back confirmed `merged=true`, `state=clos
 - #161: `3daea6623be3e2c7222101b8e6ac411423c7e16c`.
 - #162: `b02ba4100d922dd1b75c6a78121ef446c2159a54`.

-Local next-release lifecycle work will be integrated with this main before the
-next release. Funded release acceptance and the documented delivery-receipt
+Local next-release lifecycle work was integrated with main at `d69e8452`. Funded release acceptance and the documented delivery-receipt
 limitation remain as recorded above; merging does not claim a new release.
@@ -1,6 +1,9 @@
 # Repair and release execution — 2026-09-29

-**Status: IN PROGRESS. Do not publish an OTA or ISO until the release gates pass.**
+**Status: 1.8.21 PUBLISHED — see the completion record at the end.**
+
+The next release is tracked in [the current execution checklist](next-release-20260930.md).
+The dated entries below preserve the investigation history.

 User requires all tasks completed and tested on the development box before the
 next OTA and raw ISO. Passing unit tests alone does not establish live correctness.
@@ -52,8 +55,8 @@ next OTA and raw ISO. Passing unit tests alone does not establish live correctne
 - [x] Live waiting/UI verified on dev; recovery covered by deterministic tests.
 - [x] Framework operator acceptance and authorization to release recorded.
 - [x] Release version/changelog, catalog/image implications, signing prepared.
- [ ] Signed OTA built, tested, published to git and ngit.
- [ ] Raw ISO built, boot-tested, signed and published; download command supplied.
+- [x] Signed OTA built, tested, published to git and ngit.
+- [x] Raw ISO built, boot-tested, signed and published; download command supplied.

 Tests must not wipe/recreate wallets, prune the operator's existing full chain,
 or claim that arbitrary failures can never happen. Record material gaps before
@@ -1,21 +0,0 @@
-# Gitea iframe proxy — strips X-Frame-Options so Gitea works in Archipelago iframe.
-# Gitea container binds to port 3001, this proxy listens on port 3000 (the public port).
-# Deployed to /etc/nginx/conf.d/gitea-iframe.conf
-server {
-    listen 3000;
-    server_name _;
-    client_max_body_size 1G;
-
-    location / {
-        proxy_pass http://127.0.0.1:3001;
-        proxy_set_header Host $http_host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_hide_header X-Frame-Options;
-        proxy_hide_header Content-Security-Policy;
-    }
-}
@@ -1,12 +1,12 @@
 {
  "name": "neode-ui",
-  "version": "1.8.21-alpha",
+  "version": "1.8.22-alpha",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "neode-ui",
-      "version": "1.8.21-alpha",
+      "version": "1.8.22-alpha",
      "dependencies": {
        "@scure/bip39": "^2.2.0",
        "@types/dompurify": "^3.0.5",
@@ -1,7 +1,7 @@
 {
  "name": "neode-ui",
  "private": true,
-  "version": "1.8.21-alpha",
+  "version": "1.8.22-alpha",
  "type": "module",
  "scripts": {
    "start": "./start-dev.sh",
@@ -644,6 +644,35 @@
          "/var/lib/archipelago/vaultwarden:/data"
        ]
      }
+    },
+    {
+      "id": "angor-indexer",
+      "title": "Angor Indexer",
+      "version": "1.0.1",
+      "description": "Headless Bitcoin indexer endpoint for Angor. Reuses this node’s Mempool and Electrum index; requires a synced, unpruned Bitcoin node. Add this service’s address as the custom indexer in Angor settings. A relay is optional and installed separately.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-indexer:1.0.1",
+      "author": "Angor / Archipelago",
+      "requires": [
+        "Mempool API",
+        "Unpruned Bitcoin"
+      ],
+      "category": "money",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/block-core/angor"
+    },
+    {
+      "id": "angor-relay",
+      "title": "Angor Relay",
+      "version": "1.1.2",
+      "description": "Optional dedicated Nostr relay for Angor project metadata. Separate storage and access settings keep the node’s internal relay private. Add this service’s address to Angor’s relay settings; use WSS for browser clients.",
+      "dockerImage": "source.archipelago-foundation.org/chaum/angor-relay:1.1.2",
+      "author": "Angor / Archipelago",
+      "requires": [],
+      "category": "nostr",
+      "tier": "optional",
+      "icon": "/assets/img/app-icons/angor-green.png",
+      "repoUrl": "https://github.com/hoytech/strfry"
    }
  ]
 }
@@ -42,6 +42,8 @@ export const GENERATED_APP_PORTS: Record<string, number> = {
 export const GENERATED_APP_TITLES: Record<string, string> = {
  "aiui": "AI Assistant",
  "alby-hub": "Alby Hub",
+  "angor-indexer": "Angor Indexer",
+  "angor-relay": "Angor Relay",
  "archipelago-source": "GitWorkshop",
  "archy-btcpay-db": "BTCPay Postgres",
  "archy-mempool-db": "Mempool MariaDB",
@@ -4,7 +4,7 @@
    :data-controller-launch="canLaunch(pkg) ? '' : undefined"
    tabindex="0"
    role="link"
-    class="glass-card p-6 transition-all hover:-translate-y-1 cursor-pointer relative min-w-0 overflow-hidden"
+    class="glass-card flex flex-col h-full p-6 transition-all hover:-translate-y-1 cursor-pointer relative min-w-0 overflow-hidden"
    :class="{ 'card-stagger': showStagger }"
    :style="{ '--stagger-index': index }"
    @click="$emit('goToApp', id)"
@@ -56,9 +56,9 @@
      {{ description }}
    </p>

-    <div v-if="!isInstalling && !isUninstalling && pkg.state !== 'installing'" class="flex items-center gap-2">
+    <div v-if="!isInstalling && !isUninstalling && pkg.state !== 'installing'" class="flex items-center gap-2 min-w-0">
      <span
-        class="inline-flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium"
+        class="shrink-0 inline-flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium"
        :class="getStatusClass(pkg.state, pkg.health, pkg['exit-code'])"
      >
        <svg
@@ -74,14 +74,14 @@
        <span v-if="pkg.state === 'running' && pkg.health === 'unhealthy'" class="w-1.5 h-1.5 rounded-full bg-orange-400 animate-pulse"></span>
        {{ getStatusLabel(pkg.state, pkg.health, pkg['exit-code']) }}
      </span>
-    </div>
-    <p v-if="blockedReason" class="mt-2 text-xs leading-snug text-yellow-200/80">
+      <p v-if="blockedReason" :title="blockedReason" class="min-w-0 truncate text-xs leading-snug text-yellow-200/80">
        {{ blockedReason }}
      </p>
+    </div>

    <!-- Quick Actions — icon buttons in uniform dark containers -->
    <!-- Installing progress — replaces action buttons -->
-    <div v-if="isInstalling || pkg.state === 'installing'" class="mt-4">
+    <div v-if="isInstalling || pkg.state === 'installing'" class="mt-auto pt-4">
      <div class="flex items-center justify-between mb-1.5">
        <span class="text-xs text-white/70 flex items-center gap-1.5">
          <svg class="animate-spin h-3 w-3" fill="none" viewBox="0 0 24 24">
@@ -101,7 +101,7 @@
    </div>

    <!-- Uninstalling progress — truthful stage-driven bar (mirrors install) -->
-    <div v-else-if="isUninstalling" class="mt-4">
+    <div v-else-if="isUninstalling" class="mt-auto pt-4">
      <div class="flex items-center justify-between mb-1.5">
        <span class="text-xs text-white/70 flex items-center gap-1.5">
          <svg class="animate-spin h-3 w-3" fill="none" viewBox="0 0 24 24">
@@ -120,7 +120,7 @@
      </div>
    </div>

-    <div v-else class="mt-4 flex gap-2">
+    <div v-else class="mt-auto pt-4 flex gap-2">
      <!-- Update available -->
      <button
        v-if="pkg['available-update'] && pkg.state !== 'updating'"
@@ -214,7 +214,7 @@ import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import type { PackageDataEntry } from '@/types/api'
 import {
-  isWebOnlyApp, opensInTab, canLaunch, launchBlockedReason, resolveAppIcon,
+  isWebOnlyApp, opensInTab, canLaunch, launchBlockedReason, resolveAppIcon, resolveAppTitle,
  getStatusClass, getStatusLabel, handleImageError,
 } from './appsConfig'
 import { getCuratedAppList } from '../discover/curatedApps'
@@ -255,10 +255,7 @@ const isWebOnly = computed(() => isWebOnlyApp(props.id))

 // Enrich from marketplace when backend data is sparse (e.g. during install)
 const curated = computed(() => curatedMap.get(props.id))
-const title = computed(() => {
-  const t = props.pkg.manifest?.title
-  return (t && t !== props.id) ? t : (curated.value?.title || t || props.id)
-})
+const title = computed(() => resolveAppTitle(props.id, props.pkg, curated.value?.title))
 const description = computed(() => {
  const d = props.pkg.manifest?.description?.short
  return (d && d !== 'Installing...') ? d : (curated.value?.description || d || '')
@@ -132,7 +132,7 @@ import type { AppCredential, AppCredentialsResponse, PackageDataEntry } from '@/
 import { rpcClient } from '@/api/rpc-client'
 import { resolveAppUrl } from '@/views/appSession/appSessionConfig'
 import { resolveAppCredentials } from './appCredentials'
-import { canLaunch, handleImageError, isWebsitePackage, opensInTab, resolveAppIcon, resolveRuntimeLaunchUrl, WEB_ONLY_APP_URLS } from './appsConfig'
+import { canLaunch, handleImageError, isWebsitePackage, opensInTab, resolveAppIcon, resolveAppTitle, resolveRuntimeLaunchUrl, WEB_ONLY_APP_URLS } from './appsConfig'
 import { getCuratedAppList } from '../discover/curatedApps'

 const ITEMS_PER_PAGE = 16 // 4 columns x 4 rows
@@ -194,9 +194,7 @@ const pages = computed(() => {
 })

 function getTitle(id: string, pkg: PackageDataEntry): string {
-  const t = pkg.manifest?.title
-  if (t && t !== id) return t
-  return curatedMap.get(id)?.title || t || id
+  return resolveAppTitle(id, pkg, curatedMap.get(id)?.title)
 }

 function getIcon(id: string, pkg: PackageDataEntry): string {
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { ref } from 'vue'
 import { PackageState, type PackageDataEntry } from '@/types/api'
-import { APP_CATEGORY_MAP, canLaunch, filterEntriesForTab, hasFrontendUi, isServiceContainer, isServicePackage, isWebsitePackage, isAppReadyForLaunch, launchBlockedReason, resolveAppIcon, useCategoriesWithApps, DEFAULT_APP_ICON } from '../appsConfig'
+import { APP_CATEGORY_MAP, canLaunch, filterEntriesForTab, hasFrontendUi, isServiceContainer, isServicePackage, isWebsitePackage, isAppReadyForLaunch, launchBlockedReason, resolveAppIcon, resolveAppTitle, useCategoriesWithApps, DEFAULT_APP_ICON } from '../appsConfig'

 function makePkg(id: string, title: string, category: string): PackageDataEntry {
  return {
@@ -25,6 +25,15 @@ function makePkg(id: string, title: string, category: string): PackageDataEntry
 }

 describe('appsConfig service filtering', () => {
+  it('keeps standalone Angor APIs in Services without a launch button', () => {
+    for (const id of ['angor-indexer', 'angor-relay']) {
+      const pkg = makePkg(id, id, 'money')
+      expect(filterEntriesForTab([[id, pkg]], 'services', 'all')).toHaveLength(1)
+      expect(filterEntriesForTab([[id, pkg]], 'apps', 'all')).toHaveLength(0)
+      expect(canLaunch(pkg)).toBe(false)
+    }
+  })
+
  it('treats bitcoin stack UI sidecars as services', () => {
    expect(isServiceContainer('bitcoin-ui')).toBe(true)
    expect(isServiceContainer('lnd-ui')).toBe(true)
@@ -158,7 +167,7 @@ describe('appsConfig service filtering', () => {
    pkg.health = null
    expect(isAppReadyForLaunch(pkg)).toBe(false)
    expect(canLaunch(pkg)).toBe(false)
-    expect(launchBlockedReason(pkg.manifest.id, pkg)).toContain('Starting up')
+    expect(launchBlockedReason(pkg.manifest.id, pkg)).toBe('Web UI not ready: GitWorkshop')
    pkg.health = 'healthy'
    expect(canLaunch(pkg)).toBe(true)
  })
@@ -185,6 +194,18 @@ describe('appsConfig service filtering', () => {
  })
 })

+describe('headless service readiness messages', () => {
+  it('does not treat an API-only service as waiting for its own nonexistent UI', () => {
+    for (const id of ['phoenixd', 'angor-indexer', 'angor-relay', 'custom-api']) {
+      const pkg = makePkg(id, id, 'other')
+      pkg['ui-ready'] = false
+      pkg.health = 'healthy'
+      expect(canLaunch(pkg)).toBe(false)
+      expect(launchBlockedReason(id, pkg)).toBe('')
+    }
+  })
+})
+
 describe('HTTP readiness independent of container health', () => {
  it('blocks fixed launch URLs while the HTTP upstream is unavailable', () => {
    for (const id of ['gitea', 'filebrowser', 'fedimint', 'lnd']) {
@@ -193,7 +214,7 @@ describe('HTTP readiness independent of container health', () => {
      pkg.health = 'healthy'
      expect(canLaunch(pkg)).toBe(false)
      expect(isAppReadyForLaunch(pkg)).toBe(false)
-      expect(launchBlockedReason(id, pkg)).toContain('Waiting')
+      expect(launchBlockedReason(id, pkg)).toBe(`Web UI not ready: ${resolveAppTitle(id, pkg)}`)
      pkg['ui-ready'] = true
      expect(isAppReadyForLaunch(pkg)).toBe(true)
    }
@@ -205,3 +226,23 @@ describe('HTTP readiness independent of container health', () => {
    expect(isAppReadyForLaunch(pkg)).toBe(true)
  })
 })
+
+describe('manifest-generated service names', () => {
+  it('gives a new headless service its declared name without a hardcoded curated entry', () => {
+    const pkg = makePkg('angor-relay', 'angor-relay', 'money')
+    expect(resolveAppTitle('angor-relay', pkg)).toBe('Angor Relay')
+    pkg.manifest.title = 'My project relay'
+    expect(resolveAppTitle('angor-relay', pkg)).toBe('My project relay')
+    expect(resolveAppTitle('unknown-service', makePkg('unknown-service', 'unknown-service', ''))).toBe('unknown-service')
+  })
+})
+
+it('does not display a stale Mempool frontend alias beside its live package', () => {
+  const main = makePkg('mempool', 'Mempool', 'money')
+  const alias = makePkg('mempool-web', 'Mempool', 'money')
+  alias.state = PackageState.Restarting
+  const entries: Array<[string, PackageDataEntry]> = [['mempool', main], ['mempool-web', alias]]
+  const shown = [...filterEntriesForTab(entries, 'apps', 'all'), ...filterEntriesForTab(entries, 'services', 'all')]
+  expect(shown.map(([id]) => id)).toEqual(['mempool'])
+  expect(filterEntriesForTab([['mempool-web', alias]], 'apps', 'all').map(([id]) => id)).toEqual(['mempool-web'])
+})
@@ -4,6 +4,7 @@ import type { Ref } from 'vue'
 import { computed } from 'vue'
 import { PackageState, type PackageDataEntry } from '@/types/api'
 import { matchPageScheme, resolveAppUrl } from '../appSession/appSessionConfig'
+import { GENERATED_APP_TITLES } from '../appSession/generatedAppSessionConfig'
 import { portIsGateFronted } from '../discover/curatedApps'
 import { isAutoTabApp } from '@/utils/autoTabApps'
 import {
@@ -13,6 +14,14 @@ import {

 export type AppsTab = 'apps' | 'websites' | 'services'

+/** Use manifest-generated names when a new service has only its ID in runtime state. */
+export function resolveAppTitle(id: string, pkg: PackageDataEntry, curatedTitle?: string): string {
+  const title = pkg.manifest?.title
+  if (title && title !== id) return title
+  return curatedTitle || GENERATED_APP_TITLES[id] || title || id
+}
+
+
 // Re-exported for every existing caller — the canon moved to serviceNames.ts
 // so the App Store's catalog merge can share it without a circular import.
 export const SERVICE_NAMES = SHARED_SERVICE_NAMES
@@ -102,7 +111,12 @@ export function filterEntriesForTab(
  activeTab: AppsTab,
  selectedCategory: string,
 ): Array<[string, PackageDataEntry]> {
+  const hasMempool = entries.some(([id]) => id === 'mempool')
  return entries.filter(([id, pkg]) => {
+    // Older daemons can retain the frontend manifest alias during a restart.
+    // Keep one tile while the updated scanner converges; a legacy-only node
+    // must still be able to see and operate its sole Mempool entry.
+    if (hasMempool && ['mempool-web', 'mempool-frontend', 'archy-mempool-web'].includes(id)) return false
    if (isInternalToolingPackage(id, pkg)) return false
    const wantsWebsites = activeTab === 'websites' || activeTab === 'services'
    const isWebsite = isWebsitePackage(id, pkg)
@@ -222,6 +236,7 @@ function serviceParentIcon(id: string): string | undefined {
 export const DEFAULT_APP_ICON = '/assets/icon/favico-black-v2.svg'

 export function resolveAppIcon(id: string, pkg: PackageDataEntry, curatedIcon?: string): string {
+  if (id === 'angor-indexer' || id === 'angor-relay') return '/assets/img/app-icons/angor-green.png'
  const rawIcon = (pkg["static-files"]?.icon || "").trim()
  const icon = rawIcon === '/assets/img/favico.png' ? '' : rawIcon
  if (
@@ -287,9 +302,13 @@ export function isAppReadyForLaunch(pkg: PackageDataEntry): boolean {

 export function launchBlockedReason(id: string, pkg?: PackageDataEntry | null): string {
  const appId = pkg?.manifest?.id || id
+  const title = pkg ? resolveAppTitle(appId, pkg) : id
+  // API-only services have no web interface to wait for. Their health badge
+  // describes service availability; a failed HTML probe is not a dependency.
+  if (pkg && isWebsitePackage(appId, pkg)) return ''
  if (pkg?.['ui-ready'] === false && !isServicePackage(appId, pkg)) {
    if (pkg.state === PackageState.Stopped || pkg.state === PackageState.Exited) return 'App is stopped. Start it to open it.'
-    return 'Waiting for the app to be ready…'
+    return `Web UI not ready: ${title}`
  }
  if (
    (appId === 'fedimint' || appId === 'fedimintd') &&
@@ -298,7 +317,7 @@ export function launchBlockedReason(id: string, pkg?: PackageDataEntry | null):
    return 'Guardian opens a wait page until Bitcoin finishes initial sync.'
  }
  if (pkg && pkg.state === PackageState.Running && !isAppReadyForLaunch(pkg)) {
-    return 'Starting up — Launch will appear when the app is ready.'
+    return `Web UI not ready: ${title}`
  }
  return ''
 }
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from 'vitest'
-import { __setSignedCatalogForTests, portAuth, portIsGateFronted, type SignedAppCatalog } from '../curatedApps'
+import { __setSignedCatalogForTests, signedCatalogToApps, portAuth, portIsGateFronted, type SignedAppCatalog } from '../curatedApps'

 /** Catalog fragments mirroring the live signed catalog's port declarations
 *  (releases/app-catalog.json, 2026-09-01). */
@@ -77,3 +77,12 @@ describe('portAuth', () => {
    expect(portAuth('mempool-web', 4080)).toBeNull()
  })
 })
+
+describe('standalone headless services', () => {
+  it('lists Angor services while keeping shared Mempool and node relay internals hidden', () => {
+    const apps = signedCatalogToApps(catalog(Object.fromEntries(
+      ['angor-indexer', 'angor-relay', 'mempool-api', 'strfry'].map(id => [id, { version: '1' }]),
+    )))
+    expect(apps.map(app => app.id)).toEqual(['angor-indexer', 'angor-relay'])
+  })
+})
@@ -362,6 +362,31 @@ init()
              </button>
            </div>
            <div class="overflow-y-auto flex-1 min-h-0 space-y-6 pr-1">
+              <!-- v1.8.22-alpha -->
+              <div>
+                <div class="flex items-center gap-2 mb-3">
+                  <span class="text-xs font-mono px-2 py-0.5 rounded bg-orange-500/20 text-orange-300">v1.8.22-alpha</span>
+                  <span class="text-xs text-white/40">September 30, 2026</span>
+                </div>
+                <div class="space-y-3 text-sm text-white/80 pl-3 border-l border-white/10">
+                  <p>Fixed Angor Indexer health checks choosing IPv6 localhost for an IPv4 listener and unnecessarily restarting the working service.</p>
+                  <p>Prevented false app restarts by probing each published port at its actual bind address; Nginx Proxy Manager now checks its internal admin API.</p>
+                  <p>Added a backed-up migration for the recognized legacy Nginx Proxy Manager tunnel/LND port conflict in both OTA and ISO startup paths.</p>
+                  <p>Checked Bitcoin and Electrum companion dashboards instead of backend protocol ports, preserving dashboard access during initial sync.</p>
+                  <p>Removed web-interface waiting messages from headless services such as Phoenixd and clarified which interface is unavailable for launchable apps.</p>
+                  <p>Finished runtime app-file promotion before manifest loading, preventing startup catalog refresh from forgetting disk-only apps.</p>
+                  <p>Named the app in compact readiness messages and kept app-card actions aligned at the bottom.</p>
+                  <p>Removed duplicate Mempool cards caused by frontend container aliases in restored inventory.</p>
+                  <p>Kept installed apps visible through restarts and hard refreshes, and delayed app launches until their web interface is ready.</p>
+                  <p>Made Bitcoin version selection readable and usable in the ThinkPad kiosk, above the pruning settings.</p>
+                  <p>Restored GitWorkshop build files in installation/update payloads and made slow image-pull progress clearer.</p>
+                  <p>Fixed same-node Gitea access from Portainer, with persistent runtime migration, state backups and recovery after failed restarts.</p>
+                  <p>Preserved Gitea configuration and SSH operation during fresh setup and upgrades.</p>
+                  <p>Improved paid-file delivery, saved-file permissions and repeat-download compatibility; verified Tor-only payment with change, rejection refunds and free repeat downloads.</p>
+                  <p>Added a headless Angor Indexer service using the existing Mempool/ElectrumX stack, and an optional separate Angor relay.</p>
+                  <p>Prevented manifest command arguments containing apostrophes from being corrupted in generated services.</p>
+                </div>
+              </div>
              <!-- v1.8.21-alpha -->
              <div>
                <div class="flex items-center gap-2 mb-3">
@@ -81,6 +81,11 @@ def load_catalog(path: Path) -> dict[str, dict[str, Any]]:
            if not isinstance(entry, dict):
                continue
            manifest = entry.get("manifest")
+            for variant in reversed(entry.get("manifest_variants", [])):
+                requires = variant.get("requires", [])
+                if requires and all(cap == "runtime-migration-backup-v1" for cap in requires):
+                    manifest = variant.get("manifest")
+                    break
            if isinstance(manifest, dict) and isinstance(manifest.get("app"), dict):
                # Embedded manifest: compare against the same fields the disk
                # manifests expose, plus the entry's own version.
@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Test Git from Portainer's server context without creating a Source or stack."""
+import argparse
+import json
+import pathlib
+import socket
+import stat
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def classify(error):
+    text = error.lower()
+    for category, patterns in (
+        ('connection-refused', ('connection refused',)),
+        ('dns-failure', ('no such host', 'name resolution', 'server misbehaving')),
+        ('timeout', ('timeout', 'timed out', 'deadline exceeded')),
+        ('tls-failure', ('x509:', 'certificate', 'tls handshake')),
+        ('proxy-or-login-interception', ('text/html', '<html', '<!doctype', 'unexpected content-type', 'invalid pkt-len')),
+        ('repository-authentication', ('authentication required', 'authentication failed', 'authorization failed', '401', '403')),
+        ('repository-not-found-or-private', ('repository not found', '404')),
+    ):
+        if any(pattern in text for pattern in patterns):
+            return category
+    return 'git-error'
+
+
+def safe_url(value):
+    parsed = urllib.parse.urlsplit(value)
+    if parsed.scheme not in ('http', 'https') or not parsed.hostname:
+        raise ValueError('Use an HTTP(S) URL')
+    if parsed.username is not None or parsed.password is not None or parsed.query or parsed.fragment:
+        raise ValueError('URLs must not contain credentials, query parameters or fragments')
+    return value.rstrip('/')
+
+
+def private_json(path):
+    path = pathlib.Path(path)
+    if stat.S_IMODE(path.stat().st_mode) & 0o077:
+        raise ValueError('Credential file must be private (chmod 600)')
+    return json.loads(path.read_text())
+
+
+def check(base, repository, credentials, opener=None):
+    base, repository = safe_url(base), safe_url(repository)
+    # JWT/API keys and Git credentials travel in headers/body, never URLs or logs.
+    headers = {'Content-Type': 'application/json'}
+    if credentials.get('api_key'):
+        headers['X-API-Key'] = credentials['api_key']
+    elif credentials.get('jwt'):
+        headers['Authorization'] = 'Bearer ' + credentials['jwt']
+    else:
+        raise ValueError('Credential file needs api_key or jwt')
+    payload = {'url': repository, 'tlsSkipVerify': False, 'interval': '5m'}
+    if credentials.get('git'):
+        payload['authentication'] = credentials['git']
+    request = urllib.request.Request(base + '/api/gitops/sources/test',
+                                     data=json.dumps(payload).encode(), headers=headers)
+    opener = opener or urllib.request.build_opener(NoRedirect())
+    try:
+        with opener.open(request, timeout=45) as response:
+            result = json.load(response)
+    except urllib.error.HTTPError as error:
+        return {'success': False, 'category': 'portainer-authentication' if error.code in (401, 403) else 'portainer-api-error', 'http_status': error.code}
+    except (urllib.error.URLError, TimeoutError, socket.timeout) as error:
+        return {'success': False, 'category': 'portainer-api-' + classify(str(error))}
+    except (ValueError, UnicodeError):
+        return {'success': False, 'category': 'portainer-api-invalid-response'}
+    if not isinstance(result, dict) or not isinstance(result.get('success'), bool):
+        return {'success': False, 'category': 'portainer-api-invalid-response'}
+    return {'success': result['success'], 'category': 'git-refs-readable' if result['success'] else classify(str(result.get('error', '')))}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--portainer-url', required=True, help='Reachable Portainer origin, without /api')
+    parser.add_argument('--repository-url', required=True, help='The same clone URL entered in Portainer')
+    parser.add_argument('--credentials-file', required=True, help='Mode 600 JSON: api_key or jwt; optional git: {username,password}')
+    args = parser.parse_args()
+    try:
+        result = check(args.portainer_url, args.repository_url, private_json(args.credentials_file))
+    except (OSError, ValueError):
+        parser.exit(2, 'Invalid URL or private credential file; no credentials were printed.\n')
+    print(json.dumps(result))
+    return 0 if result['success'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())
@@ -72,6 +72,10 @@ def manifest_launch_port(app: dict[str, Any]) -> int | None:
                return port
            if isinstance(port, str) and port.isdigit():
                return int(port)
+        # An explicitly headless API/metrics declaration must not gain a
+        # browser launch button just because it has an HTTP health check.
+        if interfaces:
+            return None

    health_check = app.get("health_check")
    if not isinstance(health_check, dict) or str(health_check.get("type", "")).lower() != "http":
@@ -95,6 +99,20 @@ def manifest_launch_port(app: dict[str, Any]) -> int | None:
    return None


+def manifest_service_ports(app: dict[str, Any]) -> list[int]:
+    """Declared API endpoints served by the gate also need mesh reachability."""
+    interfaces = app.get("interfaces") or {}
+    declared = {
+        int(i["port"]) for i in interfaces.values()
+        if isinstance(i, dict) and i.get("type") in ("api", "metrics")
+        and str(i.get("port", "")).isdigit()
+    }
+    return [int(p["host"]) for p in app.get("ports", [])
+            if str(p.get("host", "")).isdigit() and int(p["host"]) in declared
+            and p.get("auth") in ("open", "gated", "session")
+            and p.get("protocol", "tcp") == "tcp"]
+
+
 def manifest_opens_in_new_tab(app: dict[str, Any]) -> bool:
    """Return whether manifest launch metadata opts the app out of iframe launch."""
    launch = metadata(app).get("launch")
@@ -190,6 +208,7 @@ def render_rust_ports(ports: dict[str, int], extra_ports: list[int]) -> str:
        "//! are reachable over the mesh; ports of apps that aren\'t installed have",
        "//! no listener, so allowing them is inert.",
        "",
+        "#[rustfmt::skip]",
        "pub const APP_LAUNCH_PORTS: &[u16] = &[",
    ]
    lines.extend(f"    {port}," for port in distinct)
@@ -274,7 +293,8 @@ def main() -> int:
            if (port := manifest_launch_port(app))
        }
        rust_path = Path(args.rust_app_ports)
-        rust_content = render_rust_ports(ports, RUST_EXTRA_PORTS)
+        service_ports = [p for app in manifests.values() for p in manifest_service_ports(app)]
+        rust_content = render_rust_ports(ports, RUST_EXTRA_PORTS + service_ports)
        rust_old = rust_path.read_text(encoding="utf-8") if rust_path.exists() else ""
        if rust_old != rust_content:
            rust_path.write_text(rust_content, encoding="utf-8")
@@ -36,11 +36,15 @@ source "$ROOT/scripts/image-versions.sh"
 set +a

 UPDATED="$(date -u +%Y-%m-%d)" OUT="$OUT" APPS_DIR="$ROOT/apps" \
+BASE_CATALOG="${BASE_CATALOG:-$ROOT/releases/app-catalog.json}" \
 PUBLIC_CATALOG="$ROOT/app-catalog/catalog.json" \
 EMBED_MANIFESTS="${EMBED_MANIFESTS:-1}" python3 - <<'PY'
 import glob
 import json, os

+with open(os.environ["BASE_CATALOG"], encoding="utf-8") as baseline_file:
+    baseline_entries = json.load(baseline_file).get("apps", {})
+
 try:
    import yaml
 except ImportError:
@@ -182,7 +186,17 @@ if os.environ.get("EMBED_MANIFESTS") and apps_dir:
            continue
        entry = apps.setdefault(str(app_id), {})
        entry.setdefault("version", str(app.get("version", "")) or "0")
-        entry["manifest"] = _retarget_registry(data)
+        rendered = _retarget_registry(data)
+        if data["app"].get("backup_before_runtime_change"):
+            baseline = baseline_entries.get(app_id, {}).get("manifest")
+            if not baseline or baseline.get("app", {}).get("backup_before_runtime_change"):
+                raise SystemExit(f"{app_id}: a pre-migration BASE_CATALOG manifest is required for old-node compatibility")
+            entry["manifest"] = baseline
+            entry["manifest_variants"] = [{
+                "requires": ["runtime-migration-backup-v1"], "manifest": rendered,
+            }]
+        else:
+            entry["manifest"] = rendered
        embedded += 1

 # Multi-version support (docs/bitcoin-multi-version-design.md §3 Phase 1):
@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Migrate the known NPM/LND tunnel collision, without touching wallet services.
+
+Runs as the rootless app owner before orchestrator startup. Only the narrow
+legacy web-tunnel profile is accepted. Unknown custom routing fails closed.
+"""
+import ipaddress
+import json
+import os
+from pathlib import Path
+import re
+import socket
+import subprocess
+import tempfile
+
+
+def command(*args, input=None):
+    result = subprocess.run(args, input=input, text=True, capture_output=True, timeout=45)
+    if result.returncode:
+        # Commands may read private files. Never print their captured output.
+        raise RuntimeError(f'{args[0]} operation failed (exit {result.returncode})')
+    return result.stdout
+
+
+def plan(drop, rules):
+    """Return a conservative migration, or None for absent/already fixed mapping."""
+    matches = re.findall(r'^PublishPort=([0-9.]+):18080:80/tcp$', drop, re.M)
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise ValueError('ambiguous NPM tunnel mapping')
+    destination = str(ipaddress.IPv4Address(matches[0]))
+    peer_match = re.search(r'ip saddr ([0-9.]+) ip daddr ' + re.escape(destination)
+                           + r' tcp dport \{ 18080, 18443 \} accept', rules)
+    if not peer_match:
+        raise ValueError('unrecognized NPM tunnel firewall; manual review required')
+    peer = str(ipaddress.IPv4Address(peer_match[1]))
+    # Match the entire old profile, not just a substring in an arbitrary firewall.
+    old = f'''table inet web_tunnel {{
+    chain input {{
+        type filter hook input priority -10; policy accept;
+        iifname != "wg-web" return
+        ct state established,related accept
+        ip saddr {peer} icmp type echo-request accept
+        ip saddr {peer} ip daddr {destination} tcp dport {{ 18080, 18443 }} accept
+        counter drop
+    }}
+    chain forward {{
+        type filter hook forward priority -10; policy accept;
+        iifname "wg-web" counter drop
+        oifname "wg-web" counter drop
+    }}
+}}'''
+    if rules.split() != old.split():
+        raise ValueError('custom NPM tunnel firewall differs; manual review required')
+    if 'PublishPort='+destination+':18081:' in drop:
+        raise ValueError('replacement port already configured')
+    new_rules = rules.replace('table inet web_tunnel {', f'''table inet web_tunnel {{
+    # Preserve incoming HTTP while keeping LND REST's port free.
+    chain prerouting {{
+        type nat hook prerouting priority dstnat; policy accept;
+        iifname "wg-web" ip saddr {peer} ip daddr {destination} tcp dport 18080 redirect to :18081
+    }}''', 1).replace('tcp dport { 18080, 18443 } accept',
+                     'tcp dport { 18081, 18443 } accept')
+    return (drop.replace(f'PublishPort={destination}:18080:80/tcp',
+                         f'PublishPort={destination}:18081:80/tcp'), new_rules, destination)
+
+
+def atomic_user(path, content):
+    with tempfile.NamedTemporaryFile(mode='w', dir=path.parent, delete=False) as f:
+        tmp = Path(f.name)
+        os.fchmod(f.fileno(), 0o600)
+        f.write(content)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+
+
+def root_write(path, content):
+    # Stage next to the destination; rename makes the config update atomic.
+    staged = str(path)+'.archy-npm-migration'
+    command('sudo', '-n', 'tee', staged, input=content)
+    command('sudo', '-n', 'chmod', '600', staged)
+    command('sudo', '-n', 'mv', '--', staged, str(path))
+
+
+def main():
+    drop = Path.home()/'.config/containers/systemd/nginx-proxy-manager.container.d/web-tunnel.conf'
+    rules_path = Path('/etc/wireguard/wg-web.nft')
+    state = Path.home()/'.local/state/archipelago/npm-tunnel-migration'
+    journal = state/'pending.json'
+    recovered_active = None
+    # Interrupted migrations are completed/rolled back before normal startup.
+    if journal.exists():
+        saved = json.loads(journal.read_text())
+        command('systemctl', '--user', 'stop', 'nginx-proxy-manager.service')
+        atomic_user(drop, saved['drop'])
+        root_write(rules_path, saved['rules'])
+        command('sudo', '-n', 'nft', '-f', '-', input='delete table inet web_tunnel\n'+saved['rules'])
+        command('systemctl', '--user', 'daemon-reload')
+        # Do not restart the colliding old configuration before reapplying.
+        recovered_active = saved.get('was_active')
+        journal.unlink()
+    if not drop.exists():
+        return
+    old_drop = drop.read_text()
+    if not re.search(r'^PublishPort=[0-9.]+:18080:80/tcp$', old_drop, re.M):
+        return
+    old_rules = command('sudo', '-n', 'cat', str(rules_path))
+    new_drop, new_rules, destination = plan(old_drop, old_rules)
+    # A free, assigned replacement is required; do not guess another port.
+    with socket.socket() as probe:
+        probe.bind((destination, 18081))
+    # The route must be persistent and loaded by the tunnel's startup contract.
+    wg = command('sudo', '-n', 'grep', '-E', r'^(PreUp|PostDown)\s*=', '/etc/wireguard/wg-web.conf')
+    if 'PreUp = nft -f /etc/wireguard/wg-web.nft' not in wg or 'PostDown = nft delete table inet web_tunnel' not in wg:
+        raise ValueError('unrecognized tunnel lifecycle; manual review required')
+    active = command('sudo', '-n', 'nft', 'list', 'table', 'inet', 'web_tunnel')
+    # Reject live-only rule changes instead of silently discarding them. nft
+    # canonicalizes priority names and adds counter values when listing rules.
+    def normalized(text):
+        text = re.sub(r'counter packets \d+ bytes \d+', 'counter', text)
+        return text.replace('priority filter - 10', 'priority -10').split()
+    if normalized(active) != normalized(old_rules):
+        raise ValueError('live tunnel rules differ from persistent config; review required')
+    transaction = 'delete table inet web_tunnel\n'+new_rules
+    command('sudo', '-n', 'nft', '--check', '-f', '-', input=transaction)
+    state.mkdir(parents=True, exist_ok=True, mode=0o700)
+    os.chmod(state, 0o700)
+    was_active = recovered_active or command('systemctl', '--user', 'show', 'nginx-proxy-manager.service', '--property=ActiveState', '--value').strip()
+    saved = json.dumps({'drop': old_drop, 'rules': old_rules, 'was_active': was_active})
+    atomic_user(state/'before.json', saved)
+    atomic_user(journal, saved)
+    try:
+        command('systemctl', '--user', 'stop', 'nginx-proxy-manager.service')
+        atomic_user(drop, new_drop)
+        root_write(rules_path, new_rules)
+        command('sudo', '-n', 'nft', '-f', '-', input=transaction)
+        command('systemctl', '--user', 'daemon-reload')
+        if was_active in ('active', 'activating', 'reloading', 'failed'):
+            command('systemctl', '--user', 'restart', 'nginx-proxy-manager.service')
+        journal.unlink()
+    except Exception:
+        atomic_user(drop, old_drop)
+        root_write(rules_path, old_rules)
+        command('sudo', '-n', 'nft', '-f', '-', input='delete table inet web_tunnel\n'+old_rules)
+        command('systemctl', '--user', 'daemon-reload')
+        # Keep the journal if rollback fails so the next startup retries it.
+        journal.unlink()
+        raise
+    print('NPM tunnel port repaired; original configuration backed up; native services unchanged')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception as error:
+        raise SystemExit('NPM tunnel migration requires attention: '+str(error)) from None
@@ -9,7 +9,12 @@ command -v setpriv >/dev/null
 sudo -n true || { echo 'Isolated backend tests require noninteractive sudo for systemd namespaces.' >&2; exit 1; }
 metadata=$(mktemp)
 trap 'rm -f "$metadata"' EXIT
-if ! cargo test --manifest-path "$REPO/core/Cargo.toml" -p archipelago --bin archipelago \
+case "${ARCHY_TEST_PACKAGE:-archipelago}" in
+  archipelago) test_target=(-p archipelago --bin archipelago) ;;
+  archipelago-container) test_target=(-p archipelago-container --lib) ;;
+  *) echo 'Unsupported isolated test package' >&2; exit 2 ;;
+esac
+if ! cargo test --manifest-path "$REPO/core/Cargo.toml" "${test_target[@]}" \
  --locked --no-run --message-format=json --config 'profile.test.package.archipelago.opt-level=0' > "$metadata"; then
    python3 - "$metadata" <<'PYDIAG'
 import json,sys
@@ -0,0 +1,137 @@
+import importlib.util
+from pathlib import Path
+import unittest
+from unittest.mock import patch, MagicMock
+import tempfile
+import json
+
+spec=importlib.util.spec_from_file_location('repair', Path(__file__).parents[1]/'repair-npm-tunnel.py')
+m=importlib.util.module_from_spec(spec)
+spec.loader.exec_module(m)
+DROP='[Container]\nPublishPort=10.77.0.2:18080:80/tcp\nPublishPort=10.77.0.2:18443:443/tcp\n'
+RULES='''table inet web_tunnel {
+    chain input {
+        type filter hook input priority -10; policy accept;
+        iifname != "wg-web" return
+        ct state established,related accept
+        ip saddr 10.77.0.1 icmp type echo-request accept
+        ip saddr 10.77.0.1 ip daddr 10.77.0.2 tcp dport { 18080, 18443 } accept
+        counter drop
+    }
+    chain forward {
+        type filter hook forward priority -10; policy accept;
+        iifname "wg-web" counter drop
+        oifname "wg-web" counter drop
+    }
+}'''
+
+class Plan(unittest.TestCase):
+    def test_preserves_peer_https_and_restricts_redirect(self):
+        drop,rules,dst=m.plan(DROP,RULES)
+        self.assertEqual(dst,'10.77.0.2')
+        self.assertIn('PublishPort=10.77.0.2:18081:80/tcp',drop)
+        self.assertIn('PublishPort=10.77.0.2:18443:443/tcp',drop)
+        self.assertIn('iifname "wg-web" ip saddr 10.77.0.1 ip daddr 10.77.0.2 tcp dport 18080 redirect to :18081',rules)
+        self.assertNotIn('tcp dport { 18080, 18443 } accept',rules)
+        self.assertIn('iifname "wg-web" counter drop',rules)
+    def test_idempotent(self):
+        d,r,_=m.plan(DROP,RULES)
+        self.assertIsNone(m.plan(d,r))
+    def test_standard_fresh_install_untouched(self):
+        self.assertIsNone(m.plan('[Container]\nPublishPort=127.0.0.1:8081:81/tcp',''))
+    def test_no_hardcoded_deployment_address(self):
+        d,r,dst=m.plan(DROP.replace('10.77.0.','10.55.0.'),RULES.replace('10.77.0.','10.55.0.'))
+        self.assertEqual(dst,'10.55.0.2');self.assertIn('ip saddr 10.55.0.1',r)
+    def test_custom_firewall_preserved(self):
+        for r in [RULES+'\ntable inet extra {}',RULES.replace('counter drop','accept'),RULES.replace('wg-web','wg-custom')]:
+            with self.assertRaises(ValueError): m.plan(DROP,r)
+    def test_ambiguous_mapping(self):
+        with self.assertRaises(ValueError): m.plan(DROP+DROP,RULES)
+    def test_wrong_destination(self):
+        with self.assertRaises(ValueError): m.plan(DROP.replace('10.77.0.2','10.77.0.3'),RULES)
+    def test_already_used_mapping(self):
+        with self.assertRaises(ValueError): m.plan(DROP+'PublishPort=10.77.0.2:18081:80/tcp\n',RULES)
+
+class Migration(unittest.TestCase):
+    def setUp(self):
+        self.temp=tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.home=Path(self.temp.name)
+        self.drop=self.home/'.config/containers/systemd/nginx-proxy-manager.container.d/web-tunnel.conf'
+        self.drop.parent.mkdir(parents=True)
+        self.drop.write_text(DROP)
+        self.calls=[];self.rules=RULES;self.fail=None
+        self.state=self.home/'.local/state/archipelago/npm-tunnel-migration'
+    def command(self,*args,input=None):
+        self.calls.append((args,input))
+        if self.fail and self.fail(args):
+            self.fail=None
+            raise RuntimeError('injected failure')
+        if 'cat' in args or ('list' in args and 'nft' in args): return self.rules
+        if 'grep' in args: return 'PreUp = nft -f /etc/wireguard/wg-web.nft\nPostDown = nft delete table inet web_tunnel'
+        if 'show' in args: return 'active'
+        return ''
+    def run_migration(self):
+        with patch.object(Path,'home',return_value=self.home),patch.object(m,'command',side_effect=self.command),patch.object(m,'root_write') as write,patch.object(m.socket,'socket'):
+            m.main()
+            return write
+    def test_success_and_second_run_noop(self):
+        write=self.run_migration()
+        self.assertIn(':18081:80/tcp',self.drop.read_text())
+        self.assertEqual(json.loads((self.state/'before.json').read_text())['drop'],DROP)
+        self.assertFalse((self.state/'pending.json').exists())
+        self.assertEqual(write.call_count,1)
+        self.calls.clear();self.run_migration();self.assertEqual(self.calls,[])
+    def test_no_native_service_commands(self):
+        self.run_migration()
+        for args,_ in self.calls:
+            self.assertNotIn('lnd.service',args);self.assertNotIn('bitcoin-core.service',args)
+    def test_validation_failure_does_not_stop_or_write(self):
+        self.fail=lambda a:'--check' in a
+        with self.assertRaises(RuntimeError):self.run_migration()
+        self.assertEqual(self.drop.read_text(),DROP)
+        self.assertFalse(self.state.exists())
+        self.assertFalse(any('stop' in a for a,_ in self.calls))
+    def test_apply_failure_restores_files_and_firewall(self):
+        self.fail=lambda a:'nft' in a and '-f' in a and '--check' not in a
+        with self.assertRaises(RuntimeError):self.run_migration()
+        self.assertEqual(self.drop.read_text(),DROP)
+        self.assertFalse((self.state/'pending.json').exists())
+        self.assertTrue(any(v=='delete table inet web_tunnel\n'+RULES for _,v in self.calls))
+    def test_crash_journal_recovers_and_retries(self):
+        self.state.mkdir(parents=True)
+        (self.state/'pending.json').write_text(json.dumps({'drop':DROP,'rules':RULES,'was_active':'active'}))
+        self.drop.write_text(m.plan(DROP,RULES)[0])
+        self.run_migration()
+        self.assertIn(':18081:80/tcp',self.drop.read_text())
+        self.assertFalse((self.state/'pending.json').exists())
+    def test_fresh_install_executes_no_commands(self):
+        self.drop.unlink();self.run_migration();self.assertEqual(self.calls,[])
+    def test_busy_replacement_port_does_not_mutate(self):
+        with patch.object(Path,'home',return_value=self.home),patch.object(m,'command',side_effect=self.command),patch.object(m.socket,'socket') as socket:
+            socket.return_value.__enter__.return_value.bind.side_effect=OSError('in use')
+            with self.assertRaises(OSError):m.main()
+        self.assertFalse(self.state.exists())
+        self.assertFalse(any('stop' in a for a,_ in self.calls))
+    def test_failed_rollback_keeps_recovery_journal(self):
+        with patch.object(Path,'home',return_value=self.home),patch.object(m,'command',side_effect=self.command),patch.object(m,'root_write',side_effect=RuntimeError('write failed')),patch.object(m.socket,'socket'):
+            with self.assertRaises(RuntimeError):m.main()
+        self.assertTrue((self.state/'pending.json').exists())
+        self.assertEqual(self.drop.read_text(),DROP)
+    def test_stopped_app_is_not_started(self):
+        original=self.command
+        def stopped(*args,input=None):
+            return 'inactive' if 'show' in args else original(*args,input=input)
+        with patch.object(Path,'home',return_value=self.home),patch.object(m,'command',side_effect=stopped),patch.object(m,'root_write'),patch.object(m.socket,'socket'):
+            m.main()
+        self.assertFalse(any('restart' in a for a,_ in self.calls))
+    def test_live_only_firewall_changes_are_not_discarded(self):
+        original=self.command
+        def different(*args,input=None):
+            result=original(*args,input=input)
+            return result+' table inet custom {}' if 'list' in args else result
+        with patch.object(Path,'home',return_value=self.home),patch.object(m,'command',side_effect=different),patch.object(m.socket,'socket'):
+            with self.assertRaises(ValueError):m.main()
+        self.assertEqual(self.drop.read_text(),DROP)
+
+if __name__=='__main__': unittest.main()
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Opt-in disposable rootless Angor gateway integration checks. No native app changes."""
+import subprocess,pathlib,json,urllib.request,urllib.error,time,tempfile,os,uuid,shlex
+import yaml
+if os.environ.get('ARCHY_ALLOW_DISPOSABLE_CONTAINERS') != '1':
+ raise SystemExit('Set ARCHY_ALLOW_DISPOSABLE_CONTAINERS=1 to run isolated test containers')
+manifest=yaml.safe_load((pathlib.Path(__file__).resolve().parents[2]/'apps/angor-indexer/manifest.yml').read_text())['app']
+health=manifest['health_check']
+health_url=health['endpoint'].rstrip('/')+health.get('path','/')
+run_id=uuid.uuid4().hex[:12]
+net='archy-angor-test-'+run_id;backend='angor-test-backend-'+run_id;gateway='angor-test-gateway-'+run_id
+def run(*a):
+ r=subprocess.run(a,capture_output=True,text=True)
+ if r.returncode:raise RuntimeError(r.stderr)
+ return r.stdout.strip()
+def req(path,data=None,method=None,headers={}):
+ r=urllib.request.Request('http://127.0.0.1:19098'+path,data=data,method=method,headers=headers)
+ try:
+  with urllib.request.urlopen(r,timeout=10) as f:return f.status,f.headers,f.read()
+ except urllib.error.HTTPError as e:return e.code,e.headers,e.read()
+script="""require('http').createServer((q,r)=>{let b='';q.on('data',x=>b+=x);q.on('end',()=>{r.setHeader('Access-Control-Allow-Origin','https://wrong.example');if(q.url==='/api/v1/blocks/tip/height'){r.end('900000');return}r.setHeader('Content-Type','application/json');r.end(JSON.stringify({url:q.url,method:q.method,body:b,cookie:q.headers.cookie||null,auth:q.headers.authorization||null}))})}).listen(8999,'0.0.0.0')"""
+def start_backend():run('podman','run','-d','--name',backend,'--network',net,'--network-alias','mempool-api','--cap-drop=all','--security-opt=no-new-privileges','docker.io/library/node:24-alpine','node','-e',script)
+def ready(seconds=40):
+ end=time.monotonic()+seconds
+ while time.monotonic()<end:
+  try:
+   if req('/health')[0]==200:return
+  except OSError:pass
+  time.sleep(1)
+ raise RuntimeError('Gateway readiness did not recover')
+assert subprocess.run(['podman','network','exists',net]).returncode==1
+run('podman','network','create',net)
+try:
+ start_backend()
+ run('podman','run','-d','--name',gateway,'--network',net,'--read-only','--cap-drop=all','--security-opt=no-new-privileges','--memory','128m','--health-cmd','wget -q -T 5 -O /dev/null '+shlex.quote(health_url),'--health-interval','5s','--health-retries','2','-p','127.0.0.1:19098:8080','source.archipelago-foundation.org/chaum/angor-indexer:1.0.1')
+ ready()
+ run('podman','healthcheck','run',gateway)
+ assert json.loads(run('podman','inspect',gateway))[0]['State']['Health']['Status']=='healthy'
+ print('PASS manifest health check inside actual image (including localhost address family)',flush=True)
+ for path in ['/api/v1/address/bc1fixture/txs?after_txid=abc','/api/v1/fees/recommended','/api/tx/fixture/hex']:
+  status,headers,body=req(path,headers={'Cookie':'node-secret=do-not-forward','Authorization':'Bearer do-not-forward'})
+  result=json.loads(body);assert status==200 and result['url']==(path if path.startswith('/api/v1/') else path.replace('/api/','/api/v1/',1)) and result['cookie'] is None and result['auth'] is None
+  assert headers.get_all('Access-Control-Allow-Origin')==['*']
+ assert req('/api/v1/tx',b'deadbeef')[0]==200
+ assert json.loads(req('/api/v1/tx',b'deadbeef')[2])['body']=='deadbeef'
+ assert req('/api/v1/fees/recommended',b'bad')[0]==403
+ assert req('/api/v1/tx',b'bad',method='DELETE')[0]==403
+ assert req('/api/v1/tx',method='OPTIONS')[0]==204
+ assert req('/api/v1/tx',b'x'*(4*1024*1024+1))[0]==413
+ assert req('/unknown')[0]==404
+ d=json.loads(run('podman','inspect',gateway))[0];assert d['Config']['User']=='101:101' and not d['BoundingCaps']
+ print('PASS API paths/query/body, transaction-only POST, method/size limits, CORS, credential stripping and unprivileged read-only image',flush=True)
+ run('podman','stop',backend)
+ status,headers,body=req('/health');assert status==503 and json.loads(body)['status']=='waiting'
+ run('podman','rm',backend);start_backend();ready()
+ print('PASS backend outage returns truthful 503; backend recreation recovers through runtime DNS without gateway restart',flush=True)
+except BaseException:
+ subprocess.run(['podman','logs','--tail','15',gateway],check=False)
+ raise
+finally:
+ for name in [gateway,backend]:subprocess.run(['podman','rm','-f','--time','3',name],stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+ subprocess.run(['podman','network','rm',net],stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Headless store apps must be discoverable without acquiring a UI launcher."""
+import importlib.util
+import pathlib
+import unittest
+import yaml
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+spec = importlib.util.spec_from_file_location('catalog_generator', ROOT / 'scripts/generate-app-catalog.py')
+generator = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(generator)
+
+class ServiceMetadata(unittest.TestCase):
+    def test_headless_services_have_mesh_ports_but_no_browser_launcher(self):
+        for name, port in [('angor-indexer', 8998), ('angor-relay', 8091)]:
+            app = yaml.safe_load((ROOT / 'apps' / name / 'manifest.yml').read_text())['app']
+            self.assertIsNone(generator.manifest_launch_port(app))
+            self.assertEqual(generator.manifest_service_ports(app), [port])
+            self.assertEqual(app['ports'][0]['bind'], '127.0.0.1')
+            self.assertEqual(app['security']['capabilities'], [])
+
+    def test_indexer_health_targets_ipv4_listener(self):
+        app = yaml.safe_load((ROOT / 'apps/angor-indexer/manifest.yml').read_text())['app']
+        self.assertEqual(app['health_check']['endpoint'], 'http://127.0.0.1:8080')
+        self.assertEqual(app['health_check']['path'], '/health')
+
+    def test_host_local_api_never_opens_mesh_port(self):
+        app = {'interfaces': {'main': {'type': 'api', 'port': 8999}},
+               'ports': [{'host': 8999, 'auth': 'local'}],
+               'health_check': {'type': 'http'}}
+        self.assertIsNone(generator.manifest_launch_port(app))
+        self.assertEqual(generator.manifest_service_ports(app), [])
+
+    def test_legacy_ui_fallback_retained(self):
+        self.assertEqual(generator.manifest_launch_port({'ports': [{'host': 8080}],
+            'health_check': {'type': 'http'}}), 8080)
+
+    def test_relay_storage_cannot_share_node_identity_or_database(self):
+        node = yaml.safe_load((ROOT / 'apps/strfry/manifest.yml').read_text())['app']
+        angor = yaml.safe_load((ROOT / 'apps/angor-relay/manifest.yml').read_text())['app']
+        node_paths = {v['source'] for v in node['volumes']}
+        self.assertTrue(node_paths.isdisjoint(v['source'] for v in angor['volumes']))
+        self.assertTrue(all(not f['overwrite'] for f in angor['files']))
+        self.assertEqual(angor['interfaces']['main']['type'], 'api')
+
+if __name__ == '__main__':
+    unittest.main()
@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Real nftables routing check. Run: sudo unshare --net python3 <this file>.
+Never runs in the host network namespace; creates no persistent namespaces.
+"""
+import importlib.util
+import os
+from pathlib import Path
+import socket
+import subprocess
+import threading
+
+assert os.geteuid() == 0
+assert os.readlink('/proc/self/ns/net') != os.readlink('/proc/1/ns/net'), 'requires isolated network namespace'
+repo=Path(__file__).resolve().parents[2]
+spec=importlib.util.spec_from_file_location('fixture',repo/'scripts/tests/test_repair_npm_tunnel.py')
+f=importlib.util.module_from_spec(spec);spec.loader.exec_module(f)
+def run(*args,input=None):
+    return subprocess.run(args,input=input,text=True,capture_output=True,check=True,timeout=10).stdout
+run('ip','link','set','lo','up')
+peer=subprocess.Popen(['unshare','--net','sleep','60'])
+try:
+    import time
+    for _ in range(100):
+        if os.readlink(f'/proc/{peer.pid}/ns/net')!=os.readlink('/proc/self/ns/net'): break
+        time.sleep(.02)
+    else: raise AssertionError('peer namespace did not start')
+    run('ip','link','add','wg-web','type','veth','peer','name','wgpeer')
+    run('ip','link','set','wgpeer','netns',str(peer.pid))
+    run('ip','addr','add','10.77.0.2/30','dev','wg-web')
+    run('ip','link','set','wg-web','up')
+    prefix=('nsenter','-t',str(peer.pid),'-n')
+    run(*prefix,'ip','addr','add','10.77.0.1/30','dev','wgpeer')
+    run(*prefix,'ip','link','set','wgpeer','up')
+    run(*prefix,'ip','link','set','lo','up')
+    listeners=[]
+    for address,reply in [(('10.77.0.2',18081),b'NPM'),(('0.0.0.0',18080),b'LND')]:
+        listener=socket.socket();listener.bind(address);listener.listen();listeners.append(listener)
+        def serve(sock=listener,data=reply):
+            connection,_=sock.accept()
+            with connection: connection.sendall(data)
+        threading.Thread(target=serve,daemon=True).start()
+    run('nft','-f','-',input=f.RULES)
+    _,rules,_=f.m.plan(f.DROP,f.RULES)
+    transaction='delete table inet web_tunnel\n'+rules
+    run('nft','--check','-f','-',input=transaction)
+    run('nft','-f','-',input=transaction)
+    result=run(*prefix,'python3','-c',"import socket; s=socket.create_connection(('10.77.0.2',18080),3); print(s.recv(10).decode())")
+    assert result.strip()=='NPM',result
+    with socket.create_connection(('127.0.0.1',18080),3) as connection:
+        assert connection.recv(10)==b'LND'
+    print('PASS: original peer HTTP port reaches NPM; local LND REST port remains separate')
+finally:
+    peer.terminate();peer.wait(timeout=5)
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+import importlib.util
+import io
+import json
+import pathlib
+import unittest
+import urllib.error
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+spec = importlib.util.spec_from_file_location('diagnostic', ROOT / 'scripts/check-portainer-git-source.py')
+m = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(m)
+
+
+class Response(io.BytesIO):
+    pass
+
+
+class FakeAPI:
+    def __init__(self, result=None, error=None):
+        self.result, self.error, self.request = result, error, None
+    def open(self, request, timeout):
+        self.request = request
+        if self.error:
+            raise self.error
+        return Response(json.dumps(self.result).encode())
+
+
+class Diagnostics(unittest.TestCase):
+    def test_server_context_credentials_not_in_url_and_tls_stays_enabled(self):
+        api = FakeAPI({'success': True})
+        result = m.check('http://localhost:9000', 'http://node:3001/user/repo',
+                         {'jwt': 'test-jwt', 'git': {'username': 'test-user', 'password': 'test-secret'}}, api)
+        self.assertTrue(result['success'])
+        self.assertEqual(api.request.full_url, 'http://localhost:9000/api/gitops/sources/test')
+        payload = json.loads(api.request.data)
+        self.assertFalse(payload['tlsSkipVerify'])
+        self.assertEqual(payload['authentication']['password'], 'test-secret')
+        self.assertNotIn('test-secret', json.dumps(result))
+
+    def test_failure_categories_from_source_api(self):
+        cases = [('dial tcp: connection refused', 'connection-refused'),
+                 ('lookup node: no such host', 'dns-failure'),
+                 ('context deadline exceeded', 'timeout'),
+                 ('unexpected content-type text/html', 'proxy-or-login-interception'),
+                 ('authentication required', 'repository-authentication'),
+                 ('x509: certificate signed by unknown authority', 'tls-failure'),
+                 ('repository not found', 'repository-not-found-or-private')]
+        for error, expected in cases:
+            with self.subTest(error=error):
+                result = m.check('http://localhost:9000', 'http://node/repo', {'jwt': 'test'}, FakeAPI({'success': False, 'error': error}))
+                self.assertEqual(result['category'], expected)
+                self.assertFalse(result['success'])
+
+    def test_portainer_auth_is_distinct_from_repository_auth(self):
+        api = FakeAPI(error=urllib.error.HTTPError('http://localhost', 401, 'Unauthorized', {}, None))
+        self.assertEqual(m.check('http://localhost', 'http://node/repo', {'jwt': 'bad'}, api)['category'], 'portainer-authentication')
+
+    def test_html_or_malformed_api_response_never_proves_git_success(self):
+        for value in ({'status': 1}, {'success': 'true'}, [], '<html>login</html>'):
+            self.assertFalse(m.check('http://localhost', 'http://node/repo', {'jwt': 'test'}, FakeAPI(value))['success'])
+
+    def test_credential_urls_rejected_before_request(self):
+        for value in ('http://user:secret@node/repo', 'http://node/repo?token=secret', 'file:///data/repo'):
+            with self.assertRaises(ValueError):
+                m.check('http://localhost', value, {'jwt': 'test'}, FakeAPI())
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -73,6 +73,7 @@ stage "git-diff-check"   git diff --check
 stage "cargo-fmt"        timeout 240 cargo fmt --manifest-path core/Cargo.toml --all --check
 stage "app-build-contexts" python3 tests/regression/app-build-contexts.py
 stage "manifest-shell"  python3 scripts/check-manifest-shell.py
+stage "npm-tunnel-migration" python3 -m unittest discover -s scripts/tests -p test_repair_npm_tunnel.py
 stage "doctor-ports" bash tests/regression/container-doctor-ports.sh
 stage "bitcoin-pruning" python3 tests/regression/bitcoin-prune-entrypoint.py
 stage "lnd-ui-readiness" node --test tests/regression/lnd-ui-readiness.cjs
Author	SHA1	Message	Date
archipelago	02b840f2d1	chore: prepare 1.8.22-alpha release candidate Demo images / Build & push demo images (push) Failing after 36s Details	2026-09-30 16:45:43 -04:00
archipelago	f992780957	fix: probe Angor IPv4 health endpoint inside the actual image	2026-09-30 16:40:16 -04:00
archipelago	c82c1eee98	fix: prevent NPM tunnel collisions and false app health restarts	2026-09-30 16:30:40 -04:00
archipelago	2992443d5d	docs: record verified NPM tunnel port conflict and node repair	2026-09-30 16:12:04 -04:00
archipelago	259c353147	Clear completed candidate deployment instructions	2026-09-30 13:46:50 -04:00
archipelago	1724ea05d1	Show readiness reason first and record live dashboard acceptance Demo images / Build & push demo images (push) Failing after 45s Details	2026-09-30 13:46:16 -04:00
archipelago	c1e20a71ae	Check companion dashboards and omit headless UI waiting messages Demo images / Build & push demo images (push) Failing after 37s Details	2026-09-30 13:28:37 -04:00
archipelago	bf56956790	Record UI acceptance and remaining normal-startup release gate	2026-09-30 12:57:35 -04:00
archipelago	2f1a3ade07	Promote runtime manifests before starting app reconciliation	2026-09-30 12:50:46 -04:00
archipelago	ef8254272c	Name waiting apps, align card actions, and update Angor icon Demo images / Build & push demo images (push) Failing after 39s Details	2026-09-30 12:43:53 -04:00
archipelago	d50be13232	Normalize Mempool frontend aliases in restored app inventory	2026-09-30 12:41:15 -04:00
archipelago	439b55a236	Use manifest names for new services and document release acceptance Demo images / Build & push demo images (push) Failing after 38s Details	2026-09-30 12:20:29 -04:00
archipelago	5ab65f7581	Preserve apostrophes in Quadlet commands and record funded acceptance	2026-09-30 12:08:35 -04:00
archipelago	169bf77de6	Add headless Angor services and shared-index install guard Demo images / Build & push demo images (push) Failing after 43s Details	2026-09-30 11:52:19 -04:00
archipelago	7c4169867c	docs: consolidate release scope and record migration recovery checks	2026-09-30 10:52:41 -04:00
archipelago	acf544500f	fix(apps): preserve state across runtime repairs and restore Gitea SSH	2026-09-30 10:46:38 -04:00
archipelago	7d767c8cb0	fix(catalog): gate network migration manifests on backup support	2026-09-30 10:08:56 -04:00
archipelago	eb3ccfa00b	Merge branch 'fix/gitea-portainer-20260930'	2026-09-30 09:57:49 -04:00
archipelago	eda28c4cd6	fix(portainer): repair same-node Git routing with recoverable network migration	2026-09-30 09:57:25 -04:00
archipelago	d69e845216	Merge remote-tracking branch 'origin/main' Demo images / Build & push demo images (push) Failing after 1m10s Details	2026-09-30 09:32:20 -04:00
chaum	b02ba4100d	Merge pull request 'fix(files): save purchased files atomically with rootless ownership' (#162 ) from fix/filebrowser-purchase-filing into main	2026-09-30 12:58:36 +00:00
chaum	3daea6623b	Merge pull request 'fix(ecash): prevent paid-download replay and read failures after charging' (#161 ) from fix/ecash-paid-download-v2-keyset into main	2026-09-30 12:58:33 +00:00
archipelago	0677924a64	Merge current main and make purchase filing atomic under concurrent writes	2026-09-30 07:26:51 -04:00
archipelago	971d477795	Merge current main and harden paid-download delivery	2026-09-30 07:25:47 -04:00
ssmithxandClaude Opus 5.5	33477f284b	fix(files): file purchased content into FileBrowser folders again Every paid download logged "filing into filebrowser/Music/... failed (non-fatal): Permission denied". The purchase played in-app but never appeared in Files. FileBrowser's folders belong to its rootless container range (host uid 100000, mode 755). This service is host uid 1000, outside that range, so it can read them but not create files in them. New container::filebrowser::save_new_file: - Writes directly when the folder allows it. - Otherwise writes through `podman unshare`, where that uid range is ours: to a temp file, then chowned to the folder's owner, set to 0644, and hard-linked into place. FileBrowser never sees a partial file and an existing file is never replaced. A missing folder is created and given its parent's owner. No sudo. - Keeps the "name (2).ext" de-duplication the RPC did inline. Checked the unshare script on amishparadise in a scratch folder owned like FileBrowser's: new folder + file OK, owner/mode right, no clobber, no temp file left, and the service can read the result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-29 22:36:31 +00:00
ssmithxandClaude Opus 5.5	03e38d1ca3	test: regression tests for the paid-download fixes - mint_client: a stub mint shows swap() sends the full v2 keyset id when given a cashuB short id, and leaves complete v1/v2 ids unchanged. - fips::dial: the single-delivery decisions are now small functions (fips_answer_is_final, fips_retryable). Tests cover them and, against a silent local peer, check that a single-delivery request isn't resent after a timeout while an ordinary one still is. - content_server: an unreadable paid file returns Unavailable before the payment gate runs, and a readable one still returns 402. Also covers ensure_readable's grant/reopen behaviour. The podman grant is replaced by a refusal under cfg(test) so results don't depend on the host. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-29 20:12:16 +00:00
ssmithxandClaude Opus 5.5	e5fc99d66c	fix(content): never charge for a file the seller can't serve or replay a spent token After the keyset-id fix, a Minibits paid download still failed and the buyer lost the sats. What happened, 2026-09-29, amishparadise: 1. The seller redeemed the token, then failed to read the file. It was a FileBrowser upload owned by the container subuid (100999) with mode 0640. The handler mapped that Err to 404. 2. The buyer's FIPS dial treats 404 as "fall back to Tor" and resent the request with the same, now spent, token. The seller answered 402, and the buyer showed "seller doesn't accept your Cashu mint". Fixes: - serve_content checks the file is readable before the paid gate. If it isn't, it grants read with `podman unshare chmod a+r`, which matches the other shared files. If that also fails it returns Unavailable (503) without taking payment. - The content handler returns 500 on internal errors and logs them, instead of a silent 404. - New PeerRequest::single_delivery(), used for the paid download: the FIPS answer is final, FIPS retries only when it never connected, and there's no Tor replay once the request may have been delivered. - The buyer shows the seller's error text for non-402 failures. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-29 18:42:20 +00:00
ssmithxandClaude Opus 5.5	8b74803290	fix(ecash): repair short v2 keyset ids on every swap, not just receive Paid cloud downloads paid with Minibits ecash were always rejected. The buyer sends a cashuB token, which carries NUT-02 v2 keyset ids in their 8-byte short form. Minibits rotated its active keyset to a v2 id, and the seller's verify_and_receive_payment called MintClient::swap directly, skipping the short->full id repair that only receive_token applied. The mint answered 422 ("ID length invalid"). The buyer then showed the misleading "seller doesn't accept your Cashu mint" hint. Move the repair into swap() so every caller is covered: payment verify, streaming gate, send change, and cross-mint swaps. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-09-29 15:47:23 +00:00