mac-yolo-safeguards

The OS-level safeguards layer for AI agent loops. Runaway-kill, hard timeouts, and resource limits — the enforcement your agent harness is missing — so coding agents (Antigravity agy, Claude Code, Cursor, Codex) running in YOLO mode can't burn your tokens or freeze your Mac.

TL;DR — On 2026-05-26 my Mac hit load average 307 because an AI agent kept booting iOS Simulators in a loop. This repo is the four-piece kit that stopped it: a wrapper, a LaunchAgent, a plist, and a 12-point health check. MIT, telemetry off by default, symlinks-only install. Full incident write-up: CASE-STUDY.md.

Paid reliability help: Book 20-min triage | Partner Pilot | Public-safe paid inquiry

   me:  it's just ONE simulator, what could go wrong
   Mac:  *256 simruntime processes, fan = jet engine, load 307*

        ...the guard (with sunglasses):
        nice sims, you won't need them anymore
        ^--- this repo ---^

Hosted Hermes / always-on agents: platforms keep agents online; this kit stops runaway loops and Mac freezes when real work still burns tokens or load. Positioning: docs/HERMES-HOSTED-RELIABILITY.md.

For Teams And Partners

If you only need the free Mac guard, install it below.

Built your app with AI (Cursor, Claude Code, Lovable, Bolt) and not sure it's safe to launch? Get it audited for leaked secrets, runaway cloud bills, and crash-under-load bugs → AI App Safety Audit (5-day fixed-fee, plain-English report).

If you run agents for a team or clients and have a repeated failure that costs hours, tokens, delivery risk, or client trust, start with AI Agent Reliability Hardening:

Private workflow details: book a 20-minute triage or email iganapolsky@gmail.com. Public-safe intake: open a paid hardening inquiry.

Background

On 2026-05-26 an iPhone 17 simulator was auto-booted (first by macOS window restoration, later by Antigravity's agy agent running with --dangerously-skip-permissions) and slammed the Mac to load average 307 with 256+ simulator runtime processes. This repo holds the safeguards that prevent recurrence.

Contents

The base installer uses symlinks back to this repo. The Grok fleet installer stages executable copies under ~/.hermes/grok45/ on each Mac and points the ~/.local/bin/ commands at those copies, so the remote machine never depends on a dirty or missing repository checkout.

Revenue tools write private *.md / *.tsv artifacts to business_os/revenue/ (not the repo root). After a local ops session:

./scripts/migrate-root-ops-to-business-os.sh   # move any legacy root clutter
./scripts/clean-private-root-artifacts.sh      # delete strays still in root

What this does NOT do

Scope is deliberately narrow. The kit does not:

• Manage arbitrary Mac memory pressure. If you have many editors + AI tools open and CleanMyMac yells about RAM, that's expected behavior — not a runaway. The kit detects runaway iOS Simulator spawning and only auto-reclaims known-safe memory hogs such as orphaned automation Chrome, redundant secondary browsers, and oversized Ollama llama-server workers under real pressure.
• Kill, quit, or otherwise touch GUI apps (Antigravity, Cursor, Xcode, Ghostty, Android Studio, browsers, IDEs). Ever. Hard rule. Foreground apps have unsaved work the user cares about more than they care about the freeze. The escalation path is a critical macOS alert, not a kill signal.
• Stop the agent itself from being memory-hungry. A running agy / claude / cursor-agent process consuming 1–2 GB is normal AI-agent behavior. The guard notifies (once per 30 min, debounced) when free memory drops below 15% and an AI process exceeds 1.5 GB RSS, but it only auto-kills known-safe worker/cache processes.
• Enable telemetry by default. Grok Build's optional external OTEL export remains double-opt-in and content-free; no prompt or tool details are exported. See § Telemetry and privacy.
• Work on Linux or Windows. macOS-only. The LaunchAgent, xcrun simctl, and simruntime process names are all Apple-specific.

If your symptom is "Mac is slow because I have 200 Chrome tabs and 6 IDEs open" — close some. That's not what this kit is for.

Install on a fresh Mac

git clone <this repo> ~/workspace/git/igor/mac-yolo-safeguards
cd ~/workspace/git/igor/mac-yolo-safeguards
./install.sh

install.sh creates the symlinks and bootstraps the LaunchAgent. It is idempotent — safe to re-run.

Install or refresh Grok 4.5 on the local Mac and hermes-mini with:

bash scripts/install-grok-yolo.sh --update

See Hermes Grok 4.5 Harness for standalone, Hermes, safety, authentication, and billing behavior.

After Grok Build went open source, install the high-ROI fleet integration (local Ollama/LiteLLM model routes + PreToolUse safety hooks) on both Macs:

bash scripts/install-grok-build-fleet.sh
grok-build-fleet --doctor --json

Details: Grok Build open-source fleet. Default cloud model is unchanged; use grok -m ollama-hermes-64k for local $0 runs.

When fleet zero-spend mode is active, the same grok-yolo command uses the open-source Grok Build harness with qwen3.5:9b-hermes-64k through http://127.0.0.1:11434/v1. Direct grok remains blocked because it can select a cloud model. Inspect the local route without making a model call:

grok-yolo --doctor --json
grok-yolo --dry-run --json

After routing real tasks, inspect the active backend and mine the prompt-free receipts without spending tokens:

hermes-yolo --route-status
hermes-harness-eval --write --json

Parallel Search is an optional retrieval candidate, not a silent provider call. The command explicitly selects Turbo for quick grounding, but remains dry-run unless the existing Google-SSO Parallel CLI session (preferred) or API-key fallback, paid approval, and a sufficient cost cap are all present:

hermes-search-turbo \
  --objective "Find the latest official agent retrieval architecture guidance" \
  --query "official agent retrieval architecture" \
  --query "agent retrieval evaluation guidance" \
  --max-results 10 \
  --json

Execute one capped Turbo request with --execute --paid-ok --max-cost-usd 0.001. Use --mode basic or --mode advanced only as a measured retrieval quality escalation; each costs $0.005 for the default ten results.

Wrapper configuration (env vars)

Hermes Runtime Readiness

Hermes can look healthy while its local fallback is only configured on paper. The high-signal checks are:

yolo-health
node tools/hermes-productivity-audit.js --json
node tools/local-inference-readiness.js

The runtime model is deliberately tiered:

• Ollama is acceptable for quick local fallback and smoke tests.
• A serious local inference path should expose an OpenAI-compatible /v1 API with predictable model loading, context length, logs, and concurrency behavior. vLLM or a LocalAI-style gateway is the evaluation target for that tier.
• terminal.cwd must point at an existing active repo. A stale cwd is treated as a reliability failure because Telegram/Hermes tools will run in the wrong project or return exit 130 interruptions.

Guard configuration (env vars)

The LaunchAgent reads these from the environment when sim-runaway-guard.sh runs. Override by editing the plist or wrapping the script.

Wrapper exit codes

Tests

Run the Node.js unit tests from this directory:

node tests/test-agent-decision-stack.js
node tests/test-durable-agent-loop.js
node tests/test-revenue-autonomous-loop.js
node tests/test-governed-agent-sales-copy.js
node tests/test-hermes-retrieval-harness.js

The wrapper has a 5-test verification suite. To re-run from this directory:

WRAPPER=./agy-yolo-wrapper.js
export AGY_YOLO_LOCK_PATH=/tmp/yolo-test-$$.lock AGY_YOLO_LOG_PATH=/tmp/yolo-test-$$.log

# 1. happy path
AGY_BIN=/bin/echo AGY_YOLO_NO_DEFAULT_ARGS=1 node $WRAPPER hi
# expect: exit 0

# 2. singleton
AGY_BIN=/bin/sleep AGY_YOLO_NO_DEFAULT_ARGS=1 node $WRAPPER 3 &
sleep 0.3
AGY_BIN=/bin/sleep AGY_YOLO_NO_DEFAULT_ARGS=1 node $WRAPPER 3
# expect: exit 2

# 3. timeout
AGY_BIN=/bin/sleep AGY_YOLO_NO_DEFAULT_ARGS=1 AGY_YOLO_TIMEOUT_MS=1000 node $WRAPPER 30
# expect: exit 124

# 4. stuck-loop watchdog
AGY_BIN=/usr/bin/yes AGY_YOLO_NO_DEFAULT_ARGS=1 AGY_YOLO_TIMEOUT_MS=60000 \
  AGY_YOLO_CPU_SAMPLE_MS=500 AGY_YOLO_CPU_STUCK_SAMPLES=2 AGY_YOLO_CPU_THRESHOLD=50 \
  node $WRAPPER > /dev/null
# expect: exit 124

# 5. spawn error
AGY_BIN=/nonexistent AGY_YOLO_NO_DEFAULT_ARGS=1 node $WRAPPER
# expect: exit 127

rm -f /tmp/yolo-test-$$.lock /tmp/yolo-test-$$.log

Guard E2E (browser reclaim + CPU autokill):

tests/test-secondary-browser-reclaim.sh

CI/CD

CI (.github/workflows/ci.yml) runs on every push/PR to main:

Local mirror before pushing:

./scripts/ci-verify.sh

CD — Hermes Mobile (com.iganapolsky.hermesmobile):

Firebase: hermes-mobile/docs/FIREBASE_CI.md (internal QA)

Google Play: hermes-mobile/docs/PLAY_RELEASE.md (LLC org, production track)

./scripts/sync-firebase-secrets.sh          # Firebase App Distribution
./scripts/sync-hermes-secrets.sh            # EAS / Apple (hermes-mobile/.env)

EAS: @igorganapolsky/hermes-mobile (4ed13e30-9b97-4ddd-8a12-59106cae90d6).

The incident this came from

Load average 307, 256+ simruntime processes, hard-reboot territory. Full timeline + 12/12 health-check output: CASE-STUDY.md.

Support & Paid Hardening

This kit is fully open-source (MIT-licensed), free to use, and enables zero telemetry by default.

If the safeguards saved your Mac from a freeze:

• ⭐ Star the repo — it is the strongest signal that more system-level AI safety tooling should exist.
• 💬 Open a public incident issue with non-sensitive details — this directly helps us tune the next CPU and memory threshold defaults.

For teams running AI agents in production workflows

One Mac freeze is annoying. The expensive problem is repeated agent behavior — runaway loops, retry storms, and forgotten autonomous sessions that quietly burn real money.

[!WARNING] API Billing Change (June 15, 2026): Anthropic is moving headless Agent SDK and CLI (claude -p) usage out of fixed-subscription pools and charging raw API rates. A runaway loop or recursive script will now directly drain your API credits in minutes. Safe execution boundaries are now financial protection.

Even with official updates (like v2.1.166 addressing the macOS bg-pty-host 100% CPU lockup), terminal agents still enter stuck loops, crash workflows, and burn thousands of tokens. The model isn't the issue; nothing caps the loop at the process layer before the bill lands.

AI Agent Hardening Sprint — $1,500. I take one recurring failure pattern in your agent workflow, root-cause it, and install the guardrails that block or escalate it — the Mac runaway guard plus ThumbGate memory gates — then leave you with a smoke test, before/after evidence, and handoff notes. Fixed scope, one workflow, proof at the end. If the failure costs you less than $1,500, use the free kit above instead and keep your money.

Best fit: founders and teams running Claude Code, Cursor, Codex, or Antigravity daily who can point to one failure that has cost real hours or dollars more than once.

Start here: email iganapolsky@gmail.com or book a 20-min triage via Cal.com with: the agent stack, the repeated failure, and what one incident cost you. Full scope: AI Agent Reliability Hardening.

Also available: the $499 Agent Reliability Diagnostic (20-minute call plus a written root-cause readout, no install) for smaller pain, and a $3,000 Partner Pilot (pay once) for agencies reselling reliability. Operator playbook: Sales Close Kit.

Public GitHub issues must stay public-safe. Do not post secrets, customer names, private repository details, payment data, or proprietary logs. Use the paid triage links above for private workflow details.

Telemetry and privacy

The Mac safeguard kit ships zero telemetry by default. Specifically:

• The simulator wrapper, guard, and health check make no network calls; they only read local process state (ps, uptime, xcrun simctl) and shell out to local binaries.
• All logs are written to /tmp/ (gitignored). Nothing leaves your Mac.
• No analytics, no error reporting, no usage pings.

The optional Grok Build integration is a separate surface. Its local model route uses loopback Ollama. External OpenTelemetry is off by default and requires Grok's master switch plus an exporter; the wrapper forces prompt and tool-detail content gates off. A configured OTLP collector therefore receives content-free usage/error metrics, never silently enabled analytics.

Verify it yourself:

grep -rE 'fetch|http\.|https\.|XMLHttpRequest|curl |wget |require\(.https.|require\(.http.' \
    agy-yolo-wrapper.js sim-runaway-guard.sh yolo-health install.sh
# expect: no matches

The maintainer's own launch-traffic analytics live in GitHub Insights → Traffic (free, GitHub-native, only the maintainer sees them), Cal.com bookings dashboard, and Stripe Dashboard — none of which involve any code shipped to your machine.

Related: the upstream version of this problem

This kit handles the blast radius when an AI agent goes off the rails — your Mac doesn't freeze, your simulators don't multiply, your IDEs keep their unsaved work.

It does not handle the bill for that misbehavior. Every retry loop, every "let me try a different approach", every hallucinated import that costs you tokens — those add up to $400–$1,500/mo of repeated-mistake spend on Claude / Cursor / Codex / Gemini bills.

If that's also your pain, the same author built ThumbGate — the Self-Improving Firewall for your AI Agents: open-source, MCP-compatible, thumbs-down once → that mistake is remembered, re-ranked, and can promote into a blocking gate on future agent calls. The paid hardening offers combine this Mac guard with ThumbGate's token-layer memory gates.

References

• Antigravity Lab: practical fix guide for high CPU/memory usage
• AGY CLI docs: https://antigravity.google/docs/cli-using
• Known sandbox-bypass issue: https://github.com/google-antigravity/antigravity-cli/issues/36