@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/code_graph/map_model.ts

@@ -36,6 +36,8 @@ export type FileRole =
 
 /** Roles whose files take part in clustering. */
 const CLUSTER_ROLES: ReadonlySet<FileRole> = new Set(['code', 'test', 'entry', 'view']);
+/** Directories of including views at which a view counts as a shared partial. */
+const SHARED_PARTIAL_DIRS = 3;
 
 /** Compact symbol: [name, kind, line]. */
 export type MapSymbol = [string, string, number];
@@ -103,6 +105,8 @@ export interface RequestPath {
     views: number[];
     models: number[];
     tables: string[];
+    /** Tables reached only through a call bound by name alone (a `dynamic` hop with one candidate). */
+    inferredTables: string[];
 }
 
 export interface MapThresholds {
@@ -339,9 +343,29 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
         if ((inFiles[i] as number) > infraInDegree) roles[i] = 'infra';
         else if (roles[i] === 'code' && inFiles[i] === 0 && outFiles[i] === 0) roles[i] = 'isolated';
     }
+    // A partial that views of SHARED_PARTIAL_DIRS directories include is shared
+    // the way a utility is: kept in, it glues every page that shows it into one
+    // area and names that area after itself. Counted by including directory,
+    // not by in-degree, because a project's code dwarfs its views in the p99.
+    const includers = new Map<number, Set<string>>();
+    for (const [s, t] of edges) {
+        if (roles[s] !== 'view' || roles[t] !== 'view') continue;
+        const dirs = includers.get(t) ?? new Set<string>();
+        dirs.add(path.posix.dirname(paths[s] as string));
+        includers.set(t, dirs);
+    }
+    for (const [t, dirs] of includers) if (dirs.size >= SHARED_PARTIAL_DIRS) roles[t] = 'infra';
+    // A routes file links to every handler it routes, so in the clustering it
+    // is the hub of whatever it touches. It sits out the clustering and then
+    // joins the area most of its handlers landed in.
+    const routeFiles = new Set<number>();
+    for (const n of graph.nodes) {
+        const i = n.kind === 'route' ? idx.get(n.source_file) : undefined;
+        if (i !== undefined && CLUSTER_ROLES.has(roles[i] as FileRole)) routeFiles.add(i);
+    }
 
     // 4. Areas: seeded Louvain over the coupled roles.
-    const clusterable = (i: number): boolean => CLUSTER_ROLES.has(roles[i] as FileRole);
+    const clusterable = (i: number): boolean => CLUSTER_ROLES.has(roles[i] as FileRole) && !routeFiles.has(i);
     const undirected = new Map<string, number>();
     for (const [s, t, w] of edges) {
         if (!clusterable(s) || !clusterable(t)) continue;
@@ -415,6 +439,15 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
     drafts.forEach((d, ai) => {
         for (const f of d.files) areaOf[f] = ai;
     });
+    for (const rf of [...routeFiles].sort((a, b) => a - b)) {
+        const pull = new Map<number, number>();
+        for (const [s, t, w] of edges) if (s === rf && (areaOf[t] as number) >= 0) pull.set(areaOf[t] as number, (pull.get(areaOf[t] as number) ?? 0) + w);
+        const best = [...pull.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0])[0]?.[0];
+        const ai = best ?? drafts.push({ files: [], kind: 'small-parts', hub: rf, name: `small parts · ${topDir(paths[rf] as string)}` }) - 1;
+        const d = drafts[ai] as Draft;
+        d.files = [...d.files, rf].sort((a, b) => byPath(paths[a] as string, paths[b] as string));
+        areaOf[rf] = ai;
+    }
 
     // 6. Area metrics, area→area weights, layouts.
     const areaWeights = new Map<string, number>();
@@ -662,6 +695,9 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
  * tables. Read off the overlay's edges only; a route whose handler did not
  * resolve keeps `handler: -1` rather than a guess.
  */
+/** How many calls deep a request path follows the handler: handler → service → repository → model. */
+const REQUEST_HOPS = 3;
+
 function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>): RequestPath[] {
     const nodeById = new Map(graph.nodes.map((n) => [n.id, n] as const));
     const out = new Map<string, CodeGraph['edges']>();
@@ -687,19 +723,37 @@ function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>)
         const views = new Set<number>();
         const models = new Set<number>();
         const tables = new Set<string>();
+        const inferred = new Set<string>();
         if (target) {
-            // The handler's own links only: what this route's code renders and
-            // names. Its file's links would hand every model the controller
-            // imports to every route the controller serves.
-            for (const e of out.get(target) ?? []) {
-                if (!isStatedResolution(e.resolved_via as ResolvedVia)) continue;
-                if (e.relation === 'renders') views.add(fileIdx(e.target));
-                const model = tableOf.has(e.target) ? e.target : e.target.split('::')[0];
-                const modelTables = model ? tableOf.get(model) : undefined;
-                if (modelTables) {
-                    models.add(fileIdx(model as string));
-                    for (const t of modelTables) tables.add(t);
+            // What the handler's own code reaches, up to REQUEST_HOPS calls
+            // deep: a service, its repository, the model. Only functions and
+            // methods are expanded — a class's links would hand every model it
+            // knows to every route it serves. A chain is stated when every hop
+            // is; one hop bound by name alone makes what it reaches inferred.
+            const best = new Map<string, boolean>([[target, true]]);
+            let frontier: Array<[string, boolean]> = [[target, true]];
+            for (let hop = 0; hop < REQUEST_HOPS && frontier.length > 0; hop++) {
+                const next: Array<[string, boolean]> = [];
+                for (const [id, stated] of frontier) {
+                    for (const e of out.get(id) ?? []) {
+                        const sure = isStatedResolution(e.resolved_via as ResolvedVia);
+                        if (!sure && !(e.resolved_via === 'dynamic' && nodeById.has(e.target))) continue;
+                        const chain = stated && sure;
+                        if (e.relation === 'renders' && chain) views.add(fileIdx(e.target));
+                        const model = tableOf.has(e.target) ? e.target : e.target.split('::')[0];
+                        const modelTables = model ? tableOf.get(model) : undefined;
+                        if (modelTables) {
+                            if (chain) models.add(fileIdx(model as string));
+                            for (const t of modelTables) (chain ? tables : inferred).add(t);
+                        }
+                        const kind = nodeById.get(e.target)?.kind;
+                        if (e.relation !== 'calls' || (kind !== 'method' && kind !== 'function')) continue;
+                        if (best.get(e.target) === true || best.get(e.target) === chain) continue;
+                        best.set(e.target, chain);
+                        next.push([e.target, chain]);
+                    }
                 }
+                frontier = next;
             }
         }
         paths.push({
@@ -710,6 +764,7 @@ function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>)
             views: [...views].filter((v) => v >= 0).sort((a, b) => a - b),
             models: [...models].filter((v) => v >= 0).sort((a, b) => a - b),
             tables: [...tables].sort(),
+            inferredTables: [...inferred].filter((t) => !tables.has(t)).sort(),
         });
     }
     return paths.sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : a.file - b.file));

package/src/scripts/code_graph/map_verify.ts

@@ -54,10 +54,49 @@ export interface MapRenderCheck {
         pageErrors: number;
         externalRequests: number;
         horizontalScroll: boolean;
-        views: Array<{ view: string; labels: number; outside: number; overlapping: number }>;
+        views: Array<{ view: string; labels: number; outside: number; overlapping: number; orb?: OrbSpread }>;
+        /** Area-list entries whose name is cut off, or whose colour dot sits on a line of its own. */
+        sidebar: { entries: number; clipped: number; orphanedDot: number };
     }>;
 }
 
+/**
+ * How the area bubbles of one orb view sit: overlapping near-side pairs, and how
+ * far they bunch into one cap — the length of the mean of their unit vectors on
+ * the sphere, 0 for an even spread and 1 for every bubble on one point.
+ */
+export interface OrbSpread {
+    bubbles: number;
+    concentration: number;
+    overlapping: number;
+}
+
+/** Near-side bubbles overlapping by more than a sliver count; far-side ones are seen through the near side. */
+export function orbSpread(nodes: ReadonlyArray<{ x: number; y: number; r: number; near: boolean; u?: number[] }>): OrbSpread {
+    const near = nodes.filter((n) => n.near);
+    let overlapping = 0;
+    for (let i = 0; i < near.length; i++)
+        for (let j = i + 1; j < near.length; j++) {
+            const a = near[i] as (typeof near)[number];
+            const b = near[j] as (typeof near)[number];
+            // The viewer shrinks a crowded bubble down to a dot (ORB_DOT px): two dots touching
+            // hide nothing, so only a pair where both still read as bubbles counts.
+            if (a.r <= ORB_DOT || b.r <= ORB_DOT) continue;
+            if (Math.hypot(a.x - b.x, a.y - b.y) < (a.r + b.r) * ORB_OVERLAP_TOLERANCE) overlapping += 1;
+        }
+    const sum = [0, 0, 0];
+    for (const n of nodes) for (let k = 0; k < 3; k++) sum[k] = (sum[k] as number) + (n.u?.[k] ?? 0);
+    const concentration = nodes.length ? Math.hypot(...(sum as [number, number, number])) / nodes.length : 0;
+    return { bubbles: nodes.length, concentration: Math.round(concentration * 100) / 100, overlapping };
+}
+
+/** The smallest radius the viewer shrinks a crowded orb bubble to (`viewer.js`). */
+const ORB_DOT = 2;
+/** Two bubbles overlap when their centres are closer than this share of their summed radii. */
+const ORB_OVERLAP_TOLERANCE = 0.9;
+/** Above this, the bubbles bunch into one cap. An even spread of 30 sits near 0.1; one hemisphere at 0.5. */
+export const ORB_MAX_CONCENTRATION = 0.35;
+
 interface Box {
     x: number;
     y: number;
@@ -112,14 +151,29 @@ export async function verifyMap(htmlPath: string): Promise<MapRenderCheck> {
             });
             await page.goto(url);
             await page.waitForFunction(() => (window as unknown as { __mapLabelBoxes?: unknown }).__mapLabelBoxes !== undefined);
-            const read = async (view: string): Promise<{ view: string; labels: number; outside: number; overlapping: number }> => {
+            const read = async (view: string): Promise<{ view: string; labels: number; outside: number; overlapping: number; orb?: OrbSpread }> => {
                 const r = (await page.evaluate(() => (window as unknown as { __mapLabelBoxes: { boxes: Box[]; width: number; height: number } }).__mapLabelBoxes)) as {
                     boxes: Box[];
                     width: number;
                     height: number;
                 };
-                return { view, labels: r.boxes.length, ...labelProblems(r.boxes, r.width, r.height) };
+                const bubbles = await page.evaluate(
+                    () => (window as unknown as { __mapOrbNodes?: Array<{ x: number; y: number; r: number; near: boolean; u?: number[] }> }).__mapOrbNodes ?? [],
+                );
+                return { view, labels: r.boxes.length, ...labelProblems(r.boxes, r.width, r.height), ...(bubbles.length ? { orb: orbSpread(bubbles) } : {}) };
             };
+            const sidebar = await page.evaluate(() => {
+                const entries = [...document.querySelectorAll('#panel .plist button')].filter((b) => b.querySelector('.swatch'));
+                let clipped = 0;
+                let orphanedDot = 0;
+                for (const b of entries) {
+                    const name = (b.querySelector('.fname') ?? b) as HTMLElement | null;
+                    const dot = b.querySelector('.swatch') as HTMLElement | null;
+                    if (name && name.scrollWidth > name.clientWidth + 1) clipped += 1;
+                    if (name && dot && dot.getBoundingClientRect().top > name.getBoundingClientRect().bottom) orphanedDot += 1;
+                }
+                return { entries: entries.length, clipped, orphanedDot };
+            });
             const views = [await read('overview')];
             // The orb, as it opens and turned half a revolution: the far side's labels
             // must stay hidden and the near side's must still fit and not overlap.
@@ -139,8 +193,17 @@ export async function verifyMap(htmlPath: string): Promise<MapRenderCheck> {
                 views.push(await read('largest-area'));
             }
             const horizontalScroll = await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth);
-            out.viewports.push({ name: vp.name, pageErrors, externalRequests, horizontalScroll, views });
-            if (pageErrors || externalRequests || horizontalScroll || views.some((v) => v.outside || v.overlapping)) {
+            out.viewports.push({ name: vp.name, pageErrors, externalRequests, horizontalScroll, views, sidebar });
+            const orbBad = (o: OrbSpread | undefined): boolean =>
+                !!o && (o.overlapping > 0 || (o.bubbles >= 6 && o.concentration > ORB_MAX_CONCENTRATION));
+            if (
+                pageErrors ||
+                externalRequests ||
+                horizontalScroll ||
+                sidebar.clipped ||
+                sidebar.orphanedDot ||
+                views.some((v) => v.outside || v.overlapping || orbBad(v.orb))
+            ) {
                 out.verification = 'failed';
             }
             await page.close();

package/src/scripts/code_graph/map_viewer/viewer.css

@@ -209,6 +209,18 @@ aside h3 {
     background: transparent;
     padding: 2px 4px;
 }
+.plist button.aentry {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    column-gap: 6px;
+    align-items: start;
+}
+.aentry .swatch {
+    margin: 4px 0 0;
+}
+.alabel {
+    min-width: 0;
+}
 .plist button:hover {
     background: var(--bg);
 }

package/src/scripts/code_graph/map_viewer/viewer.js

@@ -215,15 +215,18 @@
     }
 
     // The orb: the precomputed 2D layout wrapped onto a sphere with the inverse
-    // Lambert azimuthal equal-area projection, so neighbours stay neighbours and
-    // no region is squeezed — the layout's centre faces the viewer, its rim
-    // wraps to the back. Nothing is simulated; the same layout, turned.
-    function orbPoint(x, y, reach) {
-        var rho = (Math.sqrt(x * x + y * y) / reach) * 1.9;
-        var len = Math.sqrt(x * x + y * y) || 1;
+    // Lambert azimuthal equal-area projection — the layout's centre faces the
+    // viewer, its rim wraps to the back. A node's distance from the centre and
+    // its direction are both replaced by their RANK (`share`, `turn`, 0..1),
+    // order kept, so equal shares of nodes cover equal shares of the sphere.
+    // Raw coordinates put most areas on one cap: a force layout is dense in the
+    // middle and lopsided around it.
+    function orbPoint(share, turn) {
+        var rho = 2 * Math.sqrt(share) * 0.97;
+        var phi = turn * Math.PI * 2;
         var f = Math.sqrt(Math.max(0, 1 - (rho * rho) / 4));
-        var px = (x / len) * rho * f;
-        var py = (y / len) * rho * f;
+        var px = Math.cos(phi) * rho * f;
+        var py = Math.sin(phi) * rho * f;
         var pz = 1 - (rho * rho) / 2;
         var cy = Math.cos(state.rot.yaw);
         var sy = Math.sin(state.rot.yaw);
@@ -269,21 +272,39 @@
         var nodes = currentNodes();
         var pos = Object.create(null);
         if (state.orb) {
-            var reach = 0;
-            nodes.forEach(function (n) { reach = Math.max(reach, Math.sqrt(n.x * n.x + n.y * n.y)); });
-            reach = reach || 1;
+            var byReach = nodes.slice().sort(function (a, b) {
+                return (a.x * a.x + a.y * a.y) - (b.x * b.x + b.y * b.y) || a.idx - b.idx;
+            });
+            var share = Object.create(null);
+            byReach.forEach(function (n, i) { share[n.kind + n.idx] = (i + 0.5) / byReach.length; });
+            var turn = Object.create(null);
+            nodes.slice().sort(function (a, b) { return Math.atan2(a.y, a.x) - Math.atan2(b.y, b.x) || a.idx - b.idx; })
+                .forEach(function (n, i) { turn[n.kind + n.idx] = i / nodes.length; });
             var k = orbRadius();
+            // Bubble sizes are tuned for a 300 px orb; a phone's smaller orb shrinks them with it.
+            var fit = Math.min(1, k / 300);
             var cx = s.w / 2 + state.view.x;
             var cyy = s.h / 2 + state.view.y;
             nodes.forEach(function (n) {
-                var p = orbPoint(n.x, n.y, reach);
+                var p = orbPoint(share[n.kind + n.idx], turn[n.kind + n.idx]);
+                n.u = p;
                 n.sx = cx + p[0] * k;
                 n.sy = cyy + p[1] * k;
                 n.depth = p[2];
                 // Nearer is larger and opaque; the far side recedes.
-                n.r = n.r * (0.6 + 0.4 * (p[2] + 1) / 2);
+                n.r = n.r * fit * (0.6 + 0.4 * (p[2] + 1) / 2);
                 pos[n.kind + n.idx] = n;
             });
+            // No two near-side bubbles may cover each other: each is capped at a
+            // share of the gap to its nearest near-side neighbour.
+            var nearNodes = nodes.filter(function (n) { return n.depth > 0; });
+            if (nearNodes.length <= 400) {
+                nearNodes.forEach(function (n) {
+                    var gap = Infinity;
+                    nearNodes.forEach(function (o) { if (o !== n) gap = Math.min(gap, Math.hypot(o.sx - n.sx, o.sy - n.sy)); });
+                    if (gap < Infinity) n.r = Math.max(2, Math.min(n.r, gap * 0.45));
+                });
+            }
             nodes.sort(function (a, b) { return a.depth - b.depth || a.idx - b.idx; });
             var glow = ctx.createRadialGradient(cx - k * 0.35, cyy - k * 0.35, k * 0.1, cx, cyy, k);
             glow.addColorStop(0, cssVar('--orb-light'));
@@ -398,6 +419,10 @@
         });
 
         drawLabels(state.orb ? nodes.filter(function (n) { return n.depth > 0.15; }) : nodes, s);
+        // For the render check: the bubbles as drawn, with their side of the orb.
+        window.__mapOrbNodes = state.orb
+            ? nodes.map(function (n) { return { x: n.sx, y: n.sy, r: n.r, near: n.depth > 0, u: n.u }; })
+            : [];
     }
 
     // Labels: biggest first, placed only where they fit, flipped near the right
@@ -477,6 +502,7 @@
             r.views.forEach(function (v) { parts.push(base(files[v].path)); });
             r.models.forEach(function (v) { parts.push(base(files[v].path)); });
             r.tables.forEach(function (tb) { parts.push('⊞ ' + tb); });
+            (r.inferredTables || []).forEach(function (tb) { parts.push('⊞ ' + tb + ' ?'); });
             li.appendChild(el('span', { class: 'fdir' }, parts.length ? '→ ' + parts.join(' → ') : '→ ' + t('none')));
             ul.appendChild(li);
         });
@@ -582,9 +608,13 @@
         panel.appendChild(el('h3', null, t('areas') + ' (' + areas.length + ')'));
         var list = el('ul', { class: 'plist' });
         areas.forEach(function (a, i) {
-            var b = el('button', { type: 'button' });
+            var b = el('button', { type: 'button', class: 'aentry', title: a.name + ' · ' + a.files.length });
             b.appendChild(swatch(i));
-            b.appendChild(document.createTextNode(a.name + ' · ' + a.files.length));
+            var label = el('span', { class: 'alabel' });
+            var path = a.kind === 'small-parts' ? null : a.name;
+            label.appendChild(el('span', { class: 'fname' }, (path ? base(path) : a.name) + ' · ' + a.files.length));
+            if (path && dir(path) !== '.') label.appendChild(el('span', { class: 'fdir' }, dir(path)));
+            b.appendChild(label);
             b.addEventListener('click', function () { openArea(i); });
             var li = el('li');
             li.appendChild(b);

package/src/scripts/code_graph/project_ref.ts

@@ -0,0 +1,25 @@
+/**
+ * Turn a `project` argument — a repo id, a registered name or a registered
+ * path — into the root a graph verb runs against (ADR-299, step 5.1). Only a
+ * registered project resolves: an MCP caller cannot point a tool at an
+ * arbitrary directory, only at one the owner already worked in. A name two
+ * registered projects share is refused with both candidates, never guessed.
+ */
+import { findProjects, readRegistry } from '../_lib/project_registry.js';
+
+export type ProjectRef = { root: string } | { error: string; candidates: string[] };
+
+export function resolveProjectRef(ref: string): ProjectRef {
+    const reg = readRegistry();
+    const hits = findProjects(reg, ref);
+    if (hits.length === 1) return { root: (hits[0] as [string, { root: string }])[1].root };
+    if (hits.length > 1) {
+        return { error: `'${ref}' names ${hits.length} registered projects — pass an id`, candidates: hits.map(([id, e]) => `${id} ${e.root}`) };
+    }
+    return {
+        error: `no registered project matches '${ref}' — \`code-graph projects list\` shows them`,
+        candidates: Object.entries(reg.projects)
+            .slice(0, 10)
+            .map(([id, e]) => `${id} ${e.root}`),
+    };
+}

package/src/scripts/code_graph/projects_cli.ts

@@ -0,0 +1,254 @@
+/**
+ * `code-graph projects …` — the registry of projects this machine works in
+ * (ADR-299). A project is added by use (a build or refresh calls
+ * {@link registerUse}) or by hand with `add`; nothing here walks a directory
+ * tree looking for repositories.
+ *
+ *   projects list                       every entry; a root missing for 30 days is flagged
+ *   projects add <path>                 register a project by hand
+ *   projects remove <id|name|path>      drop one entry and its user-global graph homes
+ *   projects prune                      drop the flagged entries
+ *   projects index on|off|status        the estate index switch (council O1, default off)
+ *   projects budget [MB]                show or set the graph-home budget (default 2048)
+ *   projects pin|unpin <id|name|path>   keep a project's graph homes out of eviction
+ *   projects evict                      evict least recently queried homes down to the budget
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { findProjects, mainRoot, type ProjectEntry, readRegistry, recordProject, repoIdOf, updateRegistry } from '../_lib/project_registry.js';
+import { dropProjectRows, indexAfterRefresh, indexPath } from './estate_index.js';
+import { enforceBudget, homeUsage } from './graph_budget.js';
+import { graphHome, graphsRoot } from './graph_home.js';
+import type { CodeGraph } from './types.js';
+
+/** A root missing this long is flagged by `list` and removed by `prune` (6.2). */
+export const STALE_ROOT_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type RootState = 'present' | 'missing' | 'stale';
+
+export function rootState(e: ProjectEntry, now: Date = new Date()): RootState {
+    if (fs.existsSync(e.root)) return 'present';
+    return now.getTime() - Date.parse(e.last_seen) >= STALE_ROOT_DAYS * DAY_MS ? 'stale' : 'missing';
+}
+
+/**
+ * Record that `root`'s graph was just built or refreshed. Best-effort: the
+ * registry is bookkeeping, and a failure to write it never fails a build.
+ *
+ * A linked worktree shares its main checkout's repo id, so it records only its
+ * own home (for eviction and removal) and never the entry's graph home, commit,
+ * languages or estate row — a feature-branch build must not replace what the
+ * main checkout recorded.
+ */
+export function registerUse(root: string, graph: CodeGraph | null, commit: string | null): string | null {
+    try {
+        const home = graphHome(root);
+        const real = fs.realpathSync(root);
+        const worktree = mainRoot(real) !== real;
+        const usedHome = home.kind === 'global' ? { usedHome: home.dir } : {};
+        const id = recordProject(
+            root,
+            worktree
+                ? usedHome
+                : {
+                      graph_home: home.dir,
+                      ...(commit ? { graph_commit: commit } : {}),
+                      ...(graph ? { languages: [...graph.languages], providers: (graph.providers ?? []).map((p) => p.id) } : {}),
+                      ...usedHome,
+                  },
+        );
+        if (!worktree) {
+            // A row the pre-checkout registry wrote under the bare repo id goes once that entry was re-keyed.
+            if (readRegistry().projects[repoIdOf(id)] === undefined) dropProjectRows(repoIdOf(id));
+            indexAfterRefresh(id, real, home.cachePath, graph);
+        }
+        if (home.kind === 'global') enforceBudget(home.dir);
+        return id;
+    } catch {
+        return null;
+    }
+}
+
+/** User-global homes are removable caches; a home under a repository's own `agents/` never is. */
+function removeGlobalHomes(e: ProjectEntry): string[] {
+    const base = graphsRoot();
+    const removed: string[] = [];
+    for (const dir of new Set([...Object.keys(e.homes), ...(e.graph_home ? [e.graph_home] : [])])) {
+        const rel = path.relative(base, dir);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        fs.rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+    }
+    return removed;
+}
+
+function cmdList(): number {
+    const reg = readRegistry();
+    const rows = Object.entries(reg.projects);
+    if (!rows.length) {
+        process.stdout.write('no registered projects — a `code-graph build` or `code-graph projects add <path>` registers one\n');
+        return 0;
+    }
+    for (const [id, e] of rows) {
+        const state = rootState(e);
+        const flag = state === 'stale' ? ` · STALE (missing ${STALE_ROOT_DAYS}+ days — \`projects prune\` removes it)` : state === 'missing' ? ' · missing' : '';
+        process.stdout.write(
+            `${id}  ${e.root}${e.pinned ? ' · pinned' : ''}${flag}\n` +
+                `    last seen ${e.last_seen}${e.graph_commit ? ` · commit ${e.graph_commit.slice(0, 12)}` : ''}` +
+                `${e.languages.length ? ` · ${e.languages.join(', ')}` : ''}${e.providers.length ? ` · providers ${e.providers.join(', ')}` : ''}\n`,
+        );
+    }
+    process.stdout.write(`estate index: ${reg.index ? 'on' : 'off'} · budget ${reg.budget_mb} MB\n`);
+    return 0;
+}
+
+function cmdAdd(target: string | undefined): number {
+    if (!target) {
+        process.stderr.write('usage: code-graph projects add <path>\n');
+        return 2;
+    }
+    const abs = path.resolve(target);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+        process.stderr.write(`code-graph: not a directory: ${abs}\n`);
+        return 1;
+    }
+    const id = recordProject(abs);
+    process.stdout.write(`registered ${id}  ${fs.realpathSync(abs)}\n`);
+    return 0;
+}
+
+function cmdRemove(ref: string | undefined): number {
+    if (!ref) {
+        process.stderr.write('usage: code-graph projects remove <id|name|path>\n');
+        return 2;
+    }
+    const hits = findProjects(readRegistry(), ref);
+    if (hits.length === 0) {
+        process.stderr.write(`code-graph: no registered project matches '${ref}'\n`);
+        return 1;
+    }
+    if (hits.length > 1) {
+        process.stderr.write(`code-graph: '${ref}' names ${hits.length} projects — use an id:\n`);
+        for (const [id, e] of hits) process.stderr.write(`  ${id}  ${e.root}\n`);
+        return 1;
+    }
+    const [id, entry] = hits[0] as [string, ProjectEntry];
+    updateRegistry((reg) => {
+        delete reg.projects[id];
+    });
+    const removed = removeGlobalHomes(entry);
+    dropProjectRows(id);
+    process.stdout.write(`removed ${id}  ${entry.root}${removed.length ? ` · ${removed.length} graph home(s) deleted` : ''}\n`);
+    return 0;
+}
+
+function cmdPrune(): number {
+    const now = new Date();
+    const dropped = updateRegistry((reg) => {
+        const out: Array<[string, ProjectEntry]> = [];
+        for (const [id, e] of Object.entries(reg.projects)) {
+            if (rootState(e, now) !== 'stale') continue;
+            out.push([id, e]);
+            delete reg.projects[id];
+        }
+        return out;
+    });
+    for (const [id, e] of dropped) {
+        removeGlobalHomes(e);
+        dropProjectRows(id);
+        process.stdout.write(`pruned ${id}  ${e.root}\n`);
+    }
+    process.stdout.write(`${dropped.length} pruned\n`);
+    return 0;
+}
+
+function cmdIndex(action: string | undefined): number {
+    if (action === 'on' || action === 'off') {
+        updateRegistry((reg) => {
+            reg.index = action === 'on';
+        });
+        if (action === 'off') fs.rmSync(indexPath(), { force: true });
+        process.stdout.write(
+            action === 'on'
+                ? 'estate index on — each registered project is indexed on its next build or refresh. It names client projects by path and never leaves this machine.\n'
+                : 'estate index off — the index file is deleted and nothing is indexed.\n',
+        );
+        return 0;
+    }
+    if (action !== undefined && action !== 'status') {
+        process.stderr.write('usage: code-graph projects index on|off|status\n');
+        return 2;
+    }
+    const reg = readRegistry();
+    process.stdout.write(`estate index: ${reg.index ? 'on' : 'off'} · ${fs.existsSync(indexPath()) ? indexPath() : 'no index file'}\n`);
+    return 0;
+}
+
+function one(ref: string | undefined, verb: string): [string, ProjectEntry] | null {
+    if (!ref) {
+        process.stderr.write(`usage: code-graph projects ${verb} <id|name|path>\n`);
+        return null;
+    }
+    const hits = findProjects(readRegistry(), ref);
+    if (hits.length !== 1) {
+        process.stderr.write(`code-graph: '${ref}' matches ${hits.length} registered projects — use an id from \`projects list\`\n`);
+        return null;
+    }
+    return hits[0] as [string, ProjectEntry];
+}
+
+function cmdPin(ref: string | undefined, pinned: boolean): number {
+    const hit = one(ref, pinned ? 'pin' : 'unpin');
+    if (!hit) return 1;
+    updateRegistry((reg) => {
+        const e = reg.projects[hit[0]];
+        if (e) e.pinned = pinned;
+    });
+    process.stdout.write(`${pinned ? 'pinned' : 'unpinned'} ${hit[0]}  ${hit[1].root}\n`);
+    return 0;
+}
+
+function cmdBudget(value: string | undefined): number {
+    if (value !== undefined) {
+        const mb = Number(value);
+        if (!Number.isFinite(mb) || mb <= 0) {
+            process.stderr.write('usage: code-graph projects budget [MB] — a positive number\n');
+            return 2;
+        }
+        updateRegistry((reg) => {
+            reg.budget_mb = mb;
+        });
+    }
+    const used = homeUsage().reduce((n, h) => n + h.bytes, 0);
+    process.stdout.write(`graph-home budget: ${readRegistry().budget_mb} MB · in use ${(used / (1024 * 1024)).toFixed(1)} MB under ${graphsRoot()}\n`);
+    return 0;
+}
+
+function cmdEvict(): number {
+    const r = enforceBudget();
+    for (const h of r.evicted) process.stdout.write(`evicted ${h.dir} (${(h.bytes / (1024 * 1024)).toFixed(1)} MB)\n`);
+    const over = r.total > r.budget;
+    process.stdout.write(
+        `${r.evicted.length} evicted · ${(r.total / (1024 * 1024)).toFixed(1)} of ${(r.budget / (1024 * 1024)).toFixed(1)} MB` +
+            (over ? ' — still over: the rest is pinned, lock-held or being written' : '') +
+            '\n',
+    );
+    return 0;
+}
+
+export function projectsMain(argv: string[]): number {
+    const [verb, ...rest] = argv;
+    const positional = rest.filter((a) => !a.startsWith('--'));
+    if (verb === undefined || verb === 'list') return cmdList();
+    if (verb === 'add') return cmdAdd(positional[0]);
+    if (verb === 'remove') return cmdRemove(positional[0]);
+    if (verb === 'prune') return cmdPrune();
+    if (verb === 'index') return cmdIndex(positional[0]);
+    if (verb === 'budget') return cmdBudget(positional[0]);
+    if (verb === 'pin' || verb === 'unpin') return cmdPin(positional[0], verb === 'pin');
+    if (verb === 'evict') return cmdEvict();
+    process.stderr.write('usage: code-graph projects list|add|remove|prune|index|budget|pin|unpin|evict\n');
+    return 2;
+}