@event4u/agent-config 17.2.0 → 17.3.0

package/src/scripts/code_graph/build.ts

@@ -17,8 +17,9 @@ import { fileURLToPath } from 'node:url';
 
 import { write_atomic } from '../_lib/fs_atomic.js';
 import { extractFile, type FileExtract, type RawEdge } from './extract.js';
-import { buildLaravelOverlay } from './laravel_overlay.js';
 import { grammarWasmPath } from './loader.js';
+import { type PassReport, runPasses } from './passes.js';
+import { EMPTY_PROBE, PROBE_MARKERS, type ProjectProbe } from './providers/index.js';
 import {
     ALIAS_VIA,
     aliasRulesFrom,
@@ -30,8 +31,9 @@ import {
     resolveAlias,
     resolvePsr4,
 } from './resolution_tiers.js';
-import { DOC_EXTS, docsLayer } from './docs_layer.js';
-import { readScipIndex, type ScipDocument, scipEdges, supersededByScip } from './scip_reader.js';
+import { templateBase } from './conventions_default.js';
+import { DOC_EXTS } from './docs_layer.js';
+import { readScipIndex, type ScipDocument } from './scip_reader.js';
 import { emitSqliteTwin } from './sqlite_store.js';
 import {
     type CodeEdge,
@@ -78,6 +80,10 @@ const CODE_EXTS: ReadonlySet<string> = new Set(Object.keys(EXT_LANG));
 const GENERATED_DIRS: ReadonlySet<string> = new Set(['agents/map', 'agents/runtime']);
 
 export function discoverFiles(root: string, exts: ReadonlySet<string> = CODE_EXTS): string[] {
+    return walkFiles(root, (name) => exts.has(path.extname(name).toLowerCase()));
+}
+
+function walkFiles(root: string, accept: (name: string) => boolean): string[] {
     const abs = path.resolve(root);
     // Resolve the root itself first: a repo checked out under a symlinked
     // path (e.g. macOS /tmp → /private/tmp) must still confine correctly —
@@ -106,8 +112,7 @@ export function discoverFiles(root: string, exts: ReadonlySet<string> = CODE_EXT
                 continue;
             }
             if (!e.isFile()) continue;
-            const ext = path.extname(e.name).toLowerCase();
-            if (!exts.has(ext)) continue;
+            if (!accept(e.name)) continue;
             let real: string;
             try {
                 real = fs.realpathSync(full);
@@ -122,6 +127,33 @@ export function discoverFiles(root: string, exts: ReadonlySet<string> = CODE_EXT
     return out.sort();
 }
 
+/** Manifests a provider may read to detect a stack, by basename. */
+const MANIFEST_NAME = /^(?:composer\.json|package\.json|pyproject\.toml|requirements[\w.-]*\.txt|pom\.xml|build\.gradle(?:\.kts)?|go\.mod|[\w.-]+\.csproj|Gemfile)$/;
+
+/** The project's manifests and marker files, for provider detection (ADR-298). */
+export function readProjectProbe(root: string): ProjectProbe {
+    const abs = path.resolve(root);
+    const manifests = new Map<string, string>();
+    const markers = new Set<string>();
+    const paths: string[] = [];
+    for (const full of walkFiles(abs, () => true)) {
+        const rel = toPosixRel(abs, full);
+        paths.push(rel);
+        const name = path.basename(full);
+        if (!MANIFEST_NAME.test(name) && !PROBE_MARKERS.has(name)) continue;
+        if (PROBE_MARKERS.has(name)) {
+            markers.add(rel);
+            continue;
+        }
+        try {
+            manifests.set(rel, fs.readFileSync(full, 'utf-8'));
+        } catch {
+            continue;
+        }
+    }
+    return { manifests, markers, paths };
+}
+
 function toPosixRel(root: string, full: string): string {
     return path.relative(root, full).split(path.sep).join('/');
 }
@@ -234,10 +266,19 @@ function resolveSpecifier(fromFile: string, spec: string, fileIds: ReadonlySet<s
  *   go      `example.com/x/mod` → every non-test `.go` file of the most specific
  *           directory whose path ends the import path — a Go import names a
  *           package, and a package is all of its files.
+ *   csharp  `using A.B` → the one file declaring namespace `A.B` (`namespaces`).
+ *           A namespace declared by several files is left to name lookup: it
+ *           binds no file, since a `using` names no single one.
  *
  * A suffix that matches two files is refused rather than guessed.
  */
-export function resolveLangModule(lang: Lang, fromFile: string, spec: string, fileIds: readonly string[]): string[] {
+export function resolveLangModule(
+    lang: Lang,
+    fromFile: string,
+    spec: string,
+    fileIds: readonly string[],
+    namespaces: ReadonlyMap<string, readonly string[]> = new Map(),
+): string[] {
     const unique = (suffixes: string[]): string[] => {
         const hits = fileIds.filter((f) => suffixes.some((s) => f === s || f.endsWith(`/${s}`)));
         return hits.length === 1 ? hits : [];
@@ -264,6 +305,7 @@ export function resolveLangModule(lang: Lang, fromFile: string, spec: string, fi
         }
         return best ? goFiles.filter((f) => idDirname(f) === best).sort() : [];
     }
+    if (lang === 'csharp') return [...(namespaces.get(spec) ?? [])];
     return [];
 }
 
@@ -309,6 +351,8 @@ export function buildGraph(
     resolution: ResolutionConfig = EMPTY_RESOLUTION_CONFIG,
     scip: readonly ScipDocument[] = [],
     docs: readonly SourceFile[] = [],
+    probe: ProjectProbe = EMPTY_PROBE,
+    report?: { passes?: PassReport },
 ): CodeGraph {
     const nodes = extracts.flatMap((e) => e.nodes);
     const nodeIds = new Set(nodes.map((n) => n.id));
@@ -383,6 +427,8 @@ export function buildGraph(
     const fileIdList = [...fileIds].sort();
     /** Go imports name a package of several files; the binding takes the first, these carry the rest. */
     const extraImports: Array<{ source: string; target: string }> = [];
+    const namespaceFiles = new Map<string, string[]>();
+    for (const ex of extracts) for (const ns of ex.namespaces ?? []) push(namespaceFiles, ns, ex.file);
     for (const ex of extracts) {
         const locals = new Map<string, string[]>();
         for (const n of ex.nodes) if (n.kind !== 'file') push(locals, n.label, n.id);
@@ -419,8 +465,9 @@ export function buildGraph(
                 if (hit) imports.set(local, { target: hit, exact: false, via: 'name-lookup' });
                 continue;
             }
-            if (ex.lang === 'python' || ex.lang === 'java' || ex.lang === 'go') {
-                const hits = resolveLangModule(ex.lang, ex.file, spec, fileIdList);
+            if (ex.lang === 'csharp' && (namespaceFiles.get(spec)?.length ?? 0) > 1) continue;
+            if (ex.lang === 'python' || ex.lang === 'java' || ex.lang === 'go' || ex.lang === 'csharp') {
+                const hits = resolveLangModule(ex.lang, ex.file, spec, fileIdList, namespaceFiles);
                 const first = hits[0];
                 if (first === undefined) {
                     imports.set(local, {
@@ -754,39 +801,9 @@ export function buildGraph(
         });
     }
 
-    // Framework links no import states (routes, views, tables); rule-read,
-    // emitted only when the target exists. Also drops the base edges it
-    // proves false: a fluent `->middleware()` bound by name to some
-    // unrelated in-repo `middleware()`.
-    const overlay = buildLaravelOverlay(files, nodes, resolution);
-    let routeBuilderCalls = 0;
-    if (overlay.nodes.length > 0 || overlay.edges.length > 0) {
-        const kept = edges.filter((e) => !overlay.dropEdge(e));
-        routeBuilderCalls = edges.length - kept.length;
-        // Element-wise: a spread of ~200k edges overflows the call stack.
-        edges.length = 0;
-        for (const e of kept) edges.push(e);
-        for (const e of overlay.edges) edges.push(e);
-        for (const n of overlay.nodes) nodes.push(n);
-    }
-
-    if (docs.length > 0) {
-        const allFiles = new Set([...files.map((f) => f.path), ...docs.map((d) => d.path)]);
-        const layer = docsLayer(docs, allFiles);
-        for (const n of layer.nodes) nodes.push(n);
-        for (const e of layer.edges) edges.push(e);
-    }
-
-    // A project's own SCIP index states references the compiler resolved;
-    // each one supersedes the native name guess it duplicates.
-    if (scip.length > 0) {
-        const stated = scipEdges(scip, nodes);
-        const dropped = supersededByScip(stated, nodes);
-        const kept = edges.filter((e) => !dropped(e));
-        edges.length = 0;
-        for (const e of kept) edges.push(e);
-        for (const e of stated) edges.push(e);
-    }
+    // Everything after resolution: convention providers, docs, SCIP (passes.ts).
+    const passes = runPasses({ files, docs, scip, resolution, probe }, nodes, edges);
+    if (report) report.passes = passes;
 
     // deterministic ordering
     nodes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
@@ -800,7 +817,9 @@ export function buildGraph(
     for (const e of edges) counts[e.confidence] += 1;
     const suppressed: CodeGraph['suppressed_edge_counts'] = {
         dynamic_no_candidate: suppressedKeys.size,
-        ...(routeBuilderCalls > 0 ? { route_builder_call: routeBuilderCalls } : {}),
+        ...(Object.keys(passes.suppressed).length > 0
+            ? { contested_by_provider: Object.fromEntries(Object.entries(passes.suppressed).sort()) }
+            : {}),
     };
 
     const languages = [...new Set(extracts.map((e) => e.lang))].sort() as Lang[];
@@ -819,6 +838,18 @@ export function buildGraph(
         h.update(createHash('sha256').update(d.source, 'utf-8').digest('hex'));
         h.update('\n');
     }
+    // Manifests and markers decide which providers run: a changed manifest is
+    // a changed input even when no source file moved.
+    for (const [p, text] of [...probe.manifests].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        h.update(`manifest\0${p}\0`);
+        h.update(createHash('sha256').update(text, 'utf-8').digest('hex'));
+        h.update('\n');
+    }
+    for (const p of [...probe.markers].sort()) h.update(`marker\0${p}\n`);
+    // Template files are no source, yet their presence decides `renders` and
+    // default-pass edges: they are inputs too. Other non-code paths (caches,
+    // logs, assets) are not read and stay out of the identity.
+    for (const p of probe.paths) if (templateBase(p) !== null) h.update(`template\0${p}\n`);
     // The SCIP index is an input like any source file: a new index must not
     // read as the same graph.
     for (const d of [...scip].sort((a, b) => (a.path < b.path ? -1 : 1))) {
@@ -833,6 +864,7 @@ export function buildGraph(
         grammar_abi: EXPECTED_GRAMMAR_ABI,
         edge_confidence_counts: counts,
         suppressed_edge_counts: suppressed,
+        ...(passes.providers.length > 0 ? { providers: passes.providers } : {}),
         nodes,
         edges,
     };
@@ -908,6 +940,7 @@ export function serializeGraph(g: CodeGraph): string {
         'grammar_abi',
         'edge_confidence_counts',
         'suppressed_edge_counts',
+        'providers',
         'nodes',
         'edges',
     ];
@@ -936,13 +969,14 @@ export function serializeGraph(g: CodeGraph): string {
         // byte what it was before this field existed.
         if (e.ambiguity_reason) base['ambiguity_reason'] = e.ambiguity_reason;
         if (e.candidates) base['candidates'] = e.candidates;
+        if (e.provider_id) base['provider_id'] = e.provider_id;
         return base;
     };
     const ordered: Record<string, unknown> = {};
     for (const k of key_order) {
         if (k === 'nodes') ordered[k] = g.nodes.map(node);
         else if (k === 'edges') ordered[k] = g.edges.map(edge);
-        else ordered[k] = g[k];
+        else if (g[k] !== undefined) ordered[k] = g[k];
     }
     return JSON.stringify(ordered, null, 2) + '\n';
 }
@@ -1086,7 +1120,9 @@ export async function buildFromRepo(
             continue;
         }
     }
-    const graph = buildGraph(files, extracts, readResolutionConfig(root), scip, docs);
+    const report: { passes?: PassReport } = {};
+    const graph = buildGraph(files, extracts, readResolutionConfig(root), scip, docs, readProjectProbe(abs), report);
+    for (const f of report.passes?.failures ?? []) process.stderr.write(`code-graph: pass ${f.pass} failed — ${f.reason}\n`);
     const json = serializeGraph(graph);
     if (cachePath) {
         write_atomic(cachePath, json);

package/src/scripts/code_graph/cli.ts

@@ -6,8 +6,12 @@
  *   validate [--graph P]                       schema-gate a graph.json
  *   detect   [--root P] [--format json]        three-state freshness verdict
  *   refresh  [--root P] [--out P] [--budget-seconds N]
- *                                               build --update (STALE) / no-op
- *                                               (FRESH) / full build (ABSENT)
+ *            [--single-flight] [--map]          build --update (STALE) / no-op
+ *                                               (FRESH) / full build (ABSENT);
+ *                                               a result built while HEAD moved
+ *                                               is discarded and retried once
+ *   auto-refresh on|off|status [--root P]      opt this project in to the
+ *                                               session-start background refresh
  *
  * `detect --format json` (Phase 2, road-to-reachable-code-memory) emits a
  * single-line, stable-key-order JSON verdict on stdout — no timestamps, safe
@@ -62,7 +66,7 @@
  *                                               graph.
  */
 import { execFileSync, spawnSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
@@ -70,7 +74,8 @@ import { fileURLToPath } from 'node:url';
 
 import { resolve_project_root } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
-import { buildFromRepo, isTestFile, sidecarPath } from './build.js';
+import { buildFromRepo, discoverFiles, isTestFile, sidecarPath } from './build.js';
+import { DOC_EXTS } from './docs_layer.js';
 import {
     computeVerdict,
     detectSources,
@@ -80,7 +85,16 @@ import {
     pickSource,
 } from './detect.js';
 import { suggestVerb } from './intent.js';
-import { buildMap, recordOutcome } from './map.js';
+import { buildMap, graphGeneration, mapGeneration, recordOutcome } from './map.js';
+import { cliPackage, usableCli } from './refresh_cli.js';
+import {
+    AUTO_REFRESH_REL,
+    LOCK_REL,
+    acquire as acquireRefreshLock,
+    readRefreshRecords,
+    reclaimMutexPath,
+    recordRefresh,
+} from './refresh_lock.js';
 import { verifyMap } from './map_verify.js';
 import {
     affected,
@@ -655,6 +669,64 @@ function cleanupTemp(tmpOut: string): void {
  * itself uses. Any other outcome (timeout, non-zero exit, missing output)
  * cleans up the temp files and leaves `out` untouched.
  */
+function git(root: string, ...args: string[]): string | null {
+    try {
+        return execFileSync('git', ['-C', root, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenedSpawnEnv() }).trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * HEAD; `''` when no ancestor of the CANONICAL root holds `.git`; `null` when
+ * one does and HEAD cannot be read, or when the root or an ancestor cannot be
+ * inspected. "Not a repository" is read from the filesystem, never from a git
+ * probe, and is walked from the realpath so a symlinked root cannot hide the
+ * repository git itself would find.
+ */
+function headOf(root: string): string | null {
+    let dir: string;
+    try {
+        dir = fs.realpathSync(root);
+    } catch {
+        return null;
+    }
+    for (;;) {
+        try {
+            fs.lstatSync(path.join(dir, '.git'));
+            return git(dir, 'rev-parse', 'HEAD');
+        } catch (e) {
+            if ((e as NodeJS.ErrnoException).code !== 'ENOENT') return null;
+        }
+        if (path.dirname(dir) === dir) return '';
+        dir = path.dirname(dir);
+    }
+}
+
+/**
+ * A stamp of the files a build reads — path, size and modification time of every
+ * source and document file. HEAD alone misses an edit to the working tree made
+ * while the build ran (a second agent saving a file), which leaves a graph of
+ * content that never existed together. Best-effort, not definitive: an edit
+ * that keeps the size and lands within the filesystem's mtime resolution (or
+ * restores the mtime) is not seen; hashing every file's content would be.
+ */
+function treeStamp(root: string): string {
+    const h = createHash('sha256');
+    for (const full of [...discoverFiles(root), ...discoverFiles(root, DOC_EXTS)]) {
+        try {
+            const st = fs.statSync(full);
+            h.update(`${full}\0${st.size}\0${st.mtimeMs}\n`);
+        } catch {
+            h.update(`${full}\0gone\n`);
+        }
+    }
+    return h.digest('hex');
+}
+
+/** Returned by {@link runBudgetedBuild} when HEAD or the working tree moved while the child built. */
+const HEAD_MOVED = -1;
+
 function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeconds: number): number {
     if (!(budgetSeconds > 0)) {
         // Node's own `timeout` option treats 0 as "no limit" — a genuinely
@@ -682,6 +754,8 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
     const [cmd, cmdArgs] = fs.existsSync(TSX_BIN)
         ? [TSX_BIN, [_HERE, ...args]]
         : [process.execPath, [...process.execArgv, _HERE, ...args]];
+    const headBefore = headOf(root);
+    const treeBefore = treeStamp(root);
     const res = spawnSync(cmd, cmdArgs, {
         env: hardenedSpawnEnv(),
         stdio: 'ignore',
@@ -705,6 +779,19 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
         process.stderr.write('code-graph: refresh produced no output — old cache kept\n');
         return 3;
     }
+    // A checkout or rebase that lands mid-build leaves a graph of a tree that
+    // existed only in passing; publishing it would label mixed content fresh.
+    // An unreadable HEAD is not evidence it held still, so it fails the same way.
+    if (headBefore === null || headOf(root) !== headBefore) {
+        cleanupTemp(tmpOut);
+        process.stderr.write('code-graph: HEAD moved (or could not be read) during the refresh — result discarded\n');
+        return HEAD_MOVED;
+    }
+    if (treeStamp(root) !== treeBefore) {
+        cleanupTemp(tmpOut);
+        process.stderr.write('code-graph: files changed during the refresh — result discarded\n');
+        return HEAD_MOVED;
+    }
     fs.renameSync(tmpOut, out); // same-dir → atomic; real cache only ever changes here
     const tmpSidecar = sidecarPath(tmpOut);
     if (fs.existsSync(tmpSidecar)) fs.renameSync(tmpSidecar, sidecarPath(out));
@@ -712,7 +799,12 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
     return 0;
 }
 
-function cmdRefresh(argv: string[]): number {
+/**
+ * `--single-flight` takes the lock the git-hook refresh block takes and exits 0
+ * when another refresh holds it. `--map` redraws `agents/map/` afterwards, only
+ * when the project already has one and it is older than the cache.
+ */
+async function cmdRefresh(argv: string[]): Promise<number> {
     const root = resolveRoot(argv);
     const out = flag(argv, '--out') ?? cacheFor(root);
     const budgetSeconds = budgetSecondsOf(argv);
@@ -720,12 +812,126 @@ function cmdRefresh(argv: string[]): number {
         process.stderr.write(`code-graph: root not found: ${root}\n`);
         return 1;
     }
-    const v = computeVerdict(root, out);
-    if (v.verdict === 'FRESH') {
-        process.stdout.write('fresh — nothing to do\n');
+    // `--map` writes the same files a manual `map` does, so it is never drawn unlocked.
+    const locked = argv.includes('--single-flight') || argv.includes('--map');
+    const release = locked ? acquireRefreshLock(root) : () => {};
+    const record = (outcome: string, detail?: string): void => {
+        if (locked) recordRefresh(root, { by: 'refresh', outcome, ...(detail ? { detail } : {}) });
+    };
+    if (release === null) {
+        process.stdout.write('another refresh is running — nothing to do\n');
+        record('locked');
+        return 0;
+    }
+    try {
+        let rc = HEAD_MOVED;
+        // One retry: a second move inside one build window means the tree is
+        // still in motion, and the next hook or session start will refresh it.
+        for (let attempt = 0; attempt < 2 && rc === HEAD_MOVED; attempt++) {
+            const v = computeVerdict(root, out);
+            if (v.verdict === 'FRESH') {
+                process.stdout.write('fresh — nothing to do\n');
+                rc = 0;
+                break;
+            }
+            rc = runBudgetedBuild(root, out, v.verdict === 'STALE', budgetSeconds);
+        }
+        if (rc === HEAD_MOVED) {
+            record('tree-moved', 'HEAD or files changed during both attempts; the next refresh retries');
+            return 1;
+        }
+        if (rc !== 0) {
+            record('failed', `build exited ${rc}`);
+            return rc;
+        }
+        if (argv.includes('--map') && mapIsBehind(root, out)) {
+            const mrc = await drawMap(['--root', root, '--no-build', '--no-verify']);
+            record(mrc === 0 ? 'refreshed-with-map' : 'map-failed', mrc === 0 ? undefined : `map exited ${mrc}`);
+            return mrc;
+        }
+        record('refreshed');
+        return rc;
+    } finally {
+        release();
+    }
+}
+
+/**
+ * `auto-refresh on|off|status` — the explicit, local, per-project opt-in the
+ * `code-graph-refresh` session concern requires before it starts anything
+ * (ratification round of 2026-10-23: an existing cache is not consent).
+ */
+function cmdAutoRefresh(argv: string[]): number {
+    const root = resolveRoot(argv);
+    const action = argv.find((a) => !a.startsWith('--') && !isFlagValue(argv, a)) ?? 'status';
+    const marker = path.join(root, AUTO_REFRESH_REL);
+    if (action === 'on') {
+        fs.mkdirSync(path.dirname(marker), { recursive: true });
+        fs.writeFileSync(marker, `${JSON.stringify({ enabled_at: new Date().toISOString() })}\n`);
+        const cli = usableCli(root);
+        process.stdout.write(
+            'auto-refresh on — each agent session start refreshes the graph, and agents/map/ when it exists,\n' +
+                'in the background (POSIX hosts). `code-graph auto-refresh off` stops it.\n' +
+                'The opt-in is per working tree: run it again in each new git worktree.\n' +
+                (fs.existsSync(cacheFor(root)) ? '' : 'No graph yet: `code-graph build` or `code-graph map` creates one.\n'),
+        );
+        if ('reason' in cli) {
+            process.stderr.write(
+                cli.reason === 'no-cli'
+                    ? 'warning: no agent-config outside this repository is on PATH, so nothing will run yet — install it globally (npm i -g @event4u/agent-config).\n'
+                    : `warning: ${cli.cli} (version ${cliPackage(cli.cli)?.version ?? 'unknown'}) is too old for the single-flight refresh, so nothing will run yet — update it (npm i -g @event4u/agent-config).\n`,
+            );
+        }
         return 0;
     }
-    return runBudgetedBuild(root, out, v.verdict === 'STALE', budgetSeconds);
+    if (action === 'off') {
+        fs.rmSync(marker, { force: true });
+        process.stdout.write('auto-refresh off\n');
+        return 0;
+    }
+    if (action !== 'status') {
+        process.stderr.write('usage: code_graph/cli.ts auto-refresh on|off|status [--root P]\n');
+        return 2;
+    }
+    const cli = usableCli(root);
+    const last = readRefreshRecords(root);
+    const line = (r: (typeof last)['refresh']): string => (r ? `${r.outcome} at ${r.at}${r.detail ? ` (${r.detail})` : ''}` : 'never');
+    const mapDir = path.join(root, 'agents', 'map');
+    const gen = graphGeneration(cacheFor(root));
+    const drawnFrom = mapGeneration(mapDir);
+    const mutex = reclaimMutexPath(path.join(root, LOCK_REL));
+    process.stdout.write(
+        `auto-refresh: ${fs.existsSync(marker) ? 'on' : 'off'}\n` +
+            `cli: ${'reason' in cli ? (cli.reason === 'no-cli' ? 'none usable — nothing will run' : `${cli.cli} ${cliPackage(cli.cli)?.version ?? '?'} — too old, nothing will run`) : `${cli.cli} ${cliPackage(cli.cli)?.version ?? '?'}`}\n` +
+            `last session start: ${line(last['session-start'])}\n` +
+            `last refresh: ${line(last.refresh)}\n` +
+            `graph: ${computeVerdict(root, cacheFor(root)).verdict}\n` +
+            `map: ${!fs.existsSync(mapDir) ? 'absent' : drawnFrom === null ? 'present (generation unknown — redrawn on the next refresh)' : drawnFrom === gen ? 'present, drawn from the current graph' : 'present, drawn from an older graph'}\n` +
+            (fs.existsSync(mutex) && mutexAgeMs(mutex) > 60_000
+                ? `reclaim mutex: ${path.relative(root, mutex)} left by a crash — stale locks stay held until it is removed by hand\n`
+                : ''),
+    );
+    return 0;
+}
+
+function mutexAgeMs(p: string): number {
+    try {
+        return Date.now() - fs.statSync(p).mtimeMs;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * Whether the map was drawn from a different graph than the cache now holds —
+ * decided by the generation both record, never by modification times, which a
+ * copied or restored file carries wrongly. No map → never draw one unbidden.
+ */
+function mapIsBehind(root: string, cache: string): boolean {
+    const mapDir = path.join(root, 'agents', 'map');
+    if (!fs.existsSync(mapDir)) return false;
+    const gen = graphGeneration(cache);
+    return gen !== null && mapGeneration(mapDir) !== gen;
 }
 
 /**
@@ -739,6 +945,33 @@ async function cmdMap(argv: string[]): Promise<number> {
         process.stderr.write(`code-graph: root not found: ${root}\n`);
         return 1;
     }
+    // A background refresh may be redrawing the same files; two writers would
+    // interleave them. Wait for it — a session start is exactly when someone asks
+    // for the map — but not beyond one refresh budget plus a redraw.
+    let release = acquireRefreshLock(root);
+    const deadline = Date.now() + MAP_LOCK_WAIT_MS;
+    if (release === null) process.stderr.write('code-graph: waiting for a background refresh to finish…\n');
+    while (release === null && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 250));
+        release = acquireRefreshLock(root);
+    }
+    if (release === null) {
+        process.stderr.write('code-graph: a refresh is still redrawing the map — try again in a moment\n');
+        return 1;
+    }
+    try {
+        return await drawMap(argv);
+    } finally {
+        release();
+    }
+}
+
+/** How long `map` waits for a background refresh to release the lock. */
+const MAP_LOCK_WAIT_MS = Number(process.env['AGENT_CONFIG_MAP_LOCK_WAIT_MS'] ?? 90 * 1000);
+
+/** The map itself; callers hold the refresh lock. */
+async function drawMap(argv: string[]): Promise<number> {
+    const root = resolveRoot(argv);
     const out = flag(argv, '--out');
     const diffRev = flag(argv, '--diff');
     const r = await buildMap(root, {
@@ -756,15 +989,25 @@ async function cmdMap(argv: string[]): Promise<number> {
             (r.model.diff
                 ? `    diff ${r.model.diff.rev}: ${r.model.diff.changed.length} changed · ${r.model.diff.impacted.length} linked into them · ${r.model.diff.areas.length} area(s) touched\n`
                 : '') +
-            `    wrote: ${r.written.length} files under ${rel}/ — open ${path.join(rel, 'index.html')}\n`,
+            `    wrote: ${r.written.length} files under ${rel}/ — open ${path.join(rel, 'index.html')}\n` +
+            (fs.existsSync(path.join(root, AUTO_REFRESH_REL))
+                ? ''
+                : '    keep it current at every agent session start: agent-config code-graph auto-refresh on\n'),
     );
     let rc = 0;
+    const renderFile = path.join(r.outDir, 'map-render.json');
     if (argv.includes('--no-verify')) {
-        // A check from an earlier map must not sit beside this one as if it were about it.
-        fs.rmSync(path.join(r.outDir, 'map-render.json'), { force: true });
+        // A check that names the generation it checked can stay beside a newer
+        // map without being read as about it; one that names none cannot.
+        try {
+            const prev = JSON.parse(fs.readFileSync(renderFile, 'utf-8')) as { graph_generation?: unknown };
+            if (typeof prev.graph_generation !== 'string') fs.rmSync(renderFile, { force: true });
+        } catch {
+            fs.rmSync(renderFile, { force: true });
+        }
     } else {
         const check = await verifyMap(path.join(r.outDir, 'index.html'));
-        fs.writeFileSync(path.join(r.outDir, 'map-render.json'), `${JSON.stringify(check, null, 2)}\n`);
+        fs.writeFileSync(renderFile, `${JSON.stringify({ ...check, graph_generation: r.meta.graph_generation }, null, 2)}\n`);
         const problems = check.viewports
             .flatMap((v) => [
                 ...(v.pageErrors ? [`${v.name}: ${v.pageErrors} page error(s)`] : []),
@@ -831,7 +1074,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'build') return await cmdBuild(argv.slice(1));
         if (sub === 'validate') return cmdValidate(argv.slice(1));
         if (sub === 'detect') return cmdDetect(argv.slice(1));
-        if (sub === 'refresh') return cmdRefresh(argv.slice(1));
+        if (sub === 'refresh') return await cmdRefresh(argv.slice(1));
         if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
             return cmdQuery(sub, argv.slice(1));
         if (sub === 'impact') return cmdImpact(argv.slice(1));
@@ -841,9 +1084,10 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
         if (sub === 'map') return await cmdMap(argv.slice(1));
         if (sub === 'outcome') return cmdOutcome(argv.slice(1));
+        if (sub === 'auto-refresh') return cmdAutoRefresh(argv.slice(1));
         process.stderr.write(
             'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|' +
-                'impact|tests-for|untested|dead|suggest-verb|map|outcome> [options]\n',
+                'impact|tests-for|untested|dead|suggest-verb|map|outcome|auto-refresh> [options]\n',
         );
         return 2;
     } catch (e) {