@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/_lib/lineage_seed.ts

@@ -0,0 +1,116 @@
+/**
+ * Seed the two lineage ledgers from the provenance stores that already exist.
+ *
+ * Tracked side: one `mechanisms.jsonl` row per `harvests.jsonl` row — id, verdict, the
+ * asserting artefact and the date carried over, nothing else. `harvests.jsonl` stays, so
+ * every citation keeps resolving.
+ *
+ * Local side: every harvest `source_ref` and every `skills-provenance.yml` entry becomes a
+ * sealed source plus an edge to its mechanism. Nothing is invented on the way: an opaque
+ * harvest ref has no revision, so its edge records `pin: unknown`; a skills entry keeps the
+ * sealed pin it already carries. The tracked yml is read, never written.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { canonicalize } from '../harvest_reference_tokens.js';
+import type { HarvestRecord, MechanismRecord } from '../lint_harvest_provenance.js';
+import { PIN_UNKNOWN, type EdgeRow, type Ledger, type SourceKind, type SourceRow } from './lineage_ledger.js';
+import { decrypt, encrypt, is_token } from './link_crypto.js';
+import { sourceId } from './source_id.js';
+
+export const HARVESTS_REL = 'provenance/harvests.jsonl';
+export const SKILLS_PROVENANCE_REL = 'agents/settings/contexts/skills-provenance.yml';
+
+export function seedMechanismsFromHarvests(harvests: readonly HarvestRecord[]): MechanismRecord[] {
+    return harvests.map((h) => ({
+        mechanism_id: h.harvest_id,
+        verdict: h.verdict,
+        realised_in: [h.stated_in],
+        decided_at: h.harvested_at,
+    }));
+}
+
+const PINNED_REF_RE = /^(.+)@([0-9a-fA-F]{7,64})$/;
+
+function kindOf(identity: string): SourceKind {
+    if (identity.startsWith('opaque:')) return 'unknown';
+    return canonicalize(identity) === null ? 'url' : 'repo';
+}
+
+export interface ImportResult {
+    readonly ledger: Ledger;
+    /** One line per entry that could not be imported, naming why. Never a guess in its place. */
+    readonly refused: string[];
+}
+
+function readHarvests(root: string): HarvestRecord[] {
+    const file = path.join(root, HARVESTS_REL);
+    if (!fs.existsSync(file)) return [];
+    return fs
+        .readFileSync(file, 'utf-8')
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l) as HarvestRecord);
+}
+
+/** Build the local rows for `root` without writing anything. `keys[0]` seals; all keys decrypt. */
+export function buildLocalImport(root: string, keys: readonly string[]): ImportResult {
+    const key = keys[0] as string;
+    const sources = new Map<string, SourceRow>();
+    const edges: EdgeRow[] = [];
+    const refused: string[] = [];
+    const addSource = (identity: string, sealed: string, license: string): string => {
+        const id = sourceId(identity, key);
+        if (!sources.has(id)) sources.set(id, { source_id: id, kind: kindOf(identity), identity: sealed, license, watch: false });
+        return id;
+    };
+
+    for (const h of readHarvests(root)) {
+        let identity = h.source_ref;
+        let pin: string = PIN_UNKNOWN;
+        if (is_token(h.source_ref)) {
+            try {
+                identity = decrypt(h.source_ref, [...keys]);
+            } catch (e) {
+                refused.push(`${h.harvest_id}: source_ref does not decrypt with the configured key (${(e as Error).message})`);
+                continue;
+            }
+        } else if (!identity.startsWith('opaque:')) {
+            const m = PINNED_REF_RE.exec(identity);
+            if (m) {
+                identity = m[1] as string;
+                pin = encrypt(m[2] as string, key);
+            }
+        }
+        const id = addSource(identity, encrypt(identity, key), 'unknown');
+        edges.push({ source_id: id, mechanism_id: h.harvest_id, pin, locator: encrypt(h.evidence_locator, key) });
+    }
+
+    const ymlFile = path.join(root, SKILLS_PROVENANCE_REL);
+    if (fs.existsSync(ymlFile)) {
+        const doc = (parseYaml(fs.readFileSync(ymlFile, 'utf-8')) ?? {}) as Record<string, Record<string, unknown> | null>;
+        for (const [skill, entry] of Object.entries(doc)) {
+            const sealedSource = entry?.source_enc;
+            if (typeof sealedSource !== 'string' || !is_token(sealedSource)) {
+                refused.push(`${skill}: no sealed source_enc`);
+                continue;
+            }
+            let identity: string;
+            try {
+                identity = decrypt(sealedSource, [...keys]);
+            } catch (e) {
+                refused.push(`${skill}: source_enc does not decrypt with the configured key (${(e as Error).message})`);
+                continue;
+            }
+            const pinned = entry?.pinned_to_enc;
+            const license = typeof entry?.license === 'string' && entry.license !== '' ? entry.license : 'unknown';
+            const id = addSource(identity, sealedSource, license);
+            edges.push({ source_id: id, mechanism_id: skill, pin: typeof pinned === 'string' && is_token(pinned) ? pinned : PIN_UNKNOWN, locator: null });
+        }
+    }
+    return { ledger: { sources: [...sources.values()], edges }, refused };
+}

package/src/scripts/_lib/lineage_watch.ts

@@ -0,0 +1,249 @@
+/**
+ * The upstream delta watch — one local run that turns an upstream move into findings.
+ *
+ * Per source the owner switched on (`watch: true`, off by default — council O7): one
+ * `git ls-remote`; if HEAD is the newest recorded pin (a full or short SHA, or a tag
+ * resolved through `ls-remote`), stop there. Otherwise a depth-1
+ * fetch of both commits into a private cache under the user-global home, then two diffs —
+ * the files under the edges' locators, and the top-level listing — classified as:
+ *
+ *   reverify       a locator's file changed under an adopted or adapted mechanism
+ *   reopen         a locator's file changed under a rejected or deferred mechanism
+ *   drift          a locator's file was deleted or renamed away
+ *   candidate      a new top-level entry, which no mechanism has looked at yet
+ *   license-alert  a top-level license file changed
+ *
+ * It never runs under CI (the key and the identities are local, CI logs are not), never
+ * fetches without consent, and never writes code: the output is a report and a stub.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { MechanismRecord } from '../lint_harvest_provenance.js';
+import { gitEnv } from './git_env.js';
+import { assertOutsideWorkTree, LineageError, PIN_UNKNOWN, readLedger, type SourceRow } from './lineage_ledger.js';
+import { latestDecisions } from './lineage_query.js';
+import { decrypt, encrypt } from './link_crypto.js';
+import type { EnvMap } from './user_global_paths.js';
+
+export type GitRunner = (args: string[], cwd?: string) => string;
+
+const GIT_TIMEOUT_MS = 120_000;
+
+export const systemGit: GitRunner = (args, cwd) =>
+    execFileSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'protocol.ext.allow=never', '-c', 'http.followRedirects=false', ...args], {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: GIT_TIMEOUT_MS,
+        env: { ...gitEnv(), GIT_TERMINAL_PROMPT: '0' },
+    });
+
+export type FindingClass = 'reverify' | 'reopen' | 'drift' | 'candidate' | 'license-alert';
+
+export interface WatchFinding {
+    readonly class: FindingClass;
+    /** null for a candidate or a license alert — no mechanism has looked at it. */
+    readonly mechanism_id: string | null;
+    /** Plaintext, local only: the locator or top-level entry. */
+    readonly locator: string;
+}
+
+export interface SourceReport {
+    readonly source_id: string;
+    readonly identity: string;
+    readonly status: 'unchanged' | 'changed' | 'unpinned' | 'not-watchable' | 'error';
+    readonly pin: string | null;
+    readonly head: string | null;
+    readonly findings: WatchFinding[];
+    /** Mechanisms the source fed, for a license alert that concerns all of them. */
+    readonly mechanisms: string[];
+    readonly note?: string;
+}
+
+export interface WatchOptions {
+    readonly dir: string;
+    readonly keys: readonly string[];
+    readonly rows: readonly MechanismRecord[];
+    readonly git: GitRunner;
+    readonly env: EnvMap;
+}
+
+export function refuseUnderCi(env: EnvMap): void {
+    if (env.CI !== undefined && env.CI !== '' && env.CI !== 'false' && env.CI !== '0') {
+        throw new LineageError('the lineage watch never runs under CI — the key and the source identities are local, CI logs are not');
+    }
+}
+
+const LICENSE_RE = /^(licen[cs]e|copying)(\.[a-z0-9]+)?$/i;
+
+/** A locator names a path, optionally suffixed `:<line>` or `#<anchor>`. */
+function locatorPath(locator: string): string {
+    return locator.replace(/#.*$/, '').replace(/:\d+(-\d+)?$/, '').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+const under = (file: string, loc: string): boolean => file === loc || file.startsWith(`${loc}/`);
+
+/** The commit a tag names on the remote, peeled through an annotated tag; null when absent. */
+function tagCommit(git: GitRunner, identity: string, tag: string): string | null {
+    if (tag.startsWith('-')) return null;
+    const refs = new Map<string, string>();
+    // The trailing glob is what makes ls-remote print the peeled `^{}` line; the exact match is below.
+    for (const line of git(['ls-remote', '--tags', identity, `refs/tags/${tag}*`]).split('\n')) {
+        const [sha, ref] = line.trim().split(/\s+/);
+        if (sha && ref) refs.set(ref, sha);
+    }
+    const sha = refs.get(`refs/tags/${tag}^{}`) ?? refs.get(`refs/tags/${tag}`) ?? null;
+    return sha !== null && /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+}
+
+function watchOne(source: SourceRow, opts: WatchOptions): SourceReport {
+    const { keys, git } = opts;
+    const ledger = readLedger(opts.dir);
+    // The ledger is append-only, so only a mechanism's newest edge speaks for it.
+    const edges = [...new Map(ledger.edges.filter((e) => e.source_id === source.source_id).map((e) => [e.mechanism_id, e])).values()];
+    const mechanisms = [...new Set(edges.map((e) => e.mechanism_id))];
+    const identity = decrypt(source.identity, [...keys]);
+    const base = { source_id: source.source_id, identity, mechanisms };
+    if (source.kind !== 'repo') {
+        return { ...base, status: 'not-watchable', pin: null, head: null, findings: [], note: `kind ${source.kind} has no revision to compare` };
+    }
+    const pinned = edges.filter((e) => e.pin !== PIN_UNKNOWN);
+    if (pinned.length === 0) {
+        return { ...base, status: 'unpinned', pin: null, head: null, findings: [], note: 'no edge records a pin, so there is nothing to compare against' };
+    }
+    const pin = decrypt((pinned[pinned.length - 1] as { pin: string }).pin, [...keys]);
+
+    if (identity.startsWith('-')) return { ...base, status: 'error', pin, head: null, findings: [], note: 'identity is not a repository location' };
+    const head = (git(['ls-remote', identity, 'HEAD']).split(/\s+/)[0] ?? '').trim();
+    if (!/^[0-9a-f]{7,64}$/.test(head)) return { ...base, status: 'error', pin, head: null, findings: [], note: 'ls-remote returned no HEAD' };
+    const hexPin = /^[0-9a-f]{7,64}$/i.test(pin);
+    let pinRev = pin.toLowerCase();
+    if (!hexPin) {
+        const peeled = tagCommit(git, identity, pin);
+        if (peeled === null) return { ...base, status: 'error', pin, head, findings: [], note: `pin ${pin} is neither a commit nor a tag the remote has` };
+        pinRev = peeled;
+    }
+    if (head.startsWith(pinRev)) return { ...base, status: 'unchanged', pin, head, findings: [] };
+
+    const cache = path.join(opts.dir, 'cache', source.source_id);
+    // The cache is a repository of its own; what must sit outside every work tree is its container.
+    assertOutsideWorkTree(path.dirname(cache));
+    if (!fs.existsSync(path.join(cache, '.git'))) {
+        fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
+        git(['init', '-q'], cache);
+    }
+    git(['fetch', '-q', '--depth', '1', '--no-tags', identity, head], cache);
+    if (pinRev.length >= 40) git(['fetch', '-q', '--depth', '1', '--no-tags', identity, pinRev], cache);
+    else {
+        // A remote serves no object by an abbreviated name, so a short pin is found in HEAD's history.
+        const shallow = git(['rev-parse', '--is-shallow-repository'], cache).trim() === 'true';
+        git(['fetch', '-q', '--no-tags', ...(shallow ? ['--unshallow'] : []), identity, head], cache);
+        pinRev = git(['rev-parse', '--verify', '-q', `${pinRev}^{commit}`], cache).trim();
+    }
+
+    const changed = new Map<string, string>();
+    for (const line of git(['diff', '--name-status', '-M', pinRev, head], cache).split('\n')) {
+        const [status, from] = line.split('\t');
+        if (status && from) changed.set(from, status.charAt(0));
+    }
+    const listing = (rev: string): Set<string> => new Set(git(['ls-tree', '--name-only', rev], cache).split('\n').filter((x) => x !== ''));
+    const before = listing(pinRev);
+    const after = listing(head);
+
+    const latest = latestDecisions(opts.rows);
+    const findings: WatchFinding[] = [];
+    for (const e of edges) {
+        if (e.locator === null) continue;
+        const locator = decrypt(e.locator, [...keys]);
+        const loc = locatorPath(locator);
+        const hits = [...changed.entries()].filter(([f]) => under(f, loc));
+        if (hits.length === 0) continue;
+        const gone = hits.every(([, s]) => s === 'D' || s === 'R');
+        const verdict = latest.get(e.mechanism_id)?.verdict;
+        const cls: FindingClass = gone ? 'drift' : verdict === 'reject' || verdict === 'deferred' ? 'reopen' : 'reverify';
+        findings.push({ class: cls, mechanism_id: e.mechanism_id, locator });
+    }
+    for (const entry of [...after].sort()) if (!before.has(entry)) findings.push({ class: 'candidate', mechanism_id: null, locator: entry });
+    for (const [f] of changed) if (!f.includes('/') && LICENSE_RE.test(f)) findings.push({ class: 'license-alert', mechanism_id: null, locator: f });
+    return { ...base, status: 'changed', pin, head, findings };
+}
+
+/** One run over every watched source. Throws under CI before any git call. */
+export function runWatch(opts: WatchOptions): SourceReport[] {
+    refuseUnderCi(opts.env);
+    return readLedger(opts.dir)
+        .sources.filter((s) => s.watch === true)
+        .map((s) => {
+            try {
+                return watchOne(s, opts);
+            } catch (e) {
+                if (e instanceof LineageError) throw e;
+                return { source_id: s.source_id, identity: '', status: 'error' as const, pin: null, head: null, findings: [], mechanisms: [], note: (e as Error).message.split('\n')[0] ?? 'watch failed' };
+            }
+        });
+}
+
+const CLASS_ORDER: readonly FindingClass[] = ['reopen', 'drift', 'reverify', 'license-alert', 'candidate'];
+
+/** The local report: identities in plaintext, so it is written only under the user-global home. */
+export function renderWatchReport(reports: readonly SourceReport[], date: string): string {
+    const out = [`# Lineage watch — ${date} (local, never shared)`, ''];
+    for (const r of reports) {
+        out.push(`## ${r.source_id} — ${r.identity}`, '', `status ${r.status}${r.pin ? ` · pin ${r.pin}` : ''}${r.head ? ` · head ${r.head}` : ''}${r.note ? ` · ${r.note}` : ''}`, '');
+        for (const f of [...r.findings].sort((a, b) => CLASS_ORDER.indexOf(a.class) - CLASS_ORDER.indexOf(b.class))) {
+            out.push(`- ${f.class} ${f.mechanism_id ?? '(no mechanism)'} — ${f.locator}`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}
+
+/**
+ * The tracked stub: mechanism ids and freshly sealed locators, nothing else — no source id,
+ * no identity, no pin. One per run, grouped by mechanism rather than by commit, so a busy
+ * upstream produces one decision to make per mechanism. Null when there is nothing to plan.
+ */
+export function renderWatchStub(reports: readonly SourceReport[], date: string, key: string): string | null {
+    const byMechanism = new Map<string, WatchFinding[]>();
+    const unowned: WatchFinding[] = [];
+    for (const r of reports) {
+        for (const f of r.findings) {
+            if (f.class === 'license-alert') {
+                for (const m of r.mechanisms) byMechanism.set(m, [...(byMechanism.get(m) ?? []), f]);
+            } else if (f.mechanism_id === null) unowned.push(f);
+            else byMechanism.set(f.mechanism_id, [...(byMechanism.get(f.mechanism_id) ?? []), f]);
+        }
+    }
+    if (byMechanism.size === 0 && unowned.length === 0) return null;
+    const review = new Date(`${date}T00:00:00Z`);
+    review.setUTCDate(review.getUTCDate() + 90);
+    const line = (f: WatchFinding): string => `- ${f.class} — \`${encrypt(f.locator, key)}\``;
+    const out = [
+        '---',
+        'complexity: lightweight',
+        `review_by: ${review.toISOString().slice(0, 10)}`,
+        '---',
+        '',
+        `# Stub: lineage delta of ${date}`,
+        '',
+        '> **Stub — not active work.** Written by `code-graph lineage watch`. An upstream that a',
+        '> recorded mechanism was read from has moved. Nothing was implemented or merged: each',
+        '> entry below is a decision for the owner. Locators are sealed (`link_crypto decrypt`);',
+        '> the local report under the user-global `runtime/lineage/watch/` has the rest.',
+        '',
+    ];
+    for (const m of [...byMechanism.keys()].sort()) {
+        out.push(`## Mechanism \`${m}\``, '', ...(byMechanism.get(m) as WatchFinding[]).map(line), '');
+    }
+    if (unowned.length > 0) out.push('## New upstream entries no mechanism covers', '', ...unowned.map(line), '');
+    out.push(
+        '## Kill criteria',
+        '',
+        '- Every entry above is re-verified, reopened or dismissed in `provenance/mechanisms.jsonl` — then delete this stub.',
+        '',
+    );
+    return out.join('\n');
+}

package/src/scripts/_lib/link_crypto.ts

@@ -58,6 +58,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { sourceId } from './source_id.js';
+
 export const MAGIC = 'ENC1';
 const _SALT_LEN = 16;
 const _NONCE_LEN = 16;
@@ -232,19 +234,19 @@ export class ValueError extends Error {}
 export function _cli(argv: readonly string[]): number {
     const prog = 'link_crypto';
     const cmd = argv[0];
-    const validCmds = new Set(['encrypt', 'decrypt', 'keygen', 'keystatus']);
+    const validCmds = new Set(['encrypt', 'decrypt', 'keygen', 'keystatus', 'source-id']);
 
     // argparse: subparser required → error when missing/invalid (exit 2).
     if (cmd === undefined || !validCmds.has(cmd)) {
-        const choices = "'encrypt', 'decrypt', 'keygen', 'keystatus'";
+        const choices = "'encrypt', 'decrypt', 'keygen', 'keystatus', 'source-id'";
         if (cmd === undefined) {
             process.stderr.write(
-                `usage: ${prog} [-h] {encrypt,decrypt,keygen,keystatus} ...\n` +
+                `usage: ${prog} [-h] {encrypt,decrypt,keygen,keystatus,source-id} ...\n` +
                     `${prog}: error: the following arguments are required: cmd\n`,
             );
         } else {
             process.stderr.write(
-                `usage: ${prog} [-h] {encrypt,decrypt,keygen,keystatus} ...\n` +
+                `usage: ${prog} [-h] {encrypt,decrypt,keygen,keystatus,source-id} ...\n` +
                     `${prog}: error: argument cmd: invalid choice: '${cmd}' (choose from ${choices})\n`,
             );
         }
@@ -292,6 +294,8 @@ export function _cli(argv: readonly string[]): number {
     }
     if (cmd === 'encrypt') {
         process.stdout.write(encrypt(v, keys[0] as string) + '\n');
+    } else if (cmd === 'source-id') {
+        process.stdout.write(sourceId(v, keys[0] as string) + '\n');
     } else {
         process.stdout.write(decrypt(v, keys) + '\n');
     }

package/src/scripts/_lib/production_reach.ts

@@ -5,9 +5,9 @@
  * dynamic `import()` not followed. A symbol counts as reached when some module
  * in the closure imports it BY NAME from its defining module (or imports that
  * module whole), or when the defining module is itself an entry. Reaching the
- * module is not enough — `egress_normalize.ts` is in the closure for one regex
- * while `detectNormalized` has no production importer, and that is the case
- * this exists to see.
+ * module is not enough — `egress_normalize.ts` was in the closure for one regex
+ * while `detectNormalized` had no production importer (until one-detector 2.5
+ * wired it), and that is the case this exists to see.
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';

package/src/scripts/_lib/project_registry.ts

@@ -0,0 +1,227 @@
+/**
+ * The one user-global list of projects this machine has worked in (ADR-299).
+ *
+ * `runtime/projects/registry.json`, keyed by `<repo id>-<checkout>`
+ * (`code_graph/repo_identity`): two clones of one origin are one logical
+ * project but keep their own root, graph home and commit, so neither build
+ * overwrites the other's. A registry written before that, keyed by the bare
+ * repo id, still loads; the entry is re-keyed when its checkout next records.
+ * A project enters by use — a graph build or refresh, an advisories refresh, or
+ * an explicit `code-graph projects add` — never by a crawl. The file names
+ * client projects by absolute path, so nothing that leaves the machine may read
+ * it (step 6.3 enforces that).
+ *
+ * Writes are atomic (`write_atomic`), and read-modify-write goes through a
+ * short mkdir lock so two processes recording at once do not drop an entry.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { canonicalOrigin, projectsDir, remoteUrl, repoIdentity } from '../code_graph/repo_identity.js';
+import { git_common_dir } from './git_common_dir.js';
+import { write_atomic } from './fs_atomic.js';
+import type { EnvMap } from './user_global_paths.js';
+
+export const DEFAULT_BUDGET_MB = 2048;
+
+export interface ProjectEntry {
+    root: string;
+    /** The credential-free canonical origin, or null without a remote. */
+    remote: string | null;
+    fingerprint: string | null;
+    last_seen: string;
+    /** The graph home directory last used for this project. */
+    graph_home: string | null;
+    graph_commit: string | null;
+    languages: string[];
+    providers: string[];
+    pinned: boolean;
+    /** User-global graph homes of this project (main checkout and worktrees) → last query. */
+    homes: Record<string, string>;
+}
+
+export interface Registry {
+    schema: 1;
+    /** The estate index switch (council O1): off unless the owner turns it on. */
+    index: boolean;
+    budget_mb: number;
+    projects: Record<string, ProjectEntry>;
+}
+
+export interface RegistryOptions {
+    env?: EnvMap | null;
+    /** Overrides the projects directory (tests, advisories' injected machine dir). */
+    dir?: string;
+    now?: Date;
+}
+
+export function emptyRegistry(): Registry {
+    return { schema: 1, index: false, budget_mb: DEFAULT_BUDGET_MB, projects: {} };
+}
+
+export function registryDir(opts: RegistryOptions = {}): string {
+    return opts.dir ?? projectsDir(opts.env);
+}
+
+export function registryPath(env?: EnvMap | null, dir?: string): string {
+    return path.join(dir ?? projectsDir(env), 'registry.json');
+}
+
+function isEntry(v: unknown): v is ProjectEntry {
+    const e = v as Partial<ProjectEntry> | null;
+    return !!e && typeof e.root === 'string' && typeof e.last_seen === 'string';
+}
+
+/** A missing, corrupt or foreign file reads as empty, never as an error. */
+export function readRegistry(opts: RegistryOptions = {}): Registry {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(registryPath(opts.env, opts.dir), 'utf-8'));
+    } catch {
+        return emptyRegistry();
+    }
+    const r = raw as Partial<Registry> | null;
+    if (!r || typeof r !== 'object' || Array.isArray(r) || r.schema !== 1 || typeof r.projects !== 'object' || r.projects === null) {
+        return emptyRegistry();
+    }
+    const projects: Record<string, ProjectEntry> = {};
+    for (const [id, e] of Object.entries(r.projects)) {
+        if (!isEntry(e)) continue;
+        projects[id] = {
+            root: e.root,
+            remote: e.remote ?? null,
+            fingerprint: e.fingerprint ?? null,
+            last_seen: e.last_seen,
+            graph_home: e.graph_home ?? null,
+            graph_commit: e.graph_commit ?? null,
+            languages: Array.isArray(e.languages) ? e.languages : [],
+            providers: Array.isArray(e.providers) ? e.providers : [],
+            pinned: e.pinned === true,
+            homes: e.homes && typeof e.homes === 'object' ? e.homes : {},
+        };
+    }
+    return {
+        schema: 1,
+        index: r.index === true,
+        budget_mb: typeof r.budget_mb === 'number' && r.budget_mb > 0 ? r.budget_mb : DEFAULT_BUDGET_MB,
+        projects,
+    };
+}
+
+export function writeRegistry(reg: Registry, opts: RegistryOptions = {}): void {
+    write_atomic(registryPath(opts.env, opts.dir), `${JSON.stringify(reg, null, 2)}\n`);
+}
+
+const LOCK_WAIT_MS = 2_000;
+const LOCK_STALE_MS = 30_000;
+
+function sleep(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Read, change and write under the registry lock; the change sees the latest file. */
+export function updateRegistry<T>(fn: (reg: Registry) => T, opts: RegistryOptions = {}): T {
+    const lock = path.join(registryDir(opts), 'registry.lock');
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        } catch (e) {
+            if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) fs.rmSync(lock, { recursive: true, force: true });
+            } catch {
+                /* released meanwhile */
+            }
+            if (Date.now() > deadline) throw new Error(`project registry is locked: ${lock}`);
+            sleep(25);
+        }
+    }
+    try {
+        const reg = readRegistry(opts);
+        const out = fn(reg);
+        writeRegistry(reg, opts);
+        return out;
+    } finally {
+        fs.rmSync(lock, { recursive: true, force: true });
+    }
+}
+
+/** The main checkout of a worktree, else the root itself. */
+export function mainRoot(root: string): string {
+    let real: string;
+    try {
+        real = fs.realpathSync(root);
+    } catch {
+        real = path.resolve(root);
+    }
+    const common = git_common_dir(real);
+    return common !== null && path.basename(common) === '.git' ? path.dirname(common) : real;
+}
+
+export type ProjectFields = Partial<Pick<ProjectEntry, 'fingerprint' | 'graph_home' | 'graph_commit' | 'languages' | 'providers' | 'pinned'>> & {
+    /** A user-global graph home that just served or rebuilt this project. */
+    usedHome?: string;
+};
+
+/** The logical project an entry key belongs to: the repo id, for a new or a bare legacy key. */
+export function repoIdOf(key: string): string {
+    return key.split('-')[0] as string;
+}
+
+/** Record `root` (by use, never by a crawl) and return its entry key, `<repo id>-<checkout>`. */
+export function recordProject(root: string, fields: ProjectFields = {}, opts: RegistryOptions = {}): string {
+    const dir = registryDir(opts);
+    const ident = repoIdentity(root, opts.env, dir);
+    const id = `${ident.repoId}-${ident.checkout}`;
+    const main = mainRoot(root);
+    const origin = remoteUrl(main);
+    const now = (opts.now ?? new Date()).toISOString();
+    updateRegistry((reg) => {
+        const legacy = reg.projects[ident.repoId];
+        const adopt = reg.projects[id] === undefined && legacy !== undefined && legacy.root === main;
+        const prev = reg.projects[id] ?? (adopt ? legacy : undefined);
+        if (adopt) delete reg.projects[ident.repoId];
+        const { usedHome, ...rest } = fields;
+        const next: ProjectEntry = {
+            root: main,
+            remote: origin === null ? null : canonicalOrigin(origin, main),
+            fingerprint: prev?.fingerprint ?? null,
+            graph_home: prev?.graph_home ?? null,
+            graph_commit: prev?.graph_commit ?? null,
+            languages: prev?.languages ?? [],
+            providers: prev?.providers ?? [],
+            pinned: prev?.pinned ?? false,
+            homes: { ...(prev?.homes ?? {}) },
+            ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),
+            last_seen: now,
+        };
+        if (usedHome !== undefined) next.homes[usedHome] = now;
+        reg.projects[id] = next;
+    }, { ...opts, dir });
+    return id;
+}
+
+/**
+ * The entries a reference names: an entry key, a repo id (every checkout of
+ * it), a registered name (the root's basename) or a path. A name two projects
+ * share returns both, so the caller can refuse to guess.
+ */
+export function findProjects(reg: Registry, ref: string): Array<[string, ProjectEntry]> {
+    const all = Object.entries(reg.projects);
+    const byKey = all.filter(([id]) => id === ref);
+    if (byKey.length) return byKey;
+    const byId = all.filter(([id]) => repoIdOf(id) === ref);
+    if (byId.length) return byId;
+    let real: string | null = null;
+    try {
+        real = fs.realpathSync(path.resolve(ref));
+    } catch {
+        real = path.resolve(ref);
+    }
+    const byPath = all.filter(([, e]) => e.root === real || e.root === ref);
+    if (byPath.length) return byPath;
+    return all.filter(([, e]) => path.basename(e.root) === ref);
+}