@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/cli.ts

@@ -6,8 +6,17 @@
  *   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
+ *   projects list|add|remove|prune             the user-global registry of
+ *                                               projects this machine works in
+ *                                               (ADR-299, `projects_cli.ts`)
+ *   estate where-used|projects-using|          estate questions from the local
+ *          advisory-impact                     index alone (`estate_cli.ts`)
  *
  * `detect --format json` (Phase 2, road-to-reachable-code-memory) emits a
  * single-line, stable-key-order JSON verdict on stdout — no timestamps, safe
@@ -25,8 +34,10 @@
  * completed temp output — on budget-exceeded, build failure, or the child
  * never producing output, the rename never happens and the OLD cache is left
  * byte-for-byte untouched. The cache itself (default
- * `agents/runtime/state/code-graph-v1.json`) is local-only and disposable —
- * gitignored, rebuildable from source at any time; never a source of truth.
+ * `agents/runtime/state/code-graph-v1.json`; for a root without `agents/` or a
+ * project install, the user-global `runtime/graphs/<repo id>/state/`, ADR-299)
+ * is local-only and disposable — gitignored, rebuildable from source at any
+ * time; never a source of truth.
  *
  *   impact    --diff <rev> [--depth N]      callers/dependents/test files
  *                                             reachable from the changed
@@ -42,16 +53,24 @@
  * three-state staleness — so a caller can tell "no callers" from "no callers I
  * would trust", and "dead" from "dead as of a graph 40 commits behind".
  *
+ * Every verb that reads a graph also takes `--project <id|name|path>`: a
+ * project in the user-global registry, resolved to its root and graph home
+ * (ADR-299). Only a registered project resolves.
+ *
  * Query subcommands (query/path/explain/affected) are added by the Phase-3
  * query tier. Deterministic, LLM-free, no network. Exit codes:
  * 0 ok · 1 not-found / validation-failed / refresh-budget-exceeded ·
  * 2 usage · 3 internal.
  *
  *   map      [--root P] [--out DIR] [--open]  draw the project map into
- *            [--no-verify] [--diff <rev>]      agents/map/ (ADR-297); renders it
+ *            [--no-verify] [--diff <rev>]      agents/map/ (ADR-297), or the
+ *                                               graph home's map/ (ADR-299); renders it
  *            [--prs]                           (open PRs by area, via gh)
  *                                               at three widths when Playwright
  *                                               is present
+ *   map --estate [--out DIR] [--no-verify]     one page of the registered projects
+ *                                               and their links, under the user-global
+ *                                               home; refused inside a git work tree
  *
  *   suggest-verb "<question>"                  (Phase 9 D3) print the verb
  *                                               (query/affected/path/explain)
@@ -62,7 +81,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,17 +89,32 @@ 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,
     type GraphState,
     graphState,
-    NATIVE_CACHE_REL,
     pickSource,
 } from './detect.js';
+import { graphHome } from './graph_home.js';
 import { suggestVerb } from './intent.js';
-import { buildMap, recordOutcome } from './map.js';
+import { estateMain } from './estate_cli.js';
+import { estateMapMain } from './estate_map.js';
+import { touchHome } from './graph_budget.js';
+import { resolveProjectRef } from './project_ref.js';
+import { projectsMain, registerUse } from './projects_cli.js';
+import { buildMap, graphGeneration, mapGeneration, recordOutcome } from './map.js';
+import { cliPackage, usableCli } from './refresh_cli.js';
+import {
+    STALE_LOCK_MS,
+    acquire as acquireRefreshLock,
+    pidAlive,
+    readRefreshRecords,
+    reclaimMutexPath,
+    recordRefresh,
+} from './refresh_lock.js';
 import { verifyMap } from './map_verify.js';
 import {
     affected,
@@ -107,24 +141,34 @@ import {
     untested,
     type UntestedResult,
 } from './verbs.js';
+import { main as lineageMain } from './lineage_cli.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
 /**
- * The cache belongs to the project it describes: `<root>/agents/runtime/state/`,
- * the path MCP, the context hook and `detect` already read. Anchoring it to
+ * The cache belongs to the project it describes: `<root>/agents/runtime/state/`
+ * when the root has a project home, its user-global graph home otherwise
+ * (ADR-299) — the path MCP, the context hook and `detect` read. Anchoring it to
  * the package tree put a consumer's graph inside `node_modules`, where `npm ci`
  * deleted it, two projects sharing an install overwrote each other, and MCP
  * answered "no graph" right after the CLI reported a fresh one.
  */
 export function cacheFor(root: string): string {
-    return path.join(root, NATIVE_CACHE_REL);
+    return graphHome(root).cachePath;
+}
+/** A path relative to the root when it lies inside it; a graph home outside the root prints in full. */
+function shown(root: string, p: string): string {
+    const rel = path.relative(root, p);
+    return rel.startsWith('..') || path.isAbsolute(rel) ? p : rel;
 }
 /** Local `tsx` binary — `refresh` spawns `build` as a child of THIS file
  * through it, so a budget-exceeded kill only ever terminates the child. */
 const TSX_BIN = path.join(REPO_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
 const DEFAULT_BUDGET_SECONDS = 60;
 
+/** A refusal that names what the caller asked for wrongly; exits 1, not 3. */
+class UsageError extends Error {}
+
 function flag(argv: string[], name: string): string | null {
     const i = argv.indexOf(name);
     return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
@@ -143,8 +187,13 @@ function flag(argv: string[], name: string): string | null {
  */
 function resolveRoot(argv: string[]): string {
     const explicit = flag(argv, '--root');
+    const project = flag(argv, '--project');
     let candidate: string;
-    if (explicit !== null) {
+    if (project !== null) {
+        const r = resolveProjectRef(project);
+        if ('error' in r) throw new UsageError(r.error);
+        candidate = r.root;
+    } else if (explicit !== null) {
         candidate = explicit;
     } else {
         try {
@@ -183,6 +232,7 @@ async function cmdBuild(argv: string[]): Promise<number> {
     }
     const update = argv.includes('--update');
     const { graph, fileCount, reExtracted, reused } = await buildFromRepo(root, out, { update });
+    if (out === cacheFor(root)) registerUse(root, graph, git(root, 'rev-parse', 'HEAD'));
     const c = graph.edge_confidence_counts;
     process.stdout.write(
         `✅  code-graph ${update ? 'updated' : 'built'} — ${fileCount} files · ${graph.nodes.length} nodes · ${graph.edges.length} edges\n` +
@@ -190,7 +240,7 @@ async function cmdBuild(argv: string[]): Promise<number> {
             `    edges: EXTRACTED ${c.EXTRACTED} · INFERRED ${c.INFERRED} · AMBIGUOUS ${c.AMBIGUOUS}\n` +
             `    resolved_via: ${resolvedViaHistogram(graph)}\n` +
             (update ? `    incremental: ${reExtracted} re-extracted · ${reused} reused\n` : '') +
-            (out ? `    cache: ${path.relative(root, out)}\n` : '') +
+            (out ? `    cache: ${shown(root, out)}\n` : '') +
             legacyCacheNotice(root),
     );
     return 0;
@@ -247,12 +297,12 @@ function cmdValidate(argv: string[]): number {
     // content-addressed cache key, so agreement here means the twin was emitted
     // from THIS graph and not merely from a graph.
     const twinState = twinChecksumState(p, (parsed as CodeGraph).source_checksum);
-    const rel = path.relative(root, p);
+    const rel = shown(root, p);
     if (twinState.kind === 'mismatch') {
         process.stderr.write(
             `❌  SQLite twin disagrees with the canonical JSON: twin ${twinState.twin} ≠ json ${twinState.json}\n` +
                 '    The twin is derived and disposable — delete it and re-run `code-graph build`.\n' +
-                `    ${path.relative(root, sqliteTwinPath(p))}\n`,
+                `    ${shown(root, sqliteTwinPath(p))}\n`,
         );
         return 1;
     }
@@ -295,7 +345,8 @@ function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err:
     if (!picked) return { err: 'no code-graph source found — run `code_graph build` or ship a graph.json' };
     if (picked.kind === 'scip') return { err: `${picked.note ?? 'SCIP detected'} — run \`code-graph build\` to merge it into the native graph` };
     const staleNote = picked.stale ? ` ⚠ index is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild before trusting` : '';
-    return { g: loadGraph(picked.path, `${picked.kind}:${path.relative(root, picked.path)}`), note: staleNote };
+    touchHome(root);
+    return { g: loadGraph(picked.path, `${picked.kind}:${shown(root, picked.path)}`), note: staleNote };
 }
 
 function render(r: QueryResult, staleNote: string): number {
@@ -415,7 +466,8 @@ function isFlagValue(argv: string[], token: string): boolean {
  */
 function stateOf(argv: string[], answeredBy?: string): GraphState {
     const explicit = flag(argv, '--graph');
-    return graphState(resolveRoot(argv), explicit ?? answeredBy);
+    const root = resolveRoot(argv);
+    return graphState(root, explicit ?? answeredBy ?? cacheFor(root));
 }
 
 /** The two histogram lines + the staleness line, in one place so the four
@@ -621,7 +673,7 @@ function cmdDetect(argv: string[]): number {
     }
     for (const v of verdicts) {
         const fresh = v.stale === undefined ? '' : v.stale ? ` · STALE${v.commits_behind !== undefined ? ` (${v.commits_behind} behind)` : ''}` : ' · fresh';
-        process.stdout.write(`${v.kind.padEnd(9)} ${path.relative(root, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
+        process.stdout.write(`${v.kind.padEnd(9)} ${shown(root, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
     }
     const picked = pickSource(verdicts);
     if (picked) process.stdout.write(`→ query would use: ${picked.kind}\n`);
@@ -635,10 +687,21 @@ function budgetSecondsOf(argv: string[]): number {
     return Number.isFinite(n) ? n : DEFAULT_BUDGET_SECONDS;
 }
 
-/** Best-effort removal of a temp build output + its sidecar. Never throws —
- * cleanup failure must not mask the real result (budget-exceeded / error). */
-function cleanupTemp(tmpOut: string): void {
-    for (const p of [tmpOut, sidecarPath(tmpOut)]) {
+/** Best-effort removal of a temp build output, its sidecar, its SQLite twin and
+ * the twin's own half-written temp. Never throws — cleanup failure must not mask
+ * the real result (budget-exceeded / error). */
+export function cleanupTemp(tmpOut: string): void {
+    const twin = sqliteTwinPath(tmpOut);
+    let twinTemps: string[] = [];
+    try {
+        twinTemps = fs
+            .readdirSync(path.dirname(tmpOut))
+            .filter((f) => f.startsWith(`${path.basename(twin)}.tmp-`))
+            .map((f) => path.join(path.dirname(tmpOut), f));
+    } catch {
+        /* the directory is gone, so nothing in it is left to remove */
+    }
+    for (const p of [tmpOut, sidecarPath(tmpOut), twin, ...twinTemps]) {
         try {
             fs.unlinkSync(p);
         } catch {
@@ -647,6 +710,33 @@ function cleanupTemp(tmpOut: string): void {
     }
 }
 
+/**
+ * Remove what a refresh killed before its own cleanup left behind. A file is
+ * only an orphan when the pid in its name is gone AND it is older than a stale
+ * lock: the pid check alone would race a refresh that is starting right now.
+ */
+function sweepOrphanedTemps(out: string): void {
+    const dir = path.dirname(out);
+    const prefix = `.${path.basename(out)}.refresh-tmp-`;
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith(prefix)) continue;
+        const pid = Number(name.slice(prefix.length).split('-')[0]);
+        if (!Number.isInteger(pid) || pid <= 0 || pidAlive(pid)) continue;
+        const full = path.join(dir, name);
+        try {
+            if (Date.now() - fs.statSync(full).mtimeMs > STALE_LOCK_MS) fs.unlinkSync(full);
+        } catch {
+            /* raced another sweeper — fine */
+        }
+    }
+}
+
 /**
  * Run `build` (optionally `--update`) as a CHILD process against a temp
  * `--out` path, under a hard wall-clock budget. Only on a clean, in-budget
@@ -655,6 +745,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
@@ -664,6 +812,7 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
         return 1;
     }
     const dir = path.dirname(out);
+    sweepOrphanedTemps(out);
     const tmpOut = path.join(dir, `.${path.basename(out)}.refresh-tmp-${process.pid}-${randomBytes(4).toString('hex')}.json`);
     if (update) {
         const realSidecar = sidecarPath(out);
@@ -682,6 +831,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,14 +856,38 @@ 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));
-    process.stdout.write(`✅  code-graph refreshed — cache: ${path.relative(root, out)}\n`);
+    // The twin records the JSON's size and mtime; a rename keeps both, so the
+    // promoted twin matches the promoted JSON. Without a twin, the old one goes:
+    // it describes a JSON that no longer exists.
+    const tmpTwin = sqliteTwinPath(tmpOut);
+    if (fs.existsSync(tmpTwin)) fs.renameSync(tmpTwin, sqliteTwinPath(out));
+    else fs.rmSync(sqliteTwinPath(out), { force: true });
+    process.stdout.write(`✅  code-graph refreshed — cache: ${shown(root, out)}\n`);
     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 +895,137 @@ 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;
     }
-    return runBudgetedBuild(root, out, v.verdict === 'STALE', budgetSeconds);
+    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 (out === cacheFor(root)) registerUse(root, null, git(root, 'rev-parse', 'HEAD'));
+        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 home = graphHome(root);
+    const marker = home.autoRefreshPath;
+    if (action === 'on') {
+        if (home.kind === 'global') {
+            // The session concern serves project homes only; its chunk cannot carry the
+            // user-global resolver, so an opt-in here would be a promise nothing keeps.
+            process.stderr.write(
+                `code-graph: auto-refresh needs a project home (agents/ or a project install); ${root} has none.\n` +
+                    'Its graph lives in the user-global home — refresh it with `code-graph refresh`.\n',
+            );
+            return 1;
+        }
+        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;
+    }
+    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 = home.mapDir;
+    const gen = graphGeneration(cacheFor(root));
+    const drawnFrom = mapGeneration(mapDir);
+    const mutex = reclaimMutexPath(home.lockPath);
+    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: ${shown(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 = graphHome(root).mapDir;
+    if (!fs.existsSync(mapDir)) return false;
+    const gen = graphGeneration(cache);
+    return gen !== null && mapGeneration(mapDir) !== gen;
 }
 
 /**
@@ -734,11 +1034,39 @@ function cmdRefresh(argv: string[]): number {
  * Builds or updates the graph first when it is absent or behind.
  */
 async function cmdMap(argv: string[]): Promise<number> {
+    if (argv.includes('--estate')) return estateMapMain(argv);
     const root = resolveRoot(argv);
     if (!fs.existsSync(root)) {
         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 +1084,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(graphHome(root).autoRefreshPath)
+                ? ''
+                : '    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 +1169,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));
@@ -839,14 +1177,23 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'untested') return cmdUntested(argv.slice(1));
         if (sub === 'dead') return cmdDead(argv.slice(1));
         if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
+        if (sub === 'lineage' || (sub === 'map' && argv.includes('--lineage')))
+            return await lineageMain(sub === 'lineage' ? argv.slice(1) : ['map', ...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));
+        if (sub === 'projects') return projectsMain(argv.slice(1));
+        if (sub === 'estate') return estateMain(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|projects|estate|lineage> [options]\n',
         );
         return 2;
     } catch (e) {
+        if (e instanceof UsageError) {
+            process.stderr.write(`code-graph: ${e.message}\n`);
+            return 1;
+        }
         process.stderr.write(`code-graph: internal error: ${(e as Error).message}\n`);
         return 3;
     }