Safety Model
Read this before installing — it is the point of the project.
Dry-run by default
Section titled “Dry-run by default”Every mutating command plans and reports but writes nothing until you pass --execute. Dry runs print a DRY RUN — no changes will be made (pass --execute to apply) banner, and in dry-run mode the provider is wrapped in a proxy whose mutating methods throw — a planning-pass bug physically cannot mutate mail.
The never-delete guarantee
Section titled “The never-delete guarantee”Three layers, from interface to wire:
- The
MailProviderinterface has no delete methods and never will. - The JMAP layer additionally runtime-asserts that no request carries a
destroykey before any bytes leave the process. archive()only removes the Inbox label (and adds Archive) — the worst any bug can do is mislabel or archive mail, never lose it.
Confirmation above 100 mutations
Section titled “Confirmation above 100 mutations”A run planning more than 100 mutations prompts for confirmation. --yes skips the prompt; a non-interactive run without --yes refuses the whole batch (sweep/file then exit 1).
The --max cap
Section titled “The --max cap”Every scanning command accepts a hard cap on emails scanned per run.
Append-only TSV audit + resume
Section titled “Append-only TSV audit + resume”sweep and file log every mutated email id to an append-only TSV before the next batch runs, so an interrupted run resumes without duplicating work.
Tokens live in the environment only
Section titled “Tokens live in the environment only”The config loader rejects secret-shaped keys and token-shaped values in config files, and errors/reports pass through a redaction chokepoint.
MCP-server writes are gated
Section titled “MCP-server writes are gated”The MCP server forces every tool into dry-run unless started with --allow-execute (or FAST_CLASSIFIER_ALLOW_WRITES=1), and marks forced results with forcedDryRun: true. See the MCP server guide for the intended agent loop.