feat(scheduling): replica spread + resource-aware auto placement (#56)

services.spread distributes replicas across every online, schedulable
agent (replica i → agents[i mod n], deterministic). auto placement now
orders by real headroom — memory utilisation, cpu usage, then container
count — instead of count alone.

Lifecycle (start/stop/restart/delete) and GET /runtime are now driven
by container_instances inventory, so remote replicas are visible and
tear down wherever they run — covers spread, pins, and stale pin
leftovers. Spread and explicit pins are mutually exclusive.

Generated with [Devin](https://devin.ai)

Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs/api/openapi.yaml

@@ -6974,6 +6974,9 @@ components:
         node_name:
           type: string
           description: Display name of the pinned node agent (read-only)
+        spread:
+          type: boolean
+          description: Replicas are distributed across every online, schedulable node agent (replica i → agents[i mod n]). Mutually exclusive with an explicit node_id pin.
         public_url:
           type: string
           description: Computed public URL (published port or domain)
@@ -7068,6 +7071,9 @@ components:
         node_id:
           type: string
           description: Node agent id to pin to, 'auto' = least-loaded online agent; omit/empty = local host
+        spread:
+          type: boolean
+          description: Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin
 
     UpdateServiceRequest:
       type: object
@@ -7157,6 +7163,9 @@ components:
         node_id:
           type: string
           description: Node agent id to pin to, 'auto' = least-loaded online agent, 'local' = run on the Containr host (clears the pin)
+        spread:
+          type: boolean
+          description: Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin — send 'local' first to clear a pin
 
     ServiceDomain:
       type: object

docs/guides/CLI.md

@@ -143,6 +143,15 @@ containr services update <id> --node auto    # least-loaded online node
 containr services update <id> --node local   # move back to this server
 ```
 
+`auto` scores nodes by real headroom — lowest memory utilisation, then
+cpu, then container count. Or spread replicas across every online,
+schedulable node (mutually exclusive with a pin):
+
+```bash
+containr services update <id> --replicas 4 --spread    # replica i → node[i % n]
+containr services update <id> --spread=false           # back to single placement
+```
+
 Remote nodes run registry-pulled images only — git builds, domains
 (Traefik lives on the host), and sleep detection stay local. Start,
 stop, restart, redeploy, and delete all fan out to the pinned node's