undomap

AGENT WRITE-ACCESS FLOOD MAP · PANEL 01 OF 03

Survey panel 01 · textures-app

Flood-zone survey of a directory Burnt-orange Zone VE covers the bytes an AI agent could erase with no way back; mustard Zone AE is slow undo; the high ground, Zone X, is clean tracked files.

0 B across 0 places your agent can erase forever

Which paths can your AI coding agent erase with no way back? One command maps them, ranked by permanent-loss bytes, with the cheapest fix for each.

$ npx github:Blackman99/undomap

UNDOMAP — FLOOD ZONES

Agent write-access series · contour interval 1/24 of the tree · datum: last commit

Panel note

Sheet 2

Zone VE register

Benchmarks in the velocity zone, biggest first. Each has the cheapest fix that actually protects it.

    Zone AE · slow undo

      Zone X · undoable

      Sheet 3

      Legend & method

      Zone letters borrowed from flood insurance rate maps: VE is where the water moves fast and nothing is rebuilt the same.

      Zone VE · permanent
      Gitignored or untracked and not regenerable. Anything outside a git work tree. Symlinks whose target sits outside the map. A repo with no remote, because its .git is the only copy of the history. Nothing covers it: no snapshot, no backup you told undomap about, no cloud history undomap could verify.
      Zone AE · slow undo
      Comes back, but costs time: node_modules, dist, .venv, target, compiled binaries. Uncommitted edits (the last commit returns, the edits don't). Commits not pushed anywhere. Fragile paths inside a Time Machine, btrfs, ZFS or Timeshift snapshot, or behind a verified cloud levee.
      Levee · cloud history
      The project sits in a Dropbox, OneDrive or Google Drive folder and undomap could confirm the client is running, so deleted and overwritten files come back from its version history; the land behind the levee is Zone AE. It still breaks where the provider skips things: ignore marks, temp files, files over the size limit. Dashed means provisionally accredited: it looks like a sync folder but undomap couldn't confirm it, so nothing behind it is counted. iCloud Drive keeps deletes, not overwrites, so it never lowers a zone. How it decides
      Zone X · undoable
      Clean tracked files. git checkout / git restore brings them back, as long as .git survives.
      Benchmark
      One per significant path: a whole ignored directory, an untracked tree, a dirty file. Labels give the bytes at stake.
      Staked benchmark
      You staked it in .undomap.json with "permanent": it looks regenerable by name (dist/, .cache/) but you know it isn't. It stays in Zone VE unless a snapshot, a backup you listed or verified cloud history really covers it.
      Section A–A′. undomap walks the ground station by station and never writes: git runs with GIT_OPTIONAL_LOCKS=0, so not even the index is refreshed.
      1. BM 1 · git status --porcelain=v2 --ignored finds tracked, dirty, untracked and ignored trees; nested repos and submodules are surveyed on their own.
      2. BM 2 · regenerable? Known build output by name, plus content markers: pyvenv.cfg, CACHEDIR.TAG, ELF and Mach-O headers. Your "permanent" list overrules the guess.
      3. BM 3 · remotes A repo with no remote is permanent as a whole; commits not on any remote are slow undo.
      4. BM 4 · snapshots tmutil on macOS, snapper, ZFS and Timeshift on Linux. The Trash doesn't count: rm never goes there.
      5. BM 5 · cloud sync iCloud Drive, Dropbox, OneDrive, Google Drive. A folder counts only when the client's own config names it, the app is running and the path isn't ignored, a temp file or over the size limit. Otherwise it's possible cloud versioning, unverified, and stays Zone VE.

      Sheet 4

      Title block · install & use

      Run once
      npx github:Blackman99/undomap            # this directory
npx github:Blackman99/undomap ~/code --fix

      Node 18.17+ and git. One bundled file, no runtime dependencies. Read-only.

      Install
      npm install -g github:Blackman99/undomap

      Or the tarball from Releases.

      Config
      {
  "permanent": [".cache/models/"],
  "regenerable": ["out/"],
  "backedUp": ["data/"]
}

      .undomap.json at the root you map. Who wins: git's facts, then real coverage (a snapshot, your backedUp, verified cloud history), then permanent, then anything that looks regenerable. --json marks forced paths with forcedBy. Precedence

      Exit codes

      0 nothing permanent · 1 something in Zone VE · 2 usage or hard error. --max-permanent 1MB lets small things through; --json for scripts.

      MCP
      claude mcp add undomap -- npx -y github:Blackman99/undomap mcp

      Read-only tools map_report and list_permanent: the agent can check what a git clean -fdx would destroy before it runs one.

      CI / runner
      - uses: Blackman99/undomap@v0
  with:
    path: .
    fail-on-permanent: true

      Before an agent step on a self-hosted runner or a mounted volume: the job summary gets the Zone VE table.

      Not this

      undomap doesn't block commands and doesn't take backups. It tells you where protection is missing. Pair it with a guard (deny-lists, sandboxes) or checkpoints (agentckpt).

      Sheet 5

      Survey your own ground

      Run npx github:Blackman99/undomap --json > undomap.json, then drop the file here. It is drawn in this tab. Nothing is uploaded.

      …or paste the JSON