feat(ops): vision-manager sidecar to autoscale the llama.cpp container

Add a tiny privileged sidecar (vision-manager/) that polls the analysis
backlog in Postgres and starts/stops the mangalord-vision container by name:
start when analyze_page jobs are pending, stop after STOP_DEBOUNCE idle.
It is the single owner of the vision lifecycle and the only component with
Docker access — scoped through tecnativa/docker-socket-proxy (CONTAINERS+POST
only) on an internal-only network, so the internet-facing backend never
touches the socket.

Both helpers sit behind `profiles: [ai]` (vanilla `compose up` is
unaffected). The manager debounces the stop, gates the first request on
GET /health==200 after a cold start, honours a crawl RAM-mutex on the 8 GiB
box, and owns its own idle timer (leak-safe if the backend dies). Backlog
query uses the real schema (state + payload->>'kind'); a read-only DB role
(readonly-role.sql) keeps it off the backend creds.

Bump 0.80.0 -> 0.81.0.

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

docker-compose.yml

@@ -91,6 +91,13 @@ services:
       CRAWLER_TOR_CONTROL_URL: ${CRAWLER_TOR_CONTROL_URL-tcp://tor:9051}
       CRAWLER_TOR_CONTROL_PASSWORD: ${TOR_CONTROL_PASSWORD:?TOR_CONTROL_PASSWORD must be set in .env}
       CRAWLER_TOR_RECIRCUIT_MAX_ATTEMPTS: ${CRAWLER_TOR_RECIRCUIT_MAX_ATTEMPTS:-3}
+      # Vision readiness gate (env-ONLY, not a dashboard setting). When set,
+      # the analysis worker refuses to lease a page until this answers 2xx, so
+      # the vision-manager autoscaler can idle-stop the vision container
+      # without jobs burning their retries / landing `failed` rows. Leave
+      # empty (the default) to disable the gate for an always-on endpoint.
+      # Pair with the `ai` profile services below. See VISION-AUTOSCALE.md.
+      ANALYSIS_VISION_HEALTH_URL: ${ANALYSIS_VISION_HEALTH_URL:-}
     volumes:
       - storage-data:/var/lib/mangalord/storage
     # No host port mapping in the default setup — the frontend proxies
@@ -111,6 +118,62 @@ services:
     ports:
       - "3000:3000"
 
+  # ----- Vision autoscaling (profile: ai) -----------------------------------
+  # Two extra containers that idle-stop the mangalord-vision (llama.cpp)
+  # container when there is no analysis work and start it back up on demand.
+  # Gated behind `profiles: [ai]` so a vanilla `docker compose up` is
+  # unaffected — bring them up with `docker compose --profile ai up -d`.
+  # The vision container itself is NOT defined here (it lives elsewhere on the
+  # host); the manager drives it by name. See VISION-AUTOSCALE.md.
+
+  # Scoped Docker access for the manager: exposes ONLY the /containers API and
+  # write methods (start/stop) over TCP on an internal-only network. The raw
+  # host socket is mounted HERE and nowhere else — never on the backend.
+  docker-socket-proxy:
+    image: tecnativa/docker-socket-proxy:latest
+    profiles: ["ai"]
+    environment:
+      CONTAINERS: 1   # allow /containers/* (inspect, start, stop)
+      POST: 1         # allow write methods (start/stop are POSTs)
+      # Everything else stays denied (images, exec, networks, volumes, ...).
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - vision-internal
+    restart: unless-stopped
+
+  vision-manager:
+    build: ./vision-manager
+    profiles: ["ai"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+      docker-socket-proxy:
+        condition: service_started
+    environment:
+      # Read-only role — apply vision-manager/readonly-role.sql once, then set
+      # VISION_MANAGER_DATABASE_URL in .env. Do NOT reuse the backend creds.
+      DATABASE_URL: ${VISION_MANAGER_DATABASE_URL:?set VISION_MANAGER_DATABASE_URL in .env (vision_manager read-only role)}
+      VISION_CONTAINER: ${VISION_CONTAINER:-mangalord-vision}
+      VISION_HEALTH_URL: ${VISION_HEALTH_URL:-http://mangalord-vision:8000/health}
+      DOCKER_HOST: tcp://docker-socket-proxy:2375
+      POLL_INTERVAL: ${VISION_POLL_INTERVAL:-20}
+      STOP_DEBOUNCE: ${VISION_STOP_DEBOUNCE:-600}
+      START_HEALTH_TIMEOUT: ${VISION_START_HEALTH_TIMEOUT:-300}
+      RESPECT_CRAWL_MUTEX: ${VISION_RESPECT_CRAWL_MUTEX:-1}
+      MAX_UPTIME: ${VISION_MAX_UPTIME:-0}
+    networks:
+      - default          # reach postgres + the vision container by name
+      - vision-internal  # reach the socket-proxy
+    restart: unless-stopped
+
+networks:
+  default:
+  # Internal-only: no route to the outside world. Only the manager and the
+  # socket-proxy sit on it, so nothing else can reach the Docker API.
+  vision-internal:
+    internal: true
+
 volumes:
   postgres-data:
   storage-data: