fix: a restore with pg_restore 17 into Postgres 16 isn't stopped by a setting the server lacks

pg_restore 17 opens with `SET transaction_timeout = 0`, which Postgres 16 refuses.
Under --exit-on-error that one harmless statement ended every restore: the
image ships pg_restore 17.11 and the bundled server is pg16, so a restore
from the bucket (and the local restore) could never have loaded a dump. The
backup round trip, now that CI has pg_dump, found it.

pg_restore now runs to the end and its errors are judged afterwards: the
known harmless one is ignored, and any other fails the restore with that
error's words rather than the "Command was:" line that followed it.

Also sorts an import the lint lane flagged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.env.example

@@ -56,9 +56,8 @@ SECRET_KEY=
 # LINE. Leaving it set disarms the protection permanently, on an instance that
 # by then has credentials worth protecting.
 #
-# BACK UP ./images/secrets/ ALONGSIDE YOUR DATABASE. The key is the only thing
-# that can read your stored credentials; a database restored without it needs
-# every credential re-entered by hand.
+# Backups leave the key and the stored logins out on purpose: after restoring
+# onto a new install, sign in to each account again.
 CURATOR_BOOTSTRAP_NEW_KEY=1
 
 

.forgejo/workflows/build.yml

@@ -202,7 +202,8 @@ env:
 # Requires repo secret RELEASE_TOKEN — a Forgejo PAT with scopes:
 #   - write:package, read:package  (for docker push to git.fabledsword.com)
 #   - write:release                (for ext-<version> release asset cache)
-#   - write:issue                  (for future issue-management automation)
+#   - write:issue                  (`unattended-failure` opens an issue)
+#   - write:repository             (`refresh-dev` dispatches this workflow)
 # The injected GITHUB_TOKEN cannot be used — it lacks write:package.
 
 jobs:
@@ -578,6 +579,9 @@ jobs:
           else
             pip install -r requirements.txt pytest pytest-asyncio
           fi
+          # The backup round trip runs the real pg_dump and pg_restore, from the
+          # same Debian client package the app image installs.
+          command -v pg_dump >/dev/null 2>&1 || { apt-get update -qq && apt-get install -y -qq postgresql-client; }
           # Relax durability on the throwaway CI Postgres so the per-test
           # TRUNCATE's commit-fsync — the integration teardown's dominant cost
           # (~1.5-2s/test, which collapsed the suite from ~13min to ~45s) — is
@@ -1446,8 +1450,11 @@ jobs:
           # `no-cache: true`, which is a much larger version of the same
           # churn #3265 is about.
           #
-          # Only on the schedule. An ordinary push wants the cached base.
-          pull: ${{ env.IS_REFRESH == 'true' }}
+          # Only on the refresh and on a forced build. An ordinary push wants
+          # the cached base. A forced build pulls because forcing is how the
+          # refresh rebuilds `:dev` (see `refresh-dev`), and a rebuild that
+          # keeps the old base layers would be the same image again.
+          pull: ${{ env.IS_REFRESH == 'true' || format('{0}', github.event.inputs.force_build) == 'true' }}
           # ONE tag, the channel's. Every other tag is written by the step
           # below, registry-side. buildx here pushes the first tag to the
           # registry and then re-pushes the rest through the DOCKER driver,
@@ -2202,6 +2209,121 @@ jobs:
             exit 1
           fi
           echo "promote: $MOVED tag(s) written"
+
+  # The refresh rebuilds `:dev` as well as `:latest`.
+  #
+  # The refresh run itself builds main and publishes `:latest`. `:dev` needs a
+  # build of dev's own source with FC_CHANNEL=dev baked in, so copying main's
+  # refreshed bytes onto `:dev` is not the same thing: the image would report
+  # itself as main, and the reuse check would then keep it that way. Instead
+  # this job dispatches an ordinary dev run with `force_build`. That run goes
+  # through the lanes, the smoke and `promote` like any push, and a forced
+  # build pulls fresh bases (see `pull:` in both build jobs).
+  #
+  # Without this, an artifact whose source is quiet on dev (the agent, most
+  # weeks) keeps the base layers of its last build indefinitely, because
+  # reuse skips its build on every push.
+  #
+  # The dispatched run shares this run's concurrency group (both are on the
+  # dev ref), so it queues until this run has finished. It runs whatever
+  # `promote` did: a failed `:latest` refresh is no reason to leave `:dev`
+  # stale, and `unattended-failure` reports the failure either way.
+  refresh-dev:
+    needs: [promote]
+    if: >-
+      !cancelled() && (github.event_name == 'schedule'
+      || format('{0}', github.event.inputs.refresh) == 'true')
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - name: Dispatch a forced dev build
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+        run: |
+          set -eu
+          CODE=$(curl -sS --max-time 30 -o response.txt -w '%{http_code}' -X POST \
+            -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+            -d '{"ref":"dev","inputs":{"force_build":"true"}}' \
+            "$API/actions/workflows/build.yml/dispatches")
+          echo "refresh-dev: dispatch answered HTTP $CODE"
+          case "$CODE" in
+            2??) echo "refresh-dev: a forced dev run is queued behind this one" ;;
+            *)
+              cat response.txt >&2
+              echo "refresh-dev: the dispatch was refused. A 403 means RELEASE_TOKEN" >&2
+              echo "refresh-dev: lacks write:repository (see the scope list at the top)." >&2
+              exit 1 ;;
+          esac
+
+  # A run nobody is watching reports its own failure.
+  #
+  # A push run is watched by whoever pushed it. The weekly refresh and the dev
+  # run it dispatches are not, and a red run on the Actions page alone goes
+  # unseen. So any failed run that is not a push or a pull request opens an
+  # issue, or comments on the one already open, naming the run and the jobs
+  # that failed. A manual dispatch that fails reports here too; closing the
+  # issue once it is dealt with is what keeps the next failure visible.
+  #
+  # The issue is written with RELEASE_TOKEN, so it is authored by the token's
+  # owner, and the forge does not notify people of their own actions. It
+  # shows in the repository's open issues rather than as an email.
+  unattended-failure:
+    needs: [lint, extension-version, backend-lint-and-test, frontend-build,
+            extension-test, integration, sign-extension, build-web, smoke-web,
+            build-agent, promote, refresh-dev]
+    if: >-
+      failure() && github.event_name != 'push'
+      && github.event_name != 'pull_request'
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - name: Open or update the failure issue
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          EVENT: ${{ github.event_name }}
+          REF: ${{ github.ref_name }}
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          python3 - <<'EOF'
+          import json, os, urllib.parse, urllib.request
+
+          TITLE = "CI: an unattended build.yml run failed"
+          api, token = os.environ["API"], os.environ["TOKEN"]
+
+          def call(method, path, body=None):
+              req = urllib.request.Request(
+                  api + path, method=method,
+                  data=json.dumps(body).encode() if body is not None else None,
+                  headers={"Authorization": f"token {token}",
+                           "Content-Type": "application/json"})
+              with urllib.request.urlopen(req, timeout=30) as resp:
+                  return json.load(resp)
+
+          needs = json.loads(os.environ["NEEDS"])
+          failed = sorted(j for j, v in needs.items() if v.get("result") == "failure")
+          text = (f"Run: {os.environ['RUN_URL']}\n"
+                  f"Trigger: `{os.environ['EVENT']}` on `{os.environ['REF']}`\n"
+                  f"Failed jobs: {', '.join(f'`{j}`' for j in failed) or '(none reported)'}\n")
+
+          q = urllib.parse.urlencode({"state": "open", "type": "issues", "q": TITLE})
+          existing = [i for i in call("GET", f"/issues?{q}") if i["title"] == TITLE]
+          if existing:
+              n = existing[0]["number"]
+              call("POST", f"/issues/{n}/comments", {"body": text})
+              print(f"unattended-failure: commented on open issue #{n}")
+          else:
+              body = ("A build.yml run that nobody watches failed. Read the run's "
+                      "failing job logs; close this issue once it is fixed, so the "
+                      "next failure opens a new one.\n\n" + text)
+              n = call("POST", "/issues", {"title": TITLE, "body": body})["number"]
+              print(f"unattended-failure: opened issue #{n}")
+          EOF
+
   build-agent:
     # THE GATE (2026-09-23). Every lane above must have PASSED before this job
     # exists at all — so a red suite does not produce an image, let alone push
@@ -2540,8 +2662,11 @@ jobs:
           # `no-cache: true`, which is a much larger version of the same
           # churn #3265 is about.
           #
-          # Only on the schedule. An ordinary push wants the cached base.
-          pull: ${{ env.IS_REFRESH == 'true' }}
+          # Only on the refresh and on a forced build. An ordinary push wants
+          # the cached base. A forced build pulls because forcing is how the
+          # refresh rebuilds `:dev` (see `refresh-dev`), and a rebuild that
+          # keeps the old base layers would be the same image again.
+          pull: ${{ env.IS_REFRESH == 'true' || format('{0}', github.event.inputs.force_build) == 'true' }}
           # ONE tag, the channel's. Every other tag is written by the step
           # below, registry-side. buildx here pushes the first tag to the
           # registry and then re-pushes the rest through the DOCKER driver,

README.md

@@ -114,9 +114,10 @@ that cannot decrypt anything, leaving an instance that looks healthy while every
 paywalled download fails. Making you say so once, on an empty install, is the
 price of that not happening silently later.
 
-**Which means: back up `./images/secrets/` alongside your database.** It is the
-only thing that can read your stored credentials. A database restored without it
-needs every credential entered again by hand.
+**Your account logins are sealed with that key, and no backup carries either.**
+FabledCurator's backups (below) leave the key and the logins out on purpose, so
+a stolen backup holds no way into your accounts. After a restore, sign in to
+each account again through the browser extension.
 
 A few other things are worth knowing about the first few minutes:
 
@@ -177,6 +178,38 @@ Run it for a burst of tagging, stop it to get your card back. It deploys from
 `agent/docker-compose.yml`, not the main stack — see
 [agent/README.md](agent/README.md).
 
+## Backing up and restoring
+
+Backups live under **Settings → Maintenance → Backups**. With nothing else set
+up, the database is dumped nightly into `./images/_backups`, which is on the
+same disk as what it protects.
+
+To keep a copy off the machine, set up an off-site destination on the same
+screen: any S3 bucket (Fabled Archives, MinIO, AWS) and a key that may add and
+read objects. Each night FabledCurator then sends the database as a dated dump
+under `database/`, and every image and attachment once, named by its
+fingerprint, under `media/`. It never deletes from the bucket; the bucket's own
+retention thins old dumps. The first copy of a large library takes hours; a
+restart along the way carries on where it stopped rather than starting over.
+
+To rebuild after losing the server, start a fresh install (first boot as
+above), enter the same destination, and under **Restore from the bucket** choose
+a dump. The database is replaced, then every file is fetched back to its place
+and checked against its fingerprint as it arrives; progress shows on the same
+screen. **Fetch missing files** does only the second half, for a library that
+lost files but kept its database.
+
+If the web page isn't reachable, the same restore runs from a shell:
+
+```bash
+docker compose exec web python -m backend.app.scripts.restore list
+docker compose exec web python -m backend.app.scripts.restore database --dump latest --yes
+```
+
+On an install with no destination saved yet, add `--endpoint`, `--bucket` and
+`--access-key`, and put the secret key in `FC_BACKUP_SECRET_KEY` (or type it at
+the prompt).
+
 ## Upgrading
 
 ```bash

alembic/versions/0117_external_link_started_at.py

@@ -0,0 +1,33 @@
+"""external_link.started_at: when a fetch claimed the link.
+
+A worker killed mid-fetch (the Celery hard limit, an OOM, a restart) never
+reaches the code that moves its link out of 'downloading'. The external-link
+sweep returns such a link to the retry path once it has been 'downloading'
+longer than the task's hard limit, which needs the claim time.
+
+A row in 'downloading' with no claim time is treated as stale: no worker
+survives the deploy that adds this column.
+
+Revision ID: 0117
+Revises: 0116
+Create Date: 2026-11-05
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0117"
+down_revision = "0116"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "external_link",
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("external_link", "started_at")

alembic/versions/0118_external_link_recoveries.py

@@ -0,0 +1,32 @@
+"""external_link.recoveries: how many times recovery has retried a dead link.
+
+The daily recovery gives a dead link one more attempt, spaced further apart
+each time, and leaves it dead once the count reaches its limit. A link that
+can never succeed is then downloaded a handful of times in total, not every
+day.
+
+Revision ID: 0118
+Revises: 0117
+Create Date: 2026-11-05
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0118"
+down_revision = "0117"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "external_link",
+        sa.Column(
+            "recoveries", sa.Integer(), nullable=False, server_default=sa.text("0")
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("external_link", "recoveries")

alembic/versions/0119_backup_s3_destination.py

@@ -0,0 +1,43 @@
+"""import_settings: the off-site backup destination (an S3 bucket).
+
+Address, bucket, access key and region are plain settings; the secret key is
+stored sealed with the credential key. All empty means no destination is set
+up, which is every existing install's state.
+
+Revision ID: 0119
+Revises: 0118
+Create Date: 2026-11-06
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0119"
+down_revision = "0118"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("import_settings", sa.Column("backup_s3_endpoint", sa.Text(), nullable=True))
+    op.add_column(
+        "import_settings", sa.Column("backup_s3_bucket", sa.String(255), nullable=True),
+    )
+    op.add_column("import_settings", sa.Column("backup_s3_access_key", sa.Text(), nullable=True))
+    op.add_column(
+        "import_settings", sa.Column("backup_s3_secret_sealed", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "import_settings",
+        sa.Column(
+            "backup_s3_region", sa.String(64), nullable=False, server_default="us-east-1",
+        ),
+    )
+
+
+def downgrade() -> None:
+    for column in (
+        "backup_s3_region", "backup_s3_secret_sealed", "backup_s3_access_key",
+        "backup_s3_bucket", "backup_s3_endpoint",
+    ):
+        op.drop_column("import_settings", column)

alembic/versions/0120_backup_upload_limit.py

@@ -0,0 +1,30 @@
+"""import_settings: a bandwidth limit for uploads to the off-site backup bucket.
+
+In megabits per second; 0 means no limit. Every install starts at 200 Mbit/s,
+which leaves room on a gigabit link for everything else the server does.
+
+Revision ID: 0120
+Revises: 0119
+Create Date: 2026-11-07
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0120"
+down_revision = "0119"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "import_settings",
+        sa.Column(
+            "backup_upload_limit_mbps", sa.Integer(), nullable=False, server_default="200",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("import_settings", "backup_upload_limit_mbps")

alembic/versions/0121_backup_blob.py

@@ -0,0 +1,46 @@
+"""backup_blob: which library files are already in the off-site bucket.
+
+One row per (destination, sha256) sent. The media backup's work list is every
+image and attachment sha with no row for the current destination, so a run is
+incremental and resumable by construction, and pointing backups at a new
+bucket starts that bucket's copy from the beginning.
+
+backup_run.last_progress_at is the heartbeat of a run that spans hours; the
+stall sweep measures a media run's silence from it, not from its start.
+
+Revision ID: 0121
+Revises: 0120
+Create Date: 2026-11-07
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0121"
+down_revision = "0120"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "backup_blob",
+        sa.Column("target", sa.Text(), nullable=False),
+        sa.Column("sha256", sa.String(64), nullable=False),
+        sa.Column("key", sa.Text(), nullable=False),
+        sa.Column("size_bytes", sa.BigInteger(), nullable=False),
+        sa.Column(
+            "uploaded_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("target", "sha256", name=op.f("pk_backup_blob")),
+    )
+    op.add_column(
+        "backup_run",
+        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("backup_run", "last_progress_at")
+    op.drop_table("backup_blob")

backend/app/api/admin.py

@@ -475,6 +475,21 @@ async def trigger_reclaim_attachments():
     return _queued(async_result)
 
 
+@admin_bp.route("/maintenance/import-unimported", methods=["POST"])
+async def trigger_import_unimported():
+    """Import files in the artists' folders that the library has no record of.
+    Body {"dry_run": bool}; dry_run (the DEFAULT) lists what was found, per
+    artist, and changes nothing. dry_run=false queues them as an import batch
+    that attaches each file where it lies. Returns the Celery task id — poll
+    /maintenance/task-result/<id> for the summary."""
+    from ..tasks.admin import import_unimported_files_task
+
+    body = await request.get_json(silent=True) or {}
+    dry_run = bool(body.get("dry_run", True))
+    async_result = import_unimported_files_task.delay(dry_run=dry_run)
+    return _queued(async_result)
+
+
 @admin_bp.route("/maintenance/repair-discord-downloads", methods=["POST"])
 async def trigger_repair_discord_downloads():
     """Clean re-download of the Discord files broken by the `None` naming

backend/app/api/system_backup.py

@@ -20,7 +20,7 @@ system_backup_bp = Blueprint(
     "system_backup", __name__, url_prefix="/api/system/backup",
 )
 
-_KINDS = frozenset({"db", "images"})
+_KINDS = frozenset({"db", "images", "media", "restore"})
 _TAG_MAX_LEN = 64
 _BACKUP_SETTINGS_FIELDS = (
     "backup_db_nightly_enabled",
@@ -49,6 +49,9 @@ def _row_to_dict(r: BackupRun) -> dict:
         "error": r.error,
         "restored_from_id": r.restored_from_id,
         "manifest": r.manifest or {},
+        # Where an off-site dump went ({endpoint, bucket, key}); None for a
+        # backup kept on this server.
+        "offsite": (r.manifest or {}).get("offsite"),
     }
 
 
@@ -107,6 +110,134 @@ async def trigger_images_backup():
     return jsonify({"status": "dispatched"}), 202
 
 
+@system_backup_bp.route("/media", methods=["POST"])
+async def trigger_media_backup():
+    """Send the images and attachments not yet in the off-site bucket. Refused
+    when no destination is set up; a run already going is left to finish."""
+    from ..services import backup_destination as dest
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        if not dest.describe(row)["configured"]:
+            return _bad("no_destination",
+                        detail="set up an off-site destination before sending files")
+    from ..tasks.backup import backup_media_task
+    backup_media_task.delay(triggered_by="manual")
+    return jsonify({"status": "dispatched"}), 202
+
+
+@system_backup_bp.route("/media", methods=["GET"])
+async def media_coverage():
+    """How much of the library is in the off-site bucket: files and bytes,
+    sent and total, each file counted once however many posts hold it."""
+    from ..services import backup_destination as dest
+    from ..services import backup_media
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        f = dest.fields_of(row)
+        configured = dest.describe(row)["configured"]
+        tid = backup_media.destination_id(f.endpoint, f.bucket) if configured else None
+        counts = await session.run_sync(lambda s: backup_media.coverage(s, tid))
+    return jsonify({"configured": configured, **counts})
+
+
+# ── Restoring from the off-site bucket ──────────────────────────────────────
+
+
+async def _saved_target():
+    """(target, None) for the saved destination, or (None, error response)."""
+    from ..services import backup_destination as dest
+    from ..services.backup_s3 import S3Error
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        try:
+            target = dest.saved_target(row)
+        except S3Error as exc:
+            return None, _bad("destination_unreadable", detail=str(exc))
+    if target is None:
+        return None, _bad("no_destination",
+                          detail="set up an off-site destination before restoring from it")
+    return target, None
+
+
+async def _busy_reason() -> str | None:
+    from ..tasks.backup import backup_busy
+
+    async with get_session() as session:
+        return await session.run_sync(backup_busy)
+
+
+def restore_token(ts: str) -> str:
+    """What the person types to confirm replacing the database with the dump
+    taken at `ts`."""
+    return f"restore-offsite-{ts}"
+
+
+@system_backup_bp.route("/offsite/dumps", methods=["GET"])
+async def list_offsite_dumps():
+    """The database dumps in the off-site bucket, newest first, each with
+    the confirmation a restore of it asks for."""
+    import asyncio
+
+    from ..services import backup_restore
+    from ..services.backup_s3 import S3Error
+
+    target, err = await _saved_target()
+    if err:
+        return err
+    try:
+        dumps = await asyncio.to_thread(backup_restore.list_dumps, target)
+    except S3Error as exc:
+        return _bad("destination_unreachable", detail=str(exc), status=502)
+    return jsonify({"dumps": [
+        {"key": d.key, "ts": d.ts, "size_bytes": d.size_bytes, "confirm": restore_token(d.ts)}
+        for d in dumps
+    ]})
+
+
+@system_backup_bp.route("/offsite/restore", methods=["POST"])
+async def restore_from_offsite():
+    """Replace this install's database with a dump from the bucket, then
+    fetch the library's files back. Body: {key, confirm}, where confirm is
+    the dump's token from /offsite/dumps. Refused while a backup or another
+    restore is going."""
+    body = await request.get_json(silent=True) or {}
+    key = body.get("key")
+    if not isinstance(key, str) or not key.startswith("database/"):
+        return _bad("invalid_key", detail="key must be a dump's key from /offsite/dumps")
+    ts = key.removeprefix("database/fabledcurator-").removesuffix(".dump")
+    expected = restore_token(ts)
+    if body.get("confirm") != expected:
+        return _bad("confirm_mismatch", detail=f"confirm must equal {expected!r}",
+                    expected=expected)
+    _, err = await _saved_target()
+    if err:
+        return err
+    busy = await _busy_reason()
+    if busy:
+        return _bad("busy", detail=f"{busy}; try again when it has finished", status=409)
+    from ..tasks.backup import restore_offsite_task
+    restore_offsite_task.delay(dump_key=key)
+    return jsonify({"status": "dispatched"}), 202
+
+
+@system_backup_bp.route("/offsite/fetch-files", methods=["POST"])
+async def fetch_missing_files():
+    """Fetch every library file that is missing from disk back from the
+    bucket, leaving the database as it is."""
+    _, err = await _saved_target()
+    if err:
+        return err
+    busy = await _busy_reason()
+    if busy:
+        return _bad("busy", detail=f"{busy}; try again when it has finished", status=409)
+    from ..tasks.backup import restore_offsite_task
+    restore_offsite_task.delay(files_only=True)
+    return jsonify({"status": "dispatched"}), 202
+
+
 @system_backup_bp.route("/runs", methods=["GET"])
 async def list_runs():
     try:
@@ -180,6 +311,12 @@ async def trigger_restore(run_id: int):
                 "not_restorable",
                 detail=f"source backup status={row.status!r}; only 'ok' rows are restorable",
             )
+        if (row.manifest or {}).get("offsite"):
+            return _bad(
+                "not_restorable",
+                detail=("this dump is kept in the off-site bucket, not on this server, "
+                        "so it can't be restored from here"),
+            )
         expected = f"restore-{row.kind}-{row.id}"
         if supplied != expected:
             return _bad(
@@ -236,6 +373,118 @@ async def get_settings():
     })
 
 
+@system_backup_bp.route("/destination", methods=["GET"])
+async def get_destination():
+    """The off-site destination as the settings screen shows it. The secret
+    key is never returned, only whether one is saved."""
+    from ..services import backup_destination as dest
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        return jsonify(dest.describe(row))
+
+
+@system_backup_bp.route("/destination", methods=["PATCH"])
+async def patch_destination():
+    """Save the destination. Body {endpoint, bucket, access_key, region,
+    secret_key, upload_limit_mbps}; an empty field clears it, and a missing
+    upload_limit_mbps keeps the saved limit. A missing or empty secret_key
+    keeps the saved one, so the screen can save the other fields without the
+    secret being typed again."""
+    from ..services import backup_destination as dest
+
+    body = await request.get_json(silent=True)
+    if not isinstance(body, dict):
+        return _bad("invalid_body", detail="body must be a JSON object")
+    fields, why = dest.clean_fields(body)
+    if fields is None:
+        return _bad("invalid_destination", detail=why)
+    secret = body.get("secret_key")
+    if secret is not None and not isinstance(secret, str):
+        return _bad("invalid_destination", detail="secret_key must be text")
+    limit = body.get("upload_limit_mbps")
+    if limit is not None and (
+        not isinstance(limit, int) or isinstance(limit, bool) or not 0 <= limit <= 100_000
+    ):
+        return _bad("invalid_destination",
+                    detail="upload_limit_mbps must be a whole number from 0 (no limit) up")
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        if limit is not None:
+            row.backup_upload_limit_mbps = limit
+        row.backup_s3_endpoint = fields.endpoint
+        row.backup_s3_bucket = fields.bucket
+        row.backup_s3_access_key = fields.access_key
+        row.backup_s3_region = fields.region
+        if secret and secret.strip():
+            row.backup_s3_secret_sealed = dest.seal(secret.strip())
+        await session.commit()
+        return jsonify(dest.describe(row))
+
+
+@system_backup_bp.route("/destination", methods=["DELETE"])
+async def delete_destination():
+    """Forget the destination, secret included. What was already sent stays in
+    the bucket: FabledCurator never deletes there."""
+    from ..services import backup_destination as dest
+
+    async with get_session() as session:
+        row = await ImportSettings.load(session)
+        row.backup_s3_endpoint = None
+        row.backup_s3_bucket = None
+        row.backup_s3_access_key = None
+        row.backup_s3_secret_sealed = None
+        row.backup_s3_region = dest.DEFAULT_REGION
+        await session.commit()
+        return jsonify(dest.describe(row))
+
+
+@system_backup_bp.route("/destination/test", methods=["POST"])
+async def try_destination():
+    """Reach the bucket with the fields in the body (the form as typed, saved
+    or not); a missing secret_key uses the saved one. Lists the bucket and
+    writes nothing. Answers {ok, message} either way: a destination that
+    can't be reached is a result to show, not an API error."""
+    import asyncio
+
+    from ..services import backup_destination as dest
+    from ..services.backup_s3 import S3Error
+    from ..services.credential_crypto import InvalidCredentialBlob
+
+    body = await request.get_json(silent=True) or {}
+    if not isinstance(body, dict):
+        return _bad("invalid_body", detail="body must be a JSON object")
+    fields, why = dest.clean_fields(body)
+    if fields is None:
+        return jsonify({"ok": False, "message": f"Not tested: {why}."})
+    secret = body.get("secret_key")
+    secret = secret.strip() if isinstance(secret, str) else ""
+    if not secret:
+        async with get_session() as session:
+            row = await ImportSettings.load(session)
+            sealed = row.backup_s3_secret_sealed
+        if sealed:
+            try:
+                secret = dest.unseal(sealed)
+            except InvalidCredentialBlob:
+                return jsonify({"ok": False, "message": (
+                    "Not tested: the saved secret key can't be opened on this server. "
+                    "Enter the secret key again."
+                )})
+    target = dest.target_for(fields, secret or None)
+    if target is None:
+        missing = [name for name, v in (
+            ("address", fields.endpoint), ("bucket", fields.bucket),
+            ("access key", fields.access_key), ("secret key", secret),
+        ) if not v]
+        return jsonify({"ok": False, "message": f"Not tested: fill in the {', '.join(missing)}."})
+    try:
+        return jsonify(await asyncio.to_thread(dest.check_target, target))
+    except S3Error as exc:
+        return jsonify({"ok": False, "message": str(exc)})
+
+
 @system_backup_bp.route("/settings", methods=["PATCH"])
 async def patch_settings():
     body = await request.get_json(silent=True)

backend/app/celery_app.py

@@ -302,6 +302,10 @@ def make_celery() -> Celery:
                 "task": "backend.app.tasks.backup.prune_backups",
                 "schedule": 86400.0,  # daily
             },
+            "reconcile-media-backup": {
+                "task": "backend.app.tasks.backup.reconcile_media_backup",
+                "schedule": 604800.0,  # weekly: list the bucket, re-send what's missing
+            },
             # Audit 2026-06-02 — three new per-entity recovery sweeps.
             # Each runs every 5 min like the other recover_stalled_*
             # sweeps; each is a no-op when nothing is stuck.

backend/app/celery_signals.py

@@ -232,17 +232,38 @@ def _consumed_queues(consumer) -> set[str]:
 
 @worker_ready.connect
 def _on_worker_ready(sender=None, **_):
-    """The download lane clears what its previous process left behind (#4433).
+    """A lane picks up what its previous process left behind. Only the lane
+    that runs the work does it; the other lanes booting beside it must not,
+    or a lane restarting on its own would disturb work still running.
+    Best-effort: a failure is logged and the worker still starts."""
+    queues = _consumed_queues(sender)
+    if "download" in queues:
+        _clear_download_leftovers()
+    if "maintenance_long" in queues:
+        _resume_offsite_runs()
+
+
+def _resume_offsite_runs() -> None:
+    """The long-maintenance lane carries on an off-site backup or restore that
+    a restart cut off mid-chunk. With nothing queuing its next chunk, the run
+    would read "running" for hours, and block every new run, until the stall
+    sweep ended it."""
+    try:
+        from .tasks.backup import resume_offsite_runs
+
+        resume_offsite_runs()
+    except Exception:  # noqa: BLE001 — never block the worker from starting
+        log.exception("long-maintenance lane boot: resuming off-site runs failed")
+
+
+def _clear_download_leftovers() -> None:
+    """The download lane clears what its previous process left behind.
 
     A restart SIGKILLs any walk that outlives the stop grace, so its event is
     never finalized and its platform lock is never released. Both used to wait
     out timers — a 30-min stall sweep that then blamed the source, and a 27-min
-    lock TTL that stalled every other source on the platform. Only the process
-    consuming `download` does this; the other lanes booting beside it must not.
-    Best-effort: a failure here is logged and the worker still starts.
+    lock TTL that stalled every other source on the platform.
     """
-    if "download" not in _consumed_queues(sender):
-        return
     booted_at = datetime.now(UTC)
     try:
         from .services.download_recovery import interrupt_orphaned_download_events

backend/app/models/__init__.py

@@ -4,6 +4,7 @@ from .app_setting import AppSetting
 from .artist import Artist
 from .artist_membership_suggestion import ArtistMembershipSuggestion
 from .artist_visit import ArtistVisit
+from .backup_blob import BackupBlob
 from .backup_run import BackupRun
 from .base import Base
 from .character_prototype import CcipPrototypeState, CharacterPrototype
@@ -55,6 +56,7 @@ __all__ = [
     "Artist",
     "ArtistMembershipSuggestion",
     "ArtistVisit",
+    "BackupBlob",
     "BackupRun",
     "Source",
     "Credential",

backend/app/models/backup_blob.py

@@ -0,0 +1,26 @@
+"""backup_blob: a library file already sent to the off-site bucket.
+
+One row per (destination, sha256). `target` names the destination as
+"<endpoint>/<bucket>", so pointing backups at another bucket leaves these rows
+inert and that bucket's copy starts from the beginning. `key` is where the
+file sits in the bucket (`media/ab/cd/<sha256><ext>`).
+"""
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class BackupBlob(Base):
+    __tablename__ = "backup_blob"
+
+    target: Mapped[str] = mapped_column(Text, primary_key=True)
+    sha256: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(Text, nullable=False)
+    size_bytes: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    uploaded_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(),
+    )

backend/app/models/backup_run.py

@@ -1,6 +1,7 @@
 """FC-3h: backup_run — operator-facing artifact record for a backup run.
 
-One row per backup attempt (kind='db' or 'images'). Lifecycle
+One row per backup attempt (kind='db', 'images', or 'media' for the off-site
+upload of images and attachments, which spans many task chunks). Lifecycle
 tracking (started_at/finished_at/duration_ms/exception text) lives
 in task_run from FC-3i — this row records artifact metadata: file
 paths, sizes, tag (retention protection), and restore lineage via
@@ -62,6 +63,11 @@ class BackupRun(Base):
     )
     # Self-referential FK, unindexed until 0089 (#3300): SET NULL has to find
     # the rows pointing at a deleted run before it can null them.
+    # Heartbeat of a run that spans hours (the media backup): set as it makes
+    # progress, and what the stall sweep measures its silence from.
+    last_progress_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True,
+    )
     restored_from_id: Mapped[int | None] = mapped_column(
         ForeignKey("backup_run.id", ondelete="SET NULL"),
         nullable=True, index=True,

backend/app/models/external_link.py

@@ -80,12 +80,23 @@ class ExternalLink(Base):
         Integer, nullable=False, server_default=text("0")
     )
     last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Times the daily recovery has given this link another attempt after it
+    # went dead. Recovery stops at a limit, so a link that can never succeed
+    # isn't downloaded forever.
+    recoveries: Mapped[int] = mapped_column(
+        Integer, nullable=False, server_default=text("0")
+    )
     attachment_id: Mapped[int | None] = mapped_column(
         ForeignKey("post_attachment.id", ondelete="SET NULL"), nullable=True
     )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now()
     )
+    # When the current fetch claimed the link ('downloading'). The sweep uses it
+    # to recover a link whose worker died mid-fetch.
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
     completed_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )

backend/app/models/import_settings.py

@@ -9,6 +9,7 @@ from sqlalchemy import (
     CheckConstraint,
     Float,
     Integer,
+    String,
     Text,
     select,
     text,
@@ -100,6 +101,20 @@ class ImportSettings(Base):
         Integer, nullable=False, default=3,
         server_default="3",
     )
+    # Off-site backup destination: an S3 bucket (services/backup_destination).
+    # The secret key is stored sealed with the credential key, never in clear.
+    backup_s3_endpoint: Mapped[str | None] = mapped_column(Text, nullable=True)
+    backup_s3_bucket: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    backup_s3_access_key: Mapped[str | None] = mapped_column(Text, nullable=True)
+    backup_s3_secret_sealed: Mapped[str | None] = mapped_column(Text, nullable=True)
+    backup_s3_region: Mapped[str] = mapped_column(
+        String(64), nullable=False, default="us-east-1",
+        server_default="us-east-1",
+    )
+    # Upload bandwidth to that bucket, in megabits per second; 0 = no limit.
+    backup_upload_limit_mbps: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=200, server_default="200",
+    )
 
     # FC-6.3 series continuation matcher. enabled gates the rescan; threshold is
     # the weighted-score cut-off (0..1) above which a pending suggestion is made.

backend/app/scripts/restore.py

@@ -0,0 +1,119 @@
+"""Restore FabledCurator from its off-site bucket, from a shell in the
+container. The Backup screen does the same; this is for an install whose page
+you can't reach yet, or for scripting a rebuild.
+
+    python -m backend.app.scripts.restore list
+    python -m backend.app.scripts.restore database --dump latest --yes
+    python -m backend.app.scripts.restore files
+
+On a brand-new install with no destination saved, name it on the command
+line: --endpoint, --bucket and --access-key, with the secret key in the
+FC_BACKUP_SECRET_KEY environment variable (or typed at the prompt). It is
+checked by listing the bucket, then saved as this install's destination,
+sealed, exactly as the settings page saves it.
+
+`database` replaces the database with the chosen dump here, then hands the
+files to the worker; their progress shows on the Backup screen. `files`
+fetches only what is missing from disk and leaves the database alone.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import sys
+
+from ..models import ImportSettings
+from ..services import backup_destination, backup_restore
+from ..services.backup_s3 import S3Error
+from ..tasks._sync_engine import sync_session_factory
+
+
+def _human(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1000 or unit == "TB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1000
+    return str(n)
+
+
+def _destination(args) -> object:
+    """The target to restore from: the one named on the command line, saved
+    first, or the one already saved."""
+    session_factory = sync_session_factory()
+    if args.endpoint or args.bucket or args.access_key:
+        fields, why = backup_destination.clean_fields({
+            "endpoint": args.endpoint, "bucket": args.bucket,
+            "access_key": args.access_key, "region": args.region,
+        })
+        if fields is None:
+            raise SystemExit(f"Destination not usable: {why}.")
+        secret = os.environ.get("FC_BACKUP_SECRET_KEY") or getpass.getpass("Secret key: ")
+        target = backup_destination.target_for(fields, secret.strip() or None)
+        if target is None:
+            raise SystemExit("Name the address, bucket, access key and secret key.")
+        check = backup_destination.check_target(target)
+        print(check["message"])
+        if not check["ok"]:
+            raise SystemExit(1)
+        with session_factory() as session:
+            settings = ImportSettings.load_sync(session)
+            limit = settings.backup_upload_limit_mbps
+            backup_restore.keep_destination(session, target, limit)
+        print("Saved as this install's off-site destination.")
+        return target
+    with session_factory() as session:
+        target = backup_destination.saved_target(ImportSettings.load_sync(session))
+    if target is None:
+        raise SystemExit("No off-site destination is saved; name one with "
+                         "--endpoint, --bucket and --access-key.")
+    return target
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m backend.app.scripts.restore",
+                                     description=__doc__.split("\n\n")[0])
+    parser.add_argument("action", choices=("list", "database", "files"))
+    parser.add_argument("--dump", default="latest",
+                        help="the dump's key from `list`, or latest (the default)")
+    parser.add_argument("--yes", action="store_true",
+                        help="confirm replacing this install's database")
+    parser.add_argument("--endpoint")
+    parser.add_argument("--bucket")
+    parser.add_argument("--access-key")
+    parser.add_argument("--region", default=None)
+    args = parser.parse_args(argv)
+
+    try:
+        target = _destination(args)
+        if args.action == "list":
+            for d in backup_restore.list_dumps(target):
+                print(f"{d.key}  {_human(d.size_bytes)}")
+            return 0
+
+        from ..tasks.backup import restore_offsite_task
+        if args.action == "files":
+            restore_offsite_task.delay(files_only=True)
+            print("Queued: the worker fetches every missing file; watch the Backup screen.")
+            return 0
+
+        dump = backup_restore.find_dump(target, args.dump)
+        if not args.yes:
+            print(f"This replaces this install's database with {dump.key} "
+                  f"({_human(dump.size_bytes)}). Run again with --yes to go ahead.")
+            return 2
+        print(f"Restoring {dump.key}; this takes a while for a large library…")
+        result = restore_offsite_task(dump_key=dump.key)
+        if result.get("skipped"):
+            print(f"Not started: {result['skipped']}.")
+            return 1
+        print("The database is restored. The worker is fetching the library's files; "
+              "watch the Backup screen.")
+        return 0
+    except S3Error as exc:
+        print(f"Couldn't restore: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

backend/app/services/backup_destination.py

@@ -0,0 +1,138 @@
+"""The off-site backup destination: an S3 bucket (Fabled Archives, or any S3
+service) that the database dumps and the media blobs are sent to.
+
+The address, bucket, access key and region are plain settings. The secret key
+is sealed at rest with the credential key (`/images/secrets`), the same key
+that seals account logins, and no API ever returns it: the settings answer
+only whether one is set. Because the credential key is kept out of every
+backup, a database dump carries the secret only as ciphertext nobody can open
+without the original server.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from .backup_s3 import S3Error, S3Target, list_objects
+from .credential_crypto import CredentialCrypto, InvalidCredentialBlob
+
+KEY_PATH = Path("/images/secrets/credential_key.b64")
+DEFAULT_REGION = "us-east-1"
+_TEST_LISTING = 5
+
+
+def _crypto() -> CredentialCrypto:
+    return CredentialCrypto(KEY_PATH)
+
+
+def seal(secret: str) -> str:
+    return _crypto().encrypt(secret).decode("ascii")
+
+
+def unseal(sealed: str) -> str:
+    return _crypto().decrypt(sealed.encode("ascii"))
+
+
+@dataclass(frozen=True)
+class DestinationFields:
+    endpoint: str | None
+    bucket: str | None
+    access_key: str | None
+    region: str
+
+
+def clean_fields(body: dict) -> tuple[DestinationFields | None, str | None]:
+    """The destination fields from a request body, trimmed, with empty ones as
+    None; or (None, why) when the address can't be an S3 endpoint."""
+    def text(name: str) -> str | None:
+        v = body.get(name)
+        if v is None:
+            return None
+        if not isinstance(v, str):
+            raise TypeError(name)
+        return v.strip() or None
+
+    try:
+        endpoint = text("endpoint")
+        bucket = text("bucket")
+        access_key = text("access_key")
+        region = text("region") or DEFAULT_REGION
+    except TypeError as exc:
+        return None, f"{exc.args[0]} must be text"
+    if endpoint is not None:
+        u = urlsplit(endpoint)
+        if u.scheme not in ("http", "https") or not u.hostname:
+            return None, ("the address must start with http:// or https:// and name "
+                          "a host, e.g. http://archives.example:8081")
+        if u.query or u.fragment:
+            return None, "the address can't carry a query or a fragment"
+        endpoint = endpoint.rstrip("/")
+    if bucket is not None and "/" in bucket:
+        return None, "the bucket is a name, not a path: put any path in the address"
+    return DestinationFields(endpoint, bucket, access_key, region), None
+
+
+def target_for(fields: DestinationFields, secret: str | None) -> S3Target | None:
+    """The S3 target, or None while any part of it is missing."""
+    if not (fields.endpoint and fields.bucket and fields.access_key and secret):
+        return None
+    return S3Target(fields.endpoint, fields.bucket, fields.access_key, secret,
+                    region=fields.region)
+
+
+def saved_target(settings) -> S3Target | None:
+    """The destination saved in ImportSettings, or None when none is set up.
+    Raises S3Error when the secret can't be opened (the credential key
+    changed since it was saved)."""
+    sealed = settings.backup_s3_secret_sealed
+    if not sealed:
+        return None
+    try:
+        secret = unseal(sealed)
+    except InvalidCredentialBlob:
+        raise S3Error(
+            "The saved secret key can't be opened on this server (the credential "
+            "key changed since it was saved). Enter the secret key again."
+        ) from None
+    return target_for(fields_of(settings), secret)
+
+
+def fields_of(settings) -> DestinationFields:
+    return DestinationFields(
+        settings.backup_s3_endpoint, settings.backup_s3_bucket,
+        settings.backup_s3_access_key, settings.backup_s3_region or DEFAULT_REGION,
+    )
+
+
+def describe(settings) -> dict:
+    """The destination as the settings screen shows it: never the secret."""
+    f = fields_of(settings)
+    return {
+        "endpoint": f.endpoint or "",
+        "bucket": f.bucket or "",
+        "access_key": f.access_key or "",
+        "region": f.region,
+        "secret_set": bool(settings.backup_s3_secret_sealed),
+        "upload_limit_mbps": settings.backup_upload_limit_mbps,
+        "configured": bool(
+            f.endpoint and f.bucket and f.access_key and settings.backup_s3_secret_sealed
+        ),
+    }
+
+
+def check_target(target: S3Target) -> dict:
+    """Reach the bucket by listing it. A listing proves the address, the
+    bucket and both keys at once, and writes nothing, because an Archives key
+    is allowed to add objects but a test object could never be removed."""
+    try:
+        page = list_objects(target, limit=_TEST_LISTING)
+    except S3Error as exc:
+        return {"ok": False, "message": str(exc)}
+    if not page.objects:
+        said = f"Reached {target.bucket} at {target.endpoint}. The bucket is empty."
+    else:
+        more = "+" if page.next_token else ""
+        said = (f"Reached {target.bucket} at {target.endpoint}. It holds "
+                f"{len(page.objects)}{more} object(s), e.g. {page.objects[0].key}.")
+    return {"ok": True, "message": said}

backend/app/services/backup_media.py

@@ -0,0 +1,202 @@
+"""The off-site copy of the library's files: every image and attachment, sent
+once each to the backup bucket as a content-addressed object.
+
+Layout in the bucket, beside the database dumps under `database/`:
+
+    media/ab/cd/<sha256><ext>
+
+`ab` and `cd` are the first four hex digits of the file's sha256, which keeps
+any one prefix small, and the extension keeps the files readable in the bucket
+without FabledCurator. The sha256 is the one recorded at import, so a file
+uploads exactly once however many rows or posts point at it, and a run is
+incremental: its work list is every sha with no `backup_blob` row for the
+current destination. A file removed from the library stays in the bucket until
+the bucket's own retention removes it; FabledCurator never deletes there.
+
+The bucket checks every object against that recorded sha256, so a file whose
+bytes changed on disk since import is refused and reported, never stored under
+the wrong name.
+"""
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import delete, select, text
+from sqlalchemy.dialects.postgresql import insert
+
+from ..models import BackupBlob
+from .backup_s3 import (
+    Pacer,
+    S3Error,
+    S3Target,
+    list_objects,
+    object_present,
+    put_file,
+    put_file_in_parts,
+)
+
+PREFIX = "media/"
+# Files above this size go in parts (S3 refuses a single PUT over 5 GiB, and a
+# part that fails is resent alone instead of the whole file).
+MULTIPART_OVER = 1 << 30
+# The bucket is listed this many keys at a time during a reconcile, with a
+# short rest between pages.
+LIST_PAGE = 1000
+LIST_REST_SECONDS = 0.2
+_EXT = re.compile(r"^\.[a-z0-9]{1,10}$")
+
+
+@dataclass(frozen=True)
+class Blob:
+    sha256: str
+    path: str
+    size_bytes: int
+    mime: str | None
+
+
+def destination_id(endpoint: str, bucket: str) -> str:
+    """How backup_blob names a destination: one copy per endpoint and bucket."""
+    return f"{endpoint.rstrip('/')}/{bucket}"
+
+
+def target_id(target: S3Target) -> str:
+    return destination_id(target.endpoint, target.bucket)
+
+
+def blob_key(sha256: str, path: str) -> str:
+    """The bucket key for a file: `media/ab/cd/<sha256><ext>`. An extension
+    that isn't short and plain is left off, so a key is always safe."""
+    ext = Path(path).suffix.lower()
+    return f"{PREFIX}{sha256[:2]}/{sha256[2:4]}/{sha256}{ext if _EXT.match(ext) else ''}"
+
+
+# Every library file once per sha256: images and attachments together. An
+# attachment's sha can repeat across posts, and an image extracted from an
+# archive is its own file with its own sha.
+_LIBRARY = """
+    SELECT sha256, path, size_bytes, mime FROM image_record
+    UNION ALL
+    SELECT sha256, path, size_bytes, mime FROM post_attachment
+"""
+
+
+def pending(session, tid: str, *, after: str = "", limit: int = 500) -> list[Blob]:
+    """The next `limit` files not yet in the bucket, in sha order after
+    `after`, so a run walks the library once even when some files fail."""
+    rows = session.execute(text(f"""
+        SELECT DISTINCT ON (lib.sha256) lib.sha256, lib.path, lib.size_bytes, lib.mime
+        FROM ({_LIBRARY}) AS lib
+        WHERE lib.sha256 > :after
+          AND NOT EXISTS (
+              SELECT 1 FROM backup_blob b WHERE b.target = :tid AND b.sha256 = lib.sha256
+          )
+        ORDER BY lib.sha256, lib.path
+        LIMIT :limit
+    """), {"after": after, "tid": tid, "limit": limit}).all()
+    return [Blob(r.sha256, r.path, r.size_bytes, r.mime) for r in rows]
+
+
+def coverage(session, tid: str | None) -> dict:
+    """How much of the library is in the bucket: files and bytes, sent and
+    total, each sha counted once."""
+    row = session.execute(text(f"""
+        WITH lib AS (
+            SELECT DISTINCT ON (sha256) sha256, size_bytes FROM ({_LIBRARY}) AS u
+            ORDER BY sha256
+        )
+        SELECT count(*) AS files_total,
+               coalesce(sum(lib.size_bytes), 0) AS bytes_total,
+               count(b.sha256) AS files_sent,
+               coalesce(sum(lib.size_bytes) FILTER (WHERE b.sha256 IS NOT NULL), 0)
+                   AS bytes_sent
+        FROM lib
+        LEFT JOIN backup_blob b ON b.sha256 = lib.sha256 AND b.target = :tid
+    """), {"tid": tid or ""}).one()
+    return {
+        "files_total": row.files_total, "bytes_total": int(row.bytes_total),
+        "files_sent": row.files_sent, "bytes_sent": int(row.bytes_sent),
+    }
+
+
+def send(target: S3Target, blob: Blob, images_root: Path, pacer: Pacer | None) -> str:
+    """Upload one file to its key and return the key. Raises S3Error (or
+    OSError) with the reason when it can't be sent."""
+    path = Path(blob.path)
+    if not path.is_absolute():
+        path = images_root / path
+    if not path.is_file():
+        raise S3Error(f"{path} is not on disk.")
+    size = path.stat().st_size
+    if size != blob.size_bytes:
+        raise S3Error(f"{path} is {size} bytes on disk but {blob.size_bytes} when imported.")
+    key = blob_key(blob.sha256, blob.path)
+    content_type = blob.mime or "application/octet-stream"
+    try:
+        if size > MULTIPART_OVER:
+            put_file_in_parts(target, key, path, sha256=blob.sha256,
+                              content_type=content_type, pacer=pacer)
+        else:
+            put_file(target, key, path, content_type=content_type,
+                     payload_sha256=blob.sha256, pacer=pacer)
+    except S3Error:
+        if object_present(target, key, size):
+            return key          # already there from an earlier run
+        raise
+    return key
+
+
+def record(session, tid: str, blobs: list[tuple[Blob, str]]) -> None:
+    """Note files as sent: (blob, key) pairs. A row already there is kept."""
+    if blobs:
+        session.execute(insert(BackupBlob).values([
+            {"target": tid, "sha256": b.sha256, "key": key, "size_bytes": b.size_bytes}
+            for b, key in blobs
+        ]).on_conflict_do_nothing())
+
+
+def reconcile(session, target: S3Target) -> dict:
+    """Check backup_blob against what the bucket actually holds under
+    `media/`. A row whose object is missing or the wrong size is dropped, so
+    the next run sends that file again; an object the bucket holds for a
+    library file with no row (a restored database, a lost commit) is recorded,
+    so it isn't sent twice. Returns the counts."""
+    tid = target_id(target)
+    held: dict[str, int] = {}
+    token = None
+    while True:
+        page = list_objects(target, PREFIX, LIST_PAGE, continuation=token)
+        held.update((o.key, o.size) for o in page.objects)
+        token = page.next_token
+        if not token:
+            break
+        time.sleep(LIST_REST_SECONDS)
+
+    rows = session.execute(
+        select(BackupBlob.sha256, BackupBlob.key, BackupBlob.size_bytes)
+        .where(BackupBlob.target == tid)
+    ).all()
+    gone = [r.sha256 for r in rows if held.get(r.key) != r.size_bytes]
+    for at in range(0, len(gone), 1000):
+        session.execute(delete(BackupBlob).where(
+            BackupBlob.target == tid, BackupBlob.sha256.in_(gone[at:at + 1000]),
+        ))
+    kept = {r.sha256 for r in rows} - set(gone)
+
+    found = []
+    for r in session.execute(text(f"""
+        SELECT DISTINCT ON (sha256) sha256, path, size_bytes, mime
+        FROM ({_LIBRARY}) AS lib ORDER BY sha256, path
+    """)).all():
+        if r.sha256 in kept:
+            continue
+        blob = Blob(r.sha256, r.path, r.size_bytes, r.mime)
+        key = blob_key(blob.sha256, blob.path)
+        if held.get(key) == blob.size_bytes:
+            found.append((blob, key))
+    for at in range(0, len(found), 1000):
+        record(session, tid, found[at:at + 1000])
+    session.commit()
+    return {"listed": len(held), "dropped": len(gone), "adopted": len(found)}

backend/app/services/backup_restore.py

@@ -0,0 +1,191 @@
+"""Restoring from the off-site bucket: the database from one of its dated
+dumps, then every library file the restored rows name, fetched back to the
+path each row records.
+
+The database comes first because it is the map: each image and attachment row
+holds its file's path and sha256, which is also the file's name in the bucket
+(`media/ab/cd/<sha256><ext>`). A file is checked against that sha256 on
+arrival and only then moved into place, so a restore never leaves a wrong or
+half-written file in the library. A file already on disk at the right size is
+left alone, which makes a restore safe to run again and lets it bring back
+only what a damaged library is missing.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import select, text
+
+from ..models import BackupBlob, ImportSettings
+from . import backup_destination
+from .backup_media import _LIBRARY, blob_key
+from .backup_s3 import Pacer, S3Error, S3Target, get_file, list_objects
+
+DUMP_PREFIX = "database/"
+_DUMP_NAME = re.compile(r"^database/fabledcurator-(\d{8}T\d{6}Z)\.dump$")
+_ALEMBIC_INI = Path(__file__).resolve().parents[3] / "alembic.ini"
+_MIGRATE_TIMEOUT_S = 1800
+
+
+@dataclass(frozen=True)
+class Dump:
+    key: str
+    ts: str           # 20261107T134258Z, UTC
+    size_bytes: int
+
+
+def list_dumps(target: S3Target) -> list[Dump]:
+    """Every database dump in the bucket, newest first."""
+    dumps, token = [], None
+    while True:
+        page = list_objects(target, DUMP_PREFIX, 1000, continuation=token)
+        for o in page.objects:
+            if m := _DUMP_NAME.match(o.key):
+                dumps.append(Dump(o.key, m.group(1), o.size))
+        token = page.next_token
+        if not token:
+            break
+    return sorted(dumps, key=lambda d: d.ts, reverse=True)
+
+
+def find_dump(target: S3Target, key: str | None) -> Dump:
+    """The dump at `key`, or the newest when `key` is None or "latest"."""
+    dumps = list_dumps(target)
+    if not dumps:
+        raise S3Error(f"The {target.bucket} bucket holds no database dumps.")
+    if key in (None, "", "latest"):
+        return dumps[0]
+    for d in dumps:
+        if d.key == key:
+            return d
+    raise S3Error(f"{key} is not among the dumps in the {target.bucket} bucket.")
+
+
+def fetch_dump(target: S3Target, dump: Dump, into: Path, pacer: Pacer | None) -> Path:
+    """Download a dump into the folder `into`, checked against its listed
+    size. pg_restore reads it from there."""
+    into.mkdir(parents=True, exist_ok=True)
+    path = into / Path(dump.key).name
+    get_file(target, dump.key, path, size=dump.size_bytes, pacer=pacer)
+    return path
+
+
+def migrate() -> None:
+    """Bring a restored database up to this install's schema. A dump taken by
+    an older FabledCurator gains the migrations it predates; one from a newer
+    FabledCurator fails here, with alembic's reason, because this install
+    doesn't know its schema."""
+    with tempfile.TemporaryFile() as err:
+        proc = subprocess.run(
+            [sys.executable, "-m", "alembic", "-c", str(_ALEMBIC_INI), "upgrade", "head"],
+            cwd=_ALEMBIC_INI.parent, stdout=subprocess.DEVNULL, stderr=err,
+            timeout=_MIGRATE_TIMEOUT_S,
+        )
+        if proc.returncode != 0:
+            err.seek(0)
+            lines = err.read().decode(errors="replace").strip().splitlines()
+            raise S3Error("The restored database couldn't be brought up to this "
+                          f"version: {lines[-1] if lines else 'alembic failed'}")
+
+
+def keep_destination(session, target: S3Target, limit_mbps: int | None) -> None:
+    """Write this install's destination into the restored settings. The
+    dump's own copy of the secret is sealed with the old server's credential
+    key, which never leaves that server, so it can't be opened here."""
+    settings = ImportSettings.load_sync(session)
+    settings.backup_s3_endpoint = target.endpoint
+    settings.backup_s3_bucket = target.bucket
+    settings.backup_s3_access_key = target.access_key
+    settings.backup_s3_region = target.region
+    settings.backup_s3_secret_sealed = backup_destination.seal(target.secret_key)
+    settings.backup_upload_limit_mbps = limit_mbps
+    session.commit()
+
+
+# ── files ───────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class LibraryFile:
+    sha256: str
+    paths: tuple[str, ...]     # every row's path for this sha, sorted
+    size_bytes: int
+
+
+def library_files(session, *, after: str = "", limit: int = 200) -> list[LibraryFile]:
+    """The next `limit` distinct files the library names, in sha order after
+    `after`, each with every path a row gives it."""
+    rows = session.execute(text(f"""
+        SELECT lib.sha256, array_agg(DISTINCT lib.path ORDER BY lib.path) AS paths,
+               max(lib.size_bytes) AS size_bytes
+        FROM ({_LIBRARY}) AS lib
+        WHERE lib.sha256 > :after
+        GROUP BY lib.sha256
+        ORDER BY lib.sha256
+        LIMIT :limit
+    """), {"after": after, "limit": limit}).all()
+    return [LibraryFile(r.sha256, tuple(r.paths), r.size_bytes) for r in rows]
+
+
+def sent_keys(session, tid: str, shas: list[str]) -> dict[str, str]:
+    """The bucket key recorded for each sha that was sent to this destination."""
+    if not shas:
+        return {}
+    return dict(session.execute(
+        select(BackupBlob.sha256, BackupBlob.key)
+        .where(BackupBlob.target == tid, BackupBlob.sha256.in_(shas))
+    ).all())
+
+
+def _resolve(path: str, images_root: Path) -> Path:
+    """Where a row's path lands on this server. A path outside the library
+    folder is refused: a restore writes only inside it."""
+    p = Path(path)
+    if not p.is_absolute():
+        p = images_root / p
+    root = Path(*images_root.parts)
+    if ".." in p.parts or not (p == root or root in p.parents):
+        raise S3Error(f"{path} is outside {images_root}, so it isn't restored there.")
+    return p
+
+
+def _present(p: Path, size: int) -> bool:
+    try:
+        return p.is_file() and p.stat().st_size == size
+    except OSError:
+        return False
+
+
+def restore_file(target: S3Target, f: LibraryFile, key: str | None,
+                 images_root: Path, pacer: Pacer | None) -> str:
+    """Put one file back at every path the library gives it. Returns
+    "present" (nothing was missing), "copied" (a path already on disk
+    supplied the others) or "restored" (fetched from the bucket). Raises
+    ObjectMissing when the bucket doesn't hold it, S3Error or OSError
+    otherwise."""
+    places = [_resolve(p, images_root) for p in f.paths]
+    have = [p for p in places if _present(p, f.size_bytes)]
+    need = [p for p in places if p not in have]
+    if not need:
+        return "present"
+    outcome = "copied"
+    if not have:
+        first = need.pop(0)
+        first.parent.mkdir(parents=True, exist_ok=True)
+        get_file(target, key or blob_key(f.sha256, f.paths[0]), first,
+                 sha256=f.sha256, size=f.size_bytes, pacer=pacer)
+        have.append(first)
+        outcome = "restored"
+    for p in need:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        partial = p.with_name(p.name + ".partial")
+        shutil.copyfile(have[0], partial)
+        partial.replace(p)
+    return outcome
+

backend/app/services/backup_s3.py

@@ -0,0 +1,533 @@
+"""A small S3 client for sending backups off the box: AWS Signature Version 4,
+path-style addressing (endpoint/bucket/key), and the calls a backup needs —
+put an object (whole, or in parts when its size isn't known up front), read
+one back, list a prefix.
+
+FabledCurator puts, lists and reads; it never deletes. The bucket keeps the
+history and thins it on its own policy, so a key that may only add and read
+objects is enough, and is the safer key to hand a service: a stolen one cannot
+wipe the history it writes into.
+
+Built on the standard library's http.client rather than boto3: three calls
+don't justify a large dependency, and signing is a pure function the tests
+hold to AWS's own published examples. Every call is synchronous, because the
+uploads run in Celery workers; the API runs the Test destination call in a
+thread.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import http.client
+import os
+import socket
+import ssl
+import time
+import xml.etree.ElementTree as ET
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from urllib.parse import parse_qsl, quote, unquote, urlencode, urlsplit
+
+EMPTY_SHA256 = hashlib.sha256(b"").hexdigest()
+TIMEOUT_SECONDS = 30.0
+# A single object can be a multi-gigabyte video or archive; a slow link still
+# gets this long between bytes before the call gives up.
+TRANSFER_TIMEOUT_SECONDS = 15 * 60
+CHUNK = 1 << 20
+
+
+class S3Error(Exception):
+    """Why a call to the bucket failed, said to the person."""
+
+
+@dataclass(frozen=True)
+class S3Target:
+    endpoint: str          # http(s)://host[:port][/prefix], no bucket
+    bucket: str
+    access_key: str
+    secret_key: str
+    region: str = "us-east-1"
+    verify_tls: bool = True
+
+    def url(self, key: str = "") -> str:
+        base = f"{self.endpoint.rstrip('/')}/{quote(self.bucket, safe='')}"
+        return f"{base}/{quote(key, safe='/-_.~')}" if key else f"{base}/"
+
+
+@dataclass(frozen=True)
+class StoredObject:
+    key: str
+    size: int
+    last_modified: str
+
+
+@dataclass(frozen=True)
+class ListPage:
+    objects: list[StoredObject]
+    next_token: str | None     # pass back as `continuation` for the next page
+
+
+# ── Signing ──────────────────────────────────────────────────────────────────
+
+def _encode(text: str, keep_slash: bool = False) -> str:
+    return quote(text, safe="-_.~" + ("/" if keep_slash else ""))
+
+
+def _hmac(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode(), hashlib.sha256).digest()
+
+
+def sign(method: str, url: str, headers: dict[str, str], payload_sha256: str,
+         access_key: str, secret_key: str, region: str, at: datetime,
+         service: str = "s3") -> dict[str, str]:
+    """The request's headers with Host, x-amz-date, x-amz-content-sha256 and
+    Authorization added. Every header given is signed, Host always."""
+    u = urlsplit(url)
+    stamp = at.astimezone(UTC).strftime("%Y%m%dT%H%M%SZ")
+    day = stamp[:8]
+    out = dict(headers)
+    out["Host"] = u.netloc
+    out["x-amz-date"] = stamp
+    out["x-amz-content-sha256"] = payload_sha256
+    signed = {k.lower(): " ".join(str(v).split()) for k, v in out.items()}
+    names = sorted(signed)
+
+    query = sorted(
+        (_encode(k), _encode(v)) for k, v in parse_qsl(u.query, keep_blank_values=True)
+    )
+    canonical = "\n".join([
+        method.upper(),
+        _encode(unquote(u.path) or "/", keep_slash=True),
+        "&".join(f"{k}={v}" for k, v in query),
+        "".join(f"{n}:{signed[n]}\n" for n in names),
+        ";".join(names),
+        payload_sha256,
+    ])
+    scope = f"{day}/{region}/{service}/aws4_request"
+    to_sign = "\n".join(["AWS4-HMAC-SHA256", stamp, scope,
+                         hashlib.sha256(canonical.encode()).hexdigest()])
+    key = _hmac(_hmac(_hmac(_hmac(f"AWS4{secret_key}".encode(), day), region),
+                      service), "aws4_request")
+    signature = hmac.new(key, to_sign.encode(), hashlib.sha256).hexdigest()
+    out["Authorization"] = (f"AWS4-HMAC-SHA256 Credential={access_key}/{scope}, "
+                            f"SignedHeaders={';'.join(names)}, Signature={signature}")
+    return out
+
+
+# ── Transport ────────────────────────────────────────────────────────────────
+
+def _connect(target: S3Target, url: str, timeout: float) -> http.client.HTTPConnection:
+    u = urlsplit(url)
+    if u.scheme == "https":
+        ctx = ssl.create_default_context()
+        if not target.verify_tls:
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+        return http.client.HTTPSConnection(
+            u.hostname, u.port, timeout=timeout, context=ctx, blocksize=CHUNK,
+        )
+    if u.scheme != "http":
+        raise S3Error(f"{target.endpoint} isn't an http:// or https:// address.")
+    return http.client.HTTPConnection(u.hostname, u.port, timeout=timeout, blocksize=CHUNK)
+
+
+def _request_target(url: str) -> str:
+    u = urlsplit(url)
+    return (u.path or "/") + (f"?{u.query}" if u.query else "")
+
+
+def _reach_error(target: S3Target, exc: Exception) -> S3Error:
+    if isinstance(exc, TimeoutError):
+        return S3Error(f"{target.endpoint} didn't answer in time.")
+    if isinstance(exc, socket.gaierror):
+        return S3Error(f"Couldn't reach {target.endpoint}: the host name doesn't resolve.")
+    if isinstance(exc, ConnectionRefusedError):
+        return S3Error(
+            f"Couldn't reach {target.endpoint}: nothing is listening there "
+            "(check the port)."
+        )
+    if isinstance(exc, ssl.SSLError):
+        return S3Error(f"Couldn't reach {target.endpoint}: TLS failed ({exc.reason}).")
+    return S3Error(f"Couldn't reach {target.endpoint}: {exc}.")
+
+
+def _says(status: int, reason: str, content: bytes) -> str:
+    """An S3 error response in words: its Code and Message when it has them."""
+    try:
+        root = ET.fromstring(content) if content else None
+        code = (root.findtext("Code") or "") if root is not None else ""
+        message = (root.findtext("Message") or "") if root is not None else ""
+    except ET.ParseError:
+        code, message = "", ""
+    hints = {
+        "SignatureDoesNotMatch": "the secret key is wrong",
+        "InvalidAccessKeyId": "the access key isn't known there",
+        "NoSuchBucket": "there is no such bucket",
+        "AccessDenied": "the key isn't allowed to do that",
+        "XAmzContentSHA256Mismatch": "the file's bytes don't match its recorded checksum",
+    }
+    said = hints.get(code) or message or reason
+    if not code and 400 <= status < 500:
+        # S3 refuses with an <Error><Code> body. A 4xx without one came from
+        # something else at that address — most often a web server on the
+        # default port, when the S3 service listens on a port of its own.
+        said = ("the address answered, but not as S3 — check the scheme and "
+                "the port (an S3 service usually listens on its own port)")
+    return f"HTTP {status}{f' {code}' if code else ''}: {said}."
+
+
+# ── Calls ────────────────────────────────────────────────────────────────────
+
+def file_sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(CHUNK):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def put_file(target: S3Target, key: str, path: Path, *,
+             content_type: str = "application/octet-stream",
+             payload_sha256: str | None = None,
+             pacer: Pacer | None = None,
+             now: datetime | None = None) -> None:
+    """Upload one file as one object, streamed from disk. `payload_sha256` is
+    the file's sha256 when the caller already knows it (the library stores
+    every file's), which saves reading the file twice; the bucket checks the
+    bytes against it, so a file that changed on disk is refused rather than
+    stored under the wrong name."""
+    digest = payload_sha256 or file_sha256(path)
+    size = path.stat().st_size
+    url = target.url(key)
+    headers = sign("PUT", url, {"Content-Length": str(size), "Content-Type": content_type},
+                   digest, target.access_key, target.secret_key, target.region,
+                   now or datetime.now(UTC))
+    conn = _connect(target, url, TRANSFER_TIMEOUT_SECONDS)
+    try:
+        with open(path, "rb") as f:
+            conn.request("PUT", _request_target(url),
+                         body=pacer.file_chunks(f) if pacer else f, headers=headers)
+            response = conn.getresponse()
+            content = response.read()
+    except (OSError, http.client.HTTPException) as exc:
+        raise _reach_error(target, exc) from None
+    finally:
+        conn.close()
+    if response.status // 100 != 2:
+        raise S3Error(f"Upload of {key} refused: "
+                      f"{_says(response.status, response.reason, content)}")
+
+
+class ObjectMissing(S3Error):
+    """The bucket holds nothing at the key asked for."""
+
+
+def get_file(target: S3Target, key: str, path: Path, *,
+             sha256: str | None = None, size: int | None = None,
+             pacer: Pacer | None = None,
+             now: datetime | None = None) -> None:
+    """Download one object to `path`, streamed to disk. The bytes land under a
+    `.partial` name and are renamed into place when complete, so a broken
+    transfer never leaves a truncated file at `path`. With `sha256` (and
+    `size`) given, the bytes are checked on arrival and a copy that doesn't
+    match is thrown away and reported. Raises ObjectMissing when the bucket
+    has no such object."""
+    url = target.url(key)
+    headers = sign("GET", url, {}, EMPTY_SHA256, target.access_key, target.secret_key,
+                   target.region, now or datetime.now(UTC))
+    partial = path.with_name(path.name + ".partial")
+    digest = hashlib.sha256()
+    got = 0
+    conn = _connect(target, url, TRANSFER_TIMEOUT_SECONDS)
+    try:
+        conn.request("GET", _request_target(url), headers=headers)
+        response = conn.getresponse()
+        if response.status == 404:
+            response.read()
+            raise ObjectMissing(f"{key} is not in the {target.bucket} bucket.")
+        if response.status != 200:
+            raise S3Error(f"Reading {key} refused: "
+                          f"{_says(response.status, response.reason, response.read())}")
+        with open(partial, "wb") as f:
+            while chunk := response.read(CHUNK):
+                if pacer:
+                    pacer.take(len(chunk))
+                digest.update(chunk)
+                got += len(chunk)
+                f.write(chunk)
+        if size is not None and got != size:
+            raise S3Error(f"{key} arrived as {got} bytes, not the {size} expected.")
+        if sha256 and digest.hexdigest() != sha256:
+            raise S3Error(f"{key} arrived with a different fingerprint "
+                          f"({digest.hexdigest()[:12]}…), so it wasn't kept.")
+        os.replace(partial, path)
+    except (OSError, http.client.HTTPException) as exc:
+        partial.unlink(missing_ok=True)
+        raise _reach_error(target, exc) from None
+    except S3Error:
+        partial.unlink(missing_ok=True)
+        raise
+    finally:
+        conn.close()
+
+
+def list_objects(target: S3Target, prefix: str = "", limit: int = 1000, *,
+                 continuation: str | None = None,
+                 now: datetime | None = None) -> ListPage:
+    """One page (up to `limit`) of the objects under `prefix`, ListObjectsV2."""
+    params = {"list-type": "2", "max-keys": str(limit)}
+    if prefix:
+        params["prefix"] = prefix
+    if continuation:
+        params["continuation-token"] = continuation
+    url = f"{target.url()}?{urlencode(params, quote_via=quote)}"
+    headers = sign("GET", url, {}, EMPTY_SHA256, target.access_key, target.secret_key,
+                   target.region, now or datetime.now(UTC))
+    conn = _connect(target, url, TIMEOUT_SECONDS)
+    try:
+        conn.request("GET", _request_target(url), headers=headers)
+        response = conn.getresponse()
+        content = response.read()
+    except (OSError, http.client.HTTPException) as exc:
+        raise _reach_error(target, exc) from None
+    finally:
+        conn.close()
+    if response.status != 200:
+        raise S3Error(f"Listing {target.bucket} refused: "
+                      f"{_says(response.status, response.reason, content)}")
+    try:
+        root = ET.fromstring(content)
+    except ET.ParseError:
+        raise S3Error(
+            f"{target.endpoint} answered a listing with something that isn't S3's XML."
+        ) from None
+    objects, next_token = [], None
+    for item in root.iter():
+        tag = item.tag.rsplit("}", 1)[-1]
+        if tag == "NextContinuationToken":
+            next_token = item.text or None
+        if tag != "Contents":
+            continue
+        fields = {child.tag.rsplit("}", 1)[-1]: (child.text or "") for child in item}
+        objects.append(StoredObject(fields.get("Key", ""), int(fields.get("Size") or 0),
+                                    fields.get("LastModified", "")))
+    return ListPage(objects, next_token)
+
+
+# ── Multipart: one object sent in parts ─────────────────────────────────────
+
+# Each part is held in memory while it is sent, so this bounds the memory a
+# streamed upload uses. S3 allows 10,000 parts, which at this size is 640 GiB
+# for one object, and every part but the last must be at least 5 MiB.
+PART_SIZE = 64 * CHUNK
+# A part the bucket couldn't take (it didn't answer, or said it was busy) is
+# sent again after a rest that grows each time: 15 s, then 60 s.
+PART_RETRY_WAITS = (15, 60)
+_BUSY = frozenset({429, 500, 502, 503, 504})
+_MAX_RETRY_AFTER = 300
+
+
+class Pacer:
+    """Holds the bytes a job moves to an average rate, across every request
+    it makes, so a backup or a restore leaves room on the link for everything
+    else."""
+
+    def __init__(self, mbps: int | None):
+        self.rate = mbps * 1_000_000 / 8 if mbps else None   # bytes per second
+        self.sent = 0
+        self.started = time.monotonic()
+
+    def take(self, n: int) -> None:
+        """Count `n` bytes moved, pausing while the job is ahead of its rate."""
+        if self.rate:
+            self.sent += n
+            ahead = self.sent / self.rate - (time.monotonic() - self.started)
+            if ahead > 0:
+                time.sleep(ahead)
+
+    def chunks(self, data: bytes) -> Iterator[memoryview]:
+        view = memoryview(data)
+        for at in range(0, len(view), CHUNK):
+            piece = view[at:at + CHUNK]
+            self.take(len(piece))
+            yield piece
+
+    def file_chunks(self, f) -> Iterator[bytes]:
+        while piece := f.read(CHUNK):
+            self.take(len(piece))
+            yield piece
+
+
+def _send(target: S3Target, method: str, url: str, body: bytes = b"",
+          headers: dict[str, str] | None = None, *, timeout: float = TIMEOUT_SECONDS,
+          pacer: Pacer | None = None,
+          now: datetime | None = None) -> tuple[int, str, http.client.HTTPMessage, bytes]:
+    """Sign and send one request with an in-memory body, paced when a pacer
+    is given. Returns (status, reason, headers, content)."""
+    digest = hashlib.sha256(body).hexdigest()
+    signed = sign(method, url, {"Content-Length": str(len(body)), **(headers or {})},
+                  digest, target.access_key, target.secret_key, target.region,
+                  now or datetime.now(UTC))
+    conn = _connect(target, url, timeout)
+    try:
+        conn.request(method, _request_target(url),
+                     body=pacer.chunks(body) if pacer and body else body, headers=signed)
+        response = conn.getresponse()
+        content = response.read()
+    except (OSError, http.client.HTTPException) as exc:
+        raise _reach_error(target, exc) from None
+    finally:
+        conn.close()
+    return response.status, response.reason, response.headers, content
+
+
+def _xml_field(content: bytes, name: str) -> str | None:
+    try:
+        root = ET.fromstring(content)
+    except ET.ParseError:
+        return None
+    for item in root.iter():
+        if item.tag.rsplit("}", 1)[-1] == name:
+            return item.text
+    return None
+
+
+def _is_error_body(content: bytes) -> bool:
+    try:
+        return bool(content) and ET.fromstring(content).tag.rsplit("}", 1)[-1] == "Error"
+    except ET.ParseError:
+        return False
+
+
+def _retry_after(headers: http.client.HTTPMessage | None, default: int) -> int:
+    try:
+        asked = int((headers or {}).get("Retry-After") or default)
+    except ValueError:
+        asked = default
+    return max(0, min(asked, _MAX_RETRY_AFTER))
+
+
+class Upload:
+    """One object written as a series of parts, for data whose size isn't known
+    when it starts, such as a database dump streamed from pg_dump.
+
+    The object appears in the bucket only when `complete()` succeeds. Until
+    then the parts are invisible, so a stream that fails partway leaves
+    nothing behind that looks like a finished backup. `abort()` asks the
+    bucket to drop the parts at once; if the abort is refused or never
+    arrives, S3 services expire an unfinished upload on their own (Fabled
+    Archives after a day)."""
+
+    def __init__(self, target: S3Target, key: str, *,
+                 content_type: str = "application/octet-stream",
+                 pacer: Pacer | None = None):
+        self.target = target
+        self.key = key
+        self.size = 0
+        self.pacer = pacer
+        self._etags: list[str] = []
+        status, reason, _, content = _send(
+            target, "POST", f"{target.url(key)}?uploads", headers={"Content-Type": content_type},
+        )
+        upload_id = _xml_field(content, "UploadId") if status == 200 else None
+        if not upload_id:
+            raise S3Error(f"Starting the upload of {key} refused: "
+                          f"{_says(status, reason, content)}")
+        self.upload_id = upload_id
+
+    def _url(self, **params: str) -> str:
+        query = urlencode({**params, "uploadId": self.upload_id}, quote_via=quote)
+        return f"{self.target.url(self.key)}?{query}"
+
+    @property
+    def parts(self) -> int:
+        return len(self._etags)
+
+    def add(self, data: bytes) -> None:
+        """Send the next part, resting and sending it again when the bucket
+        doesn't answer or says it is busy."""
+        n = len(self._etags) + 1
+        for wait in (*PART_RETRY_WAITS, None):
+            headers = None
+            try:
+                status, reason, headers, content = _send(
+                    self.target, "PUT", self._url(partNumber=str(n)), data,
+                    timeout=TRANSFER_TIMEOUT_SECONDS, pacer=self.pacer,
+                )
+            except S3Error as exc:
+                if wait is None:
+                    raise S3Error(f"Part {n} of {self.key}: {exc}") from None
+                time.sleep(wait)
+                continue
+            etag = headers.get("ETag") if status == 200 else None
+            if etag:
+                self._etags.append(etag)
+                self.size += len(data)
+                return
+            if status not in _BUSY or wait is None:
+                raise S3Error(f"Part {n} of {self.key} refused: "
+                              f"{_says(status, reason, content)}")
+            time.sleep(_retry_after(headers, wait))
+
+    def complete(self) -> None:
+        """Join the parts into the object. S3 can refuse a completion with an
+        error body under a 200 status, so the body is read too."""
+        if not self._etags:
+            raise S3Error(f"Nothing was sent for {self.key}.")
+        body = "<CompleteMultipartUpload>" + "".join(
+            f"<Part><PartNumber>{n}</PartNumber><ETag>{etag}</ETag></Part>"
+            for n, etag in enumerate(self._etags, start=1)
+        ) + "</CompleteMultipartUpload>"
+        status, reason, _, content = _send(
+            self.target, "POST", self._url(), body.encode(),
+            headers={"Content-Type": "application/xml"}, timeout=TRANSFER_TIMEOUT_SECONDS,
+        )
+        if status != 200 or _is_error_body(content):
+            raise S3Error(f"Finishing the upload of {self.key} refused: "
+                          f"{_says(status, reason, content)}")
+
+    def abort(self) -> None:
+        """Drop the parts sent so far. Never raises: it runs while another
+        failure is already being reported, and the bucket expires the parts on
+        its own if this doesn't reach it."""
+        try:
+            _send(self.target, "DELETE", self._url())
+        except Exception:  # noqa: BLE001 — best effort, see above
+            pass
+
+
+def put_file_in_parts(target: S3Target, key: str, path: Path, *, sha256: str,
+                      content_type: str = "application/octet-stream",
+                      pacer: Pacer | None = None) -> int:
+    """Upload a large file as a multipart object, read from disk a part at a
+    time. The whole file's sha256 is computed on the way and must equal
+    `sha256` before the upload is completed; otherwise it is aborted, so a file
+    that changed on disk is never stored under its old name. Returns the
+    number of bytes sent."""
+    upload = Upload(target, key, content_type=content_type, pacer=pacer)
+    digest = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            while part := f.read(PART_SIZE):
+                digest.update(part)
+                upload.add(part)
+        if digest.hexdigest() != sha256:
+            raise S3Error(f"{path} no longer matches its recorded checksum; not stored.")
+        upload.complete()
+    except BaseException:
+        upload.abort()
+        raise
+    return upload.size
+
+
+def object_present(target: S3Target, key: str, size: int) -> bool:
+    """Whether `key` is already in the bucket at `size` bytes. Used when a put
+    is refused: an append-only bucket refuses to replace an object that is
+    already there, which for a content-addressed key means the work is done."""
+    try:
+        page = list_objects(target, prefix=key, limit=1)
+    except S3Error:
+        return False
+    return any(o.key == key and o.size == size for o in page.objects)

backend/app/services/backup_service.py

@@ -4,7 +4,9 @@ Two independent backup kinds:
   - 'db'     — pg_dump only; fast; nightly via Beat (settings-gated)
   - 'images' — tar+zstd of /images; slow; manual trigger only
 
-Files live under <images_root>/_backups/. Each backup writes:
+With an off-site destination set up, a database dump streams straight to that
+bucket instead (backup_db_offsite). Otherwise files live under
+<images_root>/_backups/. Each local backup writes:
   fc_<kind>_<ts>.{sql|tar.zst}        — the artifact
   fc_<kind>_<ts>.json                 — manifest (kind/tag/triggered_by)
 
@@ -19,6 +21,7 @@ import os
 import shutil
 import subprocess
 import tempfile
+import time
 from datetime import UTC, datetime
 from pathlib import Path
 
@@ -62,6 +65,14 @@ _IMAGES_SUBPROCESS_TIMEOUT_S = 21000       # ~5.8 hr, under the 6-hr images soft
 _KILL_REAP_GRACE_S = 10
 
 
+# Every database dump, local or off-site: custom format (-Fc, compressed and
+# restored with pg_restore), without ownership or grants so it loads into any
+# install. The `credential` table's rows (account logins, sealed with the key
+# in /images/secrets) stay out: a restored install keeps the table, empty, and
+# you sign in to each account again.
+_PG_DUMP = ["pg_dump", "--no-owner", "--no-acl", "-Fc", "--exclude-table-data=credential"]
+
+
 def _run_bounded(cmd: list[str], timeout: int) -> None:
     """subprocess.run(check=True, timeout) whose reaper can't itself hang.
 
@@ -153,10 +164,7 @@ def backup_db(
     tmp_path = Path(tmp_name)
     try:
         _run_bounded(
-            [
-                "pg_dump", "--no-owner", "--no-acl", "-Fc",
-                "-f", str(tmp_path), _libpq_url(db_url),
-            ],
+            _gently([*_PG_DUMP, "-f", str(tmp_path), _libpq_url(db_url)]),
             _DB_SUBPROCESS_TIMEOUT_S,
         )
         shutil.move(str(tmp_path), str(sql_path))
@@ -177,6 +185,79 @@ def backup_db(
     }
 
 
+class DumpFailed(Exception):
+    """pg_dump exited with an error; the message is its last line of output."""
+
+
+def offsite_dump_key(ts: str) -> str:
+    """Where a database dump lands in the off-site bucket. Dated names sit
+    side by side under one prefix, which is what lets the bucket's retention
+    thin them by age."""
+    return f"database/fabledcurator-{ts}.dump"
+
+
+def _gently(cmd: list[str]) -> list[str]:
+    """`cmd` at low CPU priority, and low disk priority where `ionice` is
+    installed, so a long dump leaves the server responsive."""
+    io = ["ionice", "-c", "2", "-n", "7"] if shutil.which("ionice") else []
+    return ["nice", "-n", "10", *io, *cmd]
+
+
+def _last_line(f) -> str | None:
+    f.seek(0)
+    lines = f.read().decode(errors="replace").strip().splitlines()
+    return lines[-1].strip() if lines else None
+
+
+def backup_db_offsite(*, db_url: str, target, limit_mbps: int | None = None) -> dict:
+    """Stream `pg_dump` straight into the off-site bucket, in parts, with no
+    copy staged on this server. The object appears only once pg_dump has
+    exited cleanly and every part has arrived; a dump that fails partway
+    leaves nothing in the bucket, and raises DumpFailed with pg_dump's own
+    last line. Returns a dict for the caller to record in BackupRun."""
+    from .backup_s3 import PART_SIZE, Pacer, Upload
+
+    ts = _now_ts()
+    key = offsite_dump_key(ts)
+    deadline = time.monotonic() + _DB_SUBPROCESS_TIMEOUT_S
+    with tempfile.TemporaryFile() as err:
+        proc = subprocess.Popen(
+            _gently([*_PG_DUMP, _libpq_url(db_url)]),
+            stdout=subprocess.PIPE, stderr=err,
+        )
+        upload = None
+        try:
+            upload = Upload(target, key, pacer=Pacer(limit_mbps))
+            while part := proc.stdout.read(PART_SIZE):
+                if time.monotonic() > deadline:
+                    raise subprocess.TimeoutExpired(proc.args, _DB_SUBPROCESS_TIMEOUT_S)
+                upload.add(part)
+            proc.stdout.close()
+            proc.wait(timeout=_KILL_REAP_GRACE_S * 6)
+            if proc.returncode != 0:
+                raise DumpFailed(_last_line(err) or f"pg_dump exited with {proc.returncode}")
+            upload.complete()
+        except BaseException:
+            if proc.poll() is None:
+                proc.kill()
+                try:
+                    proc.wait(timeout=_KILL_REAP_GRACE_S)
+                except subprocess.TimeoutExpired:
+                    pass  # unkillable (D-state): abandon the reap, fail fast
+            if upload is not None:
+                upload.abort()
+            raise
+    return {
+        "kind": "db",
+        "ts": ts,
+        "key": key,
+        "bucket": target.bucket,
+        "endpoint": target.endpoint,
+        "parts": upload.parts,
+        "size_bytes": upload.size,
+    }
+
+
 def backup_images(
     *, images_root: Path,
     tag: str | None = None, triggered_by: str = "manual",
@@ -213,25 +294,105 @@ def backup_images(
     }
 
 
-def restore_db(*, db_url: str, sql_path: Path) -> None:
-    """Wipe public schema, then load from the custom-format dump. Raises on
-    subprocess failure; partial-restore state is the caller's concern."""
-    libpq = _libpq_url(db_url)
-    subprocess.run(
+class RestoreFailed(Exception):
+    """psql or pg_restore exited with an error; the message is its last line."""
+
+
+# A restore waits this long for other connections to let go of the tables it
+# replaces, then gives up with Postgres' own reason instead of queueing every
+# other query behind it.
+_RESTORE_LOCK_TIMEOUT = "60s"
+# pg_restore of a large library (vector tables, rebuilt indexes) runs well past
+# a dump's length; it is bounded on its own.
+_RESTORE_SUBPROCESS_TIMEOUT_S = 3 * 3600
+
+
+def _run_reporting(cmd: list[str], timeout: int, env: dict | None = None) -> None:
+    """Run `cmd`; raise RestoreFailed with the last line it printed when it
+    exits non-zero."""
+    with tempfile.TemporaryFile() as err:
+        proc = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=err, timeout=timeout,
+                              env=env)
+        if proc.returncode != 0:
+            raise RestoreFailed(_last_line(err) or f"{cmd[0]} exited with {proc.returncode}")
+
+
+# Every other connection to this database: the web server's, the other
+# workers'. Ended before the tables are dropped, so none holds a lock the drop
+# waits on, and again once the restore is in, so none keeps statements it
+# prepared against the old tables. Each reconnects on its next query.
+_END_OTHER_CONNECTIONS = (
+    "SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
+    "WHERE datname = current_database() AND pid <> pg_backend_pid();"
+)
+
+
+def end_other_connections(*, db_url: str) -> None:
+    _run_reporting(["psql", _libpq_url(db_url), "-v", "ON_ERROR_STOP=1",
+                    "-c", _END_OTHER_CONNECTIONS], 60)
+
+
+def wipe_db(*, db_url: str) -> None:
+    """Drop and recreate the public schema: an empty database, ready for a
+    dump or for `alembic upgrade head`."""
+    _run_reporting(
         [
-            "psql", libpq, "-c",
-            "DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public;",
+            "psql", _libpq_url(db_url), "-v", "ON_ERROR_STOP=1", "-c",
+            f"{_END_OTHER_CONNECTIONS} DROP SCHEMA IF EXISTS public CASCADE; "
+            "CREATE SCHEMA public;",
         ],
-        capture_output=True, check=True, timeout=120,
-    )
-    # Custom-format (-Fc) dumps are restored with pg_restore, not psql.
-    subprocess.run(
-        ["pg_restore", "--no-owner", "--no-acl", "-d", libpq, str(sql_path)],
-        capture_output=True, check=True,
-        timeout=_DB_SUBPROCESS_TIMEOUT_S,
+        120,
+        # Set for the session, not as a SET inside the same -c string.
+        env={**os.environ, "PGOPTIONS": f"-c lock_timeout={_RESTORE_LOCK_TIMEOUT}"},
     )
 
 
+# A pg_restore newer than the server sets parameters the server doesn't have
+# (pg_restore 17 against Postgres 16: `SET transaction_timeout = 0`). The
+# statement fails and nothing depends on it, so its error is not a failed
+# restore.
+_HARMLESS_RESTORE_ERRORS = (
+    'unrecognized configuration parameter "transaction_timeout"',
+)
+
+
+def _restore_errors(stderr: str) -> list[str]:
+    """pg_restore's error lines, less the harmless ones."""
+    return [
+        line.strip() for line in stderr.splitlines()
+        if "error:" in line and not any(h in line for h in _HARMLESS_RESTORE_ERRORS)
+    ]
+
+
+def restore_db(*, db_url: str, sql_path: Path) -> None:
+    """Wipe the public schema, then load the custom-format dump. Any error
+    pg_restore reports, other than a harmless one, raises RestoreFailed with
+    the first; the database is then partly loaded, and the caller decides what
+    to put back."""
+    wipe_db(db_url=db_url)
+    # Custom-format (-Fc) dumps are restored with pg_restore, not psql. It runs
+    # on past errors (it can't skip the harmless one and stop at the rest), so
+    # its errors are judged once it is done.
+    cmd = _gently(["pg_restore", "--no-owner", "--no-acl",
+                   "-d", _libpq_url(db_url), str(sql_path)])
+    with tempfile.TemporaryFile() as err:
+        proc = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=err,
+                              timeout=_RESTORE_SUBPROCESS_TIMEOUT_S)
+        if proc.returncode == 0:
+            return
+        err.seek(0)
+        said = err.read().decode(errors="replace")
+    errors = _restore_errors(said)
+    if errors:
+        raise RestoreFailed(errors[0] if len(errors) == 1
+                            else f"{errors[0]} ({len(errors)} errors in all)")
+    if not any(h in said for h in _HARMLESS_RESTORE_ERRORS):
+        # A failure with no error line to show for it.
+        lines = said.strip().splitlines()
+        raise RestoreFailed(lines[-1].strip() if lines
+                            else f"pg_restore exited with {proc.returncode}")
+
+
 def restore_images(*, images_root: Path, tar_path: Path) -> None:
     """Untar over images_root.parent. Additive — files NOT in the
     tarball are NOT removed. Caller wipes first if a clean restore

backend/app/services/download_service.py

@@ -369,11 +369,8 @@ class DownloadService:
                     if do_embed:
                         embed_image.delay(img_id)
             elif result.status == "attached":
-                # Non-media or extracted archive captured as PostAttachment
-                # (FC-2d-iii). The canonical copy lives in the attachments
-                # store; the original download path is now redundant —
-                # mirror duplicate_hash cleanup so we don't keep two copies.
-                # Operator-flagged 2026-06-02 (Lustria OST zip).
+                # Non-media, or an archive with no new images, captured as a
+                # PostAttachment; the attachments store holds the copy.
                 import_summary["attached"] += 1
                 # An archive captured WITHOUT extracting any image carries a
                 # reason on result.error — record it so the event explains the
@@ -390,35 +387,13 @@ class DownloadService:
                     bytes_downloaded += path.stat().st_size  # noqa: ASYNC240
                 except OSError:
                     pass
-                try:
-                    path.unlink(missing_ok=True)  # noqa: ASYNC240
-                except OSError:
-                    pass
-            elif result.status == "skipped" and result.skip_reason and result.skip_reason.value in (
-                "duplicate_hash", "duplicate_phash",
-            ):
-                import_summary["skipped"] += 1
-                try:
-                    path.unlink(missing_ok=True)  # noqa: ASYNC240
-                except OSError:
-                    pass
             elif result.status == "skipped":
-                # Soft skip (too_small, too_transparent, invalid_image) —
-                # the file just didn't qualify, not a download/ingest
-                # failure. Don't flag the run as error; the file stays
-                # on disk for operator inspection.
+                # A duplicate, or a file the import filters rejected. Neither
+                # is a download failure, so the run is not flagged.
                 import_summary["skipped"] += 1
             elif result.status == "failed":
-                # Hard failure (today only: archive probe crash/timeout).
-                # The original archive sits in /images/ as an orphan; the
-                # filesystem scanner would re-import and re-crash on the
-                # same file, so delete the source file and surface the
-                # error in import_summary. Audit 2026-06-02.
+                # Hard failure: an archive probe crashed or timed out.
                 import_summary["errors"] += 1
-                try:
-                    path.unlink(missing_ok=True)  # noqa: ASYNC240
-                except OSError:
-                    pass
             elif result.status == "refreshed":
                 # Currently unreachable from attach_in_place (the download
                 # path never runs in deep=True mode), but the importer's
@@ -427,6 +402,10 @@ class DownloadService:
                 import_summary["attached"] += 1
             else:
                 import_summary["errors"] += 1
+            # Remove the download when the library no longer needs it at this
+            # path: an attachment or archive now in the store, a duplicate, a
+            # rejected file. One policy for every download path.
+            self.importer.discard_after_attach(path, result)
 
         # Post-only records: media-less posts (pure-text) the native ingester
         # captured so the artist archive is complete. Upsert each (keyed on

backend/app/services/external_fetch.py

@@ -241,11 +241,19 @@ def _fetch_gdrive(url: str, dest_dir: Path, *, read_timeout: float,
 def _fetch_mega(url: str, dest_dir: Path, *, read_timeout: float,
                 total_timeout: float,
                 should_stop: Callable[[], bool]) -> FetchResult:
-    before = set(dest_dir.iterdir()) if dest_dir.exists() else set()
+    # A folder link keeps its subfolders, so files are found at any depth.
+    # Dotfiles are megatools' `.megatmp.*` staging names.
+    def _complete_files() -> set[Path]:
+        return {
+            p for p in dest_dir.rglob("*")
+            if p.is_file() and not p.name.startswith(".")
+        } if dest_dir.exists() else set()
+
+    before = _complete_files()
     # megatools is a subprocess: its timeout IS a total wall-clock cap (the read
     # timeout has no analogue here), so the total budget applies directly.
     _run_mega_get(url, str(dest_dir), timeout=total_timeout)
-    new = [p for p in dest_dir.iterdir() if p not in before and p.is_file()]
+    new = sorted(_complete_files() - before)
     if not new:
         return FetchResult(error="mega-get wrote no new file")
     return FetchResult(files=new, bytes=sum(p.stat().st_size for p in new))

backend/app/services/external_links.py

@@ -21,9 +21,9 @@ log = logging.getLogger(__name__)
 
 
 def refetch_links_for_post(session: Session, post_id: int) -> dict:
-    """Reset every settled ExternalLink on a post to pending (fresh attempt
-    budget) and dispatch its fetch. In-flight ('downloading') links are left
-    alone. Commits. Returns {links_total, links_reset}."""
+    """Reset every settled ExternalLink on a post to pending (fresh attempt and
+    recovery budgets) and dispatch its fetch. In-flight ('downloading') links
+    are left alone. Commits. Returns {links_total, links_reset}."""
     links = session.execute(
         select(ExternalLink).where(ExternalLink.post_id == post_id)
     ).scalars().all()
@@ -33,6 +33,7 @@ def refetch_links_for_post(session: Session, post_id: int) -> dict:
             continue
         link.status = "pending"
         link.attempts = 0
+        link.recoveries = 0
         link.last_error = None
         link.completed_at = None
         reset_ids.append(link.id)

backend/app/services/importer.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass, field
 from enum import StrEnum
 from pathlib import Path
 
+from celery.exceptions import SoftTimeLimitExceeded
 from PIL import Image
 from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
@@ -43,6 +44,7 @@ from ..utils.paths import (
 from ..utils.phash import compute_phash, find_similar, fingerprint_path, fingerprints_match
 from ..utils.sidecar import find_sidecar, parse_sidecar
 from ..utils.slug import slugify
+from ..utils.staging import is_temp_staging_file
 from .archive_extractor import extract_archive, is_archive
 from .attachment_store import AttachmentStore
 from .audits import single_color
@@ -115,6 +117,21 @@ def is_video(path: Path) -> bool:
     return path.suffix.lower() in VIDEO_EXTS
 
 
+def _not_content(path: Path) -> ImportResult | None:
+    """The skip result for a file that is never library content: a sidecar
+    `.json` (metadata) or a downloader's staging file (an unfinished download,
+    which becomes content only under its final name). None for anything else."""
+    if path.suffix.lower() == ".json":
+        error = "sidecar json is metadata, not content"
+    elif is_temp_staging_file(path):
+        error = "unfinished download (staging file), not content"
+    else:
+        return None
+    return ImportResult(
+        status="skipped", skip_reason=SkipReason.invalid_image, error=error,
+    )
+
+
 def _safe_ext(path: Path) -> str:
     """Conservatively extract a file extension for PostAttachment.ext
     (varchar(32)). Thin wrapper over the shared `utils.paths.safe_ext` (kept for
@@ -291,6 +308,44 @@ class Importer:
             sp.rollback()
             return self.session.execute(stmt).scalar_one()
 
+    def _store_new_record(self, record: ImageRecord) -> ImageRecord | None:
+        """Insert `record`, or return the row that already holds its bytes.
+
+        The sha256 lookup before an insert can lose a race: two copies of one
+        picture in different folders, imported side by side by two workers,
+        both find no row, and the unique index refuses the second insert. Only
+        that insert is undone (a savepoint), so the session stays usable and
+        the caller files its file as a duplicate of the winner. None means
+        `record` was stored."""
+        sp = self.session.begin_nested()
+        try:
+            self.session.add(record)
+            self.session.flush()
+            sp.commit()
+            return None
+        except IntegrityError:
+            sp.rollback()
+            winner = self.session.execute(
+                select(ImageRecord).where(ImageRecord.sha256 == record.sha256)
+            ).scalar_one_or_none()
+            if winner is None:
+                raise
+            return winner
+
+    def _file_as_duplicate(
+        self, existing: ImageRecord, path: Path, artist: Artist | None,
+        explicit_source: Source | None,
+    ) -> ImportResult:
+        """A byte-identical copy of `existing`: link the copy's post to the
+        image (enrich-on-duplicate), so a picture posted twice shows on both
+        posts, and report the skip."""
+        self._apply_sidecar(existing, path, artist, explicit_source=explicit_source)
+        self.session.commit()
+        return ImportResult(
+            status="skipped", skip_reason=SkipReason.duplicate_hash,
+            image_id=existing.id, error="sha256 already present",
+        )
+
     def _find_or_create_source(
         self, *, artist_id: int, platform: str, url: str,
     ) -> Source:
@@ -410,11 +465,8 @@ class Importer:
         media members (one Post via the archive-adjacent sidecar) and
         preserve the archive itself. Other non-media → PostAttachment.
         Nothing is skipped for being non-media (FC-2d-iii)."""
-        if source.suffix.lower() == ".json":
-            return ImportResult(
-                status="skipped", skip_reason=SkipReason.invalid_image,
-                error="sidecar json is metadata, not content",
-            )
+        if (refused := _not_content(source)) is not None:
+            return refused
         if is_archive(source):
             return self._import_archive(source)
         if not is_supported(source):
@@ -564,6 +616,9 @@ class Importer:
 
         artist_use = artist if artist is not None else self._resolve_artist(source)
         post = self._post_for_sidecar(source, artist_use, source_row=source_row)
+        # Committed before extraction, so a member that fails (and is rolled
+        # back on its own) can never take the archive's post with it.
+        self.session.commit()
         member_ids: list[int] = []
         # Every member image touched (new + superseded + deduped), so the
         # from_attachment_id stamp below covers files that already existed in the
@@ -690,7 +745,15 @@ class Importer:
                             member_record_ids.add(res.image_id)
                     else:
                         counts["failed"] += 1
+        except SoftTimeLimitExceeded:
+            # The task's time budget is spent: stop here so the task marks
+            # its row failed, rather than carrying on until the hard kill.
+            raise
         except Exception as exc:  # noqa: BLE001 — defensive per level; keep going
+            # Each member commits on its own, so this undoes only the one in
+            # progress; without it the next query fails on the dead transaction
+            # and the archive is never stored.
+            self.session.rollback()
             log.warning(
                 "archive extraction failed for %s (depth %d): %s",
                 archive_path.name, depth, exc,
@@ -871,18 +934,8 @@ class Importer:
         existing = self.session.execute(existing_stmt).scalar_one_or_none()
         if existing:
             if not self.deep:
-                # Enrich-on-duplicate (parity with attach_in_place): a re-scanned
-                # file that is a byte-dup of an existing image still links its
-                # post via _apply_sidecar, so a cross-posted image shows on every
-                # post.
-                self._apply_sidecar(
-                    existing, attribution_path, path_artist,
-                    explicit_source=explicit_source,
-                )
-                self.session.commit()
-                return ImportResult(
-                    status="skipped", skip_reason=SkipReason.duplicate_hash,
-                    image_id=existing.id, error="sha256 already present",
+                return self._file_as_duplicate(
+                    existing, attribution_path, path_artist, explicit_source,
                 )
             return self._deep_rederive(existing, source, attribution_path)
 
@@ -968,8 +1021,14 @@ class Importer:
             origin="imported_filesystem",
             integrity_status="unknown",
         )
-        self.session.add(record)
-        self.session.flush()
+        if (winner := self._store_new_record(record)) is not None:
+            # The copy just written is a stray unless it is the winner's own
+            # file (the same source imported twice lands on the same path).
+            if Path(winner.path) != dest:
+                dest.unlink(missing_ok=True)
+            return self._file_as_duplicate(
+                winner, attribution_path, path_artist, explicit_source,
+            )
         self._phash_cache_append(phash, width, height, record.id)
 
         # Folder→artist (path_artist resolved up-front above); bind it to the
@@ -1219,11 +1278,8 @@ class Importer:
             caller may delete the on-disk original (mirrors duplicate_hash)
           - failed → file untouched; caller decides
         """
-        if path.suffix.lower() == ".json":
-            return ImportResult(
-                status="skipped", skip_reason=SkipReason.invalid_image,
-                error="sidecar json is metadata, not content",
-            )
+        if (refused := _not_content(path)) is not None:
+            return refused
         if is_archive(path):
             return self._import_archive(
                 path, artist=artist, source_row=source,
@@ -1300,12 +1356,7 @@ class Importer:
             # only sets it when NULL. Without this the new post is left with no
             # image AND (if its other content also deduped) no attachment, i.e. a
             # bare shell — operator-flagged 2026-06-08 (1589 empty Anduo posts).
-            self._apply_sidecar(existing, path, artist, explicit_source=source)
-            self.session.commit()
-            return ImportResult(
-                status="skipped", skip_reason=SkipReason.duplicate_hash,
-                image_id=existing.id, error="sha256 already present",
-            )
+            return self._file_as_duplicate(existing, path, artist, source)
 
         # phash dedup + supersede
         phash = None
@@ -1385,8 +1436,8 @@ class Importer:
         )
         if artist is not None:
             record.artist_id = artist.id
-        self.session.add(record)
-        self.session.flush()
+        if (winner := self._store_new_record(record)) is not None:
+            return self._file_as_duplicate(winner, path, artist, source)
         self._phash_cache_append(phash, width, height, record.id)
 
         # Sidecar provenance (best-effort). When `source` is passed, link
@@ -1401,6 +1452,51 @@ class Importer:
         self.session.commit()
         return ImportResult(status="imported", image_id=record.id)
 
+    def discard_after_attach(self, path: Path, result: ImportResult) -> bool:
+        """Delete a downloaded file that `attach_in_place` has finished with,
+        when keeping it would only leave a second copy or a rejected file on
+        disk. Returns True when the file was removed. Both download paths (a
+        subscription walk's import step and the external-link worker) apply
+        this one policy:
+
+        - attached: the attachments store holds the canonical copy.
+        - imported or superseded ARCHIVE: its new images are in the library and
+          the archive itself is in the attachments store.
+        - duplicate skip: the library already holds the content.
+        - soft skip (too small, too transparent, single colour, not a readable
+          image): the import filters rejected it. A file left on disk with no
+          record is picked up by the next walk and imported again; the seen
+          ledger is what stops it being downloaded again.
+        - failed: the archive probe crashed, and a retry would crash again.
+
+        An imported or superseded media file is kept: it IS the record's file.
+        So is any path an ImageRecord points at, whatever the status, because a
+        re-fetch can write identical bytes over a record's own file. A staging
+        file is kept too: it may be a download still being written, and the
+        temp-file sweep removes it once it is old enough to be abandoned."""
+        if is_temp_staging_file(path):
+            return False
+        if result.status in ("imported", "superseded"):
+            redundant = is_archive(path)
+        else:
+            redundant = result.status in ("attached", "skipped", "failed")
+        if not redundant:
+            return False
+        owned = self.session.execute(
+            select(ImageRecord.id).where(
+                ImageRecord.path.in_({str(path), str(path.resolve())})
+            ).limit(1)
+        ).first()
+        if owned is not None:
+            log.info("keeping %s: it is image %s's file", path.name, owned.id)
+            return False
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            log.warning("could not remove %s: %s", path, exc)
+            return False
+        return True
+
     def _upsert_artist(self, name: str) -> Artist:
         slug = slugify(name)
         artist = self.session.execute(

backend/app/services/library_scan.py

@@ -0,0 +1,181 @@
+"""Files in the artists' folders that the library has no record of.
+
+A download writes its files into the artist's folder and imports them in a
+later step. A run that stops between the two (a restart, a time limit) leaves
+complete files on disk that no image or attachment points at, and a walk that
+has already marked them seen never comes back for them. `find_unimported`
+lists those files; `queue_unimported` turns the same list into an import batch
+that attaches each file where it lies (`scan_mode="library"`), so a file the
+library already holds, or one the import filters reject, is removed instead.
+
+Only files under a folder named for an existing artist (matched by slug, so a
+differently-cased folder still matches) are considered, and only images,
+videos and archives. Files changed in the last day are left for the download
+that may still be writing them.
+"""
+from __future__ import annotations
+
+import os
+import stat
+import time
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..models import Artist, ImageRecord, ImportBatch, ImportTask, PostAttachment, Source
+from ..utils.slug import slugify
+from ..utils.staging import is_temp_staging_file
+from .archive_extractor import is_archive
+from .importer import is_supported
+
+# Top-level folders that hold the library's own stores, not an artist's files.
+_STORE_DIRS = frozenset({"thumbs", "attachments", "cookies", "secrets"})
+MIN_AGE_SECONDS = 24 * 3600
+_ACTIVE_TASK_STATUSES = ("pending", "queued", "processing")
+_SAMPLES_PER_ARTIST = 3
+_ARTISTS_LISTED = 50
+
+
+@dataclass(frozen=True)
+class Unimported:
+    path: Path
+    artist_slug: str
+    task_type: str  # "media" or "archive", as ImportTask.task_type
+    size: int
+
+
+def _referenced_paths(session: Session) -> set[str]:
+    paths: set[str] = set()
+    for p, thumb in session.execute(select(ImageRecord.path, ImageRecord.thumbnail_path)):
+        paths.add(p)
+        if thumb:
+            paths.add(thumb)
+    paths.update(session.execute(select(PostAttachment.path)).scalars())
+    paths.update(session.execute(
+        select(ImportTask.source_path).where(ImportTask.status.in_(_ACTIVE_TASK_STATUSES))
+    ).scalars())
+    return paths
+
+
+def find_unimported(
+    session: Session, images_root: Path, *, now: float | None = None,
+) -> tuple[list[Unimported], dict]:
+    """Walk the artists' folders and return (files to import, summary).
+
+    The summary counts what was found and what was passed over, and lists the
+    artists with the most to import (bytes first) with a few sample paths each:
+        {"files", "bytes", "archives", "artists": [{slug, files, bytes,
+         samples}], "recent", "not_media", "no_artist"}"""
+    now = time.time() if now is None else now
+    referenced = _referenced_paths(session)
+    slugs = set(session.execute(select(Artist.slug)).scalars())
+    found: list[Unimported] = []
+    passed = {"recent": 0, "not_media": 0, "no_artist": 0}
+    root = Path(images_root)
+    for top in sorted(os.listdir(root)):
+        if top in _STORE_DIRS or top.startswith(("_", ".")):
+            continue
+        top_dir = root / top
+        if not top_dir.is_dir():
+            continue
+        slug = slugify(top)
+        known = slug in slugs
+        for dirpath, dirnames, filenames in os.walk(top_dir):
+            dirnames[:] = sorted(d for d in dirnames if not d.startswith("."))
+            for name in sorted(filenames):
+                path = Path(dirpath) / name
+                if (
+                    name.startswith(".") or path.suffix.lower() == ".json"
+                    or is_temp_staging_file(path)
+                ):
+                    continue
+                if str(path) in referenced:
+                    continue
+                try:
+                    st = path.lstat()
+                except OSError:
+                    continue
+                if not stat.S_ISREG(st.st_mode):
+                    continue
+                kind = "archive" if is_archive(path) else ("media" if is_supported(path) else None)
+                if kind is None:
+                    passed["not_media"] += 1
+                elif now - st.st_mtime < MIN_AGE_SECONDS:
+                    passed["recent"] += 1
+                elif not known:
+                    passed["no_artist"] += 1
+                else:
+                    found.append(Unimported(path, slug, kind, st.st_size))
+
+    per_artist: dict[str, dict] = defaultdict(lambda: {"files": 0, "bytes": 0, "samples": []})
+    for u in found:
+        a = per_artist[u.artist_slug]
+        a["files"] += 1
+        a["bytes"] += u.size
+        if len(a["samples"]) < _SAMPLES_PER_ARTIST:
+            a["samples"].append(str(u.path.relative_to(root)))
+    artists = sorted(
+        ({"slug": s, **v} for s, v in per_artist.items()), key=lambda a: -a["bytes"],
+    )[:_ARTISTS_LISTED]
+    summary = {
+        "files": len(found),
+        "bytes": sum(u.size for u in found),
+        "archives": sum(1 for u in found if u.task_type == "archive"),
+        "artists": artists,
+        **passed,
+    }
+    return found, summary
+
+
+def queue_unimported(
+    session: Session, images_root: Path, *, triggered_by: str = "manual",
+) -> dict:
+    """Create a `library` import batch holding every file `find_unimported`
+    lists, and queue it. Returns the same summary plus `batch_id` (None when
+    there was nothing to import)."""
+    from ..tasks.import_file import enqueue_import  # tasks import services
+
+    found, summary = find_unimported(session, images_root)
+    summary["batch_id"] = None
+    if not found:
+        return summary
+    batch = ImportBatch(
+        triggered_by=triggered_by, source_path=str(images_root),
+        scan_mode="library", status="running", total_files=len(found),
+    )
+    session.add(batch)
+    session.flush()
+    tasks = [
+        ImportTask(
+            batch_id=batch.id, source_path=str(u.path), task_type=u.task_type,
+            status="queued", size_bytes=u.size,
+        )
+        for u in found
+    ]
+    session.add_all(tasks)
+    session.commit()
+    for t in tasks:
+        enqueue_import(t.id, t.task_type)
+    summary["batch_id"] = batch.id
+    return summary
+
+
+def folder_owner(
+    session: Session, path: Path, images_root: Path,
+) -> tuple[Artist | None, Source | None]:
+    """The artist whose folder holds `path`, and that artist's source for the
+    platform folder below it when there is exactly one (a Discord artist has a
+    source per channel, so there the post's sidecar decides)."""
+    parts = Path(path).relative_to(images_root).parts
+    artist = session.execute(
+        select(Artist).where(Artist.slug == slugify(parts[0]))
+    ).scalar_one_or_none()
+    if artist is None or len(parts) < 3:
+        return artist, None
+    sources = session.execute(
+        select(Source).where(Source.artist_id == artist.id, Source.platform == parts[1])
+    ).scalars().all()
+    return artist, (sources[0] if len(sources) == 1 else None)

backend/app/tasks/admin.py

@@ -74,6 +74,12 @@ def prune_missing_file_records_task(self) -> dict:
     thumbs: list[str] = []
     last_id = 0
     with SessionLocal() as session:
+        # While a restore is fetching the library back, files are missing
+        # because they haven't arrived yet, not because they are gone.
+        from .backup import restore_going
+        if restore_going(session):
+            return {"checked": 0, "missing": 0, "deleted": 0,
+                    "skipped": "a restore is fetching the library's files"}
         while True:
             rows = session.execute(
                 select(ImageRecord.id, ImageRecord.path, ImageRecord.thumbnail_path)
@@ -459,3 +465,29 @@ def reclaim_orphaned_attachments_task(self, dry_run: bool = True) -> dict:
         return cleanup_service.reclaim_orphaned_attachments(
             session, images_root=IMAGES_ROOT, dry_run=dry_run,
         )
+
+
+@celery.task(
+    name="backend.app.tasks.admin.import_unimported_files_task",
+    bind=True,
+    autoretry_for=(OperationalError, DBAPIError),
+    retry_backoff=15, retry_backoff_max=180, max_retries=1,
+    # One walk of the artists' folders: a stat per file, so minutes on a large
+    # library on network storage. The limits are the backstop for a wedged
+    # filesystem, not the expected exit.
+    soft_time_limit=1800, time_limit=2400,  # 30 min / 40 min
+)
+def import_unimported_files_task(self, dry_run: bool = True) -> dict:
+    """Find files in the artists' folders that the library has no record of.
+    dry_run (the default) returns what was found, per artist, without changing
+    anything; apply queues them as a `library` import batch, which attaches each
+    file where it lies and removes the ones the library already holds or the
+    import filters reject."""
+    from ..services import library_scan
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        if dry_run:
+            _found, summary = library_scan.find_unimported(session, IMAGES_ROOT)
+            return {**summary, "batch_id": None}
+        return library_scan.queue_unimported(session, IMAGES_ROOT)

backend/app/tasks/backup.py

@@ -8,17 +8,26 @@ BackupRun.
 from __future__ import annotations
 
 import logging
-from datetime import UTC, datetime
+import time
+import uuid
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 from celery.exceptions import SoftTimeLimitExceeded
-from sqlalchemy import select
+from sqlalchemy import select, text, update
 from sqlalchemy.exc import DBAPIError, OperationalError
 
 from ..celery_app import celery
 from ..config import get_config
 from ..models import BackupRun, ImportSettings
-from ..services import backup_service
+from ..services import (
+    backup_destination,
+    backup_media,
+    backup_restore,
+    backup_s3,
+    backup_service,
+)
+from ._sync_engine import get_sync_engine
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
 log = logging.getLogger(__name__)
@@ -49,11 +58,19 @@ def _mark_failed(session, row: BackupRun, exc: BaseException) -> None:
 )
 def backup_db_task(self, *, tag: str | None = None,
                    triggered_by: str = "manual") -> dict:
-    """Create one DB backup. Returns {'backup_run_id': N}."""
+    """Create one DB backup. Returns {'backup_run_id': N}.
+
+    With an off-site destination set up, the dump streams to that bucket and
+    nothing is written here; the row's manifest says where it went
+    (`offsite`: endpoint, bucket, key). Without one, the dump is written to
+    /images/_backups."""
     SessionLocal = _sync_session_factory()
     cfg = get_config()
     now = datetime.now(UTC)
     with SessionLocal() as session:
+        # A restore replaces the database this would dump.
+        if restore_going(session):
+            return {"skipped": "a restore is going"}
         row = BackupRun(
             kind="db", status="running", tag=tag,
             triggered_by=triggered_by, started_at=now, manifest={},
@@ -64,10 +81,19 @@ def backup_db_task(self, *, tag: str | None = None,
         run_id = row.id
 
     try:
-        result = backup_service.backup_db(
-            db_url=cfg.database_url_sync, images_root=IMAGES_ROOT,
-            tag=tag, triggered_by=triggered_by,
-        )
+        with SessionLocal() as session:
+            settings = ImportSettings.load_sync(session)
+            target = backup_destination.saved_target(settings)
+            limit_mbps = settings.backup_upload_limit_mbps
+        if target is not None:
+            result = backup_service.backup_db_offsite(
+                db_url=cfg.database_url_sync, target=target, limit_mbps=limit_mbps,
+            )
+        else:
+            result = backup_service.backup_db(
+                db_url=cfg.database_url_sync, images_root=IMAGES_ROOT,
+                tag=tag, triggered_by=triggered_by,
+            )
     except (SoftTimeLimitExceeded, Exception) as exc:
         with SessionLocal() as session:
             row = session.get(BackupRun, run_id)
@@ -79,12 +105,23 @@ def backup_db_task(self, *, tag: str | None = None,
         row = session.get(BackupRun, run_id)
         row.status = "ok"
         row.finished_at = datetime.now(UTC)
-        row.sql_path = result["sql_path"]
         row.size_bytes = result["size_bytes"]
-        row.manifest = {
-            "manifest_path": result["manifest_path"],
-            "ts": result["ts"],
-        }
+        if target is not None:
+            row.manifest = {
+                "ts": result["ts"],
+                "offsite": {
+                    "endpoint": result["endpoint"],
+                    "bucket": result["bucket"],
+                    "key": result["key"],
+                    "parts": result["parts"],
+                },
+            }
+        else:
+            row.sql_path = result["sql_path"]
+            row.manifest = {
+                "manifest_path": result["manifest_path"],
+                "ts": result["ts"],
+            }
         session.commit()
     return {"backup_run_id": run_id}
 
@@ -242,7 +279,10 @@ def restore_images_task(self, *, source_backup_run_id: int) -> dict:
 def prune_backups() -> dict:
     """Daily Beat. Per-kind retention from ImportSettings.
 
-    Returns {"db_deleted": N, "images_deleted": M, "files_unlinked": K}.
+    Returns {"db_deleted": N, "images_deleted": M, "media_deleted": L,
+    "restore_deleted": R, "files_unlinked": K}. Media and restore runs leave
+    no files here; only their history is trimmed, to the latest
+    MEDIA_RUNS_KEPT and RESTORE_RUNS_KEPT.
     Tagged rows (tag IS NOT NULL) are never pruned.
     Status='running' / 'restoring' rows are never pruned — the
     recover_stalled_backup_runs sweep flips truly-stuck ones to
@@ -251,18 +291,21 @@ def prune_backups() -> dict:
     Audit 2026-06-02 added the dedicated sweep.)
     """
     SessionLocal = _sync_session_factory()
-    counts = {"db_deleted": 0, "images_deleted": 0, "files_unlinked": 0}
+    counts = {"db_deleted": 0, "images_deleted": 0, "media_deleted": 0,
+              "restore_deleted": 0, "files_unlinked": 0}
     with SessionLocal() as session:
         s = ImportSettings.load_sync(session)
         for kind, keep in (
             ("db", s.backup_db_keep_last_n),
             ("images", s.backup_images_keep_last_n),
+            ("media", MEDIA_RUNS_KEPT),
+            ("restore", RESTORE_RUNS_KEPT),
         ):
             candidates = session.execute(
                 select(BackupRun)
                 .where(BackupRun.kind == kind)
                 .where(BackupRun.tag.is_(None))
-                .where(BackupRun.status.in_(["ok", "error"]))
+                .where(BackupRun.status.in_(["ok", "error", "restored"]))
                 .order_by(BackupRun.started_at.desc())
                 .offset(keep)
             ).scalars().all()
@@ -300,4 +343,552 @@ def backup_db_nightly() -> dict:
     if now_hour != configured_hour:
         return {"skipped": f"hour={now_hour} != configured={configured_hour}"}
     res = backup_db_task.delay(triggered_by="nightly")
-    return {"dispatched": res.id}
+    out = {"dispatched": res.id}
+    # With an off-site destination, the night's backup is the whole library:
+    # the database dump, then any images and attachments not yet in the bucket.
+    # Both run on the long-maintenance lane, one after the other.
+    with SessionLocal() as session:
+        try:
+            offsite = backup_destination.saved_target(ImportSettings.load_sync(session))
+        except Exception:  # noqa: BLE001 — the media run reports it itself
+            offsite = True
+    if offsite is not None:
+        out["media_dispatched"] = backup_media_task.delay(triggered_by="nightly").id
+    return out
+
+
+# ── Off-site copy of the library's files ─────────────────────────────────────
+
+# Each task invocation sends files for this long, then queues the next chunk
+# of the same run, so other long-maintenance jobs get their turn in between.
+MEDIA_CHUNK_SECONDS = 45 * 60
+MEDIA_RUNS_KEPT = 60
+# A failed file is listed on the run, up to this many; the count covers all.
+MEDIA_FAILURES_LISTED = 20
+
+
+def _offsite_manifest(target) -> dict:
+    return {"endpoint": target.endpoint, "bucket": target.bucket,
+            "key": backup_media.PREFIX}
+
+
+# ── One chunk at a time ──────────────────────────────────────────────────────
+#
+# A media backup and a restore's file phase run as a chain of chunks, each
+# queuing the next. The chunk carrying a run writes its token to the run's
+# manifest as "chunk", and hands that token to the chunk it queues as `after`.
+# A chunk queued to resume a run after a restart carries `resume` instead and
+# takes the run over. Any other message is stale (a killed chunk's own message
+# delivered again, say) and is dropped, so a run never goes on twice and the
+# chain never doubles.
+
+
+def _chunk_token(task) -> str:
+    return task.request.id or uuid.uuid4().hex
+
+
+def _claim_run(session, run_id: int, status: str, token: str, *, after: str | None,
+               resume: bool) -> str | None:
+    """Take the run for this chunk. Returns None when taken, or why not."""
+    row = session.get(BackupRun, run_id, with_for_update=True)
+    if row is None or row.status != status:
+        session.rollback()
+        return "the run is no longer going"
+    held = (row.manifest or {}).get("chunk")
+    if not resume and held is not None and held != after:
+        session.rollback()
+        return "another chunk carries this run on"
+    row.manifest = {**(row.manifest or {}), "chunk": token}
+    session.commit()
+    return None
+
+
+def _still_ours(session, run_id: int, token: str) -> bool:
+    """Lock the run's row and say whether this chunk still carries it. A chunk
+    that was taken over stops at its next file rather than write over the
+    newer chunk's place; on False the transaction is already rolled back."""
+    held = session.execute(
+        select(BackupRun.manifest).where(BackupRun.id == run_id).with_for_update()
+    ).scalar_one_or_none()
+    if (held or {}).get("chunk") == token:
+        return True
+    session.rollback()
+    return False
+
+
+def resume_offsite_runs() -> dict:
+    """Queue the next chunk of every off-site run a restart cut short: a media
+    backup still running, and a restore fetching its files. Called when the
+    long-maintenance lane starts, where those chunks run, so none of theirs is
+    alive then; the queued chunk carries on from the run's saved place. A
+    restore stopped while loading its database isn't resumed: the stall sweep
+    ends it, and the screen offers the restore again."""
+    with _sync_session_factory()() as session:
+        media = list(session.execute(
+            select(BackupRun.id).where(BackupRun.kind == "media")
+            .where(BackupRun.status == "running")
+        ).scalars())
+        restores = [
+            r.id for r in session.execute(
+                select(BackupRun).where(BackupRun.kind == "restore")
+                .where(BackupRun.status == "restoring")
+            ).scalars()
+            if (r.manifest or {}).get("phase") == "files"
+        ]
+    for run_id in media:
+        backup_media_task.delay(run_id=run_id, resume=True)
+    for run_id in restores:
+        restore_offsite_task.delay(run_id=run_id, resume=True)
+    if media or restores:
+        log.info("resumed off-site runs after a restart: media %s, restore %s",
+                 media, restores)
+    return {"media": media, "restore": restores}
+
+
+@celery.task(
+    name="backend.app.tasks.backup.backup_media_task",
+    bind=True,
+    autoretry_for=(OperationalError, DBAPIError),
+    retry_backoff=30, retry_backoff_max=300, max_retries=2,
+    # A chunk stops starting files after MEDIA_CHUNK_SECONDS; the limits leave
+    # room for the file in flight, a multi-gigabyte archive at a low upload
+    # limit included.
+    soft_time_limit=21600, time_limit=23400,
+)
+def backup_media_task(self, *, run_id: int | None = None, triggered_by: str = "manual",
+                      after: str | None = None, resume: bool = False) -> dict:
+    """Send the library's images and attachments that aren't in the off-site
+    bucket yet, one chunk of a run. Called without `run_id` it starts a run
+    (unless one is already going); each chunk queues the next until nothing is
+    left, and a restart resumes the run where it stopped. A file that can't be
+    sent is listed on the run and tried again by the next run. Returns
+    {'backup_run_id': N, ...}."""
+    SessionLocal = _sync_session_factory()
+    now = datetime.now(UTC)
+    token = _chunk_token(self)
+    with SessionLocal() as session:
+        if run_id is None:
+            going = session.execute(
+                select(BackupRun.id).where(BackupRun.kind == "media")
+                .where(BackupRun.status == "running").limit(1)
+            ).scalar_one_or_none()
+            if going is not None:
+                return {"backup_run_id": going, "skipped": "a media backup is already running"}
+            # During a restore the library's files are still arriving.
+            if restore_going(session):
+                return {"skipped": "a restore is going"}
+            row = BackupRun(kind="media", status="running", triggered_by=triggered_by,
+                            started_at=now, last_progress_at=now, size_bytes=0,
+                            manifest={"sent": 0, "failed": 0, "failures": [], "cursor": "",
+                                      "chunk": token})
+            session.add(row)
+            session.commit()
+            run_id = row.id
+        else:
+            why = _claim_run(session, run_id, "running", token, after=after, resume=resume)
+            if why:
+                return {"backup_run_id": run_id, "skipped": why}
+
+    try:
+        with SessionLocal() as session:
+            settings = ImportSettings.load_sync(session)
+            target = backup_destination.saved_target(settings)
+            limit_mbps = settings.backup_upload_limit_mbps
+        if target is None:
+            raise backup_s3.S3Error("No off-site destination is set up.")
+        more = _send_media_chunk(SessionLocal, run_id, target, backup_s3.Pacer(limit_mbps),
+                                 token)
+    except (SoftTimeLimitExceeded, Exception) as exc:
+        with SessionLocal() as session:
+            row = session.get(BackupRun, run_id)
+            if row is not None:
+                _mark_failed(session, row, exc)
+        raise
+
+    if more is None:
+        return {"backup_run_id": run_id, "skipped": "another chunk took the run over"}
+    if more:
+        backup_media_task.delay(run_id=run_id, after=token)
+        return {"backup_run_id": run_id, "continues": True}
+    with SessionLocal() as session:
+        row = session.get(BackupRun, run_id)
+        m = dict(row.manifest or {})
+        row.status = "ok"
+        row.finished_at = datetime.now(UTC)
+        if m.get("failed"):
+            first = (m.get("failures") or [{}])[0]
+            row.error = (f"{m['failed']} file(s) weren't sent; the next run tries them again. "
+                         f"First: {first.get('path')}: {first.get('error')}")[:2000]
+        session.commit()
+    return {"backup_run_id": run_id, "continues": False}
+
+
+def _send_media_chunk(SessionLocal, run_id: int, target, pacer, token: str) -> bool | None:
+    """Send files until the chunk's time is up or none are left. Progress is
+    committed after every file, so a chunk that dies loses at most the file
+    in flight. Returns True when files remain for another chunk, and None when
+    another chunk has taken the run over."""
+    tid = backup_media.target_id(target)
+    deadline = time.monotonic() + MEDIA_CHUNK_SECONDS
+    with SessionLocal() as session:
+        row = session.get(BackupRun, run_id)
+        m = dict(row.manifest or {})
+        m["offsite"] = _offsite_manifest(target)
+        cursor = m.get("cursor") or ""
+        while True:
+            batch = backup_media.pending(session, tid, after=cursor)
+            # End the read before any upload starts: a transaction left open
+            # across a long transfer holds back vacuum for its whole length.
+            session.commit()
+            if not batch:
+                if not _still_ours(session, run_id, token):
+                    return None
+                m["cursor"] = cursor
+                row.manifest = dict(m)
+                row.last_progress_at = datetime.now(UTC)
+                session.commit()
+                return False
+            for blob in batch:
+                if time.monotonic() > deadline:
+                    if not _still_ours(session, run_id, token):
+                        return None
+                    m["cursor"] = cursor
+                    row.manifest = dict(m)
+                    session.commit()
+                    return True
+                key = None
+                try:
+                    key = backup_media.send(target, blob, IMAGES_ROOT, pacer)
+                except (backup_s3.S3Error, OSError) as exc:
+                    m["failed"] = m.get("failed", 0) + 1
+                    if len(m.get("failures") or []) < MEDIA_FAILURES_LISTED:
+                        m["failures"] = [*(m.get("failures") or []),
+                                         {"path": blob.path, "error": str(exc)[:300]}]
+                if not _still_ours(session, run_id, token):
+                    return None
+                if key is not None:
+                    backup_media.record(session, tid, [(blob, key)])
+                    m["sent"] = m.get("sent", 0) + 1
+                    row.size_bytes = (row.size_bytes or 0) + blob.size_bytes
+                cursor = blob.sha256
+                m["cursor"] = cursor
+                row.manifest = dict(m)
+                row.last_progress_at = datetime.now(UTC)
+                session.commit()
+
+
+@celery.task(
+    name="backend.app.tasks.backup.reconcile_media_backup",
+    soft_time_limit=1800, time_limit=2100,
+)
+def reconcile_media_backup() -> dict:
+    """Weekly Beat. Compare what the off-site bucket holds under `media/` with
+    what FabledCurator believes it sent: a missing object is sent again by
+    the next run, and an object already there is not sent twice. Skipped
+    while a media run is going, and when no destination is set up."""
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        target = backup_destination.saved_target(ImportSettings.load_sync(session))
+        if target is None:
+            return {"skipped": "no destination"}
+        going = session.execute(
+            select(BackupRun.id).where(BackupRun.kind == "media")
+            .where(BackupRun.status == "running").limit(1)
+        ).scalar_one_or_none()
+        if going is not None:
+            return {"skipped": "a media backup is running"}
+        return backup_media.reconcile(session, target)
+
+
+# ── Restoring from the off-site bucket ───────────────────────────────────────
+
+# The file phase fetches for this long per task, then queues its next chunk,
+# like a media run.
+RESTORE_CHUNK_SECONDS = 45 * 60
+RESTORE_RUNS_KEPT = 20
+RESTORE_FAILURES_LISTED = 20
+# A run over files already on disk notes its place this often, not per file.
+_RESTORE_NOTE_SECONDS = 5
+_RESTORE_COUNTS = ("restored", "copied", "present", "missing", "failed")
+
+
+def backup_busy(session) -> str | None:
+    """Why a backup or a restore can't start right now, or None."""
+    row = session.execute(
+        select(BackupRun.kind).where(BackupRun.status.in_(["running", "restoring"])).limit(1)
+    ).first()
+    if row is None:
+        return None
+    return "a restore is going" if row.kind == "restore" else f"a {row.kind} backup is running"
+
+
+def restore_going(session) -> bool:
+    return session.execute(
+        select(BackupRun.id).where(BackupRun.kind == "restore")
+        .where(BackupRun.status == "restoring").limit(1)
+    ).first() is not None
+
+
+def _library_is_empty(session) -> bool:
+    return session.execute(text(
+        "SELECT NOT EXISTS (SELECT 1 FROM image_record) "
+        "AND NOT EXISTS (SELECT 1 FROM post_attachment)"
+    )).scalar()
+
+
+def _note(session, row: BackupRun, m: dict, token: str | None = None) -> bool:
+    """Write the run's progress. Given a chunk's token, writes only while that
+    chunk still carries the run, and returns False when it doesn't."""
+    if token is not None and not _still_ours(session, row.id, token):
+        return False
+    row.manifest = dict(m)
+    row.last_progress_at = datetime.now(UTC)
+    session.commit()
+    return True
+
+
+@celery.task(
+    name="backend.app.tasks.backup.restore_offsite_task",
+    bind=True,
+    max_retries=0,  # a half-applied restore is never retried on its own
+    soft_time_limit=21600, time_limit=23400,
+)
+def restore_offsite_task(self, *, dump_key: str | None = None, files_only: bool = False,
+                         run_id: int | None = None, after: str | None = None,
+                         resume: bool = False) -> dict:
+    """Restore this install from the off-site bucket, one chunk at a time.
+
+    Started without `run_id`, it replaces the database with the dump at
+    `dump_key` (the newest when None), then fetches every library file the
+    restored rows name. With `files_only`, the database stays and only the
+    missing files are fetched, which also repairs a library that lost files.
+    Each chunk queues the next, and a restart resumes the file phase where it
+    stopped; the run's row counts files restored from the bucket, copied from
+    a duplicate already on disk, already present, missing from the bucket,
+    and failed. Returns {'backup_run_id': N, ...}."""
+    SessionLocal = _sync_session_factory()
+    token = _chunk_token(self)
+    if run_id is not None:
+        return _restore_files(SessionLocal, run_id, token, after=after, resume=resume)
+
+    now = datetime.now(UTC)
+    with SessionLocal() as session:
+        busy = backup_busy(session)
+        if busy:
+            return {"skipped": busy}
+        settings = ImportSettings.load_sync(session)
+        limit_mbps = settings.backup_upload_limit_mbps
+        row = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                        started_at=now, last_progress_at=now, size_bytes=0,
+                        manifest={"phase": "files" if files_only else "database",
+                                  "cursor": "", "failures": [],
+                                  **dict.fromkeys(_RESTORE_COUNTS, 0)})
+        session.add(row)
+        session.commit()
+        run_id = row.id
+        try:
+            target = backup_destination.saved_target(settings)
+            if target is None:
+                raise backup_s3.S3Error("No off-site destination is set up.")
+        except backup_s3.S3Error as exc:
+            _mark_failed(session, row, exc)
+            raise
+        row.manifest = {**row.manifest, "offsite": _offsite_manifest(target)}
+        session.commit()
+
+    if files_only:
+        return _restore_files(SessionLocal, run_id, token, after=None, resume=False)
+    run_id = _restore_database(SessionLocal, run_id, target, limit_mbps, dump_key)
+    # The files follow as chunks of their own, on the worker.
+    restore_offsite_task.delay(run_id=run_id)
+    return {"backup_run_id": run_id, "continues": True}
+
+
+def _restore_database(SessionLocal, run_id: int, target, limit_mbps, dump_key) -> int:
+    """Replace the database with a dump from the bucket. Returns the run's id
+    in the restored database, where its row is written again."""
+    cfg = get_config()
+    pacer = backup_s3.Pacer(limit_mbps)
+    staged = None
+    try:
+        dump = backup_restore.find_dump(target, dump_key)
+        with SessionLocal() as session:
+            row = session.get(BackupRun, run_id)
+            m = dict(row.manifest)
+            m["dump"] = {"key": dump.key, "ts": dump.ts, "size_bytes": dump.size_bytes}
+            # The database about to be replaced goes to the bucket first, so
+            # the restore can itself be undone. An empty one isn't worth a
+            # dump, and would sit in the list as the newest.
+            if not _library_is_empty(session):
+                session.commit()
+                saved = backup_service.backup_db_offsite(
+                    db_url=cfg.database_url_sync, target=target, limit_mbps=limit_mbps)
+                m["saved_before"] = saved["key"]
+            _note(session, row, m)
+            started_at, manifest = row.started_at, dict(m)
+        staged = backup_restore.fetch_dump(target, dump, IMAGES_ROOT / "_backups", pacer)
+    except (SoftTimeLimitExceeded, Exception) as exc:
+        if staged is not None:
+            staged.unlink(missing_ok=True)
+        with SessionLocal() as session:
+            row = session.get(BackupRun, run_id)
+            if row is not None:
+                _mark_failed(session, row, exc)
+        raise
+
+    # From here on the database is being replaced; every pooled connection
+    # still points at the tables being dropped.
+    get_sync_engine().dispose()
+    try:
+        backup_service.restore_db(db_url=cfg.database_url_sync, sql_path=staged)
+        backup_restore.migrate()
+        backup_service.end_other_connections(db_url=cfg.database_url_sync)
+    except (SoftTimeLimitExceeded, Exception) as exc:
+        _leave_empty_install(SessionLocal, cfg, target, limit_mbps, started_at, manifest, exc)
+        raise
+    finally:
+        staged.unlink(missing_ok=True)
+    get_sync_engine().dispose()
+
+    with SessionLocal() as session:
+        backup_restore.keep_destination(session, target, limit_mbps)
+        # The dump holds its own run as still going: it is the dump just
+        # restored, so it finished. Any other run going then is over.
+        dump_at = datetime.strptime(manifest["dump"]["ts"], "%Y%m%dT%H%M%SZ").replace(tzinfo=UTC)
+        own = session.execute(
+            select(BackupRun).where(BackupRun.kind == "db", BackupRun.status == "running")
+            # The name's time is truncated to the second, after the row began.
+            .where(BackupRun.started_at.between(dump_at - timedelta(minutes=2),
+                                                dump_at + timedelta(seconds=1)))
+            .order_by(BackupRun.started_at.desc()).limit(1)
+        ).scalar_one_or_none()
+        if own is not None:
+            own.status = "ok"
+            own.manifest = {"ts": manifest["dump"]["ts"], "offsite": {
+                **manifest["offsite"], "key": manifest["dump"]["key"]}}
+            own.size_bytes = manifest["dump"]["size_bytes"]
+        session.execute(
+            update(BackupRun).where(BackupRun.status.in_(["running", "restoring"]))
+            .values(status="error", finished_at=datetime.now(UTC),
+                    error="Interrupted: this run was going when the restored dump was taken.")
+        )
+        row = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                        started_at=started_at, last_progress_at=datetime.now(UTC),
+                        size_bytes=0, manifest={**manifest, "phase": "files"})
+        session.add(row)
+        session.commit()
+        return row.id
+
+
+def _leave_empty_install(SessionLocal, cfg, target, limit_mbps, started_at, manifest,
+                         exc: BaseException) -> None:
+    """After a failed load, put back an empty database at this version, so the
+    install starts and can try again, and record why it stopped."""
+    try:
+        backup_service.wipe_db(db_url=cfg.database_url_sync)
+        backup_restore.migrate()
+        backup_service.end_other_connections(db_url=cfg.database_url_sync)
+        get_sync_engine().dispose()
+        with SessionLocal() as session:
+            backup_restore.keep_destination(session, target, limit_mbps)
+            session.add(BackupRun(
+                kind="restore", status="error", triggered_by="restore",
+                started_at=started_at, finished_at=datetime.now(UTC), manifest=manifest,
+                error=(f"The restore stopped while loading the database: {exc}. "
+                       "The database is empty again; choose a dump and restore again.")[:2000],
+            ))
+            session.commit()
+    except Exception:  # noqa: BLE001 — the original failure is the one raised
+        log.exception("restore: the database couldn't be reset after a failed load")
+
+
+def _restore_files(SessionLocal, run_id: int, token: str, *, after: str | None,
+                   resume: bool) -> dict:
+    """One chunk of a restore's file phase; queues the next while files remain."""
+    with SessionLocal() as session:
+        why = _claim_run(session, run_id, "restoring", token, after=after, resume=resume)
+        if why:
+            return {"backup_run_id": run_id, "skipped": why}
+        row = session.get(BackupRun, run_id)
+        settings = ImportSettings.load_sync(session)
+        limit_mbps = settings.backup_upload_limit_mbps
+        try:
+            target = backup_destination.saved_target(settings)
+            if target is None:
+                raise backup_s3.S3Error("No off-site destination is set up.")
+        except backup_s3.S3Error as exc:
+            _mark_failed(session, row, exc)
+            raise
+    try:
+        more = _fetch_files_chunk(SessionLocal, run_id, target, backup_s3.Pacer(limit_mbps),
+                                  token)
+    except (SoftTimeLimitExceeded, Exception) as exc:
+        with SessionLocal() as session:
+            row = session.get(BackupRun, run_id)
+            if row is not None:
+                _mark_failed(session, row, exc)
+        raise
+
+    if more is None:
+        return {"backup_run_id": run_id, "skipped": "another chunk took the run over"}
+    if more:
+        restore_offsite_task.delay(run_id=run_id, after=token)
+        return {"backup_run_id": run_id, "continues": True}
+    with SessionLocal() as session:
+        row = session.get(BackupRun, run_id)
+        m = dict(row.manifest or {})
+        row.status = "restored"
+        row.finished_at = datetime.now(UTC)
+        missed = m.get("missing", 0) + m.get("failed", 0)
+        if missed:
+            first = (m.get("failures") or [{}])[0]
+            row.error = (f"{m.get('missing', 0)} file(s) aren't in the bucket and "
+                         f"{m.get('failed', 0)} couldn't be restored. "
+                         f"First: {first.get('path')}: {first.get('error')}")[:2000]
+        session.commit()
+    # Thumbnails aren't backed up: they are made again from the restored files.
+    from .thumbnail import backfill_thumbnails
+    backfill_thumbnails.delay()
+    return {"backup_run_id": run_id, "continues": False}
+
+
+def _fetch_files_chunk(SessionLocal, run_id: int, target, pacer, token: str) -> bool | None:
+    """Put library files back until the chunk's time is up or none are left.
+    Returns True when files remain for another chunk, and None when another
+    chunk has taken the run over."""
+    tid = backup_media.target_id(target)
+    deadline = time.monotonic() + RESTORE_CHUNK_SECONDS
+    with SessionLocal() as session:
+        row = session.get(BackupRun, run_id)
+        m = dict(row.manifest or {})
+        cursor = m.get("cursor") or ""
+        noted = time.monotonic()
+        while True:
+            batch = backup_restore.library_files(session, after=cursor)
+            keys = backup_restore.sent_keys(session, tid, [f.sha256 for f in batch])
+            # End the read before any download starts.
+            session.commit()
+            if not batch:
+                m["cursor"] = cursor
+                return False if _note(session, row, m, token) else None
+            for f in batch:
+                if time.monotonic() > deadline:
+                    m["cursor"] = cursor
+                    return True if _note(session, row, m, token) else None
+                try:
+                    outcome = backup_restore.restore_file(
+                        target, f, keys.get(f.sha256), IMAGES_ROOT, pacer)
+                except (backup_s3.S3Error, OSError) as exc:
+                    outcome = "missing" if isinstance(exc, backup_s3.ObjectMissing) else "failed"
+                    if len(m.get("failures") or []) < RESTORE_FAILURES_LISTED:
+                        m["failures"] = [*(m.get("failures") or []),
+                                         {"path": f.paths[0], "error": str(exc)[:300]}]
+                m[outcome] = m.get(outcome, 0) + 1
+                if outcome in ("restored", "copied"):
+                    row.size_bytes = (row.size_bytes or 0) + f.size_bytes
+                cursor = f.sha256
+                m["cursor"] = cursor
+                if outcome != "present" or time.monotonic() - noted > _RESTORE_NOTE_SECONDS:
+                    if not _note(session, row, m, token):
+                        return None
+                    noted = time.monotonic()

backend/app/tasks/external.py

@@ -24,7 +24,7 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 import redis
-from sqlalchemy import delete, select, update
+from sqlalchemy import delete, or_, select, update
 
 from ..celery_app import celery
 from ..config import get_config
@@ -32,6 +32,7 @@ from ..models import Artist, ExternalLink, ImageRecord, ImportSettings, Post, So
 from ..services.external_fetch import fetch_external
 from ..services.importer import Importer
 from ..services.thumbnailer import Thumbnailer
+from ..utils.staging import is_temp_staging_file
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
 log = logging.getLogger(__name__)
@@ -39,14 +40,20 @@ log = logging.getLogger(__name__)
 IMAGES_ROOT = Path("/images")
 
 # After this many failed attempts a link is dead-lettered (skipped by routine
-# sweeps; an operator recovery still re-attempts). Mirrors the ingester ledger.
+# sweeps; the daily recovery retries it, sparingly). Mirrors the ingester ledger.
 DEAD_LETTER_THRESHOLD = 3
 # Per-fetch read + total budgets now live in external_fetch (a short read
 # timeout fails a stalled host fast; a generous total caps a big-but-flowing
 # download). The celery soft/hard time_limit is the outer backstop above those.
 # Links enqueued per sweep — bounds the burst when a big backfill records many.
 _SWEEP_BATCH = 50
-# Dead rows older than this are pruned (retention).
+# Recovery gives a dead link one more attempt once it has been dead for
+# 2**recoveries days (1, 2, 4, 8, 16), and stops after _MAX_RECOVERIES. A host
+# outage gets several later chances; a link that can never succeed (too big to
+# import in time, a file made private) costs a handful of downloads, not three
+# a day.
+_MAX_RECOVERIES = 5
+# A link recovery has given up on is pruned this long after its last attempt.
 _RETENTION_DAYS = 30
 # Per-host serialize lock. TTL is a safety net for a worker that dies holding it
 # (normal completion/error releases it in `finally`); sized just past the fetch
@@ -54,6 +61,9 @@ _RETENTION_DAYS = 30
 # than one fetch would have taken.
 _LOCK_PREFIX = "fc:extdl_lock:"
 _LOCK_TTL = 2400
+# A link 'downloading' this long has outlived fetch_external_link's hard limit
+# (time_limit=3600), so its worker is gone and the sweep recovers it.
+_STALL_MINUTES = 65
 _SERIALIZE_COUNTDOWN = 120
 _MAX_SERIALIZE_WAITS = 30
 
@@ -106,7 +116,7 @@ def fetch_external_link(self, link_id: int, _serialize_waits: int = 0) -> dict:
                 ExternalLink.id == link_id,
                 ExternalLink.status.in_(("pending", "failed")),
             )
-            .values(status="downloading")
+            .values(status="downloading", started_at=datetime.now(UTC))
             .returning(ExternalLink.id)
         ).first()
         session.commit()
@@ -180,6 +190,9 @@ def fetch_external_link(self, link_id: int, _serialize_waits: int = 0) -> dict:
         / str(post.external_post_id) / str(link_id)
     )
     try:
+        # Clear the staging files an interrupted attempt left behind. Complete
+        # files it left stay, and are imported once this fetch succeeds.
+        _discard_partials(post_dir)
         result = fetch_external(host, url, post_dir)
         with SessionLocal() as session:
             link = session.get(ExternalLink, link_id)
@@ -190,6 +203,7 @@ def fetch_external_link(self, link_id: int, _serialize_waits: int = 0) -> dict:
                 )
                 _record_failure(link, attempts, result.error or "fetch failed")
                 session.commit()
+                _discard_partials(post_dir)
                 return {"link_id": link_id, "error": result.error}
 
             log.info(
@@ -201,7 +215,8 @@ def fetch_external_link(self, link_id: int, _serialize_waits: int = 0) -> dict:
             post = session.get(Post, link.post_id)
             artist = session.get(Artist, post.artist_id)
             source = session.get(Source, post.source_id) if post.source_id else None
-            image_ids = _route_files(session, result.files, post, platform, artist, source)
+            files = _unimported_files(session, post_dir, first=result.files)
+            image_ids = _route_files(session, files, post, platform, artist, source)
             link.status = "downloaded"
             link.last_error = None
             link.completed_at = datetime.now(UTC)
@@ -231,6 +246,7 @@ def fetch_external_link(self, link_id: int, _serialize_waits: int = 0) -> dict:
             if link is not None and link.status == "downloading":
                 _record_failure(link, attempts, f"{type(exc).__name__}: {exc}")
                 session.commit()
+        _discard_partials(post_dir)
         raise
     finally:
         if lock is not None:
@@ -287,10 +303,9 @@ def _route_files(session, files, post, platform, artist, source) -> list[int]:
                 post.id, f.name, result.status, len(ids),
             )
         elif result.status == "attached":
-            # Non-art / archive captured as a PostAttachment (copied into the
-            # store) — drop the on-disk original. An archive captured WITHOUT
-            # extracting any image carries the reason (the recurring "zip but no
-            # images" symptom, #718) — surface it loudly.
+            # Non-art, or an archive with no new images, captured as a
+            # PostAttachment. An archive captured WITHOUT extracting any image
+            # carries the reason, so the "zip but no images" case is visible.
             if result.error:
                 log.warning(
                     "extdl archive captured UNEXTRACTED: post=%s file=%s reason=%s",
@@ -298,51 +313,104 @@ def _route_files(session, files, post, platform, artist, source) -> list[int]:
                 )
             else:
                 log.info("extdl attachment captured: post=%s file=%s", post.id, f.name)
-            f.unlink(missing_ok=True)
         elif result.status == "skipped":
             reason = result.skip_reason.value if result.skip_reason else None
             log.info(
                 "extdl skipped: post=%s file=%s reason=%s", post.id, f.name, reason,
             )
-            if reason in ("duplicate_hash", "duplicate_phash"):
-                # Path-safe unlink: external files are imported IN PLACE, so `f`
-                # can BE the canonical record's backing file (same content
-                # re-fetched / a colliding name). Only delete `f` when it is NOT
-                # the existing record's file — otherwise we orphan the record and
-                # playback 404s. (#859)
-                canonical = None
-                if result.image_id is not None:
-                    rec = session.get(ImageRecord, result.image_id)
-                    if rec is not None:
-                        canonical = (IMAGES_ROOT / rec.path).resolve()
-                if canonical != f.resolve():
-                    f.unlink(missing_ok=True)  # a redundant copy — safe to drop
-                else:
-                    log.info(
-                        "extdl keep: %s IS record %s's canonical file — not unlinking",
-                        f.name, result.image_id,
-                    )
         elif result.status == "failed":
             log.warning(
                 "extdl import FAILED: post=%s file=%s error=%s",
                 post.id, f.name, result.error,
             )
-            f.unlink(missing_ok=True)
         else:  # 'refreshed' or any future status — work happened, no new images
             log.info(
                 "extdl import: post=%s file=%s status=%s", post.id, f.name, result.status,
             )
+        # Same policy as the subscription download path: drop the file unless
+        # the library needs it at this path. A file imported in place is kept.
+        importer.discard_after_attach(f, result)
         # The synthesized sidecar has done its job — don't litter the tree.
         Path(str(f) + ".json").unlink(missing_ok=True)
     return image_ids
 
 
+def _unimported_files(session, link_dir: Path, *, first=()) -> list[Path]:
+    """Every complete file under a link's dir, subfolders included, that no
+    ImageRecord points at: what this fetch wrote plus anything an earlier
+    attempt finished writing but never imported. `first` (the fetch's own
+    files) leads the list. Staging files and sidecars are left out."""
+    if not link_dir.is_dir():
+        return []
+    found = {
+        p for p in link_dir.rglob("*")
+        if p.is_file() and not is_temp_staging_file(p) and p.suffix.lower() != ".json"
+    }
+    ordered = [p for p in first if p in found] + sorted(found.difference(first))
+    recorded = set(session.execute(
+        select(ImageRecord.path).where(
+            ImageRecord.path.in_([str(p) for p in ordered])
+        )
+    ).scalars()) if ordered else set()
+    return [p for p in ordered if str(p) not in recorded]
+
+
+def _discard_partials(link_dir: Path) -> int:
+    """Delete the staging files under a link's dir (megatools' `.megatmp.*`, an
+    HTTP fetch's `.part`), then the dirs left empty. Every fetcher writes to a
+    staging name and renames on completion, so a staging file is a transfer
+    that never finished. Complete files stay: they may be the only copy of art
+    whose upstream has since gone. Returns the number of files removed."""
+    if not link_dir.is_dir():
+        return 0
+    removed = 0
+    for p in link_dir.rglob("*"):
+        if not (p.is_file() and is_temp_staging_file(p)):
+            continue
+        try:
+            p.unlink(missing_ok=True)
+            removed += 1
+        except OSError as exc:
+            log.warning("extdl could not remove %s: %s", p, exc)
+    for d in sorted((p for p in link_dir.rglob("*") if p.is_dir()), reverse=True):
+        try:
+            d.rmdir()
+        except OSError:
+            pass  # not empty: it holds a complete file
+    try:
+        link_dir.rmdir()
+    except OSError:
+        pass
+    if removed:
+        log.info("extdl removed %d leftover file(s) from %s", removed, link_dir)
+    return removed
+
+
 @celery.task(name="backend.app.tasks.external.sweep_external_links")
 def sweep_external_links() -> dict:
     """Enqueue a bounded batch of actionable links (pending, or failed below the
-    dead-letter threshold). Driven by the post-download hook and a beat tick."""
+    dead-letter threshold). Driven by the post-download hook and a beat tick.
+
+    First it recovers links whose worker died mid-fetch: a link 'downloading'
+    for longer than the task's hard limit has no worker left, so it counts as a
+    failed attempt and goes back to the retry path (dead-lettered at the
+    threshold like any other failure). The next attempt clears its staging
+    files and imports the complete ones."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
+        now = datetime.now(UTC)
+        stale = session.execute(
+            select(ExternalLink).where(
+                ExternalLink.status == "downloading",
+                or_(
+                    ExternalLink.started_at.is_(None),
+                    ExternalLink.started_at < now - timedelta(minutes=_STALL_MINUTES),
+                ),
+            )
+        ).scalars().all()
+        for link in stale:
+            _record_failure(link, link.attempts, "worker stopped mid-fetch")
+        session.commit()
         ids = session.execute(
             select(ExternalLink.id).where(
                 ExternalLink.status.in_(("pending", "failed")),
@@ -351,34 +419,53 @@ def sweep_external_links() -> dict:
         ).scalars().all()
     for link_id in ids:
         fetch_external_link.delay(link_id)
-    return {"enqueued": len(ids)}
+    return {"enqueued": len(ids), "recovered": len(stale)}
 
 
 @celery.task(name="backend.app.tasks.external.recover_external_links")
 def recover_external_links() -> dict:
-    """Recovery sweep (rule #89): reset dead links back to retryable so a stuck
-    host outage or a since-fixed bug gets another pass, then enqueue. Bounded."""
+    """Recovery sweep: give each dead link one more attempt once it
+    has been dead for 2**recoveries days, then enqueue. A recovered link that
+    fails again goes straight back to dead, and after _MAX_RECOVERIES it stays
+    dead until retention prunes it."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
-        session.execute(
-            update(ExternalLink).where(ExternalLink.status == "dead")
-            .values(status="failed", attempts=0, last_error=None)
-        )
+        now = datetime.now(UTC)
+        candidates = session.execute(
+            select(ExternalLink).where(
+                ExternalLink.status == "dead",
+                ExternalLink.recoveries < _MAX_RECOVERIES,
+            )
+        ).scalars().all()
+        recovered = 0
+        for link in candidates:
+            wait = timedelta(days=2 ** link.recoveries)
+            if link.completed_at is not None and link.completed_at > now - wait:
+                continue
+            link.status = "failed"
+            link.attempts = DEAD_LETTER_THRESHOLD - 1
+            link.recoveries += 1
+            recovered += 1
         session.commit()
-    return sweep_external_links()
+    return {**sweep_external_links(), "revived": recovered}
 
 
 @celery.task(name="backend.app.tasks.external.prune_external_links")
 def prune_external_links() -> dict:
-    """Retention (rule #89): delete long-dead links so the ledger doesn't grow
-    unbounded. Downloaded links are kept (they're the record of what we have)."""
+    """Retention: delete links recovery has given up on, once their
+    last attempt is _RETENTION_DAYS old, so the ledger doesn't grow unbounded.
+    Downloaded links are kept (they're the record of what we have)."""
     cutoff = datetime.now(UTC) - timedelta(days=_RETENTION_DAYS)
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
         res = session.execute(
             delete(ExternalLink).where(
                 ExternalLink.status == "dead",
-                ExternalLink.created_at < cutoff,
+                ExternalLink.recoveries >= _MAX_RECOVERIES,
+                or_(
+                    ExternalLink.completed_at.is_(None),
+                    ExternalLink.completed_at < cutoff,
+                ),
             )
         )
         session.commit()

backend/app/tasks/import_file.py

@@ -19,7 +19,8 @@ from sqlalchemy.exc import DBAPIError, OperationalError
 
 from ..celery_app import celery
 from ..models import ImportBatch, ImportSettings, ImportTask
-from ..services.importer import Importer
+from ..services.importer import Importer, ImportResult
+from ..services.library_scan import folder_owner
 from ..services.thumbnailer import Thumbnailer
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
@@ -45,8 +46,13 @@ def _mark_failed(session, task, error_msg: str) -> None:
     """Best-effort flip of a 'processing' row to 'failed' + batch counter
     increment. Wrapped in its own try because if the DB is what just
     broke, this commit will also fail — that's why the maintenance sweep
-    exists as a backstop."""
+    exists as a backstop.
+
+    The failure being recorded may have left the session's transaction dead
+    (an error mid-flush), so it is rolled back first; otherwise this commit
+    fails on it too and the row stays 'processing'."""
     try:
+        session.rollback()
         task.status = "failed"
         task.error = error_msg
         task.finished_at = datetime.now(UTC)
@@ -165,6 +171,27 @@ def enqueue_import(task_id: int, task_type: str) -> None:
         import_media_file.delay(task_id)
 
 
+def _attach_where_it_lies(session, importer: Importer, path: Path) -> ImportResult:
+    """Import a file that already sits in its artist's folder (a `library`
+    batch, from services.library_scan). It is attached in place with that
+    artist and source. The post record its folder holds (`_post.json`) is filed
+    first, so the post gets its title and date. Afterwards the file is removed
+    if the library didn't keep it: a copy of something it already holds, or a
+    file the import filters reject. A file whose import crashed stays, with the
+    task marked failed: it may be the only copy of an archive the extractor
+    can't read yet."""
+    if not path.is_file():
+        return ImportResult(status="skipped", error="no longer on disk")
+    artist, source = folder_owner(session, path, IMAGES_ROOT)
+    record = path.parent / "_post.json"
+    if artist is not None and record.is_file():
+        importer.upsert_post_record(record, artist=artist, source=source)
+    result = importer.attach_in_place(path, artist=artist, source=source)
+    if result.status != "failed":
+        importer.discard_after_attach(path, result)
+    return result
+
+
 def _do_import(session, task, import_task_id: int) -> dict:
     """Actual work, called from inside the resilience wrapper."""
     settings = ImportSettings.load_sync(session)
@@ -180,7 +207,10 @@ def _do_import(session, task, import_task_id: int) -> dict:
         deep=deep,
     )
 
-    result = importer.import_one(Path(task.source_path))
+    if batch is not None and batch.scan_mode == "library":
+        result = _attach_where_it_lies(session, importer, Path(task.source_path))
+    else:
+        result = importer.import_one(Path(task.source_path))
 
     if result.status in ("imported", "superseded"):
         task.status = "complete"

backend/app/tasks/maintenance.py

@@ -20,10 +20,12 @@ from ..models import (
     ImportSettings,
     ImportTask,
     LibraryAuditRun,
+    PostAttachment,
     Source,
     TaskRun,
 )
 from ..utils.phash import compute_phash
+from ..utils.staging import is_temp_staging_file
 from ._sync_engine import get_sync_engine
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
@@ -81,13 +83,10 @@ WIP_BACKFILL_PAGE = 500
 FFPROBE_TIMEOUT_SECONDS = 10
 TASK_RUN_KEEP_OK_SECONDS = 24 * 3600       # 24 h
 TASK_RUN_KEEP_FAILURE_SECONDS = 7 * 24 * 3600  # 7 days
-# Orphaned staging files: downloads/imports stage into <name>.part / <name>.partial
-# then os.replace() into place (importer / external_fetch / native_ingest_common /
-# attachment_store), so a kill mid-write leaves a discardable temp, never a corrupt
-# final. cleanup_orphaned_temp_files sweeps ones left behind; the min-age guard
-# keeps it from deleting an in-flight download's staging file mid-write.
+# Orphaned staging files (utils.staging): cleanup_orphaned_temp_files sweeps the
+# ones a killed write left behind; the min-age guard keeps it from deleting an
+# in-flight download's staging file mid-write.
 IMAGES_ROOT = Path("/images")
-TEMP_STAGING_SUFFIXES = (".part", ".partial")
 ORPHAN_TEMP_MIN_AGE_HOURS = 6
 
 # Audit 2026-06-02: per-entity recovery sweep thresholds. Each must be
@@ -174,6 +173,11 @@ TASK_STUCK_THRESHOLD_MINUTES: dict[str, int] = {
     # legitimately-running backup isn't flagged.
     "backend.app.tasks.backup.backup_images_task": 420,
     "backend.app.tasks.backup.restore_images_task": 420,
+    # One media-backup chunk stops starting files after 45 min but may finish
+    # a large file in flight, up to its 6.5 h hard limit.
+    "backend.app.tasks.backup.backup_media_task": 420,
+    # A restore's database load, or one chunk of its file phase, likewise.
+    "backend.app.tasks.backup.restore_offsite_task": 420,
     # Library audit scans the full library — 2h hard limit.
     "backend.app.tasks.library_audit.scan_library_for_rule": 130,
     # External file-host fetches (mega/gdrive/film packs) can run to the task's
@@ -191,6 +195,9 @@ TASK_STUCK_THRESHOLD_MINUTES: dict[str, int] = {
     # external-fetch entry above — without an override a healthy in-flight walk
     # is swept 'RecoverySweep' at the bare 5-min default. 30 = 25 + 5.
     "backend.app.tasks.admin.reclaim_orphaned_attachments_task": 30,
+    # Importing what's on disk stats every file in the artists' folders, and
+    # its hard limit is 40 min for the same wedged-filesystem case. 45 = 40 + 5.
+    "backend.app.tasks.admin.import_unimported_files_task": 45,
     # Head training and the manual head apply run to 65 min (3900s) — past the
     # ml queue's threshold (#4432). 70 = 65 + 5.
     "backend.app.tasks.ml.train_heads": 70,
@@ -198,6 +205,23 @@ TASK_STUCK_THRESHOLD_MINUTES: dict[str, int] = {
 }
 
 
+def _import_queue_depth() -> int | None:
+    """Messages waiting in the broker's import queue, or None when the broker
+    can't be read."""
+    try:
+        import redis
+
+        from ..config import get_config
+
+        client = redis.Redis.from_url(
+            get_config().celery_broker_url, socket_timeout=5, socket_connect_timeout=5,
+        )
+        return int(client.llen("import"))
+    except Exception:  # noqa: BLE001 — an unreadable broker means "don't know"
+        log.warning("recover_interrupted_tasks: import queue depth unreadable", exc_info=True)
+        return None
+
+
 @celery.task(name="backend.app.tasks.maintenance.recover_interrupted_tasks")
 def recover_interrupted_tasks() -> int:
     """Recover stuck ImportTask rows. Two distinct stuck states:
@@ -213,16 +237,22 @@ def recover_interrupted_tasks() -> int:
        2026-05-24 after a 2224-row zombie pile; archive split out
        2026-05-28.)
 
-    2. 'pending' or 'queued' > 30 min — enqueue-phase crash. scan_directory
-       creates rows with status='pending' (commit), then in a second pass
-       transitions to 'queued' and calls .delay() (commit). If the scanner
-       crashes between those two commits, rows are orphaned in 'pending'
-       (never enqueued) with no recovery path — invisible to the
-       'processing' sweep above. Flagged 2026-05-25 by operator hitting a
-       5490-row orphan pile. Flip these to 'failed' (not re-enqueue) so
-       the operator drains them via /api/import/retry-failed at their own
-       pace; bulk-re-enqueueing 5000+ rows would thundering-herd the
-       import worker.
+    2. 'pending' > 30 min — enqueue-phase crash. scan_directory creates rows
+       with status='pending' (commit), then in a second pass transitions to
+       'queued' and calls .delay() (commit). If the scanner crashes between
+       those two commits, rows are orphaned in 'pending' (never enqueued)
+       with no recovery path — invisible to the 'processing' sweep above.
+       Flip these to 'failed' (not re-enqueue) so the operator drains them
+       via /api/import/retry-failed at their own pace; bulk-re-enqueueing
+       5000+ rows would thundering-herd the import worker.
+
+       A 'queued' row has a broker message, and in a batch larger than half
+       an hour of work it is simply waiting its turn, so its age says
+       nothing. It counts as orphaned only when the broker's import queue
+       is empty: then its message is gone (a broker flush or restart) and
+       nothing will ever run it. When the queue can't be read, queued rows
+       are left alone — a queued row costs nothing to keep, and failing a
+       live one loses its import.
 
     Returns total rows touched (recovered + marked failed).
     """
@@ -299,9 +329,12 @@ def recover_interrupted_tasks() -> int:
         )
         stuck = stuck_result.all()
 
+        orphan_statuses = ["pending"]
+        if _import_queue_depth() == 0:
+            orphan_statuses.append("queued")
         orphan_result = session.execute(
             update(ImportTask)
-            .where(ImportTask.status.in_(["pending", "queued"]))
+            .where(ImportTask.status.in_(orphan_statuses))
             .where(ImportTask.created_at < orphan_cutoff)
             .values(
                 status="failed",
@@ -371,22 +404,58 @@ def cleanup_old_tasks() -> int:
         return result.rowcount or 0
 
 
+def _paths_with_rows(paths: list[str]) -> set[str]:
+    """The subset of `paths` that an image (its file or thumbnail) or an
+    attachment row points at."""
+    owned: set[str] = set()
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        for i in range(0, len(paths), 500):
+            chunk = paths[i:i + 500]
+            owned.update(session.execute(
+                select(ImageRecord.path).where(ImageRecord.path.in_(chunk))
+            ).scalars())
+            owned.update(session.execute(
+                select(ImageRecord.thumbnail_path).where(ImageRecord.thumbnail_path.in_(chunk))
+            ).scalars())
+            owned.update(session.execute(
+                select(PostAttachment.path).where(PostAttachment.path.in_(chunk))
+            ).scalars())
+    return owned
+
+
 @celery.task(name="backend.app.tasks.maintenance.cleanup_orphaned_temp_files")
 def cleanup_orphaned_temp_files() -> int:
-    """Delete orphaned .part/.partial staging files under the images root, left by
-    a download/import killed mid-write. Only removes files older than
-    ORPHAN_TEMP_MIN_AGE_HOURS so an in-flight download's staging file is never
-    pulled out from under it. Returns the count removed."""
+    """Delete orphaned staging files (.part, .partial, megatools' .megatmp.*)
+    under the images root, left by a download/import killed mid-write. Only
+    removes files older than ORPHAN_TEMP_MIN_AGE_HOURS so an in-flight
+    download's staging file is never pulled out from under it, and never a
+    file an image or attachment row points at, whatever its name: that file
+    is library content. Returns the count removed."""
     if not IMAGES_ROOT.is_dir():
         return 0
     cutoff = datetime.now(UTC).timestamp() - ORPHAN_TEMP_MIN_AGE_HOURS * 3600
-    removed = 0
+    stale: list[Path] = []
     for path in IMAGES_ROOT.rglob("*"):
-        if path.suffix not in TEMP_STAGING_SUFFIXES or not path.is_file():
+        if not is_temp_staging_file(path) or not path.is_file():
+            continue
+        try:
+            if path.stat().st_mtime < cutoff:   # fresher may be an active download
+                stale.append(path)
+        except OSError as exc:
+            log.warning("cleanup_orphaned_temp_files: %s: %s", path, exc)
+    if not stale:
+        return 0
+    owned = _paths_with_rows([str(p) for p in stale])
+    removed = 0
+    for path in stale:
+        if str(path) in owned:
+            log.warning(
+                "cleanup_orphaned_temp_files: keeping %s: a library row points at it",
+                path,
+            )
             continue
         try:
-            if path.stat().st_mtime >= cutoff:
-                continue          # too fresh — may be an active download
             path.unlink()
             removed += 1
         except OSError as exc:
@@ -778,10 +847,18 @@ def recover_stalled_backup_runs() -> int:
             update(BackupRun)
             .where(BackupRun.status.in_(["running", "restoring"]))
             # db backups/restores are fast (40-min window); images run hours (7h).
+            # A media run or an off-site restore spans many chunks and hours on
+            # purpose, so its window runs from its last progress, not its start.
             .where(
                 or_(
                     and_(BackupRun.kind == "db", BackupRun.started_at < db_cutoff),
-                    and_(BackupRun.kind != "db", BackupRun.started_at < slow_cutoff),
+                    and_(
+                        BackupRun.kind.in_(["media", "restore"]),
+                        func.coalesce(BackupRun.last_progress_at, BackupRun.started_at)
+                        < slow_cutoff,
+                    ),
+                    and_(BackupRun.kind.not_in(["db", "media", "restore"]),
+                         BackupRun.started_at < slow_cutoff),
                 )
             )
             .values(status="error", finished_at=now, error=msg)

backend/app/utils/staging.py

@@ -0,0 +1,20 @@
+"""Downloader staging files.
+
+Downloads and imports write into a staging name and `os.replace()` it into
+place when the write completes (importer, external_fetch, native_ingest_common,
+attachment_store), so a write killed midway leaves a staging file, never a
+truncated final file. Any other file is complete.
+"""
+from pathlib import Path
+
+TEMP_STAGING_SUFFIXES = (".part", ".partial")
+# megatools stages a Mega download as `.megatmp.<id>` in the target dir.
+TEMP_STAGING_PREFIXES = (".megatmp.",)
+
+
+def is_temp_staging_file(path: Path) -> bool:
+    """True for a downloader's staging file: one that never becomes library
+    content under that name, so a stale one is safe to delete."""
+    return path.suffix in TEMP_STAGING_SUFFIXES or path.name.startswith(
+        TEMP_STAGING_PREFIXES
+    )

frontend/src/components/modal/DestructiveConfirmModal.vue

@@ -89,6 +89,7 @@ const kindLabel = computed(() => ({
   artist: 'artist',
   tag: 'tag',
   'images-selection': 'image selection',
+  offsite: 'from the off-site bucket',
 }[props.kind] || props.kind))
 const alertType = computed(
   () => props.action === 'restore' ? 'warning' : 'error',

frontend/src/components/settings/BackupCard.vue

@@ -4,11 +4,18 @@
     title="Backups"
     blurb="Database + image backups, schedules and restore."
   >
-      <p class="fc-muted text-body-2 mb-4">
+      <p v-if="offsite" class="fc-muted text-body-2 mb-4">
+        Database dumps stream to the <strong>{{ offsite.bucket }}</strong> bucket
+        at {{ offsite.endpoint }}, with no copy kept on this server; the bucket's
+        own retention thins old dumps. Images and attachments go to the same
+        bucket's <code>media/</code> folder, below.
+      </p>
+      <p v-else class="fc-muted text-body-2 mb-4">
         pg_dump for the database (fast, nightly-schedulable);
         tar+zstd for the images (slow, manual only). Files live in
         <code>/images/_backups/</code>. Tag a backup to protect it
-        from autoprune.
+        from autoprune. Set up an off-site destination above to send
+        database dumps off this server instead.
       </p>
 
       <v-alert
@@ -40,6 +47,10 @@
           @update:model-value="onSettingChange('backup_db_keep_last_n', Number($event))"
         />
       </div>
+      <p v-if="offsite" class="fc-muted text-caption mb-3">
+        Nightly sends the database, then any new images and attachments. Keep
+        last applies to this list and to any dumps still on this server.
+      </p>
       <v-btn
         color="accent" variant="flat" rounded="pill"
         prepend-icon="mdi-database-arrow-up" class="mb-3"
@@ -56,6 +67,119 @@
 
       <v-divider class="my-4" />
 
+      <!-- Off-site: images and attachments as one file per fingerprint -->
+      <template v-if="offsite">
+        <h3 class="fc-section-title">Images and attachments</h3>
+        <p class="fc-muted text-body-2 mb-2">
+          Each file goes to the bucket's <code>media/</code> folder once, named by
+          its fingerprint, and the bucket checks it against the fingerprint taken
+          at import. Only files not sent yet go in each run. With Nightly on, they
+          follow the database dump every night.
+        </p>
+        <div v-if="coverage" class="mb-3">
+          <div class="text-body-2 mb-1" style="font-variant-numeric: tabular-nums;">
+            {{ coverage.files_sent.toLocaleString() }} of
+            {{ coverage.files_total.toLocaleString() }} files in the bucket
+            ({{ humanBytes(coverage.bytes_sent) }} of {{ humanBytes(coverage.bytes_total) }})
+          </div>
+          <v-progress-linear
+            :model-value="coveragePct" color="accent" height="6" rounded
+          />
+        </div>
+        <v-btn
+          color="accent" variant="flat" rounded="pill"
+          prepend-icon="mdi-cloud-upload-outline" class="mb-3"
+          :loading="mediaTriggering" :disabled="mediaRunning"
+          @click="onTrigger('media')"
+        >Send new files now</v-btn>
+        <span v-if="mediaRunning" class="text-caption fc-muted ml-2">
+          A run is going: {{ runningSent.toLocaleString() }} files sent so far.
+        </span>
+        <BackupRunsTable :runs="store.mediaRuns" />
+
+        <v-divider class="my-4" />
+
+        <!-- Off-site: restoring this install from the bucket -->
+        <h3 class="fc-section-title">Restore from the bucket</h3>
+        <p class="fc-muted text-body-2 mb-2">
+          Replace this install's database with one of the bucket's dumps, then
+          fetch every image and attachment back to where it belongs, each
+          checked against its fingerprint as it arrives. The database being
+          replaced is saved to the bucket first, so a restore can be undone.
+          Account logins aren't in the backup: sign in to each again afterwards.
+        </p>
+        <p class="fc-muted text-body-2 mb-2">
+          To repair a library that lost files, fetch only what's missing from
+          disk; the database stays as it is.
+        </p>
+        <div class="fc-settings-row mb-3">
+          <v-btn
+            color="warning" variant="tonal" rounded="pill"
+            prepend-icon="mdi-database-arrow-down"
+            :disabled="anyGoing" :loading="dumpsLoading"
+            @click="openDumps"
+          >Choose a dump…</v-btn>
+          <v-btn
+            variant="tonal" rounded="pill"
+            prepend-icon="mdi-cloud-download-outline"
+            :disabled="anyGoing" :loading="fetchTriggering"
+            @click="onFetchMissing"
+          >Fetch missing files</v-btn>
+        </div>
+        <v-alert
+          v-if="restoreDispatched || runningRestore"
+          type="info" variant="tonal" density="compact" class="mb-3"
+        >
+          <template v-if="runningRestore?.manifest?.phase === 'files'">
+            Fetching files: {{ restoreLine(runningRestore.manifest) }}.
+          </template>
+          <template v-else>
+            Restoring the database. While it loads, this page may stop answering
+            for a few minutes; it comes back on its own.
+          </template>
+        </v-alert>
+        <BackupRunsTable :runs="store.restoreRuns" empty-text="No restores yet." />
+
+        <v-dialog v-model="dumpsOpen" max-width="560">
+          <v-card>
+            <v-card-title>Dumps in {{ offsite.bucket }}</v-card-title>
+            <v-card-text>
+              <v-alert
+                v-if="dumpsError" type="warning" variant="tonal" density="compact" class="mb-3"
+              >{{ dumpsError }}</v-alert>
+              <v-table v-else density="compact">
+                <thead>
+                  <tr><th>Taken</th><th class="text-right">Size</th><th /></tr>
+                </thead>
+                <tbody>
+                  <tr v-for="d in dumps" :key="d.key">
+                    <td :title="d.key">{{ dumpWhen(d.ts) }}</td>
+                    <td class="text-right" style="font-variant-numeric: tabular-nums;">
+                      {{ humanBytes(d.size_bytes) }}
+                    </td>
+                    <td class="text-right">
+                      <v-btn size="small" variant="text" color="warning" @click="onPickDump(d)">
+                        Restore…
+                      </v-btn>
+                    </td>
+                  </tr>
+                  <tr v-if="!dumps.length">
+                    <td colspan="3" class="text-center fc-muted py-4">
+                      The bucket holds no database dumps yet.
+                    </td>
+                  </tr>
+                </tbody>
+              </v-table>
+            </v-card-text>
+            <v-card-actions>
+              <v-spacer />
+              <v-btn variant="text" @click="dumpsOpen = false">Close</v-btn>
+            </v-card-actions>
+          </v-card>
+        </v-dialog>
+      </template>
+
+      <template v-else>
       <!-- Images section -->
       <h3 class="fc-section-title">Images</h3>
       <div class="fc-settings-row mb-3">
@@ -82,23 +206,27 @@
         @delete="onDelete"
         @tag="onTag"
       />
+      </template>
     <BackupConfirmModal
       v-model="confirmOpen"
       :action="confirmAction"
       :kind="confirmKind"
       :run-id="confirmRunId"
       :description="confirmDescription"
+      :expected-token-override="confirmToken"
       @confirm="onConfirmSubmit"
     />
   </MaintenanceTile>
 </template>
 
 <script setup>
-import { computed, onMounted, onUnmounted, ref } from 'vue'
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 
 import { useBackupStore } from '../../stores/backup.js'
 import BackupConfirmModal from '../modal/DestructiveConfirmModal.vue'
 import MaintenanceTile from '../common/MaintenanceTile.vue'
+import { humanBytes } from '../../utils/bytes.js'
+import { formatDateTime } from '../../utils/date.js'
 import BackupRunsTable from './BackupRunsTable.vue'
 
 const store = useBackupStore()
@@ -110,6 +238,21 @@ const settings = computed(() => store.settings || {
   backup_images_keep_last_n: 3,
 })
 
+// The off-site destination, once it is fully set up: database dumps go there.
+const offsite = computed(() => (
+  store.destination?.configured ? store.destination : null
+))
+
+const coverage = computed(() => store.mediaCoverage)
+const coveragePct = computed(() => {
+  const c = coverage.value
+  return c && c.files_total ? (100 * c.files_sent) / c.files_total : 0
+})
+const runningMedia = computed(() => store.mediaRuns.find((r) => r.status === 'running'))
+const mediaRunning = computed(() => Boolean(runningMedia.value))
+const runningSent = computed(() => runningMedia.value?.manifest?.sent || 0)
+
+const mediaTriggering = ref(false)
 const dbTriggering = ref(false)
 const imagesTriggering = ref(false)
 const confirmOpen = ref(false)
@@ -117,16 +260,100 @@ const confirmAction = ref('restore')
 const confirmKind = ref('db')
 const confirmRunId = ref(0)
 const confirmDescription = ref('')
+const confirmToken = ref('')
+
+// Restoring from the bucket.
+const runningRestore = computed(() => store.restoreRuns.find((r) => r.status === 'restoring'))
+const anyGoing = computed(() => Boolean(
+  runningRestore.value || mediaRunning.value
+  || store.dbRuns.some((r) => r.status === 'running'),
+))
+const restoreDispatched = ref(false)
+const dumpsOpen = ref(false)
+const dumpsLoading = ref(false)
+const dumpsError = ref('')
+const dumps = ref([])
+const pickedDump = ref(null)
+const fetchTriggering = ref(false)
+// The notice that a restore was asked for stays up until its run is over.
+watch(runningRestore, (now, before) => {
+  if (before && !now) restoreDispatched.value = false
+})
+
+function restoreLine(m) {
+  const n = (k) => (m?.[k] || 0).toLocaleString()
+  return `${n('restored')} restored, ${n('copied')} copied from a duplicate, `
+    + `${n('present')} already there, ${n('missing')} not in the bucket, ${n('failed')} failed`
+}
+
+// 20261107T134258Z → the reader's local date and time.
+function dumpWhen(ts) {
+  const iso = ts.replace(
+    /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/, '$1-$2-$3T$4:$5:$6Z',
+  )
+  return formatDateTime(iso)
+}
+
+async function openDumps() {
+  dumpsLoading.value = true
+  dumpsError.value = ''
+  try {
+    dumps.value = await store.listOffsiteDumps()
+  } catch (e) {
+    dumps.value = []
+    dumpsError.value = e.message
+  } finally {
+    dumpsLoading.value = false
+    dumpsOpen.value = true
+  }
+}
+
+function onPickDump(d) {
+  pickedDump.value = d
+  dumpsOpen.value = false
+  confirmAction.value = 'restore'
+  confirmKind.value = 'offsite'
+  confirmRunId.value = ''
+  confirmToken.value = d.confirm
+  confirmDescription.value = (
+    `Replaces this install's database with the dump taken ${dumpWhen(d.ts)}, `
+    + 'then fetches the library\'s files from the bucket.'
+  )
+  confirmOpen.value = true
+}
+
+async function onFetchMissing() {
+  fetchTriggering.value = true
+  try {
+    await store.fetchMissingFiles()
+    pollOnce()
+  } catch {
+    // store.lastError is shown above.
+  } finally {
+    fetchTriggering.value = false
+  }
+}
 
 let pollId = null
+let polls = 0
+// Coverage counts every library file, so it refreshes every sixth poll
+// (30 s) rather than with the run lists.
+const COVERAGE_EVERY = 6
 function pollOnce() {
   if (document.hidden) return
   store.loadRuns('db')
-  store.loadRuns('images')
+  if (offsite.value) {
+    store.loadRuns('media')
+    store.loadRuns('restore')
+    if (polls++ % COVERAGE_EVERY === 0) store.loadMediaCoverage()
+  } else {
+    store.loadRuns('images')
+  }
 }
 
 onMounted(() => {
   store.loadSettings()
+  if (!store.destination) store.loadDestination().catch(() => {})
   pollOnce()
   pollId = setInterval(pollOnce, 5000)
 })
@@ -135,7 +362,7 @@ onUnmounted(() => {
 })
 
 async function onTrigger(kind) {
-  const triggeringRef = kind === 'db' ? dbTriggering : imagesTriggering
+  const triggeringRef = { db: dbTriggering, images: imagesTriggering, media: mediaTriggering }[kind]
   triggeringRef.value = true
   try {
     await store.triggerBackup(kind)
@@ -153,6 +380,7 @@ function _openConfirm(action, run) {
   confirmAction.value = action
   confirmKind.value = run.kind
   confirmRunId.value = run.id
+  confirmToken.value = ''
   confirmDescription.value = (
     action === 'restore'
       ? `Source artifact: ${run.kind === 'db' ? run.sql_path : run.tar_path}`
@@ -176,7 +404,10 @@ async function onTag(run) {
 
 async function onConfirmSubmit(token) {
   try {
-    if (confirmAction.value === 'restore') {
+    if (confirmKind.value === 'offsite') {
+      await store.restoreFromOffsite(pickedDump.value.key, token)
+      restoreDispatched.value = true
+    } else if (confirmAction.value === 'restore') {
       await store.restore(confirmRunId.value, token)
     } else {
       await store.deleteRun(confirmRunId.value, token)

frontend/src/components/settings/BackupDestinationCard.vue

@@ -0,0 +1,217 @@
+<!--
+  Off-site backup destination: an S3 bucket (Fabled Archives or any S3
+  service) that backups are sent to. The five fields only work together, so
+  they save as one with an explicit button rather than field by field. The
+  secret key is write-only: once saved it is never shown again, and leaving the
+  field blank keeps it. Test destination lists the bucket with what is typed
+  in the form (saved or not) and writes nothing.
+-->
+<template>
+  <MaintenanceTile
+    icon="mdi-cloud-upload-outline"
+    title="Off-site backup destination"
+    blurb="The S3 bucket (Fabled Archives or any S3 service) that backups are sent to."
+  >
+    <p class="fc-muted text-body-2 mb-3">
+      Backups sent here survive losing this server. FabledCurator only adds to the
+      bucket and never deletes from it, so a key that may add and read objects but
+      not delete them is enough, and is the safer key to use. Account logins are
+      never sent.
+    </p>
+
+    <v-alert
+      v-if="loadError" type="warning" variant="tonal" density="compact" class="mb-3"
+    >{{ loadError }}</v-alert>
+
+    <v-text-field
+      v-model="form.endpoint" label="Address"
+      placeholder="http://archives.example:8081" density="compact"
+      hint="Include the port the S3 service listens on." persistent-hint
+      class="mb-3" :disabled="busy"
+    />
+    <div class="fc-dest-row mb-3">
+      <v-text-field
+        v-model="form.bucket" label="Bucket" density="compact" hide-details
+        :disabled="busy"
+      />
+      <v-text-field
+        v-model="form.region" label="Region" density="compact" hide-details
+        class="fc-dest-region" :disabled="busy"
+      />
+    </div>
+    <v-text-field
+      v-model="form.access_key" label="Access key" density="compact" hide-details
+      autocomplete="off" class="mb-3" :disabled="busy"
+    />
+    <v-text-field
+      v-model="form.secret_key" label="Secret key" type="password"
+      autocomplete="new-password" density="compact"
+      :placeholder="secretSet ? 'Saved. Leave blank to keep it.' : ''"
+      :persistent-placeholder="secretSet"
+      :hint="secretSet ? 'A saved secret is never shown again.' : ''" persistent-hint
+      class="mb-3" :disabled="busy"
+    />
+    <v-text-field
+      v-model.number="form.upload_limit_mbps" label="Upload limit (Mbit/s)"
+      type="number" min="0" density="compact" class="fc-dest-limit mb-3"
+      hint="0 for no limit. A lower limit leaves more of the link free, and makes each upload take longer."
+      persistent-hint :disabled="busy"
+    />
+
+    <div class="d-flex align-center flex-wrap mb-2" style="gap: 8px;">
+      <v-btn
+        size="small" variant="flat" color="accent" rounded="pill"
+        prepend-icon="mdi-content-save" :loading="saving"
+        :disabled="busy || !dirty" @click="onSave"
+      >Save</v-btn>
+      <v-btn
+        size="small" variant="tonal" rounded="pill"
+        prepend-icon="mdi-lan-connect" :loading="testing"
+        :disabled="busy || !form.endpoint" @click="onTest"
+      >Test destination</v-btn>
+      <v-btn
+        v-if="configured" size="small" variant="text" rounded="pill" color="error"
+        :disabled="busy" @click="confirmRemove = true"
+      >Remove</v-btn>
+      <span v-if="savedNote" class="text-caption text-success">{{ savedNote }}</span>
+    </div>
+
+    <v-alert
+      v-if="testResult" :type="testResult.ok ? 'success' : 'error'"
+      variant="tonal" density="compact" class="mb-1"
+    >{{ testResult.message }}</v-alert>
+    <p v-if="!configured && !testResult" class="fc-muted text-caption mb-0">
+      No destination is set up, so nothing is sent off this server yet.
+    </p>
+    <p v-else-if="configured && !testResult" class="fc-muted text-caption mb-0">
+      Database backups and the library's images and attachments go to this bucket.
+      Set when they run under Backups below.
+    </p>
+
+    <v-dialog v-model="confirmRemove" max-width="440">
+      <v-card>
+        <v-card-title class="text-h6">Remove the destination?</v-card-title>
+        <v-card-text class="text-body-2">
+          FabledCurator forgets the address and both keys and stops sending
+          backups there. What was already sent stays in the bucket.
+        </v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn variant="text" @click="confirmRemove = false">Cancel</v-btn>
+          <v-btn color="error" variant="flat" :loading="saving" @click="onRemove">
+            Remove
+          </v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { computed, onMounted, reactive, ref } from 'vue'
+
+import { useBackupStore } from '../../stores/backup.js'
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+
+const store = useBackupStore()
+
+const FIELDS = ['endpoint', 'bucket', 'access_key', 'region']
+const DEFAULT_LIMIT = 200
+const form = reactive({
+  endpoint: '', bucket: '', access_key: '', region: 'us-east-1', secret_key: '',
+  upload_limit_mbps: DEFAULT_LIMIT,
+})
+const saved = ref(null)
+const loadError = ref('')
+const saving = ref(false)
+const testing = ref(false)
+const testResult = ref(null)
+const savedNote = ref('')
+const confirmRemove = ref(false)
+
+const busy = computed(() => saving.value || testing.value)
+const secretSet = computed(() => Boolean(saved.value?.secret_set))
+const configured = computed(() => Boolean(saved.value?.configured))
+const dirty = computed(() => (
+  !saved.value
+  || form.secret_key.trim() !== ''
+  || FIELDS.some((f) => (form[f] || '').trim() !== (saved.value[f] || ''))
+  || form.upload_limit_mbps !== saved.value.upload_limit_mbps
+))
+
+function apply(dest) {
+  saved.value = dest
+  for (const f of FIELDS) form[f] = dest[f] || (f === 'region' ? 'us-east-1' : '')
+  form.upload_limit_mbps = dest.upload_limit_mbps ?? DEFAULT_LIMIT
+  form.secret_key = ''
+}
+
+function fields() {
+  const out = {}
+  for (const f of FIELDS) out[f] = form[f]
+  if (form.secret_key.trim()) out.secret_key = form.secret_key
+  const limit = Number(form.upload_limit_mbps)
+  if (Number.isInteger(limit) && limit >= 0) out.upload_limit_mbps = limit
+  return out
+}
+
+function messageOf(e) {
+  return e?.body?.detail || e?.message || 'The request failed.'
+}
+
+onMounted(async () => {
+  try {
+    apply(await store.loadDestination())
+  } catch (e) {
+    loadError.value = `Couldn't load the destination: ${messageOf(e)}`
+  }
+})
+
+async function onSave() {
+  saving.value = true
+  savedNote.value = ''
+  testResult.value = null
+  try {
+    apply(await store.saveDestination(fields()))
+    savedNote.value = 'Saved.'
+  } catch (e) {
+    testResult.value = { ok: false, message: `Not saved: ${messageOf(e)}` }
+  } finally {
+    saving.value = false
+  }
+}
+
+async function onTest() {
+  testing.value = true
+  savedNote.value = ''
+  testResult.value = null
+  try {
+    testResult.value = await store.testDestination(fields())
+  } catch (e) {
+    testResult.value = { ok: false, message: messageOf(e) }
+  } finally {
+    testing.value = false
+  }
+}
+
+async function onRemove() {
+  saving.value = true
+  try {
+    apply(await store.removeDestination())
+    testResult.value = null
+    savedNote.value = 'Removed.'
+    confirmRemove.value = false
+  } catch (e) {
+    testResult.value = { ok: false, message: `Not removed: ${messageOf(e)}` }
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<style scoped>
+.fc-dest-row { display: flex; gap: 12px; flex-wrap: wrap; }
+.fc-dest-row > :first-child { flex: 1 1 200px; }
+.fc-dest-region { flex: 0 1 160px; }
+.fc-dest-limit { max-width: 260px; }
+</style>

frontend/src/components/settings/BackupRunsTable.vue

@@ -4,6 +4,7 @@
       <tr>
         <th>When</th>
         <th>Status</th>
+        <th>Saved to</th>
         <th class="text-right">Duration</th>
         <th class="text-right">Size</th>
         <th>Tag</th>
@@ -20,6 +21,15 @@
             {{ statusIcon(r.status) }}
           </v-icon>
           {{ r.status }}
+          <div
+            v-if="r.error" class="fc-run-error text-caption text-error" :title="r.error"
+          >{{ r.error }}</div>
+        </td>
+        <td :title="r.offsite ? `${r.offsite.endpoint} · ${r.offsite.key}` : ''">
+          <template v-if="r.offsite">
+            <v-icon size="small" class="mr-1">mdi-cloud-check-outline</v-icon>{{ r.offsite.bucket }}
+          </template>
+          <span v-else class="fc-muted">This server</span>
         </td>
         <td class="text-right fc-tabular">{{ formatDuration(r) }}</td>
         <td class="text-right fc-tabular">{{ formatBytes(r.size_bytes) }}</td>
@@ -30,7 +40,8 @@
           <span v-else class="fc-muted">—</span>
         </td>
         <td class="text-right">
-          <KebabMenu :label="`Actions for backup ${r.id}`">
+          <span v-if="r.offsite" class="fc-muted">—</span>
+          <KebabMenu v-else :label="`Actions for backup ${r.id}`">
             <v-list-item
               :title="r.tag ? 'Untag' : 'Tag…'"
               @click="$emit('tag', r)"
@@ -47,7 +58,7 @@
         </td>
       </tr>
       <tr v-if="!runs.length">
-        <td colspan="6" class="text-center fc-muted py-4">No backups yet.</td>
+        <td colspan="7" class="text-center fc-muted py-4">{{ emptyText }}</td>
       </tr>
     </tbody>
   </v-table>
@@ -57,7 +68,10 @@
 import { formatRelative as fmtRelative } from '../../utils/date.js'
 import KebabMenu from '../common/KebabMenu.vue'
 
-defineProps({ runs: { type: Array, default: () => [] } })
+defineProps({
+  runs: { type: Array, default: () => [] },
+  emptyText: { type: String, default: 'No backups yet.' },
+})
 defineEmits(['restore', 'delete', 'tag'])
 
 function statusIcon(s) {
@@ -97,4 +111,7 @@ function formatRelative(iso) {
 <style scoped>
 .fc-backup-table { background: transparent; }
 .fc-tabular { font-variant-numeric: tabular-nums; }
+.fc-run-error {
+  max-width: 320px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
 </style>

frontend/src/components/settings/LibraryImportCard.vue

@@ -0,0 +1,150 @@
+<template>
+  <!-- Files a download wrote into an artist's folder but never imported: a run
+       that stopped between writing and importing leaves them there, and the
+       walk that marked them seen never returns. Preview lists them per artist;
+       Import queues them as an import batch that attaches each file where it
+       lies. -->
+  <MaintenanceTile
+    icon="mdi-folder-download"
+    title="Import files the library is missing"
+    blurb="Find art in the artists' folders that was downloaded but never imported, and import it where it is."
+    :open="applying || previewing"
+  >
+    <p class="text-body-2 mb-3">
+      A download writes its files into the artist's folder, then imports them.
+      A run that stops in between leaves complete files that no image points
+      at, and later downloads skip them as already seen. This walks every
+      artist's folder for images, videos and archives the library has
+      <strong>no record of</strong>. <strong>Preview</strong> first;
+      <strong>Import</strong> runs them through the normal import where they
+      lie. A file that turns out to be a copy of something already in the
+      library, or that the import filters reject, is removed from disk. Files
+      changed in the last day are left alone, so a download still running is
+      never caught mid-write.
+    </p>
+
+    <div class="d-flex align-center flex-wrap" style="gap: 12px;">
+      <v-btn
+        color="primary" variant="tonal" rounded="pill"
+        :loading="previewing" :disabled="applying" @click="preview"
+      >
+        <v-icon start>mdi-magnify</v-icon> Preview
+      </v-btn>
+      <v-btn
+        color="primary" rounded="pill"
+        :loading="applying"
+        :disabled="previewing || !canApply"
+        @click="confirmOpen = true"
+      >
+        <v-icon start>mdi-folder-download</v-icon> Import
+      </v-btn>
+    </div>
+
+    <v-alert
+      v-if="summary" :type="summaryType" variant="tonal" class="mt-4"
+      density="comfortable"
+    >
+      <span v-if="applied && summary.batch_id">
+        Queued {{ summary.files }} file(s) ({{ humanBytes(summary.bytes) }}) for
+        import. Progress shows in the import queue below and on Activity.
+      </span>
+      <span v-else-if="hasWork">
+        {{ summary.files }} file(s), {{ humanBytes(summary.bytes) }}, are on
+        disk but not in the library<span v-if="summary.archives">, including
+        {{ summary.archives }} archive(s)</span>.
+        Click <strong>Import</strong> to bring them in.
+      </span>
+      <span v-else>Nothing to import: every file in the artists' folders is in the library.</span>
+
+      <div v-if="passedOver" class="mt-1 text-caption">
+        Left alone: {{ summary.recent }} changed in the last day,
+        {{ summary.not_media }} that aren't images, videos or archives, and
+        {{ summary.no_artist }} in folders that match no artist.
+      </div>
+    </v-alert>
+
+    <v-table v-if="hasWork && !applied" density="compact" class="mt-3">
+      <thead>
+        <tr>
+          <th>Artist</th>
+          <th class="text-right">Files</th>
+          <th class="text-right">Size</th>
+          <th>For example</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="a in summary.artists" :key="a.slug">
+          <td>{{ a.slug }}</td>
+          <td class="text-right">{{ a.files }}</td>
+          <td class="text-right">{{ humanBytes(a.bytes) }}</td>
+          <td class="text-caption text-medium-emphasis fc-sample">{{ a.samples[0] }}</td>
+        </tr>
+      </tbody>
+    </v-table>
+
+    <QueueStatusBar queue="import" queue-label="Import" />
+
+    <v-dialog v-model="confirmOpen" max-width="440">
+      <v-card>
+        <v-card-title>Import {{ summary?.files ?? 0 }} file(s)?</v-card-title>
+        <v-card-text class="text-body-2">
+          This imports <strong>{{ summary?.files ?? 0 }}</strong> file(s)
+          ({{ humanBytes(summary?.bytes) }}) where they lie. Any that turn out
+          to be copies of art already in the library, or that the import
+          filters reject, are removed from disk.
+        </v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn variant="text" @click="confirmOpen = false">Cancel</v-btn>
+          <v-btn color="primary" @click="apply">Import</v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { computed, ref } from 'vue'
+
+import { useMaintenanceTask } from '../../composables/useMaintenanceTask.js'
+import { humanBytes } from '../../utils/bytes.js'
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+import QueueStatusBar from './QueueStatusBar.vue'
+
+const confirmOpen = ref(false)
+
+// The walk stats every file in the artists' folders, so on a large library on
+// network storage it can take many minutes. 900 polls × 2s = 30 min, the
+// task's own soft limit.
+const { previewing, applying, summary, applied, preview, apply: applyTask } = useMaintenanceTask({
+  endpoint: '/api/admin/maintenance/import-unimported',
+  storageKey: 'fc.maint.importUnimported',
+  appliedToast: 'Files queued for import',
+  maxPolls: 900,
+})
+
+const hasWork = computed(() => !!summary.value && summary.value.files > 0)
+const canApply = computed(() => hasWork.value && !applied.value)
+const passedOver = computed(() => {
+  const s = summary.value
+  return !!s && (s.recent > 0 || s.not_media > 0 || s.no_artist > 0)
+})
+const summaryType = computed(() => {
+  if (applied.value) return 'success'
+  return hasWork.value ? 'info' : 'success'
+})
+
+function apply () {
+  confirmOpen.value = false
+  applyTask()
+}
+</script>
+
+<style scoped>
+.fc-sample {
+  max-width: 320px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+</style>

frontend/src/components/settings/MaintenancePanel.vue

@@ -63,8 +63,11 @@
 
     <section class="fc-section">
       <h3 class="fc-section__title">Storage</h3>
-      <p class="fc-section__hint">Database + image backups and restore.</p>
+      <p class="fc-section__hint">
+        Database + image backups and restore, and where backups are sent off this server.
+      </p>
       <div class="fc-tile-stack">
+        <BackupDestinationCard />
         <BackupCard />
       </div>
     </section>
@@ -93,6 +96,7 @@ import PostAssociationsCard from './PostAssociationsCard.vue'
 import GpuAgentCard from './GpuAgentCard.vue'
 import AliasTable from './AliasTable.vue'
 import BackupCard from './BackupCard.vue'
+import BackupDestinationCard from './BackupDestinationCard.vue'
 import { useSystemActivityStore } from '../../stores/systemActivity.js'
 
 // Poll queue depths so each task tile's QueueStatusBar shows live pending

frontend/src/stores/backup.js

@@ -8,13 +8,18 @@ export const useBackupStore = defineStore('backup', () => {
 
   const dbRuns = ref([])
   const imagesRuns = ref([])
+  const mediaRuns = ref([])
+  const restoreRuns = ref([])
   const settings = ref(null)
-  const loading = ref({ dbRuns: false, imagesRuns: false, settings: false })
+  const loading = ref({
+    dbRuns: false, imagesRuns: false, mediaRuns: false, restoreRuns: false, settings: false,
+  })
   const lastError = ref(null)
+  const RUNS = { db: dbRuns, images: imagesRuns, media: mediaRuns, restore: restoreRuns }
 
   async function loadRuns(kind) {
-    const targetRef = kind === 'db' ? dbRuns : imagesRuns
-    const loadingKey = kind === 'db' ? 'dbRuns' : 'imagesRuns'
+    const targetRef = RUNS[kind]
+    const loadingKey = `${kind}Runs`
     loading.value[loadingKey] = true
     lastError.value = null
     try {
@@ -101,9 +106,75 @@ export const useBackupStore = defineStore('backup', () => {
     }
   }
 
+  // Off-site destination (an S3 bucket). The secret key goes up but never
+  // comes back: the server answers `secret_set` instead.
+  const destination = ref(null)
+
+  async function loadDestination() {
+    destination.value = await api.get('/api/system/backup/destination')
+    return destination.value
+  }
+
+  async function saveDestination(fields) {
+    destination.value = await api.patch('/api/system/backup/destination', { body: fields })
+    return destination.value
+  }
+
+  async function removeDestination() {
+    destination.value = await api.delete('/api/system/backup/destination')
+    return destination.value
+  }
+
+  // Resolves to {ok, message}; an unreachable bucket is a result, not a throw.
+  async function testDestination(fields) {
+    return api.post('/api/system/backup/destination/test', { body: fields })
+  }
+
+  // How much of the library is in the off-site bucket:
+  // {configured, files_total, files_sent, bytes_total, bytes_sent}.
+  const mediaCoverage = ref(null)
+
+  async function loadMediaCoverage() {
+    try {
+      mediaCoverage.value = await api.get('/api/system/backup/media')
+    } catch (e) {
+      lastError.value = e.message
+    }
+  }
+
+  // Restoring from the bucket. Dumps arrive newest first, each with the
+  // `confirm` text a restore of it asks for.
+  async function listOffsiteDumps() {
+    const body = await api.get('/api/system/backup/offsite/dumps')
+    return body.dumps || []
+  }
+
+  async function restoreFromOffsite(key, confirm) {
+    lastError.value = null
+    try {
+      await api.post('/api/system/backup/offsite/restore', { body: { key, confirm } })
+    } catch (e) {
+      lastError.value = e.message
+      throw e
+    }
+  }
+
+  async function fetchMissingFiles() {
+    lastError.value = null
+    try {
+      await api.post('/api/system/backup/offsite/fetch-files', { body: {} })
+    } catch (e) {
+      lastError.value = e.message
+      throw e
+    }
+  }
+
   return {
-    dbRuns, imagesRuns, settings, loading, lastError,
+    dbRuns, imagesRuns, mediaRuns, restoreRuns, mediaCoverage, loadMediaCoverage,
+    listOffsiteDumps, restoreFromOffsite, fetchMissingFiles,
+    settings, loading, lastError,
     loadRuns, triggerBackup, restore, deleteRun, setTag,
     loadSettings, patchSettings,
+    destination, loadDestination, saveDestination, removeDestination, testDestination,
   }
 })

frontend/src/views/CleanupView.vue

@@ -22,13 +22,15 @@
       <h3 class="fc-section__title">Duplicates &amp; leftovers</h3>
       <p class="fc-section__hint">
         Tidy post records, duplicates, locked-preview leftovers and attachments
-        that outlived what they belonged to.
+        that outlived what they belonged to, and import downloads that never
+        made it into the library.
       </p>
       <div class="fc-tile-grid">
         <PostMaintenanceCard />
         <VideoDedupCard />
         <GatedPurgeCard />
         <AttachmentReclaimCard />
+        <LibraryImportCard />
       </div>
     </section>
 
@@ -63,6 +65,7 @@ import PostMaintenanceCard from '../components/settings/PostMaintenanceCard.vue'
 import VideoDedupCard from '../components/settings/VideoDedupCard.vue'
 import GatedPurgeCard from '../components/settings/GatedPurgeCard.vue'
 import AttachmentReclaimCard from '../components/settings/AttachmentReclaimCard.vue'
+import LibraryImportCard from '../components/settings/LibraryImportCard.vue'
 import TagMaintenanceCard from '../components/settings/TagMaintenanceCard.vue'
 import DangerZoneCard from '../components/settings/DangerZoneCard.vue'
 </script>

tests/fake_s3.py

@@ -0,0 +1,110 @@
+"""An in-process S3 bucket for round-trip tests: put, multipart upload,
+get, and ListObjectsV2, kept in memory. It doesn't check signatures; the
+signing has its own tests against AWS's published vectors. Like Fabled
+Archives, it refuses to replace an object that is already there.
+
+    with FakeS3() as s3:
+        target = s3.target()
+        ...
+        s3.objects  # {key: bytes}
+"""
+from __future__ import annotations
+
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, unquote, urlsplit
+from xml.sax.saxutils import escape
+
+from backend.app.services.backup_s3 import S3Target
+
+BUCKET = "curator"
+
+
+class FakeS3:
+    def __init__(self):
+        self.objects: dict[str, bytes] = {}
+        self.uploads: dict[str, dict[int, bytes]] = {}
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _parts(self):
+                u = urlsplit(self.path)
+                path = unquote(u.path).lstrip("/")
+                bucket, _, key = path.partition("/")
+                query = parse_qs(u.query, keep_blank_values=True)   # `?uploads` has no value
+                return bucket, key, {k: v[0] for k, v in query.items()}
+
+            def _reply(self, status, body=b"", headers=None):
+                self.send_response(status)
+                for name, value in (headers or {}).items():
+                    self.send_header(name, value)
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                if self.command != "HEAD":
+                    self.wfile.write(body)
+
+            def _body(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                return self.rfile.read(length) if length else b""
+
+            def do_PUT(self):
+                _, key, q = self._parts()
+                body = self._body()
+                if "uploadId" in q:
+                    outer.uploads[q["uploadId"]][int(q["partNumber"])] = body
+                    return self._reply(200, headers={"ETag": f'"p{q["partNumber"]}"'})
+                if key in outer.objects:
+                    return self._reply(403, b"<Error><Code>AccessDenied</Code></Error>")
+                outer.objects[key] = body
+                return self._reply(200)
+
+            def do_POST(self):
+                _, key, q = self._parts()
+                self._body()
+                if "uploads" in q:
+                    upload_id = f"u{len(outer.uploads) + 1}"
+                    outer.uploads[upload_id] = {}
+                    return self._reply(200, (
+                        "<InitiateMultipartUploadResult>"
+                        f"<UploadId>{upload_id}</UploadId>"
+                        "</InitiateMultipartUploadResult>").encode())
+                parts = outer.uploads.pop(q["uploadId"])
+                outer.objects[key] = b"".join(parts[n] for n in sorted(parts))
+                return self._reply(200, b"<CompleteMultipartUploadResult/>")
+
+            def do_DELETE(self):
+                _, _, q = self._parts()
+                outer.uploads.pop(q.get("uploadId", ""), None)
+                return self._reply(204)
+
+            def do_GET(self):
+                _, key, q = self._parts()
+                if q.get("list-type") == "2":
+                    prefix = q.get("prefix", "")
+                    items = "".join(
+                        f"<Contents><Key>{escape(k)}</Key><Size>{len(v)}</Size>"
+                        "<LastModified>2026-01-01T00:00:00Z</LastModified></Contents>"
+                        for k, v in sorted(outer.objects.items()) if k.startswith(prefix)
+                    )
+                    return self._reply(200, f"<ListBucketResult>{items}</ListBucketResult>".encode())
+                if key not in outer.objects:
+                    return self._reply(404, b"<Error><Code>NoSuchKey</Code></Error>")
+                return self._reply(200, outer.objects[key])
+
+            def log_message(self, *args):
+                pass
+
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+
+    def __enter__(self):
+        self.thread.start()
+        return self
+
+    def __exit__(self, *exc):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+    def target(self) -> S3Target:
+        host, port = self.httpd.server_address
+        return S3Target(f"http://{host}:{port}", BUCKET, "AK", "SK")

tests/test_api_admin.py

@@ -708,3 +708,22 @@ async def test_trigger_reclaim_attachments_threads_apply(client, monkeypatch):
     )
     assert resp.status_code == 202
     assert calls[0][1] == {"dry_run": False}
+
+
+@pytest.mark.asyncio
+async def test_trigger_import_unimported_defaults_to_preview(client, monkeypatch):
+    """An empty body previews: the apply removes files the library rejects."""
+    from backend.app.tasks import admin as admin_tasks
+
+    calls = []
+    monkeypatch.setattr(
+        admin_tasks.import_unimported_files_task, "delay", _fake_delay(calls)
+    )
+    resp = await client.post("/api/admin/maintenance/import-unimported", json={})
+    assert resp.status_code == 202
+    assert calls[0][1] == {"dry_run": True}
+
+    resp = await client.post(
+        "/api/admin/maintenance/import-unimported", json={"dry_run": False},
+    )
+    assert calls[1][1] == {"dry_run": False}

tests/test_api_system_backup.py

@@ -232,6 +232,27 @@ async def test_restore_rejects_non_ok_status(client, db):
     assert body["error"] == "not_restorable"
 
 
+@pytest.mark.asyncio
+async def test_an_off_site_dump_is_not_restored_from_this_screen(client, db):
+    db.add(BackupRun(
+        kind="db", status="ok", tag=None, triggered_by="nightly",
+        started_at=datetime.now(UTC), finished_at=datetime.now(UTC),
+        manifest={"offsite": {"endpoint": "http://archives.example:8081",
+                              "bucket": "curator", "key": "database/x.dump"}},
+    ))
+    await db.commit()
+    run = (await (await client.get("/api/system/backup/runs?kind=db&limit=1")).get_json())[
+        "runs"][0]
+    assert run["offsite"]["bucket"] == "curator"
+
+    resp = await client.post(
+        f"/api/system/backup/runs/{run['id']}/restore",
+        json={"confirm": f"restore-db-{run['id']}"},
+    )
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "not_restorable"
+
+
 # --- DELETE /runs/<id> ----------------------------------------------
 
 
@@ -322,3 +343,244 @@ async def test_patch_settings_rejects_keep_n_below_min(client):
         json={"backup_db_keep_last_n": 0},
     )
     assert resp.status_code == 400
+
+
+# --- /destination ---------------------------------------------------
+
+
+@pytest.fixture
+def _sealing_key(tmp_path, monkeypatch):
+    from backend.app.services import backup_destination
+    monkeypatch.setattr(backup_destination, "KEY_PATH", tmp_path / "credential_key.b64")
+
+
+_DEST = {
+    "endpoint": "http://archives.example:8081/",
+    "bucket": "curator",
+    "access_key": "AKEXAMPLE",
+    "region": "",
+    "secret_key": "s3cr3t-example",
+}
+
+
+@pytest.mark.asyncio
+async def test_destination_saves_and_never_returns_the_secret(client, db_sync, _sealing_key):
+    from backend.app.models import ImportSettings
+
+    resp = await client.patch("/api/system/backup/destination", json=_DEST)
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body == {
+        "endpoint": "http://archives.example:8081", "bucket": "curator",
+        "access_key": "AKEXAMPLE", "region": "us-east-1",
+        "secret_set": True, "configured": True, "upload_limit_mbps": 200,
+    }
+    assert "s3cr3t-example" not in str(await (await client.get(
+        "/api/system/backup/destination")).get_json())
+    row = db_sync.execute(select(ImportSettings).where(ImportSettings.id == 1)).scalar_one()
+    db_sync.refresh(row)
+    assert row.backup_s3_secret_sealed and "s3cr3t-example" not in row.backup_s3_secret_sealed
+
+    from backend.app.services import backup_destination
+    assert backup_destination.unseal(row.backup_s3_secret_sealed) == "s3cr3t-example"
+
+
+@pytest.mark.asyncio
+async def test_destination_blank_secret_keeps_the_saved_one(client, db_sync, _sealing_key):
+    from backend.app.models import ImportSettings
+    from backend.app.services import backup_destination
+
+    await client.patch("/api/system/backup/destination", json=_DEST)
+    resp = await client.patch(
+        "/api/system/backup/destination", json={**_DEST, "bucket": "other", "secret_key": ""},
+    )
+    assert (await resp.get_json())["bucket"] == "other"
+    row = db_sync.execute(select(ImportSettings).where(ImportSettings.id == 1)).scalar_one()
+    db_sync.refresh(row)
+    assert backup_destination.unseal(row.backup_s3_secret_sealed) == "s3cr3t-example"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("patch, word", [
+    ({"endpoint": "archives.example:8081"}, "http://"),
+    ({"endpoint": "ftp://archives.example"}, "http://"),
+    ({"bucket": "curator/sub"}, "bucket"),
+    ({"access_key": 5}, "access_key"),
+])
+async def test_destination_rejects_what_cant_be_an_s3_target(client, _sealing_key, patch, word):
+    resp = await client.patch("/api/system/backup/destination", json={**_DEST, **patch})
+    assert resp.status_code == 400
+    assert word in (await resp.get_json())["detail"]
+
+
+@pytest.mark.asyncio
+async def test_destination_remove_forgets_everything(client, _sealing_key):
+    await client.patch("/api/system/backup/destination", json=_DEST)
+    resp = await client.delete("/api/system/backup/destination")
+    assert await resp.get_json() == {
+        "endpoint": "", "bucket": "", "access_key": "", "region": "us-east-1",
+        "secret_set": False, "configured": False, "upload_limit_mbps": 200,
+    }
+
+
+@pytest.mark.asyncio
+async def test_destination_test_uses_the_form_and_the_saved_secret(
+    client, _sealing_key, monkeypatch,
+):
+    from backend.app.services import backup_destination
+
+    seen = []
+
+    def fake_check(target):
+        seen.append(target)
+        return {"ok": True, "message": "Reached it."}
+
+    monkeypatch.setattr(backup_destination, "check_target", fake_check)
+    await client.patch("/api/system/backup/destination", json=_DEST)
+    resp = await client.post(
+        "/api/system/backup/destination/test",
+        json={**_DEST, "bucket": "typed-not-saved", "secret_key": ""},
+    )
+    assert await resp.get_json() == {"ok": True, "message": "Reached it."}
+    assert seen[0].bucket == "typed-not-saved"
+    assert seen[0].secret_key == "s3cr3t-example"
+    assert seen[0].endpoint == "http://archives.example:8081"
+
+
+@pytest.mark.asyncio
+async def test_destination_test_names_what_is_missing(client, _sealing_key):
+    await client.delete("/api/system/backup/destination")
+    resp = await client.post(
+        "/api/system/backup/destination/test",
+        json={"endpoint": "http://archives.example:8081", "bucket": "curator"},
+    )
+    body = await resp.get_json()
+    assert body["ok"] is False
+    assert body["message"] == "Not tested: fill in the access key, secret key."
+
+
+@pytest.mark.asyncio
+async def test_destination_test_reports_an_unreachable_bucket_as_a_result(
+    client, _sealing_key, monkeypatch,
+):
+    from backend.app.services import backup_destination
+    from backend.app.services.backup_s3 import S3Error
+
+    def refuse(target, **kw):
+        raise S3Error("Couldn't reach http://archives.example:8081: nothing is listening there.")
+
+    monkeypatch.setattr(backup_destination, "list_objects", refuse)
+    resp = await client.post("/api/system/backup/destination/test", json=_DEST)
+    assert resp.status_code == 200
+    assert await resp.get_json() == {
+        "ok": False,
+        "message": "Couldn't reach http://archives.example:8081: nothing is listening there.",
+    }
+
+
+@pytest.mark.asyncio
+async def test_the_upload_limit_saves_and_a_missing_one_keeps_it(client, _sealing_key):
+    resp = await client.patch(
+        "/api/system/backup/destination", json={**_DEST, "upload_limit_mbps": 50},
+    )
+    assert (await resp.get_json())["upload_limit_mbps"] == 50
+    resp = await client.patch("/api/system/backup/destination", json=_DEST)
+    assert (await resp.get_json())["upload_limit_mbps"] == 50
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("limit", [-1, 2.5, "fast", True])
+async def test_an_upload_limit_that_isnt_a_whole_number_is_refused(client, _sealing_key, limit):
+    resp = await client.patch(
+        "/api/system/backup/destination", json={**_DEST, "upload_limit_mbps": limit},
+    )
+    assert resp.status_code == 400
+    assert "upload_limit_mbps" in (await resp.get_json())["detail"]
+
+
+# ── restoring from the off-site bucket ──────────────────────────────────────
+
+
+@pytest.fixture
+def _saved_bucket(monkeypatch):
+    from backend.app.services import backup_destination
+    from backend.app.services.backup_s3 import S3Target
+
+    target = S3Target("http://archives.example:8081", "curator", "AK", "SK")
+    monkeypatch.setattr(backup_destination, "saved_target", lambda settings: target)
+    dispatched = []
+    monkeypatch.setattr("backend.app.tasks.backup.restore_offsite_task.delay",
+                        lambda **kw: dispatched.append(kw))
+    return dispatched
+
+
+_DUMP = "database/fabledcurator-20261107T134258Z.dump"
+
+
+@pytest.mark.asyncio
+async def test_the_bucket_dumps_are_listed_with_their_confirmation(
+    client, _saved_bucket, monkeypatch,
+):
+    from backend.app.services import backup_restore
+
+    monkeypatch.setattr(backup_restore, "list_dumps", lambda target: [
+        backup_restore.Dump(_DUMP, "20261107T134258Z", 3222868924),
+    ])
+    resp = await client.get("/api/system/backup/offsite/dumps")
+    assert resp.status_code == 200
+    assert (await resp.get_json())["dumps"] == [{
+        "key": _DUMP, "ts": "20261107T134258Z", "size_bytes": 3222868924,
+        "confirm": "restore-offsite-20261107T134258Z",
+    }]
+
+
+@pytest.mark.asyncio
+async def test_a_restore_needs_the_dump_typed_back(client, _saved_bucket):
+    resp = await client.post("/api/system/backup/offsite/restore",
+                             json={"key": _DUMP, "confirm": "yes"})
+    assert resp.status_code == 400
+    assert (await resp.get_json())["expected"] == "restore-offsite-20261107T134258Z"
+    assert _saved_bucket == []
+
+    resp = await client.post("/api/system/backup/offsite/restore", json={
+        "key": _DUMP, "confirm": "restore-offsite-20261107T134258Z"})
+    assert resp.status_code == 202
+    assert _saved_bucket == [{"dump_key": _DUMP}]
+
+
+@pytest.mark.asyncio
+async def test_a_restore_waits_while_a_backup_runs(client, _saved_bucket, db_sync):
+    db_sync.add(BackupRun(kind="db", status="running", triggered_by="nightly",
+                          started_at=datetime.now(UTC), manifest={}))
+    db_sync.commit()
+    resp = await client.post("/api/system/backup/offsite/restore", json={
+        "key": _DUMP, "confirm": "restore-offsite-20261107T134258Z"})
+    assert resp.status_code == 409
+    assert "db backup is running" in (await resp.get_json())["detail"]
+    resp = await client.post("/api/system/backup/offsite/fetch-files", json={})
+    assert resp.status_code == 409
+    assert _saved_bucket == []
+
+
+@pytest.mark.asyncio
+async def test_fetching_missing_files_leaves_the_database(client, _saved_bucket):
+    resp = await client.post("/api/system/backup/offsite/fetch-files", json={})
+    assert resp.status_code == 202
+    assert _saved_bucket == [{"files_only": True}]
+
+
+@pytest.mark.asyncio
+async def test_restoring_needs_a_destination(client):
+    resp = await client.get("/api/system/backup/offsite/dumps")
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "no_destination"
+
+
+@pytest.mark.asyncio
+async def test_restore_runs_are_listed_as_their_own_kind(client, db_sync):
+    db_sync.add(BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                          started_at=datetime.now(UTC), manifest={"phase": "files"}))
+    db_sync.commit()
+    resp = await client.get("/api/system/backup/runs?kind=restore")
+    runs = (await resp.get_json())["runs"]
+    assert [r["status"] for r in runs] == ["restoring"]

tests/test_backup_media.py

@@ -0,0 +1,326 @@
+"""The off-site copy of the library's files (services/backup_media.py and the
+backup_media_task chunk loop): each image and attachment goes to the bucket
+once, by sha256, the work list is what isn't there yet, and a file that can't
+be sent is reported and tried again rather than stopping the run."""
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import (
+    Artist,
+    BackupBlob,
+    BackupRun,
+    ImageRecord,
+    Post,
+    PostAttachment,
+)
+from backend.app.services import backup_media
+from backend.app.services.backup_s3 import ListPage, S3Error, S3Target, StoredObject
+
+pytestmark = pytest.mark.integration
+
+TARGET = S3Target("http://archives.example:8081", "curator", "AK", "SK")
+TID = "http://archives.example:8081/curator"
+
+
+def _sha(c: str) -> str:
+    return c * 64
+
+
+def _image(db_sync, tmp_path, c, body=b"img", ext=".jpg"):
+    path = tmp_path / f"{c}{ext}"
+    path.write_bytes(body)
+    db_sync.add(ImageRecord(path=str(path), sha256=_sha(c), size_bytes=len(body),
+                            mime="image/jpeg", origin="imported_filesystem"))
+    return path
+
+
+def _attachment(db_sync, tmp_path, c, body=b"zip", name="set.zip"):
+    path = tmp_path / f"{c}-{name}"
+    path.write_bytes(body)
+    db_sync.add(PostAttachment(sha256=_sha(c), path=str(path), original_filename=name,
+                               ext=".zip", size_bytes=len(body)))
+    return path
+
+
+# ── keys and the work list ──────────────────────────────────────────────────
+
+
+def test_keys_are_content_addressed_under_media():
+    sha = "abcd" + "0" * 60
+    assert backup_media.blob_key(sha, "/images/x/Pic.JPG") == f"media/ab/cd/{sha}.jpg"
+    assert backup_media.blob_key(sha, "/images/x/noext") == f"media/ab/cd/{sha}"
+    assert backup_media.blob_key(sha, "/images/x/a.we ird") == f"media/ab/cd/{sha}"
+
+
+def test_the_work_list_is_every_file_once_that_the_bucket_lacks(db_sync, tmp_path):
+    _image(db_sync, tmp_path, "a")
+    _image(db_sync, tmp_path, "b")
+    _attachment(db_sync, tmp_path, "c")
+    # The same archive held by a post as well is one file to send.
+    artist = Artist(name="Bea", slug="bea")
+    db_sync.add(artist)
+    db_sync.flush()
+    post = Post(artist_id=artist.id, external_post_id="p1")
+    db_sync.add(post)
+    db_sync.flush()
+    db_sync.add(PostAttachment(post_id=post.id, sha256=_sha("c"),
+                               path=str(tmp_path / "c-copy.zip"),
+                               original_filename="set.zip", ext=".zip", size_bytes=3))
+    db_sync.add(BackupBlob(target=TID, sha256=_sha("b"), key="media/bb", size_bytes=3))
+    # A row for another bucket doesn't count for this one.
+    db_sync.add(BackupBlob(target="http://other/bucket", sha256=_sha("a"), key="k",
+                           size_bytes=3))
+    db_sync.commit()
+
+    shas = [b.sha256 for b in backup_media.pending(db_sync, TID)]
+    assert shas == [_sha("a"), _sha("c")]
+    assert [b.sha256 for b in backup_media.pending(db_sync, TID, after=_sha("a"))] == [_sha("c")]
+
+    cov = backup_media.coverage(db_sync, TID)
+    assert cov == {"files_total": 3, "bytes_total": 9, "files_sent": 1, "bytes_sent": 3}
+
+
+# ── sending one file ────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def puts(monkeypatch):
+    sent = []
+    monkeypatch.setattr(backup_media, "put_file",
+                        lambda t, key, path, **kw: sent.append(("whole", key, kw)))
+    monkeypatch.setattr(backup_media, "put_file_in_parts",
+                        lambda t, key, path, **kw: sent.append(("parts", key, kw)))
+    return sent
+
+
+def test_a_file_is_signed_with_its_recorded_sha(db_sync, tmp_path, puts):
+    path = _image(db_sync, tmp_path, "a")
+    blob = backup_media.Blob(_sha("a"), str(path), 3, "image/jpeg")
+    key = backup_media.send(TARGET, blob, tmp_path, None)
+    assert key == f"media/aa/aa/{_sha('a')}.jpg"
+    (how, sent_key, kw) = puts[0]
+    assert (how, sent_key) == ("whole", key)
+    assert kw["payload_sha256"] == _sha("a") and kw["content_type"] == "image/jpeg"
+
+
+def test_a_large_file_goes_in_parts(db_sync, tmp_path, puts, monkeypatch):
+    monkeypatch.setattr(backup_media, "MULTIPART_OVER", 2)
+    path = _attachment(db_sync, tmp_path, "c")
+    backup_media.send(TARGET, backup_media.Blob(_sha("c"), str(path), 3, None), tmp_path, None)
+    assert puts[0][0] == "parts"
+    assert puts[0][2]["sha256"] == _sha("c")
+
+
+def test_a_missing_or_changed_file_is_refused_before_sending(db_sync, tmp_path, puts):
+    gone = backup_media.Blob(_sha("a"), str(tmp_path / "gone.jpg"), 3, None)
+    with pytest.raises(S3Error, match="not on disk"):
+        backup_media.send(TARGET, gone, tmp_path, None)
+    path = _image(db_sync, tmp_path, "b", body=b"longer now")
+    changed = backup_media.Blob(_sha("b"), str(path), 3, None)
+    with pytest.raises(S3Error, match="when imported"):
+        backup_media.send(TARGET, changed, tmp_path, None)
+    assert puts == []
+
+
+def test_a_refusal_for_an_object_already_there_counts_as_sent(db_sync, tmp_path, monkeypatch):
+    def refused(*a, **kw):
+        raise S3Error("HTTP 403 AccessDenied: append-only.")
+    monkeypatch.setattr(backup_media, "put_file", refused)
+    monkeypatch.setattr(backup_media, "object_present", lambda t, key, size: True)
+    path = _image(db_sync, tmp_path, "a")
+    key = backup_media.send(TARGET, backup_media.Blob(_sha("a"), str(path), 3, None),
+                            tmp_path, None)
+    assert key.startswith("media/aa/aa/")
+
+
+# ── the run ─────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def run_env(monkeypatch, tmp_path):
+    monkeypatch.setattr("backend.app.tasks.backup.IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(
+        "backend.app.services.backup_destination.saved_target", lambda settings: TARGET,
+    )
+    queued = []
+    from backend.app.tasks import backup as tasks
+    monkeypatch.setattr(tasks.backup_media_task, "delay", lambda **kw: queued.append(kw))
+    return queued
+
+
+def _send_all_but(bad_sha):
+    def send(target, blob, images_root, pacer):
+        if blob.sha256 == bad_sha:
+            raise S3Error("HTTP 503: busy.")
+        return backup_media.blob_key(blob.sha256, blob.path)
+    return send
+
+
+def test_a_run_sends_what_is_missing_and_reports_what_failed(
+    db_sync, tmp_path, run_env, monkeypatch,
+):
+    from backend.app.tasks.backup import backup_media_task
+    for c in "abc":
+        _image(db_sync, tmp_path, c)
+    db_sync.commit()
+    monkeypatch.setattr(backup_media, "send", _send_all_but(_sha("b")))
+
+    result = backup_media_task(triggered_by="manual")
+    assert result["continues"] is False
+    row = db_sync.get(BackupRun, result["backup_run_id"])
+    db_sync.refresh(row)
+    assert (row.kind, row.status, row.size_bytes) == ("media", "ok", 6)
+    assert row.manifest["sent"] == 2 and row.manifest["failed"] == 1
+    assert row.manifest["offsite"]["bucket"] == "curator"
+    assert "1 file(s) weren't sent" in row.error
+    assert row.manifest["failures"][0]["error"] == "HTTP 503: busy."
+    sent = set(db_sync.execute(select(BackupBlob.sha256)).scalars())
+    assert sent == {_sha("a"), _sha("c")}
+
+    # The next run tries only the file that failed.
+    monkeypatch.setattr(backup_media, "send", _send_all_but(None))
+    again = backup_media_task(triggered_by="manual")
+    row = db_sync.get(BackupRun, again["backup_run_id"])
+    db_sync.refresh(row)
+    assert row.manifest["sent"] == 1 and row.error is None
+
+
+def test_a_run_out_of_time_queues_its_next_chunk(db_sync, tmp_path, run_env, monkeypatch):
+    from backend.app.tasks import backup as tasks
+    for c in "ab":
+        _image(db_sync, tmp_path, c)
+    db_sync.commit()
+    monkeypatch.setattr(backup_media, "send", _send_all_but(None))
+    monkeypatch.setattr(tasks, "MEDIA_CHUNK_SECONDS", -1)
+
+    result = tasks.backup_media_task(triggered_by="manual")
+    assert result["continues"] is True
+    row = db_sync.get(BackupRun, result["backup_run_id"])
+    db_sync.refresh(row)
+    assert row.status == "running" and row.last_progress_at is not None
+    # The next chunk carries the token of the chunk that queued it.
+    assert run_env == [{"run_id": row.id, "after": row.manifest["chunk"]}]
+
+
+def _going(db_sync, chunk):
+    row = BackupRun(kind="media", status="running", triggered_by="manual",
+                    started_at=datetime.now(UTC), size_bytes=0,
+                    manifest={"sent": 0, "failed": 0, "failures": [], "cursor": "",
+                              "chunk": chunk})
+    db_sync.add(row)
+    db_sync.commit()
+    return row
+
+
+def test_only_the_chunk_queued_by_the_one_carrying_the_run_goes_on(
+    db_sync, tmp_path, run_env, monkeypatch,
+):
+    from backend.app.tasks.backup import backup_media_task
+    _image(db_sync, tmp_path, "a")
+    row = _going(db_sync, "live")
+    monkeypatch.setattr(backup_media, "send", _send_all_but(None))
+
+    # A killed chunk's own message, delivered again, is dropped.
+    stale = backup_media_task(run_id=row.id, after="earlier")
+    assert "another chunk" in stale["skipped"]
+    assert backup_media_task(run_id=row.id, after="live")["continues"] is False
+    db_sync.refresh(row)
+    assert row.status == "ok" and row.manifest["sent"] == 1
+
+
+def test_a_resume_takes_the_run_and_the_chunk_it_replaced_stops(
+    db_sync, tmp_path, run_env, monkeypatch,
+):
+    from backend.app.tasks import backup as tasks
+    for c in "ab":
+        _image(db_sync, tmp_path, c)
+    row = _going(db_sync, "killed")
+
+    def send_then_lose_the_run(target, blob, images_root, pacer):
+        # While this chunk sends its first file, a newer one takes the run.
+        with tasks._sync_session_factory()() as s:
+            other = s.get(BackupRun, row.id)
+            other.manifest = {**other.manifest, "chunk": "newer"}
+            s.commit()
+        return backup_media.blob_key(blob.sha256, blob.path)
+    monkeypatch.setattr(backup_media, "send", send_then_lose_the_run)
+
+    result = tasks.backup_media_task(run_id=row.id, resume=True)
+    assert "took the run over" in result["skipped"]
+    assert run_env == []
+    db_sync.refresh(row)
+    assert row.status == "running" and row.manifest["chunk"] == "newer"
+    assert row.manifest["sent"] == 0 and row.manifest["cursor"] == ""
+
+
+def test_a_restart_resumes_every_media_run_still_going(db_sync, run_env):
+    from backend.app.tasks.backup import resume_offsite_runs
+    going = _going(db_sync, "killed")
+    db_sync.add(BackupRun(kind="media", status="ok", triggered_by="manual",
+                          started_at=datetime.now(UTC), manifest={}))
+    db_sync.commit()
+    assert resume_offsite_runs()["media"] == [going.id]
+    assert run_env == [{"run_id": going.id, "resume": True}]
+
+
+def test_a_second_run_waits_for_the_one_going(db_sync, run_env):
+    from backend.app.tasks.backup import backup_media_task
+    now = datetime.now(UTC)
+    db_sync.add(BackupRun(kind="media", status="running", triggered_by="nightly",
+                          started_at=now, manifest={}))
+    db_sync.commit()
+    assert "already running" in backup_media_task(triggered_by="manual")["skipped"]
+
+
+def test_without_a_destination_the_run_fails_with_why(db_sync, monkeypatch):
+    from backend.app.tasks.backup import backup_media_task
+    monkeypatch.setattr(
+        "backend.app.services.backup_destination.saved_target", lambda settings: None,
+    )
+    with pytest.raises(S3Error):
+        backup_media_task(triggered_by="manual")
+    row = db_sync.execute(select(BackupRun).where(BackupRun.kind == "media")).scalar_one()
+    assert row.status == "error" and "No off-site destination" in row.error
+
+
+def test_a_long_media_run_is_judged_stalled_by_its_heartbeat(db_sync):
+    from backend.app.tasks.maintenance import recover_stalled_backup_runs
+    long_ago = datetime.now(UTC) - timedelta(hours=20)
+    alive = BackupRun(kind="media", status="running", triggered_by="nightly",
+                      started_at=long_ago, last_progress_at=datetime.now(UTC), manifest={})
+    silent = BackupRun(kind="media", status="running", triggered_by="nightly",
+                       started_at=long_ago, last_progress_at=long_ago, manifest={})
+    db_sync.add_all([alive, silent])
+    db_sync.commit()
+    assert recover_stalled_backup_runs() == 1
+    db_sync.refresh(alive)
+    db_sync.refresh(silent)
+    assert (alive.status, silent.status) == ("running", "error")
+
+
+# ── reconcile ───────────────────────────────────────────────────────────────
+
+
+def test_reconcile_resends_what_the_bucket_lost_and_adopts_what_it_has(
+    db_sync, tmp_path, monkeypatch,
+):
+    _image(db_sync, tmp_path, "a")            # row, but the bucket lost it
+    _image(db_sync, tmp_path, "b")            # in the bucket, no row
+    _image(db_sync, tmp_path, "c")            # neither
+    key_a = backup_media.blob_key(_sha("a"), "x.jpg")
+    key_b = backup_media.blob_key(_sha("b"), "x.jpg")
+    db_sync.add(BackupBlob(target=TID, sha256=_sha("a"), key=key_a, size_bytes=3))
+    db_sync.commit()
+    pages = iter([
+        ListPage([StoredObject("media/zz/other", 1, "")], "next"),
+        ListPage([StoredObject(key_b, 3, "")], None),
+    ])
+    monkeypatch.setattr(backup_media, "list_objects", lambda *a, **kw: next(pages))
+    monkeypatch.setattr(backup_media.time, "sleep", lambda s: None)
+
+    assert backup_media.reconcile(db_sync, TARGET) == {
+        "listed": 2, "dropped": 1, "adopted": 1,
+    }
+    assert set(db_sync.execute(select(BackupBlob.sha256)).scalars()) == {_sha("b")}

tests/test_backup_restore.py

@@ -0,0 +1,326 @@
+"""Restoring from the off-site bucket (services/backup_restore.py and
+restore_offsite_task): the database from a dated dump, then every library
+file back at the path its row records, checked against its sha256 on arrival.
+The round trip at the bottom backs a seeded library up to an in-process S3
+bucket, wipes it, restores it, and compares every file."""
+import hashlib
+import shutil
+import time
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from sqlalchemy import func, select
+
+from backend.app.models import Artist, BackupRun, ImageRecord, Post, PostAttachment
+from backend.app.services import backup_restore
+from backend.app.services.backup_s3 import ListPage, ObjectMissing, S3Error, S3Target, StoredObject
+from tests.fake_s3 import FakeS3
+
+pytestmark = pytest.mark.integration
+
+TARGET = S3Target("http://archives.example:8081", "curator", "AK", "SK")
+
+
+def _sha(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _file(root, rel, data):
+    p = root / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_bytes(data)
+    return p
+
+
+def _image(db_sync, path, data, mime="image/jpeg"):
+    db_sync.add(ImageRecord(path=str(path), sha256=_sha(data), size_bytes=len(data),
+                            mime=mime, origin="imported_filesystem"))
+
+
+# ── dumps ───────────────────────────────────────────────────────────────────
+
+
+def test_dumps_are_listed_newest_first_and_other_keys_ignored(monkeypatch):
+    page = ListPage([
+        StoredObject("database/fabledcurator-20261101T034000Z.dump", 10, ""),
+        StoredObject("database/fabledcurator-20261107T134258Z.dump", 30, ""),
+        StoredObject("database/notes.txt", 1, ""),
+    ], None)
+    monkeypatch.setattr(backup_restore, "list_objects", lambda *a, **kw: page)
+    dumps = backup_restore.list_dumps(TARGET)
+    assert [d.ts for d in dumps] == ["20261107T134258Z", "20261101T034000Z"]
+    assert backup_restore.find_dump(TARGET, "latest").size_bytes == 30
+    assert backup_restore.find_dump(TARGET, dumps[1].key).ts == "20261101T034000Z"
+    with pytest.raises(S3Error, match="not among"):
+        backup_restore.find_dump(TARGET, "database/fabledcurator-1.dump")
+
+
+def test_an_empty_bucket_has_no_dump_to_restore(monkeypatch):
+    monkeypatch.setattr(backup_restore, "list_objects", lambda *a, **kw: ListPage([], None))
+    with pytest.raises(S3Error, match="no database dumps"):
+        backup_restore.find_dump(TARGET, None)
+
+
+# ── one file ────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def fetches(monkeypatch):
+    got = []
+
+    def get_file(target, key, path, *, sha256=None, size=None, pacer=None):
+        got.append(key)
+        path.write_bytes(b"x" * size)
+    monkeypatch.setattr(backup_restore, "get_file", get_file)
+    return got
+
+
+def test_a_file_on_disk_at_its_size_is_left_alone(tmp_path, fetches):
+    p = _file(tmp_path, "a/one.jpg", b"xxx")
+    f = backup_restore.LibraryFile("a" * 64, (str(p),), 3)
+    assert backup_restore.restore_file(TARGET, f, None, tmp_path, None) == "present"
+    assert fetches == []
+
+
+def test_a_missing_file_is_fetched_by_its_key_to_its_path(tmp_path, fetches):
+    sha = "abcd" + "0" * 60
+    f = backup_restore.LibraryFile(sha, (str(tmp_path / "bea/one.JPG"),), 4)
+    assert backup_restore.restore_file(TARGET, f, None, tmp_path, None) == "restored"
+    assert fetches == [f"media/ab/cd/{sha}.jpg"]
+    assert (tmp_path / "bea/one.JPG").read_bytes() == b"xxxx"
+
+
+def test_a_recorded_key_is_used_over_the_computed_one(tmp_path, fetches):
+    f = backup_restore.LibraryFile("e" * 64, (str(tmp_path / "x.png"),), 2)
+    backup_restore.restore_file(TARGET, f, "media/ee/ee/recorded.png", tmp_path, None)
+    assert fetches == ["media/ee/ee/recorded.png"]
+
+
+def test_one_fetch_fills_every_path_that_shares_the_file(tmp_path, fetches):
+    paths = (str(tmp_path / "p1/set.zip"), str(tmp_path / "p2/set.zip"))
+    f = backup_restore.LibraryFile("c" * 64, paths, 5)
+    assert backup_restore.restore_file(TARGET, f, None, tmp_path, None) == "restored"
+    assert len(fetches) == 1
+    assert (tmp_path / "p2/set.zip").read_bytes() == b"xxxxx"
+    # With one copy left on disk, the other is copied, not fetched.
+    (tmp_path / "p1/set.zip").unlink()
+    assert backup_restore.restore_file(TARGET, f, None, tmp_path, None) == "copied"
+    assert len(fetches) == 1
+
+
+def test_a_path_outside_the_library_is_refused(tmp_path, fetches):
+    f = backup_restore.LibraryFile("d" * 64, ("/etc/passwd",), 3)
+    with pytest.raises(S3Error, match="outside"):
+        backup_restore.restore_file(TARGET, f, None, tmp_path, None)
+    f = backup_restore.LibraryFile("d" * 64, (str(tmp_path / "../escape.jpg"),), 3)
+    with pytest.raises(S3Error, match="outside"):
+        backup_restore.restore_file(TARGET, f, None, tmp_path, None)
+    assert fetches == []
+
+
+def test_the_work_list_gives_each_file_every_path(db_sync, tmp_path):
+    _image(db_sync, tmp_path / "a.jpg", b"one")
+    artist = Artist(name="Bea", slug="bea")
+    db_sync.add(artist)
+    db_sync.flush()
+    post = Post(artist_id=artist.id, external_post_id="p1")
+    db_sync.add(post)
+    db_sync.flush()
+    for i, post_id in enumerate((None, post.id)):
+        db_sync.add(PostAttachment(post_id=post_id, sha256=_sha(b"zip"),
+                                   path=str(tmp_path / f"{i}/set.zip"),
+                                   original_filename="set.zip", ext=".zip", size_bytes=3))
+    db_sync.commit()
+    files = {f.sha256: f for f in backup_restore.library_files(db_sync)}
+    assert files[_sha(b"zip")].paths == (str(tmp_path / "0/set.zip"), str(tmp_path / "1/set.zip"))
+    assert files[_sha(b"one")].paths == (str(tmp_path / "a.jpg"),)
+
+
+# ── the file phase as a run ─────────────────────────────────────────────────
+
+
+@pytest.fixture
+def run_env(monkeypatch, tmp_path):
+    from backend.app.tasks import backup as tasks
+    monkeypatch.setattr(tasks, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(
+        "backend.app.services.backup_destination.saved_target", lambda settings: TARGET,
+    )
+    queued, thumbs = [], []
+    monkeypatch.setattr(tasks.restore_offsite_task, "delay", lambda **kw: queued.append(kw))
+    monkeypatch.setattr("backend.app.tasks.thumbnail.backfill_thumbnails.delay",
+                        lambda: thumbs.append(True))
+    return queued, thumbs
+
+
+def test_fetching_missing_files_counts_each_outcome(db_sync, tmp_path, run_env, monkeypatch):
+    from backend.app.tasks.backup import restore_offsite_task
+    _file(tmp_path, "here.jpg", b"here")
+    _image(db_sync, tmp_path / "here.jpg", b"here")
+    _image(db_sync, tmp_path / "gone.jpg", b"gone")
+    _image(db_sync, tmp_path / "lost.jpg", b"lost")
+    db_sync.commit()
+
+    def get_file(target, key, path, *, sha256=None, size=None, pacer=None):
+        if sha256 == _sha(b"lost"):
+            raise ObjectMissing(f"{key} is not in the curator bucket.")
+        path.write_bytes(b"gone")
+    monkeypatch.setattr(backup_restore, "get_file", get_file)
+
+    result = restore_offsite_task(files_only=True)
+    assert result["continues"] is False
+    row = db_sync.get(BackupRun, result["backup_run_id"])
+    db_sync.refresh(row)
+    m = row.manifest
+    assert (row.kind, row.status) == ("restore", "restored")
+    assert (m["restored"], m["present"], m["missing"], m["failed"]) == (1, 1, 1, 0)
+    assert "1 file(s) aren't in the bucket" in row.error
+    assert (tmp_path / "gone.jpg").read_bytes() == b"gone"
+    queued, thumbs = run_env
+    assert queued == [] and thumbs == [True]
+
+
+def test_a_restore_out_of_time_queues_its_next_chunk(db_sync, tmp_path, run_env, monkeypatch):
+    from backend.app.tasks import backup as tasks
+    _image(db_sync, tmp_path / "a.jpg", b"aa")
+    db_sync.commit()
+    monkeypatch.setattr(tasks, "RESTORE_CHUNK_SECONDS", -1)
+    result = tasks.restore_offsite_task(files_only=True)
+    queued, _ = run_env
+    assert result["continues"] is True
+    row = db_sync.get(BackupRun, result["backup_run_id"])
+    db_sync.refresh(row)
+    assert row.status == "restoring" and row.last_progress_at is not None
+    # The next chunk carries the token of the chunk that queued it.
+    assert queued == [{"run_id": row.id, "after": row.manifest["chunk"]}]
+
+
+def test_a_restart_resumes_the_file_phase_and_drops_the_stale_chunk(
+    db_sync, tmp_path, run_env,
+):
+    from backend.app.tasks.backup import restore_offsite_task, resume_offsite_runs
+    _file(tmp_path, "a.jpg", b"aa")
+    _image(db_sync, tmp_path / "a.jpg", b"aa")
+    now = datetime.now(UTC)
+    files = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                      started_at=now, manifest={"phase": "files", "cursor": "",
+                                                "failures": [], "chunk": "killed"})
+    loading = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                        started_at=now, manifest={"phase": "database"})
+    db_sync.add_all([files, loading])
+    db_sync.commit()
+    queued, _ = run_env
+
+    # A restore stopped while loading its database isn't resumed.
+    resume_offsite_runs()
+    assert queued == [{"run_id": files.id, "resume": True}]
+
+    # The killed chunk's own message, delivered again, is dropped.
+    assert "another chunk" in restore_offsite_task(run_id=files.id, after="earlier")["skipped"]
+    done = restore_offsite_task(run_id=files.id, resume=True)
+    assert done["continues"] is False
+    db_sync.refresh(files)
+    assert files.status == "restored" and files.manifest["present"] == 1
+
+
+def test_a_restore_waits_for_a_backup_that_is_running(db_sync, run_env):
+    from backend.app.tasks.backup import restore_offsite_task
+    db_sync.add(BackupRun(kind="media", status="running", triggered_by="nightly",
+                          started_at=datetime.now(UTC), manifest={}))
+    db_sync.commit()
+    assert restore_offsite_task(files_only=True)["skipped"] == "a media backup is running"
+
+
+def test_backups_wait_while_a_restore_is_going(db_sync, monkeypatch):
+    from backend.app.tasks.backup import backup_db_task, backup_media_task
+    db_sync.add(BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                          started_at=datetime.now(UTC), manifest={}))
+    db_sync.commit()
+    assert backup_db_task(triggered_by="nightly")["skipped"] == "a restore is going"
+    assert backup_media_task(triggered_by="nightly")["skipped"] == "a restore is going"
+
+
+def test_a_long_restore_is_judged_stalled_by_its_heartbeat(db_sync):
+    from backend.app.tasks.maintenance import recover_stalled_backup_runs
+    long_ago = datetime.now(UTC) - timedelta(hours=20)
+    alive = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                      started_at=long_ago, last_progress_at=datetime.now(UTC), manifest={})
+    silent = BackupRun(kind="restore", status="restoring", triggered_by="restore",
+                       started_at=long_ago, last_progress_at=long_ago, manifest={})
+    db_sync.add_all([alive, silent])
+    db_sync.commit()
+    assert recover_stalled_backup_runs() == 1
+    db_sync.refresh(alive)
+    db_sync.refresh(silent)
+    assert (alive.status, silent.status) == ("restoring", "error")
+
+
+# ── the round trip ──────────────────────────────────────────────────────────
+
+
+def test_a_library_comes_back_whole_from_the_bucket(db_sync, tmp_path, monkeypatch):
+    """Back the library up to a bucket, lose the files and change the
+    database, restore from the bucket: the rows are the backup's and every
+    file is back at its path with its bytes."""
+    from backend.app.services import backup_destination
+    from backend.app.tasks import backup as tasks
+
+    images = tmp_path / "images"
+    library = {
+        "bea/one.jpg": b"first picture",
+        "bea/two.png": b"second picture, a png",
+        "attachments/ab/set.zip": b"an archive of pictures" * 50,
+    }
+    for rel, data in library.items():
+        _file(images, rel, data)
+    _image(db_sync, images / "bea/one.jpg", library["bea/one.jpg"])
+    _image(db_sync, images / "bea/two.png", library["bea/two.png"], mime="image/png")
+    db_sync.add(PostAttachment(sha256=_sha(library["attachments/ab/set.zip"]),
+                               path=str(images / "attachments/ab/set.zip"),
+                               original_filename="set.zip", ext=".zip",
+                               size_bytes=len(library["attachments/ab/set.zip"])))
+    db_sync.commit()
+
+    monkeypatch.setattr(tasks, "IMAGES_ROOT", images)
+    monkeypatch.setattr(backup_destination, "seal", lambda secret: f"sealed:{secret}")
+    queued = []
+    monkeypatch.setattr(tasks.restore_offsite_task, "delay", lambda **kw: queued.append(kw))
+    monkeypatch.setattr("backend.app.tasks.thumbnail.backfill_thumbnails.delay", lambda: None)
+
+    with FakeS3() as s3:
+        monkeypatch.setattr(backup_destination, "saved_target", lambda settings: s3.target())
+        dumped = tasks.backup_db_task(triggered_by="manual")
+        tasks.backup_media_task(triggered_by="manual")
+        dump_key = [k for k in s3.objects if k.startswith("database/")][0]
+        assert len([k for k in s3.objects if k.startswith("media/")]) == 3
+
+        # Lose the files, and change the database after the dump.
+        shutil.rmtree(images)
+        db_sync.execute(ImageRecord.__table__.delete().where(
+            ImageRecord.sha256 == _sha(library["bea/two.png"])))
+        db_sync.add(Artist(name="Added later", slug="added-later"))
+        db_sync.commit()
+        time.sleep(1.1)   # the safety dump gets its own second-resolution name
+
+        first = tasks.restore_offsite_task(dump_key=dump_key)
+        assert queued == [{"run_id": first["backup_run_id"]}]
+        done = tasks.restore_offsite_task(run_id=first["backup_run_id"])
+        assert done["continues"] is False
+        dumps_now = [k for k in s3.objects if k.startswith("database/")]
+
+    # The database is the dump's: a fresh session, since the restore ended
+    # every connection that was open.
+    with tasks._sync_session_factory()() as s:
+        assert s.execute(select(func.count()).select_from(ImageRecord)).scalar() == 2
+        assert s.execute(select(Artist).where(Artist.slug == "added-later")).first() is None
+        row = s.get(BackupRun, done["backup_run_id"])
+        assert row.status == "restored" and row.error is None
+        assert row.manifest["restored"] == 3
+        assert row.manifest["dump"]["key"] == dump_key
+        # The database it replaced was saved to the bucket first.
+        assert row.manifest["saved_before"] in dumps_now and len(dumps_now) == 2
+        assert s.get(BackupRun, dumped["backup_run_id"]).status == "ok"
+        settings = s.execute(select(tasks.ImportSettings)).scalars().first()
+        assert settings.backup_s3_secret_sealed == "sealed:SK"
+    for rel, data in library.items():
+        assert (images / rel).read_bytes() == data

tests/test_backup_s3.py

@@ -0,0 +1,398 @@
+"""The backup destination's S3 client (services/backup_s3.py): signatures match
+AWS's published Signature Version 4 examples, and the calls send and read what
+S3 expects, over a real HTTP connection to a local stand-in server."""
+import hashlib
+import socket
+import threading
+from datetime import UTC, datetime
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+from backend.app.services import backup_s3 as s3
+
+# AWS's example credentials and moment ("Signature Calculations for the
+# Authorization Header", Amazon S3 API reference).
+KEY_ID = "AKIAIOSFODNN7EXAMPLE"
+SECRET = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+AT = datetime(2013, 5, 24, tzinfo=UTC)
+
+
+def _signature(headers):
+    return headers["Authorization"].rsplit("Signature=", 1)[1]
+
+
+def test_aws_example_get_object():
+    h = s3.sign("GET", "https://examplebucket.s3.amazonaws.com/test.txt",
+                {"Range": "bytes=0-9"}, s3.EMPTY_SHA256, KEY_ID, SECRET, "us-east-1", AT)
+    assert "SignedHeaders=host;range;x-amz-content-sha256;x-amz-date," in h["Authorization"]
+    assert "Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request" in h[
+        "Authorization"]
+    assert _signature(h) == "f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41"
+
+
+def test_aws_example_list_objects():
+    h = s3.sign("GET", "https://examplebucket.s3.amazonaws.com/?max-keys=2&prefix=J", {},
+                s3.EMPTY_SHA256, KEY_ID, SECRET, "us-east-1", AT)
+    assert _signature(h) == "34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7"
+
+
+def test_a_changed_secret_changes_the_signature():
+    url = "https://examplebucket.s3.amazonaws.com/test.txt"
+    a = s3.sign("GET", url, {}, s3.EMPTY_SHA256, KEY_ID, SECRET, "us-east-1", AT)
+    b = s3.sign("GET", url, {}, s3.EMPTY_SHA256, KEY_ID, SECRET + "x", "us-east-1", AT)
+    assert _signature(a) != _signature(b)
+
+
+def test_paths_are_path_style_and_keys_are_escaped():
+    t = s3.S3Target("http://archives.example:8081/s3", "curator", KEY_ID, SECRET)
+    assert t.url("media/ab/cd/abcd.jpg") == "http://archives.example:8081/s3/curator/media/ab/cd/abcd.jpg"
+    assert t.url() == "http://archives.example:8081/s3/curator/"
+    assert t.url("a b+c.jpg") == "http://archives.example:8081/s3/curator/a%20b%2Bc.jpg"
+
+
+# ── Calls, against a local stand-in ─────────────────────────────────────────
+
+
+class _Server:
+    """A local HTTP server that records each request and answers with
+    `reply(handler) -> (status, body)` or `(status, body, headers)`."""
+
+    def __init__(self, reply):
+        self.seen = []
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _serve(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                outer.seen.append({
+                    "method": self.command, "path": self.path,
+                    "headers": {k.lower(): v for k, v in self.headers.items()},
+                    "body": self.rfile.read(length) if length else b"",
+                })
+                status, body, *extra = reply(self)
+                self.send_response(status)
+                for name, value in (extra[0] if extra else {}).items():
+                    self.send_header(name, value)
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            do_GET = do_PUT = do_POST = do_DELETE = _serve
+
+            def log_message(self, *args):
+                pass
+
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+
+    def __enter__(self):
+        self.thread.start()
+        return self
+
+    def __exit__(self, *exc):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+    def target(self, bucket="curator"):
+        host, port = self.httpd.server_address
+        return s3.S3Target(f"http://{host}:{port}", bucket, KEY_ID, SECRET)
+
+
+def test_put_streams_the_file_signed(tmp_path):
+    f = tmp_path / "abcd.jpg"
+    f.write_bytes(b"x" * 5000)
+    with _Server(lambda h: (200, b"")) as srv:
+        s3.put_file(srv.target(), "media/ab/cd/abcd.jpg", f, content_type="image/jpeg")
+    req = srv.seen[0]
+    assert req["method"] == "PUT"
+    assert req["path"] == "/curator/media/ab/cd/abcd.jpg"
+    assert req["body"] == b"x" * 5000
+    assert req["headers"]["x-amz-content-sha256"] == s3.file_sha256(f)
+    assert req["headers"]["content-type"] == "image/jpeg"
+    assert req["headers"]["authorization"].startswith(
+        "AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/")
+
+
+def test_put_signs_with_a_known_sha_without_rereading(tmp_path, monkeypatch):
+    f = tmp_path / "b.bin"
+    f.write_bytes(b"y")
+    monkeypatch.setattr(s3, "file_sha256", lambda p: pytest.fail("read the file twice"))
+    with _Server(lambda h: (200, b"")) as srv:
+        s3.put_file(srv.target(), "b.bin", f, payload_sha256="a" * 64)
+    assert srv.seen[0]["headers"]["x-amz-content-sha256"] == "a" * 64
+
+
+def test_a_refusal_says_why(tmp_path):
+    f = tmp_path / "b.bin"
+    f.write_bytes(b"x")
+    body = b"<Error><Code>SignatureDoesNotMatch</Code><Message>no</Message></Error>"
+    with _Server(lambda h: (403, body)) as srv, pytest.raises(
+        s3.S3Error, match="HTTP 403 SignatureDoesNotMatch: the secret key is wrong",
+    ):
+        s3.put_file(srv.target(), "b.bin", f)
+
+
+def test_a_web_server_at_the_address_is_named_as_not_s3():
+    """An address without the S3 port lands on whatever serves the default
+    port, and its plain 404 says nothing about S3."""
+    page = b"<html><body><h1>404 Not Found</h1></body></html>"
+    with _Server(lambda h: (404, page)) as srv, pytest.raises(
+        s3.S3Error,
+        match=r"HTTP 404: the address answered, but not as S3 — check the scheme and the port",
+    ):
+        s3.list_objects(srv.target())
+
+
+def test_a_server_error_without_a_body_is_not_blamed_on_the_port():
+    with _Server(lambda h: (503, b"")) as srv, pytest.raises(
+        s3.S3Error, match="HTTP 503: Service Unavailable",
+    ) as err:
+        s3.list_objects(srv.target())
+    assert "port" not in str(err.value)
+
+
+def test_nothing_listening_says_check_the_port():
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        port = sock.getsockname()[1]
+    target = s3.S3Target(f"http://127.0.0.1:{port}", "curator", KEY_ID, SECRET)
+    with pytest.raises(s3.S3Error, match="nothing is listening there"):
+        s3.list_objects(target)
+
+
+def test_list_reads_contents_and_the_next_page_token():
+    xml = b"""<?xml version="1.0" encoding="UTF-8"?>
+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+  <Name>curator</Name><KeyCount>2</KeyCount><IsTruncated>true</IsTruncated>
+  <NextContinuationToken>tok-2</NextContinuationToken>
+  <Contents><Key>database/fabledcurator-20261105T030000Z.dump</Key><Size>1200</Size>
+    <LastModified>2026-11-05T03:00:01.000Z</LastModified></Contents>
+  <Contents><Key>database/fabledcurator-20261106T030000Z.dump</Key><Size>1300</Size>
+    <LastModified>2026-11-06T03:00:01.000Z</LastModified></Contents>
+</ListBucketResult>"""
+    with _Server(lambda h: (200, xml)) as srv:
+        page = s3.list_objects(srv.target(), "database/", continuation="tok-1")
+    path = srv.seen[0]["path"]
+    assert path.startswith("/curator/?")
+    assert "list-type=2" in path and "prefix=database%2F" in path
+    assert "continuation-token=tok-1" in path
+    assert page.next_token == "tok-2"
+    assert page.objects == [
+        s3.StoredObject("database/fabledcurator-20261105T030000Z.dump", 1200,
+                        "2026-11-05T03:00:01.000Z"),
+        s3.StoredObject("database/fabledcurator-20261106T030000Z.dump", 1300,
+                        "2026-11-06T03:00:01.000Z"),
+    ]
+
+
+def test_a_listing_that_isnt_xml_is_named():
+    with _Server(lambda h: (200, b"hello")) as srv, pytest.raises(
+        s3.S3Error, match="isn't S3's XML",
+    ):
+        s3.list_objects(srv.target())
+
+
+def test_get_streams_the_object_to_disk(tmp_path):
+    with _Server(lambda h: (200, b"y" * 3000)) as srv:
+        out = tmp_path / "b.dump"
+        s3.get_file(srv.target(), "database/b.dump", out)
+    assert srv.seen[0]["path"] == "/curator/database/b.dump"
+    assert srv.seen[0]["headers"]["x-amz-content-sha256"] == s3.EMPTY_SHA256
+    assert out.read_bytes() == b"y" * 3000
+    assert not (tmp_path / "b.dump.partial").exists()
+
+
+def test_a_refused_get_says_so_and_writes_nothing(tmp_path):
+    body = b"<Error><Code>AccessDenied</Code></Error>"
+    out = tmp_path / "b.dump"
+    with _Server(lambda h: (403, body)) as srv, pytest.raises(s3.S3Error, match="b.dump"):
+        s3.get_file(srv.target(), "b.dump", out)
+    assert not out.exists()
+    assert not (tmp_path / "b.dump.partial").exists()
+
+
+def test_a_missing_object_is_named_as_missing(tmp_path):
+    body = b"<Error><Code>NoSuchKey</Code></Error>"
+    with _Server(lambda h: (404, body)) as srv, pytest.raises(s3.ObjectMissing):
+        s3.get_file(srv.target(), "media/ab/cd/x.jpg", tmp_path / "x.jpg")
+
+
+def test_a_fetched_file_is_kept_only_when_its_fingerprint_matches(tmp_path):
+    good = b"picture bytes"
+    sha = hashlib.sha256(good).hexdigest()
+    with _Server(lambda h: (200, good)) as srv:
+        s3.get_file(srv.target(), "k", tmp_path / "ok.jpg", sha256=sha, size=len(good))
+    assert (tmp_path / "ok.jpg").read_bytes() == good
+
+    with _Server(lambda h: (200, b"other bytes!!")) as srv, \
+            pytest.raises(s3.S3Error, match="different fingerprint"):
+        s3.get_file(srv.target(), "k", tmp_path / "bad.jpg", sha256=sha, size=len(good))
+    assert not (tmp_path / "bad.jpg").exists()
+    assert not (tmp_path / "bad.jpg.partial").exists()
+
+
+def test_a_short_download_is_not_kept(tmp_path):
+    with _Server(lambda h: (200, b"abc")) as srv, pytest.raises(s3.S3Error, match="3 bytes"):
+        s3.get_file(srv.target(), "k", tmp_path / "x", size=10)
+    assert not (tmp_path / "x").exists()
+
+
+def test_a_paced_download_counts_its_bytes(tmp_path):
+    pacer = s3.Pacer(None)
+    taken = []
+    pacer.take = taken.append
+    with _Server(lambda h: (200, b"z" * 2500)) as srv:
+        s3.get_file(srv.target(), "k", tmp_path / "z", pacer=pacer)
+    assert sum(taken) == 2500
+
+
+# ── Multipart ───────────────────────────────────────────────────────────────
+
+_STARTED = b"<InitiateMultipartUploadResult><UploadId>up1</UploadId></InitiateMultipartUploadResult>"
+
+
+def _bucket(parts_reply=None, complete=(200, b"<CompleteMultipartUploadResult/>")):
+    """A stand-in bucket for one multipart upload: starts it, takes parts (each
+    answered by `parts_reply(n)`, an ETag by default) and completes it."""
+    def reply(h):
+        if h.command == "POST" and h.path.endswith("?uploads"):
+            return 200, _STARTED
+        if h.command == "PUT":
+            n = int(h.path.split("partNumber=")[1].split("&")[0])
+            return parts_reply(n) if parts_reply else (200, b"", {"ETag": f'"e{n}"'})
+        if h.command == "POST":
+            return complete
+        return 204, b""
+    return reply
+
+
+def test_an_upload_sends_its_parts_then_joins_them_in_order():
+    with _Server(_bucket()) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        up.add(b"first,")
+        up.add(b"second")
+        up.complete()
+    start, one, two, done = srv.seen
+    assert (start["method"], start["path"]) == ("POST", "/curator/database/x.dump?uploads")
+    assert one["path"] == "/curator/database/x.dump?partNumber=1&uploadId=up1"
+    assert two["body"] == b"second"
+    assert two["headers"]["x-amz-content-sha256"] == hashlib.sha256(b"second").hexdigest()
+    assert done["path"] == "/curator/database/x.dump?uploadId=up1"
+    assert done["body"].index(b'"e1"') < done["body"].index(b'"e2"')
+    assert (up.parts, up.size) == (2, len(b"first,second"))
+
+
+def test_a_refused_start_says_why():
+    with _Server(lambda h: (403, b"<Error><Code>AccessDenied</Code></Error>")) as srv:
+        with pytest.raises(s3.S3Error, match="the key isn't allowed"):
+            s3.Upload(srv.target(), "database/x.dump")
+
+
+def test_a_completion_refused_under_a_200_is_a_failure():
+    error = (200, b"<Error><Code>InternalError</Code><Message>disk full</Message></Error>")
+    with _Server(_bucket(complete=error)) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        up.add(b"data")
+        with pytest.raises(s3.S3Error, match="Finishing the upload"):
+            up.complete()
+
+
+def test_nothing_sent_is_not_completed():
+    with _Server(_bucket()) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        with pytest.raises(s3.S3Error, match="Nothing was sent"):
+            up.complete()
+
+
+def test_a_busy_bucket_gets_the_part_again_after_a_rest(monkeypatch):
+    rests = []
+    monkeypatch.setattr(s3.time, "sleep", rests.append)
+    answers = iter([(503, b"", {"Retry-After": "7"}), (200, b"", {"ETag": '"e1"'})])
+    with _Server(_bucket(parts_reply=lambda n: next(answers))) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        up.add(b"data")
+    assert rests == [7]
+    assert up.parts == 1
+
+
+def test_a_part_refused_outright_is_not_sent_again(monkeypatch):
+    monkeypatch.setattr(s3.time, "sleep", lambda s: pytest.fail("rested on a refusal"))
+    refused = (403, b"<Error><Code>AccessDenied</Code></Error>")
+    with _Server(_bucket(parts_reply=lambda n: refused)) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        with pytest.raises(s3.S3Error, match="Part 1"):
+            up.add(b"data")
+
+
+def test_a_part_that_never_lands_gives_up_after_the_rests(monkeypatch):
+    rests = []
+    monkeypatch.setattr(s3.time, "sleep", rests.append)
+    with _Server(_bucket(parts_reply=lambda n: (503, b""))) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        with pytest.raises(s3.S3Error, match="Part 1"):
+            up.add(b"data")
+    assert rests == list(s3.PART_RETRY_WAITS)
+
+
+def test_abort_asks_the_bucket_to_drop_the_parts_and_never_raises():
+    with _Server(_bucket()) as srv:
+        up = s3.Upload(srv.target(), "database/x.dump")
+        up.abort()
+        assert srv.seen[-1]["method"] == "DELETE"
+        assert srv.seen[-1]["path"] == "/curator/database/x.dump?uploadId=up1"
+    up.abort()  # the server is gone now: still no exception
+
+
+def test_the_pacer_holds_bytes_to_the_limit(monkeypatch):
+    clock = [0.0]
+    monkeypatch.setattr(s3.time, "monotonic", lambda: clock[0])
+    monkeypatch.setattr(s3.time, "sleep", lambda secs: clock.__setitem__(0, clock[0] + secs))
+    pacer = s3.Pacer(8)                     # 8 Mbit/s = 1,000,000 bytes/s
+    data = b"x" * (3 * s3.CHUNK)
+    assert b"".join(pacer.chunks(data)) == data
+    assert clock[0] == pytest.approx(len(data) / 1_000_000)
+
+
+def test_no_limit_never_waits(monkeypatch):
+    monkeypatch.setattr(s3.time, "sleep", lambda secs: pytest.fail("waited without a limit"))
+    assert b"".join(s3.Pacer(0).chunks(b"y" * (2 * s3.CHUNK + 1))) == b"y" * (2 * s3.CHUNK + 1)
+
+
+def test_a_large_file_is_sent_in_parts_and_checked_against_its_sha(tmp_path, monkeypatch):
+    monkeypatch.setattr(s3, "PART_SIZE", 4)
+    f = tmp_path / "big.zip"
+    f.write_bytes(b"0123456789")
+    with _Server(_bucket()) as srv:
+        sent = s3.put_file_in_parts(srv.target(), "media/x.zip", f,
+                                    sha256=hashlib.sha256(b"0123456789").hexdigest())
+    assert sent == 10
+    assert [r["body"] for r in srv.seen if r["method"] == "PUT"] == [b"0123", b"4567", b"89"]
+    assert srv.seen[-1]["method"] == "POST"             # completed
+
+
+def test_a_file_that_changed_since_import_is_not_completed(tmp_path, monkeypatch):
+    monkeypatch.setattr(s3, "PART_SIZE", 4)
+    f = tmp_path / "big.zip"
+    f.write_bytes(b"0123456789")
+    with _Server(_bucket()) as srv:
+        with pytest.raises(s3.S3Error, match="recorded checksum"):
+            s3.put_file_in_parts(srv.target(), "media/x.zip", f, sha256="0" * 64)
+    assert srv.seen[-1]["method"] == "DELETE"           # aborted, nothing stored
+
+
+def test_a_paced_put_sends_the_same_bytes(tmp_path):
+    f = tmp_path / "a.bin"
+    f.write_bytes(b"z" * (s3.CHUNK + 5))
+    with _Server(lambda h: (200, b"")) as srv:
+        s3.put_file(srv.target(), "a.bin", f, pacer=s3.Pacer(0))
+    assert srv.seen[0]["body"] == b"z" * (s3.CHUNK + 5)
+
+
+def test_presence_is_the_exact_key_at_the_exact_size():
+    listing = (b"<ListBucketResult><Contents><Key>media/a.jpg</Key><Size>3</Size>"
+               b"</Contents></ListBucketResult>")
+    with _Server(lambda h: (200, listing)) as srv:
+        assert s3.object_present(srv.target(), "media/a.jpg", 3)
+        assert not s3.object_present(srv.target(), "media/a.jpg", 4)
+        assert not s3.object_present(srv.target(), "media/a.jp", 3)

tests/test_backup_service.py

@@ -5,6 +5,7 @@ without external binaries. The real subprocess behavior is exercised
 implicitly via the Celery task tests in test_tasks_backup.py.
 """
 import json
+import re
 import subprocess
 from pathlib import Path
 
@@ -28,7 +29,7 @@ def fake_subprocess(monkeypatch):
         stderr = b""
 
     def _write_sentinel(cmd):
-        if cmd[0] == "pg_dump":
+        if "pg_dump" in cmd:
             i = cmd.index("-f")
             Path(cmd[i + 1]).write_bytes(b"-- fake pg_dump\n")
         elif cmd[0] == "tar" and "-cf" in cmd:
@@ -87,7 +88,7 @@ def test_backup_db_strips_sqlalchemy_psycopg_driver(tmp_path, fake_subprocess):
         db_url="postgresql+psycopg://u:p@h/d", images_root=tmp_path,
     )
     cmd = fake_subprocess[0]
-    assert cmd[0] == "pg_dump"
+    assert "pg_dump" in cmd
     assert cmd[-1].startswith("postgresql://")
     assert "+psycopg" not in cmd[-1]
 
@@ -171,11 +172,74 @@ def test_restore_db_drops_schema_then_loads(tmp_path, fake_subprocess):
     assert fake_subprocess[0][0] == "psql"
     assert "-c" in fake_subprocess[0]
     assert "DROP SCHEMA IF EXISTS public CASCADE" in fake_subprocess[0][-1]
-    assert fake_subprocess[1][0] == "pg_restore"
+    assert "pg_terminate_backend" in fake_subprocess[0][-1]
+    assert "pg_restore" in fake_subprocess[1]
     assert "-d" in fake_subprocess[1]
     assert str(dump_path) in fake_subprocess[1]
 
 
+def _pg_restore_says(monkeypatch, stderr_text: bytes):
+    class _Done:
+        returncode = 1
+
+    class _Ok:
+        returncode = 0
+
+    def run(cmd, stderr=None, **kw):
+        if "pg_restore" in cmd:
+            stderr.write(stderr_text)
+            return _Done()
+        return _Ok()
+
+    monkeypatch.setattr("subprocess.run", run)
+
+
+_NEWER_CLIENT = (
+    b'pg_restore: error: could not execute query: ERROR:  unrecognized configuration '
+    b'parameter "transaction_timeout"\nCommand was: SET transaction_timeout = 0;\n'
+)
+
+
+def test_a_newer_pg_restore_setting_what_the_server_lacks_is_not_a_failure(
+    tmp_path, monkeypatch,
+):
+    _pg_restore_says(monkeypatch, _NEWER_CLIENT
+                     + b"pg_restore: warning: errors ignored on restore: 1\n")
+    backup_service.restore_db(db_url="postgresql://u@h/d", sql_path=tmp_path / "x.dump")
+
+
+def test_a_real_error_beside_the_harmless_one_fails_the_restore_with_its_words(
+    tmp_path, monkeypatch,
+):
+    _pg_restore_says(monkeypatch, _NEWER_CLIENT
+                     + b'pg_restore: error: could not execute query: ERROR:  relation '
+                       b'"tag" does not exist\nCommand was: COPY tag FROM stdin;\n'
+                     + b"pg_restore: warning: errors ignored on restore: 2\n")
+    with pytest.raises(backup_service.RestoreFailed, match='relation "tag" does not exist'):
+        backup_service.restore_db(db_url="postgresql://u@h/d", sql_path=tmp_path / "x.dump")
+
+
+def test_a_failed_restore_says_what_pg_restore_said(tmp_path, monkeypatch):
+    class _Done:
+        def __init__(self, code):
+            self.returncode = code
+
+    def run(cmd, stderr=None, **kw):
+        if "pg_restore" in cmd:
+            stderr.write(b"pg_restore: processing data\npg_restore: error: disk full\n")
+            return _Done(1)
+        return _Done(0)
+
+    monkeypatch.setattr("subprocess.run", run)
+    with pytest.raises(backup_service.RestoreFailed, match="error: disk full"):
+        backup_service.restore_db(db_url="postgresql://u@h/d", sql_path=tmp_path / "x.dump")
+
+
+def test_every_dump_leaves_out_account_logins(tmp_path, fake_subprocess):
+    backup_service.backup_db(db_url="postgresql://u@h/d", images_root=tmp_path)
+    assert "--exclude-table-data=credential" in fake_subprocess[0]
+
+
 # --- restore_images --------------------------------------------------
 
 
@@ -284,3 +348,132 @@ def test_run_bounded_fails_fast_when_unkillable(monkeypatch):
     with pytest.raises(subprocess.TimeoutExpired):
         backup_service._run_bounded(["pg_dump"], 1)
     assert killed["n"] == 1
+
+
+# --- backup_db_offsite: pg_dump streamed to the bucket ---------------
+
+
+class _Dump:
+    """A pg_dump stand-in: `output` on stdout, `said` on stderr, exiting with
+    `code` once its output has been read."""
+
+    def __init__(self, output=b"", said=b"", code=0):
+        self.output, self.said, self.code = output, said, code
+        self.cmd = None
+        self.killed = False
+
+    def __call__(self, cmd, stdout=None, stderr=None, **kwargs):
+        import io
+        self.cmd = list(cmd)
+        self.args = cmd
+        self.stdout = io.BytesIO(self.output)
+        stderr.write(self.said)
+        self.returncode = None
+        return self
+
+    def poll(self):
+        return self.returncode
+
+    def wait(self, timeout=None):
+        if self.returncode is None:
+            self.returncode = -9 if self.killed else self.code
+        return self.returncode
+
+    def kill(self):
+        self.killed = True
+
+
+class _Bucket:
+    """Records what an Upload was asked to do instead of sending it."""
+
+    def __init__(self, fail_on_part=None):
+        self.fail_on_part = fail_on_part
+        self.uploads = []
+
+    def __call__(self, target, key, **kwargs):
+        from backend.app.services.backup_s3 import S3Error
+        bucket = self
+
+        class _Upload:
+            def __init__(self):
+                self.key, self.received = key, []
+                self.completed = self.aborted = False
+                bucket.uploads.append(self)
+
+            @property
+            def parts(self):
+                return len(self.received)
+
+            @property
+            def size(self):
+                return sum(len(p) for p in self.received)
+
+            def add(self, data):
+                if bucket.fail_on_part == len(self.received) + 1:
+                    raise S3Error("HTTP 503: busy.")
+                self.received.append(data)
+
+            def complete(self):
+                self.completed = True
+
+            def abort(self):
+                self.aborted = True
+
+        return _Upload()
+
+
+@pytest.fixture
+def offsite(monkeypatch):
+    from backend.app.services import backup_s3
+    monkeypatch.setattr(backup_s3, "PART_SIZE", 4)
+    bucket = _Bucket()
+    monkeypatch.setattr(backup_s3, "Upload", bucket)
+    target = backup_s3.S3Target("http://archives.example:8081", "curator", "AK", "SK")
+    return bucket, target
+
+
+def test_a_dump_streams_to_the_bucket_in_parts_with_nothing_kept_here(offsite, monkeypatch):
+    bucket, target = offsite
+    dump = _Dump(output=b"0123456789")
+    monkeypatch.setattr("subprocess.Popen", dump)
+    result = backup_service.backup_db_offsite(
+        db_url="postgresql+psycopg://u:p@h/d", target=target, limit_mbps=50,
+    )
+    (upload,) = bucket.uploads
+    assert upload.received == [b"0123", b"4567", b"89"]
+    assert upload.completed and not upload.aborted
+    assert re.fullmatch(r"database/fabledcurator-\d{8}T\d{6}Z\.dump", result["key"])
+    assert result["key"] == upload.key
+    assert (result["bucket"], result["size_bytes"], result["parts"]) == ("curator", 10, 3)
+    assert dump.cmd[0] == "nice" and "pg_dump" in dump.cmd and "-Fc" in dump.cmd
+    assert "-f" not in dump.cmd                  # stdout, not a file
+    assert dump.cmd[-1] == "postgresql://u:p@h/d"
+
+
+def test_a_failed_dump_leaves_nothing_in_the_bucket_and_says_why(offsite, monkeypatch):
+    bucket, target = offsite
+    said = b"pg_dump: dumping contents of table x\npg_dump: error: connection lost\n"
+    monkeypatch.setattr("subprocess.Popen", _Dump(output=b"012345", said=said, code=1))
+    with pytest.raises(backup_service.DumpFailed, match="^pg_dump: error: connection lost$"):
+        backup_service.backup_db_offsite(db_url="postgresql://u@h/d", target=target)
+    (upload,) = bucket.uploads
+    assert upload.aborted and not upload.completed
+
+
+def test_a_bucket_that_stops_taking_parts_stops_the_dump(offsite, monkeypatch):
+    from backend.app.services.backup_s3 import S3Error
+    bucket, target = offsite
+    bucket.fail_on_part = 2
+    dump = _Dump(output=b"0123456789")
+    monkeypatch.setattr("subprocess.Popen", dump)
+    with pytest.raises(S3Error):
+        backup_service.backup_db_offsite(db_url="postgresql://u@h/d", target=target)
+    assert dump.killed
+    (upload,) = bucket.uploads
+    assert upload.aborted and not upload.completed
+
+
+def test_dump_names_sort_by_time():
+    assert backup_service.offsite_dump_key("20261107T030000Z") == (
+        "database/fabledcurator-20261107T030000Z.dump"
+    )

tests/test_download_lane_boot.py

@@ -1,7 +1,9 @@
-"""#4433: only the process consuming `download` clears a restart's leftovers.
+"""Each lane picks up only its own restart's leftovers: the process consuming
+`download` clears orphaned walks and platform locks, and the one consuming
+`maintenance_long` resumes off-site backups and restores.
 
 The consolidated container boots four lanes side by side. If the scheduler or
-ml lane ran this too, a lane restarting on its own (supervisord restarts a
+ml lane ran these too, a lane restarting on its own (supervisord restarts a
 crashed program) would close the events of walks that are still running.
 """
 from __future__ import annotations
@@ -42,6 +44,10 @@ def calls(monkeypatch):
         "backend.app.services.platform_lock.release_all_platform_locks",
         lambda: seen.append("release") or 0,
     )
+    monkeypatch.setattr(
+        "backend.app.tasks.backup.resume_offsite_runs",
+        lambda: seen.append("resume") or {},
+    )
     return seen
 
 
@@ -50,12 +56,25 @@ def test_the_download_lane_clears_orphans_and_locks(calls):
     assert calls == ["interrupt", "commit", "release"]
 
 
-@pytest.mark.parametrize("queues", [("maintenance", "scan"), ("ml",), ("maintenance_long",)])
-def test_other_lanes_leave_downloads_alone(calls, queues):
+@pytest.mark.parametrize("queues", [("maintenance", "scan"), ("ml",)])
+def test_other_lanes_leave_downloads_and_backups_alone(calls, queues):
     celery_signals._on_worker_ready(sender=_consumer(*queues))
     assert calls == []
 
 
+def test_the_long_maintenance_lane_resumes_offsite_runs_and_nothing_else(calls):
+    celery_signals._on_worker_ready(sender=_consumer("maintenance_long"))
+    assert calls == ["resume"]
+
+
+def test_a_failed_resume_does_not_stop_the_worker_starting(monkeypatch, calls):
+    def boom():
+        raise RuntimeError("db down")
+
+    monkeypatch.setattr("backend.app.tasks.backup.resume_offsite_runs", boom)
+    celery_signals._on_worker_ready(sender=_consumer("maintenance_long"))  # must not raise
+
+
 def test_unreadable_queues_do_nothing_rather_than_guess(calls):
     celery_signals._on_worker_ready(sender=SimpleNamespace())
     assert calls == []

tests/test_download_service.py

@@ -193,6 +193,69 @@ async def test_download_source_attaches_written_files(
     assert imported_when_marked == [2]
 
 
+@pytest.mark.asyncio
+async def test_import_step_keeps_only_the_files_the_library_needs_on_disk(
+    db, db_sync, tmp_path, seed_artist_and_source,
+):
+    """After the import step, a downloaded image the library took stays where it
+    is, while an archive whose images were extracted (the archive is in the
+    attachments store) and an image the import filters rejected are removed, so
+    nothing is left on disk without a record for a later walk to import again."""
+    import zipfile
+
+    from PIL import Image
+
+    from backend.app.models import PostAttachment
+    from backend.app.services.download_service import DownloadService
+    from backend.app.services.importer import Importer
+
+    _artist, source = seed_artist_and_source
+    images_root = tmp_path / "images"
+    post_dir = images_root / "alice" / "patreon" / "post"
+
+    kept = post_dir / "a.jpg"
+    _make_jpg(kept, split="h")
+    member = tmp_path / "member.jpg"
+    _make_jpg(member, split="v")
+    archive = post_dir / "pack.zip"
+    with zipfile.ZipFile(archive, "w") as z:
+        z.writestr("art.jpg", member.read_bytes())
+    tiny = post_dir / "tiny.png"
+    Image.new("RGB", (16, 16), (200, 30, 30)).save(tiny)  # below min_width
+
+    result = _make_fake_dl_result(
+        success=True, written_paths=[str(kept), str(archive), str(tiny)],
+        files_downloaded=3,
+    )
+    sync_settings = db_sync.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    ).scalar_one()
+    sync_settings.phash_threshold = 0
+    sync_settings.min_width = 32
+    importer = Importer(
+        session=db_sync, images_root=images_root, import_root=images_root,
+        thumbnailer=Thumbnailer(images_root=images_root), settings=sync_settings,
+    )
+    crypto = CredentialCrypto(tmp_path / "key.b64", bootstrap_ok=True)
+    svc = DownloadService(
+        async_session=db, sync_session=db_sync, gdl=_fake_gdl_with_result(result),
+        importer=importer, cred_service=CredentialService(db, crypto),
+    )
+    _stub_patreon_ingester(svc, result)
+    await svc.download_source(source.id)
+
+    assert kept.exists()
+    assert not archive.exists()
+    assert not tiny.exists()
+    # The archive and its image are both still in the library.
+    assert db_sync.execute(
+        select(func.count(PostAttachment.id)).where(
+            PostAttachment.original_filename == "pack.zip"
+        )
+    ).scalar_one() == 1
+    assert db_sync.execute(select(func.count(ImageRecord.id))).scalar_one() == 2
+
+
 @pytest.mark.asyncio
 async def test_download_source_skipped_when_disabled(
     db, db_sync, tmp_path, seed_artist_and_source,

tests/test_external_fetch.py

@@ -108,6 +108,27 @@ def test_mega_collects_new_files(tmp_path, monkeypatch):
     assert res.files[0].name == "film.mp4"
 
 
+def test_mega_folder_link_collects_files_in_subfolders(tmp_path, monkeypatch):
+    """A folder link keeps the folder's tree; every file in it is collected,
+    files already there before the fetch and staging files are not."""
+    (tmp_path / "old.png").write_bytes(b"earlier")
+
+    def fake_mega(url, out_dir, *, timeout):
+        nested = Path(out_dir) / "images" / "2020"
+        nested.mkdir(parents=True)
+        (nested / "kara.png").write_bytes(b"png")
+        (Path(out_dir) / "videos").mkdir()
+        (Path(out_dir) / "videos" / "loop.webm").write_bytes(b"webm")
+        (nested / ".megatmp.AbCd").write_bytes(b"half")
+
+    monkeypatch.setattr(ef, "_run_mega_get", fake_mega)
+    res = fetch_external("mega", "https://mega.nz/folder/x#k", tmp_path)
+    assert res.ok
+    assert sorted(p.relative_to(tmp_path).as_posix() for p in res.files) == [
+        "images/2020/kara.png", "videos/loop.webm",
+    ]
+
+
 def test_unsupported_host(tmp_path):
     res = fetch_external("nope", "https://x", tmp_path)
     assert not res.ok

tests/test_external_worker.py

@@ -251,3 +251,293 @@ def test_downloaded_archive_gets_provenance_and_tagging(db_sync, tmp_path, monke
     # Tagging + thumbnails queued for exactly those member images.
     assert set(tagged) == member_ids
     assert set(thumbed) == member_ids
+
+
+def _link_dir(tmp_path, host, link_id):
+    return tmp_path / f"ext-{host}" / "patreon" / "external" / f"EXT-{host}" / str(link_id)
+
+
+def test_extracted_archive_is_not_left_in_the_link_dir(db_sync, tmp_path, monkeypatch):
+    """An archive whose images were extracted is in the attachments store, so
+    the downloaded copy is removed instead of sitting beside it."""
+    _, link = _seed(db_sync, host="mega")
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+    written = []
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        zpath = dest_dir / "pack.zip"
+        with zipfile.ZipFile(zpath, "w") as z:
+            z.writestr("art.jpg", _structured_jpeg_bytes())
+        written.append(zpath)
+        return FetchResult(files=[zpath], bytes=zpath.stat().st_size)
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    import backend.app.tasks.ml as ml_mod
+    import backend.app.tasks.thumbnail as thumb_mod
+    monkeypatch.setattr(ml_mod.embed_image, "delay", lambda i: None)
+    monkeypatch.setattr(thumb_mod.generate_thumbnail, "delay", lambda i: None)
+
+    out = ext.fetch_external_link(link_id)
+    assert out["images"] >= 1
+    assert not written[0].exists()
+    db_sync.expire_all()
+    assert db_sync.execute(
+        select(func.count(PostAttachment.id))
+        .where(PostAttachment.original_filename == "pack.zip")
+    ).scalar_one() == 1
+
+
+def test_a_failed_fetch_leaves_no_partial_files(db_sync, tmp_path, monkeypatch):
+    """A fetch that fails midway (megatools leaves `.megatmp.*` behind) clears
+    the link's staging dir, so a dead link leaves nothing on disk."""
+    _, link = _seed(db_sync, host="mega")
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        (dest_dir / ".megatmp.AbCd").write_bytes(b"half a game build")
+        return FetchResult(error="megatools dl exit 1: timed out")
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    ext.fetch_external_link(link_id)
+
+    link_dir = _link_dir(tmp_path, "mega", link_id)
+    assert not (link_dir / ".megatmp.AbCd").exists()
+    db_sync.expire_all()
+    assert db_sync.get(ExternalLink, link_id).status == "failed"
+
+
+def test_a_retry_clears_what_a_killed_attempt_left(db_sync, tmp_path, monkeypatch):
+    """Leftovers from an attempt whose worker was killed are removed before the
+    next fetch starts; an image imported in place by an earlier attempt stays."""
+    _, link = _seed(db_sync, host="pixeldrain")
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+    link_dir = _link_dir(tmp_path, "pixeldrain", link_id)
+    link_dir.mkdir(parents=True)
+    leftover = link_dir / "build.zip.part"
+    leftover.write_bytes(b"partial")
+    imported = link_dir / "kept.jpg"
+    imported.write_bytes(_structured_jpeg_bytes())
+    db_sync.add(ImageRecord(
+        path=str(imported), sha256="ext-kept".ljust(64, "x"),
+        size_bytes=imported.stat().st_size, mime="image/jpeg",
+        width=256, height=256, origin="downloaded", integrity_status="ok",
+    ))
+    db_sync.commit()
+    seen_at_fetch = []
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        seen_at_fetch.extend(sorted(p.name for p in dest_dir.iterdir()))
+        return FetchResult(error="HTTP 503")
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    ext.fetch_external_link(link_id)
+
+    assert seen_at_fetch == ["kept.jpg"]
+    assert imported.exists()
+    assert not leftover.exists()
+
+
+def test_a_rejected_download_is_removed(db_sync, tmp_path, monkeypatch):
+    """A downloaded image the import filters reject has no record, so it is
+    removed rather than left in the link's dir."""
+    from backend.app.models import ImportSettings
+
+    _, link = _seed(db_sync, host="dropbox")
+    link_id = link.id
+    settings = db_sync.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    ).scalar_one()
+    settings.min_width = 512
+    db_sync.commit()
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+    written = []
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        f = dest_dir / "small.jpg"  # 256px wide, below min_width
+        f.write_bytes(_structured_jpeg_bytes())
+        written.append(f)
+        return FetchResult(files=[f], bytes=f.stat().st_size)
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    out = ext.fetch_external_link(link_id)
+
+    assert out["images"] == 0
+    assert not written[0].exists()
+    db_sync.expire_all()
+    assert db_sync.get(ExternalLink, link_id).status == "downloaded"
+
+
+def _other_jpeg_bytes():
+    # A second structured image, unlike _structured_jpeg_bytes, so the two
+    # don't near-duplicate each other at import.
+    im = Image.new("RGB", (256, 256))
+    px = im.load()
+    for y in range(256):
+        for x in range(256):
+            px[x, y] = ((x * x) % 256, (y * 3) % 256, (x ^ y) % 256)
+    buf = io.BytesIO()
+    im.save(buf, "JPEG")
+    return buf.getvalue()
+
+
+def test_a_failed_fetch_keeps_complete_files(db_sync, tmp_path, monkeypatch):
+    """A failed fetch removes staging files only. A complete file may be the
+    only copy left once the host has dropped the upload."""
+    _, link = _seed(db_sync, host="mega")
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        (dest_dir / "images").mkdir(parents=True, exist_ok=True)
+        (dest_dir / "images" / "done.jpg").write_bytes(_structured_jpeg_bytes())
+        (dest_dir / "images" / ".megatmp.AbCd").write_bytes(b"half")
+        return FetchResult(error="API call 'f' failed: ENOENT")
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    ext.fetch_external_link(link_id)
+
+    link_dir = _link_dir(tmp_path, "mega", link_id)
+    assert (link_dir / "images" / "done.jpg").exists()
+    assert not (link_dir / "images" / ".megatmp.AbCd").exists()
+
+
+def test_a_successful_fetch_imports_what_an_earlier_attempt_finished(
+    db_sync, tmp_path, monkeypatch,
+):
+    """Complete files an earlier attempt wrote, in subfolders too, are imported
+    with the new fetch's files instead of being deleted or left behind."""
+    _, link = _seed(db_sync, host="mega")
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+    link_dir = _link_dir(tmp_path, "mega", link_id)
+    (link_dir / "pack").mkdir(parents=True)
+    earlier = link_dir / "pack" / "earlier.jpg"
+    earlier.write_bytes(_structured_jpeg_bytes())
+
+    def fake_fetch(host, url, dest_dir, **kwargs):
+        f = dest_dir / "new.jpg"
+        f.write_bytes(_other_jpeg_bytes())
+        return FetchResult(files=[f], bytes=f.stat().st_size)
+
+    monkeypatch.setattr(ext, "fetch_external", fake_fetch)
+    import backend.app.tasks.ml as ml_mod
+    import backend.app.tasks.thumbnail as thumb_mod
+    monkeypatch.setattr(ml_mod.embed_image, "delay", lambda i: None)
+    monkeypatch.setattr(thumb_mod.generate_thumbnail, "delay", lambda i: None)
+
+    out = ext.fetch_external_link(link_id)
+
+    assert out["images"] == 2
+    db_sync.expire_all()
+    paths = set(db_sync.execute(select(ImageRecord.path)).scalars())
+    assert {str(earlier), str(link_dir / "new.jpg")} <= paths
+
+
+def test_sweep_recovers_a_link_whose_worker_died(db_sync, monkeypatch):
+    """A link 'downloading' past the task's hard limit (or with no claim time)
+    counts as a failed attempt and is retried; a fresh claim is left alone."""
+    from datetime import UTC, datetime, timedelta
+
+    _, stale = _seed(db_sync, host="mega", status="downloading")
+    _, unclaimed = _seed(db_sync, host="gdrive", status="downloading")
+    _, fresh = _seed(db_sync, host="dropbox", status="downloading")
+    now = datetime.now(UTC)
+    stale.started_at = now - timedelta(minutes=ext._STALL_MINUTES + 5)
+    fresh.started_at = now - timedelta(minutes=5)
+    db_sync.commit()
+    stale_id, unclaimed_id, fresh_id = stale.id, unclaimed.id, fresh.id
+
+    enqueued = []
+    monkeypatch.setattr(ext.fetch_external_link, "delay", lambda lid: enqueued.append(lid))
+    out = ext.sweep_external_links()
+
+    assert out["recovered"] == 2
+    assert set(enqueued) == {stale_id, unclaimed_id}
+    db_sync.expire_all()
+    for lid in (stale_id, unclaimed_id):
+        row = db_sync.get(ExternalLink, lid)
+        assert (row.status, row.attempts) == ("failed", 1)
+    assert db_sync.get(ExternalLink, fresh_id).status == "downloading"
+
+
+def test_recovery_gives_a_dead_link_one_more_attempt_at_growing_intervals(db_sync, monkeypatch):
+    """A dead link is retried once after 2**recoveries days, not given a fresh
+    three-attempt budget, so a link that always fails isn't downloaded daily."""
+    from datetime import UTC, datetime, timedelta
+
+    now = datetime.now(UTC)
+    _, due = _seed(db_sync, host="mega", status="dead")
+    _, waiting = _seed(db_sync, host="gdrive", status="dead")
+    _, spent = _seed(db_sync, host="dropbox", status="dead")
+    due.attempts = waiting.attempts = spent.attempts = ext.DEAD_LETTER_THRESHOLD
+    due.recoveries, due.completed_at = 2, now - timedelta(days=4, hours=1)
+    waiting.recoveries, waiting.completed_at = 2, now - timedelta(days=3)
+    spent.recoveries, spent.completed_at = ext._MAX_RECOVERIES, now - timedelta(days=90)
+    db_sync.commit()
+    due_id, waiting_id, spent_id = due.id, waiting.id, spent.id
+
+    enqueued = []
+    monkeypatch.setattr(ext.fetch_external_link, "delay", lambda lid: enqueued.append(lid))
+    out = ext.recover_external_links()
+
+    assert out["revived"] == 1
+    assert enqueued == [due_id]
+    db_sync.expire_all()
+    row = db_sync.get(ExternalLink, due_id)
+    assert (row.status, row.attempts, row.recoveries) == (
+        "failed", ext.DEAD_LETTER_THRESHOLD - 1, 3,
+    )
+    assert db_sync.get(ExternalLink, waiting_id).status == "dead"
+    assert db_sync.get(ExternalLink, spent_id).status == "dead"
+
+
+def test_a_recovered_link_that_fails_again_goes_straight_back_to_dead(
+    db_sync, tmp_path, monkeypatch,
+):
+    _, link = _seed(db_sync, host="mega", status="dead")
+    link.attempts = ext.DEAD_LETTER_THRESHOLD
+    db_sync.commit()
+    link_id = link.id
+    monkeypatch.setattr(ext, "IMAGES_ROOT", tmp_path)
+    monkeypatch.setattr(ext, "_redis", lambda: _FakeRedis())
+    monkeypatch.setattr(ext, "fetch_external", lambda *a, **k: FetchResult(error="too big"))
+    monkeypatch.setattr(ext.fetch_external_link, "delay", ext.fetch_external_link)
+
+    ext.recover_external_links()
+
+    db_sync.expire_all()
+    row = db_sync.get(ExternalLink, link_id)
+    assert (row.status, row.recoveries) == ("dead", 1)
+
+
+def test_prune_removes_only_links_recovery_has_given_up_on(db_sync):
+    from datetime import UTC, datetime, timedelta
+
+    old = datetime.now(UTC) - timedelta(days=ext._RETENTION_DAYS + 1)
+    _, spent = _seed(db_sync, host="mega", status="dead")
+    _, recovering = _seed(db_sync, host="gdrive", status="dead")
+    _, recent = _seed(db_sync, host="dropbox", status="dead")
+    spent.recoveries, spent.completed_at = ext._MAX_RECOVERIES, old
+    recovering.recoveries, recovering.completed_at = 1, old
+    recent.recoveries = ext._MAX_RECOVERIES
+    recent.completed_at = datetime.now(UTC) - timedelta(days=1)
+    db_sync.commit()
+    spent_id, recovering_id, recent_id = spent.id, recovering.id, recent.id
+
+    assert ext.prune_external_links() == {"pruned": 1}
+    db_sync.expire_all()
+    assert db_sync.get(ExternalLink, spent_id) is None
+    assert db_sync.get(ExternalLink, recovering_id) is not None
+    assert db_sync.get(ExternalLink, recent_id) is not None

tests/test_importer_attach_in_place.py

@@ -410,6 +410,31 @@ def test_attach_in_place_invalid_image_returns_skipped(importer):
     assert result.skip_reason.value == "invalid_image"
 
 
+@pytest.mark.parametrize("name", ["film.mp4abc123_.part", "img.jpg.partial", ".megatmp.Xy12"])
+def test_an_unfinished_download_is_refused_and_left_on_disk(importer, db_sync, name):
+    """A staging file is a download still being written (or abandoned): it is
+    never stored as an attachment, and the importer never deletes it, so a
+    download in progress is not pulled out from under its writer."""
+    from backend.app.models import PostAttachment
+
+    artist = Artist(name="Hal", slug="hal")
+    db_sync.add(artist)
+    db_sync.flush()
+    staging = importer.images_root / "hal" / "patreon" / "post" / name
+    staging.parent.mkdir(parents=True, exist_ok=True)
+    staging.write_bytes(b"half of a video")
+
+    for result in (importer.attach_in_place(staging, artist=artist),
+                   importer.import_one(staging)):
+        assert result.status == "skipped"
+        assert "unfinished download" in result.error
+        assert importer.discard_after_attach(staging, result) is False
+    assert staging.exists()
+    assert db_sync.execute(
+        select(func.count()).where(PostAttachment.original_filename == name)
+    ).scalar() == 0
+
+
 def test_attach_in_place_non_media_routes_to_attachment(importer, db_sync):
     """FC-2d-iii dispatch parity for the download path. A non-media file
     (.pdf, .txt etc.) downloaded by gallery-dl must become a PostAttachment,

tests/test_importer_sha_race.py

@@ -0,0 +1,202 @@
+"""Two workers importing the same picture at once (services/importer.py).
+
+The importer looks a file's sha256 up before inserting its row. When two copies
+of one picture are imported side by side, both lookups can find nothing; the
+unique index on sha256 then refuses the second insert. The loser files its copy
+as a duplicate of the winner, links its post, and leaves the session usable,
+instead of failing the import with a dead transaction.
+
+The race is staged the way tests/test_importer_provenance_race.py stages its
+own: the loser's sha256 lookup is forced to miss once, as it would if it ran
+just before the winner's commit. The loser's near-duplicate cache is empty for
+the same reason (it was loaded before the winner's row existed).
+"""
+
+import io
+import zipfile
+from pathlib import Path
+
+import pytest
+from PIL import Image
+from sqlalchemy import func, select
+
+from backend.app.models import Artist, ImageRecord, ImportSettings, PostAttachment
+from backend.app.services.importer import Importer, SkipReason
+from backend.app.services.thumbnailer import Thumbnailer
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+def layout(tmp_path):
+    import_root = tmp_path / "import"
+    images_root = tmp_path / "images"
+    import_root.mkdir()
+    images_root.mkdir()
+    return import_root, images_root
+
+
+def _worker(db_sync, layout) -> Importer:
+    import_root, images_root = layout
+    settings = db_sync.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    ).scalar_one()
+    return Importer(
+        session=db_sync, images_root=images_root, import_root=import_root,
+        thumbnailer=Thumbnailer(images_root=images_root), settings=settings,
+    )
+
+
+def _jpeg(path: Path) -> bytes:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", (320, 240), (40, 90, 160)).save(path, "JPEG")
+    return path.read_bytes()
+
+
+def _copy(src: Path, dst: Path) -> Path:
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_bytes(src.read_bytes())
+    return dst
+
+
+def _lose_the_race(importer: Importer, monkeypatch) -> None:
+    """Make `importer` miss its first sha256 lookup and see no near-duplicates."""
+    real_execute = importer.session.execute
+    missed = [False]
+
+    class _Miss:
+        def scalar_one_or_none(self):
+            return None
+
+    def execute(stmt, *args, **kwargs):
+        sql = str(stmt)
+        if not missed[0] and "FROM image_record" in sql and "image_record.sha256 =" in sql:
+            missed[0] = True
+            return _Miss()
+        return real_execute(stmt, *args, **kwargs)
+
+    monkeypatch.setattr(importer.session, "execute", execute)
+    monkeypatch.setattr(importer, "_phash_candidates_cache", lambda: [])
+
+
+def _records(db_sync) -> int:
+    return db_sync.execute(select(func.count()).select_from(ImageRecord)).scalar_one()
+
+
+def test_a_copy_imported_alongside_the_original_is_filed_as_its_duplicate(
+    db_sync, layout, monkeypatch,
+):
+    import_root, images_root = layout
+    first = import_root / "Alice" / "set1" / "pic.jpg"
+    _jpeg(first)
+    second = _copy(first, import_root / "Alice" / "set2" / "pic.jpg")
+
+    winner = _worker(db_sync, layout).import_one(first)
+    assert winner.status == "imported"
+    kept = Path(db_sync.get(ImageRecord, winner.image_id).path)
+
+    loser = _worker(db_sync, layout)
+    _lose_the_race(loser, monkeypatch)
+    result = loser.import_one(second)
+
+    assert result.status == "skipped"
+    assert result.skip_reason == SkipReason.duplicate_hash
+    assert result.image_id == winner.image_id
+    monkeypatch.undo()
+    assert _records(db_sync) == 1
+    assert kept.is_file()
+    # The loser's copy in the library was a stray and is gone; only the
+    # winner's file remains.
+    library_files = [p for p in images_root.rglob("*.jpg") if p.is_file()]
+    assert library_files == [kept]
+
+
+def test_the_same_file_imported_twice_at_once_keeps_its_library_copy(
+    db_sync, layout, monkeypatch,
+):
+    """Both runs write the same library path, so the loser's copy IS the
+    winner's file and must not be deleted."""
+    import_root, _ = layout
+    src = import_root / "Alice" / "pic.jpg"
+    _jpeg(src)
+
+    winner = _worker(db_sync, layout).import_one(src)
+    kept = Path(db_sync.get(ImageRecord, winner.image_id).path)
+
+    loser = _worker(db_sync, layout)
+    _lose_the_race(loser, monkeypatch)
+    result = loser.import_one(src)
+
+    assert result.skip_reason == SkipReason.duplicate_hash
+    assert kept.is_file()
+
+
+def test_a_copy_attached_in_place_alongside_the_original_is_its_duplicate(
+    db_sync, layout, monkeypatch,
+):
+    _, images_root = layout
+    artist = Artist(name="Bea", slug="bea")
+    db_sync.add(artist)
+    db_sync.commit()
+    first = images_root / "bea" / "patreon" / "post1" / "pic.jpg"
+    _jpeg(first)
+    second = _copy(first, images_root / "bea" / "patreon" / "post2" / "pic.jpg")
+
+    winner = _worker(db_sync, layout).attach_in_place(first, artist=artist)
+    assert winner.status == "imported"
+
+    loser = _worker(db_sync, layout)
+    _lose_the_race(loser, monkeypatch)
+    result = loser.attach_in_place(second, artist=artist)
+
+    assert result.status == "skipped"
+    assert result.skip_reason == SkipReason.duplicate_hash
+    assert result.image_id == winner.image_id
+    monkeypatch.undo()
+    assert _records(db_sync) == 1
+    # Removing the loser's file is the caller's step (discard_after_attach).
+    assert first.is_file() and second.is_file()
+
+
+def test_an_archive_whose_member_breaks_the_transaction_is_still_stored(
+    db_sync, layout, monkeypatch,
+):
+    """A member whose import fails mid-flush leaves the transaction dead. The
+    member loop rolls it back, so the archive itself is still stored and the
+    import ends with a result instead of an exception."""
+    import_root, _ = layout
+    seed = _worker(db_sync, layout).import_one(_jpeg_at(import_root / "Cy" / "seed.jpg"))
+    seed_path = db_sync.get(ImageRecord, seed.image_id).path
+
+    arc = import_root / "Cy" / "set.zip"
+    with zipfile.ZipFile(arc, "w") as zf:
+        zf.writestr("a.jpg", _jpeg_bytes())
+
+    importer = _worker(db_sync, layout)
+
+    def breaks_the_transaction(*args, **kwargs):
+        importer.session.add(ImageRecord(
+            path=seed_path, sha256="f" * 64, size_bytes=1, mime="image/jpeg",
+            origin="imported_filesystem",
+        ))
+        importer.session.flush()  # refused: the path is taken
+
+    monkeypatch.setattr(importer, "_import_media", breaks_the_transaction)
+    result = importer.import_one(arc)
+
+    assert result.status == "attached"
+    stored = db_sync.execute(
+        select(func.count()).select_from(PostAttachment)
+    ).scalar_one()
+    assert stored == 1
+
+
+def _jpeg_at(path: Path) -> Path:
+    _jpeg(path)
+    return path
+
+
+def _jpeg_bytes() -> bytes:
+    buf = io.BytesIO()
+    Image.new("RGB", (64, 48), (200, 30, 30)).save(buf, "JPEG")
+    return buf.getvalue()

tests/test_library_scan.py

@@ -0,0 +1,123 @@
+"""Finding files in the artists' folders that the library has no record of, and
+importing them where they lie (services.library_scan + the `library` batch)."""
+
+import io
+import os
+import time
+
+import pytest
+from PIL import Image
+from sqlalchemy import select
+
+import backend.app.tasks.import_file as import_file
+from backend.app.models import Artist, ImageRecord, ImportSettings, ImportTask
+from backend.app.services import library_scan
+from backend.app.services.importer import Importer
+from backend.app.services.thumbnailer import Thumbnailer
+
+pytestmark = pytest.mark.integration
+
+
+def _jpeg(seed: int) -> bytes:
+    im = Image.new("RGB", (256, 256))
+    px = im.load()
+    for y in range(256):
+        for x in range(256):
+            px[x, y] = ((x * seed) % 256, (y * (seed + 1)) % 256, (x ^ y) % 256)
+    buf = io.BytesIO()
+    im.save(buf, "JPEG")
+    return buf.getvalue()
+
+
+def _write(path, data: bytes, *, age_days: float = 2):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    t = time.time() - age_days * 86400
+    os.utime(path, (t, t))
+    return path
+
+
+@pytest.fixture
+def layout(db_sync, tmp_path):
+    db_sync.add(Artist(name="Libscan Maewix", slug="libscan-maewix"))
+    db_sync.commit()
+    post = tmp_path / "Libscan-Maewix" / "patreon" / "2026-05-01_123_Pack"
+    files = {
+        "missing": _write(post / "01_art.jpg", _jpeg(1)),
+        "owned": _write(post / "02_owned.jpg", _jpeg(2)),
+        "sidecar": _write(post / "01_art.json", b'{"category": "patreon", "id": "123"}'),
+        "staging": _write(post / "03_big.zip.part", b"partial"),
+        "recent": _write(post / "04_new.jpg", _jpeg(4), age_days=0),
+        "not_media": _write(post / "05_game.exe", b"MZ"),
+        "no_artist": _write(tmp_path / "libscan-nobody" / "x" / "a.jpg", _jpeg(5)),
+        "store": _write(tmp_path / "thumbs" / "abc" / "f.jpg", _jpeg(6)),
+    }
+    db_sync.add(ImageRecord(
+        path=str(files["owned"]), sha256="libscan-owned".ljust(64, "x"),
+        size_bytes=files["owned"].stat().st_size, mime="image/jpeg",
+        width=256, height=256, origin="downloaded", integrity_status="ok",
+    ))
+    db_sync.commit()
+    return tmp_path, files
+
+
+def test_finds_only_unrecorded_media_in_an_artists_folder(db_sync, layout):
+    """A differently-cased folder still matches its artist. Recorded files,
+    sidecars, staging files, the library's own stores, folders that match no
+    artist, files changed in the last day and non-media are not listed."""
+    root, files = layout
+    found, summary = library_scan.find_unimported(db_sync, root)
+
+    assert [u.path for u in found] == [files["missing"]]
+    assert found[0].artist_slug == "libscan-maewix"
+    assert found[0].task_type == "media"
+    assert summary["files"] == 1
+    assert summary["recent"] == 1
+    assert summary["not_media"] == 1
+    assert summary["no_artist"] == 1
+    assert summary["artists"][0]["slug"] == "libscan-maewix"
+    assert summary["artists"][0]["samples"] == [
+        "Libscan-Maewix/patreon/2026-05-01_123_Pack/01_art.jpg",
+    ]
+
+
+def test_queue_makes_a_library_batch_of_what_find_lists(db_sync, layout, monkeypatch):
+    """The import queued is exactly the previewed list."""
+    root, files = layout
+    queued = []
+    monkeypatch.setattr(import_file, "enqueue_import", lambda tid, tt: queued.append((tid, tt)))
+
+    summary = library_scan.queue_unimported(db_sync, root)
+
+    tasks = db_sync.execute(
+        select(ImportTask).where(ImportTask.batch_id == summary["batch_id"])
+    ).scalars().all()
+    assert [t.source_path for t in tasks] == [str(files["missing"])]
+    assert tasks[0].batch.scan_mode == "library"
+    assert queued == [(tasks[0].id, "media")]
+
+
+def test_a_library_import_attaches_in_place_and_removes_a_copy(db_sync, layout, monkeypatch):
+    """The file stays where it is and becomes the record's file. A byte-identical
+    copy found later is removed from disk, since the library already holds it."""
+    root, files = layout
+    monkeypatch.setattr(import_file, "IMAGES_ROOT", root)
+    importer = Importer(
+        session=db_sync, images_root=root, import_root=root,
+        thumbnailer=Thumbnailer(images_root=root),
+        settings=ImportSettings.load_sync(db_sync),
+    )
+
+    result = import_file._attach_where_it_lies(db_sync, importer, files["missing"])
+
+    assert result.status == "imported"
+    record = db_sync.get(ImageRecord, result.image_id)
+    assert record.path == str(files["missing"])
+    assert files["missing"].exists()
+    assert db_sync.get(Artist, record.artist_id).slug == "libscan-maewix"
+
+    copy = _write(files["missing"].parent / "09_copy.jpg", files["missing"].read_bytes())
+    again = import_file._attach_where_it_lies(db_sync, importer, copy)
+    assert again.status == "skipped"
+    assert not copy.exists()
+    assert files["missing"].exists()

tests/test_maintenance.py

@@ -26,26 +26,50 @@ def _make_batch(session) -> int:
     return batch.id
 
 
-def test_cleanup_orphaned_temp_files_removes_stale_only(tmp_path, monkeypatch):
+def test_cleanup_orphaned_temp_files_removes_stale_only(db_sync, tmp_path, monkeypatch):
     import os
 
+    from backend.app.models import ImageRecord, PostAttachment
     from backend.app.tasks import maintenance as m
 
     monkeypatch.setattr(m, "IMAGES_ROOT", tmp_path)
-    stale = tmp_path / "artist" / "img.jpg.part"      # killed download → orphan
-    stale.parent.mkdir(parents=True)
-    stale.write_bytes(b"x")
     old = datetime.now(UTC).timestamp() - 8 * 3600     # older than the 6h guard
-    os.utime(stale, (old, old))
-    fresh = tmp_path / "in_progress.jpg.partial"       # active download → keep
-    fresh.write_bytes(b"x")
-    keep = tmp_path / "real.jpg"                        # a real image → keep
-    keep.write_bytes(b"x")
 
-    assert m.cleanup_orphaned_temp_files() == 1
+    def staged(rel: str, *, aged: bool = True):
+        p = tmp_path / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"x")
+        if aged:
+            os.utime(p, (old, old))
+        return p
+
+    stale = staged("artist/img.jpg.part")                 # killed download → orphan
+    mega = staged("artist/.megatmp.AbCd123")              # abandoned megatools stage
+    fresh = staged("in_progress.jpg.partial", aged=False)  # active download → keep
+    keep = tmp_path / "real.jpg"                          # a real image → keep
+    keep.write_bytes(b"x")
+    # Staging-named files a library row points at are library content.
+    attached = staged("attachments/ab/abc.part")
+    imaged = staged("artist/video.mp4.part")
+    db_sync.add(PostAttachment(
+        post_id=None, artist_id=None, sha256="tempsweep-att".ljust(64, "x"),
+        path=str(attached), original_filename="film.mp4.part", ext=".part",
+        size_bytes=1,
+    ))
+    db_sync.add(ImageRecord(
+        path=str(imaged), sha256="tempsweep-img".ljust(64, "x"), size_bytes=1,
+        mime="video/mp4", width=1, height=1, origin="downloaded",
+        integrity_status="ok",
+    ))
+    db_sync.commit()
+
+    assert m.cleanup_orphaned_temp_files() == 2
     assert not stale.exists()
+    assert not mega.exists()
     assert fresh.exists()
     assert keep.exists()
+    assert attached.exists()
+    assert imaged.exists()
 
 
 def test_recover_interrupted_only_old(db_sync, monkeypatch):
@@ -98,7 +122,10 @@ def test_recover_interrupted_sweeps_pending_orphans_to_failed(db_sync, monkeypat
     Banked 2026-05-25 after operator hit 5490 stuck pending rows.
     """
     from backend.app.tasks import import_file
+    from backend.app.tasks import maintenance as m
     monkeypatch.setattr(import_file.import_media_file, "delay", lambda *_: None)
+    # The broker's import queue is empty, so a stale 'queued' row's message is gone.
+    monkeypatch.setattr(m, "_import_queue_depth", lambda: 0)
 
     batch_id = _make_batch(db_sync)
     now = datetime.now(UTC)
@@ -146,6 +173,42 @@ def test_recover_interrupted_sweeps_pending_orphans_to_failed(db_sync, monkeypat
     assert "orphan" in (stale_pending.error or "")
 
 
+@pytest.mark.parametrize("depth", [7, None])
+def test_recover_interrupted_keeps_queued_rows_while_the_import_queue_holds_work(
+    db_sync, monkeypatch, depth,
+):
+    """A queued row in a batch bigger than half an hour of work is waiting its
+    turn, not orphaned: while the import queue holds messages (or can't be
+    read), only never-enqueued 'pending' rows are swept."""
+    from sqlalchemy import update as _upd
+
+    from backend.app.tasks import maintenance as m
+
+    monkeypatch.setattr(m, "_import_queue_depth", lambda: depth)
+    batch_id = _make_batch(db_sync)
+    waiting = ImportTask(
+        batch_id=batch_id, source_path="/import/waiting.jpg", task_type="media",
+        status="queued",
+    )
+    never_sent = ImportTask(
+        batch_id=batch_id, source_path="/import/never.jpg", task_type="media",
+        status="pending",
+    )
+    db_sync.add_all([waiting, never_sent])
+    db_sync.flush()
+    db_sync.execute(
+        _upd(ImportTask).where(ImportTask.id.in_([waiting.id, never_sent.id]))
+        .values(created_at=datetime.now(UTC) - timedelta(hours=2))
+    )
+    db_sync.commit()
+
+    assert m.recover_interrupted_tasks.apply().get() == 1
+    db_sync.refresh(waiting)
+    db_sync.refresh(never_sent)
+    assert waiting.status == "queued"
+    assert never_sent.status == "failed"
+
+
 def test_recover_interrupted_handles_both_stuck_and_orphans(db_sync, monkeypatch):
     """One sweep tick handles both 'processing' crashes AND
     'pending'/'queued' orphans in a single pass."""
@@ -885,3 +948,14 @@ def test_reclaim_attachments_stuck_threshold_exceeds_hard_time_limit():
         "backend.app.tasks.admin.reclaim_orphaned_attachments_task"
     ]
     assert override >= hard_minutes
+
+
+def test_import_unimported_stuck_threshold_exceeds_hard_time_limit():
+    """The same invariant for the walk that imports files on disk."""
+    from backend.app.tasks.admin import import_unimported_files_task
+    from backend.app.tasks.maintenance import TASK_STUCK_THRESHOLD_MINUTES
+
+    override = TASK_STUCK_THRESHOLD_MINUTES[
+        "backend.app.tasks.admin.import_unimported_files_task"
+    ]
+    assert override >= import_unimported_files_task.time_limit / 60

tests/test_tasks_backup.py

@@ -33,7 +33,7 @@ def fake_subprocess_and_images_root(monkeypatch, tmp_path):
         stderr = b""
 
     def _sentinel(cmd):
-        if cmd[0] == "pg_dump":
+        if "pg_dump" in cmd:
             i = cmd.index("-f")
             Path(cmd[i + 1]).write_bytes(b"-- fake pg_dump\n")
         elif cmd[0] == "tar" and "-cf" in cmd:
@@ -128,6 +128,63 @@ async def test_backup_db_task_persists_tag(db_sync):
     assert tag == "pre-cutover"
 
 
+@pytest.fixture
+def archives(monkeypatch):
+    """An off-site destination is set up; the dump itself is faked."""
+    from backend.app.services.backup_s3 import S3Target
+    target = S3Target("http://archives.example:8081", "curator", "AK", "SK")
+    monkeypatch.setattr(
+        "backend.app.services.backup_destination.saved_target", lambda settings: target,
+    )
+    sent = []
+
+    def _offsite(*, db_url, target, limit_mbps):
+        sent.append({"target": target, "limit_mbps": limit_mbps})
+        return {
+            "kind": "db", "ts": "20261107T030000Z",
+            "key": "database/fabledcurator-20261107T030000Z.dump",
+            "bucket": target.bucket, "endpoint": target.endpoint,
+            "parts": 3, "size_bytes": 1234,
+        }
+    monkeypatch.setattr("backend.app.services.backup_service.backup_db_offsite", _offsite)
+    return sent
+
+
+@pytest.mark.asyncio
+async def test_with_a_destination_the_dump_goes_off_site_and_nothing_is_written_here(
+    db_sync, archives, tmp_path,
+):
+    from backend.app.tasks.backup import backup_db_task
+    run_id = backup_db_task.delay(triggered_by="nightly").get()["backup_run_id"]
+    row = db_sync.get(BackupRun, run_id)
+    assert row.status == "ok"
+    assert row.sql_path is None
+    assert row.size_bytes == 1234
+    assert row.manifest["offsite"] == {
+        "endpoint": "http://archives.example:8081", "bucket": "curator",
+        "key": "database/fabledcurator-20261107T030000Z.dump", "parts": 3,
+    }
+    assert archives[0]["limit_mbps"] == 200        # the setting's default
+    assert not (tmp_path / "_backups").exists()
+
+
+@pytest.mark.asyncio
+async def test_an_off_site_dump_that_fails_is_recorded_with_why(db_sync, monkeypatch, archives):
+    from backend.app.services.backup_service import DumpFailed
+    from backend.app.tasks.backup import backup_db_task
+
+    def _fails(**kwargs):
+        raise DumpFailed("pg_dump: error: connection lost")
+    monkeypatch.setattr("backend.app.services.backup_service.backup_db_offsite", _fails)
+    with pytest.raises(DumpFailed):
+        backup_db_task.delay().get()
+    row = db_sync.execute(
+        select(BackupRun).where(BackupRun.kind == "db").order_by(BackupRun.id.desc()).limit(1)
+    ).scalar_one()
+    assert row.status == "error"
+    assert row.error == "DumpFailed: pg_dump: error: connection lost"
+
+
 # --- backup_images_task ---------------------------------------------