@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/memory/repomap.ts

@@ -0,0 +1,516 @@
+// A compact, persistent map of a code folder: what is where and what each important file exports, so an agent does
+// not rediscover the same files every session. Built from the git working tree (`git ls-files`, so .gitignore is
+// respected) with regex-level symbol extraction, no model, no network, deterministic.
+//
+// Freshness: a stale map is worse than none, so the cache key is HEAD + `git status` + the size and mtime of every
+// file git reports as modified or untracked (an edit that leaves the status letter unchanged still changes the key).
+// Cached at <home>/.brain/cache/repomap-<hash of cwd>.json; BRAIN_NO_CACHE=1 bypasses it.
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { basename, extname, join, resolve } from "node:path"
+import { approxTokens } from "./types.ts"
+
+export const REPOMAP_TOKENS = 1_500
+/** Files over this many bytes are never read. */
+export const MAX_FILE_BYTES = 200 * 1024
+const MAX_FILES_READ = 4_000
+const MAX_TOTAL_BYTES = 48 * 1024 * 1024
+const MAX_WALK_FILES = 6_000
+const MAX_SYMBOLS_PER_FILE = 14
+const MAX_LINE = 260
+/** Bumped when the output format changes, so old caches are not served. */
+const FORMAT = 2
+
+export interface RepoMap {
+  text: string
+  tokens: number
+  /** The freshness key the map was built for (HEAD plus a hash of the working-tree state), when known. */
+  head?: string
+}
+
+// ---------------------------------------------------------------- files
+
+interface Listing {
+  files: string[] // relative to cwd, '/' separated, sorted
+  git: boolean
+  /** Recently changed files, newest first (git only). */
+  recent: string[]
+  /** Files with uncommitted changes (git only). */
+  dirty: Set<string>
+}
+
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "out", "target", "vendor", "coverage", "venv", "env", "__pycache__", "site-packages", "bower_components"])
+
+function git(cwd: string, args: string[]): string | undefined {
+  try {
+    const p = Bun.spawnSync(["git", "-c", "core.quotepath=off", ...args], { cwd, stdout: "pipe", stderr: "ignore", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } })
+    return p.exitCode === 0 ? p.stdout.toString() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function walk(cwd: string): string[] {
+  const out: string[] = []
+  const rec = (rel: string, depth: number) => {
+    if (out.length >= MAX_WALK_FILES || depth > 8) return
+    let names: string[]
+    try {
+      names = readdirSync(join(cwd, rel)).sort()
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (out.length >= MAX_WALK_FILES) return
+      if (name.startsWith(".")) continue
+      const r = rel ? `${rel}/${name}` : name
+      let st
+      try {
+        st = statSync(join(cwd, r))
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) {
+        if (!SKIP_DIRS.has(name)) rec(r, depth + 1)
+      } else if (st.isFile()) out.push(r)
+    }
+  }
+  rec("", 0)
+  return out
+}
+
+function list(cwd: string): Listing {
+  const inside = git(cwd, ["rev-parse", "--is-inside-work-tree"])?.trim() === "true"
+  if (!inside) return { files: walk(cwd), git: false, recent: [], dirty: new Set() }
+  const tracked = (git(cwd, ["ls-files", "-co", "--exclude-standard", "-z"]) ?? "").split("\0").filter(Boolean)
+  // A tracked file that was deleted in the working tree is still listed by ls-files.
+  const files = [...new Set(tracked)].filter((f) => !f.split("/").includes("node_modules") && existsSync(join(cwd, f))).sort()
+  const recent: string[] = []
+  const log = git(cwd, ["log", "-n", "300", "--name-only", "--pretty=format:", "--relative", "--", "."]) ?? ""
+  const have = new Set(files)
+  for (const l of log.split("\n")) if (l && have.has(l) && !recent.includes(l)) recent.push(l)
+  return { files, git: true, recent, dirty: new Set(dirtyFiles(cwd)) }
+}
+
+/** Files with uncommitted changes or not yet tracked, relative to cwd. */
+function dirtyFiles(cwd: string): string[] {
+  const out = git(cwd, ["ls-files", "-m", "-o", "--exclude-standard", "-z"]) ?? ""
+  return [...new Set(out.split("\0").filter(Boolean))].sort()
+}
+
+/** The freshness key of the folder's current state. Cheap: a few git calls and a stat per dirty file. */
+export function repoKey(cwd: string, maxTokens = REPOMAP_TOKENS): string {
+  const h = createHash("sha256")
+  h.update(`v${FORMAT}\0${maxTokens}\0`)
+  const inside = git(cwd, ["rev-parse", "--is-inside-work-tree"])?.trim() === "true"
+  let head = "nogit"
+  if (inside) {
+    head = git(cwd, ["rev-parse", "HEAD"])?.trim() || "nohead"
+    h.update(`${head}\0`)
+    h.update(git(cwd, ["status", "--porcelain", "-uall", "--", "."]) ?? "")
+    for (const f of dirtyFiles(cwd)) h.update(`\0${f}:${statKey(join(cwd, f))}`)
+    // A staged-only or committed-away change shows in status/HEAD; the stats above catch content edits.
+  } else {
+    for (const f of walk(cwd)) h.update(`\0${f}:${statKey(join(cwd, f))}`)
+  }
+  return `${head.slice(0, 12)}-${h.digest("hex").slice(0, 16)}`
+}
+
+function statKey(p: string): string {
+  try {
+    const s = statSync(p)
+    return `${s.size}:${Math.round(s.mtimeMs)}`
+  } catch {
+    return "gone"
+  }
+}
+
+// ---------------------------------------------------------------- symbols
+
+const LANG: Record<string, string> = {
+  ".ts": "ts", ".tsx": "ts", ".mts": "ts", ".cts": "ts", ".js": "ts", ".jsx": "ts", ".mjs": "ts", ".cjs": "ts",
+  ".py": "py", ".go": "go", ".rs": "rs", ".java": "java", ".kt": "kt", ".kts": "kt", ".rb": "rb",
+  ".h": "c", ".hpp": "c", ".hh": "c", ".hxx": "c",
+}
+/** Source files we read for mentions even though they yield no symbols (so references from them still count). */
+const MENTION_ONLY = new Set([".c", ".cc", ".cpp", ".cxx", ".swift", ".cs", ".php", ".scala", ".sh", ".vue", ".svelte", ".md", ".json", ".toml", ".yaml", ".yml"])
+
+type Kind = "fn" | "class" | "type" | "const" | "mod"
+interface Sym {
+  kind: Kind
+  name: string
+}
+
+const KIND_LABEL: Record<Kind, string> = { fn: "fn", class: "class", type: "type", const: "const", mod: "mod" }
+
+/** Exported / public symbols of one file, in order of appearance, without duplicates. Regex-level: good enough to orient, not a parser. */
+export function extractSymbols(lang: string, text: string): Sym[] {
+  const out: Sym[] = []
+  const seen = new Set<string>()
+  const add = (kind: Kind, name: string | undefined) => {
+    if (!name || seen.has(name)) return
+    seen.add(name)
+    out.push({ kind, name })
+  }
+  const lines = text.split("\n")
+  switch (lang) {
+    case "ts": {
+      for (const l of lines) {
+        if (!l.startsWith("export")) continue
+        let m = l.match(/^export\s+(?:default\s+)?(?:declare\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/)
+        if (m) {
+          add("fn", m[1])
+          continue
+        }
+        m = l.match(/^export\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/)
+        if (m) {
+          add("class", m[1])
+          continue
+        }
+        m = l.match(/^export\s+(?:declare\s+)?(?:interface|type|(?:const\s+)?enum)\s+([A-Za-z_$][\w$]*)/)
+        if (m) {
+          add("type", m[1])
+          continue
+        }
+        m = l.match(/^export\s+(?:declare\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]*)?=\s*(async\s+)?(\(|[A-Za-z_$][\w$]*\s*=>|function)/)
+        if (m) {
+          add("fn", m[1])
+          continue
+        }
+        m = l.match(/^export\s+(?:declare\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)/)
+        if (m) {
+          add("const", m[1])
+          continue
+        }
+        m = l.match(/^export\s+(?:type\s+)?\{([^}]*)\}/)
+        if (m) {
+          for (const part of m[1]!.split(",")) {
+            const n = part.trim().split(/\s+as\s+/).pop()?.replace(/^type\s+/, "").trim()
+            if (n && /^[A-Za-z_$][\w$]*$/.test(n)) add("const", n)
+          }
+        }
+      }
+      break
+    }
+    case "py": {
+      for (const l of lines) {
+        let m = l.match(/^(?:async\s+)?def\s+([A-Za-z][\w]*)\s*\(/)
+        if (m) {
+          add("fn", m[1])
+          continue
+        }
+        m = l.match(/^class\s+([A-Za-z][\w]*)/)
+        if (m) {
+          add("class", m[1])
+          continue
+        }
+        m = l.match(/^([A-Z][A-Z0-9_]{2,})\s*(?::[^=]+)?=/)
+        if (m) add("const", m[1])
+      }
+      break
+    }
+    case "go": {
+      for (const l of lines) {
+        let m = l.match(/^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)\s*[(\[]/)
+        if (m) {
+          add("fn", m[1])
+          continue
+        }
+        m = l.match(/^type\s+([A-Z]\w*)/)
+        if (m) {
+          add("type", m[1])
+          continue
+        }
+        m = l.match(/^(?:const|var)\s+([A-Z]\w*)/)
+        if (m) add("const", m[1])
+      }
+      break
+    }
+    case "rs": {
+      for (const l of lines) {
+        const m = l.match(/^\s*pub\s+(?:async\s+)?(?:unsafe\s+)?(?:extern\s+"[^"]*"\s+)?(fn|struct|enum|trait|type|const|static|mod|union)\s+(?:mut\s+)?([A-Za-z_]\w*)/)
+        if (!m) continue
+        const k = m[1]!
+        add(k === "fn" ? "fn" : k === "const" || k === "static" ? "const" : k === "mod" ? "mod" : k === "type" ? "type" : "class", m[2])
+      }
+      break
+    }
+    case "java": {
+      for (const l of lines) {
+        let m = l.match(/^\s*public\s+(?:(?:static|final|abstract|sealed|non-sealed|strictfp)\s+)*(class|interface|enum|record|@interface)\s+(\w+)/)
+        if (m) {
+          add("class", m[2])
+          continue
+        }
+        m = l.match(/^\s+public\s+(?:(?:static|final|abstract|synchronized|default)\s+)*(?:<[^>]+>\s+)?[\w<>\[\],.? ]+?\s+(\w+)\s*\(/)
+        if (m && !["if", "for", "while", "switch", "return", "new"].includes(m[1]!)) add("fn", m[1])
+      }
+      break
+    }
+    case "kt": {
+      for (const l of lines) {
+        if (/\b(private|protected|internal)\b/.test(l.split(/[({=]/)[0]!)) continue
+        let m = l.match(/^(?:(?:public|open|abstract|sealed|data|enum|annotation|inline|value|fun)\s+)*(class|interface|object)\s+(\w+)/)
+        if (m) {
+          add("class", m[2])
+          continue
+        }
+        m = l.match(/^(?:(?:public|inline|suspend|tailrec|operator|infix|external|actual|expect)\s+)*fun\s+(?:<[^>]+>\s+)?(?:[\w.<>?]+\.)?(\w+)\s*\(/)
+        if (m) {
+          add("fn", m[1])
+          continue
+        }
+        m = l.match(/^(?:public\s+)?(?:const\s+)?(?:val|var)\s+(\w+)/)
+        if (m) add("const", m[1])
+      }
+      break
+    }
+    case "rb": {
+      let priv = false
+      for (const l of lines) {
+        let m = l.match(/^\s*(class|module)\s+([A-Z][\w:]*)/)
+        if (m) {
+          priv = false
+          add(m[1] === "module" ? "mod" : "class", m[2])
+          continue
+        }
+        if (/^\s*(private|protected)\s*$/.test(l)) priv = true
+        else if (/^\s*public\s*$/.test(l)) priv = false
+        m = l.match(/^(\s{0,2})def\s+(?:self\.)?([a-z_][\w?!=]*)/)
+        if (m && !priv && !m[2]!.startsWith("_")) add("fn", m[2])
+      }
+      break
+    }
+    case "c": {
+      for (const l of lines) {
+        if (/^\s/.test(l) || l.startsWith("//") || l.startsWith("static") || l.startsWith("return")) continue
+        let m = l.match(/^#define\s+([A-Za-z_]\w*)/)
+        if (m) {
+          if (!/^_*[A-Z0-9_]+_H(PP|XX)?_*$/.test(m[1]!)) add("const", m[1])
+          continue
+        }
+        m = l.match(/^(?:typedef\s+)?(struct|class|enum|union)\s+([A-Za-z_]\w*)/)
+        if (m && !l.includes("(")) {
+          add("class", m[2])
+          continue
+        }
+        m = l.match(/^typedef\s+.*?\b([A-Za-z_]\w*)\s*;/)
+        if (m) {
+          add("type", m[1])
+          continue
+        }
+        m = l.match(/^(?:extern\s+(?:"C"\s+)?)?(?:inline\s+)?[A-Za-z_][\w\s*:<>,&]*?[\s*&]+([A-Za-z_]\w*)\s*\([^;{]*\)\s*(?:const)?\s*;/)
+        if (m && !["if", "while", "for", "return", "sizeof"].includes(m[1]!)) add("fn", m[1])
+      }
+      break
+    }
+  }
+  return out
+}
+
+function formatSymbols(syms: Sym[]): string {
+  const shown = syms.slice(0, MAX_SYMBOLS_PER_FILE)
+  const byKind = new Map<Kind, string[]>()
+  for (const s of shown) byKind.set(s.kind, [...(byKind.get(s.kind) ?? []), s.name])
+  const parts = (["class", "fn", "type", "const", "mod"] as Kind[]).filter((k) => byKind.has(k)).map((k) => `${KIND_LABEL[k]} ${byKind.get(k)!.join(", ")}`)
+  const extra = syms.length - shown.length
+  return parts.join("; ") + (extra > 0 ? `; +${extra} more` : "")
+}
+
+// ---------------------------------------------------------------- reading
+
+function readSource(abs: string): string | undefined {
+  try {
+    const st = statSync(abs)
+    if (!st.isFile() || st.size > MAX_FILE_BYTES) return undefined
+    const fd = openSync(abs, "r")
+    try {
+      const probe = Buffer.alloc(Math.min(8192, st.size))
+      readSync(fd, probe, 0, probe.length, 0)
+      if (probe.includes(0)) return undefined // binary
+    } finally {
+      closeSync(fd)
+    }
+    return readFileSync(abs, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+const MANIFESTS = new Set(["package.json", "cargo.toml", "go.mod", "pyproject.toml", "setup.py", "requirements.txt", "pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "gemfile", "cmakelists.txt", "makefile", "dockerfile", "tsconfig.json", "deno.json", "composer.json", "mix.exs", "pubspec.yaml", "package.swift"])
+const ENTRYPOINT = /^(?:index|main|cli|app|server|__main__|manage|mod|lib|root)\.(?:[mc]?[jt]sx?|py|go|rs|java|kt|rb|c|cc|cpp)$/i
+const README = /^readme(?:\.[a-z]+)?$/i
+
+const ID = /[A-Za-z_$][\w$]{2,}/g
+
+function dirSummary(files: string[]): string {
+  const top = new Map<string, number>()
+  const second = new Map<string, Map<string, number>>()
+  for (const f of files) {
+    const parts = f.split("/")
+    const d = parts.length > 1 ? parts[0]! : "."
+    top.set(d, (top.get(d) ?? 0) + 1)
+    if (parts.length > 2) {
+      const m = second.get(d) ?? new Map<string, number>()
+      m.set(parts[1]!, (m.get(parts[1]!) ?? 0) + 1)
+      second.set(d, m)
+    }
+  }
+  const dirs = [...top.entries()].filter(([d]) => d !== ".").sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+  const rootFiles = top.get(".") ?? 0
+  const out: string[] = []
+  for (const [d, n] of dirs.slice(0, 14)) {
+    const subs = [...(second.get(d) ?? [])].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+    const sub = n >= 20 && subs.length > 1 ? ` (${subs.slice(0, 4).map(([s, c]) => `${s}/ ${c}`).join(", ")}${subs.length > 4 ? ", ..." : ""})` : ""
+    out.push(`${d}/ ${n}${sub}`)
+  }
+  if (dirs.length > 14) out.push(`+${dirs.length - 14} more dirs`)
+  if (rootFiles) out.push(`root files ${rootFiles}`)
+  return out.join("; ")
+}
+
+// ---------------------------------------------------------------- build
+
+/** Builds the map for `cwd` from scratch (no cache). */
+export function buildRepoMap(cwd: string, opts: { maxTokens?: number } = {}): RepoMap {
+  const maxTokens = opts.maxTokens ?? REPOMAP_TOKENS
+  const root = resolve(cwd)
+  const listing = list(root)
+  const { files } = listing
+  const head = repoKey(root, maxTokens)
+  if (!files.length) return { text: "", tokens: 0, head }
+
+  // Pass 1: read each source file once, extract its symbols.
+  interface Src {
+    path: string
+    text: string
+    size: number
+    syms: Sym[]
+  }
+  const sources: Src[] = []
+  let total = 0
+  for (const f of files) {
+    if (sources.length >= MAX_FILES_READ || total >= MAX_TOTAL_BYTES) break
+    const ext = extname(f).toLowerCase()
+    const lang = LANG[ext]
+    if (!lang && !MENTION_ONLY.has(ext)) continue
+    const text = readSource(join(root, f))
+    if (text === undefined) continue
+    total += text.length
+    sources.push({ path: f, text, size: text.length, syms: lang ? extractSymbols(lang, text) : [] })
+  }
+
+  // Candidate names: symbols defined in at most 3 files (a name defined everywhere says nothing) and file basenames.
+  const definedIn = new Map<string, number>()
+  for (const s of sources) for (const y of new Set(s.syms.map((x) => x.name))) definedIn.set(y, (definedIn.get(y) ?? 0) + 1)
+  const stem = (p: string) => basename(p).replace(/\.[^.]+$/, "")
+  const owners = new Map<string, Set<number>>() // candidate name -> files that define it / carry that stem
+  sources.forEach((s, i) => {
+    const names = new Set<string>(s.syms.filter((y) => y.name.length >= 3 && (definedIn.get(y.name) ?? 0) <= 3).map((y) => y.name))
+    const st = stem(s.path)
+    if (st.length >= 3 && st !== "index" && st !== "main") names.add(st)
+    for (const n of names) owners.set(n, (owners.get(n) ?? new Set()).add(i))
+  })
+
+  // Pass 2: which other files mention each file's names (distinct files, so one noisy file counts once).
+  const refs = new Array<number>(sources.length).fill(0)
+  const referrers: Array<Set<number>> = sources.map(() => new Set())
+  sources.forEach((s, j) => {
+    const ids = new Set(s.text.match(ID) ?? [])
+    for (const id of ids) {
+      const own = owners.get(id)
+      if (!own) continue
+      for (const i of own) if (i !== j) referrers[i]!.add(j)
+    }
+  })
+  referrers.forEach((r, i) => (refs[i] = r.size))
+
+  // Rank: references dominate, then recency, then size. Ties by path, so the output is deterministic.
+  const recentRank = new Map(listing.recent.map((f, i) => [f, i] as const))
+  const score = (s: Src, i: number): number => {
+    const r = recentRank.get(s.path)
+    const recent = r === undefined ? 0 : 20 * (1 - r / 300)
+    const dirty = listing.dirty.has(s.path) ? 25 : 0
+    const size = Math.min(5, Math.log2(s.size / 1024 + 1)) * 2
+    return refs[i]! * 10 + recent + dirty + size
+  }
+  const ranked = sources
+    .map((s, i) => ({ s, i, score: score(s, i) }))
+    .filter((x) => x.s.syms.length > 0)
+    .sort((a, b) => b.score - a.score || (a.s.path < b.s.path ? -1 : a.s.path > b.s.path ? 1 : 0))
+
+  // Header lines.
+  const exts = new Map<string, number>()
+  for (const f of files) {
+    const e = extname(f).toLowerCase()
+    if (LANG[e]) exts.set(LANG[e]!, (exts.get(LANG[e]!) ?? 0) + 1)
+  }
+  const langs = [...exts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([l, n]) => `${l} ${n}`)
+  const lines: string[] = [`# repo map: ${basename(root)}, ${files.length} files${langs.length ? ` (${langs.join(", ")})` : ""}${listing.git ? "" : ", not a git repo"}`]
+  lines.push(`dirs: ${dirSummary(files)}`)
+  const key: string[] = []
+  for (const f of files) {
+    const depth = f.split("/").length
+    const b = basename(f)
+    if ((MANIFESTS.has(b.toLowerCase()) && depth <= 2) || (README.test(b) && depth <= 2) || (ENTRYPOINT.test(b) && depth <= 3)) key.push(f)
+  }
+  key.sort((a, b) => a.split("/").length - b.split("/").length || (a < b ? -1 : 1))
+  if (key.length) lines.push(`key files: ${key.slice(0, 16).join(", ")}${key.length > 16 ? `, +${key.length - 16} more` : ""}`)
+  lines.push("exports by importance (references, recency, size):")
+
+  const fit = (all: string[]) => approxTokens(all.join("\n"))
+  // Never the header alone over budget: it is cut to the budget in the last step.
+  const body: string[] = []
+  let omitted = 0
+  for (const { s } of ranked) {
+    let line = `${s.path}: ${formatSymbols(s.syms)}`
+    if (line.length > MAX_LINE) line = `${line.slice(0, MAX_LINE - 1)}…`
+    if (fit([...lines, ...body, line, `(+${ranked.length} more files)`]) > maxTokens) {
+      omitted++
+      continue
+    }
+    body.push(line)
+  }
+  omitted = ranked.length - body.length
+  let text = [...lines, ...body].join("\n")
+  if (omitted > 0) text += `\n(+${omitted} more files with exports; read directories narrowly)`
+  if (approxTokens(text) > maxTokens) text = `${text.slice(0, Math.max(0, maxTokens * 4 - 1)).trimEnd()}…`
+  return { text, tokens: approxTokens(text), head }
+}
+
+// ---------------------------------------------------------------- cache
+
+const cachePath = (home: string, cwd: string) => join(home, ".brain", "cache", `repomap-${createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 16)}.json`)
+
+export interface CachedMap extends RepoMap {
+  /** true when served from the cache, false when it was just built. */
+  cached: boolean
+}
+
+/** The map for `cwd`, from the cache while the code is unchanged, else rebuilt (and cached unless `write` is false). */
+export function repoMap(cwd: string, home: string, opts: { maxTokens?: number; write?: boolean } = {}): CachedMap {
+  const maxTokens = opts.maxTokens ?? REPOMAP_TOKENS
+  if (process.env.BRAIN_NO_CACHE === "1") return { ...buildRepoMap(cwd, { maxTokens }), cached: false }
+  const key = repoKey(resolve(cwd), maxTokens)
+  const file = cachePath(home, cwd)
+  try {
+    const c = JSON.parse(readFileSync(file, "utf8")) as { key?: string; text?: string; tokens?: number; head?: string }
+    if (c.key === key && typeof c.text === "string" && typeof c.tokens === "number") return { text: c.text, tokens: c.tokens, head: key, cached: true }
+  } catch {
+    // no cache, or unreadable: rebuild
+  }
+  const built = buildRepoMap(cwd, { maxTokens })
+  // The key was computed before the build; if the files moved in between, the next call sees a different key and rebuilds.
+  const map: RepoMap = { ...built, head: key }
+  if (opts.write !== false && map.text) {
+    try {
+      mkdirSync(join(home, ".brain", "cache"), { recursive: true, mode: 0o700 })
+      const tmp = `${file}.${process.pid}.tmp`
+      writeFileSync(tmp, JSON.stringify({ key, text: map.text, tokens: map.tokens, head: key }), { mode: 0o600 })
+      renameSync(tmp, file)
+    } catch {
+      // A cache that cannot be written only costs a rebuild.
+    }
+  }
+  return { ...map, cached: false }
+}