feat: one number per lane — the cap — and the autoscaler is the mechanism (4295)

Operator, 2026-09-23: *"auto should be always on, not a setting, so that idle
instances quiet down when not running. the number that is visible and
something the user can tweak and manage should be the cap itself the number of
running workers is handled by the autoscaling function which is always on."*

They are right, and the reason it was not built this way is worth stating: the
manual dial came first (steps 2-4) and the autoscaler came last (step 7), as
an opt-in BESIDE a control that already existed. Nothing ever asked whether
the dial should still exist once something could move it automatically. Each
step was defensible; the result was three operator settings over one number.

## `slots`, `enabled` and `autoscale` are gone

`slots` was a MEASUREMENT wearing a preference's clothes. How many workers a
lane runs is read live and moved every minute; storing it meant the operator
had to keep two numbers in agreement and the autoscaler had to be told it was
allowed to touch one of them.

`autoscale` gated the mechanism behind a choice, so a lane nobody opted in
never gave its workers back — which is why an idle instance never quieted
down.

`enabled` is derived: a cap of zero means no consumers. "Off" and "may use no
workers" were two spellings of one fact, stored separately, free to disagree.

## Two sweeps become one

`reconcile_lanes_sync` drove the pool to the stored `slots`; `autoscale_lanes_
sync` moved it away from that same number; and most of step 7's hardest
reasoning — a stored value that is a FLOOR, a target of `max(stored, current)`
— existed only to stop them fighting. Delete the stored number and the problem
is not solved, it is absent.

`size_lanes_sync` runs every minute and owns both consumers and pool size. It
also subsumes what the reconcile was for: a worker restarted at its ENV
concurrency is corrected on the next tick rather than after five.

Growth is immediate, shrink is one worker per tick. Deliberately asymmetric —
"always on" is only pleasant if the ramp keeps up, and +1/minute would take
four minutes to answer a burst. Being one worker too large for a minute costs
a sleeping process; being too small costs work not happening. For ML the
asymmetry matters most: every new slot reloads a multi-GB model, so the slow
shrink is what stops a quiet patch from paying that cost again a minute later.

## The caps ship at one, and zero for ML

Per the operator. Conservative on purpose — and a conservative default nobody
knows how to raise is just a slow product, which is the other half of what
they asked for:

    "there needs to be something that tells the user to bump those numbers to
     improve processing rate or they'd never know the controls exist."

So a lane running everything its cap allows while work piles up says so, in
its own row, with the headroom named: *"4,060 waiting and all 1 worker busy.
Raise the cap to run more at once — this machine allows up to 7."*

It fires only when raising the cap would actually help. Not when the lane is
keeping up, not when the sizing pass has room it has not taken, and not at the
machine ceiling — where "raise the cap" is advice nobody can take.

## Migration 0105 rewrites the caps rather than carrying them

The old defaults (4/2/2/1) bounded a manual control and were loose because
moving within them was the ordinary act. The number now means "the most
workers this lane may use", which is a different promise; carrying the old
figure over would quadruple the worker lane on every existing install at the
moment this deploys.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LVjrnpQjRgHdvq95rASoiR

backend/app/services/worker_lanes.py

@@ -129,18 +129,15 @@ class Lane:
     # with CELERY_QUEUES=maintenance_long). Recorded here so the generated
     # supervisord config and the compose file cannot disagree about it.
     entrypoint_role: str
-    default_slots: int
-    # The cap a lane STARTS with, which is not the ceiling. Set low enough
-    # that raising slots within it is an ordinary adjustment, and raising the
-    # cap itself is a deliberate act — a cap that begins at the ceiling is a
-    # rubber stamp and protects nobody.
+    # THE cap a lane starts with — and, since 2026-09-23, the only number an
+    # operator sets for it. How many workers actually run is the autoscaler's
+    # job; this is the most it may use. Zero means the lane is off.
+    #
+    # One, and zero for ML. Deliberately far below the operator's own
+    # production numbers, which are tuned for their hardware and are not a
+    # sane first boot for a stranger — and low enough that a busy instance
+    # tells them to raise it rather than quietly consuming the machine.
     default_slots_cap: int
-    default_enabled: bool
-    # Whether a lane arrives with the autoscaler on. False for every lane, and
-    # the field exists anyway: this module is the one place that describes a
-    # lane, and leaving one operator-settable default to the column's DDL
-    # default would make it the only setting you cannot read here.
-    default_autoscale: bool = False
     # True when a slot costs a copy of the ML model rather than just a process.
     # The only lane whose ceiling is decided by memory instead of by cores.
     memory_bound: bool = False
@@ -159,51 +156,58 @@ class Lane:
         return tuple(sorted(self.queues))
 
 
-# Defaults are ONE OF EACH, with ML off — operator, 2026-09-22: *"that
-# starting value should be one of each."* Deliberately far below the
-# operator's own production numbers (worker 8, ml 2), which are tuned for
-# their hardware and are not a sane first boot for a stranger.
+# ONE CAP PER LANE, and that is the whole of what an operator sets.
 #
-# ML ships disabled because enabling it is what triggers the SigLIP download
-# (milestone 422 step 6) — rule 164 allows a feature that needs a fetch only
-# when it is "optional and clearly off", and off-by-default is also what keeps
-# a small box from loading a multi-GB model it was never asked to load.
+# Operator, 2026-09-23: *"auto should be always on, not a setting, so that
+# idle instances quiet down when not running. the number that is visible and
+# something the user can tweak and manage should be the cap itself the number
+# of running workers is handled by the autoscaling function which is always
+# on."*
+#
+# Until then a lane had THREE operator values — `slots`, `slots_cap` and
+# `autoscale` — because the manual dial was built first (steps 2-4) and the
+# autoscaler arrived last (step 7) as an opt-in beside a control that already
+# existed. Nothing ever asked whether the dial should still exist once
+# something could move it automatically. It should not: "how many are running
+# right now" is a measurement, not a preference.
+#
+# One of each, and ML at zero. ML at zero is also rule 164's carve-out: a cap
+# of zero means no consumers, so a fresh install never loads a model or
+# reaches HuggingFace, and raising the cap is what triggers the fetch.
+#
+# These are far below the operator's own production numbers, and deliberately
+# so — they are what a stranger's first boot should do, not what a tuned
+# machine can. The UI is what closes that gap: a lane sitting at its cap with
+# a backlog says so, and says raising the cap is the fix. Without that a
+# conservative default is just a slow instance nobody knows how to speed up.
 LANES: tuple[Lane, ...] = (
     Lane(
         name="worker",
         display_name="Worker",
         queues=("default", "import", "thumbnail", "download"),
         entrypoint_role="worker",
-        default_slots=1,
-        default_slots_cap=4,
-        default_enabled=True,
+        default_slots_cap=1,
     ),
     Lane(
         name="scheduler",
         display_name="Scheduler",
         queues=("maintenance", "scan"),
         entrypoint_role="scheduler",
-        default_slots=1,
-        default_slots_cap=2,
-        default_enabled=True,
+        default_slots_cap=1,
     ),
     Lane(
         name="maintenance_long",
         display_name="Long maintenance",
         queues=("maintenance_long",),
         entrypoint_role="worker",
-        default_slots=1,
-        default_slots_cap=2,
-        default_enabled=True,
+        default_slots_cap=1,
     ),
     Lane(
         name="ml",
         display_name="ML tagging",
         queues=("ml",),
         entrypoint_role="ml-worker",
-        default_slots=0,
-        default_slots_cap=1,
-        default_enabled=False,
+        default_slots_cap=0,
         memory_bound=True,
         models=(SIGLIP_MODEL,),
         optional=True,
@@ -242,6 +246,22 @@ ML_BYTES_PER_SLOT = SIGLIP_MODEL.approx_resident_bytes
 # the processes an OOM kill must not take (see the module docstring).
 RESERVED_BYTES = 2 * GIB
 
+# The smallest pool a lane can actually run: ONE process, never zero.
+#
+# billiard refuses to remove the last worker in a pool, so a lane asked to
+# shrink to nothing gets `ValueError("Can't shrink pool. All processes
+# busy!")` and the sizing pass re-sends the doomed message forever. Found on
+# the operator's live deploy, 2026-09-23.
+#
+# It is also what makes "off" expressible: a lane at cap 0 keeps this one
+# parked process with its consumers cancelled, so it still answers `inspect`
+# (and so reads as present rather than crashed), and `add_consumer` has
+# something to reach when the cap goes back up.
+#
+# Lives HERE rather than in `worker_control` because `gen_supervisord` needs
+# it at container boot and must not import the models package to get it.
+MIN_POOL_SLOTS = 1
+
 # The floor a cores-derived ceiling never goes below. A single-core box still
 # needs to be able to run its lanes; the ceiling exists to stop absurd values,
 # not to make a small machine unusable.