@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/providers/typeorm.ts

@@ -0,0 +1,58 @@
+/**
+ * TypeORM, in files that import from `typeorm` (MikroORM shares `@Entity`):
+ *
+ *   @Entity('t') · @Entity({ name: 't' }) · @Entity()   class --persists--> table:t
+ *                                                       (bare: snake_case of the class, TypeORM's default naming)
+ *   @ManyToOne(() => X) · @OneToMany(() => X, …)        class --relates-->  X
+ *   queryRunner.createTable(new Table({ name: 't' }))   migration --migrates--> table:t
+ *
+ * A custom naming strategy, `@ViewEntity`, string-named relation targets and
+ * `EntitySchema` definitions are not followed.
+ */
+import { npmRoots } from './shared/detect.js';
+import { scopeKit } from './shared/js.js';
+import { lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const EXTS = ['.ts', '.js'];
+
+/** TypeORM's DefaultNamingStrategy table name: `UserProfile` → `user_profile`, `HTTPLog` → `http_log`. */
+export function typeormTableName(className: string): string {
+    return className
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase();
+}
+
+export const typeormProvider: ConventionProvider = {
+    id: 'typeorm',
+    detect: (probe) => npmRoots(probe, ['typeorm']),
+    build: (input) => {
+        const kit = scopeKit(makeKit(input), (src) => /\bfrom\s+['"]typeorm['"]|require\(\s*['"]typeorm['"]\s*\)/.test(src));
+        for (const f of kit.filesWithExt(...EXTS)) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(/@Entity\(\s*(?:(['"`])(?<name>[^'"`]+)\1|\{(?<opts>[^}]*)\})?/g)) {
+                const cls = kit.nextSymbol(f.path, at(m.index as number), ['class']);
+                if (!cls || cls.kind !== 'class') continue;
+                const fromOpts = /\bname\s*:\s*(['"`])([^'"`]+)\1/.exec(m.groups?.['opts'] ?? '')?.[2];
+                const name = m.groups?.['name'] ?? fromOpts ?? typeormTableName(cls.label);
+                kit.emit(cls.id, kit.table(name, f.path, cls.source_location[0] as number), 'persists', 'schema-call');
+            }
+            const relation = /@(?:ManyToOne|OneToMany|OneToOne|ManyToMany)\(\s*(?:\(\s*\w*\s*\)|\w+)\s*=>\s*([A-Za-z_$][\w$]*)/g;
+            for (const m of f.source.matchAll(relation)) {
+                const owner = kit.classAt(f.path, at(m.index as number));
+                const target = kit.resolveName(f.path, m[1] as string);
+                if (!owner || !target || target === owner.id || kit.nodeById.get(target)?.kind !== 'class') continue;
+                kit.emit(owner.id, target, 'relates', 'orm-relation');
+            }
+            const create = /new\s+Table\(\s*\{\s*name\s*:\s*(['"`])(?<name>[^'"`]+)\1|CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(?<raw>\w+)/gi;
+            if (/\bMigrationInterface\b/.test(f.source)) {
+                for (const m of f.source.matchAll(create)) {
+                    const name = m.groups?.['name'] ?? m.groups?.['raw'];
+                    if (name) kit.emit(f.path, kit.table(name, f.path, at(m.index as number)), 'migrates', 'schema-call');
+                }
+            }
+        }
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/providers/types.ts

@@ -0,0 +1,56 @@
+/**
+ * The provider seam (ADR-298): everything a framework links by convention
+ * reaches the graph through a registered provider, never through a call the
+ * build hard-wires. The core imports providers only through `./index.ts`.
+ */
+import type { SourceFile } from '../build.js';
+import type { FileRole } from '../map_model.js';
+import type { ResolutionConfig } from '../resolution_tiers.js';
+import type { CodeEdge, CodeNode } from '../types.js';
+
+/**
+ * What a provider may read to decide whether it applies: manifests and marker
+ * files, never file suffixes — `.php` does not mean any one framework.
+ */
+export interface ProjectProbe {
+    /** Manifest files by repo-relative POSIX path → text. */
+    manifests: ReadonlyMap<string, string>;
+    /** Repo-relative paths of marker files that carry no text worth reading (an entry script). */
+    markers: ReadonlySet<string>;
+    /** Every project path, sorted, code or not (templates, assets); empty when unknown. */
+    paths: readonly string[];
+}
+
+export const EMPTY_PROBE: ProjectProbe = { manifests: new Map(), markers: new Set(), paths: [] };
+
+export interface ProviderInput {
+    files: readonly SourceFile[];
+    baseNodes: readonly CodeNode[];
+    /** The graph's edges so far, read-only (import bindings, for resolving a handler name). */
+    baseEdges: readonly CodeEdge[];
+    /** Every project path under the provider's roots, code or not (templates). */
+    paths: readonly string[];
+    /** The manifests under the provider's roots, by repo-relative path → text. */
+    manifests: ReadonlyMap<string, string>;
+    resolution: ResolutionConfig;
+    /** Package roots the provider was detected in; `''` is the repository root. */
+    roots: readonly string[];
+}
+
+export interface ProviderResult {
+    nodes: CodeNode[];
+    edges: CodeEdge[];
+    /** Base edges the provider proves false; applied only when it drew something. */
+    contest?: (e: CodeEdge) => boolean;
+}
+
+export interface ConventionProvider {
+    id: string;
+    /** Basenames of marker files whose presence the probe should record (an entry script). */
+    markers?: readonly string[];
+    /** Package roots this provider applies to; empty when it does not. */
+    detect(probe: ProjectProbe): string[];
+    build(input: ProviderInput): ProviderResult;
+    /** A role the map gives a file by this provider's conventions. */
+    roleOf?(path: string): FileRole | undefined;
+}

package/src/scripts/code_graph/providers/vue-router.ts

@@ -0,0 +1,21 @@
+/**
+ * Vue Router: route objects `{ path: '/x', component: X }` or
+ * `component: () => import('./views/X.vue')` → PAGE /x --routes-to--> the
+ * component the file names or the single-file component it imports. Child
+ * paths are not joined to their parent's; `components: { default: … }` named
+ * views and alias specifiers (`@/views/X.vue`) are not followed.
+ */
+import { npmRoots } from './shared/detect.js';
+import { routeObjects } from './shared/js.js';
+import { makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+export const vueRouterProvider: ConventionProvider = {
+    id: 'vue-router',
+    detect: (probe) => npmRoots(probe, ['vue-router']),
+    build: (input) => {
+        const kit = makeKit(input);
+        routeObjects(kit, { exts: ['.ts', '.js', '.mjs'], componentKeys: ['component'] });
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/providers/wordpress.ts

@@ -0,0 +1,128 @@
+/**
+ * WordPress: hooks and theme parts, which no import or call states.
+ *
+ *   add_action('init', 'cb') · add_filter(…)       route `HOOK init` --routes-to--> the callback
+ *   add_shortcode('card', 'cb')                    route `SHORTCODE card` --routes-to--> the callback
+ *   get_template_part('parts/card'[, 'wide'])       caller --renders--> parts/card(-wide).php
+ *
+ * A hook name is no URL, so its route path is the name as written, without the
+ * leading slash an HTTP route carries. A callback resolves as a function of the
+ * same file, else the one function of that name in the tree; `[$this, 'm']`
+ * resolves to the enclosing class's method, `[X::class, 'm']` to X's method
+ * only when X is the class the file's namespace names. A closure, a dynamic
+ * hook name or an ambiguous function gets no edge. `do_action` fires a hook and
+ * declares nothing.
+ *
+ * Detection: a `wp-config.php` marker, a composer manifest requiring a
+ * WordPress core package or a wpackagist plugin/theme, or a composer manifest
+ * whose `type` is a WordPress plugin, theme or must-use plugin. A plugin or theme
+ * shipping no composer manifest carries no signal and stays undetected.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../types.js';
+import { markerRoots, union } from './shared/detect.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import { classNode, phpScope, qualify, shortName } from './shared/php.js';
+import type { ConventionProvider, ProjectProbe } from './types.js';
+import type { ResolutionConfig } from '../resolution_tiers.js';
+
+const CORE = /^(?:johnpbloch\/wordpress(?:-core)?|roots\/wordpress(?:-no-content)?|roots\/bedrock|wpackagist-(?:plugin|theme)\/.+)$/;
+const TYPES = new Set(['wordpress-plugin', 'wordpress-theme', 'wordpress-muplugin']);
+
+function detectWordpress(probe: ProjectProbe): string[] {
+    const roots: string[] = [];
+    for (const [p, text] of probe.manifests) {
+        if (path.posix.basename(p) !== 'composer.json') continue;
+        try {
+            const j = JSON.parse(text) as { name?: string; type?: string; require?: Record<string, string>; 'require-dev'?: Record<string, string> };
+            const deps = [...Object.keys(j.require ?? {}), ...Object.keys(j['require-dev'] ?? {})];
+            if (TYPES.has(j.type ?? '') || j.name === 'roots/bedrock' || deps.some((d) => CORE.test(d))) {
+                const d = path.posix.dirname(p);
+                roots.push(d === '.' ? '' : d);
+            }
+        } catch {
+            continue;
+        }
+    }
+    return union(roots, markerRoots(probe, 'wp-config.php'));
+}
+
+const REGISTRATION = /\b(?<fn>add_action|add_filter|add_shortcode)\(\s*(['"])(?<name>[\w\-/.:]+)\2\s*,\s*/g;
+
+function callback(kit: Kit, file: string, src: string, at: number, line: number, functions: Map<string, CodeNode[]>, resolution: ResolutionConfig): string | null {
+    const rest = src.slice(at, at + 300);
+    const fn = /^(['"])\\?(?:[\w\\]+\\)?(?<name>\w+)\1/.exec(rest)?.groups?.['name'];
+    if (fn) {
+        const local = (functions.get(fn) ?? []).filter((n) => n.source_file === file);
+        if (local.length === 1) return (local[0] as CodeNode).id;
+        const all = functions.get(fn) ?? [];
+        return all.length === 1 ? (all[0] as CodeNode).id : null;
+    }
+    const pair = /^(?:\[|array\()\s*(?<recv>\$this|self::class|static::class|__CLASS__|[\\\w]+::class|(['"])[\\\w]+\2)\s*,\s*(['"])(?<member>\w+)\3/.exec(rest);
+    if (!pair?.groups) return null;
+    const recv = pair.groups['recv'] as string;
+    const member = pair.groups['member'] as string;
+    let cls: string | null = null;
+    if (/^(?:\$this|self::class|static::class|__CLASS__)$/.test(recv)) cls = kit.classAt(file, line)?.id ?? null;
+    else {
+        const ref = recv.replace(/::class$/, '').replace(/^['"]|['"]$/g, '');
+        const fq = /^['"]/.test(recv) ? ref.replace(/^\\/, '') : qualify(ref, phpScope(src));
+        cls = classNode(kit, fq, resolution) ?? classByNamespace(kit, fq);
+    }
+    return cls ? kit.methodOf(cls, member) : null;
+}
+
+/** The one class node whose short name and declaring file's namespace spell `fq`. */
+function classByNamespace(kit: Kit, fq: string): string | null {
+    const short = shortName(fq);
+    const hits = kit.nodesNamed(short).filter((n) => {
+        if (n.kind !== 'class') return false;
+        const f = kit.files.find((x) => x.path === n.source_file);
+        const ns = f ? phpScope(f.source).namespace : '';
+        return (ns ? `${ns}\\${short}` : short) === fq;
+    });
+    return hits.length === 1 ? (hits[0] as CodeNode).id : null;
+}
+
+/** `slug[-name].php`, preferring a part under a directory that holds the calling file (its theme). */
+function templatePart(kit: Kit, caller: string, slug: string, name: string | undefined): string | null {
+    for (const rel of name ? [`${slug}-${name}.php`, `${slug}.php`] : [`${slug}.php`]) {
+        const hits = kit.paths.filter((p) => p === rel || p.endsWith(`/${rel}`));
+        const own = hits.filter((p) => caller.startsWith(p.slice(0, p.length - rel.length)));
+        if (own.length === 1) return own[0] as string;
+        if (own.length === 0 && hits.length === 1) return hits[0] as string;
+    }
+    return null;
+}
+
+export const wordpressProvider: ConventionProvider = {
+    id: 'wordpress',
+    markers: ['wp-config.php'],
+    detect: detectWordpress,
+    build: (input) => {
+        const kit = makeKit(input);
+        const functions = new Map<string, CodeNode[]>();
+        for (const n of input.baseNodes) {
+            if (n.kind !== 'function' || !n.source_file.endsWith('.php')) continue;
+            functions.set(n.label, [...(functions.get(n.label) ?? []), n]);
+        }
+        for (const f of kit.filesWithExt('.php')) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(REGISTRATION)) {
+                const line = at(m.index as number);
+                const verb = m.groups?.['fn'] === 'add_shortcode' ? 'SHORTCODE' : 'HOOK';
+                const id = kit.route(f.path, verb, m.groups?.['name'] as string, line);
+                const target = callback(kit, f.path, f.source, (m.index as number) + m[0].length, line, functions, input.resolution);
+                if (target) kit.emit(id, target, 'routes-to', 'route-table');
+            }
+            for (const m of f.source.matchAll(/\bget_template_part\(\s*(['"])(?<slug>[\w\-/]+)\1\s*(?:,\s*(['"])(?<name>[\w-]+)\3)?/g)) {
+                const target = templatePart(kit, f.path, m.groups?.['slug'] as string, m.groups?.['name']);
+                if (!target) continue;
+                kit.fileNode(target);
+                kit.emit(kit.enclosing(f.path, at(m.index as number)), target, 'renders', 'directive-scan');
+            }
+        }
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/query.ts

@@ -13,7 +13,6 @@ import {
     emitSqliteTwin,
     type GraphIndex,
     INDEXED_READ_MIN_EDGES,
-    loadSerializedFromTwin,
     openGraphIndex,
 } from './sqlite_store.js';
 import type { CodeEdge, CodeGraph, CodeNode, Relation } from './types.js';
@@ -132,6 +131,9 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     // used to be preferred and still returned the entire serialization, which
     // made it a cheaper blob transport rather than an index.
     const index = openGraphIndex(graphPath);
+    // `openGraphIndex` declines on exactly the conditions under which the twin
+    // is stale, absent or corrupt — so a handle here means it needs no re-emit.
+    const twinCurrent = index !== null;
     if (index) {
         if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source, graphPath);
         // Small graph: the in-memory path is cheaper. Release the handle rather
@@ -139,12 +141,10 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
         index.close();
     }
 
-    // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
-    // the canonical JSON, byte-identical content, ~1/90 the load cost at
-    // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
-    // twin from it (zero-touch rebuild-on-drift, Phase 7).
-    const fromTwin = loadSerializedFromTwin(graphPath);
-    const raw = fromTwin ?? fs.readFileSync(graphPath, 'utf-8');
+    // Below the threshold the JSON is parsed. The twin no longer carries a
+    // second copy of it to read instead; a missing or stale twin is re-emitted
+    // below (zero-touch rebuild-on-drift, ADR-129 Phase 7).
+    const raw = fs.readFileSync(graphPath, 'utf-8');
     const parsed = JSON.parse(raw) as unknown;
     // A consumer's own graph file, written by another tool, is DETECTED by
     // `detect.ts` and used to throw here — detected-but-unloadable, the worst
@@ -166,8 +166,8 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     // The twin is a cache of a file's bytes keyed on its own checksum. An
     // adapted graph's bytes are not the file's, so emitting one would cache a
     // derivation under the source's identity.
-    if (fromTwin === null && !foreignAdapted) {
-        emitSqliteTwin(graph, raw, graphPath);
+    if (!twinCurrent && !foreignAdapted) {
+        emitSqliteTwin(graph, graphPath);
     }
     const byId = new Map(graph.nodes.map((n) => [n.id, n]));
     const outM = new Map<string, CodeEdge[]>();

package/src/scripts/code_graph/refresh_cli.ts

@@ -0,0 +1,81 @@
+/**
+ * Which `agent-config` a background refresh may start — shared by the
+ * `code-graph-refresh` session concern and `code-graph auto-refresh on`, so the
+ * opt-in can say at once when nothing usable is installed.
+ *
+ * The executable is never taken from the repository (its root, its
+ * `node_modules/.bin`, a relative PATH entry): the same trust rule the host hook
+ * shim applies before it runs the dispatcher. And it must be able to do the job:
+ * a global install older than the single-flight refresh ignores the flags it
+ * does not know and would build unlocked with an old extractor.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** A file only a package that implements `refresh --single-flight` ships (the published tarball carries `src/scripts/`). */
+const CAPABILITY_FILE = 'src/scripts/code_graph/refresh_lock.ts';
+
+/**
+ * The first `agent-config` on PATH whose real location lies outside `root`.
+ * Relative PATH entries are skipped: they resolve against the repository.
+ */
+export function resolveCli(root: string, envPath: string = process.env['PATH'] ?? ''): string | null {
+    let realRoot: string;
+    try {
+        realRoot = fs.realpathSync(root);
+    } catch {
+        return null;
+    }
+    const inside = (p: string): boolean => {
+        const rel = path.relative(realRoot, p);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    };
+    for (const dir of envPath.split(path.delimiter)) {
+        if (!path.isAbsolute(dir)) continue;
+        const candidate = path.join(dir, 'agent-config');
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            const real = fs.realpathSync(candidate);
+            if (fs.statSync(real).isFile() && !inside(real) && !inside(path.resolve(dir))) return candidate;
+        } catch {
+            /* not here */
+        }
+    }
+    return null;
+}
+
+/** The installed package a CLI belongs to: the nearest `package.json` above its real path naming this package. */
+export function cliPackage(cli: string): { root: string; version: string } | null {
+    try {
+        for (let dir = path.dirname(fs.realpathSync(cli)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+            const file = path.join(dir, 'package.json');
+            if (!fs.existsSync(file)) continue;
+            const pkg = JSON.parse(fs.readFileSync(file, 'utf-8')) as { name?: string; version?: string };
+            if (pkg.name === '@event4u/agent-config') return { root: dir, version: pkg.version ?? '?' };
+        }
+    } catch {
+        /* unreadable — no package */
+    }
+    return null;
+}
+
+/**
+ * Whether the package a CLI belongs to implements the single-flight refresh.
+ * An installed CLI is `<package>/dist/cli/agent-config.js`; the check is the
+ * presence of a file only such a package ships, so nothing is executed.
+ */
+export function cliIsCapable(cli: string): boolean {
+    // The same package root the version report uses, so a symlinked or hoisted
+    // layout cannot make one call see a package the other does not.
+    const pkg = cliPackage(cli);
+    return pkg !== null && fs.existsSync(path.join(pkg.root, CAPABILITY_FILE));
+}
+
+export type CliVerdict = { cli: string } | { reason: 'no-cli' } | { reason: 'cli-too-old'; cli: string };
+
+/** A trusted `agent-config` that implements the single-flight refresh, or why there is none. */
+export function usableCli(root: string, envPath?: string): CliVerdict {
+    const cli = resolveCli(root, envPath);
+    if (cli === null) return { reason: 'no-cli' };
+    return cliIsCapable(cli) ? { cli } : { reason: 'cli-too-old', cli };
+}

package/src/scripts/code_graph/refresh_lock.ts

@@ -0,0 +1,197 @@
+/**
+ * Single-flight lock for `code-graph refresh --single-flight` and `map`.
+ *
+ * Every producer goes through {@link acquire}: the git-hook refresh block in
+ * `install-hooks.sh` and the `code-graph-refresh` session concern both run
+ * `refresh --single-flight`, so there is one locking protocol, not two.
+ * `mkdir` is the primitive because it is atomic on every POSIX filesystem.
+ *
+ * Ownership is recorded in a SIBLING file, never inside the directory, so the
+ * directory is empty and a single `rmdir`-style removal clears it.
+ *
+ * A lock is reclaimed only on positive evidence that its owner is gone (see
+ * {@link isStale}); an owner-less lock — a torn owner write — counts as stale
+ * only past {@link STALE_LOCK_MS}. A release removes the lock only while the
+ * owner record still carries the releaser's nonce, so a holder that was
+ * reclaimed cannot delete its successor's lock on the way out.
+ */
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { graphHome } from './graph_home.js';
+
+export const STALE_LOCK_MS = 5 * 60 * 1000;
+/**
+ * How long an owner on ANOTHER host (a container sharing the checkout) is
+ * believed: this host cannot probe its PID, so age is the only signal. An
+ * availability compromise, not proof — it reads the owner's own wall clock, so
+ * clock skew between hosts shifts it. A same-host owner whose PID is alive is
+ * never reclaimed on age (ratification, 2026-10-24, two of two seats): a paused,
+ * debugged or overloaded refresh is still a refresh.
+ */
+export const MAX_LOCK_AGE_MS = 30 * 60 * 1000;
+
+interface Owner {
+    pid: number;
+    started_at: number;
+    nonce: string;
+    /** Absent in records written before the host was stored; such an owner is judged by age alone. */
+    host?: string;
+}
+
+const ownerPath = (lock: string): string => `${lock}.owner.json`;
+
+export interface RefreshRecord {
+    at: string;
+    /** `session-start` (the concern) or `refresh` (the CLI run it starts, or a manual one). */
+    by: 'session-start' | 'refresh';
+    outcome: string;
+    detail?: string | undefined;
+}
+
+/** One file per side, so the session concern writes without reading or merging anything. */
+export const refreshRecordPath = (root: string, by: RefreshRecord['by']): string =>
+    path.join(path.dirname(graphHome(root).lockPath), `code-graph-refresh.${by}.json`);
+
+/** The last outcome of one side, so a refresh that never happens is visible. Best-effort. */
+export function recordRefresh(root: string, rec: Omit<RefreshRecord, 'at'>): void {
+    recordRefreshIn(path.dirname(graphHome(root).lockPath), rec);
+}
+
+/** For the session concern: its chunk must not carry the user-global resolver. */
+export function recordRefreshIn(stateDir: string, rec: Omit<RefreshRecord, 'at'>): void {
+    try {
+        fs.writeFileSync(path.join(stateDir, `code-graph-refresh.${rec.by}.json`), JSON.stringify({ at: new Date().toISOString(), ...rec }));
+    } catch {
+        /* never fails a refresh */
+    }
+}
+
+export function readRefreshRecords(root: string): Partial<Record<RefreshRecord['by'], RefreshRecord>> {
+    const out: Partial<Record<RefreshRecord['by'], RefreshRecord>> = {};
+    for (const by of ['session-start', 'refresh'] as const) {
+        try {
+            out[by] = JSON.parse(fs.readFileSync(refreshRecordPath(root, by), 'utf-8')) as RefreshRecord;
+        } catch {
+            /* never recorded */
+        }
+    }
+    return out;
+}
+
+export function pidAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        // EPERM means the process exists but belongs to someone else.
+        return (e as NodeJS.ErrnoException).code === 'EPERM';
+    }
+}
+
+const errno = (e: unknown): string | undefined => (e as NodeJS.ErrnoException).code;
+
+/** The owner record; `'none'` when there is no file or no valid record; `'unreadable'` on any other error. */
+function readOwner(lock: string): Owner | 'none' | 'unreadable' {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(ownerPath(lock), 'utf-8');
+    } catch (e) {
+        return errno(e) === 'ENOENT' ? 'none' : 'unreadable';
+    }
+    try {
+        const o = JSON.parse(raw) as Partial<Owner>;
+        if (typeof o.pid === 'number' && typeof o.started_at === 'number' && typeof o.nonce === 'string') return o as Owner;
+    } catch {
+        /* a torn write; fall through to the age rule */
+    }
+    return 'none';
+}
+
+/**
+ * True only on positive evidence: the owner's process is gone, the lock has
+ * vanished, or an owner-less lock is provably older than the threshold. A lock
+ * or owner record that cannot be inspected is treated as live.
+ */
+export function isStale(lock: string, now: number = Date.now()): boolean {
+    const owner = readOwner(lock);
+    if (owner === 'unreadable') return false;
+    if (owner !== 'none') {
+        // Only an owner that NAMES this host is judged by its PID. Another host's
+        // PID means nothing here, and a record without a host cannot be placed,
+        // so both are judged by age alone (see MAX_LOCK_AGE_MS).
+        if (owner.host !== os.hostname()) return now - owner.started_at > MAX_LOCK_AGE_MS;
+        return !pidAlive(owner.pid);
+    }
+    try {
+        return now - fs.statSync(lock).mtimeMs > STALE_LOCK_MS;
+    } catch (e) {
+        return errno(e) === 'ENOENT';
+    }
+}
+
+function take(lock: string): () => void {
+    const nonce = randomBytes(16).toString('hex');
+    fs.writeFileSync(ownerPath(lock), JSON.stringify({ pid: process.pid, started_at: Date.now(), nonce, host: os.hostname() }));
+    return () => {
+        const owner = readOwner(lock);
+        if (typeof owner === 'string' || owner.nonce !== nonce) return;
+        fs.rmSync(ownerPath(lock), { force: true });
+        fs.rmSync(lock, { recursive: true, force: true });
+    };
+}
+
+export const reclaimMutexPath = (lock: string): string => `${lock}.reclaim`;
+
+/** True when this process holds the lock (the CLI took it before calling in). */
+export function heldByThisProcess(root: string): boolean {
+    const owner = readOwner(graphHome(root).lockPath);
+    return typeof owner !== 'string' && owner.pid === process.pid;
+}
+
+/**
+ * Take the lock, or return null when another refresh holds it.
+ *
+ * A stale lock is removed only while holding a second mkdir mutex, and only
+ * after staleness is checked AGAIN under it. A reclaimer that judged the lock
+ * stale and was then overtaken finds the successor's live lock on that second
+ * check and declines, so it can never delete a lock created after it looked.
+ * A reclaim mutex left by a crash inside that short section is never removed
+ * automatically: no check before a removal can prove which mutex instance it
+ * removes, and removing a successor's would let two reclaimers in (ratification,
+ * 2026-10-24). Stale locks then stay held — lost freshness, never lost exclusion
+ * — and `code-graph auto-refresh status` names the leftover for a human to remove.
+ * `afterStaleCheck` exists for the interleaving test only.
+ */
+export function acquire(root: string, afterStaleCheck?: () => void): (() => void) | null {
+    const lock = graphHome(root).lockPath;
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    try {
+        fs.mkdirSync(lock);
+        return take(lock);
+    } catch (e) {
+        if (errno(e) !== 'EEXIST' || !isStale(lock)) return null;
+    }
+    afterStaleCheck?.();
+    const mutex = reclaimMutexPath(lock);
+    try {
+        fs.mkdirSync(mutex);
+    } catch {
+        return null;
+    }
+    try {
+        if (!isStale(lock)) return null;
+        fs.rmSync(ownerPath(lock), { force: true });
+        fs.rmSync(lock, { recursive: true, force: true });
+        try {
+            fs.mkdirSync(lock);
+        } catch {
+            return null;
+        }
+        return take(lock);
+    } finally {
+        fs.rmSync(mutex, { recursive: true, force: true });
+    }
+}