guard rails: no bound on files, graph size, or memory; a scan of a very large repo can exhaust the machine

[JordanCoin]

What happened

2026-09-04: an automated review ran two codemap builds concurrently over several repositories, two of them very large. Memory climbed until the machine became unusable and the run had to be killed by hand. codemap never refused, warned, or degraded; it kept building the graph.

What exists today

grep -rn 'Max' limits/ finds only output-size caps (MaxContextOutputBytes, handoff and diff budgets) and agentEditsMaxBytes. There is no cap on the number of files walked, the number of graph nodes or edges, resident memory, or scan wall time, and no flag to set one. --depth limits the printed tree only.

Proposed guard rails

1. A default file-count ceiling (for example 50,000 files) above which codemap stops, prints the count and the flag to raise it, and exits non-zero. --max-files N and --allow-large override.
2. A wall-clock budget for a full scan (default a few minutes) with the same stop-and-report behaviour; --scan-timeout.
3. A soft memory check: sample runtime.MemStats during the walk and graph build, and above a configurable budget (default a fraction of physical RAM), stop and report partial coverage with a resource-limit source, never a silent complete.
4. Watch daemons inherit the same limits and refuse to start on a repo above the ceiling, logging why.
5. Hooks never trigger a full scan on a repo above the ceiling; they emit a one-line notice instead.

Exit test

A synthetic tree of 200,000 small files: codemap . exits within a second with a clear message and non-zero status; with --allow-large it runs; memory stays under the configured budget or the run stops with resource-limit in coverage.

Related: #185 (duplicate daemons), #184 (hygiene), #148 (coverage honesty).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TcyheQmM3HCvxF5wRL3s5t