@event4u/agent-config 16.2.0 → 16.3.0

package/src/install/installedRuleLinks.ts

@@ -0,0 +1,220 @@
+/**
+ * Do the links inside an installed rule file resolve from where the install
+ * puts it?
+ *
+ * A rule body is authored in `src/rules/` and projected to
+ * `dist/agent-src/rules/`, where `](../guidelines/x.md)` resolves because the
+ * sibling directory is right there. The installer then copies a SUBSET of
+ * those sibling directories into the host's rule directory, so the same link
+ * resolves or does not depending on a list in `install.ts` that the rule
+ * author never sees. Nothing checked the two against each other.
+ *
+ * This module answers one question per link — resolved, or why not — against a
+ * deploy plan rather than against a materialised tree, so the audit costs a
+ * `statSync` per distinct target instead of a copy of 299 skills.
+ *
+ * Side-effect-free, no CLI entry, no `process.exit`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Why a link does not resolve from the installed file's own directory. */
+export type LinkVerdict =
+    /** The target file is present in the installed tree. */
+    | 'resolved'
+    /** The link climbs above the install root — a repo-tree path, never shipped. */
+    | 'outside-install-root'
+    /** The first segment names a directory the deploy plan does not write. */
+    | 'directory-not-deployed'
+    /** The directory IS deployed, but the file is not in it. */
+    | 'file-missing';
+
+export interface LinkAudit {
+    /** Rule file the link was written in, as a bare id (no directory, no `.md`). */
+    rule: string;
+    /** The link target exactly as the markdown carries it, anchor included. */
+    target: string;
+    /** Install-root-relative path the target resolves to, or null when it escapes. */
+    resolved_to: string | null;
+    verdict: LinkVerdict;
+}
+
+export interface LinkAuditReport {
+    audits: LinkAudit[];
+    /** Count per verdict, every verdict present even at zero. */
+    counts: Record<LinkVerdict, number>;
+    /** Unresolved links grouped by the first path segment, highest first. */
+    by_directory: { directory: string; count: number; verdict: LinkVerdict }[];
+}
+
+/**
+ * A deploy plan: installed directory name -> the package directory copied into
+ * it. Exactly the shape of one `GLOBAL_DEPLOY_SOURCES` entry, inverted, so a
+ * caller can hand this module the real plan rather than a restatement of it.
+ */
+export type DeployPlan = Map<string, string>;
+
+/**
+ * Build a plan from `GLOBAL_DEPLOY_SOURCES`-shaped pairs.
+ *
+ * The empty destination (`cline` maps rules to the root) is deliberately kept:
+ * a rule installed at the root resolves `../x` differently, and silently
+ * dropping the entry would make this module answer a question about a layout
+ * that is not the one being installed.
+ */
+export function deployPlanFrom(pairs: ReadonlyArray<readonly [string, string]>): DeployPlan {
+    const plan: DeployPlan = new Map();
+    for (const [source, dest] of pairs) plan.set(dest, source);
+    return plan;
+}
+
+/** Markdown inline links, minus the ones that are not a path into the tree. */
+export function relativeLinkTargets(markdown: string): string[] {
+    const out: string[] = [];
+    for (const m of markdown.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const target = m[1] as string;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue; // http:, mailto:, etc.
+        if (target.startsWith('#')) continue; // same-file anchor
+        if (target.startsWith('/')) continue; // absolute — not ours to resolve
+        out.push(target);
+    }
+    return out;
+}
+
+/** Strip a trailing `#anchor`; a bare directory link keeps its trailing slash. */
+function withoutAnchor(target: string): string {
+    const hash = target.indexOf('#');
+    return hash === -1 ? target : target.slice(0, hash);
+}
+
+/**
+ * Audit one link written in a rule that the install places at
+ * `<install-root>/<rulesDest>/<rule>.md`.
+ */
+export function auditLink(
+    rule: string,
+    target: string,
+    rulesDest: string,
+    plan: DeployPlan,
+    packageRoot: string,
+): LinkAudit {
+    const bare = withoutAnchor(target);
+    // Resolve the link the way a reader does: from the installed file's own
+    // DIRECTORY — `rulesDest` is that directory, not the file — as a POSIX
+    // path relative to the install root. A sibling link (`[x](other.md)`, no
+    // `../`) therefore stays inside the rules directory, which is where the
+    // installer puts its sibling.
+    const fromDir = rulesDest === '' ? '.' : rulesDest;
+    const resolved = path.posix.normalize(path.posix.join(fromDir, bare));
+
+    if (resolved.startsWith('..')) {
+        return { rule, target, resolved_to: null, verdict: 'outside-install-root' };
+    }
+
+    const segments = resolved.split('/');
+    // Which deployed directory does this land in? Normally the first segment
+    // names it. When rules install at the install ROOT (`cline` maps them to
+    // `''`), there is no such segment: a sibling link like `](scope-control.md)`
+    // resolves to `scope-control.md`, whose first segment is a FILE NAME. Read
+    // literally that is `directory-not-deployed` for a file the install writes
+    // right beside the rule — 275 of cline's 523 links, every one of them fine.
+    // The `''` key exists in the plan precisely for this and could never be
+    // reached by a first-segment lookup.
+    const rootSource = plan.get('');
+    // The root entry answers for a BARE filename only. A link with a directory
+    // segment the plan does not carry is `directory-not-deployed`, the same as
+    // anywhere else — resolving it against the rules source would probe a path
+    // the install never writes and report `file-missing`, whose documented
+    // meaning ("the directory IS deployed") would then be false.
+    const useRoot = rootSource !== undefined && segments.length === 1;
+    const source = useRoot ? rootSource : plan.get(segments[0] as string);
+    const rest = useRoot ? segments : segments.slice(1);
+    if (source === undefined) {
+        return { rule, target, resolved_to: resolved, verdict: 'directory-not-deployed' };
+    }
+
+    // An empty `rest` means the link points at the deployed directory itself.
+    const onDisk = path.join(packageRoot, source, ...rest);
+    const exists = fs.existsSync(onDisk);
+    return {
+        rule,
+        target,
+        resolved_to: resolved,
+        verdict: exists ? 'resolved' : 'file-missing',
+    };
+}
+
+const EMPTY_COUNTS = (): Record<LinkVerdict, number> => ({
+    resolved: 0,
+    'outside-install-root': 0,
+    'directory-not-deployed': 0,
+    'file-missing': 0,
+});
+
+/**
+ * Audit every link in every rule the plan installs.
+ *
+ * `packageRoot` is the package checkout the installer copies FROM; the rule
+ * bodies are read from the plan's own rules source, so the audit cannot drift
+ * from what is shipped.
+ */
+export function auditInstalledRuleLinks(plan: DeployPlan, packageRoot: string): LinkAuditReport {
+    const audits: LinkAudit[] = [];
+    for (const [dest, source] of plan) {
+        if (!source.endsWith('/rules')) continue;
+        const dir = path.join(packageRoot, source);
+        if (!fs.existsSync(dir)) continue;
+        const files = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const file of files) {
+            const rule = file.replace(/\.md$/, '');
+            const body = fs.readFileSync(path.join(dir, file), 'utf8');
+            for (const target of relativeLinkTargets(body)) {
+                audits.push(auditLink(rule, target, dest, plan, packageRoot));
+            }
+        }
+    }
+
+    const counts = EMPTY_COUNTS();
+    for (const a of audits) counts[a.verdict] += 1;
+
+    const grouped = new Map<string, { count: number; verdict: LinkVerdict }>();
+    for (const a of audits) {
+        if (a.verdict === 'resolved') continue;
+        const key = a.resolved_to === null ? a.target.replace(/[^/]*$/, '') : (a.resolved_to.split('/')[0] as string);
+        const row = grouped.get(key);
+        if (row) row.count += 1;
+        else grouped.set(key, { count: 1, verdict: a.verdict });
+    }
+    const by_directory = [...grouped.entries()]
+        .map(([directory, v]) => ({ directory, count: v.count, verdict: v.verdict }))
+        .sort((a, b) => b.count - a.count || a.directory.localeCompare(b.directory));
+
+    return { audits, counts, by_directory };
+}
+
+/**
+ * Standing-text cost of the rewrite option, in characters.
+ *
+ * Option A of this roadmap's step 1.2: leave the install plan alone and
+ * rewrite every link to an absolute package path. Each unresolved link then
+ * grows by the absolute prefix minus the `../` it replaces — and it grows
+ * INSIDE a rule body, which is the text the host loads as instructions.
+ *
+ * `prefixChars` is the installed package root's own length, which is a
+ * property of the machine, so the caller supplies it and the report says which
+ * value it used.
+ */
+export function rewriteOptionCost(report: LinkAuditReport, prefixChars: number): number {
+    const unresolved = report.audits.filter((a) => a.verdict !== 'resolved');
+    let total = 0;
+    for (const a of unresolved) {
+        // `../x` and `../../x` both become `<abs>/x`: the climb is replaced.
+        const climb = (a.target.match(/\.\.\//g) ?? []).length * 3;
+        total += prefixChars + 1 - climb;
+    }
+    return total;
+}

package/src/install/wizard-plan.ts

@@ -64,6 +64,30 @@ export const USER_SCOPE_PATHS: Readonly<Record<string, string>> = {
 /**
  * Universal Anthropic-shaped skill bundle deployed to markdown-skills
  * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in the retired Python installer (ADR-200).
+ *
+ * NOT deploying `contexts/` and `guidelines/` here is a held decision, not an
+ * oversight — see the `rule-link-targets-change-the-frozen-install-abi` blocker
+ * on `road-to-rule-triggers-and-links-that-hold`.
+ *
+ * A rule is authored against the package tree and projected verbatim, so
+ * `](../guidelines/x.md)` resolves in `dist/agent-src/rules/` and then does
+ * not resolve in the install, because this table does not carry those two
+ * directories. Measured by `report_installed_rule_links` on 2026-10-03: 136 of
+ * 523 links in an installed Claude rule directory point nowhere, 112 of them
+ * into exactly those two. Adding them is the cheaper of the two repairs on the
+ * budget that is scarce — 0 standing characters against **5,152** for rewriting
+ * those same 112 links to absolute package paths, at a 48-character install
+ * prefix (the report prints the prefix it used; the figure scales with it).
+ *
+ * The totals were 160 of 550 when this was first measured and 158 of 545 on
+ * 2026-10-02; what fell since is the OTHER population — repo-tree link forms no
+ * install ever held — so the 112 this paragraph is about has not moved.
+ *
+ * It is held because this table is part of the FROZEN install ABI
+ * (`docs/contracts/install-layout.md`), and any change to it owes an
+ * `install_layout_version` bump plus a deprecation window: old and new shape
+ * side by side for a minor cycle, with in-place migration. That is a release
+ * commitment, not an implementation detail, so it is the owner's to make.
  */
 const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
     ['dist/agent-src/rules',    'rules'],

package/src/scripts/_cli/cmd_doctor.ts

@@ -134,6 +134,8 @@ import {
 } from './detection_report.js';
 import { review_gate_doctor_signal } from '../ai_team/review_gate.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { rglob as _rglob_raw, scanForeign } from '../_lib/foreign_scan.js';
+import { runCensus, summaryLine } from './cmd_doctor_neighbours.js';
 import {
     LEGACY_ALL,
     excludedRuleBasenames,
@@ -617,77 +619,17 @@ function _collect_manifest_entries(
     return [records, known];
 }
 
-/**
- * Walk every declared deploy root and surface unclaimed files. Only regular
- * files under `deploy_roots` count; bookkeeping is on the resolved final path.
- */
-function _scan_foreign(
-    project_root: string,
-    manifest: Dict,
-    known: Set<string>,
-): string[] {
-    const roots =
-        (manifest['deploy_roots'] as unknown[] | undefined) ||
-        Array.from(installed_tools.DEFAULT_DEPLOY_ROOTS);
-    const foreign: string[] = [];
-    const seen = new Set<string>();
-    for (const root_rel of roots) {
-        const root = _resolve_path(project_root, String(root_rel));
-        if (!pathExists(root) || !isDir(root)) {
-            continue;
-        }
-        for (const child of rglob(root)) {
-            if (!isFile(child)) {
-                continue;
-            }
-            let resolved: string;
-            try {
-                resolved = resolvePath(child);
-            } catch {
-                resolved = child;
-            }
-            if (known.has(resolved) || seen.has(resolved)) {
-                continue;
-            }
-            seen.add(resolved);
-            foreign.push(child);
-        }
-    }
-    foreign.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    return foreign;
-}
-
-/**
- * `Path.rglob("*")` — every descendant path (dirs + files), recursively.
- * Order is not relied upon by callers (they sort the matched set), but the
- * walk is deterministic (sorted per directory) to keep behaviour stable.
- */
-function rglob(root: string): string[] {
-    const out: string[] = [];
-    const walk = (dir: string): void => {
-        let entries: fs.Dirent[];
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            return;
-        }
-        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-        for (const ent of entries) {
-            const full = path.join(dir, ent.name);
-            out.push(full);
-            let dirLike = ent.isDirectory();
-            if (ent.isSymbolicLink()) {
-                // pathlib rglob follows into symlinked dirs.
-                dirLike = isDir(full);
-            }
-            if (dirLike) {
-                walk(full);
-            }
-        }
-    };
-    walk(root);
-    return out;
-}
+const rglob = (root: string): string[] => _rglob_raw(root, isDir, path.join);
+const _scan_foreign = (project_root: string, manifest: Dict, known: Set<string>): string[] =>
+    scanForeign(project_root, manifest, known, {
+        pathExists,
+        isDir,
+        isFile,
+        resolvePath,
+        join: path.join,
+        resolveRoot: _resolve_path,
+        defaultRoots: installed_tools.DEFAULT_DEPLOY_ROOTS,
+    });
 
 /**
  * Split manifest records into missing / modified / tag-drift lists.
@@ -3028,6 +2970,11 @@ function _run_no_manifest(
         _emit_checks_text(checks);
         _emit_detection_text(project_root, checks);
     }
+    // Also on the no-manifest branch: a consumer with no project lockfile
+    // still has neighbours, and a census that appeared only once a lockfile
+    // existed would be missing on exactly the install shape most likely to
+    // have other packages in it.
+    if (opts.check === null && !opts.json) print(summaryLine(runCensus(project_root, _package_root())));
 
     if (opts.check !== null) {
         if (skipped_requested) {
@@ -3452,6 +3399,11 @@ function main(argv: string[] | null = null): number {
         _emit_detection_text(project_root, checks);
         if (opts.check === null) {
             _emit_text(project_root, missing, modified, foreign, tag_drift);
+            // One line, counts only — the `foreign` listing above stays as it
+            // is and nothing is removed from it. That listing walks THIS
+            // package's deploy roots; the census walks where the hosts keep
+            // things, which is a strictly larger question with its own verb.
+            print(summaryLine(runCensus(project_root, _package_root())));
         }
     }
 

package/src/scripts/_cli/cmd_doctor_neighbours.ts

@@ -0,0 +1,293 @@
+/**
+ * `agent-config doctor neighbours` — render the neighbour census.
+ *
+ * A separate entry point rather than another branch inside `cmd_doctor.ts`,
+ * which sits 2,000 lines above the source-size ceiling: a verb this size does
+ * not belong in a file that already cannot grow. The census itself is
+ * `_lib/neighbour_census.ts`; everything here is presentation and the one
+ * summary line the full `doctor` run links to.
+ *
+ * Refuses nothing. No label here removes, blocks, or rewrites a neighbour's
+ * artifact — a label is a report, never a gate.
+ *
+ * It is no longer read-ONLY, and the two writes are named rather than implied.
+ * Both land under `agents/reports/` and both are caches of this run's own
+ * findings: `neighbour-scan.json`, the shape-scan verdicts the ranker reads on
+ * the hook path, and `neighbour-overlap.json`, the cross-root pairs keyed by the
+ * census digest. Nothing outside that directory is touched, and a failed write
+ * is not a failed census.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import {
+    census,
+    fileDigest,
+    gatedEventsFrom,
+    scanCachePath,
+    type NeighbourCensus,
+} from '../_lib/neighbour_census.js';
+import { scanNeighbourBody, writeScanCache } from '../_lib/neighbour_scan.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
+import {
+    OVERLAP_THRESHOLD,
+    CROSS_CACHE_NAME,
+    cachedCrossRootPairs,
+    crossRootOverlapMap,
+} from '../audit_skill_overlap.js';
+
+interface ManifestShape {
+    concerns?: Record<string, { effect?: string }>;
+    platforms?: Record<string, Record<string, unknown>>;
+    native_event_aliases?: Record<string, Record<string, string>>;
+}
+
+/** Read the hook manifest for the events a `permission` concern of ours sits on. */
+function gatedEvents(packageRoot: string): Set<string> {
+    try {
+        // A missing or unreadable manifest yields an empty gate set, which
+        // downgrades `degraded` to `coordinated` rather than inventing a gate
+        // that is not there.
+        const file = path.join(packageRoot, 'src', 'scripts', 'hook_manifest.yaml');
+        const doc = YAML.parse(fs.readFileSync(file, 'utf-8')) as ManifestShape;
+        return gatedEventsFrom(doc, doc.native_event_aliases ?? {});
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/** This package's own skill names, for the `shadowed` warning. */
+function ourSkillNames(packageRoot: string): Set<string> {
+    try {
+        return new Set(
+            fs
+                .readdirSync(path.join(packageRoot, 'src', 'skills'), { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name),
+        );
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/**
+ * The census, in two passes, and the second one is not an accident.
+ *
+ * The cross-root overlap can only be computed over the neighbour skills the
+ * census FOUND — the unclaimed entries of two roots that also hold claimed ones,
+ * since `agent-config install` writes this package's own skills into
+ * `~/.claude/skills`. Pairing whole roots instead would compare our installed
+ * copies against our own source tree and publish the install as an overlap. So
+ * pass one finds them, the overlap runs over exactly those files, and pass two
+ * labels them.
+ *
+ * The shape scan is memoized across both passes, so the four linters run once
+ * per neighbour body rather than twice. The scan verdicts are then WRITTEN to
+ * the cache the ranker reads on the hook path — this verb is the only producer,
+ * which is why its absence reads there as `no-scan-record` rather than as a pass.
+ */
+export function runCensus(
+    projectRoot: string,
+    packageRoot: string,
+    homeRoot?: string,
+): NeighbourCensus {
+    const scanned = new Map<string, string | null>();
+    const scan = (p: string): string | null => {
+        const hit = scanned.get(p);
+        if (hit !== undefined) return hit;
+        const kind = scanNeighbourBody(p).kind;
+        scanned.set(p, kind);
+        return kind;
+    };
+    const base = {
+        gatedEvents: gatedEvents(packageRoot),
+        templatesRoot: path.join(packageRoot, 'src', 'agent-src', 'templates'),
+        ourSkillNames: ourSkillNames(packageRoot),
+        packageRoot,
+        scan,
+        ...(homeRoot === undefined ? {} : { homeRoot }),
+    };
+    const first = census(projectRoot, base);
+    const ourRoot = path.join(packageRoot, 'src', 'skills');
+    let overlaps = new Map<string, { names: string[]; similarity: number }>();
+    if (first.skills.length > 0 && fs.existsSync(ourRoot)) {
+        try {
+            const { pairs } = cachedCrossRootPairs(
+                first.skills.map((s) => s.source),
+                ourRoot,
+                path.join(projectRoot, 'agents', 'reports', CROSS_CACHE_NAME),
+                OVERLAP_THRESHOLD,
+            );
+            overlaps = crossRootOverlapMap(pairs);
+        } catch {
+            // An overlap pass that cannot run leaves every entry unlabelled by
+            // it, which reads as `unclassified` — the absence of a signal — and
+            // never as a claim that the pair is disjoint.
+        }
+    }
+    const full = census(projectRoot, { ...base, overlaps });
+    writeScanCache(
+        scanCachePath(projectRoot),
+        // `fileDigest`, not the census's own `digest`: the ranker re-digests the
+        // file bytes it is about to index, and a cache written under a different
+        // digest function would read as `digest-changed` on every prompt.
+        full.skills.map((s) => ({
+            qualified: s.qualified,
+            digest: fileDigest(s.source) ?? '',
+            unscanned: s.unscanned,
+        })),
+    );
+    return full;
+}
+
+/** The one line the full `doctor` run prints, linking to this verb. */
+export function summaryLine(c: NeighbourCensus): string {
+    const counts = [
+        `${c.hook_groups.length} hook group(s)`,
+        `${c.skills.length} skill(s)`,
+        `${c.commands.length} command(s)`,
+        `${c.agents.length} agent(s)`,
+        `${c.mcp_servers.length} mcp server(s)`,
+        `${c.rule_files.length} rule file(s)`,
+        `${c.instruction_sections.length} instruction section(s)`,
+    ].join(', ');
+    const labels = c.hosts.map((h) => `${h.host}=${h.label}`).join(' ');
+    return `  🏘️   neighbours: ${counts}${labels === '' ? '' : ` · ${labels}`} (run \`doctor neighbours\` for the census)`;
+}
+
+export function renderText(c: NeighbourCensus): string[] {
+    const out: string[] = [];
+    out.push(`  📍  project_root: ${c.project_root}`);
+    out.push('');
+    for (const h of c.hosts) {
+        out.push(`  ${h.host}: ${h.label} — ${h.label_reason}`);
+        for (const e of h.hook_groups) {
+            const matcher = e.matcher === null ? '' : ` matcher=${e.matcher}`;
+            const timeout = e.timeout === null ? '' : ` timeout=${e.timeout}`;
+            out.push(`      ${e.event}: ${e.command_head}${matcher}${timeout} effect=${e.effect}`);
+        }
+    }
+    const section = (title: string, rows: ReadonlyArray<{ id: string }>): void => {
+        if (rows.length === 0) return;
+        out.push('');
+        out.push(`  ${title} (${rows.length})`);
+        for (const r of rows) out.push(`      ${r.id}`);
+    };
+    if (c.skills.length > 0) {
+        out.push('');
+        out.push(`  skills (${c.skills.length})`);
+        for (const s of c.skills) {
+            const also = s.also.length === 0 ? '' : ` also: ${s.also.join(', ')}`;
+            const why = s.unscanned === null ? '' : ` unscanned: ${s.unscanned}`;
+            out.push(`      ${s.qualified}  compat: ${s.compat}${also}${why}`);
+        }
+    }
+    section('commands', c.commands);
+    section('agents', c.agents);
+    if (c.mcp_servers.length > 0) {
+        out.push('');
+        out.push(`  mcp servers (${c.mcp_servers.length})`);
+        for (const m of c.mcp_servers) {
+            // `used` and `advertised` are printed side by side so the reader
+            // never takes the first for a coverage ratio: the denominator is
+            // not missing by accident, it is not obtainable without launching
+            // the neighbour's process, which this census does not do.
+            out.push(
+                `      ${m.id}  tools used (${m.tools_window_days}d): ${m.tools_used_30d}` +
+                    `  advertised: ${m.tools_advertised}`,
+            );
+        }
+    }
+    section('rule files', c.rule_files);
+    section('instruction sections', c.instruction_sections);
+    if (c.warnings.length > 0) {
+        out.push('');
+        for (const w of c.warnings) out.push(`  ⚠️   ${w.kind}: ${w.detail}`);
+    }
+    out.push('');
+    out.push(
+        '  The host owns load order. This census says what is there and what each entry would do;',
+    );
+    out.push('  it cannot say what ran first, and no label here refuses anything.');
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let json = false;
+    let root = process.cwd();
+    let home: string | undefined;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--json') json = true;
+        else if (argv[i] === '--project') {
+            root = argv[i + 1] ?? root;
+            i += 1;
+        } else if (argv[i] === '--home') {
+            // Fixture-only: the user-scope half of the census is real `$HOME`
+            // in production, and a test must be able to plant one.
+            home = argv[i + 1];
+            i += 1;
+        } else if (argv[i] === 'neighbours') {
+            continue;
+        } else {
+            process.stderr.write(`doctor neighbours: unknown argument: ${argv[i]}\n`);
+            return 2;
+        }
+    }
+    const c = runCensus(path.resolve(root), resolvePackageRoot(import.meta.url), home);
+    if (json) {
+        // Compact, not pretty-printed: this is the machine contract, and the
+        // gate that reads it matches on adjacency rather than on indentation.
+        process.stdout.write(`${JSON.stringify(c)}\n`);
+    } else {
+        for (const line of renderText(c)) process.stdout.write(`${line}\n`);
+    }
+    return 0;
+}
+
+/**
+ * Same entry guard the sibling CLIs use — including the delegate branch, which
+ * an earlier version of this file left out and which the delegate smoke test
+ * caught: `no bundle is a silent no-op` reported `cmd_doctor_neighbours.js (no
+ * output, exit 0)`, the exact shape the paragraph below describes.
+ *
+ * Inside the cli-delegate bundle `--splitting` moves this module's body into a
+ * shared chunk, so the URL comparison weighs the CHUNK against `argv[1]` and
+ * never matches. `agent-config doctor` shipped that way once already — a
+ * diagnostic reporting success while saying nothing. The invoked file name is
+ * the reliable signal there; a miss falls THROUGH to the realpath comparison
+ * rather than returning false, so a symlinked or renamed invocation still
+ * resolves. Inlined into the installer / hook / MCP bundle instead, it must
+ * never auto-run, which is why one "am I bundled" flag cannot answer "may I
+ * run" and both flags are read.
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
+function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    if (bundled && !cliDelegate) return false;
+    if (process.argv[1] === undefined) return false;
+    if (cliDelegate && path.basename(process.argv[1], '.js') === 'cmd_doctor_neighbours') {
+        return true;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}