Repository navigation
feat: make the memory and CPU load guard tracked tooling every home arms - #27
Merged
Merged
Conversation
Add bin/fm-load-guard.sh (check/status/arm/disarm): a standing watcher check that wakes firstmate when memory free or measured CPU idle crosses its threshold (defaults 25% and 10%, config/load-guard), on macOS via memory_pressure and iostat and on Linux via /proc. Unmeasurable readings never alarm, and an episode record suppresses repeat wakes to its start, worsening, and a periodic reminder. Locked bootstrap arms it idempotently in every home, secondmates included, and disarms it when config/load-guard says off. fm-spawn warns over a threshold and refuses a fresh launch below the memory spawn floor (15%) unless FM_LOAD_GUARD_OVERRIDE carries a reason, recorded in the task record. The housekeeping skill owns the wake response procedure.
…d episode hysteresis
…e after hold expiry
withkrew
approved these changes
Oct 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes the memory/CPU load guard - until now a private, hand-written
state/load-guard.check.shin one home - tracked Firstmate tooling that every home arms automatically.bin/fm-load-guard.sh(check | status | arm | disarm): a standing watcher check (generated shim +fm-check-registerbinding, same pattern asfm-mail-check.sh) that prints one wake line when memory free or measured CPU idle crosses its threshold (defaults 25% / 10%, configurable inconfig/load-guard,offopts out).memory_pressure+ the measurediostatsample (idle column located by header). Linux:/proc/meminfoMemAvailable+/proc/statdeltas.FM_CHECK_TIMEOUT.state/.load-guarddedupes: wake at episode start, when another metric joins, when memory crosses the spawn floor, and at most everyremind_secs; an episode ends only after readings stay clear for a sustained hold.bin/fm-bootstrap.sh: the locked session-start path arms it idempotently in every home, secondmates included, and disarms it whenconfig/load-guardisoff; failures printLOAD_GUARD:.bin/fm-spawn.sh: warns when a threshold is crossed; refuses a NEW launch below the memory spawn floor (default 15%) unlessFM_LOAD_GUARD_OVERRIDE=<reason>is set (recorded asload_guard_overridein the task record). Recovery (relaunch, dead-secondmate auto-recovery) only warns. An unmeasurable reading never refuses.housekeepingskill (identify whose load, throttle own workers, hold spawns, never kill foreign processes or pattern-kill, tell the captain when the load is not the fleet's), plus a one-line trigger inAGENTS.mdsection 8.docs/configuration.md"Load guard",docs/scripts.md,bootstrap-diagnostics, script headers.Notes
state/load-guard.check.shis replaced by the generated shim (same check id).config/load-guardis per home and not inherited by secondmate homes.tests/lib.sh(and the real-spawn smoke/e2e safety helper) pinFM_LOAD_GUARD=offso other suites never read the host's real load.Tests
tests/fm-load-guard.test.sh: both platform parsers via env seams, unmeasurable readings, dedupe/reminder/hysteresis, floor crossing, config/off/malformed, arm idempotency and shim execution, bootstrap arming, spawn warn/refuse/override and recovery exemption.