@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/bench_graph_feeder_latency.ts

@@ -66,7 +66,8 @@ import { gitEnv } from './_lib/git_env.js';
 import { graphUntestedVerdict } from './_lib/graph_feeder_record.js';
 import { LexicalIndex } from './_lib/lexical_index.js';
 import { buildFromRepo } from './code_graph/build.js';
-import { graphState, NATIVE_CACHE_REL } from './code_graph/detect.js';
+import { graphState } from './code_graph/detect.js';
+import { graphHome } from './code_graph/graph_home.js';
 import { loadGraph } from './code_graph/query.js';
 import { emitSqliteTwin, sqliteTwinPath } from './code_graph/sqlite_store.js';
 import type { CodeEdge, CodeGraph } from './code_graph/types.js';
@@ -159,7 +160,13 @@ export async function makeFixture(root: string, files: number, withGraph: boolea
     git(dir, ['init', '-q']);
     git(dir, ['add', '-A']);
     git(dir, ['commit', '-q', '-m', 'fixture']);
-    if (withGraph) await buildFromRepo(dir, path.join(dir, NATIVE_CACHE_REL));
+    if (withGraph) {
+        // A project home, as in every repository the feeder serves: the hooks the
+        // bench spawns run under their own user-global root, where a global
+        // graph home would not be found.
+        fs.mkdirSync(path.join(dir, 'agents'));
+        await buildFromRepo(dir, graphHome(dir).cachePath);
+    }
     fs.writeFileSync(path.join(dir, 'src', 'service.ts'), 'export function handle(x: string): string {\n    return x.trim();\n}\n');
     return dir;
 }
@@ -404,7 +411,7 @@ export function benchLoadSplit(opts: { graph: string; runs?: number | undefined
             if (!v.ok) throw new Error(`invalid graph at ${opts.graph}: ${v.errors.slice(0, 3).join('; ')}`);
             const graph = parsed as CodeGraph;
             const t3 = performance.now();
-            const wrote = emitSqliteTwin(graph, raw, copy);
+            const wrote = emitSqliteTwin(graph, copy);
             const t4 = performance.now();
             const byId = new Map(graph.nodes.map((n) => [n.id, n]));
             const outM = new Map<string, CodeEdge[]>();

package/src/scripts/check_dependency_floors.ts

@@ -60,6 +60,13 @@ export const EXACT_PIN_EXCEPTIONS: Readonly<Record<string, string>> = {
         'which would make every grammar load throw rather than degrade — so the runtime ' +
         'and its grammars move together, in one reviewed change, or not at all. ' +
         'Refresh procedure: src/vendor/grammars/README.md.',
+    // The three sigstore modules are the trusted computing base of the
+    // unattended upgrade's provenance check (sigstore_provenance.ts): a
+    // patch release of any of them changes what "verified" means, so each
+    // version is reviewed rather than resolved. They move together.
+    '@sigstore/verify': 'Trusted computing base of the release provenance check; moves only in a reviewed change, with its two siblings.',
+    '@sigstore/bundle': 'Parses the bundle the provenance check verifies; pinned with @sigstore/verify for the same reason.',
+    '@sigstore/protobuf-specs': 'Decodes the pinned trust root and npm keys; pinned with @sigstore/verify for the same reason.',
 };
 
 /**

package/src/scripts/check_egress_mutations.ts

@@ -33,6 +33,7 @@ export const ENGINE_MODULES: readonly string[] = [
     'src/scripts/_lib/egress_rules.ts',
     'src/scripts/_lib/egress_token.ts',
     'src/scripts/_lib/egress_text.ts',
+    'src/scripts/_lib/egress_normalize.ts',
 ];
 
 export interface Recipe {

package/src/scripts/code_graph/build.ts

@@ -79,6 +79,16 @@ const CODE_EXTS: ReadonlySet<string> = new Set(Object.keys(EXT_LANG));
 /** Generated output under the project root: the engine never reads its own artefacts back. */
 const GENERATED_DIRS: ReadonlySet<string> = new Set(['agents/map', 'agents/runtime']);
 
+/** Whether the discovery walk would enter every directory of repo-relative `rel` (posix). */
+export function walkedPath(rel: string): boolean {
+    const dirs = rel.split('/').slice(0, -1);
+    for (let i = 0; i < dirs.length; i++) {
+        const d = dirs[i] as string;
+        if (IGNORE_DIRS.has(d) || d.startsWith('.') || GENERATED_DIRS.has(dirs.slice(0, i + 1).join('/'))) return false;
+    }
+    return true;
+}
+
 export function discoverFiles(root: string, exts: ReadonlySet<string> = CODE_EXTS): string[] {
     return walkFiles(root, (name) => exts.has(path.extname(name).toLowerCase()));
 }
@@ -128,7 +138,7 @@ function walkFiles(root: string, accept: (name: string) => boolean): string[] {
 }
 
 /** 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)$/;
+export 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 {
@@ -266,6 +276,8 @@ 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.
+ *   ruby    `require_relative 'x'` → `x.rb` beside the importer; `require 'a/b'`
+ *           → the one `a/b.rb` under any directory (a load-path root).
  *   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.
@@ -305,6 +317,15 @@ export function resolveLangModule(
         }
         return best ? goFiles.filter((f) => idDirname(f) === best).sort() : [];
     }
+    if (lang === 'ruby') {
+        if (spec.startsWith('.')) {
+            const dir = idDirname(fromFile);
+            const joined = path.posix.normalize(dir && dir !== '.' ? `${dir}/${spec}` : spec);
+            const c = joined.endsWith('.rb') ? joined : `${joined}.rb`;
+            return fileIds.includes(c) ? [c] : [];
+        }
+        return unique([spec.endsWith('.rb') ? spec : `${spec}.rb`]);
+    }
     if (lang === 'csharp') return [...(namespaces.get(spec) ?? [])];
     return [];
 }
@@ -429,6 +450,19 @@ export function buildGraph(
     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);
+    // C# name lookup is scoped by namespace, not by file: a type is visible
+    // from its own namespace, every enclosing one, and each `using`. Within
+    // that set a unique name IS the binding the compiler makes.
+    const csTypes = new Map<string, string[]>();
+    const csVisible = new Map<string, string[]>();
+    for (const ex of extracts) {
+        if (ex.lang !== 'csharp') continue;
+        for (const [id, ns] of Object.entries(ex.typeNamespaces ?? {})) push(csTypes, `${ns}\0${id.slice(id.indexOf('#') + 1)}`, id);
+        const seen = new Set<string>();
+        for (const ns of ex.namespaces ?? []) for (let p = ns; p; p = p.includes('.') ? p.slice(0, p.lastIndexOf('.')) : '') seen.add(p);
+        for (const r of ex.rawEdges) if (r.relation === 'imports' && r.importKind === 'namespace' && !r.localName && r.moduleSpecifier) seen.add(r.moduleSpecifier);
+        csVisible.set(ex.file, [...seen]);
+    }
     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);
@@ -466,7 +500,7 @@ export function buildGraph(
                 continue;
             }
             if (ex.lang === 'csharp' && (namespaceFiles.get(spec)?.length ?? 0) > 1) continue;
-            if (ex.lang === 'python' || ex.lang === 'java' || ex.lang === 'go' || ex.lang === 'csharp') {
+            if (ex.lang === 'python' || ex.lang === 'java' || ex.lang === 'go' || ex.lang === 'csharp' || ex.lang === 'ruby') {
                 const hits = resolveLangModule(ex.lang, ex.file, spec, fileIdList, namespaceFiles);
                 const first = hits[0];
                 if (first === undefined) {
@@ -549,6 +583,11 @@ export function buildGraph(
                 // reported as ones.
                 via: bound.via,
             };
+        if (lang === 'csharp') {
+            const ids = new Set((csVisible.get(file) ?? []).flatMap((ns) => csTypes.get(`${ns}\0${name}`) ?? []));
+            const fit = [...ids].filter((id) => satisfies(nodeKind.get(id), want));
+            if (fit.length === 1) return { target: fit[0] as string, confidence: 'EXTRACTED', via: 'namespace-scope' };
+        }
         if (scopeOnly) return null;
         const wide =
             want === 'constructible'
@@ -654,6 +693,9 @@ export function buildGraph(
             // against a same-named declaration elsewhere in the repository is
             // the defect this roadmap removes, applied to a second relation.
             const hit = resolveInScope(ex.file, r.targetName, 'any', ex.lang, true);
+            // A C# type reference to a framework type (`List`, `Task`) names no
+            // project file, and a `symbol:` edge per mention would only be noise.
+            if (!hit && ex.lang === 'csharp') return;
             emit({
                 source: r.sourceId,
                 target: hit?.target ?? `symbol:${r.targetName}`,
@@ -717,6 +759,28 @@ export function buildGraph(
             }
             return;
         }
+        // scoped `C::m()` whose class the file binds by a stated mechanism
+        // (an import, PSR-4, a local declaration, a C# namespace): the class
+        // is known, so a method it declares or inherits is the target, and the
+        // edge is exactly as trustworthy as the class binding.
+        if ((r.callStyle === 'scoped' || r.callStyle === 'dynamic') && r.scopeName) {
+            const cls = resolveInScope(ex.file, r.scopeName, 'any', ex.lang, true);
+            const kind = cls ? nodeKind.get(cls.target) : undefined;
+            if (cls && isStatedResolution(cls.via) && (kind === 'class' || kind === 'interface' || kind === 'enum')) {
+                const m = resolveHierMethod(cls.target, r.targetName);
+                if (m) {
+                    emit({
+                        source: r.sourceId,
+                        target: m,
+                        relation: 'calls',
+                        confidence: m.startsWith(`${cls.target}::`) ? cls.confidence : 'INFERRED',
+                        resolved_via: cls.via,
+                        provider: 'native',
+                    });
+                    return;
+                }
+            }
+        }
         // scoped (Class::m unresolved / facade) or dynamic ($obj->m) → AMBIGUOUS
         const cands = methodCandidates(r.targetName, ex.lang);
         if (r.callStyle === 'dynamic' && cands.length === 0) {
@@ -1129,7 +1193,7 @@ export async function buildFromRepo(
         write_atomic(sidecarPath(cachePath), JSON.stringify(nextSidecar));
         // Derived SQLite twin (ADR-129): best-effort accelerator beside the
         // canonical JSON — never fails the build, no-op on old Node.
-        emitSqliteTwin(graph, json, cachePath);
+        emitSqliteTwin(graph, cachePath);
     }
     return { graph, json, fileCount: files.length, reExtracted, reused };
 }

package/src/scripts/code_graph/cli.ts

@@ -12,6 +12,11 @@
  *                                               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
@@ -29,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
@@ -46,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)
@@ -81,16 +96,21 @@ import {
     detectSources,
     type GraphState,
     graphState,
-    NATIVE_CACHE_REL,
     pickSource,
 } from './detect.js';
+import { graphHome } from './graph_home.js';
 import { suggestVerb } from './intent.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 {
-    AUTO_REFRESH_REL,
-    LOCK_REL,
+    STALE_LOCK_MS,
     acquire as acquireRefreshLock,
+    pidAlive,
     readRefreshRecords,
     reclaimMutexPath,
     recordRefresh,
@@ -121,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;
@@ -157,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 {
@@ -197,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` +
@@ -204,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;
@@ -261,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;
     }
@@ -309,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 {
@@ -429,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
@@ -635,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`);
@@ -649,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 {
@@ -661,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
@@ -736,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);
@@ -795,7 +872,13 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
     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;
 }
 
@@ -844,6 +927,7 @@ async function cmdRefresh(argv: string[]): Promise<number> {
             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}`);
@@ -864,8 +948,18 @@ async function cmdRefresh(argv: string[]): Promise<number> {
 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);
+    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);
@@ -896,10 +990,10 @@ function cmdAutoRefresh(argv: string[]): number {
     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 mapDir = home.mapDir;
     const gen = graphGeneration(cacheFor(root));
     const drawnFrom = mapGeneration(mapDir);
-    const mutex = reclaimMutexPath(path.join(root, LOCK_REL));
+    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` +
@@ -908,7 +1002,7 @@ function cmdAutoRefresh(argv: string[]): number {
             `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`
+                ? `reclaim mutex: ${shown(root, mutex)} left by a crash — stale locks stay held until it is removed by hand\n`
                 : ''),
     );
     return 0;
@@ -928,7 +1022,7 @@ function mutexAgeMs(p: string): number {
  * 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');
+    const mapDir = graphHome(root).mapDir;
     if (!fs.existsSync(mapDir)) return false;
     const gen = graphGeneration(cache);
     return gen !== null && mapGeneration(mapDir) !== gen;
@@ -940,6 +1034,7 @@ function mapIsBehind(root: string, cache: string): boolean {
  * 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`);
@@ -990,7 +1085,7 @@ async function drawMap(argv: string[]): Promise<number> {
                 ? `    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` +
-            (fs.existsSync(path.join(root, AUTO_REFRESH_REL))
+            (fs.existsSync(graphHome(root).autoRefreshPath)
                 ? ''
                 : '    keep it current at every agent session start: agent-config code-graph auto-refresh on\n'),
     );
@@ -1082,15 +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|auto-refresh> [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;
     }

package/src/scripts/code_graph/conventions_default.ts

@@ -19,6 +19,21 @@ import type { SourceFile } from './build.js';
 import type { CodeEdge, CodeNode, ResolvedVia } from './types.js';
 import { EXT_LANG, MAX_FILE_BYTES } from './types.js';
 
+/** A line that is a log, print or throw call up to this point: its literals are messages, not files. */
+const MESSAGE_CALL =
+    /(?:\bconsole\.\w+|\blog(?:ger|ging)?\.\w+|\bLog::\w+|\b(?:print|println|printf|echo|error_log)\b|\bthrow\s+new\s+\w+)\s*\(?/;
+
+/** `src` with comments and Python docstrings blanked to spaces, every offset and newline kept. */
+function maskComments(src: string, lang: string | undefined): string {
+    const blank = (m: string): string => m.replace(/[^\n]/g, ' ');
+    let out = src
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/(^|[^:'"\\])(\/\/[^\n]*)/g, (_m, pre: string, c: string) => pre + blank(c));
+    if (lang === 'python' || lang === 'php') out = out.replace(/(^|[ \t])(#[^\n]*)/gm, (_m, pre: string, c: string) => pre + blank(c));
+    if (lang === 'python') out = out.replace(/("""|''')[\s\S]*?\1/g, blank);
+    return out;
+}
+
 /** The text right before a JS/TS module specifier: `from`, `import`, `import(`, `require(`. */
 const IMPORT_POSITION = /(?:\bfrom|\bimport|\bimport\s*\(|\brequire\s*\()\s*$/;
 
@@ -177,8 +192,12 @@ export function conventionsDefault(input: DefaultInput): { nodes: CodeNode[]; ed
         const jsLike = lang === 'typescript' || lang === 'javascript';
         if (on['literal-path']) {
             // Single and double quotes only: a backtick span is usually a mention in a comment.
-            for (const m of f.source.matchAll(/(['"])([^'"`\s\\${}()<>|,;]{3,200})\1/g)) {
+            // Comments and docstrings are blanked first, so a path they mention is never read.
+            const code = maskComments(f.source, lang);
+            for (const m of code.matchAll(/(['"])([^'"`\s\\${}()<>|,;]{3,200})\1/g)) {
                 const lit = m[2] as string;
+                const lineStart = code.lastIndexOf('\n', m.index as number) + 1;
+                if (MESSAGE_CALL.test(code.slice(lineStart, m.index as number))) continue;
                 // A module specifier belongs to the import tier: resolved, it is an
                 // `imports` edge already; unresolved, it is an external module — a
                 // read in neither case.

package/src/scripts/code_graph/detect.ts

@@ -19,6 +19,7 @@ import * as path from 'node:path';
 
 import { load_agent_settings } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { projectHome } from './graph_home.js';
 import { EXT_LANG } from './types.js';
 import { validateGraph } from './validate.js';
 
@@ -226,9 +227,6 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
     };
 }
 
-/** Cache path a repository root's native graph lives at, repo-relative. */
-export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
-
 /**
  * The four-state staleness token every consumer of the graph reports.
  *
@@ -328,10 +326,12 @@ function hasUncommittedIndexedEdit(root: string): boolean {
  * report `absent` while answering from that very file — the state of a cache
  * nobody asked about. Passing the graph the verb is actually reading makes the
  * printed staleness a statement about the answer rather than about a
- * convention.
+ * convention. The default is the project home only: the hooks that call this
+ * ship in the dispatch bundle, which cannot carry the user-global resolver, so
+ * a caller serving a user-global home passes `graphHome(root).cachePath`.
  */
 export function graphState(root: string, nativeCache?: string): GraphState {
-    const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
+    const picked = pickSource(detectSources(root, nativeCache ?? projectHome(root).cachePath));
     if (!picked) return 'absent';
     if (picked.stale === true) {
         const behind = picked.commits_behind;