Merge pull request 'Release v26.05.25.4 — importer ext sanitize fix, CI shard split, BrowserExtensionCard on Overview' (#15) from dev into main

_apply_sidecar is additive: it find-or-creates Post/Source/ImageProvenance
and sets primary_post_id NULL-only, so any IR-migration provenance on the
existing row survives untouched and the new GS sidecar adds a second
ImageProvenance pointing at the freshly-created Post.

Wrapped in try/except so a malformed sidecar can't unwind the file-swap
commit — the file replacement is the critical operation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.forgejo/workflows/ci.yml

@@ -24,11 +24,26 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Cache pip wheels
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-py314-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            pip-${{ runner.os }}-py314-
+
       - name: Install Python deps
         # ruff is pre-installed in the ci-python image (see CI-Runner/CI-python/
         # Dockerfile's RUFF_VERSION). Per FabledRulebook ci-runners.md, toolchain
         # versions live on the runner image, not here.
-        run: pip install -r requirements.txt pytest pytest-asyncio
+        # uv: 5-10x faster wheel resolve than pip for cold caches.
+        # Falls back to pip install on uv-missing runners (older images).
+        run: |
+          if command -v uv >/dev/null 2>&1; then
+            uv pip install --system -r requirements.txt pytest pytest-asyncio
+          else
+            pip install -r requirements.txt pytest pytest-asyncio
+          fi
 
       - name: Ruff lint
         run: ruff check backend/ tests/ alembic/
@@ -57,17 +72,28 @@ jobs:
       - run: npm run test:unit
       - run: npm run build
 
-  integration:
-    # This act_runner (swarm-runner v0.6.1) puts service containers on the
-    # default bridge with NO service-name DNS, and publishing fixed host
-    # ports collides with the operator's running docker-compose dev stack on
-    # the same shared daemon. Workaround: publish NO host ports, and reach
-    # each service by its bridge IP — discovered at runtime via the mounted
-    # docker socket (the ci-python image ships /usr/bin/docker). Default-bridge
-    # containers can talk by IP (only embedded DNS is missing), so IP
-    # addressing is reliable here. Everything runs in ONE step so resolved
-    # values don't depend on cross-step env passing. Pattern documented in
-    # FabledRulebook/forgejo.md "CI philosophy".
+  # Integration suite split into THREE parallel shards (2026-05-25, runner
+  # capacity bumped 2→6). Each shard gets its own Postgres + Redis service
+  # set and runs alembic + a disjoint subset of integration tests. Shards
+  # share no DB state, so the autouse TRUNCATE fixture in tests/conftest.py
+  # stays single-threaded per shard but multiple shards run in parallel
+  # wall-clock. Approximate split — rebalance once --durations=15 output
+  # reveals which shard is the long pole.
+  #
+  # Each shard's docker-ps filter uses its own unique job name to scope
+  # service-container resolution. act_runner appears to strip underscores
+  # from job names when building container labels — `int_api` yielded
+  # zero matches on 2026-05-25 — so shards use no-separator names
+  # (`intapi`, `intimp`, `intcore`) instead. Each step prints
+  # `docker ps -a` first so a future naming-convention shift surfaces in
+  # the log without another guess-and-push cycle.
+  #
+  # Pre-baking requirements.txt into ci-python:3.14 is intentionally NOT
+  # done — per ci-requirements.md, FC is the only Python consumer of that
+  # image and the CI-Runner project's "add deps to image when used by >1
+  # project" rule keeps the install per-job.
+
+  intapi:
     runs-on: python-ci
     container:
       image: git.fabledsword.com/bvandeusen/ci-python:3.14
@@ -98,15 +124,21 @@ jobs:
           --health-retries 10
     steps:
       - uses: actions/checkout@v4
-
-      - name: Integration suite (resolve service IPs, migrate, test)
+      - name: Cache pip wheels
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-py314-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            pip-${{ runner.os }}-py314-
+      - name: API integration shard (resolve service IPs, migrate, test)
         run: |
           set -eux
-          # Scope to THIS job's service containers (act_runner names them
-          # ...JOB-integration...); the operator's compose stack uses the
-          # same images but different names, so it won't match.
-          PG=$(docker ps --filter "name=JOB-integration" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
-          RD=$(docker ps --filter "name=JOB-integration" --filter "ancestor=redis:7-alpine" -q | head -n1)
+          echo "=== container landscape (diagnostic for filter scoping) ==="
+          docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
+          echo "=== end landscape ==="
+          PG=$(docker ps --filter "name=intapi" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
+          RD=$(docker ps --filter "name=intapi" --filter "ancestor=redis:7-alpine" -q | head -n1)
           test -n "$PG" && test -n "$RD"
           PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
           RD_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$RD")
@@ -114,11 +146,153 @@ jobs:
           export DB_HOST="$PG_IP"
           export CELERY_BROKER_URL="redis://$RD_IP:6379/0"
           export CELERY_RESULT_BACKEND="redis://$RD_IP:6379/0"
-          # Wait for Postgres to accept TCP (bash /dev/tcp; no extra tools).
           for i in $(seq 1 60); do
             (echo > "/dev/tcp/$PG_IP/5432") >/dev/null 2>&1 && break
             sleep 2
           done
-          pip install -r requirements.txt pytest pytest-asyncio
+          if command -v uv >/dev/null 2>&1; then
+            uv pip install --system -r requirements.txt pytest pytest-asyncio
+          else
+            pip install -r requirements.txt pytest pytest-asyncio
+          fi
           alembic upgrade head
-          pytest tests/ -v -m integration
+          pytest tests/test_api_*.py -v -m integration --durations=15
+
+  intimp:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    env:
+      DB_USER: fabledcurator
+      DB_PASSWORD: ci_integration
+      DB_PORT: "5432"
+      DB_NAME: fabledcurator_test
+      SECRET_KEY: ci_integration_placeholder
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: fabledcurator
+          POSTGRES_PASSWORD: ci_integration
+          POSTGRES_DB: fabledcurator_test
+        options: >-
+          --health-cmd "pg_isready -U fabledcurator"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+      redis:
+        image: redis:7-alpine
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Cache pip wheels
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-py314-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            pip-${{ runner.os }}-py314-
+      - name: Importer integration shard (resolve service IPs, migrate, test)
+        run: |
+          set -eux
+          echo "=== container landscape (diagnostic for filter scoping) ==="
+          docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
+          echo "=== end landscape ==="
+          PG=$(docker ps --filter "name=intimp" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
+          RD=$(docker ps --filter "name=intimp" --filter "ancestor=redis:7-alpine" -q | head -n1)
+          test -n "$PG" && test -n "$RD"
+          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
+          RD_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$RD")
+          test -n "$PG_IP" && test -n "$RD_IP"
+          export DB_HOST="$PG_IP"
+          export CELERY_BROKER_URL="redis://$RD_IP:6379/0"
+          export CELERY_RESULT_BACKEND="redis://$RD_IP:6379/0"
+          for i in $(seq 1 60); do
+            (echo > "/dev/tcp/$PG_IP/5432") >/dev/null 2>&1 && break
+            sleep 2
+          done
+          if command -v uv >/dev/null 2>&1; then
+            uv pip install --system -r requirements.txt pytest pytest-asyncio
+          else
+            pip install -r requirements.txt pytest pytest-asyncio
+          fi
+          alembic upgrade head
+          pytest tests/test_importer*.py tests/test_import_*.py tests/test_migration_*.py tests/test_phash_*.py tests/test_sidecar_*.py tests/test_scan_*.py tests/test_archive_extractor.py tests/test_backfill_phash.py -v -m integration --durations=15
+
+  intcore:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    env:
+      DB_USER: fabledcurator
+      DB_PASSWORD: ci_integration
+      DB_PORT: "5432"
+      DB_NAME: fabledcurator_test
+      SECRET_KEY: ci_integration_placeholder
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: fabledcurator
+          POSTGRES_PASSWORD: ci_integration
+          POSTGRES_DB: fabledcurator_test
+        options: >-
+          --health-cmd "pg_isready -U fabledcurator"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+      redis:
+        image: redis:7-alpine
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Cache pip wheels
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-py314-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            pip-${{ runner.os }}-py314-
+      - name: Core integration shard (everything not api / importer / migration / phash / sidecar / scan / archive / backfill)
+        run: |
+          set -eux
+          echo "=== container landscape (diagnostic for filter scoping) ==="
+          docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
+          echo "=== end landscape ==="
+          PG=$(docker ps --filter "name=intcore" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
+          RD=$(docker ps --filter "name=intcore" --filter "ancestor=redis:7-alpine" -q | head -n1)
+          test -n "$PG" && test -n "$RD"
+          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
+          RD_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$RD")
+          test -n "$PG_IP" && test -n "$RD_IP"
+          export DB_HOST="$PG_IP"
+          export CELERY_BROKER_URL="redis://$RD_IP:6379/0"
+          export CELERY_RESULT_BACKEND="redis://$RD_IP:6379/0"
+          for i in $(seq 1 60); do
+            (echo > "/dev/tcp/$PG_IP/5432") >/dev/null 2>&1 && break
+            sleep 2
+          done
+          if command -v uv >/dev/null 2>&1; then
+            uv pip install --system -r requirements.txt pytest pytest-asyncio
+          else
+            pip install -r requirements.txt pytest pytest-asyncio
+          fi
+          alembic upgrade head
+          pytest tests/ -v -m integration --durations=15 \
+            --ignore-glob='tests/test_api_*.py' \
+            --ignore-glob='tests/test_importer*.py' \
+            --ignore-glob='tests/test_import_*.py' \
+            --ignore-glob='tests/test_migration_*.py' \
+            --ignore-glob='tests/test_phash_*.py' \
+            --ignore-glob='tests/test_sidecar_*.py' \
+            --ignore-glob='tests/test_scan_*.py' \
+            --ignore-glob='tests/test_archive_extractor.py' \
+            --ignore-glob='tests/test_backfill_phash.py'

.forgejo/workflows/extension.yml

@@ -2,7 +2,14 @@ name: extension
 on:
   push:
     branches: [dev, main]
-    paths: ['extension/**']
+    # Self-retriggering: include the workflow file itself so edits to
+    # this workflow (filename-glob fixes, env tweaks, etc.) run the
+    # sign-and-publish dance on next push without needing a manual
+    # Forgejo dispatch. Side-effect commits (`ext: publish signed XPI`)
+    # only touch frontend/public/extension/ so they DON'T re-trigger.
+    paths:
+      - 'extension/**'
+      - '.forgejo/workflows/extension.yml'
   workflow_dispatch:
 
 jobs:
@@ -38,22 +45,52 @@ jobs:
           WEB_EXT_API_SECRET: ${{ secrets.MOZILLA_AMO_JWT_SECRET }}
       - name: Commit signed XPI to frontend/public/extension/
         run: |
-          set -e
-          XPI=$(ls extension/web-ext-artifacts/fabledcurator-*.xpi | head -1)
+          set -ex
+          # AMO renames signed XPIs using its internal addon-id-safe-string
+          # (e.g. 997017ca3e104e30a75a-1.0.1.xpi), NOT our gecko ID. Match
+          # any *.xpi in the artifacts dir — fresh CI runner means there's
+          # exactly one — and rename it on copy so the FC server's
+          # whitelist (backend/app/frontend.py expects 'fabledcurator-*.xpi')
+          # keeps working.
+          # Diagnostic instrumentation 2026-05-25: a prior run (id 1731)
+          # reported success without producing an `ext: publish signed XPI`
+          # commit on main. Tracing the cwd, artifacts dir, version
+          # extraction, staging state, and push response so the next run's
+          # log explains the gap.
+          echo "=== cwd ==="
+          pwd
+          echo "=== ref / branch ==="
+          echo "ref: ${GITHUB_REF:-unset}  sha: ${GITHUB_SHA:-unset}"
+          git log --oneline -3 || true
+          echo "=== artifacts dir ==="
+          ls -la extension/web-ext-artifacts/ 2>&1 || echo "(dir missing)"
+          XPI=$(ls extension/web-ext-artifacts/*.xpi 2>/dev/null | head -1)
+          echo "XPI=$XPI"
           if [ -z "$XPI" ]; then
             echo "No XPI produced by web-ext sign — exiting"
             exit 1
           fi
+          VERSION=$(grep -E '"version"' extension/package.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+          echo "VERSION=$VERSION"
+          DEST="frontend/public/extension/fabledcurator-${VERSION}.xpi"
+          echo "DEST=$DEST"
           mkdir -p frontend/public/extension
-          cp "$XPI" frontend/public/extension/
-          # Also copy as -latest.xpi so the FC server can serve a stable URL.
+          # Wipe any prior versions so the directory doesn't grow each release.
+          rm -f frontend/public/extension/fabledcurator-*.xpi
+          cp "$XPI" "$DEST"
           cp "$XPI" "frontend/public/extension/fabledcurator-latest.xpi"
+          echo "=== frontend/public/extension/ after copy ==="
+          ls -la frontend/public/extension/
           git config user.name  "FC extension CI"
           git config user.email "noreply@fabledsword.com"
           git add frontend/public/extension/
+          echo "=== git status after add ==="
+          git status --short
+          echo "=== diff --cached --stat ==="
+          git diff --cached --stat || true
           if git diff --cached --quiet; then
-            echo "No changes to commit"
+            echo "No changes to commit (frontend/public/extension/ matches HEAD)"
           else
-            git commit -m "ext: publish signed XPI $(basename $XPI)"
-            git push origin HEAD:main
+            git commit -m "ext: publish signed XPI fabledcurator-${VERSION}.xpi"
+            git push -v origin HEAD:main
           fi

backend/app/api/import_admin.py

@@ -47,6 +47,8 @@ async def status():
         if active:
             payload["active_batch"] = {
                 "id": active.id,
+                "source_path": active.source_path,
+                "scan_mode": active.scan_mode,
                 "total_files": active.total_files,
                 "imported": active.imported,
                 "skipped": active.skipped,

backend/app/services/importer.py

@@ -71,6 +71,31 @@ def is_video(path: Path) -> bool:
     return path.suffix.lower() in VIDEO_EXTS
 
 
+def _safe_ext(path: Path) -> str:
+    """Conservatively extract a file extension for PostAttachment.ext
+    (varchar(32)).
+
+    gallery-dl produces some filenames with URL-encoded query-string
+    artifacts embedded into the basename (e.g.
+    `79507046_media_..._https___www.patreon.com_media-u_Z0FBQUFBQm5q...`).
+    `Path.suffix` finds the LAST dot and returns everything after, which
+    in those cases yields a 50+ char "extension" of mostly base64-ish
+    junk. That blows the column. Operator-flagged 2026-05-25.
+
+    Real extensions are short and alphanumeric. We accept anything ≤ 16
+    chars where every post-dot character is alphanumeric; anything else
+    means the input wasn't a real extension and we return the empty
+    string. ext is nullable-ish (empty string still satisfies NOT NULL)
+    and consumers should treat "" as "no known extension".
+    """
+    suffix = path.suffix.lower()
+    if not suffix or len(suffix) > 16:
+        return ""
+    if not all(c.isalnum() for c in suffix[1:]):
+        return ""
+    return suffix
+
+
 def _mime_for(path: Path) -> str:
     suffix = path.suffix.lower()
     image_mimes = {
@@ -209,7 +234,7 @@ class Importer:
                 sha256=sha,
                 path=stored,
                 original_filename=source.name,
-                ext=source.suffix.lower(),
+                ext=_safe_ext(source),
                 mime=_mime_for(source),
                 size_bytes=source.stat().st_size,
             ))
@@ -722,6 +747,15 @@ class Importer:
         row id (so tags/series/curation stay attached). ML is cleared so
         the import task re-derives it on the new pixels.
 
+        After the file swap, the new file's adjacent gallery-dl sidecar
+        (if any) is applied via _apply_sidecar — operator-flagged
+        2026-05-25: scanning a GS download dir with smaller IR-migrated
+        images on the receiving end used to swap files but lose the GS
+        sidecar's post metadata entirely. _apply_sidecar is additive
+        (find-or-create Post / Source / ImageProvenance, NULL-only
+        primary_post_id update) so any pre-existing Post linkage
+        survives untouched.
+
         If `new_path` is provided, `source` is assumed to ALREADY be at
         that path (FC-3c attach_in_place case) — skip the copy step.
         Otherwise the file is copied via _copy_to_library."""
@@ -751,6 +785,22 @@ class Importer:
         self.session.flush()
         self.session.commit()
 
+        # Sidecar enrichment from the new (larger) file's location.
+        # _apply_sidecar resolves artist from the sidecar itself if the
+        # existing row has none, and is internally guarded against
+        # missing-or-malformed sidecars (silent return).
+        try:
+            self._apply_sidecar(existing, source, None)
+        except Exception as exc:
+            # Don't unwind the supersede DB swap if sidecar parsing
+            # blows up unexpectedly — the file replacement is the
+            # critical operation, sidecar is enrichment.
+            log.warning(
+                "sidecar enrichment failed during supersede of "
+                "image_record.id=%s from %s: %s",
+                existing.id, source, exc,
+            )
+
         for stale in (old_path, old_thumb):
             if not stale or stale == str(dest):
                 # If the supersede kept the file in place (new_path == old

backend/app/services/ml/embedder.py

@@ -34,10 +34,21 @@ class Embedder:
         if self._model is not None:
             return
         import torch
-        from transformers import AutoModel, AutoProcessor
+        from transformers import AutoModel, SiglipImageProcessor
 
         self._torch = torch
-        self._processor = AutoProcessor.from_pretrained(str(self._model_dir))
+        # FC's embedder only does IMAGE inference — never text. AutoProcessor
+        # loads the full processor including SiglipTokenizer, which requires
+        # the sentencepiece library at import time even if we never call it.
+        # SiglipImageProcessor loads ONLY preprocessor_config.json (image
+        # side) and skips the tokenizer config entirely. Operator hit the
+        # ImportError 2026-05-25 once the ml-worker started actually running
+        # tag_and_embed; switching to the image-only loader avoids the
+        # tokenizer dep without adding ~30 MB of unused C++ build to the
+        # lean ml-worker image.
+        self._processor = SiglipImageProcessor.from_pretrained(
+            str(self._model_dir)
+        )
         self._model = AutoModel.from_pretrained(str(self._model_dir))
         self._model.eval()
 

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "FabledCurator",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Export cookies from supported platforms to FabledCurator and add creators as sources in one click.",
 
   "browser_specific_settings": {

extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabledcurator-extension",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": true,
   "description": "Firefox extension for FabledCurator",
   "scripts": {

frontend/src/components/settings/ImportTriggerPanel.vue

@@ -7,7 +7,8 @@
           indeterminate color="accent" size="20"
         />
         <span>
-          Scanning {{ store.activeBatch.source_path }} —
+          {{ store.activeBatch.scan_mode === 'deep' ? 'Deep scanning' : 'Scanning' }}
+          {{ store.activeBatch.source_path || '/import' }} —
           imported {{ store.activeBatch.imported }},
           skipped {{ store.activeBatch.skipped }},
           failed {{ store.activeBatch.failed }} /
@@ -24,8 +25,12 @@
 
       <p class="text-body-2 mb-3">
         <span v-if="!store.activeBatch">
-          Run a quick scan of the import directory. Deep scan (pHash dedup,
-          archives) lands in FC-2d.
+          <strong>Quick scan</strong> walks <code>/import</code> and enqueues
+          new files only (skips paths already on a non-failed ImportTask).
+          <strong>Deep scan</strong> additionally chains a phash backfill
+          across the existing library — use after bulk-imports to catch
+          near-duplicates that slipped through. Both modes route non-media
+          + sidecar pairs through PostAttachment capture.
         </span>
         <span v-else>
           An active batch is in progress. Wait for it to finish, or click
@@ -34,15 +39,26 @@
         </span>
       </p>
 
-      <v-btn
-        color="primary" rounded="pill"
-        :disabled="!!store.activeBatch"
-        :loading="busy"
-        @click="trigger"
-      >
-        <v-icon start>mdi-magnify-scan</v-icon>
-        Quick scan
-      </v-btn>
+      <div class="d-flex flex-wrap" style="gap: 12px;">
+        <v-btn
+          color="primary" rounded="pill"
+          :disabled="!!store.activeBatch"
+          :loading="busy === 'quick'"
+          @click="trigger('quick')"
+        >
+          <v-icon start>mdi-magnify-scan</v-icon>
+          Quick scan
+        </v-btn>
+        <v-btn
+          color="secondary" rounded="pill" variant="tonal"
+          :disabled="!!store.activeBatch"
+          :loading="busy === 'deep'"
+          @click="trigger('deep')"
+        >
+          <v-icon start>mdi-magnify-plus-outline</v-icon>
+          Deep scan
+        </v-btn>
+      </div>
 
       <v-alert v-if="store.triggerError" type="error" variant="tonal" class="mt-3" closable>
         {{ store.triggerError }}
@@ -56,12 +72,12 @@ import { ref } from 'vue'
 import { useImportStore } from '../../stores/import.js'
 
 const store = useImportStore()
-const busy = ref(false)
+const busy = ref(null)
 const clearing = ref(false)
 
-async function trigger() {
-  busy.value = true
-  try { await store.triggerScan() } catch {} finally { busy.value = false }
+async function trigger(mode) {
+  busy.value = mode
+  try { await store.triggerScan(mode) } catch {} finally { busy.value = null }
 }
 
 async function onClearStuck() {

frontend/src/components/settings/MaintenancePanel.vue

@@ -14,7 +14,6 @@
     <AliasTable class="mt-4" />
     <BackupCard class="mt-6" />
     <TagMaintenanceCard class="mt-6" />
-    <BrowserExtensionCard class="mt-6" />
     <LegacyMigrationCard class="mt-6" />
   </div>
 </template>
@@ -27,7 +26,6 @@ import AllowlistTable from './AllowlistTable.vue'
 import AliasTable from './AliasTable.vue'
 import BackupCard from './BackupCard.vue'
 import TagMaintenanceCard from './TagMaintenanceCard.vue'
-import BrowserExtensionCard from './BrowserExtensionCard.vue'
 import LegacyMigrationCard from './LegacyMigrationCard.vue'
 </script>
 

frontend/src/stores/import.js

@@ -52,11 +52,37 @@ export const useImportStore = defineStore('import', () => {
     }
   }
 
-  async function triggerScan() {
+  async function triggerScan(mode = 'quick') {
+    if (!['quick', 'deep', 'verify'].includes(mode)) {
+      throw new Error(`unsupported scan mode: ${mode}`)
+    }
     triggerError.value = null
     try {
-      await api.post('/api/import/trigger', { body: { mode: 'quick' } })
+      await api.post('/api/import/trigger', { body: { mode } })
+      // Acknowledge immediately so the click isn't invisible. scan_directory
+      // can finalize the batch synchronously when every file in /import is
+      // already on a non-failed ImportTask (operator-flagged 2026-05-25:
+      // 233k existing tasks → all paths in skip-set → files_seen=0 →
+      // batch flashes 'running' for <100ms then 'complete' before the
+      // first refreshStatus() lands; UI never sees the active state).
+      const label = mode === 'deep'
+        ? 'Deep scan triggered (pHash backfill chained)'
+        : mode === 'verify' ? 'Library verify triggered' : 'Quick scan triggered'
+      window.__fcToast?.({ text: label, type: 'success' })
       await refreshStatus()
+      // Re-poll twice over ~5s to catch quick-finalize transitions and
+      // surface a result toast either way. Skip the "no new files" hint
+      // for 'verify' since it doesn't walk the import_root.
+      setTimeout(async () => {
+        await refreshStatus()
+        await loadTasks(true)
+        if (!activeBatch.value && mode !== 'verify') {
+          window.__fcToast?.({
+            text: 'Scan complete — no new files (everything already on an ImportTask row)',
+            type: 'info',
+          })
+        }
+      }, 2000)
     } catch (e) {
       triggerError.value = e.message
       window.__fcToast?.({ text: `Scan failed: ${e.message}`, type: 'error' })

frontend/src/views/SettingsView.vue

@@ -1,6 +1,16 @@
 <template>
   <v-container fluid class="py-6">
-    <v-tabs v-model="tab" color="accent" class="mb-4">
+    <!-- Sticky tabs: operator-flagged 2026-05-25 — long Import / Maintenance
+         panels pushed the tab strip out of the viewport, forcing a scroll-
+         to-top just to change tab. AppShell's TopNav is 64px sticky, so the
+         tab strip lives directly under it. Background uses the theme surface
+         token so it visually merges with the page rather than the
+         translucent v-tabs default. -->
+    <v-tabs
+      v-model="tab" color="accent" class="mb-4"
+      style="position: sticky; top: 64px; z-index: 4;
+             background: rgb(var(--v-theme-surface));"
+    >
       <v-tab value="overview">Overview</v-tab>
       <v-tab value="activity">Activity</v-tab>
       <v-tab value="import">Import</v-tab>
@@ -21,6 +31,11 @@
           {{ system.stats.tasks.pending + system.stats.tasks.queued }} import task(s) pending.
           <v-btn variant="text" size="small" @click="tab = 'import'">Go to Import tab</v-btn>
         </v-alert>
+        <!-- Browser-extension install/download lives on Overview (moved
+             from Maintenance 2026-05-25). Overview is the discovery
+             surface for "things to set up"; Maintenance is for
+             housekeeping of already-set-up systems. -->
+        <BrowserExtensionCard class="mt-6" />
       </v-window-item>
 
       <v-window-item value="activity">
@@ -28,11 +43,14 @@
       </v-window-item>
 
       <v-window-item value="import">
+        <!-- Order: trigger → recent tasks → filters. Tasks sit directly
+             below the trigger so operator sees hit/miss feedback without
+             scrolling past the filter card (operator-flagged 2026-05-25). -->
         <ImportTriggerPanel />
         <v-divider class="my-6" />
-        <ImportFiltersForm />
-        <v-divider class="my-6" />
         <ImportTaskList />
+        <v-divider class="my-6" />
+        <ImportFiltersForm />
       </v-window-item>
 
       <v-window-item value="maintenance">
@@ -49,6 +67,7 @@ import { useImportStore } from '../stores/import.js'
 import SystemStatsCards from '../components/settings/SystemStatsCards.vue'
 import SystemActivitySummary from '../components/settings/SystemActivitySummary.vue'
 import SystemActivityTab from '../components/settings/SystemActivityTab.vue'
+import BrowserExtensionCard from '../components/settings/BrowserExtensionCard.vue'
 import ImportTriggerPanel from '../components/settings/ImportTriggerPanel.vue'
 import ImportFiltersForm from '../components/settings/ImportFiltersForm.vue'
 import ImportTaskList from '../components/settings/ImportTaskList.vue'

tests/test_importer_attachments.py

@@ -59,3 +59,25 @@ def test_json_sidecar_is_not_attached(importer, import_layout):
         select(func.count()).select_from(PostAttachment)
     ).scalar_one()
     assert n == 0
+
+
+def test_mangled_filename_extension_is_sanitized(importer, import_layout):
+    """gallery-dl sometimes URL-encodes a query string into the basename
+    (`...https___www.patreon.com_media-u_Z0F...`). Python's Path.suffix
+    returns 50+ chars of base64-ish junk for those, which blows the
+    PostAttachment.ext varchar(32) column. Operator-flagged 2026-05-25.
+    The importer should record an empty ext rather than crash."""
+    import_root, _ = import_layout
+    f = (
+        import_root / "Alice"
+        / "79507046_media_https___www.patreon.com_media-u_Z0FBQUFBQm5q"
+    )
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_bytes(b"binary blob")
+    r = importer.import_one(f)
+    assert r.status == "attached"
+    att = importer.session.execute(select(PostAttachment)).scalar_one()
+    # Junk "extension" -> stored as empty string (not the 50-char garbage).
+    assert att.ext == ""
+    # original_filename is Text-typed so the full name survives intact.
+    assert att.original_filename.endswith("_Z0FBQUFBQm5q")

tests/test_phash_dedup.py

@@ -10,7 +10,15 @@ import pytest
 from PIL import Image
 from sqlalchemy import func, select
 
-from backend.app.models import ImageRecord, ImportSettings, Tag, TagKind
+from backend.app.models import (
+    ImageProvenance,
+    ImageRecord,
+    ImportSettings,
+    Post,
+    Source,
+    Tag,
+    TagKind,
+)
 from backend.app.models.tag import image_tag
 from backend.app.services.importer import Importer, SkipReason
 from backend.app.services.thumbnailer import Thumbnailer
@@ -141,6 +149,67 @@ def test_smaller_existing_is_superseded(importer, import_layout):
     assert Path(row.path).exists()
 
 
+def test_supersede_applies_new_file_sidecar(importer, import_layout):
+    """Operator-flagged 2026-05-25: scanning the GS download dir should
+    supersede smaller IR-migrated images AND wire up the GS sidecar's
+    Post/Source/ImageProvenance. Previously _supersede swapped the file
+    but ignored the sidecar entirely."""
+    import json
+    import_root, _ = import_layout
+
+    # Stage 1: a small, sidecar-less image (the "IR migration" precondition).
+    small = import_root / "ir-migration-folder" / "small.png"
+    _write(small, (60, 130, 200), (200, 200))
+    r1 = importer.import_one(small)
+    assert r1.status == "imported"
+    eid = r1.image_id
+
+    # Stage 2: a larger version of the same image (same phash) WITH a
+    # gallery-dl JSON sidecar adjacent. Live in a separate folder to
+    # simulate the GS download dir.
+    big = import_root / "Maewix" / "patreon" / "01_big.png"
+    _write(big, (60, 130, 200), (900, 900))
+    sidecar_path = big.with_suffix(big.suffix + ".json")
+    sidecar_path.parent.mkdir(parents=True, exist_ok=True)
+    sidecar_path.write_text(json.dumps({
+        "category": "patreon",
+        "id": 555,
+        "url": "https://www.patreon.com/posts/555",
+        "title": "Set 1",
+        "content": "<p>The big version</p>",
+        "page_count": 1,
+        "published_at": "2025-08-01T00:00:00+00:00",
+        "artist": "Maewix",
+    }))
+
+    r2 = importer.import_one(big)
+    assert r2.status == "superseded"
+    assert r2.image_id == eid
+
+    importer.session.expire_all()
+    # Row preserved, file replaced, sidecar metadata wired up.
+    row = importer.session.get(ImageRecord, eid)
+    assert row.width == 900 and row.height == 900
+
+    post = importer.session.execute(
+        select(Post).where(Post.external_post_id == "555")
+    ).scalar_one()
+    assert post.post_title == "Set 1"
+    assert "big version" in (post.description or "")
+
+    source = importer.session.execute(
+        select(Source).where(Source.id == post.source_id)
+    ).scalar_one()
+    assert source.platform == "patreon"
+
+    prov_count = importer.session.execute(
+        select(func.count(ImageProvenance.id))
+        .where(ImageProvenance.image_record_id == eid)
+        .where(ImageProvenance.post_id == post.id)
+    ).scalar_one()
+    assert prov_count == 1
+
+
 def test_threshold_controls_match(importer, import_layout):
     # Structurally distinct images (orthogonal splits) are far apart in
     # phash space, so a tight threshold keeps them independent rather than