@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/lint_roadmap_blockers.ts

@@ -360,6 +360,130 @@ function _countRoadmapTree(dir: string): number {
     return n;
 }
 
+/**
+ * Blocker ids declared `Status: open` in one file, by id.
+ *
+ * Reads exactly one fact per blocker — id and open-ness. It is deliberately
+ * NOT `_scanBoth`: the five-field contract, the class taxonomy and the
+ * decidability ratchet are not applied here, because the corpus this runs over
+ * includes `archive/` and applying the contract there lands 23 findings on day
+ * one against a change that caused none of them. That shape has been reverted
+ * twice in this repository — `lint_roadmap_later_disposition` at 68 files and
+ * `check_no_new_legacy_path` at 46 — and the exclusion also protects a true
+ * thing an archived roadmap is allowed to say: a blocker genuinely unresolved
+ * when its roadmap closed is history, not a defect.
+ */
+function _openBlockerIds(text: string): Set<string> {
+    const stripped = _stripFencedCode(text);
+    const out = new Set<string>();
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(stripped);
+    if (!sectionMatch) {
+        return out;
+    }
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    const rest = stripped.slice(sectionStart);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = stripped.slice(sectionStart, h2 ? sectionStart + h2.index : stripped.length);
+
+    BLOCKER_HEADING_RE.lastIndex = 0;
+    const heads: Array<{ end: number; start: number; id: string }> = [];
+    let hm: RegExpExecArray | null;
+    while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+        heads.push({ start: hm.index, end: hm.index + hm[0].length, id: (hm[1] as string).trim() });
+        if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+            BLOCKER_HEADING_RE.lastIndex++;
+        }
+    }
+    for (let i = 0; i < heads.length; i++) {
+        const cur = heads[i] as { end: number; start: number; id: string };
+        const bodyEnd =
+            i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
+        const body = section.slice(cur.end, bodyEnd);
+        // Resolved is a prefix test for the same reason `blocker_is_resolved`
+        // makes it one: `resolved 2026-09-08 by …` is resolved.
+        if (!/^-[ \t]*\*\*Status:\*\*[ \t]*resolved\b/im.test(body)) {
+            out.add(cur.id);
+        }
+    }
+    return out;
+}
+
+/** Sorted `*.md` directly under the archive directory. */
+function _globArchivedRoadmaps(): string[] {
+    const dir = path.join(REPO_ROOT, 'agents', 'roadmaps', 'archive');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+
+interface Overlap {
+    id: string;
+    active: string[];
+    archived: string[];
+}
+
+/** id → the files (repo-relative, sorted by input order) declaring it open. */
+function _openIdIndex(files: string[]): Map<string, string[]> {
+    const index = new Map<string, string[]>();
+    for (const f of files) {
+        const rel = _relPosix(f, REPO_ROOT);
+        for (const id of _openBlockerIds(fs.readFileSync(f, 'utf-8'))) {
+            const hits = index.get(id);
+            if (hits === undefined) {
+                index.set(id, [rel]);
+            } else {
+                hits.push(rel);
+            }
+        }
+    }
+    return index;
+}
+
+/**
+ * Blocker ids declared open in BOTH an active and an archived roadmap.
+ *
+ * The assertion is the one an archived record cannot legitimately make: a
+ * blocker still being decided in the active tree, simultaneously declared open
+ * in a file that says the work closed. The transition check in
+ * `archive_completed_roadmaps` catches the archival that produces this state;
+ * this catches it however else it arrives — a hand edit, a bad merge, or a
+ * commit that shipped stale index content.
+ *
+ * `open_blockers` is a shrink-only ratchet over the ACTIVE tree only, so
+ * without this the count is satisfiable by archiving rather than by resolving.
+ *
+ * Deliberately NOT "no id open in more than one file". Two ACTIVE roadmaps may
+ * legitimately share one cross-cutting blocker, and forbidding that would break
+ * a real pattern to catch a different defect (AI council 2026-09-08, 2/2
+ * present: the unscoped form "forbids legitimate cross-cutting blockers in
+ * multiple active roadmaps"). Two ARCHIVED files sharing an open id is out of
+ * scope for the same day-one reason as the contract itself: measured at 2 on
+ * this tree, so a hard assertion there would red the build on records this
+ * change did not create.
+ */
+function _archiveOverlap(
+    activeFiles: string[] = _globRoadmaps(),
+    archivedFiles: string[] = _globArchivedRoadmaps(),
+): Overlap[] {
+    const active = _openIdIndex(activeFiles);
+    const archived = _openIdIndex(archivedFiles);
+    const out: Overlap[] = [];
+    for (const [id, activeHits] of [...active.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        const archivedHits = archived.get(id);
+        if (archivedHits !== undefined) {
+            out.push({ id, active: activeHits, archived: archivedHits });
+        }
+    }
+    return out;
+}
+
 function main(): number {
     try {
         assertScanned({
@@ -411,6 +535,38 @@ function main(): number {
         return 1;
     }
 
+    // An archived roadmap says the work closed. An open blocker declared in one
+    // AND in an active roadmap therefore contradicts itself, and the shrink-only
+    // `open_blockers` ratchet reads the active tree only — so without this the
+    // count is satisfiable by archiving rather than by resolving.
+    //
+    // HARD rather than ratcheted, and measured before it shipped: 0 overlapping
+    // ids on this tree at 2026-09-08 (12 active open ids, 33 archived), so on
+    // the day it lands it fires on nothing and there is no backlog to
+    // grandfather — the same argument the `Class:` contract above makes.
+    const overlap = _archiveOverlap();
+    if (overlap.length > 0) {
+        process.stderr.write(
+            `\n❌  ${overlap.length} blocker id(s) declared open in both an active ` +
+                'and an archived roadmap\n',
+        );
+        for (const o of overlap) {
+            process.stderr.write(`    ${o.id}\n`);
+            for (const rel of o.active) {
+                process.stderr.write(`        active:   ${rel}\n`);
+            }
+            for (const rel of o.archived) {
+                process.stderr.write(`        archived: ${rel}\n`);
+            }
+        }
+        process.stderr.write(
+            '\n    Resolve it in one place. An archived record may keep a blocker that\n' +
+                '    was genuinely unresolved when its roadmap closed; it may not keep one\n' +
+                '    the active tree is still deciding.\n',
+        );
+        return 1;
+    }
+
     // The decidability ratchet. A blocker that names no option, no command and
     // no recommendation is a research task handed to the person with the least
     // context — the defect this half of the gate exists to stop growing.
@@ -434,6 +590,10 @@ function main(): number {
     }
     if (!QUIET) {
         process.stdout.write(`\n✅  ${roadmaps.length} roadmap(s) blocker-contract-clean\n`);
+        process.stdout.write(
+            `✅  0 blocker id(s) open in both an active and an archived roadmap ` +
+                `(${_globArchivedRoadmaps().length} archived file(s) read)\n`,
+        );
         process.stdout.write(`✅  ${verdict.message}\n`);
     }
     return 0;
@@ -477,6 +637,9 @@ export {
     _scan,
     _scanBoth,
     _globRoadmaps,
+    _globArchivedRoadmaps,
+    _openBlockerIds,
+    _archiveOverlap,
     main,
 };
-export type { Violation, ScanResult };
+export type { Violation, ScanResult, Overlap };

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
-  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). The 'implemented_on' field lists transports where the real handler is wired. Entries marked '[stub — implemented on demand]' are DOCUMENTATION of the on-demand backlog: per ADR-132 they are NOT registered on the stdio tools/list (the wire carries implemented tools only); the 'not_implemented' envelope contract (docs/contracts/mcp-tool-stub-envelope.md) remains for Worker parity. Generated by `build_mcp_catalog` — never hand-edit this file.",
-  "install_hint_stdio": "npx -y @event4u/agent-config mcp-server",
+  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). The 'implemented_on' field lists transports where the real handler is wired. Entries marked '[stub — implemented on demand]' are DOCUMENTATION of the on-demand backlog: per ADR-132 they are NOT registered on the stdio tools/list (the wire carries implemented tools only); the 'not_implemented' envelope contract (docs/contracts/mcp-tool-stub-envelope.md) remains for Worker parity. The 'install_hint_stdio' field is the INSTALLED-BINARY form and therefore assumes `agent-config` is on PATH (a global install, or an npx-resolved one the client already has); it deliberately carries no `npx` invocation, because the un-prompted form of that command is the one string this file's own gate forbids and the prompted form hangs a non-interactive client start. Generated by `build_mcp_catalog` — never hand-edit this file.",
+  "install_hint_stdio": "agent-config mcp-server",
   "tools": [
     {
       "name": "capabilities_index",
@@ -222,6 +222,156 @@
         "readOnlyHint": true
       }
     },
+    {
+      "name": "graph_dead",
+      "description": "Symbols with no accepted reference that no declared entry point names. REFUSES (status `refused`) while a source is unreadable: with no exportedness recorded, an exported-but-unimported symbol is indistinguishable from a dead one. Never a deletion recommendation.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "entry_points": {
+            "type": "string",
+            "description": "Path under this root to a newline-separated id/label list; `#` comments ok."
+          },
+          "accept_missing_exports": {
+            "type": "boolean",
+            "default": false,
+            "description": "Answer anyway, accepting the gap. Never a default."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "graph_impact",
+      "description": "What a diff can break: callers, dependents and test files reaching the changed symbols. Walks only stated-fact edges, never a same-name guess, and reports the guesses refused. Runs `git diff` for the rev.",
+      "side_effect": "shell",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "diff"
+        ],
+        "properties": {
+          "diff": {
+            "type": "string",
+            "description": "Git rev to diff HEAD against, e.g. `HEAD~1`."
+          },
+          "depth": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 2,
+            "description": "Hop limit."
+          },
+          "untested_only": {
+            "type": "boolean",
+            "default": false,
+            "description": "Instead return changed symbols no test imports."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "graph_path",
+      "description": "The shortest relation chain between two symbols, direction preserved. Answers \"how does A reach B\" without reading the files between. `(no path found)` when unconnected is an answer.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "from",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string",
+            "description": "Start node id, label, or free text."
+          },
+          "to": {
+            "type": "string",
+            "description": "Goal node id, label, or free text."
+          },
+          "budget": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 1500,
+            "description": "Token budget for lines."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "graph_query",
+      "description": "A symbol's direct outgoing relations — calls, imports, uses, inherits — each line carrying its confidence and resolution mechanism. For \"what does this touch\" before reading a file.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "symbol"
+        ],
+        "properties": {
+          "symbol": {
+            "type": "string",
+            "description": "Node id, label, or free text."
+          },
+          "budget": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 1500,
+            "description": "Token budget for lines."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "graph_tests_for",
+      "description": "Which test files exercise a symbol, derived from a test file importing it or its module. Empty means no test imports it — a finding, not an error.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "symbol"
+        ],
+        "properties": {
+          "symbol": {
+            "type": "string",
+            "description": "Node id `<relpath>#<sym>`, label, or free text."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
     {
       "name": "lint_skills",
       "description": "Lint skill, rule, command, guideline, and persona markdown files for frontmatter and structural errors. Use before committing or opening a PR that adds or edits any of those artifacts, to catch schema violations early. Read-only — never writes files or spawns git. Returns the `scripts/skill_linter.py --format json` payload: a `summary` object (pass / pass_with_warnings / fail / total counts) and a per-file `results` array with severity-tagged findings. Pass `paths` to lint a subset; omit for a full tree scan.",

package/src/scripts/mcp_server/graph_tools.ts

@@ -0,0 +1,294 @@
+/**
+ * The five code-graph MCP tools (`road-to-a-graph-that-is-shipped` 4.1).
+ *
+ * `graph_impact`, `graph_tests_for`, `graph_dead`, `graph_query`, `graph_path`.
+ * They are the agent-facing half of Phase 3: the verbs exist on the CLI and an
+ * agent that has to shell out to reach them will not, so the engine's answers
+ * were unreachable from the surface the consumer actually talks to. Risk-Register
+ * rank 1 is precisely "the install grows and the graph is still unread"; these
+ * are the readers.
+ *
+ * REGISTERED HERE, NOT IN `tools.ts`.
+ *
+ * `tools.ts` sits ~500 lines past the 1500-line ceiling
+ * `check_source_size_budget` enforces as a shrink-only ratchet, so five tool
+ * records with their schemas would cost ~150 units of excess there and nothing
+ * here. `tools.ts` spreads {@link GRAPH_TOOLS} into `ALLOWLIST`, which is two
+ * lines — paid for by moving `_strip` / `_resolvePath` out to `path_util.ts` in
+ * the same change.
+ *
+ * TELEMETRY NEEDS NO PER-TOOL WORK.
+ *
+ * `ToolCache.dispatch` records every `tools/call` centrally, so these five emit
+ * the identical line the other 31 do by being in `ALLOWLIST` at all — which is
+ * what the step's "same telemetry line as the other 31" asks for, and is
+ * stronger than a per-tool emit because it cannot be forgotten.
+ *
+ * READ-ONLY, WITH ONE HONEST EXCEPTION.
+ *
+ * Four are `side_effect: 'ro'`. `graph_impact` is `'shell'`, because it resolves
+ * its `diff` argument by running `git diff --name-only`. That subprocess is
+ * read-only in effect, and the enum has no value that says so — between
+ * understating the mechanism as `'ro'` and naming it, naming it is the only
+ * choice a capability enum exists to support.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { changedFiles } from '../code_graph/cli.js';
+import { detectSources, graphState, NATIVE_CACHE_REL, pickSource } from '../code_graph/detect.js';
+import { resolvePath } from './path_util.js';
+import { isTestFile } from '../code_graph/build.js';
+import { loadGraph, type LoadedGraph, path as graphPathVerb, query as graphQueryVerb } from '../code_graph/query.js';
+import {
+    dead,
+    entryPointsFromFile,
+    impact,
+    repoEntryPoints,
+    testsFor,
+    untested,
+} from '../code_graph/verbs.js';
+import type { BuiltinTool } from './tools.js';
+
+/** The `no graph here` answer, in one place so all five agree on its shape. */
+function noGraph(root: string): Record<string, unknown> {
+    return {
+        status: 'unavailable',
+        staleness: 'absent',
+        error:
+            'no code-graph source found under this root — run `agent-config code-graph build` ' +
+            'to build one, or ship a graph.json',
+        root,
+    };
+}
+
+/**
+ * Resolve the graph, run `fn`, release the handle.
+ *
+ * The handle owns an open SQLite database on the indexed path, so the `finally`
+ * is not hygiene — a long-lived MCP server that leaked one per call would hold
+ * a descriptor for the life of the process.
+ */
+function withGraph<T extends Record<string, unknown>>(
+    root: string,
+    fn: (g: LoadedGraph) => T,
+): Record<string, unknown> {
+    const picked = pickSource(detectSources(root, path.join(root, NATIVE_CACHE_REL)));
+    if (!picked || picked.kind === 'scip') return noGraph(root);
+    const g = loadGraph(picked.path, `${picked.kind}:${path.relative(root, picked.path)}`);
+    try {
+        const out = fn(g);
+        // `status` is DERIVED from the answer, never prefixed onto it. An
+        // independent review found `graph_dead`'s refusal returning
+        // `{status:'ok', refusal:'…', dead:[]}` — the same status a real answer
+        // carries, so a caller branching on `status` (which every fixture here
+        // trains it to do) read the refusal as "nothing is dead". That is the
+        // false negative the CLI's exit 1 exists to prevent, arriving over the
+        // wire instead. A refusal is its own status.
+        const refused = typeof out['refusal'] === 'string' && out['refusal'] !== '';
+        return { status: refused ? 'refused' : 'ok', ...out };
+    } finally {
+        g.close();
+    }
+}
+
+function str(args: Record<string, unknown>, key: string): string {
+    const v = args[key];
+    return typeof v === 'string' ? v.trim() : '';
+}
+
+function num(args: Record<string, unknown>, key: string, dflt: number): number {
+    const v = args[key];
+    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : dflt;
+}
+
+export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
+    graph_impact: {
+        name: 'graph_impact',
+        side_effect: 'shell',
+        description:
+            'What a diff can break: callers, dependents and test files reaching the ' +
+            'changed symbols. Walks only stated-fact edges, never a same-name guess, ' +
+            'and reports the guesses refused. Runs `git diff` for the rev.',
+        input_schema: {
+            type: 'object',
+            required: ['diff'],
+            properties: {
+                diff: { type: 'string', description: 'Git rev to diff HEAD against, e.g. `HEAD~1`.' },
+                depth: { type: 'integer', minimum: 1, default: 2, description: 'Hop limit.' },
+                untested_only: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Instead return changed symbols no test imports.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const rev = str(args, 'diff');
+            if (rev === '') return { status: 'error', error: 'diff must be a non-empty git rev' };
+            const files = changedFiles(root, rev);
+            if (files === null) return { status: 'error', error: `cannot resolve rev '${rev}' in ${root}` };
+            const state = graphState(root);
+            return withGraph(root, (g) =>
+                args['untested_only'] === true
+                    ? { ...untested(g, files, state), changed_files: files.length }
+                    : { ...impact(g, files, state, num(args, 'depth', 2), isTestFile), changed_files: files.length },
+            );
+        },
+    },
+
+    graph_tests_for: {
+        name: 'graph_tests_for',
+        side_effect: 'ro',
+        description:
+            'Which test files exercise a symbol, derived from a test file importing ' +
+            'it or its module. Empty means no test imports it — a finding, not an error.',
+        input_schema: {
+            type: 'object',
+            required: ['symbol'],
+            properties: {
+                symbol: { type: 'string', description: 'Node id `<relpath>#<sym>`, label, or free text.' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const symbol = str(args, 'symbol');
+            if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
+            const state = graphState(root);
+            return withGraph(root, (g) => ({ ...testsFor(g, symbol, state) }));
+        },
+    },
+
+    graph_dead: {
+        name: 'graph_dead',
+        side_effect: 'ro',
+        description:
+            'Symbols with no accepted reference that no declared entry point names. ' +
+            'REFUSES (status `refused`) while a source is unreadable: with no ' +
+            'exportedness recorded, an exported-but-unimported symbol is ' +
+            'indistinguishable from a dead one. Never a deletion recommendation.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                entry_points: {
+                    type: 'string',
+                    description: 'Path under this root to a newline-separated id/label list; `#` comments ok.',
+                },
+                accept_missing_exports: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Answer anyway, accepting the gap. Never a default.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const state = graphState(root);
+            const listArg = str(args, 'entry_points');
+            let sources = repoEntryPoints(root);
+            if (listArg !== '') {
+                // REALPATH containment, matching the sibling pattern in
+                // `tools.ts` rather than reimplementing a weaker one — an
+                // independent review found this check using `path.resolve` +
+                // `startsWith`, which a symlink inside the root walks straight
+                // through, in the same change that extracted `resolvePath` for
+                // reuse. `fs.readFileSync` would then follow the link, and
+                // because the file's lines used to be echoed back in the
+                // response (see `entry_count` below) that was an
+                // arbitrary-file-read path.
+                const abs = resolvePath(path.resolve(root, listArg));
+                const rootReal = resolvePath(path.resolve(root));
+                if (abs !== rootReal && !abs.startsWith(rootReal + path.sep)) {
+                    return { status: 'error', error: `path escapes consumer_root: ${abs}` };
+                }
+                if (!fs.existsSync(abs)) return { status: 'error', error: `entry-point list not found: ${listArg}` };
+                sources = [
+                    ...sources.map((s) =>
+                        s.name === 'exports'
+                            ? { ...s, status: 'read' as const, detail: `supplied by ${listArg}`, entries: [] }
+                            : s,
+                    ),
+                    entryPointsFromFile(abs),
+                ];
+            }
+            return withGraph(root, (g) => {
+                const r = dead(g, sources, state, {
+                    acceptMissingExports: args['accept_missing_exports'] === true,
+                });
+                // The `entries` arrays are NOT returned. On this repository they
+                // are ~2,595 identifier strings — an unbounded per-call payload
+                // beside the standing-cost row this change itself adds — and
+                // returning a file the caller named is what made the
+                // containment check above a read primitive. A count answers the
+                // question a caller actually has ("was this source read, and did
+                // it have anything in it") without shipping the contents.
+                return {
+                    ...r,
+                    sources: r.sources.map((srcRow) => ({
+                        name: srcRow.name,
+                        status: srcRow.status,
+                        ...(srcRow.detail === undefined ? {} : { detail: srcRow.detail }),
+                        entry_count: srcRow.entries.length,
+                    })),
+                };
+            });
+        },
+    },
+
+    graph_query: {
+        name: 'graph_query',
+        side_effect: 'ro',
+        description:
+            "A symbol's direct outgoing relations — calls, imports, uses, inherits — " +
+            'each line carrying its confidence and resolution mechanism. For "what ' +
+            'does this touch" before reading a file.',
+        input_schema: {
+            type: 'object',
+            required: ['symbol'],
+            properties: {
+                symbol: { type: 'string', description: 'Node id, label, or free text.' },
+                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const symbol = str(args, 'symbol');
+            if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
+            const staleness = graphState(root);
+            return withGraph(root, (g) => ({
+                staleness,
+                ...graphQueryVerb(g, symbol, num(args, 'budget', 1500)),
+            }));
+        },
+    },
+
+    graph_path: {
+        name: 'graph_path',
+        side_effect: 'ro',
+        description:
+            'The shortest relation chain between two symbols, direction preserved. ' +
+            'Answers "how does A reach B" without reading the files between. ' +
+            '`(no path found)` when unconnected is an answer.',
+        input_schema: {
+            type: 'object',
+            required: ['from', 'to'],
+            properties: {
+                from: { type: 'string', description: 'Start node id, label, or free text.' },
+                to: { type: 'string', description: 'Goal node id, label, or free text.' },
+                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const from = str(args, 'from');
+            const to = str(args, 'to');
+            if (from === '' || to === '') return { status: 'error', error: 'from and to must be non-empty strings' };
+            const staleness = graphState(root);
+            return withGraph(root, (g) => ({
+                staleness,
+                ...graphPathVerb(g, from, to, num(args, 'budget', 1500)),
+            }));
+        },
+    },
+};

package/src/scripts/mcp_server/path_util.ts

@@ -0,0 +1,31 @@
+/**
+ * Two string/path helpers extracted from `tools.ts`.
+ *
+ * They are generic — a whitespace trim and a tolerant realpath — and `tools.ts`
+ * sits ~525 lines past the 1500-line ceiling `check_source_size_budget`
+ * enforces as a shrink-only ratchet, so every line there costs one unit of
+ * excess and the gate names re-pinning the baseline a defect rather than a fix.
+ * Moving them here pays for the graph-tool registration that arrives with
+ * `road-to-a-graph-that-is-shipped` 4.1, and puts them in a file where their
+ * prose is free.
+ *
+ * They are imported under their original underscore-prefixed names, so the
+ * 28 call sites in `tools.ts` are unchanged — a rename would have made a
+ * two-function move read as a sweep.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Mirror Python `str.strip()` (also strips the same Unicode whitespace set we care about here). */
+export function strip(s: string): string {
+    return s.replace(/^\s+/, '').replace(/\s+$/, '');
+}
+
+/** Mirror Python `Path(...).resolve()` — absolutize + realpath, tolerating a missing tail. */
+export function resolvePath(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return path.resolve(p);
+    }
+}