perf(test): cap CPU at 85% via cpulimit/nice, reduce parallelism to 85% nproc

Keeps the machine responsive during test runs:
- make test: wraps go test with cpulimit -l (nproc*85) when cpulimit is
  installed; falls back to nice -n 15 otherwise. -p and -parallel default
  to floor(nproc * 0.85) = 10 on a 12-core machine.
- pre-commit hook: same CPU limiter + same 85% parallelism.
  CGO_ENABLED=0 is exported before the runner so it works with both
  cpulimit and nice (neither accepts env-var assignments as arguments).
- Reset baseline to 60s (realistic for nice -n 15 + p=10).

Override examples:
  make test                   # 85% CPU, auto parallelism
  make test TEST_P=4          # manual package concurrency

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: claude

.githooks/checks/02-unit-tests.sh

@@ -1,25 +1,41 @@
 #!/bin/sh
 # L1: unit tests — fast, no external deps, no Docker.
 #
-# Time guard: elapsed seconds are compared against .test-time-baseline.
-# The baseline file is committed so the reference survives machine changes.
+# CPU is capped at 85% so the machine stays responsive:
+#   - cpulimit(1) if installed: hard CPU cap via kernel scheduler
+#   - otherwise: nice -n 15 (lower scheduling priority)
 #
-# .test-time-baseline  — last recorded elapsed time (seconds). Updated on
-#                        every passing run. Fail if current > baseline * 1.5.
-#
-# To reset after an intentional perf change:
-#   echo <new_seconds> > .test-time-baseline
-#   git add .test-time-baseline && git commit -m "perf: reset test baseline"
+# Time guard: compare elapsed seconds against .test-time-baseline (committed).
+# Fail if current > baseline * 1.5. Update baseline on every passing run.
+# To reset: echo <new_seconds> > .test-time-baseline
 
 REPO="$(git rev-parse --show-toplevel)"
 LOG_FILE="${REPO}/.test-fail.log"
 BASELINE_FILE="${REPO}/.test-time-baseline"
 rm -f "$LOG_FILE"
 
-echo "pre-commit: running unit tests..."
+# Determine parallelism: 85% of nproc.
+NCPU=$(nproc)
+P85=$(( NCPU * 85 / 100 ))
+[ "$P85" -lt 1 ] && P85=1
+
+# CPU limiter: cpulimit if available, else nice.
+if command -v cpulimit >/dev/null 2>&1; then
+    LIMIT_PCT=$(( NCPU * 85 ))
+    RUNNER="cpulimit -l ${LIMIT_PCT} --"
+else
+    RUNNER="nice -n 15"
+fi
+
+echo "pre-commit: running unit tests (cpu≤85%, p=${P85})..."
 
+export CGO_ENABLED=0
 START=$(date +%s)
-if ! CGO_ENABLED=0 go test -timeout 180s -p "$(nproc)" -parallel "$(nproc)" ./... > "$LOG_FILE" 2>&1; then
+if ! $RUNNER go test \
+        -timeout 180s \
+        -p "${P85}" \
+        -parallel "${P85}" \
+        ./... > "$LOG_FILE" 2>&1; then
     echo "" >&2
     echo "COMMIT BLOCKED: unit tests failed." >&2
     echo "" >&2
@@ -32,10 +48,10 @@ END=$(date +%s)
 ELAPSED=$((END - START))
 rm -f "$LOG_FILE"
 
-# Time guard: compare against last successful run.
+# Time guard.
 if [ -f "$BASELINE_FILE" ]; then
     BASELINE=$(cat "$BASELINE_FILE")
-    THRESHOLD=$((BASELINE + BASELINE / 2))   # 150% of baseline
+    THRESHOLD=$((BASELINE + BASELINE / 2))
     if [ "$ELAPSED" -gt "$THRESHOLD" ]; then
         echo "" >&2
         echo "COMMIT BLOCKED: test time regression." >&2
@@ -47,6 +63,5 @@ if [ -f "$BASELINE_FILE" ]; then
     fi
 fi
 
-# Update baseline to current run time.
 echo "$ELAPSED" > "$BASELINE_FILE"
 echo "pre-commit: unit tests passed (${ELAPSED}s)."

Makefile

@@ -34,13 +34,21 @@ DAEMON_NAME = mxcli-daemon
 # Clean version for VS Code extension (must be valid semver: major.minor.patch)
 VSCE_VERSION = $(shell echo "$(VERSION)" | sed 's/^v//; s/-.*//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$$' || echo "0.0.0")
 
-# Max parallel test packages (lower = less memory; override with: make test TEST_P=8)
-TEST_P ?= $(shell nproc)
-# Max concurrent tests within a package (default: GOMAXPROCS). Lower values
-# reduce peak memory and I/O pressure. Override: make test TEST_PARALLEL=4
-TEST_PARALLEL ?= $(shell nproc)
-# Hard ceiling on how long the full test suite may run. Fail fast rather
-# than hang CI. Override: make test TEST_TIMEOUT=300s
+# Limit CPU to 85% so the machine stays responsive during test runs.
+# Uses cpulimit(1) when installed; falls back to nice -n 15.
+# cpulimit -l value = nproc * 85 (percentage of one core per core).
+_NCPU         := $(shell nproc)
+_CPU_LIMIT_L  := $(shell echo "$(_NCPU) * 85" | bc)
+_CPU_RUNNER   := $(shell command -v cpulimit >/dev/null 2>&1 \
+                   && echo "cpulimit -l $(_CPU_LIMIT_L) --" \
+                   || echo "nice -n 15")
+
+# Max concurrent packages and tests, capped at 85% of nproc.
+_85PCT        := $(shell echo "$(_NCPU) * 85 / 100" | bc)
+TEST_P        ?= $(_85PCT)
+TEST_PARALLEL ?= $(_85PCT)
+
+# Hard ceiling on how long the full test suite may run.
 TEST_TIMEOUT ?= 180s
 
 .PHONY: build build-debug release clean test test-mdl report report-bench report-reset-baseline grammar sync-skills sync-commands sync-lint-rules sync-changelog sync-examples sync-all docs documentation docs-site docs-serve source-tree sbom sbom-report lint lint-go fmt vet update-helpdesk-golden test-helpdesk-regression setup
@@ -170,9 +178,12 @@ release: clean sync-all
 	@echo "  Launchers: mxcli-{os}-{arch}"
 	@echo "  Daemons:   mxcli-daemon-{os}-{arch}.tar.zst (or .zip)"
 
-# Run tests. TEST_TIMEOUT guards against hangs; TEST_P caps concurrent packages
-# to prevent I/O storms; TEST_PARALLEL caps concurrent tests within a package.
+# Run tests. CPU is capped at 85% via _CPU_RUNNER (cpulimit or nice -n 15)
+# so the machine stays responsive. TEST_P/TEST_PARALLEL default to 85% nproc.
 test:
+	$(_CPU_RUNNER) $(MAKE) _test-inner
+
+_test-inner:
 	CGO_ENABLED=0 go test -timeout $(TEST_TIMEOUT) -p $(TEST_P) -parallel $(TEST_PARALLEL) ./...
 
 # Run full test suite and generate layered report (terminal + HTML)