Add a memory-pressure guard to executor spawns (warn by default)

[bborn]

Why

Nothing in ty bounded how many agent sessions could be live at once. Each session is a claude process plus its MCP servers, so a queue that fans out freely can walk a workstation into swap thrashing — at which point every session, dev server and test run on the box gets slower, including the ones already doing useful work.

Measured on a 24GB M4 while diagnosing this: 36 live sessions across 393 processes, of which 35 session trees belonged to tasks that were already done or blocked — 4.4GB resident and a large share of what was filling 27GB of swap. Only 2 tasks were actually processing.

What this is not

Deliberately not a concurrency cap. A fixed "max N sessions" is a hidden wall — the right number depends entirely on how much RAM the machine has and what else is running, and someone who legitimately wants dozens of concurrent agents shouldn't be told "no" by an arbitrary constant.

So this gates on the machine's actual memory pressure instead. With headroom, spawn as many as you like. The guard only has an opinion once the kernel says memory is genuinely short.

How

systemFreeMemoryPct is implemented per platform behind one stable contract — percent of memory still available, or "can't tell" — so the threshold means the same thing everywhere:

Platform	Signal
darwin	kern.memorystatus_level — what Activity Monitor's memory-pressure graph is derived from
linux	cgroup v2 if the cgroup is limited, else /proc/meminfo MemAvailable
everything else	inert — guard has no opinion, spawns proceed as before

TY_MEMORY_GUARD=off|warn|block        # default: warn
TY_MEMORY_GUARD_MIN_FREE_PCT=<0-100>  # default: 20

On macOS the default of 20 maps to Activity Monitor's zones (green 100-50, yellow 50-30, red 30-0), so it fires only well into the red — when the machine is already hurting, not merely busy.

Default mode is warn: it logs loudly and never blocks. Behaviour is unchanged for everyone unless they opt in. TestGuardMemoryForSpawnDefaultNeverBlocks pins that property specifically — it forces the threshold to 100% (so the machine is guaranteed "under pressure") and asserts the default mode still returns no error.

In block mode the spawn returns ErrMemoryPressure carrying the actual free percentage, the threshold, the task id, and the override — so if it ever does bite, it says why and how to get past it rather than silently stalling.

Wired into both spawn choke points: createTmuxWindow (daemon path) and EnsureTaskWindow (TUI/API path).

Two Linux details that matter

Both are load-bearing, and both have tests:

• MemAvailable, not MemFree. Linux fills RAM with reclaimable cache, so MemFree reads ~1% on a perfectly healthy box. Using it would wedge spawns in block mode for no reason. Pre-3.14 kernels fall back to MemFree + Buffers + Cached.
• cgroup v2 first, and subtract inactive_file. A containerised agent server must be measured against its own limit, not the host's RAM — otherwise a 2GB container on a 64GB host looks infinitely roomy right up until the OOM killer fires. And because memory.current counts page cache, which is reclaimable, a long-running container would otherwise sit at 0% free forever and stop spawning entirely.

PSI (/proc/pressure/memory) is deliberately not used. It's the sharper Linux pressure signal, but it measures stall time rather than a fraction of memory, so it can't share TY_MEMORY_GUARD_MIN_FREE_PCT's meaning with the macOS path. One threshold that means the same thing on every platform seemed worth more than a slightly better Linux signal.

Testing

gofmt and go vet clean; full internal/executor suite passes. Verified building for darwin, linux, freebsd and openbsd. (Windows still doesn't build, on executorlock's syscall.Flock — pre-existing, confirmed by building the branch without these files, and untouched here.)

17 tests. The Linux parsers live in a build-tag-free file specifically so they're unit-testable on the macOS machines this gets developed on, rather than shipped unverified:

• Guard logic: mode parsing (unset and unrecognised both fall back to warn, never block), threshold parsing and out-of-range fallback, off being inert, the default-never-blocks property, block mode at 100% and 0% thresholds, raw signal in range.
• meminfo: normal parse, the MemAvailable-vs-MemFree property, pre-3.14 fallback, SwapCached not leaking into Cached, garbage rejection.
• cgroup: normal parse, page-cache-is-available property, unlimited (max) falling back, garbage rejection, over-limit clamping.

Tests skip rather than fail where the live signal is unavailable, so they're safe on any CI.

Follow-up not included here

A --strict-mcp-config change was considered to cut per-session MCP fan-out (~21 servers merge into every task session today, only 1 of which is taskyou). It was rejected: strict mode's mechanism is "ignore everything except this file," which breaks ty's premise that a worktree agent has the same MCP servers its parent repo has. Worth revisiting only if Claude Code grows a way to disable user/plugin scope while keeping project scope.

🤖 Generated with Claude Code