Skip to content

feat: make the memory and CPU load guard tracked tooling every home arms - #27

Merged
Boxyboxy merged 4 commits into
feat/omp-adaptorfrom
fm/fm-load-guard-mainstay
Oct 2, 2026
Merged

Boxyboxy merged 4 commits into
feat/omp-adaptorfrom
fm/fm-load-guard-mainstay

Conversation

@Boxyboxy

@Boxyboxy Boxyboxy commented Oct 2, 2026

Copy link
Copy Markdown
Owner

What

Makes the memory/CPU load guard - until now a private, hand-written state/load-guard.check.sh in 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-register binding, same pattern as fm-mail-check.sh) that prints one wake line when memory free or measured CPU idle crosses its threshold (defaults 25% / 10%, configurable in config/load-guard, off opts out).
    • macOS: memory_pressure + the measured iostat sample (idle column located by header). Linux: /proc/meminfo MemAvailable + /proc/stat deltas.
    • Unknown or unmeasurable readings never alarm; probes are bounded well under FM_CHECK_TIMEOUT.
    • Episode record state/.load-guard dedupes: wake at episode start, when another metric joins, when memory crosses the spawn floor, and at most every remind_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 when config/load-guard is off; failures print LOAD_GUARD:.
  • bin/fm-spawn.sh: warns when a threshold is crossed; refuses a NEW launch below the memory spawn floor (default 15%) unless FM_LOAD_GUARD_OVERRIDE=<reason> is set (recorded as load_guard_override in the task record). Recovery (relaunch, dead-secondmate auto-recovery) only warns. An unmeasurable reading never refuses.
  • Response procedure: a "Load-guard wakes" section in the housekeeping skill (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 in AGENTS.md section 8.
  • Docs: docs/configuration.md "Load guard", docs/scripts.md, bootstrap-diagnostics, script headers.

Notes

  • An armed check counts as a reason to watch, so every armed home (including idle secondmates) keeps a live watcher.
  • On first session start after landing, a home's existing hand-written state/load-guard.check.sh is replaced by the generated shim (same check id).
  • config/load-guard is per home and not inherited by secondmate homes.
  • tests/lib.sh (and the real-spawn smoke/e2e safety helper) pin FM_LOAD_GUARD=off so 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.

Boxyboxy and others added 4 commits October 2, 2026 12:42
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.
@Boxyboxy
Boxyboxy merged commit a4e0556 into feat/omp-adaptor Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants