## TL;DR

A 4GB monorepo defeats single-pass scans. Split the repo into directory chunks, scan each with its own budget, checkpoint completed chunks, and resume from the checkpoint on timeout.

## Error

```text
scanner agent failed with timeout scanning a 4gb monorepo
```

## Steps

1. Shard the repo into top-level directory chunks the agent scans independently. Expected: bounded work per chunk.
2. Give each chunk its own timeout and retry, independent of the others. Expected: one slow chunk does not kill the run.
3. Write a checkpoint file as each chunk completes. Expected: resume skips finished chunks.
4. Exclude generated, vendored, and binary-heavy directories up front. Expected: far less work.
5. Merge chunk reports into one findings file at the end. Expected: complete coverage.

## When to use

- Agent scans timing out on very large repos.
- Designing resilient scan orchestration.

## When not to use

- Timeouts on small repos (fix the scanner or its config).
- One-off manual scans (just raise the timeout).

## Tool compatibility

- Gitleaks, trufflehog; agent orchestration with checkpoints.

## Variant phrasings

### scan times out on huge repo

Chunk it.

### agent scan killed on monorepo

Same sharding fix.

## Why it happens

Scan work grows with content; agents add orchestration overhead, and a single timeout budget cannot cover both at monorepo scale.

## Edge cases

- Cross-chunk findings (same secret in two dirs) need dedup at merge.
- Checkpoints must be atomic; partial writes corrupt resume.
- Shard boundaries should follow team ownership for triage.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_90NP_ZESu7lz58Ij7LpbSg