Bound gitleaks scans on macOS: per-user lock and 6 GiB footprint watchdog (Jetsam 2026-09-24) - #193

Why

At 09:45 and 09:46 EDT on 2026-09-24, Jetsam on the 24 GB MacBook Pro (M5 Pro, macOS 26.5.1) recorded three concurrent gitleaks 8.30.1 processes. Together they used 52.8 GiB, then 58.2 GiB, with the compressor holding about 80 to 84 GiB of data. macOS killed 405 processes, then 4,255.

Root cause. gitleaks' filter() calls report.Finding.Redact for every finding. Redact runs strings.ReplaceAll over Finding.Line, so it keeps one full copy of the matched line per finding. In git mode, a -U0 hunk holds whole lines. The generated explorer (docs/ecosystem/index.html) is one 12,889,851-byte line with 2,335 findings. That is about 30 GB, or 28 GiB, matching the 28.25 GiB process in the Jetsam report.

• The two largest processes came from the global pre-commit hook: gitleaks git --pre-commit --staged --redact …. The hook ran on scratch commits from tests/test_catalog_freshness_propose.py, whose TrackedExplorerSubprocessTests force-adds the explorer. These runs happened before Make tests hermetic against global and system git config #181 made the tests' git config hermetic.
• The recipe's all-refs gitleaks git --redact=100 hits the same problem: 240 commits in the history touch the explorer.
• dir mode reads files in bounded chunks, so it stays near 0.13 GiB.

What changes

• adoption/tools/gitleaks-guarded-macos is a macOS counterpart to gitleaks-guarded, using only the Python standard library. It keeps upstream arguments, output and exit codes.
  • Lock: one scan per user through a flock on ~/.local/state/ecosystem-gitleaks.lock. A read-only descriptor is enough, so sandboxed clients can take it. A second scan waits up to 60 s, then exits 75.
  • Caps: every 50 ms it sums the physical footprint (the figure Jetsam uses) of the scan's whole process tree. Above 6 GiB it SIGKILLs the tree and exits 137. After 600 s it stops the tree and exits 124. Callers can lower either cap but never raise it.
  • Refusals: exits 78 before any scan starts, for example when the binary or lock is unusable.
• tests/test_gitleaks_guarded_macos.py: structural checks on every host, a refusal check off macOS, and on macOS integration checks against stub binaries. They cover exit codes, the memory cap on a grandchild, the runtime cap, lock busy/wait/serialisation/holding, and each refusal.
• Receipt: evidence/receipts/gitleaks-macos-memory-bound-20260924.json holds sanitized before/after measurements, registered in manifests/evidence.json. It is not added to the gitleaks component's evidence_ids, because tests/test_stack_lifecycle would then require a row in the token-native saturation audit, which belongs to another lane. The harness is under evidence/artifacts/gitleaks-macos-memory-bound-20260924/.
• Docs: adoption/tools/README.md gets a macOS section that replaces "macOS has no equivalent". recipes/README.md and adoption/update.md point macOS runs at the guard.

Measurements (this Mac, one scan at a time)

Peak is the sampled physical footprint of the process group (gitleaks + git + guard). The "before" runs were stopped by the measurement harness at its own cap, not by gitleaks.

Rejected alternatives, all measured on the same host:

• --max-target-megabytes fails open. It skips the oversized fragment at debug log level, so the staged explorer's 2,335 findings came back as no leaks found with exit 0.
• Top-level path exclusions skip whole files in both modes (see the .gitleaks.toml header), and dir memory was already bounded.
• GOMEMLIMIT=4GiB still crossed the cap, because the growth is live findings.
• An unprivileged Jetsam task limit (memorystatus_control) returns EPERM.

Limits. This is a user-space watchdog, not a kernel limit: measured overshoot was 0.04–0.20 GiB. If the guard itself is SIGKILLed, the scan runs on unwatched, though it keeps the lock. There is no CPU or task cap. A scan stopped at the cap produces no result. That is fail-closed, not coverage: this repository's all-refs history still has no complete redacted pass on macOS.

Hand-off (not edited here)

The global hook (~/.config/git/hooks/pre-commit) is managed by agent-ecosystem's config/git/hooks/dispatch. Its owner under the single-writer decision in seathatflowsinourveins/agent-ecosystem#28 is the foundation-lane-setup session. The change is handed off in seathatflowsinourveins/agent-ecosystem#40, which that session has taken. It reviewed this guard at b8cc293 and will vendor it pinned at the merge commit. The hand-off covers installing the guard, creating the lock once outside any sandbox, having the dispatcher call the guard, and routing the history-mirror scans through it. Nothing was installed on this host's PATH, no lock was created at the default path, and nothing global was edited.

Checks

• python3 scripts/validate.py: passed (69 components, 144 receipts, 5,239 hashed files).
• GITLEAKS_TESTS_REQUIRED=1 python3 -m unittest tests.test_gitleaks_config tests.test_adoption_guarded_runners tests.test_gitleaks_guarded_macos: 66 tests OK, 13 skipped (12 need a systemd --user scope; one runs only off macOS). Passes both sandboxed and unsandboxed.
• python3 -m unittest discover -s tests (unsandboxed, this Mac, head a1d446b): 3,958 tests, 1 failure, 511 skipped. The failure is LlamaWrapperQuotingTests.test_install_path_with_shell_syntax_is_data_in_the_wrapper, the known real-Mac failure (SIP strips DYLD_LIBRARY_PATH) that Make the llama wrapper quoting test pass on SIP-enabled Macs (wrapper unaffected) #178 addresses; this PR doesn't touch it.
• An earlier full run on b8cc293 also failed tests/test_stack_lifecycle because of the component evidence link, fixed in a1d446b. That run also had 21 guard-test errors: an aborted local rebase briefly deleted the guard while it ran, so those errors are not results.
• CI-configuration gitleaks scan of this commit, through the guard, inside the sandbox: 1 commit, no leaks.

Follow-ups

• Secret-storage practice: per-host 0600 store, agent read guard hook + deny rules, managed-profile install, names-only checker #182 (merged while this was in progress) adds scripts/git-hooks/pre-commit, which runs the same --pre-commit --staged --redact scan without a bound. Routing it through this guard on macOS is flagged as a separate task.
• The stack.json form with an absolute "${PROJECT_ROOT}" reports 219 findings in a clean worktree, because the path-scoped allowlists and .gitleaksignore fingerprints are relative. gitleaks dir . from the main checkout also descends into the nested .claude/worktrees. This is flagged as a separate task.

🤖 Generated with Claude Code