Bound warm workers' host memory and account local RAM

A worker over FLOW_WORKER_MAX_RSS_MB (--worker-max-rss) when its node
returns is retired instead of kept warm, in the shared pool and in every
declared one; 0, the default, keeps them all. The engine now accounts its
own memory (FLOW_RAM / --ram, else the box or the cgroup limit less 1 GB),
so a node's `ram` declaration holds locally. A declared environment the
shared pool already has is that pool rather than a duplicate set of warm
workers.

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

docs/code/cli.md

@@ -79,6 +79,8 @@ Another instance's Fluksio on the port is named, and the move happens as usual.
 | `--max-cascades N` | 4 | cascades in flight at once (`FLOW_MAX_CASCADES`) |
 | `--max-workers N` | 4 | python worker processes (`FLOW_MAX_WORKERS`) |
 | `--gpus N` | counted | GPUs on this machine a node may be given (`FLOW_GPUS`) |
+| `--ram MB` | worked out | memory on this machine a node may be given (`FLOW_RAM`) |
+| `--worker-max-rss MB` | 0 (never) | retire a warm worker holding more when its node returns (`FLOW_WORKER_MAX_RSS_MB`) |
 
 Cards are counted from NVIDIA's device nodes (`/dev/nvidia0`, `/dev/nvidia1`, …),
 which asks no vendor tool and so keeps the one dependency from becoming two.

docs/getting-started/data-science.md

@@ -315,6 +315,13 @@ given `CUDA_VISIBLE_DEVICES`, and leaves a warm worker holding whatever it
 preallocated. Declaring the card is what makes it a worker the engine knows
 to retire, and what stops two such nodes running at once in the first place.
 
+Host memory is held the same way, and there the declaration is not needed. A
+worker that fitted a model keeps what it allocated, and on a laptop a few warm
+ones are the machine. `fluksio serve --worker-max-rss 1024` retires any worker
+holding more than that when its node returns, whichever pool it is in. A
+node's `ram` is counted against this machine's memory, so declaring it is what
+stops three large fits from starting at once.
+
 Declaring nothing is the default and is right for most nodes: a poll, a
 threshold, a message on its way somewhere. Those share the engine's worker pool
 and are given a fair share of `FLOW_CPUS` as a thread cap, which is what stops

docs/reference/configuration.md

@@ -134,6 +134,8 @@ warning into a refusal to start.
 | `FLOW_NODE_TIMEOUT` | `0` | seconds a node may be silent, unless it sets its own; 0 is no limit |
 | `FLOW_CPUS` | `0` | cores nodes that declare `resources` may be given; 0 works it out as every core but two, which are what keeps the engine answering while the machine is busy |
 | `FLOW_GPUS` | `0` | GPUs on this machine, each held by one node at a time. 0 counts NVIDIA's device nodes; say a number for anything they miss |
+| `FLOW_RAM` | `0` | megabytes nodes that declare `ram` may be given; 0 works it out as the machine's memory, or the container's limit where that is lower, less a gigabyte for the engine |
+| `FLOW_WORKER_MAX_RSS_MB` | `0` | a warm worker holding more resident memory than this when its node returns is retired rather than kept; 0 keeps every worker warm |
 | `OBS_RETENTION_DAYS` | `30` | how long metrics, events and run records are kept |
 | `ARTIFACT_GC_INTERVAL_S` | `3600` | how often artifact bytes nothing refers to are swept away; 0 never sweeps |
 | `ARTIFACT_GC_GRACE_S` | `3600` | how long a freshly written artifact is spared, whatever refers to it |
@@ -142,10 +144,10 @@ warning into a refusal to start.
 | `ARTIFACT_VOLATILE_BYTES` | `50331648` | how much that ring holds before the oldest frames fall out; 0 turns it off and volatile saves land in the store |
 
 The three concurrency limits are also flags on `fluksio serve`
-(`--max-workers`, `--max-cascades`, `--max-runs`), as is the card count,
-`--gpus`. The flags
+(`--max-workers`, `--max-cascades`, `--max-runs`), as are the card count and
+memory, `--gpus` and `--ram`, and the worker ceiling, `--worker-max-rss`. The flags
 outrank the file, and the engine says which numbers it started with in its
-first lines. Each pool size must be at least 1 and the card count at least 0:
+first lines. Each pool size must be at least 1 and the others at least 0:
 a number below that is refused as a flag error naming it, rather than read as
 the default. Leave one empty (or unset) to get the default.
 
@@ -170,7 +172,15 @@ several at once cannot each size themselves to the whole machine. Setting
 `OMP_NUM_THREADS` (or any of its siblings) on the engine yourself overrides
 that default.
 
-These two are this machine's figures. An attached worker reports its own when
+Workers are kept warm between calls, and a library like JAX keeps what it
+allocated for as long as its process lives — so a worker that fitted a model
+can sit on gigabytes after its run is over, on the shared pool as much as on a
+declared one. `FLOW_WORKER_MAX_RSS_MB` retires such a worker when its node
+returns, and the next call pays its imports again. That bounds idle memory
+only; what a node holds while it runs is accounted, and only if it declared
+`ram`.
+
+`FLOW_CPUS`, `FLOW_GPUS` and `FLOW_RAM` are this machine's figures. An attached worker reports its own when
 it dials in, and a node goes to whichever machine can grant what it asked for,
 so a GPU on a worker needs no `FLOW_GPUS` here. What every machine has free, and
 which nodes are queued, is `GET /api/v1/workers/resources` and the Workers