@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/code_graph/graph_budget.ts

@@ -0,0 +1,158 @@
+/**
+ * The storage budget for user-global graph homes (ADR-299, council O4).
+ *
+ * Only directories under `runtime/graphs/` are ever evicted — a graph under a
+ * repository's own `agents/` is the project's, not this machine's cache.
+ * Eviction is least-recently-QUERIED first: a query touches its home's
+ * `.last-query` marker, a build or refresh records it in the registry, and a
+ * registry scan changes neither. A pinned project's homes, a home whose
+ * refresh lock is held, and a home written to within a stale-lock window or
+ * holding a temp output are never evicted, so a budget can stay exceeded. The
+ * last guard exists because a plain `code-graph build` takes no lock.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readRegistry, updateRegistry } from '../_lib/project_registry.js';
+import { graphHome, graphsRoot } from './graph_home.js';
+import { isStale, STALE_LOCK_MS } from './refresh_lock.js';
+
+const MB = 1024 * 1024;
+const LAST_QUERY = '.last-query';
+
+/** Record that a query just read `root`'s graph. Only user-global homes keep recency. */
+export function touchHome(root: string): void {
+    try {
+        const home = graphHome(root);
+        if (home.kind !== 'global' || !fs.existsSync(home.dir)) return;
+        const marker = path.join(home.dir, LAST_QUERY);
+        const now = new Date();
+        try {
+            fs.utimesSync(marker, now, now);
+        } catch {
+            fs.writeFileSync(marker, '');
+        }
+    } catch {
+        /* recency is a hint; a query never fails on it */
+    }
+}
+
+interface Walk {
+    bytes: number;
+    /** Newest mtime of anything below the home except the query marker. */
+    newest: number;
+    /** A build's or refresh's temp output is present. */
+    temp: boolean;
+}
+
+const TEMP_RE = /\.refresh-tmp-|\.tmp-/;
+
+function walk(dir: string, top: boolean, acc: Walk = { bytes: 0, newest: 0, temp: false }): Walk {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return acc;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (TEMP_RE.test(e.name)) acc.temp = true;
+        let st: fs.Stats;
+        try {
+            st = fs.lstatSync(p);
+        } catch {
+            continue;
+        }
+        if (!(top && e.name === LAST_QUERY)) acc.newest = Math.max(acc.newest, st.mtimeMs);
+        if (e.isDirectory()) walk(p, false, acc);
+        else acc.bytes += st.size;
+    }
+    return acc;
+}
+
+export interface HomeUsage {
+    dir: string;
+    bytes: number;
+    /** Last query, else last build or refresh, else the directory's own mtime. */
+    used_at: number;
+    pinned: boolean;
+    locked: boolean;
+    /** Written within the last {@link STALE_LOCK_MS}, or holding a temp output: a build may be mid-write. */
+    busy: boolean;
+    project: string | null;
+}
+
+/** Every user-global graph home with its size and why it may or may not go. */
+export function homeUsage(): HomeUsage[] {
+    const base = graphsRoot();
+    let names: string[];
+    try {
+        names = fs.readdirSync(base);
+    } catch {
+        return [];
+    }
+    const reg = readRegistry();
+    const owner = new Map<string, { id: string; pinned: boolean; at: number }>();
+    for (const [id, e] of Object.entries(reg.projects)) {
+        for (const [dir, at] of Object.entries(e.homes)) owner.set(dir, { id, pinned: e.pinned, at: Date.parse(at) || 0 });
+    }
+    const out: HomeUsage[] = [];
+    const now = Date.now();
+    for (const name of names) {
+        const dir = path.join(base, name);
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(dir);
+        } catch {
+            continue;
+        }
+        if (!st.isDirectory()) continue;
+        let queried = 0;
+        try {
+            queried = fs.statSync(path.join(dir, LAST_QUERY)).mtimeMs;
+        } catch {
+            queried = 0;
+        }
+        const o = owner.get(dir);
+        const lock = path.join(dir, 'state', 'code-graph-refresh.lock');
+        const w = walk(dir, true);
+        out.push({
+            dir,
+            bytes: w.bytes,
+            used_at: Math.max(queried, o?.at ?? 0) || st.mtimeMs,
+            pinned: o?.pinned ?? false,
+            locked: fs.existsSync(lock) && !isStale(lock),
+            busy: w.temp || now - w.newest < STALE_LOCK_MS,
+            project: o?.id ?? null,
+        });
+    }
+    return out;
+}
+
+/**
+ * Evict the least recently used homes until the total fits `budget_mb`;
+ * returns what went. `keep` is the home a build just wrote, which is never its
+ * own victim.
+ */
+export function enforceBudget(keep?: string): { evicted: HomeUsage[]; total: number; budget: number } {
+    const budget = readRegistry().budget_mb * MB;
+    const homes = homeUsage();
+    let total = homes.reduce((n, h) => n + h.bytes, 0);
+    const evicted: HomeUsage[] = [];
+    for (const h of [...homes].sort((a, b) => a.used_at - b.used_at)) {
+        if (total <= budget) break;
+        if (h.pinned || h.locked || h.busy || h.dir === keep) continue;
+        fs.rmSync(h.dir, { recursive: true, force: true });
+        total -= h.bytes;
+        evicted.push(h);
+    }
+    if (evicted.length) {
+        const gone = new Set(evicted.map((h) => h.dir));
+        updateRegistry((reg) => {
+            for (const e of Object.values(reg.projects)) {
+                for (const dir of Object.keys(e.homes)) if (gone.has(dir)) delete e.homes[dir];
+            }
+        });
+    }
+    return { evicted, total, budget };
+}

package/src/scripts/code_graph/graph_home.ts

@@ -0,0 +1,80 @@
+/**
+ * Where a root's graph, map and refresh lock live (ADR-299).
+ *
+ * A root that has `agents/` or a project install keeps today's paths under
+ * `<root>/agents/`, byte-identical, so a map shared through the repository is
+ * unchanged. Every other root gets a home under the user-global
+ * `runtime/graphs/<repo id>-<checkout | instance>/`, so building a graph of
+ * somebody else's repository writes nothing into it, and two clones of one
+ * origin never share a cache, lock or budget slot. Resolving never creates `agents/`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { type EnvMap, event4u_root } from '../_lib/user_global_paths.js';
+import { repoIdentity } from './repo_identity.js';
+
+export const STATE_DIR_REL = path.join('agents', 'runtime', 'state');
+export const NATIVE_CACHE_REL = path.join(STATE_DIR_REL, 'code-graph-v1.json');
+export const MAP_DIR_REL = path.join('agents', 'map');
+export const LOCK_REL = path.join(STATE_DIR_REL, 'code-graph-refresh.lock');
+/** Written by `code-graph auto-refresh on`; the session concern acts only while it exists. */
+export const AUTO_REFRESH_REL = path.join(STATE_DIR_REL, 'code-graph-auto-refresh.json');
+
+export interface GraphHome {
+    kind: 'project' | 'global';
+    root: string;
+    /** `<root>/agents` for a project home, the per-repository directory otherwise. */
+    dir: string;
+    stateDir: string;
+    cachePath: string;
+    mapDir: string;
+    lockPath: string;
+    autoRefreshPath: string;
+    repoId: string | null;
+    instance: string | null;
+}
+
+export function graphsRoot(env?: EnvMap | null): string {
+    return path.join(event4u_root(env), 'runtime', 'graphs');
+}
+
+/** `agents/` exists, or the installer's settings file marks a project install. */
+export function hasProjectHome(root: string): boolean {
+    return fs.existsSync(path.join(root, 'agents')) || fs.existsSync(path.join(root, '.agent-settings.yml'));
+}
+
+/** Today's in-repository paths; callers that serve project homes only use this alone. */
+export function projectHome(root: string): GraphHome {
+    return {
+        kind: 'project',
+        root,
+        dir: path.join(root, 'agents'),
+        stateDir: path.join(root, STATE_DIR_REL),
+        cachePath: path.join(root, NATIVE_CACHE_REL),
+        mapDir: path.join(root, MAP_DIR_REL),
+        lockPath: path.join(root, LOCK_REL),
+        autoRefreshPath: path.join(root, AUTO_REFRESH_REL),
+        repoId: null,
+        instance: null,
+    };
+}
+
+export function graphHome(root: string, env?: EnvMap | null): GraphHome {
+    if (hasProjectHome(root)) return projectHome(root);
+    const id = repoIdentity(root, env);
+    const dir = path.join(graphsRoot(env), `${id.repoId}-${id.instance ?? id.checkout}`);
+    const stateDir = path.join(dir, 'state');
+    return {
+        kind: 'global',
+        root,
+        dir,
+        stateDir,
+        cachePath: path.join(stateDir, path.basename(NATIVE_CACHE_REL)),
+        mapDir: path.join(dir, 'map'),
+        lockPath: path.join(stateDir, path.basename(LOCK_REL)),
+        autoRefreshPath: path.join(stateDir, path.basename(AUTO_REFRESH_REL)),
+        repoId: id.repoId,
+        instance: id.instance,
+    };
+}

package/src/scripts/code_graph/lineage_cli.ts

@@ -0,0 +1,315 @@
+/**
+ * `code-graph lineage <verb>` — where harvested mechanisms came from, and what is still missing.
+ *
+ * Two ledgers answer, never one (council O5): the tracked, source-free decision ledger
+ * `provenance/mechanisms.jsonl` of the repo at `--root`, and the local source ledger under
+ * the user-global `runtime/lineage/` (`_lib/lineage_ledger.ts`). A verb that needs the
+ * local side and the key refuses without them instead of answering from half the data.
+ *
+ * Exit codes: 0 ok · 1 findings · 2 usage or refused.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    assertOutsideWorkTree,
+    checkLedger,
+    hasLedger,
+    LineageError,
+    lineageDir,
+    mergeIntoLedger,
+    readLedger,
+    writeLedger,
+    writePrivateFile,
+} from '../_lib/lineage_ledger.js';
+import { BACKFILL_DIR_REL, isIgnored, scanTree, writeBackfill } from '../_lib/lineage_backfill.js';
+import { LINEAGE_VIEW_REL, renderSourceLineage, renderTrackedLineage } from '../_lib/lineage_map.js';
+import { refuseUnderCi, renderWatchReport, renderWatchStub, runWatch, systemGit } from '../_lib/lineage_watch.js';
+import { gaps, lineageFrom, lineageOf, readDecisions, rejected } from '../_lib/lineage_query.js';
+import { buildLocalImport } from '../_lib/lineage_seed.js';
+import { resolve_keys } from '../_lib/link_crypto.js';
+import type { EnvMap } from '../_lib/user_global_paths.js';
+
+export interface LineageDeps {
+    readonly env?: EnvMap;
+    /** Link keys; resolved from settings when absent. Tests pass them explicitly. */
+    readonly keys?: readonly string[];
+    readonly now?: () => Date;
+    readonly stdout?: (s: string) => void;
+    readonly stderr?: (s: string) => void;
+}
+
+export interface Io {
+    readonly env: EnvMap;
+    readonly root: string;
+    readonly keys: () => readonly string[];
+    readonly now: () => Date;
+    readonly out: (s: string) => void;
+    readonly err: (s: string) => void;
+}
+
+export function flag(argv: readonly string[], name: string): string | undefined {
+    const i = argv.indexOf(name);
+    return i === -1 ? undefined : argv[i + 1];
+}
+
+function cmdCheck(io: Io): number {
+    const dir = lineageDir(io.env);
+    if (!hasLedger(dir)) {
+        io.err(`code-graph lineage: no local lineage ledger at ${dir} — run \`code-graph lineage import\` first\n`);
+        return 2;
+    }
+    const findings = checkLedger(dir, io.keys());
+    const { sources, edges } = readLedger(dir);
+    if (findings.length > 0) {
+        for (const f of findings) io.err(`${f.file}:${String(f.line)} ${f.message}\n`);
+        io.err(`code-graph lineage check: ${String(findings.length)} finding(s)\n`);
+        return 1;
+    }
+    io.out(`code-graph lineage check: ${String(sources.length)} source(s), ${String(edges.length)} edge(s) OK at ${dir}\n`);
+    return 0;
+}
+
+/** Refuse, naming the setting, when no link key is configured. */
+export function needKeys(io: Io, verb: string): readonly string[] | null {
+    const keys = io.keys();
+    if (keys.length > 0) return keys;
+    io.err(
+        `code-graph lineage ${verb}: no link_encryption_key configured (secrets.link_encryption_key) — ` +
+            'the local ledger is sealed with it, so nothing is read or written without it\n',
+    );
+    return null;
+}
+
+function cmdImport(io: Io): number {
+    const keys = needKeys(io, 'import');
+    if (keys === null) return 2;
+    const { ledger, refused } = buildLocalImport(io.root, keys);
+    const dir = lineageDir(io.env);
+    const added = mergeIntoLedger(dir, ledger, keys);
+    for (const r of refused) io.err(`code-graph lineage import: skipped ${r}\n`);
+    io.out(
+        `code-graph lineage import: ${String(added.sources)} new source(s), ${String(added.edges)} new edge(s) into ${dir}` +
+            `${refused.length > 0 ? ` · ${String(refused.length)} skipped` : ''}\n`,
+    );
+    return refused.length > 0 ? 1 : 0;
+}
+
+/** The graph's node lookup for `root`, or null when no graph has been built. */
+async function graphLookup(io: Io, explicit: string | undefined): Promise<{ has(id: string): boolean } | null> {
+    // Dynamic: cli.ts dispatches into this module, and the default cache path is its to own.
+    const graphPath = explicit ?? (await import('./cli.js')).cacheFor(io.root);
+    if (!fs.existsSync(graphPath)) return null;
+    const { loadGraph } = await import('./query.js');
+    return loadGraph(graphPath).byId;
+}
+
+async function cmdOf(io: Io, query: string | undefined, graphFlag: string | undefined): Promise<number> {
+    if (query === undefined || query.startsWith('--')) {
+        io.err('usage: code-graph lineage of <mechanism-id|path> [--root P] [--graph P]\n');
+        return 2;
+    }
+    const entries = lineageOf(io.root, query, await graphLookup(io, graphFlag));
+    if (entries.length === 0) {
+        io.err(`code-graph lineage of: no mechanism matches ${query} in provenance/mechanisms.jsonl\n`);
+        return 1;
+    }
+    let broken = 0;
+    for (const e of entries) {
+        io.out(`${e.mechanism_id}  ${e.verdict}  ${e.decided_at}  (${String(e.decisions)} decision(s))\n`);
+        for (const r of e.realised) {
+            if (r.status === 'broken') broken += 1;
+            const g = r.in_graph === null ? 'no graph built' : r.in_graph ? 'indexed' : 'not indexed';
+            io.out(`  realised_in ${r.path}  ${r.status === 'ok' ? 'ok' : 'BROKEN'}  graph: ${g}\n`);
+        }
+    }
+    if (broken > 0) io.err(`code-graph lineage of: ${String(broken)} broken edge(s) — the file moved or is gone\n`);
+    return broken > 0 ? 1 : 0;
+}
+
+function cmdGaps(io: Io): number {
+    const view = gaps(readDecisions(io.root));
+    for (const g of view) {
+        io.out(`${g.mechanism_id}  ${g.verdict}  ${g.owner}${g.reopen_if ? `  reopen if: ${g.reopen_if}` : ''}\n`);
+    }
+    io.out(`code-graph lineage gaps: ${String(view.length)} open mechanism(s)\n`);
+    return 0;
+}
+
+function cmdRejected(io: Io): number {
+    const view = rejected(readDecisions(io.root));
+    for (const r of view) {
+        io.out(`${r.mechanism_id}  ${r.reason ?? ''}${r.reopen_if ? `  reopen if: ${r.reopen_if}` : ''}\n`);
+    }
+    io.out(`code-graph lineage rejected: ${String(view.length)} rejected mechanism(s)\n`);
+    return 0;
+}
+
+function cmdFrom(io: Io, query: string | undefined): number {
+    if (query === undefined || query.startsWith('--')) {
+        io.err('usage: code-graph lineage from <source-id|identity> [--root P]\n');
+        return 2;
+    }
+    const dir = lineageDir(io.env);
+    if (!hasLedger(dir)) {
+        io.err(`code-graph lineage from: no local lineage ledger at ${dir} — the source side exists only on the owner's machine\n`);
+        return 2;
+    }
+    const keys = needKeys(io, 'from');
+    if (keys === null) return 2;
+    const found = lineageFrom(readLedger(dir), query, keys, readDecisions(io.root));
+    if (found === null) {
+        io.err('code-graph lineage from: no such source in the local ledger\n');
+        return 1;
+    }
+    io.out(`${found.source.source_id}  ${found.source.kind}  ${found.identity}  license ${found.source.license}  watch ${found.source.watch ? 'on' : 'off'}\n`);
+    for (const m of found.mechanisms) {
+        io.out(`  ${m.mechanism_id}  ${m.verdict ?? '(no decision)'}  pin ${m.pin}${m.locator ? `  at ${m.locator}` : ''}\n`);
+    }
+    return 0;
+}
+
+/**
+ * `map --lineage` (tracked view, verdicts only) or `map --lineage --sources` (local view).
+ * The tracked view is written only into a repo that already has `agents/`, so a foreign
+ * repository never gains a directory from it.
+ */
+function cmdMap(io: Io, argv: readonly string[]): number {
+    const outFlag = flag(argv, '--out');
+    if (argv.includes('--sources')) {
+        const out = path.resolve(outFlag ?? path.join(lineageDir(io.env), 'map', 'sources.md'));
+        assertOutsideWorkTree(out);
+        const dir = lineageDir(io.env);
+        if (!hasLedger(dir)) {
+            io.err(`code-graph lineage map --sources: no local lineage ledger at ${dir}\n`);
+            return 2;
+        }
+        const keys = needKeys(io, 'map --sources');
+        if (keys === null) return 2;
+        writePrivateFile(out, renderSourceLineage(readLedger(dir), keys, readDecisions(io.root)));
+        io.out(`code-graph lineage map: source view written to ${out}\n`);
+        return 0;
+    }
+    const out = path.resolve(outFlag ?? path.join(io.root, LINEAGE_VIEW_REL));
+    if (outFlag === undefined && !fs.existsSync(path.join(io.root, 'agents'))) {
+        io.err(`code-graph lineage map: ${io.root} has no agents/ directory — pass --out to choose where the view goes\n`);
+        return 2;
+    }
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, renderTrackedLineage(readDecisions(io.root)));
+    io.out(`code-graph lineage map: tracked view written to ${out}\n`);
+    return 0;
+}
+
+function cmdBackfill(io: Io, argv: readonly string[]): number {
+    if (!argv.includes('--draft')) {
+        io.err('code-graph lineage backfill: only --draft exists — the backfill proposes drafts and never writes a ledger row\n');
+        return 2;
+    }
+    if (!isIgnored(io.root, BACKFILL_DIR_REL)) {
+        io.err(`code-graph lineage backfill: ${BACKFILL_DIR_REL}/ is not ignored by git in ${io.root} — decrypted identities would become trackable\n`);
+        return 2;
+    }
+    const keys = needKeys(io, 'backfill');
+    if (keys === null) return 2;
+    const result = scanTree(io.root, keys);
+    const out = writeBackfill(io.root, result);
+    for (const u of result.unclear) io.out(`unclear ${u}\n`);
+    for (const u of result.undecryptable) io.out(`undecryptable ${u}\n`);
+    io.out(
+        `code-graph lineage backfill: ${String(result.drafts.length)} draft(s), ${String(result.unclear.length)} unclear, ` +
+            `${String(result.undecryptable.length)} undecryptable — written to ${out}; no ledger row written\n`,
+    );
+    return 0;
+}
+
+function cmdWatchFlag(io: Io, on: boolean, id: string | undefined): number {
+    const dir = lineageDir(io.env);
+    if (id === undefined || !hasLedger(dir)) {
+        io.err(`usage: code-graph lineage watch ${on ? 'enable' : 'disable'} <source-id> (needs the local ledger at ${dir})\n`);
+        return 2;
+    }
+    const ledger = readLedger(dir);
+    const hit = ledger.sources.find((s) => s.source_id === id);
+    if (hit === undefined) {
+        io.err(`code-graph lineage watch: no source ${id} in the local ledger\n`);
+        return 1;
+    }
+    writeLedger(dir, { sources: ledger.sources.map((s) => (s.source_id === id ? { ...s, watch: on } : s)), edges: ledger.edges });
+    io.out(`code-graph lineage watch: ${id} ${on ? 'on' : 'off'}\n`);
+    return 0;
+}
+
+function cmdWatch(io: Io, argv: readonly string[]): number {
+    if (argv[1] === 'enable' || argv[1] === 'disable') return cmdWatchFlag(io, argv[1] === 'enable', argv[2]);
+    refuseUnderCi(io.env);
+    const dir = lineageDir(io.env);
+    if (!hasLedger(dir)) {
+        io.err(`code-graph lineage watch: no local lineage ledger at ${dir}\n`);
+        return 2;
+    }
+    const keys = needKeys(io, 'watch');
+    if (keys === null) return 2;
+    const reports = runWatch({ dir, keys, rows: readDecisions(io.root), git: systemGit, env: io.env });
+    for (const r of reports) {
+        io.out(`${r.source_id}  ${r.status}${r.note ? `  ${r.note}` : ''}\n`);
+        for (const f of r.findings) io.out(`  ${f.class}  ${f.mechanism_id ?? '(no mechanism)'}  ${f.locator}\n`);
+    }
+    io.out(`code-graph lineage watch: ${String(reports.length)} watched source(s)\n`);
+    if (argv.includes('--dry-run')) return 0;
+
+    const date = io.now().toISOString().slice(0, 10);
+    if (reports.length > 0) {
+        const reportPath = path.join(dir, 'watch', `report-${date}.md`);
+        writePrivateFile(reportPath, renderWatchReport(reports, date));
+        io.out(`code-graph lineage watch: report written to ${reportPath}\n`);
+    }
+    const stub = renderWatchStub(reports, date, keys[0] as string);
+    if (stub === null) return 0;
+    const stubDir = path.join(io.root, 'agents', 'roadmaps', 'stubs');
+    if (!fs.existsSync(stubDir)) {
+        io.err(`code-graph lineage watch: ${io.root} has no agents/roadmaps/stubs/ — the stub was not written\n`);
+        return 2;
+    }
+    const stubPath = path.join(stubDir, `road-to-lineage-delta-${date}.md`);
+    fs.writeFileSync(stubPath, stub);
+    io.out(`code-graph lineage watch: stub written to ${stubPath}\n`);
+    return 0;
+}
+
+const USAGE = 'usage: code-graph lineage <check|import|of|gaps|rejected|from|map|backfill|watch> [args] [--root P]\n';
+
+export async function main(argv: readonly string[], deps: LineageDeps = {}): Promise<number> {
+    const env = deps.env ?? process.env;
+    const root = path.resolve(flag(argv, '--root') ?? process.cwd());
+    let cached: readonly string[] | null = null;
+    const io: Io = {
+        env,
+        root,
+        keys: () => (cached ??= deps.keys ?? resolve_keys(root)),
+        now: deps.now ?? (() => new Date()),
+        out: deps.stdout ?? ((s) => void process.stdout.write(s)),
+        err: deps.stderr ?? ((s) => void process.stderr.write(s)),
+    };
+    const verb = argv[0];
+    try {
+        if (verb === 'check') return cmdCheck(io);
+        if (verb === 'import') return cmdImport(io);
+        if (verb === 'of') return await cmdOf(io, argv[1], flag(argv, '--graph'));
+        if (verb === 'gaps') return cmdGaps(io);
+        if (verb === 'rejected') return cmdRejected(io);
+        if (verb === 'from') return cmdFrom(io, argv[1]);
+        if (verb === 'map') return cmdMap(io, argv);
+        if (verb === 'backfill') return cmdBackfill(io, argv);
+        if (verb === 'watch') return cmdWatch(io, argv);
+    } catch (e) {
+        if (e instanceof LineageError) {
+            io.err(`code-graph lineage: ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+    io.err(USAGE);
+    return 2;
+}

package/src/scripts/code_graph/map.ts

@@ -23,7 +23,8 @@ import { write_atomic } from '../_lib/fs_atomic.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
 import { buildFromRepo, readProjectProbe } from './build.js';
 import { acquire as acquireRefreshLock, heldByThisProcess } from './refresh_lock.js';
-import { computeVerdict, graphState, NATIVE_CACHE_REL } from './detect.js';
+import { computeVerdict, graphState } from './detect.js';
+import { graphHome } from './graph_home.js';
 import {
     areaDrift,
     buildMapModel,
@@ -39,7 +40,6 @@ import type { CodeGraph } from './types.js';
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const VIEWER_DIR = path.join(_HERE, 'map_viewer');
 
-export const MAP_DIR_REL = path.join('agents', 'map');
 /** Rough characters-per-token used to hold MAP.md to its budget. */
 const CHARS_PER_TOKEN = 4;
 export const MAP_TOKEN_BUDGET = 2000;
@@ -233,12 +233,14 @@ export function diffFiles(root: string, rev: string): string[] | null {
 }
 
 /** Where `code-graph outcome` records which files a session found useful — local, never sent anywhere. */
-export const OUTCOMES_REL = path.join('agents', 'runtime', 'state', 'map-outcomes.jsonl');
+export function outcomesPath(root: string): string {
+    return path.join(graphHome(root).stateDir, 'map-outcomes.jsonl');
+}
 
 export function readOutcomes(root: string): OutcomeEvent[] {
     let text: string;
     try {
-        text = fs.readFileSync(path.join(root, OUTCOMES_REL), 'utf-8');
+        text = fs.readFileSync(outcomesPath(root), 'utf-8');
     } catch {
         return [];
     }
@@ -259,7 +261,7 @@ export function readOutcomes(root: string): OutcomeEvent[] {
 }
 
 export function recordOutcome(root: string, file: string, outcome: OutcomeEvent['outcome'], at: Date = new Date()): void {
-    const p = path.join(root, OUTCOMES_REL);
+    const p = outcomesPath(root);
     fs.mkdirSync(path.dirname(p), { recursive: true });
     const rel = path.relative(fs.realpathSync(root), fs.realpathSync(path.resolve(file)));
     if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) throw new Error(`not a file inside ${root}: ${file}`);
@@ -310,7 +312,8 @@ export async function buildMap(
 let drawing = false;
 
 async function drawGeneration(root: string, opts: Parameters<typeof buildMap>[1] = {}): Promise<MapBuildResult> {
-    const outDir = opts.outDir ?? path.join(root, MAP_DIR_REL);
+    const home = graphHome(root);
+    const outDir = opts.outDir ?? home.mapDir;
     // A chosen --out directory is only ever written into when it is empty or
     // already holds a map: the writer clears stale area pages, and that must
     // never reach a directory of someone else's Markdown.
@@ -322,7 +325,7 @@ async function drawGeneration(root: string, opts: Parameters<typeof buildMap>[1]
     ) {
         throw new Error(`refusing to write a map into ${outDir}: it is not empty and holds no map.json`);
     }
-    const cachePath = opts.cachePath ?? path.join(root, NATIVE_CACHE_REL);
+    const cachePath = opts.cachePath ?? home.cachePath;
     const { graph, built } = await loadOrBuildGraph(root, cachePath, opts.noBuild === true);
     let diff: { rev: string; changed: string[] } | undefined;
     if (opts.diffRev !== undefined) {
@@ -364,7 +367,7 @@ async function drawGeneration(root: string, opts: Parameters<typeof buildMap>[1]
     // The default map stages under the gitignored runtime dir, so a killed redraw
     // leaves nothing in agents/ itself; a chosen --out stages beside itself.
     const suffix = `${process.pid}-${randomBytes(4).toString('hex')}`;
-    const stage = opts.outDir === undefined ? path.join(root, 'agents', 'runtime', 'state') : path.dirname(outDir);
+    const stage = opts.outDir === undefined ? home.stateDir : path.dirname(outDir);
     fs.mkdirSync(stage, { recursive: true });
     const next = path.join(stage, `.map-next-${suffix}`);
     const prev = path.join(stage, `.map-prev-${suffix}`);
@@ -633,7 +636,7 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
         const rank = (r: (typeof rp)[number]): number =>
             (r.route.startsWith('GET ') ? 0 : 2) + (r.views.length > 0 ? 0 : 1);
         const withChain = rp
-            .filter((r) => r.views.length + r.tables.length > 0)
+            .filter((r) => r.views.length + r.tables.length + (r.inferredTables?.length ?? 0) > 0)
             .sort((a, b) => rank(a) - rank(b) || (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
         sections.push([
             'Request paths',
@@ -641,7 +644,8 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
                 '## Request paths',
                 '',
                 `${m.analyses.requestPathsTotal} declared routes; ${m.analyses.requestPathsResolved} reach a handler in this tree. ` +
-                    'Route → handler → views it renders · tables its models persist:',
+                    'Route → handler → views it renders · tables its models persist, up to three calls deep ' +
+                    '(inferred: reached through a call bound by name alone):',
                 '',
                 ...(withChain.length ? withChain : rp).slice(0, 10).map((r) => {
                     const handlerFile = path.posix.basename(f[r.handler]?.path ?? '');
@@ -649,6 +653,7 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
                         handlerFile.replace(/\.php$/, '') === r.handlerSymbol ? handlerFile : `${handlerFile}::${r.handlerSymbol}`,
                         ...r.views.map((v) => path.posix.basename(f[v]?.path ?? '')),
                         ...r.tables.map((t) => `table ${code(t)}`),
+                        ...(r.inferredTables ?? []).map((t) => `table ${code(t)} (inferred)`),
                     ];
                     return `- ${code(r.route)} → ${chain.map((c) => (c.startsWith('table') ? c : `${code(c)}`)).join(' → ')}`;
                 }),
@@ -872,7 +877,7 @@ export function renderHtml(m: MapModel, meta: MapMeta): string {
 
 /** The map a previous `code-graph map` wrote, or null when there is none. */
 export function readMap(root: string): { meta: MapMeta; model: MapModel } | null {
-    return readMapAt(path.join(root, MAP_DIR_REL));
+    return readMapAt(graphHome(root).mapDir);
 }
 
 function readMapAt(dir: string): { meta: MapMeta; model: MapModel } | null {
@@ -918,7 +923,11 @@ export interface AreaReport {
  * One area, found by id (`a3`), by exact name, or by a file it contains —
  * exact matches only, so the answer is always about the area that was named.
  */
-export function areaReport(m: MapModel, query: string): AreaReport | { refusal: string; candidates: string[] } {
+export function areaReport(
+    m: MapModel,
+    query: string,
+    pageDir: string = path.posix.join('agents', 'map'),
+): AreaReport | { refusal: string; candidates: string[] } {
     let i = m.areas.findIndex((a) => a.id === query || a.name === query);
     if (i < 0) {
         const f = m.files.findIndex((x) => x.path === query);
@@ -974,6 +983,6 @@ export function areaReport(m: MapModel, query: string): AreaReport | { refusal:
             .sort((x, y) => y[1] - x[1] || x[0] - y[0])
             .slice(0, cap)
             .map(([ai, w]) => ({ area: `${m.areas[ai]?.id ?? ''} ${m.areas[ai]?.name ?? ''}`, links: w })),
-        page: a.files.length >= AREA_PAGE_MIN_FILES ? path.posix.join('agents', 'map', 'areas', `${a.id}.md`) : null,
+        page: a.files.length >= AREA_PAGE_MIN_FILES ? path.posix.join(pageDir, 'areas', `${a.id}.md`) : null,
     };
 }