auto-balance

/auto-balance — machine truth and account budget for parallel agents

Make this session a good citizen on a machine that is running several others. Cap what it consumes, take turns on hardware, and size its own agent count so the account never hits a limit.

First run does setup and writes the environment description down. Every later run re-balances against what is actually running now.

Step 1 — First-Run Setup (once per repo)

Ask, then persist to .agent/balance.json (gitignored — it may name hosts):

1. The machine: cores, RAM, and whether builds routinely OOM today.
2. Typical concurrency: how many editor windows / agent sessions run at once.
3. Attached hardware: Android devices, dev boards, ESP32s, anything on serial.
4. Remote hosts: a Mac for iOS work, a build server. Ask for connection details — an SSH Host alias, a Tailscale name, the user to connect as. Store the alias, never a key or password; the key lives in ~/.ssh/ and is referenced by config.
5. Claude plan and session habits: which plan, and how many sessions typically run at once.

Record what you measured alongside what you were told:

nproc; grep -E '^(MemTotal|MemAvailable|SwapTotal)' /proc/meminfo
cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers
oomctl        # works unprivileged: SwapUsedLimit, DefaultMemoryPressureLimit, duration

oomctl is step zero on every run — it tells you what will kill you and at what threshold before you start anything.

Step 2 — Know What Actually Works Here

Resource controls fail silently more often than they fail loudly. Establish the truth per machine:

cgroup delegation. A user slice typically delegates cpu memory pids and not io. Consequence:

systemd-run --user --scope -p CPUQuota=50%  ...    # works
systemd-run --user --scope -p MemoryMax=2G  ...    # works
systemd-run --user --scope -p IOWeight=50   ...    # EXIT 0, NO ERROR, NO EFFECT