/system-performance-guardrail

name: system-performance-guardrail
description: >-
  Measure, root-cause, fix, verify and record performance contention on a developer machine: cloud-sync daemons (iCloud Drive, OneDrive, Dropbox, Google Drive), file indexers, AI-tool MCP server fleets, and automation browsers left behind by tests and browser skills. Trigger when the machine is slow, apps freeze, browser or MCP tool calls time out, load exceeds the core count, or before and after any UI/UX/performance test run. Includes the L0–L4 optimisation scale and the test-hygiene contract.

system-performance-guardrail — the machine is part of the test environment

Agentic delivery runs many things at once on one laptop: several AI CLI sessions, each with its own MCP servers; browser automation (Playwright, Selenium, Puppeteer, a CDP harness); indexers; cloud-sync clients; dev servers; test suites. When they contend, the symptoms look like product bugs — timeouts, flaky UI tests, "the site is slow" — and the next agent spends its budget diagnosing a healthy remote. This skill makes the machine's state a measured input, gives each signature a cause and a bounded action, and makes cleanup a contract rather than a hope.

Script: `scripts/perf-guardrail.sh` (bash 3.2, macOS, no sudo, no third-party tools). Read-only except `cleanup --yes` (kills), `icloud throttle|restore` (signals) and `record` (appends). Linux notes are at the end.

The loop

| Phase | Command | Output | |---|---|---| | 1 Measure | `perf-guardrail.sh snapshot --save /tmp/pre.snap`, `hangs 7`, `fleet`, `orphans` (`rows` gives the same as machine-readable lines for CI gates) | load vs cores, memory, swap, top consumers **with the session that owns them**, sync daemons (a stopped one is flagged), indexer, MCP fleets, automation browsers, and every app hang report with the frames that explain it | | 2 Attribute | the signature table below | one cause per signature, never "the Mac is slow" | | 3 Act | only the sanctioned actions below | bounded, reversible, one attempt | | 4 Verify | `perf-guardrail.sh verify /tmp/pre.snap`, `hangs 1` | a before → after table in the reply; a fix without numbers did not happen | | 5 Record | `perf-guardrail.sh record "<one line>"` | a dated lessons file the next agent reads before re-deriving anything |

Interpretation rules: load average on macOS counts runnable threads only, so high load with free memory is CPU contention, not paging; `ps %cpu` is a lifetime average, confirm live with `top -l 2 -s 1 -pid`; a *frozen* app (a hang report) is almost never memory — read the report.

Signature → cause → action

| Signature | Cause | Action | |---|---|---| | Hang reports whose main thread waits in the cloud-sync client (`ubiquityIdentityToken` → `CloudDocs` → `bird` on macOS); the sync daemon shows stat `T` | someone stopped the daemon with SIGSTOP; its IPC port stays open and every caller waits forever | `perf-guardrail.sh icloud restore` (SIGCONT). **Never SIGSTOP a sync daemon**: a stopped process is worse than a dead one, because a dead one returns an error and a stopped one returns nothing | | Load far above the core count, memory fine, a dozen `npm exec …@latest` / `npx` processes at 60–80% CPU each | an AI CLI run starting its entire MCP server list; `@latest` re-resolves against the registry on every start | `fleet` to find the owner; remove servers the run does not use; pin versions; prefer remote (HTTP) MCP servers over per-session stdio processes | | Indexer (`mds_stores`, Windows Search) at 150–250% CPU, workers respawning | indexing git repositories and `node_modules` inside a cloud-synced folder | keep repositories outside the sync root; exclude dev trees from the indexer | | `git`, `rsync`, `mv` asleep for minutes at 0% CPU on a synced path | evicted ("online-only") files being materialised; moving a tree out of the sync root downloads all of it first | work outside the sync root; copy out, verify against `origin`, delete in place — never `mv` out. Git state read inside a sync root is not trustworthy: the client can rewrite `.git` from a stale cloud snapshot | | Sync client at 50–100% CPU with hundreds of item-not-found errors per 30 s | retry storm after a mass deletion inside the sync root | one restart of the client; then let it drain (overnight, if needed); last resort: sign the folder out and back in | | Browser family memory > 6 GB, or a headless / throwaway-profile browser or WebDriver whose launcher is gone | a test or browser skill opened it and never closed it | `perf-guardrail.sh cleanup` lists the candidates; `cleanup --yes` kills them; `--all --yes` every disposable one after a test run. Only **disposable** browsers qualify: headless, or a profile under a temp dir / Playwright / Puppeteer / Selenium / harness path (extend with `PERF_DISPOSABLE_RE`). A browser on a normal profile is never a candidate, even with `--remote-debugging-port` — that is a developer's DevTools session; `PERF_KEEP_RE` protects anything else | | Several AI CLI sessions each holding stdio MCP children | every session starts its own servers | close idle sessions; remote servers where they exist |

Sanctioned actions and guards

Safe, reversible, no permission needed: SIGCONT a stopped daemon; throttle a sync client to background priority (`taskpolicy -b` on macOS, `renice`/`ionice` on Linux) rather than stopping it; kill disposable automation browsers and drivers (`cleanup --yes`; dry run first); remove unused MCP servers after backing up the config; one `killall` of a wedged daemon that its supervisor will respawn.

Needs the operator: system extensions, privileged daemons, indexer privacy lists, turning "optimise storage" off (check how many gigabytes would download first).

Never: SIGSTOP a daemon; unload a system-protected service; `mv` a tree out of a sync root; kill by name pattern without reading the parent chain; loop a kill.

The cloud-sync and performance optimisation scale

Use it to say where a machine or a team