Module spawn_gate 

Spawn gate (x-c5cc): global concurrency cap + free-RAM floor + queue loop.

Called at the top of the client spawn arm for the bg/headless substrates only (pane re-execs into the Python CLI, whose mirrored gate in fno/agents/spawn_gate.py is the sole gate on that path — exactly one gate evaluation per spawn, LD1).

The gate is READ-ONLY: the max_live slot cap counts the fno registry (worker provenance) and the RAM floor reads system vm_stat/meminfo. The claude daemon roster is consulted only as a LIVENESS ORACLE for fno bg rows that carry no local pid, and by the post-spawn QoS demotion helper — never as a population to count (x-bdf9: the roster’s non-work sessions must not consume worker slots; only rows that are ALSO in the fno registry count). The gate’s only writes are its own claims (spawn-gate check→dispatch mutex, worker:<name> headless slot claims). Every guard fails OPEN on read errors (LD5): the gate is protective infrastructure and must never become the thing that bricks spawning.

Structs

GateFlags

Flags the spawn arm parses for the gate.

GateGuard

Held gate state. The caller keeps this alive across its dispatch call and calls GateGuard::release (or drops it) when the dispatch result exists, so the next waiter’s count includes the newcomer.

Constants

EXIT_NO_WAIT

EXIT_QUEUE_TIMEOUT

Exit codes, distinct from existing dispatch codes (2, 13, 14, 15, 18, 127).

EXIT_RAM_REFUSED

Functions

available_ram_gb

Available system RAM in GB, or None when unreadable (guard skipped, fail open — a broken vm_stat must never brick spawning).

parse_meminfo

Parse /proc/meminfo (Linux) MemAvailable: kB to bytes.

parse_vm_stat

Parse vm_stat output (macOS) to available bytes: (free + inactive + speculative + purgeable) pages × page size. None on any shape surprise so the guard fails open.

qos_demote_bg_worker

After a --substrate bg dispatch, poll the roster briefly for the new worker’s pid and demote it post-hoc (its exec is claude’s, not ours). Bounded ~10s; one warning if the pid never appears (AC3-UI).

qos_demote_pid

Best-effort post-hoc demotion of a claude-daemon-owned bg worker pid (taskpolicy -b -p on macOS, renice 10 -p on Linux; same uid, so permitted). Non-fatal: failure prints one warning, the spawn stands.

qos_wrap

Exec-wrap a child command at background priority when config.agents.worker_qos is utility: taskpolicy -c utility -- <cmd> on macOS, nice -n 10 <cmd> on Linux. Identity on off / other OSes.

run_gate

Run the full gate for a bg/headless spawn. Returns a guard to keep alive across dispatch on pass, or Err(exit_code) on refusal/timeout. All human-facing output goes to stderr (LD10: the stdout receipt is byte-reserved for the pass path).

slot_count

Count fno WORKER SLOTS in use for the max_live cap: liveness-filtered fno registry rows + live worker:<name> headless slot claims.

spawn_cap_would_emit

Pure parity core (x-91b5, AC2-FR): would a bypass in this env emit spawn-cap? True iff FNO_SPAWN_GATE=0 AND no non-empty test-context marker. Mirrors fno.events.gate_escape.should_emit_spawn_cap exactly; a shared JSON fixture (gate_escape_spawn_cap_parity.json) asserts the two implementations agree on every row, so neither can drift (Locked Decision 5).