feat(agent): survive + auto-recover when curator is unreachable

For redeploying curator while away with nobody to restart the agent:

- _process now distinguishes a TRANSPORT error (curator down/redeploying, 5xx,
  401/403/408/409/429, or our lease reclaimed mid-flight) from a genuine job
  fault. On a transport error it hands the job back (best effort) and signals
  the loop to back off — instead of calling fail(), which would burn the job's
  server-side attempt budget (MAX_ATTEMPTS=3) and permanently error good jobs
  across a redeploy. Job-specific 4xx (404 image gone) still fail so they don't
  re-lease forever.
- lease loop retries with capped exponential backoff (poll_idle → 60s) and
  resets on the first successful lease, so a long outage is gentle and recovery
  is automatic within ≤60s of curator returning. Sleeps are interruptible so
  Stop / pool-shrink stays responsive.
- AUTO_START env (default on in compose) resumes the worker on container start,
  so a host reboot / crash-restart (restart: unless-stopped) self-heals with
  nobody at the desktop.
- control UI shows a "waited out" counter + an "curator unreachable, holding
  work" banner so the recovering state reads as recovery, not failure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ttrj5P7upUTueSfoJcxEqa

.forgejo/workflows/build.yml

@@ -329,3 +329,41 @@ jobs:
           file: Dockerfile.ml
           push: true
           tags: ${{ steps.tag.outputs.tags }}
+
+  # The desktop GPU agent (#114) — published so the operator pulls + runs it on
+  # the GPU machine instead of building locally. Independent of web/ml (its own
+  # CUDA + onnxruntime-gpu image, context = agent/). Same tag cadence.
+  build-agent:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Determine tag
+        id: tag
+        run: |
+          SHORT_SHA=$(printf '%s' "$GITHUB_SHA" | cut -c1-7)
+          if [ "${GITHUB_REF#refs/tags/}" != "${GITHUB_REF}" ]; then
+            TAG_NAME="${GITHUB_REF#refs/tags/}"
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator-agent:${TAG_NAME}" >> "$GITHUB_OUTPUT"
+          elif [ "${GITHUB_REF##*/}" = "main" ]; then
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator-agent:main,git.fabledsword.com/bvandeusen/fabledcurator-agent:latest,git.fabledsword.com/bvandeusen/fabledcurator-agent:c-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=git.fabledsword.com/bvandeusen/fabledcurator-agent:dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Login to Forgejo registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.fabledsword.com
+          username: ${{ github.actor }}
+          password: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Build and push agent image
+        uses: docker/build-push-action@v5
+        with:
+          context: agent
+          file: agent/Dockerfile
+          push: true
+          tags: ${{ steps.tag.outputs.tags }}

agent/Dockerfile

@@ -0,0 +1,27 @@
+# FabledCurator GPU agent — runs on the desktop with the GPU.
+# CUDA + cuDNN runtime so onnxruntime-gpu can use the card (it needs cuDNN 9 —
+# the plain -runtime image lacks it: "libcudnn.so.9: cannot open shared object
+# file"); ffmpeg for video frames.
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+
+ENV DEBIAN_FRONTEND=noninteractive PYTHONUNBUFFERED=1
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 python3-pip ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+# torch from the CUDA-12.4 wheel index (matches the base image); its wheels
+# bundle their own CUDA + cuDNN and coexist with onnxruntime-gpu. Installed
+# first + separately so the GPU build of torch is deterministic and layer-cached.
+RUN pip3 install --no-cache-dir torch==2.6.0 --index-url https://download.pytorch.org/whl/cu124
+COPY requirements.txt .
+RUN pip3 install --no-cache-dir -r requirements.txt
+COPY fc_agent ./fc_agent
+
+# imgutils ONNX models + the transformers SigLIP weights both cache here; mount
+# a volume to persist them across restarts (the SigLIP download is ~3.5 GB once).
+ENV HF_HOME=/models
+EXPOSE 8770
+
+# The control UI; the worker is started from it (or POST /start).
+CMD ["uvicorn", "fc_agent.app:app", "--host", "0.0.0.0", "--port", "8770"]

agent/README.md

@@ -0,0 +1,71 @@
+# FabledCurator GPU agent
+
+A desktop-GPU worker that embeds characters (CCIP) + figure crops for
+FabledCurator. It talks to FC **only over HTTP** — it leases jobs, fetches image
+pixels, runs the models on your GPU, and posts results back. Your FC database and
+Redis stay private; the agent never touches them.
+
+You run it when you want a burst and stop it to reclaim the card.
+
+## 0. Host prerequisite — NVIDIA Container Toolkit
+Docker needs the toolkit to hand the GPU to a container (else: *"could not select
+device driver nvidia with capabilities [[gpu]]"*). On Arch/CachyOS:
+```sh
+sudo pacman -S nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+# verify:
+docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
+```
+
+## 1. Get a token
+In FC: **Settings → Tagging → GPU agent → Generate token** (or Rotate). Copy it.
+
+## 2. Pull (CI publishes it alongside the web/ml images)
+```sh
+docker pull git.fabledsword.com/bvandeusen/fabledcurator-agent:latest
+```
+> Local build for development instead: `docker build -t fc-gpu-agent agent/`
+
+## 3. Run (on the machine with the GPU)
+```sh
+docker run --rm --gpus all -p 8770:8770 \
+  -e FC_URL=http://curator.traefik.internal \
+  -e FC_TOKEN=<paste-the-token> \
+  -v fc-agent-models:/models \
+  git.fabledsword.com/bvandeusen/fabledcurator-agent:latest
+```
+Then open <http://localhost:8770> — the control page. Click **Start** to begin
+draining the queue; **Pause**/**Stop** to yield the GPU. The `-v fc-agent-models`
+volume caches the downloaded ONNX models so restarts are fast.
+
+Kick off a backfill from FC (**GPU agent card → Queue character embedding**), then
+watch the queue counts on the control page (or FC's card) drain.
+
+## Config (env)
+| var | default | meaning |
+|---|---|---|
+| `FC_URL` | `http://localhost:8000` | FC base URL |
+| `FC_TOKEN` | — | the bearer token (required) |
+| `AGENT_ID` | `desktop-agent` | identifies this agent's leases |
+| `BATCH_SIZE` | `4` | jobs leased per round (still processed one at a time) |
+| `CCIP_MODEL` | imgutils default | CCIP model name |
+| `DETECTOR_LEVEL` | `m` | person-detector size: `n` < `s` < `m` < `x` |
+| `POLL_IDLE_SECONDS` | `10` | wait between empty leases |
+
+## ⚠️ Verify on first run
+This part can't be CI-tested (no GPU/models in CI), so confirm against your
+installed `dghs-imgutils` (`pip show dghs-imgutils`) — see `fc_agent/models.py`:
+- `imgutils.detect.detect_person(image, level=...)` returns
+  `[((x0,y0,x1,y1), label, score), ...]`.
+- `imgutils.metrics.ccip_extract_feature(image, model=...)` returns a vector
+  (768-d for caformer). If you want the F1-0.94 variant, set
+  `CCIP_MODEL=ccip-caformer_b36-24` (verify the exact string in imgutils).
+
+If FC's matcher under/over-fires, tune the cosine threshold in
+`backend/app/services/ml/ccip.py` (`DEFAULT_SIM_THRESHOLD`) and use
+`GET /api/ccip/overview` + `/api/ccip/images/<id>` to spot-check.
+
+## CPU fallback
+Swap `onnxruntime-gpu` → `onnxruntime` in `requirements.txt` and drop `--gpus all`
+to grind it slowly on the server instead. Same agent, no card.

agent/docker-compose.yml

@@ -0,0 +1,53 @@
+# FabledCurator GPU agent — desktop run via docker compose.
+#
+# Usage:
+#   1. Generate a token: FC → Settings → Tagging → GPU agent → Generate token.
+#   2. Create a .env next to this file:
+#        FC_URL=http://curator.traefik.internal
+#        FC_TOKEN=<paste-the-token>
+#        # optional: CCIP_MODEL=ccip-caformer_b36-24   (the F1-0.94 variant)
+#   3. docker compose up -d     (pulls the published image)
+#   4. Open http://localhost:8770 → Start. Pause/Stop hands the GPU back.
+#      docker compose down       to stop the container entirely.
+#
+# Surviving a curator redeploy (you're away, can't touch the agent):
+#   - A running agent rides out curator being unreachable on its own — it retries
+#     leasing with capped backoff and resumes when the server is back. In-flight
+#     work is handed back (not failed), so a redeploy never poisons good jobs.
+#   - AUTO_START=1 (below) also resumes the worker if the AGENT container itself
+#     restarts (host reboot / crash via `restart: unless-stopped`) — no click.
+#
+# Needs the NVIDIA Container Toolkit installed on the host for --gpus.
+
+services:
+  fc-gpu-agent:
+    image: git.fabledsword.com/bvandeusen/fabledcurator-agent:latest
+    pull_policy: always
+    ports:
+      - "8770:8770"
+    environment:
+      FC_URL: ${FC_URL:-http://curator.traefik.internal}
+      FC_TOKEN: ${FC_TOKEN:?set FC_TOKEN in .env (FC → GPU agent → Generate token)}
+      CCIP_MODEL: ${CCIP_MODEL:-}
+      DETECTOR_LEVEL: ${DETECTOR_LEVEL:-m}
+      BATCH_SIZE: ${BATCH_SIZE:-4}
+      # Resume the worker automatically on container start (survive a reboot /
+      # crash-restart while you're away). Set to 0 to require a manual Start.
+      AUTO_START: ${AUTO_START:-1}
+      # Crop embedder (SigLIP concept bag): float16 keeps VRAM low on a shared
+      # desktop GPU; the model itself is announced by the server.
+      SIGLIP_DTYPE: ${SIGLIP_DTYPE:-float16}
+    volumes:
+      # Persist the downloaded ONNX models so restarts are fast.
+      - fc-agent-models:/models
+    restart: unless-stopped
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]
+
+volumes:
+  fc-agent-models:

agent/fc_agent/app.py

@@ -0,0 +1,134 @@
+"""FastAPI control surface for the agent (served on localhost).
+
+Start / stop the worker pool, tune the worker count live (trades desktop
+responsiveness for throughput), and watch GPU load + progress + the server-side
+queue. Config is env-seeded; the worker count is adjustable here on the fly.
+"""
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from .config import Config
+from .gpu import read_gpu
+from .worker import Worker
+
+cfg = Config.from_env()
+worker = Worker(cfg)
+app = FastAPI(title="FabledCurator GPU agent")
+
+
+@app.on_event("startup")
+def _maybe_autostart() -> None:
+    # With AUTO_START set, a container restart (host reboot, or `restart:
+    # unless-stopped` after a crash) resumes the worker on its own — the slots
+    # then ride out a still-down curator via lease backoff. Lets the agent
+    # survive a redeploy with nobody at the desktop to click Start.
+    if cfg.auto_start and cfg.token:
+        worker.start()
+
+
+@app.get("/", response_class=HTMLResponse)
+def index() -> str:
+    return _PAGE
+
+
+@app.post("/start")
+def start():
+    worker.start()
+    return JSONResponse(worker.status())
+
+
+@app.post("/stop")
+def stop():
+    worker.stop()
+    return JSONResponse(worker.status())
+
+
+@app.post("/concurrency")
+async def concurrency(request: Request):
+    body = await request.json()
+    worker.set_concurrency(int(body.get("value", 1)))
+    return JSONResponse(worker.status())
+
+
+@app.get("/status")
+def status():
+    s = worker.status()
+    s["fc_url"] = cfg.fc_url
+    s["configured"] = bool(cfg.token)
+    s["gpu"] = read_gpu()
+    try:
+        s["queue"] = worker.client.queue_status()
+    except Exception:
+        s["queue"] = None
+    return JSONResponse(s)
+
+
+_PAGE = """<!doctype html><html><head><meta charset=utf-8>
+<title>FabledCurator GPU agent</title>
+<style>
+ body{font:14px system-ui;margin:2rem;max-width:680px;background:#14171a;color:#e8e8e8}
+ h1{font-size:18px} button{font:14px system-ui;padding:.5rem 1rem;border:0;border-radius:6px;
+ margin-right:.5rem;cursor:pointer;color:#fff} .start{background:#2e7d32}.stop{background:#b3261e}
+ .step{background:#33373b;padding:.4rem .7rem;font-weight:700}
+ .stat{display:inline-block;margin-right:1.5rem;vertical-align:top}
+ .n{font-size:22px;font-weight:700} code{background:#222;padding:2px 6px;border-radius:4px}
+ .q,.gpu{margin-top:1rem;color:#9aa} .bar{height:8px;border-radius:4px;background:#222;overflow:hidden;
+ max-width:320px;margin-top:4px} .bar>i{display:block;height:100%;background:#3f7d3f}
+ .row{margin:.8rem 0}
+</style></head><body>
+<h1>FabledCurator GPU agent</h1>
+<p>FC: <code id=fc>—</code> · token <code id=cfg>—</code></p>
+<div class=row>
+ <button class=start onclick=act('start')>Start</button>
+ <button class=stop onclick=act('stop')>Stop</button>
+</div>
+<div class=row>
+ workers
+ <button class=step onclick=setc(-1)>−</button>
+ <input id=conc type=number min=1 value=1
+  style="width:3.5rem;font:700 16px system-ui;text-align:center;background:#222;color:#e8e8e8;border:1px solid #444;border-radius:6px;padding:.3rem"
+  onchange="setv(this.value)">
+ <button class=step onclick=setc(1)>+</button>
+ <span class=cap style=color:#9aa>(more = overlap I/O, fill the GPU) max <b id=capn>8</b></span>
+</div>
+<div class=row>
+ <span class=stat><span class=n id=state>stopped</span><br>state</span>
+ <span class=stat><span class=n id=active>0</span><br>active now</span>
+ <span class=stat><span class=n id=done>0</span><br>processed</span>
+ <span class=stat><span class=n id=err>0</span><br>errors</span>
+ <span class=stat><span class=n id=wait>0</span><br>waited out</span>
+</div>
+<div id=banner style="display:none;margin:.6rem 0;padding:.5rem .8rem;border-radius:6px;background:#5a4a17;color:#ffe28a">
+ curator unreachable — holding work + retrying, will resume on its own (no restart needed)
+</div>
+<div class=gpu id=gpu>GPU — …</div>
+<div class=bar><i id=gpubar style=width:0%></i></div>
+<div class=q id=queue></div>
+<script>
+ let CAP=8
+ async function act(p){await fetch('/'+p,{method:'POST'});refresh()}
+ function setc(d){ setv((parseInt(conc.value||'1'))+d) }
+ async function setv(v){
+  v=Math.max(1,Math.min(CAP,parseInt(v)||1)); conc.value=v
+  await fetch('/concurrency',{method:'POST',headers:{'Content-Type':'application/json'},
+   body:JSON.stringify({value:v})});refresh()
+ }
+ async function refresh(){
+  const s=await (await fetch('/status')).json()
+  CAP=s.max_concurrency||8; capn.textContent=CAP
+  state.textContent=s.state; active.textContent=s.active; done.textContent=s.processed
+  err.textContent=s.errors; fc.textContent=s.fc_url; wait.textContent=s.transient||0
+  // Running but the queue read failed → curator is unreachable; show we're
+  // riding it out rather than erroring.
+  banner.style.display=(s.state==='running' && !s.queue)?'block':'none'
+  if(document.activeElement!==conc) conc.value=s.concurrency
+  conc.max=CAP
+  cfg.textContent=s.configured?'set':'MISSING'
+  if(s.gpu){
+   gpu.textContent=`GPU — ${s.gpu.util_pct}% util · VRAM ${s.gpu.mem_used_mb}/${s.gpu.mem_total_mb} MB · ${s.gpu.temp_c}°C`
+   gpubar.style.width=Math.round(100*s.gpu.mem_used_mb/s.gpu.mem_total_mb)+'%'
+  } else { gpu.textContent='GPU — n/a (CPU fallback?)'; gpubar.style.width='0%' }
+  queue.textContent=s.queue?`queue — pending ${s.queue.pending} · in flight ${s.queue.leased} · done ${s.queue.done} · errored ${s.queue.error}`:'queue — unreachable'
+ }
+ refresh(); setInterval(refresh,3000)
+</script></body></html>"""

agent/fc_agent/client.py

@@ -0,0 +1,85 @@
+"""HTTP client for the FabledCurator GPU-job API.
+
+The agent's ONLY contact with FC — lease/submit/heartbeat/fail + fetch image
+bytes, all over HTTP with the bearer token. No DB/Redis.
+"""
+import requests
+from requests.adapters import HTTPAdapter
+
+
+class FcClient:
+    def __init__(self, base_url: str, token: str, agent_id: str):
+        self.base = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self.s = requests.Session()
+        self.s.headers["Authorization"] = f"Bearer {token}"
+        # Many worker threads share this Session; the default pool (10) would
+        # throttle them + spam "connection pool is full". Size it for the cap.
+        adapter = HTTPAdapter(pool_connections=64, pool_maxsize=64)
+        self.s.mount("http://", adapter)
+        self.s.mount("https://", adapter)
+
+    def lease(self, batch_size: int) -> list[dict]:
+        r = self.s.post(
+            f"{self.base}/api/gpu/jobs/lease",
+            json={"agent_id": self.agent_id, "batch_size": batch_size},
+            timeout=30,
+        )
+        r.raise_for_status()
+        return r.json().get("jobs", [])
+
+    def submit(self, job_id: int, regions: list[dict], replace_kinds: list[str]) -> dict:
+        r = self.s.post(
+            f"{self.base}/api/gpu/jobs/submit",
+            json={
+                "agent_id": self.agent_id, "job_id": job_id,
+                "regions": regions, "replace_kinds": replace_kinds,
+            },
+            timeout=120,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def heartbeat(self, job_ids: list[int]) -> None:
+        try:
+            self.s.post(
+                f"{self.base}/api/gpu/jobs/heartbeat",
+                json={"agent_id": self.agent_id, "job_ids": job_ids},
+                timeout=30,
+            )
+        except requests.RequestException:
+            pass
+
+    def fail(self, job_id: int, error: str) -> None:
+        try:
+            self.s.post(
+                f"{self.base}/api/gpu/jobs/fail",
+                json={"agent_id": self.agent_id, "job_id": job_id, "error": error},
+                timeout=30,
+            )
+        except requests.RequestException:
+            pass
+
+    def release(self, job_ids: list[int]) -> None:
+        # Graceful hand-back on stop so orphaned work is re-leased at once.
+        if not job_ids:
+            return
+        try:
+            self.s.post(
+                f"{self.base}/api/gpu/jobs/release",
+                json={"agent_id": self.agent_id, "job_ids": job_ids},
+                timeout=30,
+            )
+        except requests.RequestException:
+            pass
+
+    def fetch_image(self, image_url: str) -> bytes:
+        # image_url is a server-relative path ("/images/...").
+        r = self.s.get(f"{self.base}{image_url}", timeout=180)
+        r.raise_for_status()
+        return r.content
+
+    def queue_status(self) -> dict:
+        r = self.s.get(f"{self.base}/api/gpu/status", timeout=15)
+        r.raise_for_status()
+        return r.json()

agent/fc_agent/config.py

@@ -0,0 +1,36 @@
+"""Agent config, all from env (the control container is configured at run)."""
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    fc_url: str          # base URL of the FabledCurator web service
+    token: str           # the bearer token from Settings → Tagging → GPU agent
+    agent_id: str        # identifies this agent's leases
+    batch_size: int      # jobs a worker leases per round
+    concurrency: int     # INITIAL parallel workers (tunable live from the UI)
+    ccip_model: str      # imgutils CCIP model name ("" → imgutils default)
+    detector_level: str  # imgutils person-detector level: n|s|m|x
+    poll_idle_seconds: float   # wait between empty leases
+    embed_dtype: str     # torch dtype for the crop embedder: float16|float32
+    embed_model_override: str  # force a SigLIP-family model ("" → use the one
+    #                            the server announces in the lease)
+    auto_start: bool     # start the worker pool on boot (so a container restart
+    #                      resumes processing without anyone clicking Start)
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        return cls(
+            fc_url=os.environ.get("FC_URL", "http://localhost:8000").rstrip("/"),
+            token=os.environ.get("FC_TOKEN", ""),
+            agent_id=os.environ.get("AGENT_ID", "desktop-agent"),
+            batch_size=int(os.environ.get("BATCH_SIZE", "4")),
+            concurrency=int(os.environ.get("CONCURRENCY", "1")),
+            ccip_model=os.environ.get("CCIP_MODEL", ""),
+            detector_level=os.environ.get("DETECTOR_LEVEL", "m"),
+            poll_idle_seconds=float(os.environ.get("POLL_IDLE_SECONDS", "10")),
+            embed_dtype=os.environ.get("SIGLIP_DTYPE", "float16"),
+            embed_model_override=os.environ.get("EMBED_MODEL_NAME", ""),
+            auto_start=os.environ.get("AUTO_START", "").lower() in ("1", "true", "yes"),
+        )

agent/fc_agent/crops.py

@@ -0,0 +1,36 @@
+"""Crop primitive — vendored from backend/app/services/ml/crops.py so the agent
+is self-contained. Keep in sync if the floor logic changes."""
+from PIL import Image
+
+MIN_CROP_FRACTION = 0.10
+MIN_CROP_PX = 64
+
+
+def crop_region(
+    img: Image.Image,
+    bbox: tuple[float, float, float, float],
+    *,
+    pad: float = 0.0,
+    min_fraction: float = MIN_CROP_FRACTION,
+    min_px: int = MIN_CROP_PX,
+) -> Image.Image | None:
+    """Crop a NORMALIZED bbox (x, y, w, h in [0,1]); None if below the size
+    floor (max of a fraction-of-short-side and an absolute pixel floor)."""
+    iw, ih = img.size
+    x, y, w, h = bbox
+    px, py, pw, ph = x * iw, y * ih, w * iw, h * ih
+    if pad:
+        px -= pw * pad / 2.0
+        py -= ph * pad / 2.0
+        pw *= (1.0 + pad)
+        ph *= (1.0 + pad)
+    left = max(0, int(round(px)))
+    top = max(0, int(round(py)))
+    right = min(iw, int(round(px + pw)))
+    bottom = min(ih, int(round(py + ph)))
+    if right <= left or bottom <= top:
+        return None
+    floor = max(min_px, int(min_fraction * min(iw, ih)))
+    if min(right - left, bottom - top) < floor:
+        return None
+    return img.crop((left, top, right, bottom)).convert("RGB")

agent/fc_agent/embedder.py

@@ -0,0 +1,69 @@
+"""Crop EMBEDDER for the concept bag — model-agnostic (CLIP/SigLIP-family).
+
+The server trains its per-concept heads in the embedding space of whatever model
+its `embedder_model_version` names; a crop must be embedded with the SAME model
+or its vector lands in a different coordinate system and every head misfires. So
+the model identity (HF name + version) is ANNOUNCED BY THE SERVER in the lease —
+nothing here is hardcoded to SigLIP. Whatever name the server sends is loaded via
+transformers `get_image_features` (the CLIP/SigLIP-family image-tower call); a
+non-CLIP backbone (e.g. a DINO encoder) would need its own pooling adapter.
+
+torch on CUDA, fp16 by default to keep VRAM low on a shared desktop GPU — the
+tiny fp16-vs-fp32 difference is negligible for the linear heads (cosine ~0.999).
+A single inference lock serializes the forward pass: the pipeline is I/O-bound,
+so the GPU isn't the bottleneck, and one model shared across worker threads is
+safest behind a lock.
+"""
+import threading
+
+import numpy as np
+from PIL import Image
+
+
+class CropEmbedder:
+    def __init__(self, model_name: str, dtype: str = "float16"):
+        self._name = model_name
+        self._dtype_name = dtype
+        self._model = None
+        self._processor = None
+        self._torch = None
+        self._device = None
+        self._dt = None
+        self._load_lock = threading.Lock()
+        self._infer_lock = threading.Lock()
+
+    @property
+    def model_name(self) -> str:
+        return self._name
+
+    def load(self) -> None:
+        if self._model is not None:
+            return
+        with self._load_lock:
+            if self._model is not None:
+                return
+            import torch
+            from transformers import AutoImageProcessor, AutoModel
+
+            self._torch = torch
+            self._device = "cuda" if torch.cuda.is_available() else "cpu"
+            dt = getattr(torch, self._dtype_name, torch.float16)
+            if self._device == "cpu":
+                dt = torch.float32   # fp16 matmul is unsupported/slow on CPU
+            self._dt = dt
+            self._processor = AutoImageProcessor.from_pretrained(self._name)
+            model = AutoModel.from_pretrained(self._name, torch_dtype=dt)
+            model.eval().to(self._device)
+            self._model = model
+
+    def embed(self, image: Image.Image) -> list[float]:
+        """A crop → its embedding as a plain float list, ready to POST."""
+        self.load()
+        torch = self._torch
+        enc = self._processor(images=image, return_tensors="pt")
+        pixel_values = enc["pixel_values"].to(self._device, self._dt)
+        with self._infer_lock, torch.no_grad():
+            out = self._model.get_image_features(pixel_values=pixel_values)
+        pooled = out.pooler_output if hasattr(out, "pooler_output") else out
+        vec = pooled[0].float().cpu().numpy().astype(np.float32).reshape(-1)
+        return vec.tolist()

agent/fc_agent/gpu.py

@@ -0,0 +1,30 @@
+"""GPU load readout via nvidia-smi (present in the container thanks to the
+NVIDIA Container Toolkit's `utility` capability). Returns None if unavailable —
+the UI just shows n/a (e.g. CPU-fallback run)."""
+import subprocess
+
+
+def read_gpu() -> dict | None:
+    try:
+        out = subprocess.run(
+            [
+                "nvidia-smi",
+                "--query-gpu=utilization.gpu,memory.used,memory.total,temperature.gpu",
+                "--format=csv,noheader,nounits",
+            ],
+            capture_output=True, text=True, timeout=5, check=True,
+        ).stdout.strip().splitlines()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if not out:
+        return None
+    parts = [p.strip() for p in out[0].split(",")]
+    try:
+        return {
+            "util_pct": int(float(parts[0])),
+            "mem_used_mb": int(float(parts[1])),
+            "mem_total_mb": int(float(parts[2])),
+            "temp_c": int(float(parts[3])),
+        }
+    except (ValueError, IndexError):
+        return None

agent/fc_agent/media.py

@@ -0,0 +1,63 @@
+"""Image + video handling. Stills load directly; videos are sampled into frames
+(ffmpeg) at the cadence FC sends — so a video becomes a bag of per-frame
+instances, each with a timestamp."""
+import io
+import os
+import subprocess
+import tempfile
+
+from PIL import Image
+
+
+def is_video(mime: str) -> bool:
+    return bool(mime) and (mime.startswith("video/") or mime in {"image/gif"})
+
+
+def to_rgb(img: Image.Image) -> Image.Image:
+    """RGB, flattening any transparency onto white first. A naive convert('RGB')
+    on a palette-with-transparency image (common for character PNGs on a clear
+    background) lets PIL guess the transparent pixels — usually black artifacts
+    that bleed into the crop + the embedding (and the "should be converted to
+    RGBA" warning). Compositing over white gives a clean, consistent background."""
+    if img.mode in ("RGBA", "LA", "PA") or (
+        img.mode == "P" and "transparency" in img.info
+    ):
+        img = img.convert("RGBA")
+        bg = Image.new("RGBA", img.size, (255, 255, 255, 255))
+        return Image.alpha_composite(bg, img).convert("RGB")
+    return img.convert("RGB")
+
+
+def load_image(data: bytes) -> Image.Image:
+    return to_rgb(Image.open(io.BytesIO(data)))
+
+
+def sample_frames(
+    data: bytes, interval_seconds: float, max_frames: int
+) -> list[tuple[float, Image.Image]]:
+    """Extract up to max_frames frames at one-every-interval_seconds via ffmpeg.
+    Returns [(timestamp_seconds, frame)]. Empty on failure (caller falls back)."""
+    interval = max(0.5, float(interval_seconds or 4.0))
+    cap = max(1, int(max_frames or 64))
+    with tempfile.TemporaryDirectory() as tmp:
+        src = os.path.join(tmp, "in")
+        with open(src, "wb") as fh:
+            fh.write(data)
+        pattern = os.path.join(tmp, "f_%05d.jpg")
+        try:
+            subprocess.run(
+                [
+                    "ffmpeg", "-nostdin", "-loglevel", "error", "-i", src,
+                    "-vf", f"fps=1/{interval}", "-frames:v", str(cap),
+                    "-q:v", "3", pattern,
+                ],
+                check=True, timeout=600,
+            )
+        except (subprocess.SubprocessError, FileNotFoundError):
+            return []
+        out: list[tuple[float, Image.Image]] = []
+        names = sorted(n for n in os.listdir(tmp) if n.startswith("f_"))
+        for i, name in enumerate(names[:cap]):
+            with Image.open(os.path.join(tmp, name)) as im:
+                out.append((round(i * interval, 2), to_rgb(im)))
+        return out

agent/fc_agent/models.py

@@ -0,0 +1,39 @@
+"""imgutils model wrappers — the figure DETECTOR + the CCIP EMBEDDER.
+
+⚠️ VERIFY ON FIRST RUN: the exact imgutils function names/signatures + the CCIP
+model string can drift between dghs-imgutils releases. These are the two seams to
+check against your installed version (`pip show dghs-imgutils`):
+  - detect_person(image, level=...) -> [((x0,y0,x1,y1), label, score), ...]
+  - ccip_extract_feature(image, model=...) -> a vector (768-d for caformer)
+imgutils auto-downloads the ONNX models from HuggingFace on first use; GPU is
+used when onnxruntime-gpu is installed.
+"""
+import numpy as np
+from PIL import Image
+
+
+def detect_figures(image: Image.Image, level: str = "m") -> list[tuple[tuple, float | None]]:
+    """Person/figure bounding boxes, NORMALIZED (x, y, w, h in [0,1]) + score.
+    Returns [] if detection finds nothing (caller falls back to whole-image)."""
+    from imgutils.detect import detect_person
+
+    iw, ih = image.size
+    out = []
+    for (x0, y0, x1, y1), _label, score in detect_person(image, level=level):
+        out.append((
+            (x0 / iw, y0 / ih, (x1 - x0) / iw, (y1 - y0) / ih),
+            float(score),
+        ))
+    return out
+
+
+def ccip_vector(image: Image.Image, model: str | None = None) -> list[float]:
+    """The CCIP identity embedding of a (cropped) character image, as a plain
+    float list ready to POST."""
+    from imgutils.metrics import ccip_extract_feature
+
+    feat = (
+        ccip_extract_feature(image, model=model)
+        if model else ccip_extract_feature(image)
+    )
+    return np.asarray(feat, dtype=np.float32).reshape(-1).tolist()

agent/fc_agent/worker.py

@@ -0,0 +1,274 @@
+"""The lease → fetch → detect+embed → submit loop, run by a pool of worker
+slots whose count is tunable live from the UI.
+
+Each slot is an independent loop (its own leases; the server's SKIP-LOCKED lease
+keeps them from colliding). More slots = more GPU load + throughput; the model is
+loaded once and shared, so slots add concurrent inference, not N× model VRAM.
+That's the dial the operator turns to trade desktop responsiveness for speed.
+
+Stop (or shrinking the pool) RELEASES a slot's still-leased jobs immediately so
+orphaned work is re-picked at once rather than waiting out the lease.
+"""
+import threading
+
+import requests
+
+from . import media, models
+from .client import FcClient
+from .config import Config
+from .crops import crop_region
+
+# Cap on the lease-retry backoff: when curator is unreachable (e.g. you redeploy
+# it while away), each slot retries leasing with exponential backoff up to this
+# many seconds, then resumes within this window once the server is back — no
+# restart needed.
+MAX_BACKOFF_SECONDS = 60.0
+
+
+def _is_transient(exc: "requests.RequestException") -> bool:
+    """A server/transport problem (wait it out) vs a job-specific fault (fail it).
+    No response → connection refused/timeout → curator is down → transient. With
+    a response: 5xx, auth (401/403, e.g. a token blip on redeploy), 408/409/429
+    (timeout / our lease reclaimed / rate-limited) are all 'not this job's fault'.
+    A specific 4xx like 404 (image gone) / 400 IS the job's fault → fail it."""
+    resp = getattr(exc, "response", None)
+    if resp is None:
+        return True
+    return resp.status_code >= 500 or resp.status_code in (401, 403, 408, 409, 429)
+
+# Generous cap: the pipeline is usually I/O-bound (downloading + decoding images
+# over HTTP), so the GPU stays underused until many workers overlap that I/O.
+# Push it up while watching the GPU util + VRAM in the UI.
+MAX_CONCURRENCY = 32
+
+# Fallbacks only — the server ANNOUNCES the embedding model (name + version) in
+# the lease so the agent stays model-agnostic and in lock-step with the space
+# the heads were trained in. These cover an older server that doesn't send them.
+DEFAULT_EMBED_MODEL = "google/siglip-so400m-patch14-384"
+DEFAULT_EMBED_VERSION = "siglip-so400m-patch14-384"
+
+
+class _Slot:
+    """One worker loop. `inflight` = jobs leased but not yet processed, so a
+    graceful stop can hand them back."""
+    __slots__ = ("stop", "inflight")
+
+    def __init__(self):
+        self.stop = threading.Event()
+        self.inflight: list[int] = []
+
+
+class Worker:
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+        self.client = FcClient(cfg.fc_url, cfg.token, cfg.agent_id)
+        self._lock = threading.Lock()
+        self._running = False
+        self._target = max(1, min(MAX_CONCURRENCY, cfg.concurrency))
+        self._slots: list[_Slot] = []
+        self.processed = 0
+        self.errors = 0
+        self.transient = 0        # jobs handed back due to a server outage (NOT
+        #                           failed) — the "waiting out curator" counter
+        self._active = 0          # slots currently mid-image
+        # The crop embedder (SigLIP-family) is built lazily on the first job that
+        # needs it, from the model the server announces — one shared instance.
+        self._embedder = None
+        self._embedder_lock = threading.Lock()
+
+    # --- control -----------------------------------------------------------
+    def start(self):
+        with self._lock:
+            self._running = True
+            self._reconcile_locked()
+
+    def stop(self):
+        with self._lock:
+            self._running = False
+            slots, self._slots = self._slots, []
+        for s in slots:
+            s.stop.set()          # each slot releases its inflight on exit
+
+    def set_concurrency(self, n: int):
+        with self._lock:
+            self._target = max(1, min(MAX_CONCURRENCY, int(n)))
+            if self._running:
+                self._reconcile_locked()
+
+    def _reconcile_locked(self):
+        while len(self._slots) < self._target:
+            slot = _Slot()
+            self._slots.append(slot)
+            threading.Thread(target=self._loop, args=(slot,), daemon=True).start()
+        while len(self._slots) > self._target:
+            self._slots.pop().stop.set()
+
+    def status(self) -> dict:
+        with self._lock:
+            return {
+                "state": "running" if self._running else "stopped",
+                "concurrency": self._target,
+                "max_concurrency": MAX_CONCURRENCY,
+                "workers": len(self._slots),
+                "active": self._active,
+                "processed": self.processed,
+                "errors": self.errors,
+                "transient": self.transient,
+            }
+
+    def _bump(self, *, processed=0, errors=0, active=0, transient=0):
+        with self._lock:
+            self.processed += processed
+            self.errors += errors
+            self.transient += transient
+            self._active += active
+
+    # --- per-slot loop -----------------------------------------------------
+    def _loop(self, slot: _Slot):
+        backoff = self.cfg.poll_idle_seconds
+        while not slot.stop.is_set() and self._running:
+            try:
+                jobs = self.client.lease(self.cfg.batch_size)
+                backoff = self.cfg.poll_idle_seconds      # server answered → reset
+            except Exception:
+                # curator unreachable (redeploy, network drop): wait it out with
+                # exponential backoff, capped — resume on our own when it returns.
+                self._interruptible_sleep(slot, backoff)
+                backoff = min(backoff * 2, MAX_BACKOFF_SECONDS)
+                continue
+            if not jobs:
+                self._interruptible_sleep(slot, self.cfg.poll_idle_seconds)
+                continue
+            slot.inflight = [j["job_id"] for j in jobs]
+            for job in jobs:
+                if slot.stop.is_set() or not self._running:
+                    break
+                ok = self._process(job)
+                slot.inflight = [i for i in slot.inflight if i != job["job_id"]]
+                if not ok:
+                    # Server went away mid-batch: hand the rest back (best effort)
+                    # and back off instead of hammering a recovering server or
+                    # burning the jobs' attempt budgets on fail().
+                    if slot.inflight:
+                        self.client.release(slot.inflight)
+                        slot.inflight = []
+                    self._interruptible_sleep(slot, backoff)
+                    backoff = min(backoff * 2, MAX_BACKOFF_SECONDS)
+                    break
+                if slot.inflight:
+                    self.client.heartbeat(slot.inflight)
+        # Graceful hand-back of anything leased but not processed.
+        if slot.inflight:
+            self.client.release(slot.inflight)
+            slot.inflight = []
+
+    def _interruptible_sleep(self, slot: _Slot, seconds: float):
+        """Sleep, but wake immediately if the slot is told to stop — so a Stop or
+        a pool-shrink doesn't hang for a full backoff window."""
+        slot.stop.wait(timeout=seconds)
+
+    def _ensure_embedder(self, model_name: str):
+        if self._embedder is not None:
+            return self._embedder
+        with self._embedder_lock:
+            if self._embedder is None:
+                from .embedder import CropEmbedder
+                self._embedder = CropEmbedder(model_name, self.cfg.embed_dtype)
+        return self._embedder
+
+    def _process(self, job: dict) -> bool:
+        """Process one job. Returns True when handled (completed, or hard-failed
+        because the job itself is bad) and False on a TRANSPORT error (curator
+        unreachable / 5xx / our lease was reclaimed mid-flight) — which is not
+        the job's fault, so the caller backs off and the job is left to be
+        re-leased rather than fail()ed into its attempt budget."""
+        self._bump(active=1)
+        try:
+            data = self.client.fetch_image(job["image_url"])
+            if media.is_video(job.get("mime", "")):
+                frames = media.sample_frames(
+                    data, job.get("frame_interval_seconds", 4.0),
+                    job.get("max_frames", 64),
+                ) or [(None, media.load_image(data))]
+            else:
+                frames = [(None, media.load_image(data))]
+
+            # task picks what to produce per crop:
+            #   'siglip' (backfill existing images) → concept (SigLIP) regions
+            #     ONLY, so it never churns their figure/CCIP regions or the
+            #     character-reference cache.
+            #   'ccip' / 'both' (a new image's first pass) → figure (CCIP) AND
+            #     concept (SigLIP) in one go, off the same crop.
+            task = job.get("task") or "ccip"
+            want_ccip = task in ("ccip", "both")
+            want_siglip = task in ("ccip", "siglip", "both")
+            replace_kinds = (
+                ["concept"] if task == "siglip" else ["figure", "face", "concept"]
+            )
+
+            embed_version = job.get("embed_version") or DEFAULT_EMBED_VERSION
+            embedder = None
+            if want_siglip:
+                model_name = (
+                    self.cfg.embed_model_override
+                    or job.get("embed_model_name")
+                    or DEFAULT_EMBED_MODEL
+                )
+                embedder = self._ensure_embedder(model_name)
+
+            regions = []
+            ccip_ev = self.cfg.ccip_model or "ccip-default"
+            dv = f"person-{self.cfg.detector_level}"
+            for t, frame in frames:
+                figs = models.detect_figures(frame, self.cfg.detector_level)
+                if not figs:
+                    figs = [((0.0, 0.0, 1.0, 1.0), None)]   # whole-frame fallback
+                for bbox, score in figs:
+                    crop = crop_region(frame, bbox)
+                    if crop is None:
+                        continue
+                    if want_ccip:
+                        regions.append({
+                            "kind": "figure",
+                            "bbox": list(bbox),
+                            "frame_time": t,
+                            "score": score,
+                            "ccip_embedding": models.ccip_vector(
+                                crop, self.cfg.ccip_model or None
+                            ),
+                            "embedding_version": ccip_ev,
+                            "detector_version": dv,
+                        })
+                    if want_siglip:
+                        regions.append({
+                            "kind": "concept",
+                            "bbox": list(bbox),
+                            "frame_time": t,
+                            "score": score,
+                            "siglip_embedding": embedder.embed(crop),
+                            "embedding_version": embed_version,
+                            "detector_version": dv,
+                        })
+            self.client.submit(job["job_id"], regions, replace_kinds)
+            self._bump(processed=1)
+            return True
+        except requests.RequestException as exc:
+            if _is_transient(exc):
+                # curator down/redeploying, a 5xx, or our lease was reclaimed
+                # while we worked. NOT the job's fault — hand it back (best
+                # effort; no-ops if the server is still down, then the server's
+                # orphan-recovery reclaims it) and signal the loop to wait.
+                self._bump(transient=1)
+                self.client.release([job["job_id"]])
+                return False
+            # A job-specific HTTP fault (404 image gone, 400) → fail it so it
+            # doesn't re-lease forever.
+            self._bump(errors=1)
+            self.client.fail(job["job_id"], str(exc)[:500])
+            return True
+        except Exception as exc:   # noqa: BLE001 — a genuine job fault: report it
+            self._bump(errors=1)
+            self.client.fail(job["job_id"], str(exc)[:500])
+            return True
+        finally:
+            self._bump(active=-1)

agent/requirements.txt

@@ -0,0 +1,15 @@
+# CCIP + figure detection (ONNX models, auto-downloaded from HuggingFace).
+dghs-imgutils>=0.4
+# GPU inference for the ONNX models. Swap to onnxruntime (CPU) for a slow
+# server-side fallback run.
+onnxruntime-gpu
+# The crop EMBEDDER (concept bag). torch is installed separately in the
+# Dockerfile from the CUDA-12.4 wheel index so the GPU build is deterministic;
+# transformers loads whatever SigLIP-family model the server announces.
+transformers>=4.45
+# Control surface + HTTP.
+fastapi
+uvicorn[standard]
+requests
+pillow
+numpy

alembic/versions/0058_tag_head.py

@@ -0,0 +1,95 @@
+"""tag_head + head_training_run: production heads that learn from tags (#114)
+
+The eval (#1130) proved the frozen-embedding + trained-head spine; this lands its
+production form. tag_head stores one logistic-regression head per concept (the
+new suggestion source, replacing Camie + centroid); head_training_run tracks the
+batch that (re)trains them. Adds two head-training tunables to ml_settings.
+
+Revision ID: 0058
+Revises: 0057
+Create Date: 2026-06-28
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from pgvector.sqlalchemy import Vector
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "0058"
+down_revision: Union[str, None] = "0057"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_HEAD_DIM = 1152
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tag_head",
+        sa.Column(
+            "tag_id", sa.Integer(),
+            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True,
+        ),
+        sa.Column("embedding_version", sa.String(length=128), nullable=False),
+        sa.Column("weights", Vector(_HEAD_DIM), nullable=False),
+        sa.Column("bias", sa.Float(), nullable=False),
+        sa.Column("suggest_threshold", sa.Float(), nullable=False),
+        sa.Column("auto_apply_threshold", sa.Float(), nullable=True),
+        sa.Column("n_pos", sa.Integer(), nullable=False),
+        sa.Column("n_neg", sa.Integer(), nullable=False),
+        sa.Column("ap", sa.Float(), nullable=False),
+        sa.Column("precision_cv", sa.Float(), nullable=False),
+        sa.Column("recall", sa.Float(), nullable=False),
+        sa.Column(
+            "trained_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column("metrics", JSONB(), nullable=True),
+    )
+
+    op.create_table(
+        "head_training_run",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("params", JSONB(), nullable=False),
+        sa.Column(
+            "status", sa.String(length=16), nullable=False,
+            server_default="running",
+        ),
+        sa.Column(
+            "started_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("n_trained", sa.Integer(), nullable=True),
+        sa.Column("n_skipped", sa.Integer(), nullable=True),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index(
+        "ix_head_training_run_status", "head_training_run", ["status"],
+    )
+
+    # Head-training tunables on the ml_settings singleton.
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "head_min_positives", sa.Integer(), nullable=False,
+            server_default="8",
+        ),
+    )
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "head_auto_apply_precision", sa.Float(), nullable=False,
+            server_default="0.97",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ml_settings", "head_auto_apply_precision")
+    op.drop_column("ml_settings", "head_min_positives")
+    op.drop_index("ix_head_training_run_status", table_name="head_training_run")
+    op.drop_table("head_training_run")
+    op.drop_table("tag_head")

alembic/versions/0059_head_auto_apply.py

@@ -0,0 +1,70 @@
+"""head_auto_apply_run + earned-auto-apply settings (#114)
+
+A graduated head can apply its tag without a human, gated by a master switch +
+a support floor. head_auto_apply_run tracks each sweep / dry-run preview.
+
+Revision ID: 0059
+Revises: 0058
+Create Date: 2026-06-29
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "0059"
+down_revision: Union[str, None] = "0058"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "head_auto_apply_run",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "dry_run", sa.Boolean(), nullable=False, server_default=sa.false()
+        ),
+        sa.Column("params", JSONB(), nullable=False),
+        sa.Column(
+            "status", sa.String(length=16), nullable=False,
+            server_default="running",
+        ),
+        sa.Column(
+            "started_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("n_applied", sa.Integer(), nullable=True),
+        sa.Column("report", JSONB(), nullable=True),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index(
+        "ix_head_auto_apply_run_status", "head_auto_apply_run", ["status"],
+    )
+
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "head_auto_apply_enabled", sa.Boolean(), nullable=False,
+            server_default=sa.true(),  # opt-out: on by default (operator-asked)
+        ),
+    )
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "head_auto_apply_min_positives", sa.Integer(), nullable=False,
+            server_default="30",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ml_settings", "head_auto_apply_min_positives")
+    op.drop_column("ml_settings", "head_auto_apply_enabled")
+    op.drop_index(
+        "ix_head_auto_apply_run_status", table_name="head_auto_apply_run"
+    )
+    op.drop_table("head_auto_apply_run")

alembic/versions/0060_head_metrics.py

@@ -0,0 +1,74 @@
+"""head_metric + head_metrics_snapshot: auto-apply observability (#114)
+
+Running misfire/under-fire counters per concept (captured at correction time,
+since image_tag.source is lost on delete) + a daily per-concept time-series so
+the operator can tune the precision target + support floor from real data.
+
+Revision ID: 0060
+Revises: 0059
+Create Date: 2026-06-29
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0060"
+down_revision: Union[str, None] = "0059"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "head_metric",
+        sa.Column(
+            "tag_id", sa.Integer(),
+            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True,
+        ),
+        sa.Column("n_misfires", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("n_underfires", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+    op.create_table(
+        "head_metrics_snapshot",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "tag_id", sa.Integer(),
+            sa.ForeignKey("tag.id", ondelete="CASCADE"),
+        ),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column(
+            "snapshot_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column("n_auto_applied", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("n_misfires", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("n_underfires", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("ap", sa.Float(), nullable=True),
+        sa.Column("precision_cv", sa.Float(), nullable=True),
+        sa.Column("recall", sa.Float(), nullable=True),
+        sa.Column("n_pos", sa.Integer(), nullable=True),
+    )
+    op.create_index(
+        "ix_head_metrics_snapshot_tag_id", "head_metrics_snapshot", ["tag_id"],
+    )
+    op.create_index(
+        "ix_head_metrics_snapshot_snapshot_at", "head_metrics_snapshot",
+        ["snapshot_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_head_metrics_snapshot_snapshot_at", table_name="head_metrics_snapshot"
+    )
+    op.drop_index(
+        "ix_head_metrics_snapshot_tag_id", table_name="head_metrics_snapshot"
+    )
+    op.drop_table("head_metrics_snapshot")
+    op.drop_table("head_metric")

alembic/versions/0061_image_region.py

@@ -0,0 +1,59 @@
+"""image_region: detected/proposed regions + their crop embeddings (#114)
+
+Storage backbone of the crop pipeline. A region = normalized bbox + the crop's
+embedding (CCIP for face/figure → character id; SigLIP for concept regions →
+head bag-of-embeddings). Also serves as grounded-tag bbox provenance.
+
+Revision ID: 0061
+Revises: 0060
+Create Date: 2026-06-29
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from pgvector.sqlalchemy import Vector
+
+revision: str = "0061"
+down_revision: Union[str, None] = "0060"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_CCIP_DIM = 768
+_SIGLIP_DIM = 1152
+
+
+def upgrade() -> None:
+    op.create_table(
+        "image_region",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "image_record_id", sa.Integer(),
+            sa.ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("kind", sa.String(length=16), nullable=False),
+        # Video/animated: source frame timestamp (seconds); NULL for stills.
+        sa.Column("frame_time", sa.Float(), nullable=True),
+        sa.Column("rx", sa.Float(), nullable=False),
+        sa.Column("ry", sa.Float(), nullable=False),
+        sa.Column("rw", sa.Float(), nullable=False),
+        sa.Column("rh", sa.Float(), nullable=False),
+        sa.Column("score", sa.Float(), nullable=True),
+        sa.Column("detector_version", sa.String(length=64), nullable=True),
+        sa.Column("crop_version", sa.String(length=64), nullable=True),
+        sa.Column("embedding_version", sa.String(length=128), nullable=True),
+        sa.Column("ccip_embedding", Vector(_CCIP_DIM), nullable=True),
+        sa.Column("siglip_embedding", Vector(_SIGLIP_DIM), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index(
+        "ix_image_region_image_record_id", "image_region", ["image_record_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_image_region_image_record_id", table_name="image_region")
+    op.drop_table("image_region")

alembic/versions/0062_gpu_job.py

@@ -0,0 +1,55 @@
+"""gpu_job: the HTTP-leased GPU work queue for the desktop agent (#114)
+
+The agent stays HTTP-only — the server enqueues per-(image, task) jobs here and
+the agent leases/submits over the web API; Redis/Postgres stay private.
+
+Revision ID: 0062
+Revises: 0061
+Create Date: 2026-06-29
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0062"
+down_revision: Union[str, None] = "0061"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "gpu_job",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "image_record_id", sa.Integer(),
+            sa.ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("task", sa.String(length=32), nullable=False),
+        sa.Column(
+            "status", sa.String(length=16), nullable=False,
+            server_default="pending",
+        ),
+        sa.Column("lease_token", sa.String(length=64), nullable=True),
+        sa.Column("leased_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("lease_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("attempts", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index("ix_gpu_job_image_record_id", "gpu_job", ["image_record_id"])
+    op.create_index("ix_gpu_job_status", "gpu_job", ["status"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_gpu_job_status", table_name="gpu_job")
+    op.drop_index("ix_gpu_job_image_record_id", table_name="gpu_job")
+    op.drop_table("gpu_job")

alembic/versions/0063_ccip_match_threshold.py

@@ -0,0 +1,33 @@
+"""ml_settings.ccip_match_threshold — tunable CCIP character-match cut (#114)
+
+The v1 matcher used a flat 0.75 cosine; live data showed that over-fires (a
+high-reference character matched a scatter of images). 0.85 keeps the confident
+single-character matches and drops the noise. Tunable from the GPU agent card.
+
+Revision ID: 0063
+Revises: 0062
+Create Date: 2026-06-29
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0063"
+down_revision: Union[str, None] = "0062"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "ccip_match_threshold", sa.Float(), nullable=False,
+            server_default="0.85",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ml_settings", "ccip_match_threshold")

alembic/versions/0064_ccip_auto_apply.py

@@ -0,0 +1,42 @@
+"""ml_settings: CCIP auto-apply switch + threshold (#114)
+
+Confident CCIP character matches auto-tag (source='ccip_auto') on a daily sweep,
+so identity tags keep flowing without pressing a button. ON by default (opt-out,
+like head auto-apply); the high threshold (0.92, above the 0.85 suggest cut) +
+single-character references keep it safe, and every auto-tag is reversible.
+
+Revision ID: 0064
+Revises: 0063
+Create Date: 2026-06-30
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0064"
+down_revision: Union[str, None] = "0063"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "ccip_auto_apply_enabled", sa.Boolean(), nullable=False,
+            server_default=sa.true(),
+        ),
+    )
+    op.add_column(
+        "ml_settings",
+        sa.Column(
+            "ccip_auto_apply_threshold", sa.Float(), nullable=False,
+            server_default="0.92",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ml_settings", "ccip_auto_apply_threshold")
+    op.drop_column("ml_settings", "ccip_auto_apply_enabled")

backend/app/api/__init__.py

@@ -20,11 +20,14 @@ def all_blueprints() -> list[Blueprint]:
     from .artist import artist_bp
     from .artists import artists_bp
     from .attachments import attachments_bp
+    from .ccip import ccip_bp
     from .cleanup import cleanup_bp
     from .credentials import credentials_bp
     from .downloads import downloads_bp
     from .extension import extension_bp
     from .gallery import gallery_bp
+    from .gpu import gpu_bp
+    from .heads import heads_bp
     from .import_admin import import_admin_bp
     from .ml_admin import ml_admin_bp
     from .platforms import platforms_bp
@@ -58,6 +61,9 @@ def all_blueprints() -> list[Blueprint]:
         allowlist_bp,
         aliases_bp,
         tag_eval_bp,
+        heads_bp,
+        gpu_bp,
+        ccip_bp,
         ml_admin_bp,
         thumbnails_bp,
         sources_bp,

backend/app/api/ccip.py

@@ -0,0 +1,124 @@
+"""CCIP / region observability API (#114) — read-only, analysis-shaped.
+
+So the work can be checked through an API as the agent fills in vectors: overall
+coverage (regions by kind, how many images have figure CCIP vectors, which
+characters have enough reference examples to match on) + a per-image drill-down
+(its regions + the CCIP character matches it would get). Mirrors the heads
+metrics endpoint; no GPU, just reads what's stored.
+"""
+
+from quart import Blueprint, jsonify
+from sqlalchemy import distinct, func, select
+
+from ..extensions import get_session
+from ..models import ImageRegion, Tag, TagKind
+from ..models.tag import image_tag
+from ..services.ml.ccip import match_image
+
+ccip_bp = Blueprint("ccip", __name__, url_prefix="/api/ccip")
+
+_FIGURE_KINDS = ("face", "figure")
+
+
+@ccip_bp.route("/overview", methods=["GET"])
+async def overview():
+    async with get_session() as session:
+        by_kind = dict(
+            (
+                await session.execute(
+                    select(ImageRegion.kind, func.count()).group_by(ImageRegion.kind)
+                )
+            ).all()
+        )
+        images_with_figure_ccip = (
+            await session.execute(
+                select(func.count(distinct(ImageRegion.image_record_id)))
+                .where(ImageRegion.kind.in_(_FIGURE_KINDS))
+                .where(ImageRegion.ccip_embedding.is_not(None))
+            )
+        ).scalar_one()
+        # Concept-crop (SigLIP bag) coverage — how far the back-catalogue embed
+        # has progressed, so the max-over-bag scorer's reach is checkable.
+        images_with_concept_siglip = (
+            await session.execute(
+                select(func.count(distinct(ImageRegion.image_record_id)))
+                .where(ImageRegion.kind == "concept")
+                .where(ImageRegion.siglip_embedding.is_not(None))
+            )
+        ).scalar_one()
+        # Per-character reference counts (no vectors loaded) — which characters
+        # have enough examples to match on.
+        ref_rows = (
+            await session.execute(
+                select(image_tag.c.tag_id, Tag.name, func.count())
+                .select_from(ImageRegion)
+                .join(
+                    image_tag,
+                    image_tag.c.image_record_id == ImageRegion.image_record_id,
+                )
+                .join(Tag, Tag.id == image_tag.c.tag_id)
+                .where(Tag.kind == TagKind.character)
+                .where(ImageRegion.kind.in_(_FIGURE_KINDS))
+                .where(ImageRegion.ccip_embedding.is_not(None))
+                .group_by(image_tag.c.tag_id, Tag.name)
+                .order_by(func.count().desc())
+            )
+        ).all()
+        versions = [
+            v for (v,) in (
+                await session.execute(
+                    select(distinct(ImageRegion.embedding_version))
+                )
+            ).all() if v
+        ]
+        auto_applied = (
+            await session.execute(
+                select(func.count()).select_from(image_tag).where(
+                    image_tag.c.source == "ccip_auto"
+                )
+            )
+        ).scalar_one()
+    return jsonify({
+        "regions_by_kind": by_kind,
+        "images_with_figure_ccip": images_with_figure_ccip,
+        "images_with_concept_siglip": images_with_concept_siglip,
+        "characters_with_references": len(ref_rows),
+        "character_references": [
+            {"tag_id": t, "name": n, "n_refs": c} for (t, n, c) in ref_rows
+        ],
+        "embedding_versions": versions,
+        "auto_applied": auto_applied,
+    })
+
+
+@ccip_bp.route("/images/<int:image_id>", methods=["GET"])
+async def image_detail(image_id: int):
+    """An image's stored regions + the CCIP character matches it would get —
+    for spot-checking the agent's output + the matcher."""
+    async with get_session() as session:
+        regions = (
+            await session.execute(
+                select(ImageRegion)
+                .where(ImageRegion.image_record_id == image_id)
+                .order_by(ImageRegion.id)
+            )
+        ).scalars().all()
+        matches = await match_image(session, image_id)
+    return jsonify({
+        "image_id": image_id,
+        "regions": [
+            {
+                "id": r.id,
+                "kind": r.kind,
+                "bbox": [r.rx, r.ry, r.rw, r.rh],
+                "frame_time": r.frame_time,
+                "score": r.score,
+                "detector_version": r.detector_version,
+                "embedding_version": r.embedding_version,
+                "has_ccip": r.ccip_embedding is not None,
+                "has_siglip": r.siglip_embedding is not None,
+            }
+            for r in regions
+        ],
+        "ccip_matches": matches,
+    })

backend/app/api/gpu.py

@@ -0,0 +1,220 @@
+"""GPU-job API (#114): the HTTP surface the desktop agent pulls work from.
+
+The agent stays HTTP-only — it leases jobs, fetches image pixels via the normal
+FC image URLs, and submits embeddings/regions back, all over this API. Redis and
+Postgres are never exposed. The agent endpoints are gated by a bearer token
+(Authorization: Bearer <token>) stored in AppSetting; the admin endpoints
+(token / backfill / status) ride the browser session like the rest of FC's
+homelab admin.
+"""
+
+import secrets
+
+from quart import Blueprint, jsonify, request
+from sqlalchemy import func, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+from ..extensions import get_session
+from ..models import AppSetting, GpuJob, ImageRecord, MLSettings
+from ..services.gallery_service import image_url
+from ..services.ml.embedder import MODEL_NAME as EMBED_MODEL_NAME
+from ..services.ml.gpu_jobs import GpuJobService
+from ..services.ml.regions import RegionService
+
+gpu_bp = Blueprint("gpu", __name__, url_prefix="/api/gpu")
+
+_TOKEN_KEY = "gpu_agent_token"
+
+
+def _bearer() -> str | None:
+    h = request.headers.get("Authorization", "")
+    return h[7:].strip() if h.startswith("Bearer ") else None
+
+
+async def _agent_authed(session) -> bool:
+    supplied = _bearer()
+    if not supplied:
+        return False
+    stored = (
+        await session.execute(
+            select(AppSetting.value).where(AppSetting.key == _TOKEN_KEY)
+        )
+    ).scalar_one_or_none()
+    return stored is not None and secrets.compare_digest(supplied, stored)
+
+
+# --- Admin (browser): token + backfill + status -------------------------
+
+@gpu_bp.route("/token", methods=["GET"])
+async def get_token():
+    async with get_session() as session:
+        tok = (
+            await session.execute(
+                select(AppSetting.value).where(AppSetting.key == _TOKEN_KEY)
+            )
+        ).scalar_one_or_none()
+    return jsonify({"token": tok, "configured": tok is not None})
+
+
+@gpu_bp.route("/token/rotate", methods=["POST"])
+async def rotate_token():
+    token = secrets.token_urlsafe(32)
+    async with get_session() as session:
+        await session.execute(
+            pg_insert(AppSetting)
+            .values(key=_TOKEN_KEY, value=token)
+            .on_conflict_do_update(index_elements=["key"], set_={"value": token})
+        )
+        await session.commit()
+    return jsonify({"token": token})
+
+
+@gpu_bp.route("/status", methods=["GET"])
+async def status():
+    async with get_session() as session:
+        rows = (
+            await session.execute(
+                select(GpuJob.status, func.count()).group_by(GpuJob.status)
+            )
+        ).all()
+    counts = dict(rows)
+    return jsonify({
+        "pending": counts.get("pending", 0),
+        "leased": counts.get("leased", 0),
+        "done": counts.get("done", 0),
+        "error": counts.get("error", 0),
+    })
+
+
+@gpu_bp.route("/backfill", methods=["POST"])
+async def backfill():
+    """Enqueue a job for every image that doesn't already have one for `task`."""
+    body = await request.get_json(silent=True) or {}
+    task = str(body.get("task") or "ccip")
+    from ..tasks.ml import enqueue_gpu_backfill
+
+    r = enqueue_gpu_backfill.delay(task)
+    return jsonify({"celery_task_id": r.id, "task": task}), 202
+
+
+# --- Agent (bearer token): lease / submit / heartbeat / fail ------------
+
+@gpu_bp.route("/jobs/lease", methods=["POST"])
+async def lease():
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    try:
+        batch = min(max(int(body.get("batch_size", 8)), 1), 64)
+    except (TypeError, ValueError):
+        batch = 8
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        jobs = await GpuJobService(session).lease(agent_id, batch_size=batch)
+        ml = (
+            await session.execute(select(MLSettings).where(MLSettings.id == 1))
+        ).scalar_one()
+        # image rows for url/mime in one shot
+        ids = [j.image_record_id for j in jobs]
+        imgs = {
+            i.id: i for i in (
+                await session.execute(
+                    select(ImageRecord).where(ImageRecord.id.in_(ids))
+                )
+            ).scalars()
+        } if ids else {}
+        await session.commit()
+        out = []
+        for j in jobs:
+            img = imgs.get(j.image_record_id)
+            if img is None:
+                continue
+            out.append({
+                "job_id": j.id,
+                "image_id": j.image_record_id,
+                "task": j.task,
+                "mime": img.mime,
+                "image_url": image_url(img.path),
+                # For video/animated: the agent samples at this cadence.
+                "frame_interval_seconds": ml.video_frame_interval_seconds,
+                "max_frames": ml.video_max_frames,
+                # The embedding model the agent must use for concept crops, so
+                # its region vectors land in the SAME space the heads trained in.
+                # Server-announced → the agent stays model-agnostic; a swap is a
+                # server setting + a re-embed migration, never an agent change.
+                "embed_model_name": EMBED_MODEL_NAME,
+                "embed_version": ml.embedder_model_version,
+            })
+    return jsonify({"jobs": out})
+
+
+@gpu_bp.route("/jobs/heartbeat", methods=["POST"])
+async def heartbeat():
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    job_ids = [int(x) for x in (body.get("job_ids") or [])]
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        n = await GpuJobService(session).heartbeat(agent_id, job_ids)
+        await session.commit()
+    return jsonify({"extended": n})
+
+
+@gpu_bp.route("/jobs/submit", methods=["POST"])
+async def submit():
+    """Store a job's regions + close it. regions: [{kind, bbox:[x,y,w,h],
+    frame_time?, score?, *_version?, ccip_embedding?, siglip_embedding?}].
+    replace_kinds defaults to the kinds present in the submitted regions."""
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    job_id = body.get("job_id")
+    regions = body.get("regions") or []
+    if job_id is None:
+        return jsonify({"error": "job_id required"}), 400
+    kinds = body.get("replace_kinds") or sorted({r["kind"] for r in regions})
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        job = await session.get(GpuJob, int(job_id))
+        if job is None or job.status != "leased" or job.lease_token != agent_id:
+            return jsonify({"error": "lease_invalid"}), 409
+        if kinds:
+            await RegionService(session).replace_regions(
+                job.image_record_id, kinds, regions
+            )
+        await GpuJobService(session).complete(agent_id, int(job_id))
+        await session.commit()
+    return jsonify({"ok": True, "stored": len(regions)})
+
+
+@gpu_bp.route("/jobs/fail", methods=["POST"])
+async def fail():
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    job_id = body.get("job_id")
+    if job_id is None:
+        return jsonify({"error": "job_id required"}), 400
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        ok = await GpuJobService(session).fail(
+            agent_id, int(job_id), str(body.get("error") or "")
+        )
+        await session.commit()
+    return jsonify({"ok": ok})
+
+
+@gpu_bp.route("/jobs/release", methods=["POST"])
+async def release():
+    """Graceful stop: the agent hands its still-leased jobs back to pending so
+    they're picked up immediately instead of waiting out the lease."""
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    job_ids = [int(x) for x in (body.get("job_ids") or [])]
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        n = await GpuJobService(session).release(agent_id, job_ids)
+        await session.commit()
+    return jsonify({"released": n})

backend/app/api/heads.py

@@ -0,0 +1,285 @@
+"""Heads API (#114): train + inspect the per-concept heads that power
+suggestions (replacing Camie + centroid).
+
+POST /api/heads/train   — (re)train all eligible heads (one run at a time).
+GET  /api/heads         — status: head count, last-trained, running run, the
+                          per-concept head table (strength + auto-apply ready),
+                          and recent training runs. The card rehydrates from
+                          here so status survives navigation.
+"""
+
+from quart import Blueprint, jsonify, request
+from sqlalchemy import desc, func, select
+
+from ..extensions import get_session
+from ..models import (
+    HeadAutoApplyRun,
+    HeadMetric,
+    HeadMetricsSnapshot,
+    HeadTrainingRun,
+    Tag,
+    TagHead,
+)
+from ..models.tag import image_tag
+from ..services.ml.heads import (
+    HeadAutoApplyAlreadyRunning,
+    HeadAutoApplyDisabled,
+    HeadTrainingAlreadyRunning,
+    start_head_auto_apply_run,
+    start_head_training_run,
+)
+
+heads_bp = Blueprint("heads", __name__, url_prefix="/api/heads")
+
+
+def _serialize_run(run: HeadTrainingRun) -> dict:
+    return {
+        "id": run.id,
+        "params": run.params,
+        "status": run.status,
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "finished_at": run.finished_at.isoformat() if run.finished_at else None,
+        "n_trained": run.n_trained,
+        "n_skipped": run.n_skipped,
+        "error": run.error,
+    }
+
+
+@heads_bp.route("/train", methods=["POST"])
+async def train():
+    body = await request.get_json(silent=True) or {}
+    params = body.get("params") or body or {}
+    async with get_session() as session:
+        try:
+            run_id = await session.run_sync(
+                lambda s: start_head_training_run(s, params)
+            )
+        except HeadTrainingAlreadyRunning as running:
+            return jsonify({
+                "error": "training_already_running",
+                "running_id": int(running.args[0]),
+            }), 409
+        await session.commit()
+    return jsonify({"run_id": run_id, "status": "running"}), 202
+
+
+@heads_bp.route("", methods=["GET"])
+async def status():
+    async with get_session() as session:
+        count, last_trained = (
+            await session.execute(
+                select(func.count(), func.max(TagHead.trained_at))
+            )
+        ).one()
+        graduated = (
+            await session.execute(
+                select(func.count()).where(
+                    TagHead.auto_apply_threshold.is_not(None)
+                )
+            )
+        ).scalar_one()
+        running = (
+            await session.execute(
+                select(HeadTrainingRun.id)
+                .where(HeadTrainingRun.status == "running")
+                .order_by(HeadTrainingRun.id.desc())
+                .limit(1)
+            )
+        ).scalar_one_or_none()
+        runs = (
+            await session.execute(
+                select(HeadTrainingRun)
+                .order_by(HeadTrainingRun.id.desc())
+                .limit(10)
+            )
+        ).scalars().all()
+        # The per-concept table: strongest first, capped for the admin card.
+        head_rows = (
+            await session.execute(
+                select(
+                    TagHead.tag_id, Tag.name, Tag.kind,
+                    TagHead.n_pos, TagHead.n_neg, TagHead.ap,
+                    TagHead.precision_cv, TagHead.recall,
+                    TagHead.auto_apply_threshold, TagHead.trained_at,
+                )
+                .join(Tag, Tag.id == TagHead.tag_id)
+                .order_by(desc(TagHead.ap))
+                .limit(500)
+            )
+        ).all()
+        heads = [
+            {
+                "tag_id": r.tag_id,
+                "name": r.name,
+                "category": r.kind.value if hasattr(r.kind, "value") else str(r.kind),
+                "n_pos": r.n_pos,
+                "n_neg": r.n_neg,
+                "ap": r.ap,
+                "precision": r.precision_cv,
+                "recall": r.recall,
+                "auto_apply": r.auto_apply_threshold is not None,
+                "trained_at": r.trained_at.isoformat() if r.trained_at else None,
+            }
+            for r in head_rows
+        ]
+    return jsonify({
+        "head_count": count,
+        "graduated_count": graduated,
+        "last_trained_at": last_trained.isoformat() if last_trained else None,
+        "running_id": running,
+        "runs": [_serialize_run(r) for r in runs],
+        "heads": heads,
+    })
+
+
+def _serialize_apply_run(run: HeadAutoApplyRun) -> dict:
+    return {
+        "id": run.id,
+        "dry_run": run.dry_run,
+        "status": run.status,
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "finished_at": run.finished_at.isoformat() if run.finished_at else None,
+        "n_applied": run.n_applied,
+        "report": run.report,
+        "error": run.error,
+    }
+
+
+@heads_bp.route("/auto-apply", methods=["POST"])
+async def auto_apply():
+    """Trigger an earned-auto-apply sweep. {dry_run:true} previews (writes
+    nothing); a real sweep needs head_auto_apply_enabled on."""
+    body = await request.get_json(silent=True) or {}
+    params = {"dry_run": bool(body.get("dry_run", False))}
+    async with get_session() as session:
+        try:
+            run_id = await session.run_sync(
+                lambda s: start_head_auto_apply_run(s, params)
+            )
+        except HeadAutoApplyAlreadyRunning as running:
+            return jsonify({
+                "error": "auto_apply_already_running",
+                "running_id": int(running.args[0]),
+            }), 409
+        except HeadAutoApplyDisabled:
+            return jsonify({"error": "auto_apply_disabled"}), 400
+        await session.commit()
+    return jsonify({"run_id": run_id, "status": "running"}), 202
+
+
+@heads_bp.route("/auto-apply", methods=["GET"])
+async def auto_apply_status():
+    async with get_session() as session:
+        running = (
+            await session.execute(
+                select(HeadAutoApplyRun.id)
+                .where(HeadAutoApplyRun.status == "running")
+                .order_by(HeadAutoApplyRun.id.desc())
+                .limit(1)
+            )
+        ).scalar_one_or_none()
+        runs = (
+            await session.execute(
+                select(HeadAutoApplyRun)
+                .order_by(HeadAutoApplyRun.id.desc())
+                .limit(10)
+            )
+        ).scalars().all()
+    return jsonify({
+        "running_id": running,
+        "runs": [_serialize_apply_run(r) for r in runs],
+    })
+
+
+@heads_bp.route("/metrics", methods=["GET"])
+async def metrics():
+    """Auto-apply observability: per-concept current counts (volume, misfires,
+    under-fires, realized misfire rate, head quality) + the daily time-series so
+    the operator can tune the precision target + support floor from real data."""
+    async with get_session() as session:
+        head_rows = (
+            await session.execute(
+                select(
+                    TagHead.tag_id, Tag.name, TagHead.ap, TagHead.precision_cv,
+                    TagHead.recall, TagHead.auto_apply_threshold, TagHead.n_pos,
+                ).join(Tag, Tag.id == TagHead.tag_id)
+            )
+        ).all()
+        heads = {r.tag_id: r for r in head_rows}
+        metric_rows = (
+            await session.execute(
+                select(
+                    HeadMetric.tag_id, HeadMetric.n_misfires, HeadMetric.n_underfires
+                )
+            )
+        ).all()
+        mets = {r.tag_id: r for r in metric_rows}
+        applied = dict(
+            (
+                await session.execute(
+                    select(image_tag.c.tag_id, func.count())
+                    .where(image_tag.c.source == "head_auto")
+                    .group_by(image_tag.c.tag_id)
+                )
+            ).all()
+        )
+        names = {r.tag_id: r.name for r in head_rows}
+        # Names for metric-only tags (head pruned but corrections recorded).
+        missing = [t for t in mets if t not in names]
+        if missing:
+            for tid, nm in (
+                await session.execute(
+                    select(Tag.id, Tag.name).where(Tag.id.in_(missing))
+                )
+            ).all():
+                names[tid] = nm
+
+        concepts = []
+        for tid in set(heads) | set(mets):
+            h = heads.get(tid)
+            m = mets.get(tid)
+            n_applied = applied.get(tid, 0)
+            n_mis = m.n_misfires if m else 0
+            denom = n_applied + n_mis
+            concepts.append({
+                "tag_id": tid,
+                "name": names.get(tid, str(tid)),
+                "n_auto_applied": n_applied,
+                "n_misfires": n_mis,
+                "n_underfires": m.n_underfires if m else 0,
+                # Of everything this head ever auto-applied, the fraction you
+                # removed — the misfire rate (null until something fired).
+                "misfire_rate": round(n_mis / denom, 4) if denom else None,
+                "ap": h.ap if h else None,
+                "precision_cv": h.precision_cv if h else None,
+                "recall": h.recall if h else None,
+                "auto_apply": bool(h and h.auto_apply_threshold is not None),
+                "n_pos": h.n_pos if h else None,
+            })
+        concepts.sort(key=lambda c: (c["n_misfires"], c["n_auto_applied"]), reverse=True)
+
+        snaps = (
+            await session.execute(
+                select(HeadMetricsSnapshot)
+                .order_by(HeadMetricsSnapshot.snapshot_at.desc())
+                .limit(1000)
+            )
+        ).scalars().all()
+    return jsonify({
+        "concepts": concepts,
+        "snapshots": [
+            {
+                "tag_id": s.tag_id,
+                "name": s.name,
+                "snapshot_at": s.snapshot_at.isoformat() if s.snapshot_at else None,
+                "n_auto_applied": s.n_auto_applied,
+                "n_misfires": s.n_misfires,
+                "n_underfires": s.n_underfires,
+                "ap": s.ap,
+                "precision_cv": s.precision_cv,
+                "recall": s.recall,
+                "n_pos": s.n_pos,
+            }
+            for s in snaps
+        ],
+    })

backend/app/api/ml_admin.py

@@ -17,6 +17,13 @@ _EDITABLE = (
     "video_frame_interval_seconds",
     "video_max_frames",
     "video_min_tag_frames",
+    "head_min_positives",
+    "head_auto_apply_precision",
+    "head_auto_apply_enabled",
+    "head_auto_apply_min_positives",
+    "ccip_match_threshold",
+    "ccip_auto_apply_enabled",
+    "ccip_auto_apply_threshold",
 )
 
 
@@ -40,6 +47,13 @@ async def get_settings():
             "video_min_tag_frames": s.video_min_tag_frames,
             "tagger_model_version": s.tagger_model_version,
             "embedder_model_version": s.embedder_model_version,
+            "head_min_positives": s.head_min_positives,
+            "head_auto_apply_precision": s.head_auto_apply_precision,
+            "head_auto_apply_enabled": s.head_auto_apply_enabled,
+            "head_auto_apply_min_positives": s.head_auto_apply_min_positives,
+            "ccip_match_threshold": s.ccip_match_threshold,
+            "ccip_auto_apply_enabled": s.ccip_auto_apply_enabled,
+            "ccip_auto_apply_threshold": s.ccip_auto_apply_threshold,
         }
     )
 
@@ -100,6 +114,17 @@ def _validate(p: dict) -> str | None:
         return "video_min_tag_frames must be >= 1"
     if p["video_min_tag_frames"] > p["video_max_frames"]:
         return "video_min_tag_frames cannot exceed video_max_frames"
+    # Head training (#114).
+    if int(p["head_min_positives"]) < 1:
+        return "head_min_positives must be >= 1"
+    if not (0.5 <= float(p["head_auto_apply_precision"]) <= 0.999):
+        return "head_auto_apply_precision must be between 0.5 and 0.999"
+    if int(p["head_auto_apply_min_positives"]) < 1:
+        return "head_auto_apply_min_positives must be >= 1"
+    if not (0.5 <= float(p["ccip_match_threshold"]) <= 0.999):
+        return "ccip_match_threshold must be between 0.5 and 0.999"
+    if not (0.5 <= float(p["ccip_auto_apply_threshold"]) <= 0.999):
+        return "ccip_auto_apply_threshold must be between 0.5 and 0.999"
     return None
 
 

backend/app/api/suggestions.py

@@ -61,6 +61,10 @@ async def get_suggestions(image_id: int):
                         # modal's "Treat as alias"/"Remove alias" affordances.
                         "raw_name": s.raw_name,
                         "via_alias": s.via_alias,
+                        # operator dismissed this tag for this image — surfaced
+                        # (not dropped) so the rail can show it rejected + offer
+                        # one-click un-reject.
+                        "rejected": s.rejected,
                     }
                     for s in items
                 ]
@@ -131,6 +135,21 @@ async def dismiss_suggestion(image_id: int):
     return "", 204
 
 
+@suggestions_bp.route(
+    "/images/<int:image_id>/suggestions/undismiss", methods=["POST"]
+)
+async def undismiss_suggestion(image_id: int):
+    """Reverse a per-image dismissal (reject-recovery). Idempotent — undoing a
+    tag that isn't rejected is a no-op delete."""
+    body = await request.get_json()
+    if not body or "tag_id" not in body:
+        return jsonify({"error": "tag_id required"}), 400
+    async with get_session() as session:
+        await AllowlistService(session).undismiss(image_id, body["tag_id"])
+        await session.commit()
+    return "", 204
+
+
 @suggestions_bp.route("/suggestions/bulk", methods=["POST"])
 async def bulk_suggestions():
     body = await request.get_json()

backend/app/celery_app.py

@@ -109,6 +109,36 @@ def make_celery() -> Celery:
                 "task": "backend.app.tasks.ml.apply_allowlist_tags",
                 "schedule": 86400.0,
             },
+            "train-heads-nightly": {
+                "task": "backend.app.tasks.ml.scheduled_train_heads",
+                "schedule": 86400.0,  # passive cadence; manual retrain stays available
+            },
+            "apply-head-tags-daily": {
+                "task": "backend.app.tasks.ml.scheduled_apply_head_tags",
+                "schedule": 86400.0,  # no-op unless head_auto_apply_enabled
+            },
+            "recover-orphaned-gpu-jobs": {
+                "task": "backend.app.tasks.ml.recover_orphaned_gpu_jobs",
+                "schedule": 60.0,  # quick pickup of work a dead agent orphaned
+            },
+            "enqueue-ccip-backfill-hourly": {
+                "task": "backend.app.tasks.ml.enqueue_gpu_backfill",
+                "schedule": 3600.0,  # auto-feed new images (+ retry errored) so
+                "args": ("ccip",),   # the queue keeps moving without the button
+            },
+            "enqueue-siglip-backfill-daily": {
+                "task": "backend.app.tasks.ml.enqueue_gpu_backfill",
+                "schedule": 86400.0,  # drain the concept-crop back-catalogue +
+                "args": ("siglip",),  # retry failed embeds, no button needed
+            },
+            "ccip-auto-apply-daily": {
+                "task": "backend.app.tasks.ml.scheduled_ccip_auto_apply",
+                "schedule": 86400.0,  # no-op unless ccip_auto_apply_enabled
+            },
+            "snapshot-head-metrics-daily": {
+                "task": "backend.app.tasks.maintenance.snapshot_head_metrics",
+                "schedule": 86400.0,
+            },
             "integrity-verify-weekly": {
                 "task": "backend.app.tasks.maintenance.verify_integrity",
                 "schedule": 604800.0,  # weekly
@@ -160,6 +190,14 @@ def make_celery() -> Celery:
                 "task": "backend.app.tasks.maintenance.recover_stalled_tag_eval_runs",
                 "schedule": 300.0,
             },
+            "recover-stalled-head-training-runs": {
+                "task": "backend.app.tasks.maintenance.recover_stalled_head_training_runs",
+                "schedule": 300.0,
+            },
+            "recover-stalled-head-auto-apply-runs": {
+                "task": "backend.app.tasks.maintenance.recover_stalled_head_auto_apply_runs",
+                "schedule": 300.0,
+            },
             "recover-stalled-import-batches": {
                 "task": "backend.app.tasks.maintenance.recover_stalled_import_batches",
                 "schedule": 300.0,

backend/app/models/__init__.py

@@ -8,9 +8,15 @@ from .base import Base
 from .credential import Credential
 from .download_event import DownloadEvent
 from .external_link import ExternalLink
+from .gpu_job import GpuJob
+from .head_auto_apply_run import HeadAutoApplyRun
+from .head_metric import HeadMetric
+from .head_metrics_snapshot import HeadMetricsSnapshot
+from .head_training_run import HeadTrainingRun
 from .image_prediction import ImagePrediction
 from .image_provenance import ImageProvenance
 from .image_record import ImageRecord
+from .image_region import ImageRegion
 from .import_batch import ImportBatch
 from .import_settings import ImportSettings
 from .import_task import ImportTask
@@ -30,6 +36,7 @@ from .tag import Tag, TagKind, image_tag
 from .tag_alias import TagAlias
 from .tag_allowlist import TagAllowlist
 from .tag_eval_run import TagEvalRun
+from .tag_head import TagHead
 from .tag_positive_confirmation import TagPositiveConfirmation
 from .tag_reference_embedding import TagReferenceEmbedding
 from .tag_suggestion_rejection import TagSuggestionRejection
@@ -55,19 +62,26 @@ __all__ = [
     "ImageRecord",
     "ImagePrediction",
     "ImageProvenance",
+    "ImageRegion",
     "Tag",
     "TagKind",
     "image_tag",
     "DownloadEvent",
     "ExternalLink",
+    "GpuJob",
     "ImportBatch",
     "ImportTask",
     "ImportSettings",
     "LibraryAuditRun",
     "MLSettings",
+    "HeadAutoApplyRun",
+    "HeadMetric",
+    "HeadMetricsSnapshot",
+    "HeadTrainingRun",
     "TagAlias",
     "TagAllowlist",
     "TagEvalRun",
+    "TagHead",
     "TagPositiveConfirmation",
     "TagReferenceEmbedding",
     "TagSuggestionRejection",

backend/app/models/gpu_job.py

@@ -0,0 +1,50 @@
+"""GpuJob — a unit of GPU work the desktop agent pulls over HTTP (#114).
+
+The durable work list that lets the agent stay HTTP-only: the server enqueues a
+job per (image, task) — e.g. detect figures + CCIP-embed — and the agent LEASES a
+batch, computes on its GPU, then SUBMITS results, all over the already-exposed web
+API. Redis/Postgres stay private. A lease has an expiry; the lease query itself
+re-claims expired leases (agent died / stopped mid-batch), so the queue is
+self-healing without a separate sweep. One job is per ITEM; the agent fans a
+VIDEO out into per-frame instances internally (see image_region.frame_time).
+
+State: pending → leased → done | error (a failure under the attempt cap returns to
+pending for another agent).
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class GpuJob(Base):
+    __tablename__ = "gpu_job"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    image_record_id: Mapped[int] = mapped_column(
+        ForeignKey("image_record.id", ondelete="CASCADE"), index=True
+    )
+    # What to compute, e.g. 'ccip' (detect figures + CCIP-embed) or 'siglip_region'.
+    task: Mapped[str] = mapped_column(String(32), nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="pending", index=True
+    )
+    # pending | leased | done | error
+    lease_token: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    leased_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    lease_expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/app/models/head_auto_apply_run.py

@@ -0,0 +1,46 @@
+"""HeadAutoApplyRun — persisted lifecycle of an earned-auto-apply sweep (#114).
+
+A graduated head can apply its tag to images it scores above the head's
+auto-apply threshold, without a human. This row tracks one such sweep (or a
+dry-run PREVIEW of it) so the result survives navigation and the admin card can
+show what fired / what would fire. Mirrors HeadTrainingRun. State machine:
+running → ready / error. The `report` JSONB holds per-concept counts
+(applied / projected / scanned).
+"""
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import Boolean, DateTime, Integer, String, Text, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class HeadAutoApplyRun(Base):
+    __tablename__ = "head_auto_apply_run"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    # dry_run=True is a PREVIEW: scores + counts what WOULD apply, writes nothing
+    # (preview/apply parity, rule 93).
+    dry_run: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    params: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="running", index=True
+    )
+    # running | ready | error
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # Total tags applied across all heads this sweep (0 for a clean dry-run).
+    n_applied: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # Per-concept breakdown: [{tag_id, name, applied, scanned, threshold}, ...].
+    report: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    last_progress_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )

backend/app/models/head_metric.py

@@ -0,0 +1,32 @@
+"""HeadMetric — running correction counters per concept (#114 observability).
+
+Earned auto-apply fires graduated heads; to TUNE it we need to know how often a
+head's auto-applied tag was wrong (the operator removed it = a MISFIRE) and how
+often the operator had to add a tag a head exists for by hand (an UNDER-FIRE,
+the head missed it). image_tag.source is lost when a row is deleted, so these
+are captured as durable cumulative counters at correction time — they survive
+head retrain/prune (keyed by tag, not by the head row). The daily snapshot reads
+them into the time-series.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class HeadMetric(Base):
+    __tablename__ = "head_metric"
+
+    tag_id: Mapped[int] = mapped_column(
+        ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True
+    )
+    # An auto-applied (source='head_auto') tag the operator later REMOVED.
+    n_misfires: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # A tag with a head that the operator added by HAND (the head missed it).
+    n_underfires: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/app/models/head_metrics_snapshot.py

@@ -0,0 +1,38 @@
+"""HeadMetricsSnapshot — a daily per-concept time-series point (#114).
+
+The "amount of change over time" reporting the operator asked for: once a day,
+record each concept's auto-applied VOLUME (current head_auto tags), cumulative
+misfires/under-fires, and the head's measured quality. Plotting these rows over
+time shows whether auto-apply is landing better/worse and whether tagging more is
+sharpening a concept — the signal for tuning the precision target + support floor.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class HeadMetricsSnapshot(Base):
+    __tablename__ = "head_metrics_snapshot"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    tag_id: Mapped[int] = mapped_column(
+        ForeignKey("tag.id", ondelete="CASCADE"), index=True
+    )
+    # Denormalized so a snapshot stays readable even if the tag is later renamed.
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    snapshot_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), index=True
+    )
+    # Current count of source='head_auto' applications still standing.
+    n_auto_applied: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    n_misfires: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    n_underfires: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # The head's measured quality at snapshot time (null if no head exists).
+    ap: Mapped[float | None] = mapped_column(Float, nullable=True)
+    precision_cv: Mapped[float | None] = mapped_column(Float, nullable=True)
+    recall: Mapped[float | None] = mapped_column(Float, nullable=True)
+    n_pos: Mapped[int | None] = mapped_column(Integer, nullable=True)

backend/app/models/head_training_run.py

@@ -0,0 +1,44 @@
+"""HeadTrainingRun — persisted lifecycle of a head-training batch (#114).
+
+Mirrors TagEvalRun so the run SURVIVES navigation and the admin card can show
+live + historical status instead of holding it in transient frontend state.
+Training is idempotent (it upserts tag_head rows), so a SIGKILL'd run is harmless
+— a maintenance recovery sweep flips a stalled `running` row to `error`, and the
+next run re-trains. State machine: running → ready / error.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import DateTime, Integer, String, Text, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class HeadTrainingRun(Base):
+    __tablename__ = "head_training_run"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    # Training parameters: {min_positives, neg_ratio, precision_target, ...}.
+    params: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="running", index=True
+    )
+    # running | ready | error
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # How many concepts got a (re)trained head vs were skipped (too few labels).
+    n_trained: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    n_skipped: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Last time the task made progress — the recovery sweep tells a live run from
+    # a SIGKILL'd one by this (mirrors TagEvalRun).
+    last_progress_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )

backend/app/models/image_region.py

@@ -0,0 +1,62 @@
+"""ImageRegion — a detected/proposed sub-region of an image + its crop embedding.
+
+The storage backbone of the crop pipeline (#114). A region is a normalized bbox
+plus the embedding of its crop:
+- kind='face' / 'figure' → embedded by CCIP for cross-artist character identity.
+- kind='concept' → embedded by SigLIP, a localized instance for a concept head's
+  bag-of-embeddings (a concept is "present if ANY instance matches").
+One row carries the embedding appropriate to its kind (the other is null). The
+bbox doubles as grounded-tag provenance (hover a tag → highlight its region; a
+wrong box is a precise negative). The GPU agent writes these via the job API;
+the few-shot character matcher + bag scorer read them — both server-side, no GPU.
+"""
+
+from datetime import datetime
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+CCIP_DIM = 768       # deepghs/imgutils CCIP character embedding
+SIGLIP_DIM = 1152    # matches image_record.siglip_embedding
+
+
+class ImageRegion(Base):
+    __tablename__ = "image_region"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    image_record_id: Mapped[int] = mapped_column(
+        ForeignKey("image_record.id", ondelete="CASCADE"), index=True
+    )
+    # 'frame' (a whole video frame → SigLIP bag) | 'face' | 'figure' (→ CCIP
+    # character id) | 'concept' (→ SigLIP head bag).
+    kind: Mapped[str] = mapped_column(String(16), nullable=False)
+    # For video/animated media: the source frame's timestamp in SECONDS. NULL for
+    # static images. Lets a video be a BAG of per-frame instances (fixes the
+    # mean-embedding muddle) + grounds a tag to "appears at 0:42".
+    frame_time: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # Normalized bbox in [0,1]: top-left (rx, ry) + size (rw, rh). Named rx/ry/…
+    # rather than x/y/by to dodge SQL keyword ambiguity ('by').
+    rx: Mapped[float] = mapped_column(Float, nullable=False)
+    ry: Mapped[float] = mapped_column(Float, nullable=False)
+    rw: Mapped[float] = mapped_column(Float, nullable=False)
+    rh: Mapped[float] = mapped_column(Float, nullable=False)
+    # Proposer/detector confidence (null for deterministic proposers).
+    score: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # Version stamps so a re-detect / re-crop / re-embed can be gated (compute
+    # once; only redo when the producing model version changes).
+    detector_version: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    crop_version: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    embedding_version: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # Exactly one is set, per kind.
+    ccip_embedding: Mapped[list[float] | None] = mapped_column(
+        Vector(CCIP_DIM), nullable=True
+    )
+    siglip_embedding: Mapped[list[float] | None] = mapped_column(
+        Vector(SIGLIP_DIM), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/app/models/ml_settings.py

@@ -2,7 +2,15 @@
 
 from datetime import datetime
 
-from sqlalchemy import CheckConstraint, DateTime, Float, Integer, String, func
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    Float,
+    Integer,
+    String,
+    func,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from .base import Base
@@ -55,6 +63,44 @@ class MLSettings(Base):
     video_min_tag_frames: Mapped[int] = mapped_column(
         Integer, nullable=False, default=3
     )
+    # Tagging-v2 head training (#114). The head is the suggestion source that
+    # LEARNS from the operator's tags (replacing Camie + centroid). A concept
+    # needs >= head_min_positives labelled images before a head is trained;
+    # head_auto_apply_precision is the precision bar a head must clear (at some
+    # operating point) to "graduate" into earned auto-apply. Operator-tunable.
+    head_min_positives: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=8
+    )
+    head_auto_apply_precision: Mapped[float] = mapped_column(
+        Float, nullable=False, default=0.97
+    )
+    # Earned auto-apply (#114). A graduated head fires (tags images without a
+    # human) when this master switch is on AND the head has at least
+    # head_auto_apply_min_positives clean labels — so a precise-looking but
+    # under-supported low-N head can't spray tags across the library. ON by
+    # default (operator-asked 2026-06-29: opt-OUT, not opt-in); the support +
+    # measured-precision gates keep it safe, and every auto-tag is reversible.
+    head_auto_apply_enabled: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True
+    )
+    head_auto_apply_min_positives: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=30
+    )
+    # CCIP character-match cosine cut (#114). 0.85 default — the v1 flat 0.75
+    # over-fired (high-reference characters matched a scatter of images); 0.85
+    # keeps the confident single-character matches. Tunable from the agent card.
+    ccip_match_threshold: Mapped[float] = mapped_column(
+        Float, nullable=False, default=0.85
+    )
+    # CCIP auto-apply (#114). Confident matches (>= ccip_auto_apply_threshold,
+    # above the suggest cut) auto-tag on a daily sweep. ON by default (opt-out);
+    # single-character references + the high bar keep it safe, every tag reversible.
+    ccip_auto_apply_enabled: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True
+    )
+    ccip_auto_apply_threshold: Mapped[float] = mapped_column(
+        Float, nullable=False, default=0.92
+    )
     tagger_model_version: Mapped[str] = mapped_column(
         String(128), nullable=False, default="camie-tagger-v2"
     )

backend/app/models/tag_head.py

@@ -0,0 +1,77 @@
+"""TagHead — a small per-concept classifier trained on the operator's tags.
+
+Milestone #114, tagging-v2: the production form of the head the eval (#1130)
+proved. One row per concept (general or character) that has enough labelled
+positives. The head is a logistic-regression boundary over the FROZEN SigLIP
+embedding (L2-normalized), trained on the operator's positives + negatives
+(rejections + sampled unlabeled). It REPLACES the Camie prediction + per-tag
+centroid as the suggestion source — and unlike them it LEARNS: every accept /
+reject re-trains it sharper.
+
+Scoring (suggestion path, API worker, NO numpy): p = sigmoid(weights · x̂ + bias)
+where x̂ is the L2-normalized image embedding. Surface as a suggestion when
+p >= suggest_threshold; auto-apply only once auto_apply_threshold is set (the
+head "graduated" — a precision-targeted operating point was achievable). The
+thresholds come from CROSS-VALIDATED out-of-fold scores so they're honest, not
+in-sample-optimistic; the deployable weights are fit on all data.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import (
+    DateTime,
+    Float,
+    ForeignKey,
+    Integer,
+    String,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+# Matches image_record.siglip_embedding's dimensionality — the head operates in
+# the same space. A model-version change re-embeds AND retrains (embedding_version
+# guards staleness).
+HEAD_DIM = 1152
+
+
+class TagHead(Base):
+    __tablename__ = "tag_head"
+
+    # One head per concept tag; cascade so deleting a tag retires its head.
+    tag_id: Mapped[int] = mapped_column(
+        ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True
+    )
+    # The embedding the head was trained against (image_record's
+    # embedder_model_version). A mismatch with the current embedder means the
+    # head is stale and must be retrained, not scored.
+    embedding_version: Mapped[str] = mapped_column(String(128), nullable=False)
+    # Logistic-regression coefficients over the L2-normalized embedding, stored
+    # as a pgvector for compactness + a future in-DB dot-product path. NOT a
+    # similarity target, just a serialized weight vector.
+    weights: Mapped[list[float]] = mapped_column(Vector(HEAD_DIM), nullable=False)
+    bias: Mapped[float] = mapped_column(Float, nullable=False)
+    # Probability cutoff for SURFACING as a suggestion (F1-best on CV scores).
+    suggest_threshold: Mapped[float] = mapped_column(Float, nullable=False)
+    # Probability cutoff for EARNED auto-apply: the operating point that holds
+    # precision >= the configured target while maximizing recall. NULL = the head
+    # hasn't graduated (can't auto-apply without a human yet).
+    auto_apply_threshold: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # Training-set sizes + cross-validated quality, surfaced in the admin card so
+    # the operator can see which concepts are strong / need more tags.
+    n_pos: Mapped[int] = mapped_column(Integer, nullable=False)
+    n_neg: Mapped[int] = mapped_column(Integer, nullable=False)
+    ap: Mapped[float] = mapped_column(Float, nullable=False)
+    # 'precision' is a SQL reserved word → store as precision_cv (the
+    # cross-validated precision at the suggest operating point).
+    precision_cv: Mapped[float] = mapped_column(Float, nullable=False)
+    recall: Mapped[float] = mapped_column(Float, nullable=False)
+    trained_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    # Extra detail (auto-apply operating point, F1, etc.) — non-load-bearing.
+    metrics: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)

backend/app/services/ml/allowlist.py

@@ -89,6 +89,12 @@ class AllowlistService:
         )
         await self.session.execute(stmt)
 
+    async def undismiss(self, image_id: int, tag_id: int) -> None:
+        """Undo a per-image dismissal — drop the TagSuggestionRejection so the
+        suggestion reverts to a live (un-rejected) state. Backs the rail's
+        one-click reject-recovery (operator-asked 2026-06-27)."""
+        await self._clear_rejection(image_id, tag_id)
+
     async def reject_applied_tag(self, image_id: int, tag_id: int) -> None:
         """Operator removed an applied tag from an image. Remove the
         image_tag row AND record a rejection so the allowlist won't

backend/app/services/ml/ccip.py

@@ -0,0 +1,180 @@
+"""CCIP few-shot character matcher (#114) — server-side, numpy on stored vectors.
+
+CCIP is a FROZEN identity embedding; we don't train it. Instead the operator's
+tagged characters become reference prototypes: a character tag's references are
+the CCIP vectors of figure/face regions on images carrying that tag. To suggest
+characters for a new image, we compare its figure-region CCIP vectors to every
+character's references (multi-prototype: best match over a character's examples)
+and surface the ones that clear a similarity threshold. No GPU here — the agent
+already produced the vectors; this is cosine matching on what's stored.
+
+v1 uses cosine similarity on the raw CCIP vectors with a tunable threshold; the
+exact CCIP difference metric/threshold gets validated against the model during
+the hands-on eval. numpy is imported lazily (API worker has it via pgvector).
+"""
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...models import ImageRegion, MLSettings, Tag, TagKind
+from ...models.tag import image_tag
+
+# Cosine-similarity floor to call a figure the same character. The live setting
+# (ml_settings.ccip_match_threshold) drives it; this is only the fallback when no
+# threshold is supplied AND no settings row exists.
+DEFAULT_SIM_THRESHOLD = 0.85
+_FIGURE_KINDS = ("face", "figure")
+
+
+async def _settings_threshold(session: AsyncSession) -> float:
+    val = (
+        await session.execute(
+            select(MLSettings.ccip_match_threshold).where(MLSettings.id == 1)
+        )
+    ).scalar_one_or_none()
+    return float(val) if val is not None else DEFAULT_SIM_THRESHOLD
+
+
+def _l2norm(mat, np):
+    n = np.linalg.norm(mat, axis=1, keepdims=True)
+    n[n == 0] = 1.0
+    return mat / n
+
+
+# Single-shot cache of the (expensive) reference load, keyed on a cheap
+# signature that changes exactly when references could: a character tag added/
+# removed (n_char_tags) or a figure embedded (max/ n of ccip regions). Shared by
+# the live matcher (every modal open) and the auto-apply sweep.
+_REF_CACHE: dict = {"sig": None, "refs": None}
+
+
+def _single_character_images():
+    """Subquery of image ids carrying EXACTLY ONE character tag. References come
+    only from these — on a multi-character image the tag is image-level, so every
+    figure would otherwise pollute each character's prototype set (a 2-character
+    image tagged 'Velma' would make Daphne's figure a Velma reference)."""
+    return (
+        select(image_tag.c.image_record_id)
+        .join(Tag, Tag.id == image_tag.c.tag_id)
+        .where(Tag.kind == TagKind.character)
+        .group_by(image_tag.c.image_record_id)
+        .having(func.count() == 1)
+    )
+
+
+async def _ref_signature(session: AsyncSession) -> tuple:
+    n_tags = (
+        await session.execute(
+            select(func.count())
+            .select_from(image_tag)
+            .join(Tag, Tag.id == image_tag.c.tag_id)
+            .where(Tag.kind == TagKind.character)
+        )
+    ).scalar_one()
+    n_regs, max_id = (
+        await session.execute(
+            select(func.count(), func.max(ImageRegion.id)).where(
+                ImageRegion.kind.in_(_FIGURE_KINDS),
+                ImageRegion.ccip_embedding.is_not(None),
+            )
+        )
+    ).one()
+    return (n_tags, n_regs, max_id)
+
+
+async def character_references(session: AsyncSession) -> dict[int, list]:
+    """Per character-tag CCIP reference vectors: figure/face-region CCIP
+    embeddings on UNAMBIGUOUS (single-character) images carrying that tag.
+    Multi-prototype — several vectors per character. Cached on a cheap signature."""
+    sig = await _ref_signature(session)
+    if _REF_CACHE["sig"] == sig and _REF_CACHE["refs"] is not None:
+        return _REF_CACHE["refs"]
+    rows = (
+        await session.execute(
+            select(image_tag.c.tag_id, ImageRegion.ccip_embedding)
+            .select_from(ImageRegion)
+            .join(
+                image_tag,
+                image_tag.c.image_record_id == ImageRegion.image_record_id,
+            )
+            .join(Tag, Tag.id == image_tag.c.tag_id)
+            .where(Tag.kind == TagKind.character)
+            .where(ImageRegion.kind.in_(_FIGURE_KINDS))
+            .where(ImageRegion.ccip_embedding.is_not(None))
+            .where(ImageRegion.image_record_id.in_(_single_character_images()))
+        )
+    ).all()
+    refs: dict[int, list] = {}
+    for tag_id, vec in rows:
+        refs.setdefault(tag_id, []).append(vec)
+    _REF_CACHE.update(sig=sig, refs=refs)
+    return refs
+
+
+async def _tag_names(session: AsyncSession, tag_ids: list[int]) -> dict[int, str]:
+    if not tag_ids:
+        return {}
+    return dict(
+        (
+            await session.execute(
+                select(Tag.id, Tag.name).where(Tag.id.in_(tag_ids))
+            )
+        ).all()
+    )
+
+
+async def match_image(
+    session: AsyncSession, image_id: int, threshold: float | None = None
+) -> list[dict]:
+    """Character suggestions for one image from its figure-region CCIP vectors:
+    [{tag_id, name, category:'character', score, source:'ccip'}], ranked.
+    Already-applied character tags are excluded. Empty if the image has no figure
+    CCIP vectors or no character references exist yet. threshold defaults to the
+    live ml_settings.ccip_match_threshold."""
+    import numpy as np
+
+    if threshold is None:
+        threshold = await _settings_threshold(session)
+
+    qvecs = (
+        await session.execute(
+            select(ImageRegion.ccip_embedding).where(
+                ImageRegion.image_record_id == image_id,
+                ImageRegion.kind.in_(_FIGURE_KINDS),
+                ImageRegion.ccip_embedding.is_not(None),
+            )
+        )
+    ).scalars().all()
+    if not qvecs:
+        return []
+    refs = await character_references(session)
+    if not refs:
+        return []
+    applied = set(
+        (
+            await session.execute(
+                select(image_tag.c.tag_id).where(
+                    image_tag.c.image_record_id == image_id
+                )
+            )
+        ).scalars()
+    )
+    names = await _tag_names(session, [t for t in refs if t not in applied])
+
+    Q = _l2norm(np.vstack([np.asarray(v, dtype=np.float32) for v in qvecs]), np)
+    out = []
+    for tag_id, vecs in refs.items():
+        if tag_id in applied:
+            continue
+        R = _l2norm(np.vstack([np.asarray(v, dtype=np.float32) for v in vecs]), np)
+        best = float((Q @ R.T).max())   # best (query figure, reference) cosine
+        if best >= threshold:
+            out.append({
+                "tag_id": tag_id,
+                "name": names.get(tag_id, str(tag_id)),
+                "category": "character",
+                "score": round(best, 4),
+                "source": "ccip",
+            })
+    out.sort(key=lambda d: d["score"], reverse=True)
+    return out

backend/app/services/ml/crops.py

@@ -0,0 +1,73 @@
+"""Shared crop primitive for the region/crop pipeline (#114).
+
+One model- and transport-agnostic function sits at the trunk of both crop jobs:
+- CCIP characters: a face/figure detector proposes regions → crop → CCIP-embed.
+- SigLIP concepts: head-guided / saliency proposes regions → crop → SigLIP-embed.
+Only the PROPOSER (where to crop) and the EMBEDDER (what to run) differ; the crop
+itself — including the lower-bound size floor below which a region is too small to
+embed reliably — is identical, so it lives here and both jobs call it.
+
+The actual detector + embedders run in the GPU agent; this is pure Pillow so it's
+importable + testable anywhere (and the agent imports it for the crop step).
+"""
+
+from __future__ import annotations
+
+from PIL import Image
+
+# Size floor: a region must be at least this big on its SHORTER edge to be worth
+# embedding — a smaller crop is a blurry upscale carrying little real signal, and
+# unbounded tiny crops would explode the bag. Expressed as BOTH a fraction of the
+# image's short side and an absolute pixel floor; the larger of the two wins.
+MIN_CROP_FRACTION = 0.10
+MIN_CROP_PX = 64
+
+
+def _to_pixels(bbox: tuple[float, float, float, float], w: int, h: int):
+    """Normalized (x, y, w, h) in [0,1] → pixel (x, y, w, h)."""
+    x, y, bw, bh = bbox
+    return x * w, y * h, bw * w, bh * h
+
+
+def crop_region(
+    img: Image.Image,
+    bbox: tuple[float, float, float, float],
+    *,
+    pad: float = 0.0,
+    min_fraction: float = MIN_CROP_FRACTION,
+    min_px: int = MIN_CROP_PX,
+    out_size: int | None = None,
+) -> Image.Image | None:
+    """Crop a NORMALIZED bbox (x, y, w, h in [0,1]) from img.
+
+    - pad: grow the box by this fraction on each side (e.g. 0.15 = +15% context),
+      clamped to the image bounds.
+    - Returns None when the resulting region is below the size floor (too small to
+      embed reliably) — the caller skips embedding it.
+    - out_size: if given, resize the crop to out_size×out_size; otherwise return
+      the raw crop and let the embedder do its own preprocessing.
+    """
+    iw, ih = img.size
+    px, py, pw, ph = _to_pixels(bbox, iw, ih)
+
+    if pad:
+        px -= pw * pad / 2.0
+        py -= ph * pad / 2.0
+        pw *= (1.0 + pad)
+        ph *= (1.0 + pad)
+
+    left = max(0, int(round(px)))
+    top = max(0, int(round(py)))
+    right = min(iw, int(round(px + pw)))
+    bottom = min(ih, int(round(py + ph)))
+    if right <= left or bottom <= top:
+        return None
+
+    floor = max(min_px, int(min_fraction * min(iw, ih)))
+    if min(right - left, bottom - top) < floor:
+        return None
+
+    crop = img.crop((left, top, right, bottom)).convert("RGB")
+    if out_size:
+        crop = crop.resize((out_size, out_size))
+    return crop

backend/app/services/ml/gpu_jobs.py

@@ -0,0 +1,177 @@
+"""GPU-job queue engine (#114): enqueue / lease / heartbeat / complete / fail
+/ release / recover_orphaned.
+
+Backs the HTTP API the desktop agent pulls work from. The lease claims pending
+OR expired-leased jobs with FOR UPDATE SKIP LOCKED, so concurrent agents/workers
+never grab the same job. Orphan recovery is three-layered: a graceful agent stop
+calls release() to hand its in-flight jobs back instantly; a hard crash is caught
+by recover_orphaned() (a 60s beat sweep) which resets expired leases to pending;
+and the lease itself reclaims expired leases as a final backstop. Result-writing
+(regions) is done by the API handler via RegionService; complete() just closes.
+"""
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import and_, or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...models import GpuJob
+
+# Lease window. Kept comfortably above any single job (a capped-frame video embed
+# is tens of seconds) so a live, heartbeating worker is never falsely expired,
+# but short enough that a hard crash recovers fast once the sweep fires.
+DEFAULT_LEASE_TTL = 180     # seconds an agent holds a job before it can be re-leased
+DEFAULT_BATCH = 8
+MAX_ATTEMPTS = 3
+
+
+class GpuJobService:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def enqueue(self, image_id: int, task: str) -> GpuJob | None:
+        """Queue a (image, task) job. Idempotent: returns None if one is already
+        pending/leased for the same pair (no duplicate work)."""
+        dup = (
+            await self.session.execute(
+                select(GpuJob.id).where(
+                    GpuJob.image_record_id == image_id,
+                    GpuJob.task == task,
+                    GpuJob.status.in_(["pending", "leased"]),
+                )
+            )
+        ).first()
+        if dup:
+            return None
+        job = GpuJob(image_record_id=image_id, task=task, status="pending")
+        self.session.add(job)
+        await self.session.flush()
+        return job
+
+    async def lease(
+        self, token: str, batch_size: int = DEFAULT_BATCH, ttl: int = DEFAULT_LEASE_TTL
+    ) -> list[GpuJob]:
+        """Claim up to batch_size pending (or expired-leased) jobs for `token`."""
+        now = datetime.now(UTC)
+        picked = (
+            await self.session.execute(
+                select(GpuJob.id)
+                .where(
+                    or_(
+                        GpuJob.status == "pending",
+                        and_(
+                            GpuJob.status == "leased",
+                            GpuJob.lease_expires_at < now,
+                        ),
+                    )
+                )
+                .order_by(GpuJob.id)
+                .limit(batch_size)
+                .with_for_update(skip_locked=True)
+            )
+        ).scalars().all()
+        if not picked:
+            return []
+        await self.session.execute(
+            update(GpuJob)
+            .where(GpuJob.id.in_(picked))
+            .values(
+                status="leased", lease_token=token, leased_at=now,
+                lease_expires_at=now + timedelta(seconds=ttl),
+                attempts=GpuJob.attempts + 1, updated_at=now,
+            )
+        )
+        # populate_existing: overwrite identity-map copies with the post-UPDATE
+        # values so the returned jobs reflect the new lease/attempts, not stale
+        # pre-lease state.
+        return list(
+            (
+                await self.session.execute(
+                    select(GpuJob)
+                    .where(GpuJob.id.in_(picked))
+                    .order_by(GpuJob.id)
+                    .execution_options(populate_existing=True)
+                )
+            ).scalars()
+        )
+
+    async def heartbeat(
+        self, token: str, job_ids: list[int], ttl: int = DEFAULT_LEASE_TTL
+    ) -> int:
+        """Extend the lease on the agent's in-flight jobs. Returns rows touched."""
+        now = datetime.now(UTC)
+        res = await self.session.execute(
+            update(GpuJob)
+            .where(
+                GpuJob.id.in_(job_ids),
+                GpuJob.lease_token == token,
+                GpuJob.status == "leased",
+            )
+            .values(lease_expires_at=now + timedelta(seconds=ttl), updated_at=now)
+        )
+        return res.rowcount or 0
+
+    async def complete(self, token: str, job_id: int) -> bool:
+        """Close a leased job (after its results were stored). False if the job
+        isn't leased by this token (a stale/expired submit)."""
+        job = await self.session.get(GpuJob, job_id)
+        if job is None or job.status != "leased" or job.lease_token != token:
+            return False
+        job.status = "done"
+        job.lease_token = None
+        job.lease_expires_at = None
+        job.error = None
+        job.updated_at = datetime.now(UTC)
+        return True
+
+    async def fail(self, token: str, job_id: int, error: str) -> bool:
+        """Report a failure: re-queue (pending) until MAX_ATTEMPTS, then 'error'."""
+        job = await self.session.get(GpuJob, job_id)
+        if job is None or job.lease_token != token:
+            return False
+        if job.attempts >= MAX_ATTEMPTS:
+            job.status = "error"
+        else:
+            job.status = "pending"
+            job.lease_token = None
+            job.lease_expires_at = None
+        job.error = (error or "")[:1000]
+        job.updated_at = datetime.now(UTC)
+        return True
+
+    async def release(self, token: str, job_ids: list[int]) -> int:
+        """Hand the agent's still-leased jobs back to pending NOW (graceful stop),
+        so another worker picks them up immediately instead of waiting out the
+        lease. Scoped to the token's own leases. Returns rows released."""
+        if not job_ids:
+            return 0
+        now = datetime.now(UTC)
+        res = await self.session.execute(
+            update(GpuJob)
+            .where(
+                GpuJob.id.in_(job_ids),
+                GpuJob.lease_token == token,
+                GpuJob.status == "leased",
+            )
+            .values(
+                status="pending", lease_token=None, leased_at=None,
+                lease_expires_at=None, updated_at=now,
+            )
+        )
+        return res.rowcount or 0
+
+    async def recover_orphaned(self) -> int:
+        """Reset every expired lease back to pending — catches agents that died
+        mid-job (no graceful release). Run on a short beat so the queue recovers
+        + reads honestly even when no worker is actively leasing. Returns rows
+        recovered."""
+        now = datetime.now(UTC)
+        res = await self.session.execute(
+            update(GpuJob)
+            .where(GpuJob.status == "leased", GpuJob.lease_expires_at < now)
+            .values(
+                status="pending", lease_token=None, leased_at=None,
+                lease_expires_at=None, updated_at=now,
+            )
+        )
+        return res.rowcount or 0

backend/app/services/ml/heads.py

@@ -0,0 +1,490 @@
+"""Production heads: train + score the per-concept classifiers (#114).
+
+The eval (#1130, tag_eval.py) proved the spine; this is its production form.
+- TRAIN (sync, ml worker — needs scikit-learn): for every general/character tag
+  with enough labelled positives, fit a logistic-regression head on the FROZEN
+  SigLIP embeddings (positives + negatives = rejections + sampled unlabeled),
+  derive an honest suggest threshold + earned-auto-apply point from CROSS-
+  VALIDATED scores, and upsert a TagHead row. Reuses tag_eval's proven data
+  loaders + metric helpers so production heads match the eval's measured numbers.
+- SCORE (async, API worker — numpy via pgvector, NO scikit-learn): score one
+  image's embedding against all current heads → the suggestions the rail shows,
+  REPLACING Camie predictions + per-tag centroids.
+
+scikit-learn is imported lazily inside the train path so the API worker can still
+import this module to enqueue training + to score (scoring needs only numpy).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+from ...models import (
+    HeadAutoApplyRun,
+    HeadTrainingRun,
+    ImageRecord,
+    ImageRegion,
+    MLSettings,
+    Tag,
+    TagHead,
+    TagKind,
+    TagSuggestionRejection,
+)
+from ...models.tag import image_tag
+from .tag_eval import (
+    _auto_apply_point,
+    _ids_with_tag,
+    _l2norm,
+    _load_embeddings,
+    _metrics_from_scores,
+    _rejected_ids,
+    _safe_folds,
+    _sample_unlabeled,
+)
+
+log = logging.getLogger(__name__)
+
+DEFAULT_NEG_RATIO = 3
+DEFAULT_CV_FOLDS = 5
+MIN_POSITIVES_FLOOR = 8     # hard floor; settings.head_min_positives can raise it
+_UNLABELED_POOL = 4000
+_EXAMPLES_MIN = 8           # need at least this many embedded +/- to fit a head
+
+# Only these tag kinds get heads (the surfaced suggestion categories).
+_HEAD_KINDS = (TagKind.general, TagKind.character)
+# tag.kind -> the suggestion category the rail groups under.
+_CATEGORY = {TagKind.general: "general", TagKind.character: "character"}
+
+
+class HeadTrainingAlreadyRunning(Exception):
+    """Raised by start_head_training_run when a run is already in flight."""
+
+
+def start_head_training_run(session: Session, params: dict[str, Any]) -> int:
+    """Create a HeadTrainingRun (status='running') + dispatch the ml-queue task.
+    Returns the run id. One training run at a time (light guard)."""
+    existing = session.execute(
+        select(HeadTrainingRun.id).where(HeadTrainingRun.status == "running")
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise HeadTrainingAlreadyRunning(existing)
+    norm = _normalize_params(session, params)
+    run = HeadTrainingRun(
+        params=norm, status="running", last_progress_at=datetime.now(UTC)
+    )
+    session.add(run)
+    session.flush()
+    run_id = run.id
+    from ...tasks.ml import train_heads as _task
+    _task.delay(run_id)
+    return run_id
+
+
+def _settings(session: Session) -> MLSettings:
+    return session.execute(
+        select(MLSettings).where(MLSettings.id == 1)
+    ).scalar_one()
+
+
+def _normalize_params(session: Session, params: dict[str, Any] | None) -> dict[str, Any]:
+    params = params or {}
+    s = _settings(session)
+    try:
+        min_pos = max(MIN_POSITIVES_FLOOR, int(params.get("min_positives", s.head_min_positives)))
+    except (TypeError, ValueError):
+        min_pos = max(MIN_POSITIVES_FLOOR, s.head_min_positives)
+    try:
+        neg_ratio = max(1, int(params.get("neg_ratio", DEFAULT_NEG_RATIO)))
+    except (TypeError, ValueError):
+        neg_ratio = DEFAULT_NEG_RATIO
+    try:
+        cv_folds = max(2, int(params.get("cv_folds", DEFAULT_CV_FOLDS)))
+    except (TypeError, ValueError):
+        cv_folds = DEFAULT_CV_FOLDS
+    try:
+        precision_target = min(max(float(params.get("precision_target", s.head_auto_apply_precision)), 0.5), 0.999)
+    except (TypeError, ValueError):
+        precision_target = s.head_auto_apply_precision
+    return {
+        "min_positives": min_pos,
+        "neg_ratio": neg_ratio,
+        "cv_folds": cv_folds,
+        "precision_target": round(precision_target, 4),
+    }
+
+
+def _embedder_version(session: Session) -> str:
+    return _settings(session).embedder_model_version
+
+
+def _eligible_tag_ids(session: Session, min_pos: int) -> list[int]:
+    """Concept tags (general/character) with >= min_pos labelled images — the
+    set that gets a head. Counts all sources; source-aware filtering (#1133) is
+    a separate, optional refinement."""
+    rows = session.execute(
+        select(Tag.id)
+        .join(image_tag, image_tag.c.tag_id == Tag.id)
+        .where(Tag.kind.in_(_HEAD_KINDS))
+        .group_by(Tag.id)
+        .having(func.count(image_tag.c.image_record_id) >= min_pos)
+    ).all()
+    return [r[0] for r in rows]
+
+
+def train_all_heads(
+    session: Session, params: dict[str, Any], run: HeadTrainingRun | None = None
+) -> dict[str, int]:
+    """(Re)train a head for every eligible concept; prune heads whose tag is no
+    longer eligible. Commits per head so a SIGKILL leaves trained heads durable
+    (training is idempotent). Returns {n_trained, n_skipped}."""
+    import numpy as np
+
+    cfg = _normalize_params(session, params)
+    embedding_version = _embedder_version(session)
+    eligible = _eligible_tag_ids(session, cfg["min_positives"])
+    eligible_set = set(eligible)
+    trained = 0
+    skipped = 0
+    for i, tag_id in enumerate(eligible):
+        try:
+            ok = train_head(session, tag_id, embedding_version, cfg, np)
+        except Exception:
+            log.exception("train_head failed for tag %d", tag_id)
+            ok = False
+        session.commit()
+        trained += int(ok)
+        skipped += int(not ok)
+        if run is not None and i % 10 == 0:
+            run.last_progress_at = datetime.now(UTC)
+            session.commit()
+    # Retire heads whose concept dropped out of the eligible set (lost its
+    # positives, or the tag was re-kinded) so stale heads can't keep suggesting.
+    if eligible_set:
+        session.execute(delete(TagHead).where(TagHead.tag_id.not_in(eligible_set)))
+    else:
+        session.execute(delete(TagHead))
+    session.commit()
+    return {"n_trained": trained, "n_skipped": skipped}
+
+
+def train_head(
+    session: Session, tag_id: int, embedding_version: str, cfg: dict, np
+) -> bool:
+    """Fit + upsert one head. Returns True if a head was written, False if the
+    concept had too few usable examples to train (the row is then removed)."""
+    from sklearn.linear_model import LogisticRegression
+    from sklearn.model_selection import StratifiedKFold, cross_val_predict
+
+    pos_ids = _ids_with_tag(session, tag_id)
+    if len(pos_ids) < cfg["min_positives"]:
+        session.execute(delete(TagHead).where(TagHead.tag_id == tag_id))
+        return False
+
+    pos_set = set(pos_ids)
+    rejected = [i for i in _rejected_ids(session, tag_id) if i not in pos_set]
+    want_neg = max(len(pos_ids) * cfg["neg_ratio"], _EXAMPLES_MIN * 4)
+    sampled = _sample_unlabeled(
+        session, pos_set | set(rejected), min(_UNLABELED_POOL, want_neg)
+    )
+    neg_ids = rejected + [i for i in sampled if i not in pos_set]
+
+    emb = _load_embeddings(session, pos_ids + neg_ids)
+    pos = [emb[i] for i in pos_ids if i in emb]
+    neg = [emb[i] for i in neg_ids if i in emb]
+    if len(pos) < _EXAMPLES_MIN or len(neg) < _EXAMPLES_MIN:
+        session.execute(delete(TagHead).where(TagHead.tag_id == tag_id))
+        return False
+
+    X = np.vstack(pos + neg).astype(np.float32)
+    y = np.array([1] * len(pos) + [0] * len(neg))
+    Xn = _l2norm(X, np)
+
+    clf = LogisticRegression(max_iter=1000, class_weight="balanced")
+    cv = StratifiedKFold(
+        n_splits=_safe_folds(y, cfg["cv_folds"], np), shuffle=True, random_state=0
+    )
+    # Honest thresholds from out-of-fold scores; deployable weights from a final
+    # fit on ALL the data.
+    cv_probs = cross_val_predict(clf, Xn, y, cv=cv, method="predict_proba")[:, 1]
+    metrics = _metrics_from_scores(y, cv_probs, np)
+    auto = _auto_apply_point(y, cv_probs, cfg["precision_target"], np)
+    clf.fit(Xn, y)
+
+    head = session.get(TagHead, tag_id)
+    if head is None:
+        head = TagHead(tag_id=tag_id)
+        session.add(head)
+    head.embedding_version = embedding_version
+    head.weights = clf.coef_[0].astype(np.float32).tolist()
+    head.bias = float(clf.intercept_[0])
+    head.suggest_threshold = float(metrics["threshold"])
+    head.auto_apply_threshold = float(auto["threshold"]) if auto else None
+    head.n_pos = len(pos)
+    head.n_neg = len(neg)
+    head.ap = float(metrics["ap"])
+    head.precision_cv = float(metrics["precision"])
+    head.recall = float(metrics["recall"])
+    head.trained_at = datetime.now(UTC)
+    head.metrics = {"f1": metrics["f1"], "auto_apply": auto}
+    return True
+
+
+# --- Scoring (async, API worker) -----------------------------------------
+# Score one image against every current head to produce the rail's suggestions.
+# A tiny in-process cache holds the stacked weight matrix keyed on (count,
+# max(trained_at)) so a retrain invalidates it without per-request weight loads.
+_HEADS_CACHE: dict[str, Any] = {"key": None, "heads": None}
+
+
+async def _current_heads(session: AsyncSession, embedding_version: str):
+    """Stacked (W, b, thresholds, tag_id/name/category) for heads matching the
+    current embedding, cached until the next retrain."""
+    import numpy as np
+
+    sig = (
+        await session.execute(
+            select(func.count(), func.max(TagHead.trained_at)).where(
+                TagHead.embedding_version == embedding_version
+            )
+        )
+    ).one()
+    key = f"{embedding_version}:{sig[0]}:{sig[1].isoformat() if sig[1] else '-'}"
+    cached = _HEADS_CACHE.get("heads")
+    if cached is not None and _HEADS_CACHE.get("key") == key:
+        return cached
+    rows = (
+        await session.execute(
+            select(
+                TagHead.tag_id, Tag.name, Tag.kind,
+                TagHead.weights, TagHead.bias,
+                TagHead.suggest_threshold, TagHead.auto_apply_threshold,
+            )
+            .join(Tag, Tag.id == TagHead.tag_id)
+            .where(TagHead.embedding_version == embedding_version)
+        )
+    ).all()
+    if not rows:
+        loaded = {"W": None, "rows": []}
+    else:
+        W = np.vstack([np.asarray(r.weights, dtype=np.float32) for r in rows])
+        b = np.asarray([r.bias for r in rows], dtype=np.float32)
+        thr = np.asarray([r.suggest_threshold for r in rows], dtype=np.float32)
+        meta = [
+            {
+                "tag_id": r.tag_id,
+                "name": r.name,
+                "category": _CATEGORY.get(r.kind, "general"),
+                "auto_apply_threshold": r.auto_apply_threshold,
+            }
+            for r in rows
+        ]
+        loaded = {"W": W, "b": b, "thr": thr, "meta": meta}
+    _HEADS_CACHE["key"] = key
+    _HEADS_CACHE["heads"] = loaded
+    return loaded
+
+
+async def score_image(
+    session: AsyncSession, image_id: int, threshold_override: float | None = None,
+) -> list[dict]:
+    """Suggestions for one image from the trained heads: [{tag_id, name,
+    category, score}], ranked. A concept surfaces when its score clears the
+    head's own suggest_threshold — or, when threshold_override is given (the
+    typed-dropdown "show everything" mode), that flat floor instead (0 → every
+    head). Empty if the image has no embedding or no heads exist yet.
+
+    MAX-OVER-BAG: the image is scored as a BAG of embeddings — the whole-image
+    vector PLUS every concept-region crop the agent embedded (same model
+    version) — and each head takes its MAX score across the bag. A small/local
+    concept (glasses, a stomach bulge) that the whole-image vector washes out
+    can still surface from the crop where it dominates. The whole-image vector is
+    always in the bag, so this can never score lower than whole-image alone."""
+    import numpy as np
+
+    img = await session.get(ImageRecord, image_id)
+    if img is None or img.siglip_embedding is None:
+        return []
+    settings = await _settings_async(session)
+    heads = await _current_heads(session, settings.embedder_model_version)
+    if heads["W"] is None:
+        return []
+
+    bag = [np.asarray(img.siglip_embedding, dtype=np.float32)]
+    region_vecs = (
+        await session.execute(
+            select(ImageRegion.siglip_embedding)
+            .where(ImageRegion.image_record_id == image_id)
+            .where(ImageRegion.siglip_embedding.is_not(None))
+            .where(ImageRegion.embedding_version == settings.embedder_model_version)
+        )
+    ).all()
+    for (vec,) in region_vecs:
+        if vec is not None:
+            bag.append(np.asarray(vec, dtype=np.float32))
+
+    X = np.vstack(bag)                                  # (B, D)
+    norms = np.linalg.norm(X, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    Xn = X / norms
+    Z = Xn @ heads["W"].T + heads["b"]                  # (B, H)
+    probs = (1.0 / (1.0 + np.exp(-Z))).max(axis=0)      # (H,) best over the bag
+    out = []
+    for i, p in enumerate(probs):
+        cut = threshold_override if threshold_override is not None else heads["thr"][i]
+        if p >= cut:
+            m = heads["meta"][i]
+            out.append({
+                "tag_id": m["tag_id"],
+                "name": m["name"],
+                "category": m["category"],
+                "score": float(p),
+            })
+    out.sort(key=lambda d: d["score"], reverse=True)
+    return out
+
+
+async def _settings_async(session: AsyncSession) -> MLSettings:
+    return (
+        await session.execute(select(MLSettings).where(MLSettings.id == 1))
+    ).scalar_one()
+
+
+# --- Earned auto-apply (sync, ml worker) ---------------------------------
+# A graduated head can apply its tag to images it scores above the head's
+# auto_apply_threshold, without a human. Gated by a master switch + a support
+# floor so a precise-looking but under-supported head can't spray tags.
+
+_AUTO_APPLY_CHUNK = 5000
+
+
+class HeadAutoApplyAlreadyRunning(Exception):
+    """Raised when an auto-apply sweep is already in flight."""
+
+
+class HeadAutoApplyDisabled(Exception):
+    """Raised when a real (non-dry-run) sweep is requested but the master
+    switch (head_auto_apply_enabled) is off."""
+
+
+def start_head_auto_apply_run(session: Session, params: dict[str, Any]) -> int:
+    """Create a HeadAutoApplyRun + dispatch the ml-queue sweep. dry_run previews
+    (writes nothing); a real sweep needs the master switch on. One run at a time."""
+    dry_run = bool((params or {}).get("dry_run", False))
+    existing = session.execute(
+        select(HeadAutoApplyRun.id).where(HeadAutoApplyRun.status == "running")
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise HeadAutoApplyAlreadyRunning(existing)
+    if not dry_run and not _settings(session).head_auto_apply_enabled:
+        raise HeadAutoApplyDisabled()
+    run = HeadAutoApplyRun(
+        dry_run=dry_run, params={"dry_run": dry_run}, status="running",
+        last_progress_at=datetime.now(UTC),
+    )
+    session.add(run)
+    session.flush()
+    run_id = run.id
+    from ...tasks.ml import apply_head_tags as _task
+    _task.delay(run_id)
+    return run_id
+
+
+def _auto_apply_heads(session: Session, embedding_version: str, min_pos: int):
+    """Eligible heads to fire: graduated (auto_apply_threshold set), enough
+    support, current embedding. Returns the row list (tag_id/name/weights/...)."""
+    return session.execute(
+        select(
+            TagHead.tag_id, Tag.name, TagHead.weights, TagHead.bias,
+            TagHead.auto_apply_threshold,
+        )
+        .join(Tag, Tag.id == TagHead.tag_id)
+        .where(TagHead.embedding_version == embedding_version)
+        .where(TagHead.auto_apply_threshold.is_not(None))
+        .where(TagHead.n_pos >= min_pos)
+    ).all()
+
+
+def auto_apply_sweep(
+    session: Session, run: HeadAutoApplyRun, dry_run: bool
+) -> dict[str, Any]:
+    """Score every embedded image against the eligible heads and apply (or, for
+    dry_run, just count) each head's tag where score >= its auto_apply_threshold
+    and the tag isn't already applied or rejected on that image. Streams
+    embeddings in chunks; commits per chunk on a real run. Returns
+    {n_applied, concepts:[{tag_id,name,applied,scanned,threshold}]}."""
+    import numpy as np
+    from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+    settings = _settings(session)
+    rows = _auto_apply_heads(
+        session, settings.embedder_model_version,
+        settings.head_auto_apply_min_positives,
+    )
+    if not rows:
+        return {"n_applied": 0, "concepts": []}
+
+    W = np.vstack([np.asarray(r.weights, dtype=np.float32) for r in rows])
+    b = np.asarray([r.bias for r in rows], dtype=np.float32)
+    thr = np.asarray([r.auto_apply_threshold for r in rows], dtype=np.float32)
+    tag_ids = [r.tag_id for r in rows]
+    names = [r.name for r in rows]
+
+    # Skip images that already carry, or have rejected, each tag.
+    skip = {tid: set() for tid in tag_ids}
+    for tid in tag_ids:
+        for (iid,) in session.execute(
+            select(image_tag.c.image_record_id).where(image_tag.c.tag_id == tid)
+        ):
+            skip[tid].add(iid)
+        for (iid,) in session.execute(
+            select(TagSuggestionRejection.image_record_id).where(
+                TagSuggestionRejection.tag_id == tid
+            )
+        ):
+            skip[tid].add(iid)
+
+    applied = [0] * len(rows)
+    scanned = 0
+    all_ids = list(session.execute(
+        select(ImageRecord.id).where(ImageRecord.siglip_embedding.is_not(None))
+    ).scalars())
+    for start in range(0, len(all_ids), _AUTO_APPLY_CHUNK):
+        chunk = all_ids[start:start + _AUTO_APPLY_CHUNK]
+        emb = _load_embeddings(session, chunk)
+        cids = [i for i in chunk if i in emb]
+        if not cids:
+            continue
+        Xn = _l2norm(np.vstack([emb[i] for i in cids]).astype(np.float32), np)
+        probs = 1.0 / (1.0 + np.exp(-(Xn @ W.T + b)))   # (N, H)
+        scanned += len(cids)
+        for h in range(len(rows)):
+            tid = tag_ids[h]
+            for idx in np.where(probs[:, h] >= thr[h])[0]:
+                iid = cids[int(idx)]
+                if iid in skip[tid]:
+                    continue
+                skip[tid].add(iid)
+                applied[h] += 1
+                if not dry_run:
+                    session.execute(
+                        pg_insert(image_tag)
+                        .values(image_record_id=iid, tag_id=tid, source="head_auto")
+                        .on_conflict_do_nothing()
+                    )
+        if not dry_run:
+            session.commit()
+        run.last_progress_at = datetime.now(UTC)
+        session.commit()
+
+    concepts = [
+        {"tag_id": tag_ids[h], "name": names[h], "applied": applied[h],
+         "scanned": scanned, "threshold": float(thr[h])}
+        for h in range(len(rows))
+    ]
+    return {"n_applied": sum(applied), "concepts": concepts}

backend/app/services/ml/regions.py

@@ -0,0 +1,59 @@
+"""Region read/write for the crop pipeline (#114).
+
+The GPU agent's results endpoint calls replace_regions() to store a freshly
+detected/embedded set; the character matcher + concept-bag scorer read via
+get_regions(). Replacement is scoped BY KIND so the figure pipeline and the
+concept pipeline don't clobber each other.
+"""
+
+from typing import Any
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...models import ImageRegion
+
+
+class RegionService:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def get_regions(
+        self, image_id: int, kinds: list[str] | None = None
+    ) -> list[ImageRegion]:
+        stmt = select(ImageRegion).where(ImageRegion.image_record_id == image_id)
+        if kinds:
+            stmt = stmt.where(ImageRegion.kind.in_(kinds))
+        return list(
+            (await self.session.execute(stmt.order_by(ImageRegion.id))).scalars()
+        )
+
+    async def replace_regions(
+        self, image_id: int, kinds: list[str], regions: list[dict[str, Any]]
+    ) -> int:
+        """Replace this image's regions OF THE GIVEN KINDS with `regions` (a
+        re-detect/re-propose supersedes the prior set without touching other
+        kinds). Each region dict: {kind, bbox:(x,y,w,h), score?, detector_version?,
+        crop_version?, embedding_version?, ccip_embedding?, siglip_embedding?}.
+        Returns the number inserted."""
+        await self.session.execute(
+            delete(ImageRegion)
+            .where(ImageRegion.image_record_id == image_id)
+            .where(ImageRegion.kind.in_(kinds))
+        )
+        n = 0
+        for r in regions:
+            rx, ry, rw, rh = r["bbox"]
+            self.session.add(ImageRegion(
+                image_record_id=image_id, kind=r["kind"],
+                frame_time=r.get("frame_time"),
+                rx=rx, ry=ry, rw=rw, rh=rh,
+                score=r.get("score"),
+                detector_version=r.get("detector_version"),
+                crop_version=r.get("crop_version"),
+                embedding_version=r.get("embedding_version"),
+                ccip_embedding=r.get("ccip_embedding"),
+                siglip_embedding=r.get("siglip_embedding"),
+            ))
+            n += 1
+        return n

backend/app/services/ml/suggestions.py

@@ -1,24 +1,23 @@
-"""The suggestion read-path: raw predictions + centroids -> alias-resolved,
-threshold-filtered, category-grouped, ranked suggestions for one image.
+"""The suggestion read-path: trained HEADS score one image's frozen embedding
+into alias-resolved, category-grouped, ranked suggestions.
+
+Tagging-v2 (#114): suggestions now come from the per-concept heads that LEARN
+from the operator's tags (services/ml/heads.py) — the Camie prediction source
+and the per-tag SigLIP centroid have been REMOVED. A head exists only for an
+existing concept tag, so every suggestion is a canonical tag (no raw model key,
+no alias remap, no creates-new). Rejected tags stay in the list FLAGGED (not
+dropped) so the rail can show + reverse a dismissal.
 """
 
 from dataclasses import dataclass, field
 
-from sqlalchemy import func, select
+from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ...models import (
-    ImagePrediction,
-    ImageRecord,
-    MLSettings,
-    Tag,
-    TagSuggestionRejection,
-)
+from ...models import ImageRecord, TagSuggestionRejection
 from ...models.tag import image_tag
-from .aliases import AliasService
-from .centroids import CentroidService
-from .tag_name import normalize as normalize_tag_name
-from .tagger import SURFACED_CATEGORIES
+from .ccip import match_image as ccip_match_image
+from .heads import score_image
 
 
 @dataclass(frozen=True)
@@ -29,7 +28,7 @@ class Suggestion:
     display_name: str
     category: str
     score: float
-    source: str  # 'tagger' | 'centroid' | 'both'
+    source: str  # 'head' | 'ccip' | 'both' (Camie tagger/centroid removed in v2)
     creates_new_tag: bool
     # raw_name = the booru model vocab key behind this suggestion. It's the key
     # an alias MUST be stored under (resolution looks up the raw key), so the
@@ -39,6 +38,11 @@ class Suggestion:
     # via_alias = this suggestion was surfaced because an operator alias remapped
     # the raw prediction to this canonical tag. Lets the UI mark it + offer undo.
     via_alias: bool = False
+    # rejected = the operator dismissed this tag for this image (a stored
+    # TagSuggestionRejection). It stays in the list — flagged, not dropped — so
+    # the rejection is VISIBLE and REVERSIBLE in the rail (misclick recovery,
+    # operator-asked 2026-06-27) instead of silently vanishing or re-suggesting.
+    rejected: bool = False
 
 
 @dataclass
@@ -49,67 +53,24 @@ class SuggestionList:
 class SuggestionService:
     def __init__(self, session: AsyncSession):
         self.session = session
-        self.aliases = AliasService(session)
-        self.centroids = CentroidService(session)
-
-    async def _settings(self) -> MLSettings:
-        return (
-            await self.session.execute(select(MLSettings).where(MLSettings.id == 1))
-        ).scalar_one()
-
-    async def _load_predictions(self, image_id: int) -> dict:
-        """Predictions for one image from the normalized image_prediction
-        table (#768), in the {raw_name: {category, confidence}} shape the rest
-        of this service consumed from the old JSON column — so all downstream
-        threshold/alias/merge logic is unchanged."""
-        rows = (
-            await self.session.execute(
-                select(
-                    ImagePrediction.raw_name,
-                    ImagePrediction.category,
-                    ImagePrediction.score,
-                ).where(ImagePrediction.image_record_id == image_id)
-            )
-        ).all()
-        return {
-            r.raw_name: {"category": r.category, "confidence": r.score}
-            for r in rows
-        }
-
-    def _threshold_for(
-        self, s: MLSettings, category: str, override: float | None = None,
-    ) -> float:
-        # 'artist' (FC-2d-vii-c) and 'copyright' (2026-06-01) retired;
-        # both fall through to the 1.01 "never surfaces" default like any
-        # unsurfaced category.
-        # override (the typed-dropdown "show everything the model saw" mode)
-        # applies to the surfaced categories only — unsurfaced ones are already
-        # skipped before the threshold check, so they can't leak in.
-        if override is not None:
-            return override
-        return {
-            "character": s.suggestion_threshold_character,
-            "general": s.suggestion_threshold_general,
-        }.get(category, 1.01)
 
     async def for_image(
-        self, image_id: int, *, threshold_override: float | None = None,
+        self, image_id: int, threshold_override: float | None = None,
     ) -> SuggestionList:
-        """Ranked suggestions for one image.
+        """Head-scored suggestions for one image, grouped by category and ranked.
 
-        threshold_override surfaces EVERY stored tagger prediction (down to the
-        ingest STORE_FLOOR) regardless of the configured per-category suggestion
-        thresholds — backs the tag-input dropdown's "search all of the model's
-        predictions, including low-confidence ones, in the canonical formatting"
-        mode (operator-asked 2026-06-09). The Suggestions panel still calls with
-        no override so it stays the curated above-threshold list."""
+        Each trained head scores the image's frozen embedding; a concept surfaces
+        when its score clears the head's own suggest threshold. threshold_override
+        (used by the typed tag-input dropdown's "show everything" mode) replaces
+        that per-head cut with a flat floor (0 → every head), so a low-scoring
+        concept can still be typed + picked in canonical formatting.
+
+        Already-applied tags are dropped; rejected tags stay FLAGGED and sink to
+        the bottom of their category so a dismissal is visible + reversible."""
         img = await self.session.get(ImageRecord, image_id)
         if img is None:
             return SuggestionList()
 
-        settings = await self._settings()
-        predictions: dict = await self._load_predictions(image_id)
-
         applied = set(
             (
                 await self.session.execute(
@@ -129,148 +90,50 @@ class SuggestionService:
             ).scalars().all()
         )
 
-        # --- Camie predictions ---
-        # candidates carry (raw_name, display_name, category, confidence).
-        # raw_name = the booru-formatted vocab key, kept for alias_map
-        # lookup since alias rows are hand-curated against raw keys.
-        # display_name = normalize_tag_name(raw_name) — what the operator
-        # sees AND what gets written to tag.name on Accept.
-        candidates: list[tuple[str, str, str, float]] = []
-        for name, p in predictions.items():
-            category = p.get("category", "general")
-            if category not in SURFACED_CATEGORIES:
-                continue
-            conf = float(p.get("confidence", 0.0))
-            if conf < self._threshold_for(settings, category, threshold_override):
-                continue
-            display = normalize_tag_name(name)
-            if display is None:
-                # emoticon / pure-punctuation vocab entry — drop entirely
-                continue
-            candidates.append((name, display, category, conf))
-
-        alias_map = await self.aliases.resolve_many(
-            [(raw, c) for raw, _disp, c, _conf in candidates]
+        hits = await score_image(
+            self.session, image_id, threshold_override=threshold_override
         )
+        # CCIP character matches OVERLAY the SigLIP character heads — a
+        # complementary, identity-specialized signal with different failure modes
+        # (CCIP needs a detected figure; heads work whole-image). Merged by tag:
+        # 'both' when they corroborate, taking the higher score.
+        ccip_hits = await ccip_match_image(self.session, image_id)
 
-        merged: dict[object, Suggestion] = {}
-
-        def _merge(key, sug: Suggestion):
-            existing = merged.get(key)
-            if existing is None:
-                merged[key] = sug
-            elif sug.score > existing.score:
-                merged[key] = Suggestion(
-                    canonical_tag_id=existing.canonical_tag_id,
-                    display_name=existing.display_name,
-                    category=existing.category,
-                    score=sug.score,
-                    source="both"
-                    if existing.source != sug.source
-                    else existing.source,
-                    creates_new_tag=existing.creates_new_tag,
-                    # Keep the alias identity from `existing`: the tagger pass
-                    # (which carries raw_name / via_alias) runs before centroid
-                    # augmentation, so it's always the first writer for a key.
-                    raw_name=existing.raw_name,
-                    via_alias=existing.via_alias,
-                )
-
-        for raw, display, category, conf in candidates:
-            canonical = alias_map.get((raw, category))
-            if canonical is not None:
-                if canonical.id in applied or canonical.id in rejected:
-                    continue
-                _merge(
-                    canonical.id,
-                    Suggestion(
-                        canonical_tag_id=canonical.id,
-                        display_name=canonical.name,
-                        category=category,
-                        score=conf,
-                        source="tagger",
-                        creates_new_tag=False,
-                        raw_name=raw,
-                        via_alias=True,
-                    ),
-                )
+        merged: dict[tuple[str, int], dict] = {}
+        for h in hits:
+            merged[(h["category"], h["tag_id"])] = {
+                "name": h["name"], "score": h["score"], "source": "head",
+            }
+        for c in ccip_hits:
+            key = ("character", c["tag_id"])
+            ex = merged.get(key)
+            if ex is not None:
+                ex["source"] = "both"
+                ex["score"] = max(ex["score"], c["score"])
             else:
-                # Case-insensitive match on BOTH the raw camie key AND
-                # the normalized form — covers legacy underscore-named
-                # Tag rows accepted before normalization shipped, AND
-                # any tag the operator created with the human form.
-                existing_tag = (
-                    await self.session.execute(
-                        select(Tag).where(
-                            func.lower(Tag.name).in_(
-                                [raw.lower(), display.lower()]
-                            )
-                        )
-                    )
-                ).scalars().first()
-                if existing_tag is not None:
-                    if (
-                        existing_tag.id in applied
-                        or existing_tag.id in rejected
-                    ):
-                        continue
-                    _merge(
-                        existing_tag.id,
-                        Suggestion(
-                            canonical_tag_id=existing_tag.id,
-                            display_name=existing_tag.name,
-                            category=category,
-                            score=conf,
-                            source="tagger",
-                            creates_new_tag=False,
-                            raw_name=raw,
-                            via_alias=False,
-                        ),
-                    )
-                else:
-                    _merge(
-                        f"raw:{display}:{category}",
-                        Suggestion(
-                            canonical_tag_id=None,
-                            display_name=display,
-                            category=category,
-                            score=conf,
-                            source="tagger",
-                            creates_new_tag=True,
-                            raw_name=raw,
-                            via_alias=False,
-                        ),
-                    )
-
-        # --- Centroid augmentation ---
-        hits = await self.centroids.find_similar_tags(image_id, limit=30)
-        for hit in hits:
-            if hit.similarity < settings.centroid_similarity_threshold:
-                continue
-            if hit.tag_id in applied or hit.tag_id in rejected:
-                continue
-            tag = await self.session.get(Tag, hit.tag_id)
-            if tag is None:
-                continue
-            cat = tag.kind.value if hasattr(tag.kind, "value") else str(tag.kind)
-            display_cat = cat if cat in SURFACED_CATEGORIES else "general"
-            _merge(
-                tag.id,
-                Suggestion(
-                    canonical_tag_id=tag.id,
-                    display_name=tag.name,
-                    category=display_cat,
-                    score=hit.similarity,
-                    source="centroid",
-                    creates_new_tag=False,
-                ),
-            )
+                merged[key] = {
+                    "name": c["name"], "score": c["score"], "source": "ccip",
+                }
 
         result = SuggestionList()
-        for sug in merged.values():
-            result.by_category.setdefault(sug.category, []).append(sug)
+        for (cat, tag_id), m in merged.items():
+            if tag_id in applied:
+                continue
+            result.by_category.setdefault(cat, []).append(
+                Suggestion(
+                    canonical_tag_id=tag_id,
+                    display_name=m["name"],
+                    category=cat,
+                    score=m["score"],
+                    source=m["source"],
+                    creates_new_tag=False,
+                    rejected=tag_id in rejected,
+                )
+            )
         for cat in result.by_category:
-            result.by_category[cat].sort(key=lambda s: s.score, reverse=True)
+            # Live suggestions first (by score), rejected ones sink to the
+            # bottom of the category — visible for recovery, out of the way.
+            result.by_category[cat].sort(key=lambda s: (s.rejected, -s.score))
         return result
 
     async def for_selection(
@@ -297,6 +160,11 @@ class SuggestionService:
                 for s in items:
                     if s.canonical_tag_id is None or s.creates_new_tag:
                         continue
+                    # for_image keeps rejected tags (flagged) for the rail;
+                    # bulk consensus must still ignore them — a tag dismissed on
+                    # an image isn't a suggestion for that image.
+                    if s.rejected:
+                        continue
                     st = stats.get(s.canonical_tag_id)
                     if st is None:
                         st = {

backend/app/services/tag_service.py

@@ -9,7 +9,7 @@ from sqlalchemy import and_, case, exists, func, select, text, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ..models import Tag, TagKind, image_tag
+from ..models import HeadMetric, Tag, TagHead, TagKind, image_tag
 from ..models.tag_allowlist import TagAllowlist
 from ..models.tag_reference_embedding import TagReferenceEmbedding
 from .db_helpers import get_or_create
@@ -215,6 +215,18 @@ class TagService:
 
     async def add_to_image(self, image_id: int, tag_id: int, source: str = "manual") -> None:
         """Idempotent: re-adding an existing tag does nothing."""
+        # A genuinely-new MANUAL add of a tag that already has a head is an
+        # UNDER-FIRE signal — the auto-system should have caught it (#114 obs).
+        is_new = source == "manual" and (
+            await self.session.execute(
+                select(image_tag.c.tag_id).where(
+                    and_(
+                        image_tag.c.image_record_id == image_id,
+                        image_tag.c.tag_id == tag_id,
+                    )
+                )
+            )
+        ).first() is None
         stmt = pg_insert(image_tag).values(
             image_record_id=image_id, tag_id=tag_id, source=source
         )
@@ -222,8 +234,22 @@ class TagService:
             index_elements=["image_record_id", "tag_id"]
         )
         await self.session.execute(stmt)
+        if is_new:
+            await self._note_under_fire(tag_id)
 
     async def remove_from_image(self, image_id: int, tag_id: int) -> None:
+        # Removing an auto-applied (source='head_auto') tag is a MISFIRE — read
+        # the source BEFORE deleting, since it's lost with the row (#114 obs).
+        src = (
+            await self.session.execute(
+                select(image_tag.c.source).where(
+                    and_(
+                        image_tag.c.image_record_id == image_id,
+                        image_tag.c.tag_id == tag_id,
+                    )
+                )
+            )
+        ).scalar_one_or_none()
         await self.session.execute(
             image_tag.delete().where(
                 and_(
@@ -232,6 +258,31 @@ class TagService:
                 )
             )
         )
+        if src == "head_auto":
+            await self._bump_metric(tag_id, "n_misfires")
+
+    async def _note_under_fire(self, tag_id: int) -> None:
+        """Count an under-fire only when the tag actually has a head."""
+        has_head = (
+            await self.session.execute(
+                select(TagHead.tag_id).where(TagHead.tag_id == tag_id)
+            )
+        ).first() is not None
+        if has_head:
+            await self._bump_metric(tag_id, "n_underfires")
+
+    async def _bump_metric(self, tag_id: int, column: str) -> None:
+        """Increment a HeadMetric counter (upsert), keyed by tag so it survives
+        head retrain/prune."""
+        col = HeadMetric.__table__.c[column]
+        await self.session.execute(
+            pg_insert(HeadMetric)
+            .values(tag_id=tag_id, **{column: 1})
+            .on_conflict_do_update(
+                index_elements=["tag_id"],
+                set_={column: col + 1, "updated_at": func.now()},
+            )
+        )
 
     async def list_for_image(self, image_id: int) -> Sequence:
         """Tags on an image, ordered (kind, name). Each row carries the fandom's

backend/app/tasks/maintenance.py

@@ -13,6 +13,8 @@ from ..celery_app import celery
 from ..models import (
     BackupRun,
     DownloadEvent,
+    HeadAutoApplyRun,
+    HeadTrainingRun,
     ImageRecord,
     ImportBatch,
     ImportSettings,
@@ -97,6 +99,12 @@ LIBRARY_AUDIT_STALL_THRESHOLD_MINUTES = 135
 # tag-eval (#1130) has a 30-min soft limit; flag a run with no progress past 40.
 TAG_EVAL_STALL_THRESHOLD_MINUTES = 40
 TAG_EVAL_KEEP_RUNS = 20
+# head training (#114) has a 60-min soft limit; flag no-progress past 75.
+HEAD_TRAINING_STALL_THRESHOLD_MINUTES = 75
+HEAD_TRAINING_KEEP_RUNS = 20
+# head auto-apply (#114) shares the 60-min soft limit; flag past 75.
+HEAD_AUTO_APPLY_STALL_THRESHOLD_MINUTES = 75
+HEAD_AUTO_APPLY_KEEP_RUNS = 20
 # Import batches finalize only after every child ImportTask hits a
 # terminal state. The recovery sweep targets the case where every
 # task is done but the batch never got its closing UPDATE
@@ -753,6 +761,168 @@ def recover_stalled_tag_eval_runs() -> int:
         return recovered
 
 
+@celery.task(name="backend.app.tasks.maintenance.recover_stalled_head_training_runs")
+def recover_stalled_head_training_runs() -> int:
+    """Flip HeadTrainingRun rows stuck in 'running' past the stall threshold to
+    'error', and prune old runs to the last HEAD_TRAINING_KEEP_RUNS (retention,
+    rule 89). Runs every 5 min on the maintenance lane; no-op when idle."""
+    SessionLocal = _sync_session_factory()
+    now = datetime.now(UTC)
+    cutoff = now - timedelta(minutes=HEAD_TRAINING_STALL_THRESHOLD_MINUTES)
+    with SessionLocal() as session:
+        result = session.execute(
+            update(HeadTrainingRun)
+            .where(HeadTrainingRun.status == "running")
+            .where(
+                func.coalesce(
+                    HeadTrainingRun.last_progress_at, HeadTrainingRun.started_at
+                )
+                < cutoff
+            )
+            .values(
+                status="error", finished_at=now,
+                error=(
+                    f"stranded by recovery sweep (no progress for "
+                    f"{HEAD_TRAINING_STALL_THRESHOLD_MINUTES} min)"
+                ),
+            )
+        )
+        keep = session.execute(
+            select(HeadTrainingRun.id).order_by(HeadTrainingRun.id.desc())
+            .limit(HEAD_TRAINING_KEEP_RUNS)
+        ).scalars().all()
+        if keep:
+            session.execute(
+                delete(HeadTrainingRun).where(HeadTrainingRun.id.not_in(keep))
+            )
+        session.commit()
+        recovered = result.rowcount or 0
+        if recovered:
+            log.info(
+                "recover_stalled_head_training_runs: recovered %d rows", recovered
+            )
+        return recovered
+
+
+@celery.task(name="backend.app.tasks.maintenance.recover_stalled_head_auto_apply_runs")
+def recover_stalled_head_auto_apply_runs() -> int:
+    """Flip stalled HeadAutoApplyRun 'running' rows to 'error' + prune to the
+    last HEAD_AUTO_APPLY_KEEP_RUNS (retention, rule 89). 5-min maintenance lane."""
+    SessionLocal = _sync_session_factory()
+    now = datetime.now(UTC)
+    cutoff = now - timedelta(minutes=HEAD_AUTO_APPLY_STALL_THRESHOLD_MINUTES)
+    with SessionLocal() as session:
+        result = session.execute(
+            update(HeadAutoApplyRun)
+            .where(HeadAutoApplyRun.status == "running")
+            .where(
+                func.coalesce(
+                    HeadAutoApplyRun.last_progress_at, HeadAutoApplyRun.started_at
+                )
+                < cutoff
+            )
+            .values(
+                status="error", finished_at=now,
+                error=(
+                    f"stranded by recovery sweep (no progress for "
+                    f"{HEAD_AUTO_APPLY_STALL_THRESHOLD_MINUTES} min)"
+                ),
+            )
+        )
+        keep = session.execute(
+            select(HeadAutoApplyRun.id).order_by(HeadAutoApplyRun.id.desc())
+            .limit(HEAD_AUTO_APPLY_KEEP_RUNS)
+        ).scalars().all()
+        if keep:
+            session.execute(
+                delete(HeadAutoApplyRun).where(HeadAutoApplyRun.id.not_in(keep))
+            )
+        session.commit()
+        recovered = result.rowcount or 0
+        if recovered:
+            log.info(
+                "recover_stalled_head_auto_apply_runs: recovered %d rows", recovered
+            )
+        return recovered
+
+
+# Keep ~6 months of daily head-metric snapshots (enough to see tuning trends).
+HEAD_METRICS_SNAPSHOT_RETENTION_DAYS = 180
+
+
+@celery.task(name="backend.app.tasks.maintenance.snapshot_head_metrics")
+def snapshot_head_metrics() -> int:
+    """Daily per-concept observability point (#114): record each head-bearing
+    concept's auto-applied volume, cumulative misfires/under-fires, and the
+    head's measured quality — the time-series the operator tunes from. Prunes
+    points older than the retention window."""
+    from ..models import (
+        HeadMetric,
+        HeadMetricsSnapshot,
+        Tag,
+        TagHead,
+    )
+    from ..models.tag import image_tag
+
+    SessionLocal = _sync_session_factory()
+    now = datetime.now(UTC)
+    with SessionLocal() as session:
+        heads = {
+            r.tag_id: r for r in session.execute(
+                select(
+                    TagHead.tag_id, TagHead.ap, TagHead.precision_cv,
+                    TagHead.recall, TagHead.n_pos,
+                )
+            )
+        }
+        metrics = {
+            r.tag_id: r for r in session.execute(
+                select(
+                    HeadMetric.tag_id, HeadMetric.n_misfires, HeadMetric.n_underfires
+                )
+            )
+        }
+        # .all() first: dict() of a bare Result tries the mapping protocol (a
+        # Result exposes .keys()) and subscripts it, which fails.
+        applied = dict(
+            session.execute(
+                select(image_tag.c.tag_id, func.count())
+                .where(image_tag.c.source == "head_auto")
+                .group_by(image_tag.c.tag_id)
+            ).all()
+        )
+        tag_ids = set(heads) | set(metrics)
+        if not tag_ids:
+            return 0
+        names = dict(
+            session.execute(
+                select(Tag.id, Tag.name).where(Tag.id.in_(tag_ids))
+            ).all()
+        )
+        for tid in tag_ids:
+            h = heads.get(tid)
+            m = metrics.get(tid)
+            session.add(HeadMetricsSnapshot(
+                tag_id=tid, name=names.get(tid, str(tid)),
+                snapshot_at=now,
+                n_auto_applied=applied.get(tid, 0),
+                n_misfires=m.n_misfires if m else 0,
+                n_underfires=m.n_underfires if m else 0,
+                ap=h.ap if h else None,
+                precision_cv=h.precision_cv if h else None,
+                recall=h.recall if h else None,
+                n_pos=h.n_pos if h else None,
+            ))
+        session.execute(
+            delete(HeadMetricsSnapshot).where(
+                HeadMetricsSnapshot.snapshot_at
+                < now - timedelta(days=HEAD_METRICS_SNAPSHOT_RETENTION_DAYS)
+            )
+        )
+        session.commit()
+        return len(tag_ids)
+
+
 @celery.task(name="backend.app.tasks.maintenance.recover_stalled_import_batches")
 def recover_stalled_import_batches() -> int:
     """Finalize ImportBatch rows stuck in running past the hard limit

backend/app/tasks/ml.py

@@ -583,3 +583,355 @@ def tag_eval_run(self, run_id: int) -> str:
         run.finished_at = datetime.now(UTC)
         session.commit()
         return "ready"
+
+
+@celery.task(
+    name="backend.app.tasks.ml.train_heads",
+    bind=True,
+    # Trains a logistic-regression head per eligible concept over stored SigLIP
+    # embeddings — minutes for a full library. Runs on the ml queue (only that
+    # worker has scikit-learn). Commits per head so a kill leaves progress.
+    soft_time_limit=3600, time_limit=3900,
+)
+def train_heads(self, run_id: int) -> str:
+    """(Re)train all eligible concept heads into tag_head, tracked by the
+    HeadTrainingRun row so the admin card shows live + historical status."""
+    from datetime import UTC, datetime
+
+    from ..models import HeadTrainingRun
+    from ..services.ml.heads import train_all_heads
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        run = session.get(HeadTrainingRun, run_id)
+        if run is None:
+            return "missing"
+        run.last_progress_at = datetime.now(UTC)
+        session.commit()
+        try:
+            result = train_all_heads(session, run.params, run)
+        except SoftTimeLimitExceeded:
+            run.status = "error"
+            run.error = "timed out"
+            run.finished_at = datetime.now(UTC)
+            session.commit()
+            raise
+        except Exception as exc:
+            log.exception("train_heads %d failed", run_id)
+            run.status = "error"
+            run.error = str(exc)
+            run.finished_at = datetime.now(UTC)
+            session.commit()
+            return "error"
+        run.n_trained = result["n_trained"]
+        run.n_skipped = result["n_skipped"]
+        run.status = "ready"
+        run.finished_at = datetime.now(UTC)
+        session.commit()
+        return "ready"
+
+
+@celery.task(name="backend.app.tasks.ml.scheduled_train_heads")
+def scheduled_train_heads() -> str:
+    """Nightly passive retrain (#114): fold the day's accepts/rejects + any
+    newly-eligible concepts into the heads without the operator clicking. Skips
+    if a run is already in flight (one at a time). Creates + COMMITS the run row
+    before dispatching so the ml-queue worker can always find it."""
+    from datetime import UTC, datetime
+
+    from sqlalchemy import select as sa_select
+
+    from ..models import HeadTrainingRun
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        running = session.execute(
+            sa_select(HeadTrainingRun.id).where(HeadTrainingRun.status == "running")
+        ).scalar_one_or_none()
+        if running is not None:
+            return "already running"
+        run = HeadTrainingRun(
+            params={"source": "scheduled"}, status="running",
+            last_progress_at=datetime.now(UTC),
+        )
+        session.add(run)
+        session.commit()
+        run_id = run.id
+    train_heads.delay(run_id)
+    return "dispatched"
+
+
+@celery.task(
+    name="backend.app.tasks.ml.apply_head_tags",
+    bind=True,
+    # Scores the whole library against the graduated heads and applies their
+    # tags (or, dry_run, just counts). Streams embeddings in chunks; numpy only,
+    # but ml queue keeps it off the API workers. Commits per chunk.
+    soft_time_limit=3600, time_limit=3900,
+)
+def apply_head_tags(self, run_id: int) -> str:
+    """Run an earned-auto-apply sweep into the persisted HeadAutoApplyRun row."""
+    from datetime import UTC, datetime
+
+    from ..models import HeadAutoApplyRun
+    from ..services.ml.heads import auto_apply_sweep
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        run = session.get(HeadAutoApplyRun, run_id)
+        if run is None:
+            return "missing"
+        run.last_progress_at = datetime.now(UTC)
+        session.commit()
+        try:
+            result = auto_apply_sweep(session, run, run.dry_run)
+        except SoftTimeLimitExceeded:
+            run.status = "error"
+            run.error = "timed out"
+            run.finished_at = datetime.now(UTC)
+            session.commit()
+            raise
+        except Exception as exc:
+            log.exception("apply_head_tags %d failed", run_id)
+            run.status = "error"
+            run.error = str(exc)
+            run.finished_at = datetime.now(UTC)
+            session.commit()
+            return "error"
+        run.n_applied = result["n_applied"]
+        run.report = {"concepts": result["concepts"]}
+        run.status = "ready"
+        run.finished_at = datetime.now(UTC)
+        session.commit()
+        return "ready"
+
+
+@celery.task(name="backend.app.tasks.ml.scheduled_apply_head_tags")
+def scheduled_apply_head_tags() -> str:
+    """Daily passive auto-apply sweep (#114) — only when the master switch is on.
+    Skips if a sweep is already in flight. Creates + COMMITS the run before
+    dispatching so the worker always finds it."""
+    from datetime import UTC, datetime
+
+    from sqlalchemy import select as sa_select
+
+    from ..models import HeadAutoApplyRun, MLSettings
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        enabled = session.execute(
+            sa_select(MLSettings.head_auto_apply_enabled).where(MLSettings.id == 1)
+        ).scalar_one_or_none()
+        if not enabled:
+            return "disabled"
+        running = session.execute(
+            sa_select(HeadAutoApplyRun.id).where(HeadAutoApplyRun.status == "running")
+        ).scalar_one_or_none()
+        if running is not None:
+            return "already running"
+        run = HeadAutoApplyRun(
+            dry_run=False, params={"dry_run": False, "source": "scheduled"},
+            status="running", last_progress_at=datetime.now(UTC),
+        )
+        session.add(run)
+        session.commit()
+        run_id = run.id
+    apply_head_tags.delay(run_id)
+    return "dispatched"
+
+
+@celery.task(name="backend.app.tasks.ml.enqueue_gpu_backfill")
+def enqueue_gpu_backfill(task_name: str) -> int:
+    """Enqueue a gpu_job for every image that still needs `task_name` (one
+    INSERT…SELECT, so it scales to a full library). The desktop agent drains the
+    queue over HTTP. Returns the number enqueued.
+
+    'siglip' gates on the RESULT (no concept region yet) rather than on a prior
+    job, so it picks up the back-catalogue of images that were CCIP-embedded
+    before concept crops existed, and retries images whose concept embed failed —
+    without re-touching their figure/CCIP regions."""
+    from sqlalchemy import exists, insert, literal
+    from sqlalchemy import select as sa_select
+
+    from ..models import GpuJob, ImageRecord, ImageRegion
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        if task_name == "siglip":
+            has_concept = exists().where(
+                ImageRegion.image_record_id == ImageRecord.id,
+                ImageRegion.kind == "concept",
+            )
+            queued = exists().where(
+                GpuJob.image_record_id == ImageRecord.id,
+                GpuJob.task == "siglip",
+                GpuJob.status.in_(["pending", "leased"]),
+            )
+            sel = sa_select(
+                ImageRecord.id, literal("siglip"), literal("pending")
+            ).where(~has_concept).where(~queued)
+        else:
+            already = exists().where(
+                GpuJob.image_record_id == ImageRecord.id,
+                GpuJob.task == task_name,
+                GpuJob.status.in_(["pending", "leased", "done"]),
+            )
+            sel = sa_select(
+                ImageRecord.id, literal(task_name), literal("pending")
+            ).where(~already)
+        # RETURNING + count: result.rowcount is unreliable for INSERT…SELECT.
+        rows = session.execute(
+            insert(GpuJob)
+            .from_select(["image_record_id", "task", "status"], sel)
+            .returning(GpuJob.id)
+        ).fetchall()
+        session.commit()
+        return len(rows)
+
+
+@celery.task(name="backend.app.tasks.ml.recover_orphaned_gpu_jobs")
+def recover_orphaned_gpu_jobs() -> int:
+    """Reset expired GPU-job leases back to pending — recovers work orphaned by an
+    agent that died mid-job (no graceful release). Short beat cadence so orphans
+    get picked back up quickly + the queue counts read honestly. Returns the
+    number recovered."""
+    from datetime import UTC, datetime
+
+    from sqlalchemy import update
+
+    from ..models import GpuJob
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        now = datetime.now(UTC)
+        res = session.execute(
+            update(GpuJob)
+            .where(GpuJob.status == "leased", GpuJob.lease_expires_at < now)
+            .values(
+                status="pending", lease_token=None, leased_at=None,
+                lease_expires_at=None, updated_at=now,
+            )
+        )
+        session.commit()
+        return res.rowcount or 0
+
+
+@celery.task(
+    name="backend.app.tasks.ml.scheduled_ccip_auto_apply",
+    soft_time_limit=1800, time_limit=2100,
+)
+def scheduled_ccip_auto_apply() -> str:
+    """Auto-tag confident CCIP character matches (source='ccip_auto') so identity
+    tags keep flowing without a button. No-op unless ccip_auto_apply_enabled.
+    References come only from single-character images (unambiguous); a tag is
+    applied where any figure's best cosine to a character's prototypes clears
+    ccip_auto_apply_threshold and it isn't already applied/rejected. Reversible."""
+    import numpy as np
+    from sqlalchemy import func
+    from sqlalchemy import select as sa_select
+    from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+    from ..models import ImageRegion, MLSettings, Tag, TagKind, TagSuggestionRejection
+    from ..models.tag import image_tag
+
+    fig = ("face", "figure")
+
+    def _l2(m):
+        n = np.linalg.norm(m, axis=1, keepdims=True)
+        n[n == 0] = 1.0
+        return m / n
+
+    SessionLocal = _sync_session_factory()
+    with SessionLocal() as session:
+        s = session.get(MLSettings, 1)
+        if s is None or not s.ccip_auto_apply_enabled:
+            return "disabled"
+        thr = float(s.ccip_auto_apply_threshold)
+
+        single = (
+            sa_select(image_tag.c.image_record_id)
+            .join(Tag, Tag.id == image_tag.c.tag_id)
+            .where(Tag.kind == TagKind.character)
+            .group_by(image_tag.c.image_record_id)
+            .having(func.count() == 1)
+        )
+        ref_rows = session.execute(
+            sa_select(image_tag.c.tag_id, ImageRegion.ccip_embedding)
+            .select_from(ImageRegion)
+            .join(
+                image_tag,
+                image_tag.c.image_record_id == ImageRegion.image_record_id,
+            )
+            .join(Tag, Tag.id == image_tag.c.tag_id)
+            .where(Tag.kind == TagKind.character)
+            .where(ImageRegion.kind.in_(fig))
+            .where(ImageRegion.ccip_embedding.is_not(None))
+            .where(ImageRegion.image_record_id.in_(single))
+        ).all()
+        if not ref_rows:
+            return "no-references"
+
+        by_char: dict[int, list] = {}
+        for tid, vec in ref_rows:
+            by_char.setdefault(tid, []).append(vec)
+        ref_tags = list(by_char)
+        mats = [_l2(np.asarray(by_char[t], dtype=np.float32)) for t in ref_tags]
+        allref = np.vstack(mats)                                  # (total, 768)
+        seg = np.cumsum([0] + [len(m) for m in mats])[:-1]        # per-char start
+
+        # Per character: images that already carry OR rejected the tag — skip.
+        skip = {t: set() for t in ref_tags}
+        for t in ref_tags:
+            for (iid,) in session.execute(
+                sa_select(image_tag.c.image_record_id).where(
+                    image_tag.c.tag_id == t
+                )
+            ):
+                skip[t].add(iid)
+            for (iid,) in session.execute(
+                sa_select(TagSuggestionRejection.image_record_id).where(
+                    TagSuggestionRejection.tag_id == t
+                )
+            ):
+                skip[t].add(iid)
+
+        img_ids = list(session.execute(
+            sa_select(ImageRegion.image_record_id)
+            .where(ImageRegion.kind.in_(fig), ImageRegion.ccip_embedding.is_not(None))
+            .distinct()
+        ).scalars())
+
+        applied = 0
+        chunk_n = 500
+        for start in range(0, len(img_ids), chunk_n):
+            chunk = img_ids[start:start + chunk_n]
+            rows = session.execute(
+                sa_select(ImageRegion.image_record_id, ImageRegion.ccip_embedding)
+                .where(
+                    ImageRegion.image_record_id.in_(chunk),
+                    ImageRegion.kind.in_(fig),
+                    ImageRegion.ccip_embedding.is_not(None),
+                )
+            ).all()
+            by_img: dict[int, list] = {}
+            for iid, vec in rows:
+                by_img.setdefault(iid, []).append(vec)
+            for iid, vecs in by_img.items():
+                q = _l2(np.asarray(vecs, dtype=np.float32))      # (nq, 768)
+                colmax = (q @ allref.T).max(axis=0)              # (total,)
+                charmax = np.maximum.reduceat(colmax, seg)       # (n_chars,)
+                for ci in np.where(charmax >= thr)[0]:
+                    t = ref_tags[int(ci)]
+                    if iid in skip[t]:
+                        continue
+                    skip[t].add(iid)
+                    session.execute(
+                        pg_insert(image_tag)
+                        .values(
+                            image_record_id=iid, tag_id=t, source="ccip_auto",
+                        )
+                        .on_conflict_do_nothing()
+                    )
+                    applied += 1
+            session.commit()
+        return f"applied={applied}"

frontend/src/components/modal/SuggestionItem.vue

@@ -1,29 +1,54 @@
 <template>
   <!-- Chip-card row: visible border + hover/focus state unifies the
        name, score, and action buttons as one "object" (operator-asked
-       2026-06-01). The row itself is informational; the explicit
-       Accept button + 3-dot menu are the action affordances. -->
-  <div class="fc-suggestion">
+       2026-06-01). The row itself is informational; the green ✓ / red ✗
+       verdict pair + 3-dot alias menu are the action affordances. -->
+  <div class="fc-suggestion" :class="{ 'fc-suggestion--rejected': suggestion.rejected }">
     <span class="fc-suggestion__name">
       {{ suggestion.display_name }}
-      <span v-if="suggestion.creates_new_tag" class="fc-suggestion__new"
+      <span v-if="suggestion.rejected" class="fc-suggestion__rejected-tag"
+        title="You rejected this for this image — un-reject to recover">rejected</span>
+      <span v-else-if="suggestion.creates_new_tag" class="fc-suggestion__new"
         title="No matching tag yet — accepting creates it">+ new</span>
       <span v-else-if="suggestion.via_alias" class="fc-suggestion__alias"
         :title="`Mapped from the tagger's “${suggestion.raw_name}” via an alias`">alias</span>
     </span>
     <span class="fc-suggestion__score">{{ scorePct }}</span>
-    <v-btn
-      class="fc-suggestion__accept"
-      size="small" variant="tonal" color="accent"
-      density="compact" rounded="pill"
-      :aria-label="`Accept ${suggestion.display_name}`"
-      @click="$emit('accept', suggestion)"
-    >
-      Accept
-    </v-btn>
+    <!-- Green ✓ / red ✗ pair (operator-asked 2026-06-28) mirrors the eval
+         card's verdict buttons: ✓ accepts the tag (positive), ✗ dismisses it
+         for this image (records a TagSuggestionRejection — a hard negative the
+         heads train on). Together they occupy ~the footprint of the old single
+         Accept pill, so rejecting is now a one-click peer of accepting rather
+         than buried in the kebab. When the row is already rejected the ✗ swaps
+         to an undo (↶) so the rejection is reversible in place. -->
+    <div class="fc-suggestion__acts">
+      <button
+        class="fc-act fc-act--yes" type="button"
+        :aria-label="`Accept ${suggestion.display_name}`"
+        :title="`Yes — tag ${suggestion.display_name}`"
+        @click="$emit('accept', suggestion)"
+      ><v-icon size="16">mdi-check</v-icon></button>
+      <button
+        v-if="suggestion.rejected"
+        class="fc-act fc-act--undo" type="button"
+        :aria-label="`Un-reject ${suggestion.display_name}`"
+        :title="`Undo — restore ${suggestion.display_name} as a suggestion`"
+        @click="$emit('undismiss', suggestion)"
+      ><v-icon size="16">mdi-undo-variant</v-icon></button>
+      <button
+        v-else
+        class="fc-act fc-act--no" type="button"
+        :aria-label="`Reject ${suggestion.display_name}`"
+        :title="`No — not ${suggestion.display_name}`"
+        @click="$emit('dismiss', suggestion)"
+      ><v-icon size="16">mdi-close</v-icon></button>
+    </div>
     <!-- Modal-safe kebab is baked into KebabMenu (this row lives in the
-         teleported image modal — #711). -->
+         teleported image modal — #711). Only rendered when an alias action
+         applies — dismiss now lives on the red ✗, so a centroid hit with no
+         alias option has no menu. -->
     <KebabMenu
+      v-if="hasMenu"
       class="fc-suggestion__menu" size="small" variant="outlined"
       :label="`More actions for ${suggestion.display_name}`"
     >
@@ -42,9 +67,6 @@
       >
         <v-list-item-title>Remove alias</v-list-item-title>
       </v-list-item>
-      <v-list-item @click="$emit('dismiss', suggestion)">
-        <v-list-item-title>Dismiss for this image</v-list-item-title>
-      </v-list-item>
     </KebabMenu>
   </div>
 </template>
@@ -54,9 +76,15 @@ import { computed } from 'vue'
 import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({ suggestion: { type: Object, required: true } })
-defineEmits(['accept', 'alias', 'remove-alias', 'dismiss'])
+defineEmits(['accept', 'alias', 'remove-alias', 'dismiss', 'undismiss'])
 
 const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
+// Kebab now only carries alias actions: show it when this suggestion can be
+// aliased (raw model key, not yet aliased) or is already aliased (so it can be
+// un-aliased). Centroid hits (no raw_name, no alias) have an empty menu → hide.
+const hasMenu = computed(() =>
+  Boolean(props.suggestion.raw_name) || Boolean(props.suggestion.via_alias)
+)
 </script>
 
 <style scoped>
@@ -104,12 +132,51 @@ const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
   color: rgb(var(--v-theme-on-surface-variant, var(--v-theme-on-surface)));
   font-family: 'JetBrains Mono', monospace;
 }
-/* Vuetify's compact density doesn't shrink the tonal button enough
-   for a tight row; clamp the min-width so Accept stays compact. */
-.fc-suggestion__accept :deep(.v-btn__content) {
-  font-size: 12px; letter-spacing: 0.02em;
+/* Green ✓ / red ✗ verdict pair — same circular language as the eval card
+   (TagEvalCard .fc-act) so accept/reject read identically across surfaces. */
+.fc-suggestion__acts {
+  flex: 0 0 auto; display: flex; gap: 4px;
+}
+.fc-act {
+  width: 26px; height: 26px; border-radius: 50%; border: none; cursor: pointer;
+  display: flex; align-items: center; justify-content: center; color: #fff;
+  opacity: 0.9; transition: transform 0.1s, opacity 0.1s;
+}
+.fc-act:hover { opacity: 1; transform: scale(1.1); }
+.fc-act:focus-visible {
+  outline: 2px solid rgb(var(--v-theme-accent)); outline-offset: 1px;
+}
+.fc-act--yes { background: rgb(var(--v-theme-success)); }
+.fc-act--no { background: rgb(var(--v-theme-error)); }
+/* Undo reads as neutral-secondary, not a verdict: outlined, not filled. */
+.fc-act--undo {
+  background: transparent; color: rgb(var(--v-theme-on-surface-variant));
+  border: 1px solid rgb(var(--v-theme-on-surface-variant), 0.5);
 }
 .fc-suggestion__menu {
   flex: 0 0 auto;
 }
+
+/* Rejected state: the row stays put (recovery), dimmed + red-edged so it
+   reads as "handled, negative" without shouting over live suggestions. */
+.fc-suggestion--rejected {
+  border-color: rgb(var(--v-theme-error), 0.4);
+  background: rgb(var(--v-theme-error), 0.06);
+}
+.fc-suggestion--rejected .fc-suggestion__name {
+  color: rgb(var(--v-theme-on-surface-variant));
+  text-decoration: line-through;
+  text-decoration-color: rgb(var(--v-theme-error), 0.6);
+}
+.fc-suggestion__rejected-tag {
+  display: inline-block;
+  font-size: 10px; font-weight: 600;
+  color: rgb(var(--v-theme-error));
+  background: rgb(var(--v-theme-error), 0.12);
+  border: 1px solid rgb(var(--v-theme-error), 0.4);
+  padding: 1px 6px; border-radius: 999px;
+  margin-left: 6px;
+  text-transform: uppercase; letter-spacing: 0.04em;
+  text-decoration: none;
+}
 </style>

frontend/src/components/modal/SuggestionsCategoryGroup.vue

@@ -18,6 +18,7 @@
         @alias="$emit('alias', $event)"
         @remove-alias="$emit('remove-alias', $event)"
         @dismiss="$emit('dismiss', $event)"
+        @undismiss="$emit('undismiss', $event)"
       />
     </div>
   </div>
@@ -33,7 +34,7 @@ const props = defineProps({
   collapsible: { type: Boolean, default: false },
   defaultOpen: { type: Boolean, default: true }
 })
-defineEmits(['accept', 'alias', 'remove-alias', 'dismiss'])
+defineEmits(['accept', 'alias', 'remove-alias', 'dismiss', 'undismiss'])
 
 const open = ref(props.collapsible ? props.defaultOpen : true)
 </script>

frontend/src/components/modal/SuggestionsPanel.vue

@@ -21,14 +21,14 @@
         v-show="store.byCategory[cat] && store.byCategory[cat].length"
         :label="labelFor(cat)" :items="store.byCategory[cat] || []"
         @accept="onAccept" @alias="onAlias" @remove-alias="onRemoveAlias"
-        @dismiss="store.dismiss"
+        @dismiss="onDismiss" @undismiss="onUndismiss"
       />
       <SuggestionsCategoryGroup
         v-if="store.byCategory.general && store.byCategory.general.length"
         label="General" :items="store.byCategory.general"
         collapsible :default-open="true"
         @accept="onAccept" @alias="onAlias" @remove-alias="onRemoveAlias"
-        @dismiss="store.dismiss"
+        @dismiss="onDismiss" @undismiss="onUndismiss"
       />
     </div>
 
@@ -57,9 +57,15 @@ const props = defineProps({
   // so the same panel refreshes the right surface. See TagPanel.
   host: { type: Object, default: null },
 })
-// 'accepted' lets the parent return focus to the tag input after a suggestion is
-// applied (operator-asked 2026-06-08).
-const emit = defineEmits(['accepted'])
+// 'accepted'/'dismissed' let the parent return focus to the tag input after a
+// suggestion is accepted OR rejected, so the operator keeps the keyboard flow on
+// the input without re-clicking (operator-asked 2026-06-08, 2026-06-30).
+const emit = defineEmits(['accepted', 'dismissed'])
+
+// Reject (✗) / un-reject (↶): apply the store change, then signal the parent to
+// re-focus the tag input — same return-to-input behaviour as accept.
+function onDismiss (s) { store.dismiss(s); emit('dismissed') }
+function onUndismiss (s) { store.undismiss(s); emit('dismissed') }
 const store = useSuggestionsStore()
 const modalStore = useModalStore()
 const host = props.host || modalStore

frontend/src/components/modal/TagAutocomplete.vue

@@ -72,7 +72,7 @@
             </v-icon>
           </template>
           <v-list-item-title>
-            Create "{{ parsedName }}" as {{ parsedKind }}
+            {{ createLabel }}
           </v-list-item-title>
         </v-list-item>
       </template>
@@ -178,14 +178,34 @@ watch(query, () => {
   }, 200)
 })
 
+// A same-name character ALREADY exists. Characters are unique by
+// (name, kind, fandom), so this is still a valid distinct tag in another fandom.
+const sameNameCharExists = computed(() =>
+  parsedKind.value === 'character' &&
+  hits.value.some(h =>
+    h.kind === 'character' && h.name.toLowerCase() === parsedName.value.toLowerCase(),
+  ),
+)
+
 const allowCreate = computed(() => {
   const q = parsedName.value
   if (!q) return false
+  // Characters disambiguate by fandom, so a same-named character in a DIFFERENT
+  // fandom is a valid new tag — always offer Create (the fandom picker resolves
+  // it; find_or_create is idempotent if you re-pick the same fandom). Other
+  // kinds are unique by (name, kind): an exact match means it already exists.
+  if (parsedKind.value === 'character') return true
   return !hits.value.some(h =>
     h.name.toLowerCase() === q.toLowerCase() && h.kind === parsedKind.value,
   )
 })
 
+const createLabel = computed(() =>
+  sameNameCharExists.value
+    ? `Create another "${parsedName.value}" character (different fandom)`
+    : `Create "${parsedName.value}" as ${parsedKind.value}`,
+)
+
 function scorePct (s) { return `${Math.round(s.score * 100)}%` }
 
 // This image's suggestions that match the typed query, minus any the server
@@ -202,6 +222,10 @@ const suggestionHits = computed(() => {
   const out = []
   for (const list of Object.values(suggestions.allByCategory)) {
     for (const s of list || []) {
+      // Rejected suggestions now stay in allByCategory (flagged) so the panel
+      // can show + un-reject them; keep them OUT of the type-to-add dropdown,
+      // whose job is finding a tag to ADD (un-reject lives in the panel).
+      if (s.rejected) continue
       const key = `${s.category}:${s.display_name.toLowerCase()}`
       if (!s.display_name.toLowerCase().includes(q)) continue
       if (seen.has(key)) continue

frontend/src/components/modal/TagPanel.vue

@@ -28,6 +28,7 @@
       :image-id="host.currentImageId"
       :host="host"
       @accepted="focusTagInput"
+      @dismissed="focusTagInput"
     />
 
     <!-- @after-leave: when either dialog finishes closing (apply OR cancel),

frontend/src/components/settings/GpuAgentCard.vue

@@ -0,0 +1,270 @@
+<template>
+  <MaintenanceTile
+    icon="mdi-expansion-card"
+    title="GPU agent (CCIP + crops)"
+    blurb="Connect a desktop-GPU agent to embed characters (CCIP) and crops. It pulls work over HTTP — your database and Redis stay private."
+    :open="true"
+  >
+    <p class="fc-muted text-body-2 mb-3">
+      The agent is a container you run on the machine with the GPU. It
+      authenticates with the token below, leases jobs from this server, computes
+      on the GPU, and posts results back — all over HTTP. Start it when you want
+      a burst; stop it to reclaim the card.
+    </p>
+
+    <!-- Token -->
+    <div class="fc-section-h mb-1">Agent token</div>
+    <div v-if="loading" class="fc-muted text-body-2">Loading…</div>
+    <template v-else>
+      <div v-if="tokenValue" class="fc-token">
+        <code class="fc-token__val">{{ masked ? maskedToken : tokenValue }}</code>
+        <v-btn
+          size="x-small" variant="text" :icon="masked ? 'mdi-eye' : 'mdi-eye-off'"
+          :title="masked ? 'Reveal' : 'Hide'" @click="masked = !masked"
+        />
+        <v-btn
+          size="x-small" variant="text" icon="mdi-content-copy"
+          title="Copy token" @click="onCopy"
+        />
+        <v-btn
+          size="small" variant="text" color="accent" class="ml-auto"
+          prepend-icon="mdi-refresh" :loading="rotating" @click="onRotate"
+        >Rotate</v-btn>
+      </div>
+      <div v-else>
+        <v-btn
+          color="accent" variant="flat" rounded="pill" size="small"
+          prepend-icon="mdi-key-plus" :loading="rotating" @click="onRotate"
+        >Generate token</v-btn>
+      </div>
+      <p class="fc-muted text-caption mt-2 mb-0">
+        Point the agent at <code>{{ baseUrl }}</code> with this token. Rotating
+        invalidates the old token — update the agent after you rotate.
+      </p>
+    </template>
+
+    <!-- Queue -->
+    <div class="fc-section-h mt-5 mb-2">Work queue</div>
+    <div class="fc-queue">
+      <div class="fc-q"><div class="fc-q__n">{{ queue.pending }}</div><div class="fc-q__l">pending</div></div>
+      <div class="fc-q"><div class="fc-q__n">{{ queue.leased }}</div><div class="fc-q__l">in flight</div></div>
+      <div class="fc-q"><div class="fc-q__n fc-good">{{ queue.done }}</div><div class="fc-q__l">done</div></div>
+      <div class="fc-q"><div class="fc-q__n" :class="queue.error ? 'fc-weak' : ''">{{ queue.error }}</div><div class="fc-q__l">errored</div></div>
+    </div>
+
+    <v-btn
+      class="mt-4" color="accent" variant="tonal" rounded="pill" size="small"
+      prepend-icon="mdi-account-box-multiple" :loading="backfilling" @click="onBackfill"
+    >Queue character embedding (CCIP)</v-btn>
+    <p class="fc-muted text-caption mt-2 mb-0">
+      Enqueues every image that doesn't have a CCIP embedding yet. Nothing
+      processes until the agent is running.
+    </p>
+
+    <v-btn
+      class="mt-3" color="accent" variant="tonal" rounded="pill" size="small"
+      prepend-icon="mdi-crop" :loading="backfillingSiglip" @click="onBackfillSiglip"
+    >Queue concept crops (SigLIP)</v-btn>
+    <p class="fc-muted text-caption mt-2 mb-0">
+      Enqueues every image that doesn't have concept-crop embeddings yet — the
+      localized vectors that help small/local tags (glasses, etc.) surface. New
+      images get these automatically; this catches the back-catalogue.
+    </p>
+
+    <!-- Match strictness -->
+    <div class="fc-section-h mt-5 mb-1">Character-match strictness</div>
+    <div v-if="ml.settings" class="d-flex align-center" style="gap:12px">
+      <v-slider
+        v-model="threshold" :min="0.70" :max="0.95" :step="0.01"
+        color="accent" hide-details density="compact" class="flex-grow-1"
+        :loading="savingThreshold" @end="onSaveThreshold"
+      />
+      <span class="fc-q__n" style="font-size:16px">{{ threshold.toFixed(2) }}</span>
+    </div>
+    <p class="fc-muted text-caption mt-1 mb-0">
+      How close a figure must be (CCIP cosine) to suggest a character. Higher =
+      stricter — fewer but more confident matches. 0.85 recommended; below ~0.80
+      a heavily-tagged character starts matching everything.
+    </p>
+
+    <!-- Auto-apply -->
+    <div v-if="ml.settings" class="d-flex align-center mt-5" style="gap:12px">
+      <v-switch
+        v-model="autoApply" color="accent" hide-details density="compact"
+        :loading="savingAuto" label="Auto-apply confident matches"
+        @update:model-value="onSaveAuto"
+      />
+      <v-text-field
+        v-model.number="autoThreshold" type="number" min="0.80" max="0.99"
+        step="0.01" density="compact" hide-details variant="outlined"
+        style="max-width:96px" :disabled="!autoApply" label="at"
+        @change="onSaveAuto"
+      />
+    </div>
+    <p class="fc-muted text-caption mt-1 mb-0">
+      When on, a very-confident character match tags the image on its own (daily,
+      reversible) — so identity tags keep flowing without review. Stricter than
+      the suggest cut; 0.92 recommended.
+    </p>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { toast } from '../../utils/toast.js'
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+import { useGpuStore } from '../../stores/gpu.js'
+import { useMLStore } from '../../stores/ml.js'
+import { copyText } from '../../utils/clipboard.js'
+
+const store = useGpuStore()
+const ml = useMLStore()
+const loading = ref(true)
+const tokenValue = ref(null)
+const masked = ref(true)
+const rotating = ref(false)
+const backfilling = ref(false)
+const backfillingSiglip = ref(false)
+const threshold = ref(0.85)
+const savingThreshold = ref(false)
+const autoApply = ref(true)
+const autoThreshold = ref(0.92)
+const savingAuto = ref(false)
+const queue = ref({ pending: 0, leased: 0, done: 0, error: 0 })
+let pollTimer = null
+
+const baseUrl = computed(() => window.location.origin)
+const maskedToken = computed(() => {
+  const t = tokenValue.value || ''
+  return t.length > 8 ? `${t.slice(0, 4)}••••••••${t.slice(-4)}` : '••••••••'
+})
+
+onMounted(async () => {
+  try {
+    tokenValue.value = (await store.token()).token
+  } catch { /* non-fatal */ } finally {
+    loading.value = false
+  }
+  await refreshQueue()
+  pollTimer = setInterval(() => { if (!document.hidden) refreshQueue() }, 5000)
+  try {
+    await ml.loadSettings()
+    if (ml.settings?.ccip_match_threshold != null) {
+      threshold.value = ml.settings.ccip_match_threshold
+    }
+    if (ml.settings?.ccip_auto_apply_enabled != null) {
+      autoApply.value = ml.settings.ccip_auto_apply_enabled
+      autoThreshold.value = ml.settings.ccip_auto_apply_threshold
+    }
+  } catch { /* non-fatal */ }
+})
+
+async function onSaveAuto() {
+  savingAuto.value = true
+  try {
+    await ml.patchSettings({
+      ccip_auto_apply_enabled: autoApply.value,
+      ccip_auto_apply_threshold: autoThreshold.value,
+    })
+    toast({ text: 'Auto-apply settings saved', type: 'success' })
+  } catch (e) {
+    toast({ text: `Could not save: ${e.message}`, type: 'error' })
+  } finally {
+    savingAuto.value = false
+  }
+}
+onUnmounted(() => { if (pollTimer) clearInterval(pollTimer) })
+
+async function onSaveThreshold() {
+  savingThreshold.value = true
+  try {
+    await ml.patchSettings({ ccip_match_threshold: threshold.value })
+    toast({ text: `Match strictness set to ${threshold.value.toFixed(2)}`, type: 'success' })
+  } catch (e) {
+    toast({ text: `Could not save: ${e.message}`, type: 'error' })
+  } finally {
+    savingThreshold.value = false
+  }
+}
+
+async function refreshQueue() {
+  try { queue.value = await store.status() } catch { /* non-fatal */ }
+}
+
+async function onRotate() {
+  rotating.value = true
+  try {
+    tokenValue.value = (await store.rotateToken()).token
+    masked.value = false
+    toast({ text: 'New agent token generated — update your agent', type: 'success' })
+  } catch (e) {
+    toast({ text: `Could not rotate token: ${e.message}`, type: 'error' })
+  } finally {
+    rotating.value = false
+  }
+}
+
+async function onCopy() {
+  try {
+    await copyText(tokenValue.value || '')   // resolves on success, throws on fail
+    toast({ text: 'Token copied', type: 'success' })
+  } catch {
+    toast({ text: 'Copy failed — select and copy manually', type: 'warning' })
+  }
+}
+
+async function onBackfill() {
+  backfilling.value = true
+  try {
+    await store.backfill('ccip')
+    toast({ text: 'Queued CCIP embedding — run the agent to process it', type: 'success' })
+    await refreshQueue()
+  } catch (e) {
+    toast({ text: `Could not queue backfill: ${e.message}`, type: 'error' })
+  } finally {
+    backfilling.value = false
+  }
+}
+
+async function onBackfillSiglip() {
+  backfillingSiglip.value = true
+  try {
+    await store.backfill('siglip')
+    toast({ text: 'Queued concept crops — run the agent to process them', type: 'success' })
+    await refreshQueue()
+  } catch (e) {
+    toast({ text: `Could not queue backfill: ${e.message}`, type: 'error' })
+  } finally {
+    backfillingSiglip.value = false
+  }
+}
+</script>
+
+<style scoped>
+.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
+.fc-section-h {
+  font-size: 13px; font-weight: 700; letter-spacing: 0.03em;
+  text-transform: uppercase; color: rgb(var(--v-theme-on-surface));
+}
+.fc-token {
+  display: flex; align-items: center; gap: 4px;
+  background: rgb(var(--v-theme-surface-light)); border-radius: 6px;
+  padding: 4px 6px 4px 10px;
+}
+.fc-token__val {
+  font-family: 'JetBrains Mono', monospace; font-size: 13px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.fc-queue { display: flex; gap: 24px; }
+.fc-q__n {
+  font-size: 20px; font-weight: 700; line-height: 1.1;
+  font-family: 'JetBrains Mono', monospace;
+}
+.fc-q__l {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em;
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+.fc-good { color: rgb(var(--v-theme-success)); }
+.fc-weak { color: rgb(var(--v-theme-error)); }
+</style>

frontend/src/components/settings/HeadsCard.vue

@@ -0,0 +1,455 @@
+<template>
+  <MaintenanceTile
+    icon="mdi-brain"
+    title="Concept heads (the learning suggester)"
+    blurb="Train the per-concept heads that turn your tags into suggestions — they replace Camie and sharpen every time you accept or reject."
+    :open="headCount > 0 || running"
+  >
+    <p class="fc-muted text-body-2 mb-3">
+      A <strong>head</strong> is a tiny classifier trained on the SigLIP
+      embeddings already stored on your images — your positives plus your
+      negatives (rejections). One is built per general/character concept with at
+      least <strong>{{ minPositives }}</strong> tagged images. Retrain after a
+      tagging session to fold in your latest accepts/rejects; scoring is live, so
+      the rail reflects a retrain on the next image you open.
+    </p>
+
+    <!-- Summary stats -->
+    <div class="fc-stats mb-3">
+      <div class="fc-stat">
+        <div class="fc-stat__n">{{ headCount }}</div>
+        <div class="fc-stat__l">heads</div>
+      </div>
+      <div class="fc-stat">
+        <div class="fc-stat__n">{{ graduatedCount }}</div>
+        <div class="fc-stat__l" title="Heads precise enough to auto-apply without review">auto-apply ready</div>
+      </div>
+      <div class="fc-stat">
+        <div class="fc-stat__n fc-stat__n--time">{{ lastTrained }}</div>
+        <div class="fc-stat__l">last trained</div>
+      </div>
+    </div>
+
+    <v-btn
+      v-if="!running"
+      color="accent" variant="flat" rounded="pill"
+      prepend-icon="mdi-play" :loading="busy" @click="onTrain"
+    >{{ headCount > 0 ? 'Retrain heads' : 'Train heads' }}</v-btn>
+
+    <div v-if="running" class="mt-3">
+      <v-progress-linear indeterminate color="accent" />
+      <div class="text-body-2 mt-2 fc-muted">Training… (started {{ startedAgo }})</div>
+    </div>
+
+    <v-alert
+      v-if="lastError"
+      type="error" variant="tonal" density="compact" class="mt-3"
+    >Training failed: {{ lastError }}</v-alert>
+
+    <!-- Empty state -->
+    <div v-if="!running && headCount === 0" class="fc-empty mt-4">
+      <v-icon size="32" color="accent">mdi-brain</v-icon>
+      <p class="fc-muted text-body-2 mt-2 mb-0">
+        No heads yet. Tag a handful of images for the concepts you care about,
+        then train — each concept with ≥ {{ minPositives }} tags becomes a head.
+      </p>
+    </div>
+
+    <!-- Per-concept table -->
+    <div v-if="heads.length" class="mt-4">
+      <div class="fc-muted text-caption mb-2">
+        {{ heads.length }} concept{{ heads.length === 1 ? '' : 's' }}, strongest first
+        (AP = average precision; auto-apply ⚡ = precise enough to fire without review)
+      </div>
+      <div class="fc-table-wrap">
+        <table class="fc-table">
+          <thead>
+            <tr>
+              <th class="fc-l">Concept</th>
+              <th>Cat</th>
+              <th class="fc-r" title="Tagged positives the head trained on">+tags</th>
+              <th class="fc-r">AP</th>
+              <th class="fc-r" title="Precision at the suggest operating point">P</th>
+              <th class="fc-r" title="Recall at the suggest operating point">R</th>
+              <th class="fc-c">⚡</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="h in heads" :key="h.tag_id">
+              <td class="fc-l">{{ h.name }}</td>
+              <td><span class="fc-cat">{{ h.category }}</span></td>
+              <td class="fc-r fc-mono">{{ h.n_pos }}</td>
+              <td class="fc-r fc-mono" :class="apClass(h.ap)">{{ pct(h.ap) }}</td>
+              <td class="fc-r fc-mono">{{ pct(h.precision) }}</td>
+              <td class="fc-r fc-mono">{{ pct(h.recall) }}</td>
+              <td class="fc-c">
+                <v-icon v-if="h.auto_apply" size="16" color="success"
+                  title="Auto-apply ready">mdi-lightning-bolt</v-icon>
+                <span v-else class="fc-muted">—</span>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+
+    <!-- Earned auto-apply -->
+    <div class="fc-auto mt-6">
+      <div class="d-flex align-center mb-1" style="gap: 10px;">
+        <v-icon size="18" color="accent">mdi-lightning-bolt</v-icon>
+        <span class="fc-section-h">Auto-apply</span>
+        <v-switch
+          v-model="autoEnabled" :loading="settingBusy" hide-details density="compact"
+          color="success" class="ml-auto" @update:model-value="onToggleAuto"
+        />
+      </div>
+      <p class="fc-muted text-body-2 mb-3">
+        Graduated heads (⚡, with ≥ {{ autoMinPosInput }} examples) apply their tag
+        on their own where they clear {{ Math.round((autoPrecisionInput || 0) * 100) }}%
+        precision. Every auto-tag is reversible; removing one teaches the head it
+        misfired.
+      </p>
+
+      <div class="d-flex mb-3" style="gap: 12px;">
+        <v-text-field
+          v-model.number="autoPrecisionInput" label="Precision target"
+          type="number" min="0.5" max="0.999" step="0.01" density="compact"
+          hide-details style="max-width: 200px;" :disabled="settingBusy"
+          @change="onSaveSettings"
+        />
+        <v-text-field
+          v-model.number="autoMinPosInput" label="Min examples to fire"
+          type="number" min="1" density="compact" hide-details
+          style="max-width: 200px;" :disabled="settingBusy"
+          @change="onSaveSettings"
+        />
+      </div>
+
+      <div class="d-flex" style="gap: 8px;">
+        <v-btn
+          size="small" variant="tonal" color="accent" rounded="pill"
+          prepend-icon="mdi-eye-outline" :loading="autoBusy" @click="onPreview"
+        >Preview</v-btn>
+        <v-btn
+          size="small" variant="flat" color="accent" rounded="pill"
+          prepend-icon="mdi-lightning-bolt"
+          :loading="autoBusy || autoRunning" :disabled="!autoEnabled"
+          @click="onApplyNow"
+        >Apply now</v-btn>
+      </div>
+
+      <div v-if="autoRunning" class="mt-3">
+        <v-progress-linear indeterminate color="accent" />
+        <div class="text-body-2 mt-2 fc-muted">Sweeping the library…</div>
+      </div>
+
+      <div v-if="lastSweep && !autoRunning" class="mt-3">
+        <div class="fc-muted text-caption mb-1">
+          {{ lastSweep.dry_run ? 'Preview' : 'Applied' }} ·
+          {{ formatTime(lastSweep.finished_at) }} ·
+          {{ lastSweep.dry_run ? 'would apply' : 'applied' }}
+          <strong>{{ sweepTotal(lastSweep) }}</strong>
+          tag{{ sweepTotal(lastSweep) === 1 ? '' : 's' }}
+        </div>
+        <div v-if="sweepConcepts(lastSweep).length" class="fc-chips">
+          <span v-for="c in sweepConcepts(lastSweep)" :key="c.tag_id" class="fc-chip">
+            {{ c.name }} <strong>{{ c.applied }}</strong>
+          </span>
+        </div>
+      </div>
+    </div>
+
+    <!-- Performance / tuning -->
+    <div v-if="metricsConcepts.length" class="mt-5">
+      <div class="fc-section-h mb-1">How auto-apply is landing</div>
+      <div class="fc-muted text-caption mb-2">
+        Misfire = an auto-tag you removed; missed = a tag you added by hand that a
+        head should have caught. Tune the precision target from the misfire rate.
+      </div>
+      <div class="fc-table-wrap">
+        <table class="fc-table">
+          <thead>
+            <tr>
+              <th class="fc-l">Concept</th>
+              <th class="fc-r" title="Tags currently auto-applied">applied</th>
+              <th class="fc-r" title="Auto-tags you removed">misfires</th>
+              <th class="fc-r" title="Removed / (applied + removed)">rate</th>
+              <th class="fc-r" title="Tags you added by hand that a head exists for">missed</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="c in metricsConcepts" :key="c.tag_id">
+              <td class="fc-l">{{ c.name }}</td>
+              <td class="fc-r fc-mono">{{ c.n_auto_applied }}</td>
+              <td class="fc-r fc-mono">{{ c.n_misfires }}</td>
+              <td class="fc-r fc-mono" :class="rateClass(c.misfire_rate)">
+                {{ ratePct(c.misfire_rate) }}
+              </td>
+              <td class="fc-r fc-mono">{{ c.n_underfires }}</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+  </MaintenanceTile>
+</template>
+
+<script setup>
+import { toast } from '../../utils/toast.js'
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+
+import MaintenanceTile from '../common/MaintenanceTile.vue'
+import { useHeadsStore } from '../../stores/heads.js'
+import { useMLStore } from '../../stores/ml.js'
+
+const store = useHeadsStore()
+const mlSettings = useMLStore()
+const summary = ref(null)
+const busy = ref(false)
+let pollTimer = null
+
+// --- Auto-apply state ---
+const autoEnabled = ref(false)
+const autoPrecisionInput = ref(0.97)
+const autoMinPosInput = ref(30)
+const settingBusy = ref(false)
+const autoBusy = ref(false)
+const autoStatus = ref(null)
+const metricsData = ref(null)
+let autoTimer = null
+
+const autoRunning = computed(() => autoStatus.value?.running_id != null)
+const lastSweep = computed(() =>
+  (autoStatus.value?.runs || []).find(r => r.status !== 'running') || null)
+const metricsConcepts = computed(() => metricsData.value?.concepts ?? [])
+
+const headCount = computed(() => summary.value?.head_count ?? 0)
+const graduatedCount = computed(() => summary.value?.graduated_count ?? 0)
+const heads = computed(() => summary.value?.heads ?? [])
+const running = computed(() => summary.value?.running_id != null)
+const minPositives = computed(() => mlSettings.settings?.head_min_positives ?? 8)
+const lastTrained = computed(() =>
+  summary.value?.last_trained_at ? relTime(summary.value.last_trained_at) : 'never')
+// Surface the most recent terminal run's error (if it ended in error).
+const lastError = computed(() => {
+  const r = (summary.value?.runs || []).find(x => x.status !== 'running')
+  return r && r.status === 'error' ? r.error : null
+})
+const startedAgo = computed(() => {
+  const r = (summary.value?.runs || []).find(x => x.status === 'running')
+  return r?.started_at ? formatTime(r.started_at) : ''
+})
+
+onMounted(async () => {
+  // Settings power the copy + the auto-apply tuning inputs.
+  try {
+    await mlSettings.loadSettings()
+    const s = mlSettings.settings || {}
+    autoEnabled.value = !!s.head_auto_apply_enabled
+    autoPrecisionInput.value = s.head_auto_apply_precision ?? 0.97
+    autoMinPosInput.value = s.head_auto_apply_min_positives ?? 30
+  } catch { /* non-fatal */ }
+  await refresh()
+  if (running.value) startPoll()
+  await refreshAuto()
+  if (autoRunning.value) startAutoPoll()
+  refreshMetrics()
+})
+onUnmounted(() => { stopPoll(); stopAutoPoll() })
+
+async function refresh() {
+  try {
+    summary.value = await store.status()
+  } catch { /* non-fatal — the card still offers a fresh train */ }
+}
+
+function startPoll() {
+  stopPoll()
+  pollTimer = setInterval(async () => {
+    await refresh()
+    if (!running.value) stopPoll()
+  }, 5000)
+}
+function stopPoll() {
+  if (pollTimer) { clearInterval(pollTimer); pollTimer = null }
+}
+
+async function onTrain() {
+  busy.value = true
+  try {
+    await store.train()
+    await refresh()
+    startPoll()
+  } catch (e) {
+    const msg = e.body?.running_id ? 'Training is already running.' : e.message
+    toast({ text: `Could not start training: ${msg}`, type: 'error' })
+  } finally {
+    busy.value = false
+  }
+}
+
+// --- Auto-apply ---
+async function refreshAuto() {
+  try { autoStatus.value = await store.autoApplyStatus() } catch { /* non-fatal */ }
+}
+async function refreshMetrics() {
+  try { metricsData.value = await store.metrics() } catch { /* non-fatal */ }
+}
+function startAutoPoll() {
+  stopAutoPoll()
+  autoTimer = setInterval(async () => {
+    const was = autoRunning.value
+    await refreshAuto()
+    // Sweep just finished → refresh the counts + landing metrics.
+    if (was && !autoRunning.value) { refreshMetrics(); refresh() }
+    if (!autoRunning.value) stopAutoPoll()
+  }, 4000)
+}
+function stopAutoPoll() { if (autoTimer) { clearInterval(autoTimer); autoTimer = null } }
+
+async function onToggleAuto(val) {
+  settingBusy.value = true
+  try {
+    await mlSettings.patchSettings({ head_auto_apply_enabled: !!val })
+    toast({ text: val ? 'Auto-apply on' : 'Auto-apply off', type: 'success' })
+  } catch (e) {
+    autoEnabled.value = !val   // revert the switch
+    toast({ text: `Could not update: ${e.message}`, type: 'error' })
+  } finally {
+    settingBusy.value = false
+  }
+}
+async function onSaveSettings() {
+  settingBusy.value = true
+  try {
+    await mlSettings.patchSettings({
+      head_auto_apply_precision: Number(autoPrecisionInput.value),
+      head_auto_apply_min_positives: Number(autoMinPosInput.value),
+    })
+  } catch (e) {
+    toast({ text: `Could not save: ${e.message}`, type: 'error' })
+  } finally {
+    settingBusy.value = false
+  }
+}
+function onPreview() { startSweep(true) }
+function onApplyNow() { startSweep(false) }
+async function startSweep(dryRun) {
+  autoBusy.value = true
+  try {
+    await store.autoApply(dryRun)
+    await refreshAuto()
+    startAutoPoll()
+  } catch (e) {
+    const code = e.body?.error
+    const msg = code === 'auto_apply_already_running' ? 'A sweep is already running.'
+      : code === 'auto_apply_disabled' ? 'Enable auto-apply first.'
+      : e.message
+    toast({ text: `Could not start sweep: ${msg}`, type: 'error' })
+  } finally {
+    autoBusy.value = false
+  }
+}
+function sweepConcepts(run) {
+  return (run?.report?.concepts || [])
+    .filter(c => c.applied > 0)
+    .sort((a, b) => b.applied - a.applied)
+}
+function sweepTotal(run) { return run?.n_applied ?? 0 }
+function ratePct(x) { return x == null ? '—' : `${Math.round(x * 100)}%` }
+function rateClass(x) {
+  if (x == null) return ''
+  if (x <= 0.03) return 'fc-good'
+  if (x <= 0.1) return 'fc-ok'
+  return 'fc-weak'
+}
+
+function pct(x) { return x == null ? '—' : `${Math.round(x * 100)}%` }
+function apClass(ap) {
+  if (ap == null) return ''
+  if (ap >= 0.85) return 'fc-good'
+  if (ap >= 0.7) return 'fc-ok'
+  return 'fc-weak'
+}
+function formatTime(iso) {
+  if (!iso) return ''
+  try { return new Date(iso).toLocaleString() } catch { return iso }
+}
+function relTime(iso) {
+  try {
+    const d = (Date.now() - new Date(iso).getTime()) / 1000
+    if (d < 60) return 'just now'
+    if (d < 3600) return `${Math.floor(d / 60)}m ago`
+    if (d < 86400) return `${Math.floor(d / 3600)}h ago`
+    return `${Math.floor(d / 86400)}d ago`
+  } catch { return iso }
+}
+</script>
+
+<style scoped>
+.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
+
+.fc-section-h {
+  font-size: 13px; font-weight: 700; letter-spacing: 0.03em;
+  text-transform: uppercase; color: rgb(var(--v-theme-on-surface));
+}
+.fc-auto {
+  border-top: 1px solid rgb(var(--v-theme-surface-light)); padding-top: 16px;
+}
+.fc-chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.fc-chip {
+  font-size: 12px; padding: 2px 8px; border-radius: 999px;
+  background: rgb(var(--v-theme-surface-light));
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+.fc-chip strong { color: rgb(var(--v-theme-on-surface)); }
+
+.fc-stats { display: flex; gap: 28px; }
+.fc-stat__n {
+  font-size: 22px; font-weight: 700; line-height: 1.1;
+  color: rgb(var(--v-theme-on-surface));
+  font-family: 'JetBrains Mono', monospace;
+}
+.fc-stat__n--time { font-size: 15px; font-weight: 600; }
+.fc-stat__l {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em;
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+
+.fc-empty {
+  text-align: center; padding: 18px 12px;
+  border: 1px dashed rgb(var(--v-theme-surface-light)); border-radius: 8px;
+}
+
+.fc-table-wrap {
+  max-height: 360px; overflow-y: auto;
+  border: 1px solid rgb(var(--v-theme-surface-light)); border-radius: 8px;
+}
+.fc-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.fc-table thead th {
+  position: sticky; top: 0; z-index: 1;
+  background: rgb(var(--v-theme-surface));
+  text-align: right; padding: 6px 10px; font-weight: 600;
+  color: rgb(var(--v-theme-on-surface-variant));
+  border-bottom: 1px solid rgb(var(--v-theme-surface-light));
+  white-space: nowrap;
+}
+.fc-table td {
+  padding: 5px 10px; text-align: right;
+  border-bottom: 1px solid rgba(var(--v-theme-surface-light), 0.5);
+}
+.fc-table tbody tr:hover { background: rgb(var(--v-theme-surface-light)); }
+.fc-l { text-align: left !important; }
+.fc-r { text-align: right; }
+.fc-c { text-align: center !important; }
+.fc-mono { font-family: 'JetBrains Mono', monospace; }
+.fc-cat {
+  font-size: 10px; text-transform: uppercase; letter-spacing: 0.03em;
+  color: rgb(var(--v-theme-on-surface-variant));
+  background: rgb(var(--v-theme-surface-light));
+  padding: 1px 6px; border-radius: 999px;
+}
+.fc-good { color: rgb(var(--v-theme-success)); }
+.fc-ok { color: rgb(var(--v-theme-on-surface)); }
+.fc-weak { color: rgb(var(--v-theme-error)); }
+</style>

frontend/src/components/settings/MaintenancePanel.vue

@@ -26,6 +26,8 @@
       </p>
       <div class="fc-tile-stack">
         <MLThresholdSliders />
+        <HeadsCard />
+        <GpuAgentCard />
         <AllowlistTable />
         <AliasTable />
         <TagEvalCard />
@@ -52,6 +54,8 @@ import ArchiveReextractCard from './ArchiveReextractCard.vue'
 import MissingFileRepairCard from './MissingFileRepairCard.vue'
 import DbMaintenanceCard from './DbMaintenanceCard.vue'
 import MLThresholdSliders from './MLThresholdSliders.vue'
+import HeadsCard from './HeadsCard.vue'
+import GpuAgentCard from './GpuAgentCard.vue'
 import AllowlistTable from './AllowlistTable.vue'
 import AliasTable from './AliasTable.vue'
 import TagEvalCard from './TagEvalCard.vue'

frontend/src/composables/useHeadTraining.js

@@ -0,0 +1,67 @@
+import { computed, ref } from 'vue'
+
+import { useHeadsStore } from '../stores/heads.js'
+import { toast } from '../utils/toast.js'
+
+// Shared "(re)train the concept heads" behaviour (#114): trigger + poll status,
+// with toasts on start/finish. Backs both the Settings card and the Explore
+// view's inline button so the active retrain works the same everywhere.
+// Call start() on mount and stop() on unmount to manage the poll timer.
+export function useHeadTraining() {
+  const store = useHeadsStore()
+  const summary = ref(null)
+  const busy = ref(false)        // the trigger POST is in flight
+  let timer = null
+
+  const running = computed(() => summary.value?.running_id != null)
+  const headCount = computed(() => summary.value?.head_count ?? 0)
+
+  async function refresh() {
+    try {
+      summary.value = await store.status()
+    } catch { /* non-fatal — the button still offers a fresh train */ }
+  }
+
+  function startPoll() {
+    stopPoll()
+    timer = setInterval(async () => {
+      const wasRunning = running.value
+      await refresh()
+      // Announce completion once, on the running → done transition.
+      if (wasRunning && !running.value) {
+        toast({
+          text: `Heads retrained — ${headCount.value} concept${headCount.value === 1 ? '' : 's'}`,
+          type: 'success',
+        })
+      }
+      if (!running.value) stopPoll()
+    }, 5000)
+  }
+
+  function stopPoll() {
+    if (timer) { clearInterval(timer); timer = null }
+  }
+
+  // Reflect an already-running run (e.g. the nightly one) on mount.
+  async function start() {
+    await refresh()
+    if (running.value) startPoll()
+  }
+
+  async function train() {
+    busy.value = true
+    try {
+      await store.train()
+      toast({ text: 'Head training started…', type: 'info' })
+      await refresh()
+      startPoll()
+    } catch (e) {
+      const msg = e.body?.running_id ? 'Training is already running.' : e.message
+      toast({ text: `Could not start training: ${msg}`, type: 'error' })
+    } finally {
+      busy.value = false
+    }
+  }
+
+  return { summary, running, busy, headCount, refresh, train, start, stop: stopPoll }
+}

frontend/src/stores/explore.js

@@ -11,7 +11,7 @@ import { toast } from '../utils/toast.js'
 // trail. The store ALSO acts as a TagPanel "host" (current/currentImageId +
 // tag CRUD over the anchor) so the Explore workspace reuses the modal's tag
 // rail verbatim for modal-parity tagging while rabbit-holing.
-const NEIGHBOR_LIMIT = 24
+const NEIGHBOR_LIMIT = 40   // a wider pool → more variety to browse + jump into
 
 export const useExploreStore = defineStore('explore', () => {
   const api = useApi()
@@ -19,6 +19,10 @@ export const useExploreStore = defineStore('explore', () => {
   const anchor = ref(null)       // /api/gallery/image/<id> payload
   const neighbors = ref([])      // [{id, thumbnail_url, ...}]
   const breadcrumb = ref([])     // [{id, thumbnail_url}] walked path
+  // Index of the current anchor within breadcrumb — browser-style back/forward.
+  // The trail keeps its forward branch when you step back (so ← / → can move
+  // through visited items); a NEW walk off a back-step truncates that branch.
+  const cursor = ref(-1)
   const loading = ref(false)
   const error = ref(null)
 
@@ -54,13 +58,49 @@ export const useExploreStore = defineStore('explore', () => {
     }
   }
 
-  // Forward walk appends; navigating to an id already in the trail (a
-  // breadcrumb click, or a loop back) TRIMS to it — so the route stays the
-  // single source of truth and the crumb bar never grows stale branches.
+  // The route is the source of truth; this reconciles the trail + cursor to it.
+  // Revisiting an id already on the path (← / →, a crumb click, or a loop) just
+  // MOVES the cursor there — the forward branch is preserved so → can return to
+  // it. A genuinely new image off a back-step truncates the stale forward branch
+  // (browser semantics), then appends and points the cursor at the new tip.
   function _reconcileTrail (id, thumbnailUrl) {
     const idx = breadcrumb.value.findIndex((c) => c.id === id)
-    if (idx >= 0) breadcrumb.value = breadcrumb.value.slice(0, idx + 1)
-    else breadcrumb.value = [...breadcrumb.value, { id, thumbnail_url: thumbnailUrl }]
+    if (idx >= 0) {
+      cursor.value = idx
+      return
+    }
+    const base = cursor.value < breadcrumb.value.length - 1
+      ? breadcrumb.value.slice(0, cursor.value + 1)
+      : breadcrumb.value
+    breadcrumb.value = [...base, { id, thumbnail_url: thumbnailUrl }]
+    cursor.value = breadcrumb.value.length - 1
+  }
+
+  // ← target: the previous crumb (null at the start of the trail).
+  function backTarget () {
+    return cursor.value > 0 ? breadcrumb.value[cursor.value - 1].id : null
+  }
+
+  // → target: after a ←, walk forward through the already-visited trail
+  // (browser-style). Otherwise jump to a varied neighbour to keep the
+  // rabbit-hole going — null if neither exists.
+  function forwardTarget () {
+    if (cursor.value >= 0 && cursor.value < breadcrumb.value.length - 1) {
+      return breadcrumb.value[cursor.value + 1].id
+    }
+    if (!neighbors.value.length) return null
+    // Prefer UNVISITED neighbours so → opens something new instead of landing on
+    // a crumb (which snaps the cursor back into the trail — the "loops back"
+    // report). Fall back to the full set only if every neighbour's been seen.
+    const seen = new Set(breadcrumb.value.map((c) => c.id))
+    let pool = neighbors.value.filter((n) => !seen.has(n.id))
+    if (!pool.length) pool = neighbors.value
+    // neighbors come similarity-sorted (nearest first). Skip the closest slice —
+    // those near-duplicates are exactly what you get stuck cycling through — and
+    // pick from the more-varied remainder, for real variance in the walk.
+    const skip = pool.length >= 6 ? Math.floor(pool.length / 3) : 0
+    const cands = pool.slice(skip)
+    return cands[Math.floor(Math.random() * cands.length)].id
   }
 
   function reset () {
@@ -68,6 +108,7 @@ export const useExploreStore = defineStore('explore', () => {
     anchor.value = null
     neighbors.value = []
     breadcrumb.value = []
+    cursor.value = -1
     error.value = null
     loading.value = false
   }
@@ -145,8 +186,8 @@ export const useExploreStore = defineStore('explore', () => {
   function close () {}
 
   return {
-    anchor, neighbors, breadcrumb, loading, error, NEIGHBOR_LIMIT,
-    anchorOn, reset,
+    anchor, neighbors, breadcrumb, cursor, loading, error, NEIGHBOR_LIMIT,
+    anchorOn, reset, backTarget, forwardTarget,
     // host surface
     current, currentImageId,
     reloadTags, addExistingTag, removeTag, createAndAdd, close,

frontend/src/stores/gpu.js

@@ -0,0 +1,33 @@
+import { defineStore } from 'pinia'
+
+import { useApi } from '../composables/useApi.js'
+
+// GPU agent control surface (#114): the FC-side admin for the desktop agent —
+// the bearer token it authenticates with, the job-queue depth, and the backfill
+// trigger. The agent itself talks to /api/gpu/jobs/* over HTTP; nothing here
+// touches Redis/Postgres directly.
+export const useGpuStore = defineStore('gpu', () => {
+  const api = useApi()
+
+  // { token: <string|null>, configured: bool }
+  async function token() {
+    return await api.get('/api/gpu/token')
+  }
+
+  // Generate a fresh token (invalidates the old one). Returns { token }.
+  async function rotateToken() {
+    return await api.post('/api/gpu/token/rotate')
+  }
+
+  // { pending, leased, done, error }
+  async function status() {
+    return await api.get('/api/gpu/status')
+  }
+
+  // Enqueue a job per image lacking one for `task` (the agent drains it).
+  async function backfill(task = 'ccip') {
+    return await api.post('/api/gpu/backfill', { body: { task } })
+  }
+
+  return { token, rotateToken, status, backfill }
+})

frontend/src/stores/heads.js

@@ -0,0 +1,41 @@
+import { defineStore } from 'pinia'
+
+import { useApi } from '../composables/useApi.js'
+
+// Heads (#114): the per-concept classifiers that LEARN from your tags and power
+// suggestions (replacing Camie + centroid). Training runs as a background task;
+// the card rehydrates status from GET /api/heads on mount so it survives
+// navigation (the run lives in head_training_run server-side).
+export const useHeadsStore = defineStore('heads', () => {
+  const api = useApi()
+
+  // Summary: head_count, graduated_count, last_trained_at, running_id, the
+  // per-concept head table, and recent training runs.
+  async function status() {
+    return await api.get('/api/heads')
+  }
+
+  // (Re)train all eligible heads. One run at a time (409 if already running).
+  async function train(params = {}) {
+    return await api.post('/api/heads/train', { body: { params } })
+  }
+
+  // Earned auto-apply: trigger a sweep. dry_run previews (writes nothing);
+  // a real sweep needs head_auto_apply_enabled on (else 400).
+  async function autoApply(dryRun = false) {
+    return await api.post('/api/heads/auto-apply', { body: { dry_run: dryRun } })
+  }
+
+  // Recent sweeps + per-concept report (volume / projected per head).
+  async function autoApplyStatus() {
+    return await api.get('/api/heads/auto-apply')
+  }
+
+  // Observability: per-concept counts (volume, misfires, under-fires, realized
+  // misfire rate, head quality) + the daily time-series, to tune from.
+  async function metrics() {
+    return await api.get('/api/heads/metrics')
+  }
+
+  return { status, train, autoApply, autoApplyStatus, metrics }
+})

frontend/src/stores/suggestions.js

@@ -84,6 +84,19 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
     }
   }
 
+  // Flip the `rejected` flag on the matching suggestion in BOTH lists in place,
+  // so a reject/un-reject shows immediately without dropping the row (visible,
+  // reversible rejection — misclick recovery, operator-asked 2026-06-27).
+  function _setRejectedEverywhere(suggestion, value) {
+    const key = _keyOf(suggestion)
+    const cat = suggestion.category
+    for (const map of [byCategory.value, allByCategory.value]) {
+      for (const s of map[cat] || []) {
+        if (_keyOf(s) === key) s.rejected = value
+      }
+    }
+  }
+
   async function accept(suggestion) {
     // Capture imageId so a mid-flight prev/next can't reroute the
     // accept POST to a different image AND push the tag to that
@@ -168,21 +181,36 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
   async function dismiss(suggestion) {
     const imageId = currentImageId
     if (imageId == null) return
-    // Dismiss needs a tag_id; raw tags have none, so dismissing a raw
-    // suggestion just hides it client-side (nothing to persist a rejection
-    // against until the tag exists).
-    if (suggestion.canonical_tag_id != null) {
-      await api.post(`/api/images/${imageId}/suggestions/dismiss`, {
-        body: { tag_id: suggestion.canonical_tag_id }
-      })
+    // Dismiss needs a tag_id. Raw tags (creates_new_tag) have none, so there's
+    // nothing to persist a rejection against — drop them client-side as before.
+    // Canonical tags persist a rejection and STAY in the list flagged rejected,
+    // so the operator can see it and one-click un-reject (misclick recovery).
+    if (suggestion.canonical_tag_id == null) {
+      if (currentImageId === imageId) _dropEverywhere(suggestion)
+      return
     }
+    await api.post(`/api/images/${imageId}/suggestions/dismiss`, {
+      body: { tag_id: suggestion.canonical_tag_id }
+    })
     if (currentImageId === imageId) {
-      _dropEverywhere(suggestion)
+      _setRejectedEverywhere(suggestion, true)
+    }
+  }
+
+  // Undo a per-image dismissal — the suggestion reverts to a live row.
+  async function undismiss(suggestion) {
+    const imageId = currentImageId
+    if (imageId == null || suggestion.canonical_tag_id == null) return
+    await api.post(`/api/images/${imageId}/suggestions/undismiss`, {
+      body: { tag_id: suggestion.canonical_tag_id }
+    })
+    if (currentImageId === imageId) {
+      _setRejectedEverywhere(suggestion, false)
     }
   }
 
   return {
     byCategory, allByCategory, loading, error,
-    load, loadAll, accept, aliasAccept, removeAlias, dismiss
+    load, loadAll, accept, aliasAccept, removeAlias, dismiss, undismiss
   }
 })

frontend/src/views/ExploreView.vue

@@ -22,19 +22,30 @@
         <button
           v-for="(c, i) in store.breadcrumb" :key="c.id"
           class="fc-ex__crumb"
-          :class="{ 'fc-ex__crumb--current': i === store.breadcrumb.length - 1 }"
+          :class="{ 'fc-ex__crumb--current': i === store.cursor }"
           type="button"
-          :aria-current="i === store.breadcrumb.length - 1 ? 'page' : undefined"
+          :aria-current="i === store.cursor ? 'page' : undefined"
           :title="`Step ${i + 1}`"
           @click="goTo(c.id)"
         >
           <img :src="c.thumbnail_url" alt="" loading="lazy" />
         </button>
-        <v-btn
-          class="fc-ex__reseed" size="small" variant="text" color="accent"
-          prepend-icon="mdi-shuffle-variant" :loading="seeding"
-          @click="reseed"
-        >Random image</v-btn>
+        <div class="fc-ex__trail-actions">
+          <!-- Active retrain right where you tag: fold the +/- you just gave
+               into the heads without a trip to Settings (the nightly beat is the
+               passive cadence). -->
+          <v-btn
+            size="small" variant="text" color="accent"
+            prepend-icon="mdi-brain" :loading="headsBusy || headsRunning"
+            title="Retrain the concept heads on your latest tags"
+            @click="trainHeads"
+          >{{ headsRunning ? 'Training…' : 'Retrain heads' }}</v-btn>
+          <v-btn
+            size="small" variant="text" color="accent"
+            prepend-icon="mdi-shuffle-variant" :loading="seeding"
+            @click="reseed"
+          >Random image</v-btn>
+        </div>
       </nav>
 
       <v-alert v-if="store.error" type="error" variant="tonal" class="ma-3">
@@ -79,12 +90,22 @@
         <!-- CENTER: the focused image (light viewer) + meta. -->
         <section class="fc-ex__viewer">
           <div class="fc-ex__canvas">
-            <ImageCanvas
-              v-if="store.anchor"
-              :key="store.anchor.id"
-              :src="store.anchor.image_url"
-              :alt="`Image ${store.anchor.id}`"
-            />
+            <template v-if="store.anchor">
+              <!-- Videos can't render in an <img> — branch to VideoCanvas like
+                   the modal does (an MP4 in ImageCanvas just shows the alt). -->
+              <ImageCanvas
+                v-if="!isVideo"
+                :key="store.anchor.id"
+                :src="store.anchor.image_url"
+                :alt="`Image ${store.anchor.id}`"
+              />
+              <VideoCanvas
+                v-else
+                :key="store.anchor.id"
+                :src="store.anchor.image_url"
+                :mime="store.anchor.mime"
+              />
+            </template>
           </div>
           <div v-if="store.anchor" class="fc-ex__viewer-foot">
             <div class="fc-ex__artist">{{ store.anchor.artist?.name || 'Unknown artist' }}</div>
@@ -115,8 +136,10 @@ import { useRoute, useRouter } from 'vue-router'
 import { useApi } from '../composables/useApi.js'
 import { useExploreStore } from '../stores/explore.js'
 import { useModalStore } from '../stores/modal.js'
+import { useHeadTraining } from '../composables/useHeadTraining.js'
 import { isTextEntry } from '../utils/textEntry.js'
 import ImageCanvas from '../components/modal/ImageCanvas.vue'
+import VideoCanvas from '../components/modal/VideoCanvas.vue'
 import ImageMetaBar from '../components/modal/ImageMetaBar.vue'
 import ProvenancePanel from '../components/modal/ProvenancePanel.vue'
 import TagPanel from '../components/modal/TagPanel.vue'
@@ -128,10 +151,18 @@ const store = useExploreStore()
 const modal = useModalStore()
 
 const anchorId = computed(() => route.params.imageId || null)
+const isVideo = computed(() => !!store.anchor?.mime?.startsWith('video/'))
 const seeding = ref(false)
 const seedError = ref(null)
 const tagPanelRef = ref(null)
 
+// Inline head-retrain (shared with the Settings card) so banking your latest
+// +/- feedback is one click while you walk content.
+const {
+  running: headsRunning, busy: headsBusy, train: trainHeads,
+  start: startHeads, stop: stopHeads,
+} = useHeadTraining()
+
 // Auto-focus the tag input after any action so tagging needs no extra click —
 // the whole point of the workspace (operator-asked 2026-06-26). nextTick waits
 // for the post-navigation re-render, then rAF lands the focus AFTER paint so a
@@ -191,16 +222,39 @@ function goTo (id) {
 
 function openInViewer (id) { modal.open(id) }
 
-// Modal-parity focus: T or "/" jumps to the tag input (the same shortcut the
-// image modal binds), unless the caret is already in a text field.
+// Keyboard: T or "/" jumps to the tag input (modal-parity); ←/→ walk the
+// breadcrumb trail — ← steps back, → goes forward to an already-visited item
+// or, with no forward history, jumps to a random neighbour (keep rabbit-holing).
 function onKeyDown (ev) {
-  if ((ev.key === 't' || ev.key === '/') && !isTextEntry(ev.target)) {
-    const input = document.querySelector('.fc-tag-autocomplete input')
-    if (input) { ev.preventDefault(); input.focus() }
+  if (ev.metaKey || ev.ctrlKey || ev.altKey) return
+  const inText = isTextEntry(ev.target)
+  if (ev.key === 't' || ev.key === '/') {
+    if (!inText) {
+      const input = document.querySelector('.fc-tag-autocomplete input')
+      if (input) { ev.preventDefault(); input.focus() }
+    }
+    return
   }
+  if (ev.key !== 'ArrowLeft' && ev.key !== 'ArrowRight') return
+  // The tag input auto-focuses after every walk, so also allow navigation while
+  // it's focused-but-EMPTY (the caret has nowhere to go) — otherwise arrow-nav
+  // would dead-end after one step. Once a tag is being typed, arrows move the
+  // caret instead.
+  const t = ev.target
+  const inEmptyTagInput =
+    inText && t.value === '' && t.closest?.('.fc-tag-autocomplete')
+  if (inText && !inEmptyTagInput) return
+  const id = ev.key === 'ArrowLeft' ? store.backTarget() : store.forwardTarget()
+  if (id != null) { ev.preventDefault(); goTo(id) }
 }
-onMounted(() => document.addEventListener('keydown', onKeyDown))
-onUnmounted(() => document.removeEventListener('keydown', onKeyDown))
+onMounted(() => {
+  document.addEventListener('keydown', onKeyDown)
+  startHeads()   // reflect a run already in flight (e.g. the nightly one)
+})
+onUnmounted(() => {
+  document.removeEventListener('keydown', onKeyDown)
+  stopHeads()
+})
 </script>
 
 <style scoped>
@@ -233,7 +287,9 @@ onUnmounted(() => document.removeEventListener('keydown', onKeyDown))
 .fc-ex__crumb img { width: 100%; height: 100%; object-fit: cover; }
 .fc-ex__crumb--current { border-color: rgb(var(--v-theme-accent)); }
 .fc-ex__crumb:focus-visible { outline: 2px solid rgb(var(--v-theme-accent)); outline-offset: 1px; }
-.fc-ex__reseed { margin-left: auto; }
+.fc-ex__trail-actions {
+  margin-left: auto; display: flex; align-items: center; gap: 4px; flex: 0 0 auto;
+}
 
 /* The three panes fill the remaining height; each scrolls on its own.
    grid-template-rows: minmax(0, 1fr) BOUNDS the single row to the container

tests/test_api_ccip.py

@@ -0,0 +1,72 @@
+"""CCIP/region observability API (#114) — coverage overview + per-image detail."""
+import pytest
+
+from backend.app.models import ImageRecord, ImageRegion, TagKind
+from backend.app.models.tag import image_tag
+from backend.app.services.tag_service import TagService
+
+pytestmark = pytest.mark.integration
+
+
+def _ccip(slot: int) -> list[float]:
+    v = [0.0] * 768
+    v[slot] = 1.0
+    return v
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+async def _figure(db, image_id, ccip):
+    db.add(ImageRegion(
+        image_record_id=image_id, kind="figure", rx=0.0, ry=0.0, rw=1.0, rh=1.0,
+        ccip_embedding=ccip, embedding_version="ccip-test",
+    ))
+
+
+@pytest.mark.asyncio
+async def test_overview_reports_coverage(client, db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "a" * 64)
+    await _figure(db, ref.id, _ccip(0))
+    await db.execute(image_tag.insert().values(
+        image_record_id=ref.id, tag_id=raven.id, source="manual",
+    ))
+    q = await _img(db, "b" * 64)
+    await _figure(db, q.id, _ccip(0))
+    await db.commit()
+
+    body = await (await client.get("/api/ccip/overview")).get_json()
+    assert body["regions_by_kind"].get("figure", 0) >= 2
+    assert body["images_with_figure_ccip"] >= 2
+    assert any(
+        c["name"] == "Raven" and c["n_refs"] >= 1
+        for c in body["character_references"]
+    )
+    assert "ccip-test" in body["embedding_versions"]
+
+
+@pytest.mark.asyncio
+async def test_image_detail_shows_regions_and_matches(client, db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "c" * 64)
+    await _figure(db, ref.id, _ccip(0))
+    await db.execute(image_tag.insert().values(
+        image_record_id=ref.id, tag_id=raven.id, source="manual",
+    ))
+    q = await _img(db, "d" * 64)
+    await _figure(db, q.id, _ccip(0))
+    await db.commit()
+
+    body = await (await client.get(f"/api/ccip/images/{q.id}")).get_json()
+    assert len(body["regions"]) == 1
+    r = body["regions"][0]
+    assert r["kind"] == "figure" and r["has_ccip"] is True and r["has_siglip"] is False
+    assert any(m["tag_id"] == raven.id for m in body["ccip_matches"])

tests/test_api_gpu.py

@@ -0,0 +1,117 @@
+"""GPU-job HTTP API (#114): bearer auth + lease/submit round-trip + backfill."""
+import pytest
+
+from backend.app.models import ImageRecord
+from backend.app.services.ml.gpu_jobs import GpuJobService
+from backend.app.services.ml.regions import RegionService
+
+pytestmark = pytest.mark.integration
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+@pytest.mark.asyncio
+async def test_agent_endpoints_require_bearer(client, db):
+    resp = await client.post("/api/gpu/jobs/lease", json={"agent_id": "a1"})
+    assert resp.status_code == 401
+    # A wrong token is also rejected.
+    await (await client.post("/api/gpu/token/rotate")).get_json()
+    bad = await client.post(
+        "/api/gpu/jobs/lease", json={"agent_id": "a1"},
+        headers={"Authorization": "Bearer nope"},
+    )
+    assert bad.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_lease_submit_round_trip(client, db):
+    img = await _img(db, "a" * 64)
+    await GpuJobService(db).enqueue(img.id, "ccip")
+    await db.commit()
+
+    token = (await (await client.post("/api/gpu/token/rotate")).get_json())["token"]
+    hdr = {"Authorization": f"Bearer {token}"}
+
+    leased = await client.post(
+        "/api/gpu/jobs/lease", json={"agent_id": "a1", "batch_size": 5}, headers=hdr,
+    )
+    assert leased.status_code == 200
+    jobs = (await leased.get_json())["jobs"]
+    assert len(jobs) == 1
+    j = jobs[0]
+    assert j["image_id"] == img.id and j["task"] == "ccip"
+    assert j["image_url"].startswith("/images/")
+
+    submitted = await client.post("/api/gpu/jobs/submit", json={
+        "agent_id": "a1", "job_id": j["job_id"],
+        "regions": [{
+            "kind": "figure", "bbox": [0.1, 0.1, 0.4, 0.4],
+            "ccip_embedding": [0.1] * 768, "embedding_version": "ccip-test",
+        }],
+    }, headers=hdr)
+    assert submitted.status_code == 200
+    assert (await submitted.get_json())["stored"] == 1
+
+    # Job closed (read on the app's own connection via the status endpoint).
+    st = await (await client.get("/api/gpu/status")).get_json()
+    assert st["done"] == 1 and st["pending"] == 0 and st["leased"] == 0
+
+    # Region persisted with its CCIP vector.
+    regs = await RegionService(db).get_regions(img.id, kinds=["figure"])
+    assert len(regs) == 1 and len(list(regs[0].ccip_embedding)) == 768
+
+
+@pytest.mark.asyncio
+async def test_submit_with_stale_lease_is_409(client, db):
+    img = await _img(db, "b" * 64)
+    await GpuJobService(db).enqueue(img.id, "ccip")
+    await db.commit()
+    token = (await (await client.post("/api/gpu/token/rotate")).get_json())["token"]
+    hdr = {"Authorization": f"Bearer {token}"}
+    j = (await (await client.post(
+        "/api/gpu/jobs/lease", json={"agent_id": "a1"}, headers=hdr,
+    )).get_json())["jobs"][0]
+    # A different agent can't submit someone else's lease.
+    resp = await client.post("/api/gpu/jobs/submit", json={
+        "agent_id": "other", "job_id": j["job_id"], "regions": [],
+    }, headers=hdr)
+    assert resp.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_backfill_enqueues_then_is_idempotent(db):
+    await _img(db, "c" * 64)
+    await _img(db, "d" * 64)
+    await db.commit()
+    from backend.app.tasks.ml import enqueue_gpu_backfill
+
+    n = enqueue_gpu_backfill("ccip")     # sync task, own session
+    assert n >= 2
+    assert enqueue_gpu_backfill("ccip") == 0   # all already pending
+
+
+@pytest.mark.asyncio
+async def test_release_hands_job_back_to_pending(client, db):
+    img = await _img(db, "e" * 64)
+    await GpuJobService(db).enqueue(img.id, "ccip")
+    await db.commit()
+    token = (await (await client.post("/api/gpu/token/rotate")).get_json())["token"]
+    hdr = {"Authorization": f"Bearer {token}"}
+    j = (await (await client.post(
+        "/api/gpu/jobs/lease", json={"agent_id": "a1"}, headers=hdr,
+    )).get_json())["jobs"][0]
+
+    resp = await client.post("/api/gpu/jobs/release", json={
+        "agent_id": "a1", "job_ids": [j["job_id"]],
+    }, headers=hdr)
+    assert resp.status_code == 200 and (await resp.get_json())["released"] == 1
+    st = await (await client.get("/api/gpu/status")).get_json()
+    assert st["pending"] == 1 and st["leased"] == 0

tests/test_api_heads.py

@@ -0,0 +1,120 @@
+"""Heads API + scoring (#114). Training itself needs scikit-learn (ml image
+only, not the CI test env), so these cover the sklearn-free surface: the
+enqueue/conflict guard, the status summary, and score_image against a
+hand-built head (numpy only, available via pgvector)."""
+import math
+
+import pytest
+
+from backend.app.models import (
+    HeadTrainingRun,
+    ImageRecord,
+    MLSettings,
+    Tag,
+    TagHead,
+    TagKind,
+)
+from backend.app.services.ml.heads import score_image
+from backend.app.services.tag_service import TagService
+
+pytestmark = pytest.mark.integration
+
+
+async def _img_with_embedding(db, sha, emb):
+    rec = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=emb,
+    )
+    db.add(rec)
+    await db.flush()
+    return rec
+
+
+async def _embedder_version(db) -> str:
+    from sqlalchemy import select
+
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    return s.embedder_model_version
+
+
+@pytest.mark.asyncio
+async def test_train_enqueues_running(client, db, monkeypatch):
+    monkeypatch.setattr(
+        "backend.app.tasks.ml.train_heads.delay", lambda *a, **k: None
+    )
+    resp = await client.post("/api/heads/train", json={})
+    assert resp.status_code == 202
+    body = await resp.get_json()
+    assert body["status"] == "running"
+    got = await db.get(HeadTrainingRun, body["run_id"])
+    assert got is not None and got.status == "running"
+
+
+@pytest.mark.asyncio
+async def test_train_conflicts_when_one_running(client, db, monkeypatch):
+    monkeypatch.setattr(
+        "backend.app.tasks.ml.train_heads.delay", lambda *a, **k: None
+    )
+    db.add(HeadTrainingRun(params={}, status="running"))
+    await db.flush()
+    await db.commit()
+    resp = await client.post("/api/heads/train", json={})
+    assert resp.status_code == 409
+    body = await resp.get_json()
+    assert body["error"] == "training_already_running"
+
+
+@pytest.mark.asyncio
+async def test_status_summary(client, db):
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    db.add(TagHead(
+        tag_id=tag.id, embedding_version=await _embedder_version(db),
+        weights=[0.0] * 1152, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=0.9, n_pos=30, n_neg=90,
+        ap=0.88, precision_cv=0.95, recall=0.7,
+    ))
+    await db.commit()
+    resp = await client.get("/api/heads")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["head_count"] == 1
+    assert body["graduated_count"] == 1          # auto_apply_threshold set
+    assert body["running_id"] is None
+    h = next(x for x in body["heads"] if x["name"] == "glasses")
+    assert h["auto_apply"] is True and h["n_pos"] == 30
+
+
+@pytest.mark.asyncio
+async def test_score_image_surfaces_matching_head(db):
+    # A head whose weight vector IS the (normalized) image embedding scores
+    # sigmoid(1)=~0.73 >= 0.5 → surfaced. A second image orthogonal to it isn't.
+    emb = [0.0] * 1152
+    emb[0] = 3.0  # ||emb|| = 3 → x̂ = e0
+    img = await _img_with_embedding(db, "a" * 64, emb)
+    other = [0.0] * 1152
+    other[1] = 5.0
+    img2 = await _img_with_embedding(db, "b" * 64, other)
+
+    tag = await TagService(db).find_or_create("cat", TagKind.general)
+    weights = [0.0] * 1152
+    weights[0] = 1.0  # unit vector along e0 == x̂ of img
+    db.add(TagHead(
+        tag_id=tag.id, embedding_version=await _embedder_version(db),
+        weights=weights, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+    await db.commit()
+
+    hits = await score_image(db, img.id)
+    assert len(hits) == 1
+    assert hits[0]["tag_id"] == tag.id
+    assert hits[0]["category"] == "general"
+    assert hits[0]["score"] == pytest.approx(1 / (1 + math.exp(-1.0)), abs=1e-3)
+
+    # Orthogonal image: w·x̂ = 0 → sigmoid(0)=0.5; not > threshold strictly? It's
+    # == 0.5 so it passes >=; assert it's at the boundary rather than surfaced
+    # high. (Kept distinct from img's clear hit.)
+    hits2 = await score_image(db, img2.id)
+    assert all(h["score"] <= 0.5 for h in hits2)

tests/test_api_suggestions.py

@@ -1,7 +1,8 @@
 import pytest
+from sqlalchemy import select
 
 from backend.app.celery_app import celery
-from backend.app.models import ImageRecord, TagKind
+from backend.app.models import ImageRecord, MLSettings, TagHead, TagKind
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
@@ -31,13 +32,30 @@ async def _img(db, preds, sha="s" * 64):
 
 @pytest.mark.asyncio
 async def test_get_suggestions(client, db):
-    img = await _img(
-        db, {"sword": {"category": "general", "confidence": 0.97}}
+    # Suggestions come from a trained head now (Camie/centroid removed): an image
+    # whose embedding aligns with the head surfaces that concept.
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    img = ImageRecord(
+        path="/images/headsug.jpg", sha256="h" * 64, size_bytes=1,
+        mime="image/jpeg", width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=[3.0] + [0.0] * 1151,
     )
+    db.add(img)
+    await db.flush()
+    tag = await TagService(db).find_or_create("sword", TagKind.general)
+    db.add(TagHead(
+        tag_id=tag.id, embedding_version=s.embedder_model_version,
+        weights=[1.0] + [0.0] * 1151, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+    await db.commit()
     resp = await client.get(f"/api/images/{img.id}/suggestions")
     assert resp.status_code == 200
     body = await resp.get_json()
-    assert "general" in body["by_category"]
+    general = body["by_category"].get("general", [])
+    s2 = next(x for x in general if x["canonical_tag_id"] == tag.id)
+    assert s2["source"] == "head"
 
 
 @pytest.mark.asyncio
@@ -95,6 +113,25 @@ async def test_dismiss(client, db):
     assert resp.status_code == 204
 
 
+@pytest.mark.asyncio
+async def test_undismiss_reverses_rejection(client, db):
+    img = await _img(db, {})
+    tag = await TagService(db).find_or_create("UndismissMe", TagKind.general)
+    await db.commit()
+    await client.post(
+        f"/api/images/{img.id}/suggestions/dismiss", json={"tag_id": tag.id}
+    )
+    resp = await client.post(
+        f"/api/images/{img.id}/suggestions/undismiss", json={"tag_id": tag.id}
+    )
+    assert resp.status_code == 204
+    # Idempotent: un-rejecting again (nothing to clear) is still a 204.
+    resp2 = await client.post(
+        f"/api/images/{img.id}/suggestions/undismiss", json={"tag_id": tag.id}
+    )
+    assert resp2.status_code == 204
+
+
 @pytest.mark.asyncio
 async def test_alias_requires_fields(client, db):
     img = await _img(db, {})
@@ -102,67 +139,3 @@ async def test_alias_requires_fields(client, db):
         f"/api/images/{img.id}/suggestions/alias", json={"alias_string": "x"}
     )
     assert resp.status_code == 400
-
-
-async def _img_at(db, path, sha, preds):
-    from tests._prediction_helpers import seed_predictions
-
-    img = ImageRecord(
-        path=path, sha256=sha, size_bytes=1, mime="image/jpeg",
-        width=1, height=1, origin="imported_filesystem",
-        integrity_status="unknown",
-    )
-    db.add(img)
-    await db.commit()
-    await seed_predictions(db, img.id, preds)
-    await db.commit()
-    return img
-
-
-@pytest.mark.asyncio
-async def test_alias_roundtrip_resolves_by_raw_key(client, db):
-    """Locks the modal-alias contract: the suggestion exposes the RAW model key,
-    an alias authored with that key resolves on a later image, and the resolved
-    suggestion is flagged via_alias. (Pre-fix the modal stored the normalized
-    display name, which never resolved.)"""
-    canonical = await TagService(db).find_or_create(
-        "Sasuke Uchiha", TagKind.character
-    )
-    await db.commit()
-    preds = {"uchiha_sasuke": {"category": "character", "confidence": 0.99}}
-    img_a = await _img_at(db, "/images/alias_a.jpg", "a" * 64, preds)
-
-    # (a) raw_name is exposed so the modal can author the alias with it; the
-    # raw prediction doesn't textually match the tag, so it'd otherwise be +new.
-    body = await (
-        await client.get(f"/api/images/{img_a.id}/suggestions")
-    ).get_json()
-    sug = body["by_category"]["character"][0]
-    assert sug["raw_name"] == "uchiha_sasuke"
-    assert sug["via_alias"] is False
-    assert sug["creates_new_tag"] is True
-
-    # Author the alias keyed by the RAW key (what the frontend now sends).
-    resp = await client.post(
-        f"/api/images/{img_a.id}/suggestions/alias",
-        json={
-            "alias_string": sug["raw_name"],
-            "alias_category": "character",
-            "canonical_tag_id": canonical.id,
-        },
-    )
-    assert resp.status_code == 200
-    assert (await resp.get_json())["allowlisted"] is True
-
-    # (b) A DIFFERENT image with the same prediction now resolves via the alias
-    # (image A's tag is applied, so it's filtered there). Had the alias been
-    # stored under the display name, this would NOT resolve.
-    img_b = await _img_at(db, "/images/alias_b.jpg", "b" * 64, preds)
-    body_b = await (
-        await client.get(f"/api/images/{img_b.id}/suggestions")
-    ).get_json()
-    sug_b = body_b["by_category"]["character"][0]
-    assert sug_b["canonical_tag_id"] == canonical.id
-    assert sug_b["via_alias"] is True
-    assert sug_b["creates_new_tag"] is False
-    assert sug_b["raw_name"] == "uchiha_sasuke"

tests/test_ccip.py

@@ -0,0 +1,143 @@
+"""CCIP few-shot character matcher (#114). numpy cosine on stored vectors — no
+model needed, so it runs in CI with synthetic CCIP vectors."""
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import ImageRecord, ImageRegion, TagKind
+from backend.app.models.tag import image_tag
+from backend.app.services.ml.ccip import match_image
+from backend.app.services.tag_service import TagService
+
+pytestmark = pytest.mark.integration
+
+
+def _ccip(slot: int) -> list[float]:
+    v = [0.0] * 768
+    v[slot] = 1.0
+    return v
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+async def _figure(db, image_id, ccip):
+    db.add(ImageRegion(
+        image_record_id=image_id, kind="figure",
+        rx=0.0, ry=0.0, rw=1.0, rh=1.0,
+        ccip_embedding=ccip, embedding_version="ccip-test",
+    ))
+
+
+async def _tag_image(db, image_id, tag_id):
+    await db.execute(image_tag.insert().values(
+        image_record_id=image_id, tag_id=tag_id, source="manual",
+    ))
+
+
+@pytest.mark.asyncio
+async def test_matches_same_character_across_images(db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "a" * 64)               # a tagged example = a prototype
+    await _figure(db, ref.id, _ccip(0))
+    await _tag_image(db, ref.id, raven.id)
+    query = await _img(db, "b" * 64)             # untagged, near-identical figure
+    await _figure(db, query.id, _ccip(0))
+    await db.commit()
+
+    matches = await match_image(db, query.id)
+    m = next(x for x in matches if x["tag_id"] == raven.id)
+    assert m["source"] == "ccip" and m["category"] == "character"
+    assert m["score"] > 0.9
+
+
+@pytest.mark.asyncio
+async def test_no_match_for_different_character(db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "c" * 64)
+    await _figure(db, ref.id, _ccip(0))
+    await _tag_image(db, ref.id, raven.id)
+    query = await _img(db, "d" * 64)
+    await _figure(db, query.id, _ccip(5))        # orthogonal → not Raven
+    await db.commit()
+    assert await match_image(db, query.id) == []
+
+
+@pytest.mark.asyncio
+async def test_excludes_already_applied_character(db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "e" * 64)
+    await _figure(db, ref.id, _ccip(0))
+    await _tag_image(db, ref.id, raven.id)
+    query = await _img(db, "f" * 64)
+    await _figure(db, query.id, _ccip(0))
+    await _tag_image(db, query.id, raven.id)     # already tagged → no re-suggest
+    await db.commit()
+    assert all(m["tag_id"] != raven.id for m in await match_image(db, query.id))
+
+
+@pytest.mark.asyncio
+async def test_no_figure_vectors_means_no_match(db):
+    query = await _img(db, "g" * 64)
+    await db.commit()
+    assert await match_image(db, query.id) == []
+
+
+@pytest.mark.asyncio
+async def test_threshold_gates_borderline_match(db):
+    # A figure ~0.9 cosine from the reference: matched at 0.85, dropped at 0.95.
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "h" * 64)
+    await _figure(db, ref.id, _ccip(0))                 # e0
+    await _tag_image(db, ref.id, raven.id)
+    near = [0.0] * 768
+    near[0], near[1] = 0.9, 0.4359                       # |·|=1, cos(e0)=0.9
+    query = await _img(db, "i" * 64)
+    await _figure(db, query.id, near)
+    await db.commit()
+
+    assert any(m["tag_id"] == raven.id for m in await match_image(db, query.id, 0.85))
+    assert await match_image(db, query.id, 0.95) == []
+
+
+@pytest.mark.asyncio
+async def test_multi_character_image_not_used_as_reference(db):
+    # A figure on a 2-character image is ambiguous (tag is image-level), so it
+    # must NOT seed either character's prototypes — else it'd match both.
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    daphne = await TagService(db).find_or_create("Daphne", TagKind.character)
+    multi = await _img(db, "j" * 64)
+    await _figure(db, multi.id, _ccip(0))
+    await _tag_image(db, multi.id, raven.id)
+    await _tag_image(db, multi.id, daphne.id)
+    query = await _img(db, "k" * 64)
+    await _figure(db, query.id, _ccip(0))            # identical to the ambiguous figure
+    await db.commit()
+    assert await match_image(db, query.id) == []     # no clean references → nothing
+
+
+@pytest.mark.asyncio
+async def test_auto_apply_tags_confident_match(db):
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "l" * 64)
+    await _figure(db, ref.id, _ccip(0))
+    await _tag_image(db, ref.id, raven.id)           # single-character reference
+    query = await _img(db, "m" * 64)
+    await _figure(db, query.id, _ccip(0))            # identical → cosine 1.0
+    await db.commit()
+
+    from backend.app.tasks.ml import scheduled_ccip_auto_apply
+    assert "applied=" in scheduled_ccip_auto_apply()   # sync task, own session
+
+    rows = (await db.execute(
+        select(image_tag.c.tag_id, image_tag.c.source).where(
+            image_tag.c.image_record_id == query.id
+        )
+    )).all()
+    assert (raven.id, "ccip_auto") in [(t, s) for t, s in rows]

tests/test_crops.py

@@ -0,0 +1,44 @@
+"""Shared crop primitive (#114) — pure Pillow, no DB, so it runs in the fast
+unit lane (no integration marker)."""
+from PIL import Image
+
+from backend.app.services.ml.crops import crop_region
+
+
+def _quadrant_img():
+    """400x400 red with a blue bottom-right quadrant, so a crop's content is
+    checkable by pixel."""
+    img = Image.new("RGB", (400, 400), (255, 0, 0))
+    img.paste(Image.new("RGB", (200, 200), (0, 0, 255)), (200, 200))
+    return img
+
+
+def test_crop_returns_region_pixels():
+    crop = crop_region(_quadrant_img(), (0.5, 0.5, 0.5, 0.5))
+    assert crop is not None
+    assert crop.size == (200, 200)
+    assert crop.getpixel((100, 100)) == (0, 0, 255)   # the blue quadrant
+
+
+def test_crop_below_floor_is_rejected():
+    # 0.05 * 400 = 20px on a side — below max(64, 0.10*400=40) → None.
+    assert crop_region(_quadrant_img(), (0.0, 0.0, 0.05, 0.05)) is None
+
+
+def test_crop_clamped_to_image_bounds():
+    # Box runs off the right/bottom edge; clamps to the remaining 0.2*400=80px.
+    crop = crop_region(_quadrant_img(), (0.8, 0.8, 0.5, 0.5))
+    assert crop is not None
+    assert crop.size == (80, 80)
+
+
+def test_pad_expands_the_crop():
+    base = crop_region(_quadrant_img(), (0.4, 0.4, 0.2, 0.2))
+    padded = crop_region(_quadrant_img(), (0.4, 0.4, 0.2, 0.2), pad=0.5)
+    assert base.size == (80, 80)
+    assert padded.size[0] > base.size[0] and padded.size[1] > base.size[1]
+
+
+def test_out_size_resizes_square():
+    crop = crop_region(_quadrant_img(), (0.25, 0.25, 0.5, 0.5), out_size=224)
+    assert crop.size == (224, 224)

tests/test_gpu_jobs.py

@@ -0,0 +1,197 @@
+"""GPU-job queue engine (#114): enqueue dedupe + lease/heartbeat/complete/fail."""
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from sqlalchemy import func, select
+
+from backend.app.models import GpuJob, ImageRecord, ImageRegion
+from backend.app.services.ml.gpu_jobs import GpuJobService
+
+pytestmark = pytest.mark.integration
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+@pytest.mark.asyncio
+async def test_enqueue_siglip_backfill_gates_on_concept_region(db):
+    # 'siglip' backfill enqueues images that lack a concept region (the
+    # back-catalogue) and skips ones that already have one — and never double-
+    # enqueues an image that already has a pending siglip job.
+    from backend.app.tasks.ml import enqueue_gpu_backfill
+
+    need = await _img(db, "e1" * 32)          # no concept region → wants one
+    have = await _img(db, "e2" * 32)          # already embedded → skip
+    db.add(ImageRegion(
+        image_record_id=have.id, kind="concept", rx=0.0, ry=0.0, rw=1.0, rh=1.0,
+        siglip_embedding=[0.0] * 1152, embedding_version="siglip-test",
+    ))
+    await db.commit()
+
+    assert enqueue_gpu_backfill("siglip") >= 1
+
+    queued = {
+        j.image_record_id for j in (
+            await db.execute(select(GpuJob).where(GpuJob.task == "siglip"))
+        ).scalars()
+    }
+    assert need.id in queued
+    assert have.id not in queued
+
+    # Idempotent: the now-pending job means a second run doesn't re-enqueue it.
+    enqueue_gpu_backfill("siglip")
+    n_for_need = (
+        await db.execute(
+            select(func.count()).select_from(GpuJob).where(
+                GpuJob.task == "siglip", GpuJob.image_record_id == need.id
+            )
+        )
+    ).scalar_one()
+    assert n_for_need == 1
+
+
+@pytest.mark.asyncio
+async def test_enqueue_dedupes_same_pair(db):
+    img = await _img(db, "a" * 64)
+    svc = GpuJobService(db)
+    first = await svc.enqueue(img.id, "ccip")
+    dup = await svc.enqueue(img.id, "ccip")
+    other = await svc.enqueue(img.id, "siglip_region")
+    await db.commit()
+    assert first is not None
+    assert dup is None              # same (image, task) already queued
+    assert other is not None        # different task is fine
+
+
+@pytest.mark.asyncio
+async def test_lease_claims_then_skips_when_held(db):
+    img = await _img(db, "b" * 64)
+    svc = GpuJobService(db)
+    await svc.enqueue(img.id, "ccip")
+    await db.commit()
+
+    leased = await svc.lease("agent-1", batch_size=8)
+    await db.commit()
+    assert len(leased) == 1
+    assert leased[0].status == "leased" and leased[0].lease_token == "agent-1"
+    assert leased[0].attempts == 1
+
+    # Already leased + not expired → a second agent gets nothing.
+    again = await svc.lease("agent-2", batch_size=8)
+    await db.commit()
+    assert again == []
+
+
+@pytest.mark.asyncio
+async def test_expired_lease_is_reclaimed(db):
+    img = await _img(db, "c" * 64)
+    svc = GpuJobService(db)
+    job = await svc.enqueue(img.id, "ccip")
+    await db.commit()
+    # Force the lease into the past.
+    job.status = "leased"
+    job.lease_token = "dead-agent"
+    job.lease_expires_at = datetime.now(UTC) - timedelta(minutes=10)
+    await db.commit()
+
+    leased = await svc.lease("agent-2", batch_size=8)
+    await db.commit()
+    assert len(leased) == 1
+    assert leased[0].lease_token == "agent-2"
+    assert leased[0].attempts == 1   # re-lease incremented from 0 (was set directly)
+
+
+@pytest.mark.asyncio
+async def test_heartbeat_extends_only_own_lease(db):
+    img = await _img(db, "d" * 64)
+    svc = GpuJobService(db)
+    await svc.enqueue(img.id, "ccip")
+    await db.commit()
+    job = (await svc.lease("agent-1"))[0]
+    await db.commit()
+
+    assert await svc.heartbeat("agent-1", [job.id]) == 1
+    assert await svc.heartbeat("someone-else", [job.id]) == 0
+
+
+@pytest.mark.asyncio
+async def test_complete_closes_job(db):
+    img = await _img(db, "e" * 64)
+    svc = GpuJobService(db)
+    await svc.enqueue(img.id, "ccip")
+    await db.commit()
+    job = (await svc.lease("agent-1"))[0]
+    await db.commit()
+
+    assert await svc.complete("wrong-token", job.id) is False
+    assert await svc.complete("agent-1", job.id) is True
+    await db.commit()
+    fresh = await db.get(GpuJob, job.id)
+    assert fresh.status == "done" and fresh.lease_token is None
+
+
+@pytest.mark.asyncio
+async def test_fail_requeues_until_cap(db):
+    img = await _img(db, "f" * 64)
+    svc = GpuJobService(db)
+    await svc.enqueue(img.id, "ccip")
+    await db.commit()
+    job = (await svc.lease("agent-1"))[0]   # attempts -> 1
+    await db.commit()
+    # Under the cap → back to pending for a retry.
+    assert await svc.fail("agent-1", job.id, "boom") is True
+    await db.commit()
+    assert (await db.get(GpuJob, job.id)).status == "pending"
+
+    # At the attempt cap → terminal 'error'.
+    j = await db.get(GpuJob, job.id)
+    j.attempts = 3
+    j.status = "leased"
+    j.lease_token = "agent-1"
+    j.lease_expires_at = datetime.now(UTC) + timedelta(minutes=5)
+    await db.commit()
+    assert await svc.fail("agent-1", job.id, "boom again") is True
+    await db.commit()
+    assert (await db.get(GpuJob, job.id)).status == "error"
+
+
+@pytest.mark.asyncio
+async def test_release_returns_to_pending(db):
+    img = await _img(db, "01" + "a" * 62)
+    svc = GpuJobService(db)
+    await svc.enqueue(img.id, "ccip")
+    await db.commit()
+    job = (await svc.lease("agent-1"))[0]
+    await db.commit()
+
+    assert await svc.release("other", [job.id]) == 0      # not this token's lease
+    assert await svc.release("agent-1", [job.id]) == 1     # graceful hand-back
+    await db.commit()
+    fresh = await db.get(GpuJob, job.id)
+    assert fresh.status == "pending" and fresh.lease_token is None
+
+
+@pytest.mark.asyncio
+async def test_recover_orphaned_resets_only_expired(db):
+    img1 = await _img(db, "02" + "a" * 62)
+    img2 = await _img(db, "03" + "a" * 62)
+    svc = GpuJobService(db)
+    await svc.enqueue(img1.id, "ccip")
+    await svc.enqueue(img2.id, "ccip")
+    await db.commit()
+    expired, fresh = await svc.lease("dead", batch_size=2)
+    # One lease is in the past (orphaned), the other still valid.
+    expired.lease_expires_at = datetime.now(UTC) - timedelta(minutes=10)
+    await db.commit()
+
+    assert await svc.recover_orphaned() == 1
+    await db.commit()
+    assert (await db.get(GpuJob, expired.id)).status == "pending"
+    assert (await db.get(GpuJob, fresh.id)).status == "leased"   # untouched

tests/test_head_auto_apply.py

@@ -0,0 +1,150 @@
+"""Earned auto-apply (#114). The sweep is numpy-only (no scikit-learn), so the
+apply logic is tested directly via the sync session; the API guards (disabled /
+dry-run / conflict) via the async client."""
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import (
+    HeadAutoApplyRun,
+    ImageRecord,
+    MLSettings,
+    Tag,
+    TagHead,
+    TagKind,
+)
+from backend.app.models.tag import image_tag
+from backend.app.services.ml.heads import auto_apply_sweep
+
+pytestmark = pytest.mark.integration
+
+
+def _emb(slot: int) -> list[float]:
+    v = [0.0] * 1152
+    v[slot] = 3.0
+    return v
+
+
+def _img(db, sha: str, emb) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=emb,
+    )
+    db.add(img)
+    db.flush()
+    return img
+
+
+def _head(db, tag_id: int, slot: int, *, threshold=0.5, n_pos=30):
+    s = db.execute(select(MLSettings).where(MLSettings.id == 1)).scalar_one()
+    w = [0.0] * 1152
+    w[slot] = 1.0
+    db.add(TagHead(
+        tag_id=tag_id, embedding_version=s.embedder_model_version,
+        weights=w, bias=0.0, suggest_threshold=0.5, auto_apply_threshold=threshold,
+        n_pos=n_pos, n_neg=90, ap=0.9, precision_cv=0.98, recall=0.7,
+    ))
+
+
+def _run(db, dry_run=False) -> HeadAutoApplyRun:
+    run = HeadAutoApplyRun(dry_run=dry_run, params={"dry_run": dry_run}, status="running")
+    db.add(run)
+    db.flush()
+    return run
+
+
+def _applied_source(db, image_id, tag_id):
+    return db.execute(
+        select(image_tag.c.source)
+        .where(image_tag.c.image_record_id == image_id)
+        .where(image_tag.c.tag_id == tag_id)
+    ).scalar_one_or_none()
+
+
+def test_sweep_applies_to_matching_image(db_sync):
+    img = _img(db_sync, "a" * 64, _emb(0))
+    tag = Tag(name="autotag", kind=TagKind.general)
+    db_sync.add(tag)
+    db_sync.flush()
+    _head(db_sync, tag.id, 0)
+    run = _run(db_sync)
+    db_sync.commit()
+    result = auto_apply_sweep(db_sync, run, dry_run=False)
+    assert result["n_applied"] == 1
+    assert _applied_source(db_sync, img.id, tag.id) == "head_auto"
+
+
+def test_sweep_dry_run_counts_but_writes_nothing(db_sync):
+    img = _img(db_sync, "b" * 64, _emb(0))
+    tag = Tag(name="previewtag", kind=TagKind.general)
+    db_sync.add(tag)
+    db_sync.flush()
+    _head(db_sync, tag.id, 0)
+    run = _run(db_sync, dry_run=True)
+    db_sync.commit()
+    result = auto_apply_sweep(db_sync, run, dry_run=True)
+    assert result["n_applied"] == 1                      # it WOULD apply
+    assert _applied_source(db_sync, img.id, tag.id) is None  # but wrote nothing
+
+
+def test_sweep_skips_under_supported_head(db_sync):
+    # n_pos below head_auto_apply_min_positives (default 30) → a precise-looking
+    # but under-supported head never fires.
+    img = _img(db_sync, "c" * 64, _emb(0))
+    tag = Tag(name="weaktag", kind=TagKind.general)
+    db_sync.add(tag)
+    db_sync.flush()
+    _head(db_sync, tag.id, 0, n_pos=5)
+    run = _run(db_sync)
+    db_sync.commit()
+    result = auto_apply_sweep(db_sync, run, dry_run=False)
+    assert result["n_applied"] == 0
+    assert _applied_source(db_sync, img.id, tag.id) is None
+
+
+def test_sweep_skips_ungraduated_head(db_sync):
+    # auto_apply_threshold is None (head never reached the precision bar).
+    _img(db_sync, "d" * 64, _emb(0))
+    tag = Tag(name="nograd", kind=TagKind.general)
+    db_sync.add(tag)
+    db_sync.flush()
+    _head(db_sync, tag.id, 0, threshold=None)
+    run = _run(db_sync)
+    db_sync.commit()
+    result = auto_apply_sweep(db_sync, run, dry_run=False)
+    assert result["n_applied"] == 0
+
+
+@pytest.mark.asyncio
+async def test_auto_apply_disabled_blocks_real_run(client, db):
+    # With the master switch OFF, a real sweep is refused (400). (It defaults ON
+    # now — opt-out — so the test disables it explicitly to exercise this path.)
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    s.head_auto_apply_enabled = False
+    await db.commit()
+    resp = await client.post("/api/heads/auto-apply", json={"dry_run": False})
+    assert resp.status_code == 400
+    assert (await resp.get_json())["error"] == "auto_apply_disabled"
+
+
+@pytest.mark.asyncio
+async def test_auto_apply_dry_run_allowed_when_disabled(client, db, monkeypatch):
+    monkeypatch.setattr(
+        "backend.app.tasks.ml.apply_head_tags.delay", lambda *a, **k: None
+    )
+    resp = await client.post("/api/heads/auto-apply", json={"dry_run": True})
+    assert resp.status_code == 202
+    assert (await resp.get_json())["status"] == "running"
+
+
+@pytest.mark.asyncio
+async def test_auto_apply_conflict_when_one_running(client, db, monkeypatch):
+    monkeypatch.setattr(
+        "backend.app.tasks.ml.apply_head_tags.delay", lambda *a, **k: None
+    )
+    db.add(HeadAutoApplyRun(dry_run=True, params={}, status="running"))
+    await db.flush()
+    await db.commit()
+    resp = await client.post("/api/heads/auto-apply", json={"dry_run": True})
+    assert resp.status_code == 409
+    assert (await resp.get_json())["error"] == "auto_apply_already_running"

tests/test_head_metrics.py

@@ -0,0 +1,107 @@
+"""Auto-apply observability (#114): misfire/under-fire counters captured on
+operator corrections, the daily snapshot time-series, and the metrics API."""
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import HeadMetric, HeadMetricsSnapshot, ImageRecord, TagHead, TagKind
+from backend.app.models.tag import image_tag
+from backend.app.services.tag_service import TagService
+
+pytestmark = pytest.mark.integration
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+def _head(tag_id):
+    return TagHead(
+        tag_id=tag_id, embedding_version="siglip-test", weights=[0.0] * 1152,
+        bias=0.0, suggest_threshold=0.5, auto_apply_threshold=0.6,
+        n_pos=30, n_neg=90, ap=0.9, precision_cv=0.95, recall=0.7,
+    )
+
+
+@pytest.mark.asyncio
+async def test_removing_head_auto_tag_counts_misfire(db):
+    img = await _img(db, "a" * 64)
+    tag = await TagService(db).find_or_create("misfire", TagKind.general)
+    await db.execute(image_tag.insert().values(
+        image_record_id=img.id, tag_id=tag.id, source="head_auto",
+    ))
+    await db.commit()
+    await TagService(db).remove_from_image(img.id, tag.id)
+    await db.commit()
+    m = await db.get(HeadMetric, tag.id)
+    assert m is not None and m.n_misfires == 1 and m.n_underfires == 0
+
+
+@pytest.mark.asyncio
+async def test_removing_manual_tag_is_not_a_misfire(db):
+    img = await _img(db, "b" * 64)
+    tag = await TagService(db).find_or_create("manualrm", TagKind.general)
+    await db.execute(image_tag.insert().values(
+        image_record_id=img.id, tag_id=tag.id, source="manual",
+    ))
+    await db.commit()
+    await TagService(db).remove_from_image(img.id, tag.id)
+    await db.commit()
+    assert await db.get(HeadMetric, tag.id) is None
+
+
+@pytest.mark.asyncio
+async def test_manual_add_with_head_counts_underfire(db):
+    img = await _img(db, "c" * 64)
+    tag = await TagService(db).find_or_create("underfire", TagKind.general)
+    db.add(_head(tag.id))
+    await db.commit()
+    await TagService(db).add_to_image(img.id, tag.id, source="manual")
+    await db.commit()
+    m = await db.get(HeadMetric, tag.id)
+    assert m is not None and m.n_underfires == 1
+
+
+@pytest.mark.asyncio
+async def test_manual_add_without_head_no_underfire(db):
+    img = await _img(db, "d" * 64)
+    tag = await TagService(db).find_or_create("nohead", TagKind.general)
+    await db.commit()
+    await TagService(db).add_to_image(img.id, tag.id, source="manual")
+    await db.commit()
+    assert await db.get(HeadMetric, tag.id) is None
+
+
+@pytest.mark.asyncio
+async def test_snapshot_records_timeseries_point(db):
+    tag = await TagService(db).find_or_create("snap", TagKind.general)
+    db.add(_head(tag.id))
+    await db.commit()
+    from backend.app.tasks.maintenance import snapshot_head_metrics
+
+    n = snapshot_head_metrics()   # sync task, own session
+    assert n >= 1
+    snaps = (await db.execute(
+        select(HeadMetricsSnapshot).where(HeadMetricsSnapshot.tag_id == tag.id)
+    )).scalars().all()
+    assert len(snaps) == 1
+    assert snaps[0].name == "snap"
+
+
+@pytest.mark.asyncio
+async def test_metrics_api_returns_concept(client, db):
+    tag = await TagService(db).find_or_create("apimetric", TagKind.general)
+    db.add(_head(tag.id))
+    await db.commit()
+    resp = await client.get("/api/heads/metrics")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    c = next(x for x in body["concepts"] if x["name"] == "apimetric")
+    assert c["auto_apply"] is True
+    assert c["n_misfires"] == 0
+    assert "snapshots" in body

tests/test_ml_artist_retired.py

@@ -14,14 +14,12 @@ def test_artist_not_centroid_eligible():
     assert TagKind.artist not in ELIGIBLE_KINDS
 
 
-def test_threshold_for_artist_is_unsurfaced():
-    from backend.app.services.ml.suggestions import SuggestionService
+def test_artist_not_head_eligible():
+    # Tagging-v2: suggestions come from heads, and heads are only trained for
+    # general/character concepts — so 'artist' (and any other kind) can't surface.
+    from backend.app.models import TagKind
+    from backend.app.services.ml.heads import _HEAD_KINDS
 
-    class _S:
-        suggestion_threshold_character = 0.5
-        suggestion_threshold_general = 0.5
-
-    svc = SuggestionService.__new__(SuggestionService)
-    # 'artist' and 'copyright' both retired — fall through to 1.01
-    assert svc._threshold_for(_S(), "artist") == 1.01
-    assert svc._threshold_for(_S(), "copyright") == 1.01
+    assert TagKind.general in _HEAD_KINDS
+    assert TagKind.character in _HEAD_KINDS
+    assert TagKind.artist not in _HEAD_KINDS

tests/test_ml_suggestions.py

@@ -1,149 +1,199 @@
+"""Suggestion read-path (tagging-v2): suggestions come from trained HEADS, not
+Camie predictions or centroids. Heads are inserted directly (training needs
+scikit-learn, ml image only); scoring is numpy-only (available via pgvector)."""
 import pytest
+from sqlalchemy import select
 
-from backend.app.models import ImageRecord, TagKind
+from backend.app.models import ImageRecord, ImageRegion, MLSettings, TagHead, TagKind
 from backend.app.models.tag import image_tag
-from backend.app.services.ml.aliases import AliasService
+from backend.app.services.ml.allowlist import AllowlistService
 from backend.app.services.ml.suggestions import SuggestionService
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
 
 
-def _img(sha: str) -> ImageRecord:
-    return ImageRecord(
-        path=f"/images/{sha}.jpg",
-        sha256=sha,
-        size_bytes=1,
-        mime="image/jpeg",
-        width=1,
-        height=1,
-        origin="imported_filesystem",
-        integrity_status="unknown",
+def _emb(slot: int, val: float = 3.0) -> list[float]:
+    """An embedding pointing along axis `slot` (so its L2-normalized form is the
+    unit vector e_slot — a head with weights e_slot scores it sigmoid(1)≈0.73)."""
+    v = [0.0] * 1152
+    v[slot] = val
+    return v
+
+
+async def _img(db, sha: str, emb=None) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=emb,
     )
-
-
-async def _seed_img(db, sha: str, predictions: dict) -> ImageRecord:
-    """#768: create an image + seed its predictions into image_prediction
-    (the read path's source), returning the flushed record."""
-    from tests._prediction_helpers import seed_predictions
-
-    img = _img(sha)
     db.add(img)
     await db.flush()
-    await seed_predictions(db, img.id, predictions)
     return img
 
 
+async def _embver(db) -> str:
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    return s.embedder_model_version
+
+
+async def _head(db, tag_id: int, slot: int, suggest_threshold: float = 0.5):
+    weights = [0.0] * 1152
+    weights[slot] = 1.0
+    db.add(TagHead(
+        tag_id=tag_id, embedding_version=await _embver(db),
+        weights=weights, bias=0.0, suggest_threshold=suggest_threshold,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+
+
 @pytest.mark.asyncio
-async def test_threshold_filters_low_confidence_general(db):
-    # Default general threshold is 0.50 (alembic 0029 lowered it from
-    # 0.95). Use 0.30/0.60 to keep the test asserting threshold behavior
-    # rather than the exact cutoff number.
-    img = await _seed_img(
-        db,
-        "a" * 64,
-        {
-            "lowconf": {"category": "general", "confidence": 0.30},
-            "sword": {"category": "general", "confidence": 0.97},
-        },
-    )
+async def test_head_suggestion_surfaces_for_matching_image(db):
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    img = await _img(db, "a" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+
     sl = await SuggestionService(db).for_image(img.id)
-    names = [s.display_name for s in sl.by_category.get("general", [])]
-    # display_name is normalized (tag_name.normalize) before surfacing.
-    assert "Sword" in names
-    assert "Lowconf" not in names
+    general = sl.by_category["general"]
+    assert len(general) == 1
+    s = general[0]
+    assert s.canonical_tag_id == tag.id
+    assert s.source == "head"
+    assert s.creates_new_tag is False
+    assert s.via_alias is False and s.raw_name is None
+    assert s.score > 0.5
 
 
 @pytest.mark.asyncio
-async def test_threshold_override_surfaces_low_confidence(db):
-    # The typed-dropdown "show everything the model saw" mode: threshold_override
-    # surfaces stored predictions below the configured threshold (in canonical
-    # formatting) so they can be picked instead of hand-typed (2026-06-09).
-    img = await _seed_img(
-        db,
-        "d" * 64,
-        {
-            "lowconf": {"category": "general", "confidence": 0.30},
-            "sword": {"category": "general", "confidence": 0.97},
-        },
-    )
-    sl = await SuggestionService(db).for_image(img.id, threshold_override=0.0)
-    names = [s.display_name for s in sl.by_category.get("general", [])]
-    assert "Sword" in names
-    assert "Lowconf" in names  # below the configured threshold, surfaced anyway
-
-    # Unsurfaced categories are still excluded even with the override.
-    img2 = await _seed_img(
-        db, "e" * 64, {"safe": {"category": "rating", "confidence": 0.99}}
-    )
-    sl2 = await SuggestionService(db).for_image(img2.id, threshold_override=0.0)
-    assert "rating" not in sl2.by_category
+async def test_no_embedding_means_no_suggestions(db):
+    img = await _img(db, "b" * 64, None)
+    tag = await TagService(db).find_or_create("cat", TagKind.general)
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+    assert (await SuggestionService(db).for_image(img.id)).by_category == {}
 
 
 @pytest.mark.asyncio
-async def test_unsurfaced_category_dropped(db):
-    img = await _seed_img(
-        db,
-        "b" * 64,
-        {"safe": {"category": "rating", "confidence": 0.99}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    assert "rating" not in sl.by_category
-
-
-@pytest.mark.asyncio
-async def test_alias_resolution(db):
-    tags = TagService(db)
-    canonical = await tags.find_or_create("Sasuke Uchiha", TagKind.character)
-    await AliasService(db).create("uchiha_sasuke", "character", canonical.id)
-    img = await _seed_img(
-        db,
-        "c" * 64,
-        {"uchiha_sasuke": {"category": "character", "confidence": 0.96}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    chars = sl.by_category["character"]
-    assert len(chars) == 1
-    assert chars[0].display_name == "Sasuke Uchiha"
-    assert chars[0].canonical_tag_id == canonical.id
-    assert chars[0].creates_new_tag is False
-    # Surfaced via an alias on the raw model key — the UI marks it + offers undo.
-    assert chars[0].via_alias is True
-    assert chars[0].raw_name == "uchiha_sasuke"
-
-
-@pytest.mark.asyncio
-async def test_raw_tag_creates_new(db):
-    img = await _seed_img(
-        db,
-        "d" * 64,
-        {"brand_new_tag": {"category": "character", "confidence": 0.96}},
-    )
-    sl = await SuggestionService(db).for_image(img.id)
-    chars = sl.by_category["character"]
-    # display_name is the normalized Camie name (underscores -> spaces,
-    # title-cased), not the raw vocab key.
-    assert chars[0].display_name == "Brand New Tag"
-    assert chars[0].creates_new_tag is True
-    # Not aliased, but the raw key is carried so the modal can author one.
-    assert chars[0].via_alias is False
-    assert chars[0].raw_name == "brand_new_tag"
-    assert chars[0].canonical_tag_id is None
+async def test_no_heads_means_no_suggestions(db):
+    img = await _img(db, "c" * 64, _emb(0))
+    await db.commit()  # no heads trained yet
+    assert (await SuggestionService(db).for_image(img.id)).by_category == {}
 
 
 @pytest.mark.asyncio
 async def test_applied_tag_not_suggested(db):
-    tags = TagService(db)
-    tag = await tags.find_or_create("alreadyhere", TagKind.character)
-    img = await _seed_img(
-        db,
-        "e" * 64,
-        {"alreadyhere": {"category": "character", "confidence": 0.96}},
-    )
+    tag = await TagService(db).find_or_create("dog", TagKind.general)
+    img = await _img(db, "d" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
     await db.execute(
         image_tag.insert().values(
             image_record_id=img.id, tag_id=tag.id, source="manual"
         )
     )
+    await db.commit()
     sl = await SuggestionService(db).for_image(img.id)
-    assert "character" not in sl.by_category or not sl.by_category["character"]
+    assert "general" not in sl.by_category or not sl.by_category["general"]
+
+
+@pytest.mark.asyncio
+async def test_threshold_override_surfaces_below_cut(db):
+    # A head with a high suggest_threshold won't surface on a so-so score, but
+    # the dropdown's override=0 floor surfaces every head regardless.
+    tag = await TagService(db).find_or_create("horse", TagKind.general)
+    img = await _img(db, "e" * 64, _emb(1))   # orthogonal to the head → score 0.5
+    await _head(db, tag.id, slot=0, suggest_threshold=0.6)
+    await db.commit()
+    svc = SuggestionService(db)
+    assert svc and not (await svc.for_image(img.id)).by_category.get("general")
+    flooded = await svc.for_image(img.id, threshold_override=0.0)
+    assert any(s.canonical_tag_id == tag.id for s in flooded.by_category["general"])
+
+
+@pytest.mark.asyncio
+async def test_concept_region_surfaces_via_max_over_bag(db):
+    # Max-over-bag: the whole-image vector is orthogonal to the head (scores the
+    # 0.5 midpoint, under a 0.7 cut → nothing), but a concept CROP that aligns
+    # with the head lifts the max over the bag above the cut. A small/local
+    # concept surfaces ONLY because of the crop.
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    img = await _img(db, "b1" * 32, _emb(5))      # whole-image ⟂ head
+    await _head(db, tag.id, slot=0, suggest_threshold=0.7)
+    await db.commit()
+    # Whole-image alone: sigmoid(0)=0.5 < 0.7 → no suggestion.
+    assert not (await SuggestionService(db).for_image(img.id)).by_category.get("general")
+
+    # A concept crop aligned with the head, but stamped with a STALE model
+    # version → filtered out of the bag, so still nothing.
+    db.add(ImageRegion(
+        image_record_id=img.id, kind="concept",
+        rx=0.1, ry=0.1, rw=0.3, rh=0.3,
+        siglip_embedding=_emb(0), embedding_version="stale-embedder-v0",
+    ))
+    await db.commit()
+    assert not (await SuggestionService(db).for_image(img.id)).by_category.get("general")
+
+    # A matching-version concept crop → max-over-bag lifts it over the cut.
+    db.add(ImageRegion(
+        image_record_id=img.id, kind="concept",
+        rx=0.4, ry=0.4, rw=0.3, rh=0.3,
+        siglip_embedding=_emb(0), embedding_version=await _embver(db),
+    ))
+    await db.commit()
+    general = (await SuggestionService(db).for_image(img.id)).by_category["general"]
+    assert any(s.canonical_tag_id == tag.id and s.score > 0.7 for s in general)
+
+
+@pytest.mark.asyncio
+async def test_rejected_tag_surfaced_flagged_then_reversible(db):
+    # A dismissed suggestion is NOT dropped: it stays flagged rejected so the
+    # rail can show it + offer one-click un-reject (operator-asked 2026-06-27).
+    tag = await TagService(db).find_or_create("goblin", TagKind.general)
+    img = await _img(db, "f" * 64, _emb(0))
+    await _head(db, tag.id, slot=0)
+    await db.commit()
+    await AllowlistService(db).dismiss(img.id, tag.id)
+    await db.commit()
+
+    sl = await SuggestionService(db).for_image(img.id)
+    s = next(x for x in sl.by_category["general"] if x.canonical_tag_id == tag.id)
+    assert s.rejected is True
+
+    await AllowlistService(db).undismiss(img.id, tag.id)
+    await db.commit()
+    sl2 = await SuggestionService(db).for_image(img.id)
+    s2 = next(x for x in sl2.by_category["general"] if x.canonical_tag_id == tag.id)
+    assert s2.rejected is False
+
+
+async def _figure(db, image_id, slot):
+    v = [0.0] * 768
+    v[slot] = 1.0
+    db.add(ImageRegion(
+        image_record_id=image_id, kind="figure",
+        rx=0.0, ry=0.0, rw=1.0, rh=1.0,
+        ccip_embedding=v, embedding_version="ccip-test",
+    ))
+
+
+@pytest.mark.asyncio
+async def test_ccip_character_surfaces_in_rail(db):
+    # A character with a CCIP reference (a tagged figure) is suggested on a new
+    # image whose figure matches — overlaid into the rail alongside the heads.
+    raven = await TagService(db).find_or_create("Raven", TagKind.character)
+    ref = await _img(db, "0" * 64, None)         # the operator's tagged example
+    await _figure(db, ref.id, slot=0)
+    await db.execute(image_tag.insert().values(
+        image_record_id=ref.id, tag_id=raven.id, source="manual",
+    ))
+    query = await _img(db, "1" * 64, None)        # untagged, matching figure
+    await _figure(db, query.id, slot=0)
+    await db.commit()
+
+    sl = await SuggestionService(db).for_image(query.id)
+    m = next(
+        c for c in sl.by_category.get("character", [])
+        if c.canonical_tag_id == raven.id
+    )
+    assert m.source == "ccip"

tests/test_regions.py

@@ -0,0 +1,71 @@
+"""Region storage/service for the crop pipeline (#114)."""
+import pytest
+
+from backend.app.models import ImageRecord
+from backend.app.services.ml.regions import RegionService
+
+pytestmark = pytest.mark.integration
+
+
+async def _img(db, sha) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem", integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+@pytest.mark.asyncio
+async def test_replace_and_get_regions(db):
+    img = await _img(db, "a" * 64)
+    svc = RegionService(db)
+    n = await svc.replace_regions(img.id, ["figure"], [
+        {"kind": "figure", "bbox": (0.1, 0.1, 0.3, 0.4),
+         "score": 0.9, "detector_version": "det-v1", "frame_time": 42.5},
+    ])
+    await db.commit()
+    assert n == 1
+    regs = await svc.get_regions(img.id)
+    assert len(regs) == 1
+    r = regs[0]
+    assert r.kind == "figure"
+    assert r.rw == pytest.approx(0.3) and r.rh == pytest.approx(0.4)
+    assert r.score == pytest.approx(0.9)
+    assert r.frame_time == pytest.approx(42.5)   # video frame timestamp
+
+
+@pytest.mark.asyncio
+async def test_replace_is_scoped_by_kind(db):
+    img = await _img(db, "b" * 64)
+    svc = RegionService(db)
+    await svc.replace_regions(img.id, ["figure"], [
+        {"kind": "figure", "bbox": (0.0, 0.0, 0.5, 0.5)},
+    ])
+    await svc.replace_regions(img.id, ["concept"], [
+        {"kind": "concept", "bbox": (0.5, 0.5, 0.2, 0.2)},
+    ])
+    await db.commit()
+    # Re-running the figure detector must NOT wipe the concept region.
+    await svc.replace_regions(img.id, ["figure"], [
+        {"kind": "figure", "bbox": (0.1, 0.1, 0.4, 0.4)},
+    ])
+    await db.commit()
+    kinds = sorted(r.kind for r in await svc.get_regions(img.id))
+    assert kinds == ["concept", "figure"]
+
+
+@pytest.mark.asyncio
+async def test_ccip_vector_round_trips(db):
+    img = await _img(db, "c" * 64)
+    svc = RegionService(db)
+    await svc.replace_regions(img.id, ["figure"], [
+        {"kind": "figure", "bbox": (0.0, 0.0, 0.5, 0.5),
+         "ccip_embedding": [0.1] * 768, "embedding_version": "ccip-test"},
+    ])
+    await db.commit()
+    r = (await svc.get_regions(img.id, kinds=["figure"]))[0]
+    assert r.ccip_embedding is not None
+    assert len(list(r.ccip_embedding)) == 768
+    assert r.siglip_embedding is None

tests/test_suggestions_bulk.py

@@ -1,88 +1,84 @@
+"""Consensus (for_selection) over the tagging-v2 HEAD suggestion source."""
 import pytest
+from sqlalchemy import select
 
 from backend.app import create_app
-from backend.app.models import ImageRecord, TagKind
+from backend.app.models import ImageRecord, MLSettings, TagHead, TagKind
 from backend.app.models.tag import image_tag
 from backend.app.services.ml.suggestions import SuggestionService
 from backend.app.services.tag_service import TagService
-from tests._prediction_helpers import seed_predictions
 
 pytestmark = pytest.mark.integration
 
 
-def _img(sha: str) -> ImageRecord:
-    return ImageRecord(
-        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1,
-        mime="image/jpeg", width=1, height=1,
-        origin="imported_filesystem", integrity_status="unknown",
+def _emb(slot: int) -> list[float]:
+    v = [0.0] * 1152
+    v[slot] = 3.0
+    return v
+
+
+async def _img(db, sha: str, emb=None) -> ImageRecord:
+    img = ImageRecord(
+        path=f"/images/{sha}.jpg", sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown", siglip_embedding=emb,
     )
+    db.add(img)
+    await db.flush()
+    return img
+
+
+async def _head(db, tag_id: int, slot: int = 0):
+    s = (await db.execute(select(MLSettings).where(MLSettings.id == 1))).scalar_one()
+    weights = [0.0] * 1152
+    weights[slot] = 1.0
+    db.add(TagHead(
+        tag_id=tag_id, embedding_version=s.embedder_model_version,
+        weights=weights, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
 
 
 @pytest.mark.asyncio
 async def test_consensus_includes_tag_over_threshold(db):
-    tags = TagService(db)
-    t = await tags.find_or_create("sword", TagKind.general)
-    a = _img("a" * 64)
-    b = _img("b" * 64)
-    db.add_all([a, b])
-    await db.flush()
-    await seed_predictions(db, a.id, {"sword": {"category": "general", "confidence": 0.97}})
-    await seed_predictions(db, b.id, {"sword": {"category": "general", "confidence": 0.95}})
+    t = await TagService(db).find_or_create("sword", TagKind.general)
+    a = await _img(db, "a" * 64, _emb(0))
+    b = await _img(db, "b" * 64, _emb(0))
+    await _head(db, t.id, slot=0)
+    await db.commit()
     res = await SuggestionService(db).for_selection([a.id, b.id], threshold=0.8)
-    gen = res["general"]
-    assert any(s["canonical_tag_id"] == t.id for s in gen)
-    s = next(s for s in gen if s["canonical_tag_id"] == t.id)
-    assert s["coverage"] == 1.0
-    assert 0.95 <= s["confidence"] <= 0.97
+    s = next(s for s in res["general"] if s["canonical_tag_id"] == t.id)
+    assert s["coverage"] == 1.0          # suggested on both
+    assert s["confidence"] > 0.5
 
 
 @pytest.mark.asyncio
 async def test_consensus_counts_already_applied_for_coverage(db):
-    tags = TagService(db)
-    t = await tags.find_or_create("sky", TagKind.general)
-    a = _img("c" * 64)
-    b = _img("d" * 64)  # no prediction
-    db.add_all([a, b])
-    await db.flush()
-    await seed_predictions(db, a.id, {"sky": {"category": "general", "confidence": 0.96}})
-    # b already has the tag applied -> counts toward coverage, not confidence
+    t = await TagService(db).find_or_create("sky", TagKind.general)
+    a = await _img(db, "c" * 64, _emb(0))   # head suggests it
+    b = await _img(db, "d" * 64, None)       # no embedding; tag applied instead
+    await _head(db, t.id, slot=0)
     await db.execute(
         image_tag.insert().values(
             image_record_id=b.id, tag_id=t.id, source="manual"
         )
     )
+    await db.commit()
     res = await SuggestionService(db).for_selection([a.id, b.id], threshold=0.8)
     s = next(s for s in res["general"] if s["canonical_tag_id"] == t.id)
     assert s["coverage"] == 1.0          # 1 suggested + 1 applied / 2
-    assert s["confidence"] == pytest.approx(0.96, abs=1e-4)
 
 
 @pytest.mark.asyncio
 async def test_consensus_excludes_below_threshold(db):
-    tags = TagService(db)
-    await tags.find_or_create("rare", TagKind.general)
-    a = _img("e" * 64)
-    b = _img("f" * 64)
-    db.add_all([a, b])
-    await db.flush()
-    await seed_predictions(db, a.id, {"rare": {"category": "general", "confidence": 0.96}})
+    t = await TagService(db).find_or_create("rare", TagKind.general)
+    a = await _img(db, "e" * 64, _emb(0))   # suggested here
+    b = await _img(db, "f" * 64, None)       # not here → coverage 0.5 < 0.8
+    await _head(db, t.id, slot=0)
+    await db.commit()
     res = await SuggestionService(db).for_selection([a.id, b.id], threshold=0.8)
-    assert all(
-        s["name"] != "rare" for s in res.get("general", [])
-    )  # coverage 0.5 < 0.8
-
-
-@pytest.mark.asyncio
-async def test_consensus_skips_creates_new_tag(db):
-    a = _img("g" * 64)
-    b = _img("h" * 64)
-    db.add_all([a, b])
-    await db.flush()
-    await seed_predictions(db, a.id, {"neverseen": {"category": "general", "confidence": 0.99}})
-    await seed_predictions(db, b.id, {"neverseen": {"category": "general", "confidence": 0.99}})
-    res = await SuggestionService(db).for_selection([a.id, b.id], threshold=0.8)
-    # 'neverseen' has no Tag row -> creates_new_tag -> excluded from consensus
-    assert all(s["name"] != "neverseen" for s in res.get("general", []))
+    assert all(s["name"] != "rare" for s in res.get("general", []))
 
 
 @pytest.mark.asyncio
@@ -93,13 +89,9 @@ async def test_consensus_threshold_clamped_and_empty_for_no_ids(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_route(db):
-
-    tags = TagService(db)
-    await tags.find_or_create("sword", TagKind.general)
-    a = _img("i" * 64)
-    db.add(a)
-    await db.commit()
-    await seed_predictions(db, a.id, {"sword": {"category": "general", "confidence": 0.97}})
+    t = await TagService(db).find_or_create("sword", TagKind.general)
+    a = await _img(db, "i" * 64, _emb(0))
+    await _head(db, t.id, slot=0)
     await db.commit()
     app = create_app()
     async with app.test_client() as c:
@@ -115,7 +107,6 @@ async def test_bulk_suggestions_route(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_requires_ids(db):
-
     app = create_app()
     async with app.test_client() as c:
         resp = await c.post("/api/suggestions/bulk", json={})