ucn 4.0.1 → 4.1.0

package/languages/rust.js

@@ -12,6 +12,7 @@ const {
     parseStructuredParams,
     extractRustDocstring,
     visitNameNodes,
+    sameNode,
 } = require('./utils');
 const { PARSE_OPTIONS, safeParse } = require('./index');
 
@@ -38,11 +39,13 @@ function extractReturnType(node) {
  * Extract Rust parameters
  */
 function extractRustParams(paramsNode) {
+    // Distinguish "we have no node" (genuinely unknown) from "node is empty".
+    // Returning '...' for empty parens conflated zero-param functions with
+    // unknown signatures in JSON output (fix #238; the shared
+    // utils.extractParams already had this fix).
     if (!paramsNode) return '...';
     const text = paramsNode.text;
-    let params = text.replace(/^\(|\)$/g, '').trim();
-    if (!params) return '...';
-    return params;
+    return text.replace(/^\(|\)$/g, '').trim();
 }
 
 /**
@@ -659,11 +662,17 @@ function extractStructFields(structNode, codeOrLines) {
             const typeNode = field.childForFieldName('type');
 
             if (nameNode) {
+                // Record the field's own visibility (pub / pub(crate) / ...) so
+                // export listings can judge members per-symbol (fix #241 —
+                // pub fields were invisible to fileExports, and private fields
+                // used to leak in via name collision with file-level exports).
+                const visibility = extractVisibility(field.text);
                 fields.push({
                     name: nameNode.text,
                     startLine,
                     endLine,
                     memberType: 'field',
+                    ...(visibility && { modifiers: [visibility] }),
                     ...(typeNode && { fieldType: typeNode.text })
                 });
             }
@@ -769,13 +778,17 @@ function extractTraitMembers(traitNode, codeOrLines) {
                 const returnType = extractReturnType(child);
                 const hasSelf = paramsNode && paramsNode.text.includes('self');
 
+                // Rust vocabulary (fix #248): trait members carry the trait's
+                // OWN visibility — a method of a private trait is not `pub`,
+                // and 'public' is not a Rust modifier ('pub'/'pub(crate)'/...).
+                const traitVisibility = extractVisibility(traitNode.text);
                 members.push({
                     name: nameNode.text,
                     startLine,
                     endLine,
                     memberType: 'method',
                     isMethod: true,
-                    modifiers: ['public'], // Trait methods are implicitly public
+                    modifiers: traitVisibility ? [traitVisibility] : [],
                     ...(paramsNode && { params: extractRustParams(paramsNode) }),
                     ...(paramsNode && { paramsStructured: parseStructuredParams(paramsNode, 'rust') }),
                     ...(returnType && { returnType }),
@@ -822,9 +835,17 @@ function extractImplMembers(implNode, codeOrLines, typeName) {
                 const inCfgTest = _isInsideCfgTestModule(child, Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n'));
                 const modifiers = [];
                 if (visibility) modifiers.push(visibility);
+                // Function qualifiers, same vocabulary as free functions
+                // (fix #248: `pub async fn get` rendered as `pub get(...)`;
+                // const/unsafe methods had no machine-readable qualifier).
+                if (firstLine.includes('async ')) modifiers.push('async');
+                if (firstLine.includes('unsafe ')) modifiers.push('unsafe');
+                if (firstLine.includes('const fn')) modifiers.push('const');
+                if (firstLine.includes('extern ')) modifiers.push('extern');
                 for (const attr of attributes) modifiers.push(attr);
                 if (inCfgTest) modifiers.push('cfg_test_module');
 
+                const memberGenerics = extractGenerics(child);
                 members.push({
                     name: nameNode.text,
                     params: extractRustParams(paramsNode),
@@ -837,7 +858,10 @@ function extractImplMembers(implNode, codeOrLines, typeName) {
                     modifiers,
                     ...(typeName && { receiver: typeName }),  // All impl members get receiver for findMethodsForType
                     ...(returnType && { returnType }),
-                    ...(docstring && { docstring })
+                    ...(docstring && { docstring }),
+                    // Method-level type params (fix #229): generic-param receiver
+                    // types inside the method resolve against this declaration.
+                    ...(memberGenerics && { generics: memberGenerics })
                 });
             }
         }
@@ -1916,17 +1940,18 @@ function findExportsInCode(code, parser) {
  * @param {string} code - Source code
  * @param {string} name - Symbol name to find
  * @param {object} parser - Tree-sitter parser instance
+ * @param {object} [tree] - Pre-parsed tree (per-operation cache); parsed here when absent
  * @returns {Array<{line: number, column: number, usageType: string}>}
  */
 function _indexInParent(node, parent) {
     for (let i = 0; i < parent.childCount; i++) {
-        if (parent.child(i) === node) return i;
+        if (sameNode(parent.child(i), node)) return i;
     }
     return -1;
 }
 
-function findUsagesInCode(code, name, parser) {
-    const tree = parseTree(parser, code);
+function findUsagesInCode(code, name, parser, tree) {
+    tree = tree || parseTree(parser, code);
     const usages = [];
 
     visitNameNodes(tree, code, name, (node) => {
@@ -1961,40 +1986,69 @@ function findUsagesInCode(code, name, parser) {
             }
             // Call: name()
             else if (parent.type === 'call_expression' &&
-                     parent.childForFieldName('function') === node) {
+                     sameNode(parent.childForFieldName('function'), node)) {
                 usageType = 'call';
             }
             // Scoped call: Type::method() — only the LAST segment is the callee;
             // the path qualifier (Type in Type::method()) is a type reference,
-            // not a call of Type
+            // not a call of Type. The qualifier IS the receiver — without it,
+            // --class-name scoping could never match associated-function calls
+            // (fix #244: `Kit::make()` invisible to `tests make --class-name Kit`).
             else if (parent.type === 'scoped_identifier') {
                 const grandparent = parent.parent;
-                if (grandparent && grandparent.type === 'call_expression' &&
-                    grandparent.childForFieldName('function') === parent &&
-                    parent.childForFieldName('name') === node) {
+                const isDirectCall = grandparent && grandparent.type === 'call_expression' &&
+                    sameNode(grandparent.childForFieldName('function'), parent);
+                // Turbofish on a scoped path: Type::<T>::m() wraps the path in
+                // generic_function before the call_expression.
+                const isTurbofishCall = grandparent && grandparent.type === 'generic_function' &&
+                    grandparent.parent && grandparent.parent.type === 'call_expression' &&
+                    sameNode(grandparent.parent.childForFieldName('function'), grandparent);
+                if ((isDirectCall || isTurbofishCall) &&
+                    sameNode(parent.childForFieldName('name'), node)) {
+                    usageType = 'call';
+                    const pathNode = parent.childForFieldName('path');
+                    if (pathNode) {
+                        const segs = pathNode.text.split('::');
+                        const receiver = segs[segs.length - 1];
+                        if (receiver) {
+                            usages.push({ line, column, usageType, receiver });
+                            return true;
+                        }
+                    }
+                }
+            }
+            // Turbofish call on a bare name: f::<T>() — the identifier's parent
+            // is generic_function, the call wraps that (fix #244: classified
+            // 'reference', so the account confirmed the edge while the
+            // coverage scan reported the function uncovered).
+            else if (parent.type === 'generic_function' &&
+                     sameNode(parent.childForFieldName('function'), node)) {
+                const gp = parent.parent;
+                if (gp && gp.type === 'call_expression' &&
+                    sameNode(gp.childForFieldName('function'), parent)) {
                     usageType = 'call';
                 }
             }
             // Macro invocation: name!
             else if (parent.type === 'macro_invocation') {
                 const macroNode = parent.childForFieldName('macro');
-                if (macroNode === node) {
+                if (sameNode(macroNode, node)) {
                     usageType = 'call';
                 }
             }
             // Definition: fn name
             else if (parent.type === 'function_item' &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'definition';
             }
             // Definition: struct name
             else if (parent.type === 'struct_item' &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'definition';
             }
             // Definition: enum name
             else if (parent.type === 'enum_item' &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'definition';
             }
             // Definition: impl for Type
@@ -2003,7 +2057,7 @@ function findUsagesInCode(code, name, parser) {
             }
             // Definition: type alias
             else if (parent.type === 'type_item' &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'definition';
             }
             // Definition: let binding
@@ -2013,22 +2067,22 @@ function findUsagesInCode(code, name, parser) {
             }
             // Definition: const/static
             else if ((parent.type === 'const_item' || parent.type === 'static_item') &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'definition';
             }
             // Definition: parameter name (not the type)
             else if (parent.type === 'parameter' &&
-                     parent.childForFieldName('pattern') === node) {
+                     sameNode(parent.childForFieldName('pattern'), node)) {
                 usageType = 'definition';
             }
             // Struct expression: Type { field: value }
             else if (parent.type === 'struct_expression' &&
-                     parent.childForFieldName('name') === node) {
+                     sameNode(parent.childForFieldName('name'), node)) {
                 usageType = 'call';
             }
             // Method call: obj.name()
             else if (parent.type === 'field_expression' &&
-                     parent.childForFieldName('field') === node) {
+                     sameNode(parent.childForFieldName('field'), node)) {
                 const grandparent = parent.parent;
                 if (grandparent && grandparent.type === 'call_expression') {
                     usageType = 'call';
@@ -2079,11 +2133,17 @@ function findUsagesInCode(code, name, parser) {
 
         // Filter out enum variant references: Boundary::Grid is NOT a usage of Grid struct
         // If our node is the NAME (right side) of a scoped_identifier/scoped_type_identifier,
-        // and the PATH (left side) is a different Capitalized type, it's likely an enum variant
-        if (parent && (parent.type === 'scoped_identifier' || parent.type === 'scoped_type_identifier')) {
+        // and the PATH (left side) is a different Capitalized type, it's likely an enum variant.
+        // Never a CALL site (fix #234, campaign G2-rust BUG-1): the scoped-call
+        // branch classified `DataService::with_defaults()` as a call, and this
+        // filter then swallowed it — usages reported '0 calls' for every
+        // path-qualified Type::method() invocation, the exact answer that
+        // invites deleting a live function.
+        if (usageType !== 'call' &&
+            parent && (parent.type === 'scoped_identifier' || parent.type === 'scoped_type_identifier')) {
             const nameField = parent.childForFieldName('name');
             const pathField = parent.childForFieldName('path');
-            if (nameField === node && pathField) {
+            if (sameNode(nameField, node) && pathField) {
                 const pathText = pathField.text;
                 // If path is a Capitalized identifier different from our target, it's Type::Variant
                 // Skip module paths (lowercase), self/Self/super/crate keywords
@@ -2120,7 +2180,10 @@ function getEntryPointKind(symbol) {
     // Functions inside #[cfg(test)] mod blocks — test-only code, even if they
     // lack a direct #[test] attribute (e.g. shared helpers in `mod tests`).
     if (m.includes('cfg_test_module')) return 'test';
-    if (symbol.name === 'main') return 'main';
+    // Only the FREE function fn main() is the binary entry — an impl method
+    // named `main` is an ordinary method (fix #243; it was never audited by
+    // deadcode and entrypoints listed it as runtime).
+    if (symbol.name === 'main' && !symbol.className && !symbol.receiver) return 'main';
     // Trait-impl methods are framework entry points (invoked by trait holder).
     if (symbol.isMethod && symbol.className && symbol.traitImpl) return 'framework';
     return null;

package/languages/utils.js

@@ -11,8 +11,11 @@
  */
 function traverseTree(node, callback, options) {
     if (callback(node) === false) return;
-    for (let i = 0; i < node.namedChildCount; i++) {
-        traverseTree(node.namedChild(i), callback, options);
+    // Single batched native call per node — namedChildCount + N × namedChild(i)
+    // costs N+1 native round-trips for the same children.
+    const children = node.namedChildren;
+    for (let i = 0; i < children.length; i++) {
+        traverseTree(children[i], callback, options);
     }
     if (options?.onLeave) {
         options.onLeave(node);
@@ -123,12 +126,20 @@ function parseJSParam(param, info) {
             info.default = valueNode.text;
             info.optional = true;
         } else if (!info.rest) {
-            // Also check for bare number/string/etc. children as defaults
+            // Also check for bare number/string/etc. children as defaults.
+            // TS parameter-property modifiers (private/protected/public/
+            // readonly/override) and parameter decorators (@Inject()) are
+            // NOT defaults (fix #230 — `constructor(protected config:
+            // Config)` used to report default 'protected', optional true,
+            // wrecking expectedArgs.min and the signature display).
+            const NON_DEFAULT_PARAM_CHILDREN = new Set([
+                'identifier', 'type_annotation', 'rest_pattern',
+                'accessibility_modifier', 'override_modifier', 'readonly', 'decorator',
+            ]);
             for (let i = 0; i < param.namedChildCount; i++) {
                 const child = param.namedChild(i);
                 if (child !== patternNode && child !== (typeNode && typeNode.parent === param ? typeNode : null) &&
-                    child.type !== 'type_annotation' && child.type !== 'rest_pattern' &&
-                    !['identifier', 'type_annotation'].includes(child.type)) {
+                    !NON_DEFAULT_PARAM_CHILDREN.has(child.type)) {
                     // This is likely a default value node
                     info.default = child.text;
                     info.optional = true;
@@ -683,8 +694,10 @@ function _buildNodeList(rootNode) {
         const idx = nodes.length;
         nodes.push(node);
         subtreeEnds.push(0);
-        for (let i = 0; i < node.namedChildCount; i++) {
-            collect(node.namedChild(i));
+        // Batched children read — one native call instead of N+1 (see traverseTree)
+        const children = node.namedChildren;
+        for (let i = 0; i < children.length; i++) {
+            collect(children[i]);
         }
         subtreeEnds[idx] = nodes.length;
     }
@@ -950,7 +963,22 @@ function extractSprintfPrefix(callNode) {
     return { value: hasFmt ? (literal + '*') : literal, interp: hasFmt };
 }
 
+
+/**
+ * Stable node equality (fix #233): tree-sitter node WRAPPERS are not
+ * reference-stable — `parent.child(i) === node` can return false for the
+ * same underlying node once a tree has been walked by an earlier operation
+ * (the CI macro-flake root cause: assert_eq!-wrapped calls flipped
+ * 'call'→'reference' on the second index build in a process because
+ * _indexInParent returned -1). `.id` is node-tree-sitter's stable native
+ * node identity — compare that, never the wrapper reference.
+ */
+function sameNode(a, b) {
+    return !!a && !!b && (a === b || a.id === b.id);
+}
+
 module.exports = {
+    sameNode,
     traverseTree,
     traverseTreeCached,
     visitNameNodes,

package/mcp/server.js

@@ -189,6 +189,7 @@ const TOOL_DESCRIPTION = `Code intelligence toolkit for AI agents. Extract speci
 TOP 5 (covers 90% of tasks): about, impact, trace, find, deadcode
 
 QUICK GUIDE — choosing the right command:
+  New/unfamiliar repo → orient (size, top dirs, hot functions, entry points, trust — run FIRST)
   Understand a symbol → about (everything), context (callers/callees only), smart (code + called functions inline)
   Before modifying    → impact (all call sites with args), verify (signature check), plan (preview refactor)
   Execution flow      → trace (function call tree) or graph (file imports/exports)
@@ -241,13 +242,22 @@ REFACTORING:
 
 DIAGNOSTICS:
 - doctor: Index health/coverage report — file/symbol counts, language breakdown, dynamic-import / eval / reflection blind spots, parse failures, and a verdict (HIGH/MEDIUM/LOW trust). Use deep=true to also sample resolution coverage and bucket edges by confidence. Use in= to scope to a subtree.
+- orient: One-screen repo orientation for a codebase you just entered: size + language mix, densest directories, most-called functions, entry-point counts, and the trust verdict. Best FIRST command in a new repo.
 
 OTHER:
 - typedef <name>: Find type definitions matching a name: interfaces, enums, structs, traits, type aliases. See field shapes, required methods, or enum values.
 - stacktrace: Parse a stack trace, show source context per frame. Requires stack param. Handles JS, Python, Go, Rust, Java formats.
 - api: Public API surface of project or file: all exported/public symbols with signatures. Use to understand what a library exposes. Pass file to scope to one file. Python needs __all__; use toc instead.
 - stats: Quick project stats: file counts, symbol counts, lines of code by language and symbol type. Use functions=true for per-function line counts sorted by size (complexity audit). Set hot=true with top=N for the most-called functions (project orientation primitive).
-- audit_async: Find async calls inside async functions that are likely missing await (probable bugs). JS/TS/Python only. Filter with file/exclude/limit.` + generateMcpParamSection();
+- audit_async: Find async calls inside async functions that are likely missing await (probable bugs). JS/TS/Python only. Filter with file/exclude/limit.
+
+READING OUTPUT (trust contract):
+- Caller/impact answers PARTITION every text occurrence of the symbol — nothing is silently hidden. CONFIRMED entries carry binding/receiver/import evidence (safe to act on). UNVERIFIED entries are call-syntax matches without evidence, each with a reason — treat as possible callers before a breaking change. The ACCOUNT line reconciles the arithmetic; "0 unaccounted" means the partition is complete.
+- A CONFIRMED(0) + UNVERIFIED(0) answer with 0 unaccounted and no WARNING is a trustworthy zero: the symbol genuinely has no callers.
+- WARNING lines list unparsed files containing the symbol — their lines were NOT analyzed; fall back to text search there.
+- verify arg-checks and plan plans CONFIRMED sites only; their UNVERIFIED CALL SITES sections list candidates to review manually. check reports "N callers (+M unverified)" per changed function.
+- context/smart/trace also account the callee side (CALLEE ACCOUNT line + unverified callees with reasons).
+- Advisory commands (related, example, stacktrace, endpoints bridge=true) mark output "Advisory:" — ranked heuristics, not verified claims. Every other listed answer is contract-backed.` + generateMcpParamSection();
 
 server.registerTool(
     'ucn',
@@ -261,8 +271,8 @@ server.registerTool(
             exclude: z.string().optional().describe('Comma-separated patterns to exclude (e.g. "test,mock,vendor")'),
             include_tests: z.boolean().optional().describe('Include test files in results (excluded by default)'),
             exclude_tests: z.boolean().optional().describe('Exclude test files from results. Used by entrypoints (where tests are included by default).'),
-            include_methods: z.boolean().optional().describe('Include obj.method() calls in trace/blast/smart/verify (implied for about/context/impact — method calls tiered by receiver evidence)'),
-            include_uncertain: z.boolean().optional().describe('Include uncertain matches in smart/verify (implied for about/context/impact/trace/blast/reverse_trace/affected_tests — unverified candidates always shown, tiered)'),
+            include_methods: z.boolean().optional().describe('Include obj.method() callee expansion in trace/blast. No effect on about/context/impact/verify — method calls are always analyzed and tiered by receiver evidence'),
+            include_uncertain: z.boolean().optional().describe('No effect on tiered commands (about/context/impact/trace/blast/reverse_trace/affected_tests/verify/smart) — unverified candidates are always shown with reasons'),
             expand_unverified: z.boolean().optional().describe('blast/reverse_trace: follow unverified caller edges in the tree — downstream nodes are marked as unverified chains (possible, not confirmed, impact)'),
             min_confidence: z.number().min(0).max(1).optional().describe('Minimum confidence threshold (0.0-1.0) to filter caller/callee edges'),
             show_confidence: z.boolean().optional().describe('Show confidence scores per edge (default: true). Set false to hide.'),
@@ -302,6 +312,7 @@ server.registerTool(
             all: z.boolean().optional().describe('Show all results (expand truncated sections). Applies to about, toc, related, trace, and others.'),
             top_level: z.boolean().optional().describe('Show only top-level functions in toc (exclude nested/indented)'),
             class_name: z.string().optional().describe('Class name to scope method analysis (e.g. "MarketDataFetcher" for close)'),
+            line: z.number().int().positive().optional().describe('Definition line pin — resolves the symbol defined at this exact line (the middle component of a file:line:name handle). Disambiguates same-file same-name definitions.'),
             limit: z.number().int().positive().max(1000000).optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, toc --detailed. Must be a positive integer.'),
             max_files: z.number().int().positive().max(10000000).optional().describe('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.'),
             max_chars: z.number().int().positive().max(10000000).optional().describe('Max output chars before truncation. Targeted commands (about, context, smart, etc.): 10K default. Broad commands (toc, entrypoints, deadcode, etc.): 3K default. Max: 100K. Use all=true to bypass all caps.'),
@@ -376,6 +387,19 @@ server.registerTool(
         const te = strippedNote
             ? (msg) => toolError(msg + strippedNote)
             : toolError;
+        // Translate CLI flag syntax in execute-layer notes to MCP param
+        // syntax — the deadcode exported/decorated hints were already
+        // param-styled, but limit/depth/truncation notes leaked
+        // '--limit N' / '--max-files N' / '--all' at this surface.
+        const mn = (note) => note && note
+            .replace(/--limit N\b/g, 'limit=<n>')
+            .replace(/--max-files N\b/g, 'max_files=<n>')
+            .replace(/--depth=N\b/g, 'depth=<n>')
+            .replace(/--detailed\b/g, 'detailed=true')
+            .replace(/--all\b/g, 'all=true')
+            .replace(/--expand-unverified\b/g, 'expand_unverified=true')
+            .replace(/--include-uncertain\b/g, 'include_uncertain=true')
+            .replace(/--(\w[\w-]*)/g, (_m, f) => f.replace(/-/g, '_'));
 
         let index = null; // Track for post-command cache save
         try {
@@ -394,8 +418,9 @@ server.registerTool(
                 let aboutText = output.formatAbout(result, {
                     allHint: 'Repeat with all=true to show all.',
                     showConfidence: ep.showConfidence !== false,
+                    compact: ep.compact,
                 });
-                if (note) aboutText += '\n\n' + note;
+                if (note) aboutText += '\n\n' + mn(note);
                 return tr(aboutText);
             }
 
@@ -406,10 +431,11 @@ server.registerTool(
                 const { text, expandable } = output.formatContext(ctx, {
                     expandHint: 'Use expand command with item number to see code for any item.',
                     showConfidence: ep.showConfidence !== false,
+                    compact: ep.compact,
                 });
                 expandCacheInstance.save(index.root, ep.name, ep.file, expandable);
                 let ctxText = text;
-                if (note) ctxText += '\n\n' + note;
+                if (note) ctxText += '\n\n' + mn(note);
                 return tr(ctxText);
             }
 
@@ -417,8 +443,8 @@ server.registerTool(
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'impact', ep);
                 if (!ok) return te(error);
-                let impactText = output.formatImpact(result);
-                if (note) impactText += '\n\n' + note;
+                let impactText = output.formatImpact(result, { compact: ep.compact });
+                if (note) impactText += '\n\n' + mn(note);
                 return tr(impactText);
             }
 
@@ -429,7 +455,7 @@ server.registerTool(
                 let blastText = output.formatBlast(result, {
                     allHint: 'Set depth to expand all children.',
                 });
-                if (note) blastText += '\n\n' + note;
+                if (note) blastText += '\n\n' + mn(note);
                 return tr(blastText);
             }
 
@@ -438,7 +464,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'smart', ep);
                 if (!ok) return te(error);
                 let smartText = output.formatSmart(result);
-                if (note) smartText += '\n\n' + note;
+                if (note) smartText += '\n\n' + mn(note);
                 return tr(smartText);
             }
 
@@ -450,7 +476,7 @@ server.registerTool(
                     allHint: 'Set depth to expand all children.',
                     methodsHint: 'Note: obj.method() calls excluded. Use include_methods=true to include them.'
                 });
-                if (note) traceText += '\n\n' + note;
+                if (note) traceText += '\n\n' + mn(note);
                 return tr(traceText);
             }
 
@@ -461,7 +487,7 @@ server.registerTool(
                 let rtText = output.formatReverseTrace(result, {
                     allHint: 'Set depth to expand all children.',
                 });
-                if (note) rtText += '\n\n' + note;
+                if (note) rtText += '\n\n' + mn(note);
                 return tr(rtText);
             }
 
@@ -480,7 +506,7 @@ server.registerTool(
                     all: ep.all || false, top: ep.top,
                     allHint: 'Repeat with all=true to show all.'
                 });
-                if (note) relText += '\n\n' + note;
+                if (note) relText += '\n\n' + mn(note);
                 return tr(relText);
             }
 
@@ -498,6 +524,13 @@ server.registerTool(
                 return tr(output.formatDoctor(result));
             }
 
+            case 'orient': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error } = execute(index, 'orient', ep);
+                if (!ok) return te(error);
+                return tr(output.formatOrient(result));
+            }
+
             case 'check': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'check', ep);
@@ -511,8 +544,14 @@ server.registerTool(
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'find', ep);
                 if (!ok) return te(error);
-                let text = output.formatFind(result, ep.name, ep.top);
-                if (note) text += '\n\n' + note;
+                // Same formatter as every other surface (fix #250 — the
+                // legacy formatFind had a different default limit, no stable
+                // file:line:name handles, no confidence markers, and
+                // silently ignored all/depth/compact).
+                let text = output.formatFindDetailed(result, ep.name, {
+                    depth: ep.depth, top: ep.top, all: ep.all, compact: ep.compact,
+                });
+                if (note) text += '\n\n' + mn(note);
                 return tr(text);
             }
 
@@ -520,8 +559,8 @@ server.registerTool(
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'usages', ep);
                 if (!ok) return te(error);
-                let text = output.formatUsages(result, ep.name);
-                if (note) text += '\n\n' + note;
+                let text = output.formatUsages(result, ep.name, { compact: ep.compact });
+                if (note) text += '\n\n' + mn(note);
                 return tr(text);
             }
 
@@ -532,7 +571,7 @@ server.registerTool(
                 let text = output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 });
-                if (note) text += '\n\n' + note;
+                if (note) text += '\n\n' + mn(note);
                 return tr(text);
             }
 
@@ -546,7 +585,7 @@ server.registerTool(
                 } else {
                     searchText = output.formatSearch(result, ep.term);
                 }
-                if (note) searchText += '\n\n' + note;
+                if (note) searchText += '\n\n' + mn(note);
                 return tr(searchText);
             }
 
@@ -555,7 +594,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'tests', ep);
                 if (!ok) return te(error);
                 let testsText = output.formatTests(result, ep.name);
-                if (note) testsText += '\n\n' + note;
+                if (note) testsText += '\n\n' + mn(note);
                 return tr(testsText);
             }
 
@@ -564,7 +603,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'affectedTests', ep);
                 if (!ok) return te(error);
                 let atText = output.formatAffectedTests(result, { all: ep.all });
-                if (note) atText += '\n\n' + note;
+                if (note) atText += '\n\n' + mn(note);
                 return tr(atText);
             }
 
@@ -576,10 +615,10 @@ server.registerTool(
                 let dcText = output.formatDeadcode(result, {
                     top: ep.top || 0,
                     decoratedHint: !ep.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use include_decorated=true to include them.` : undefined,
-                    exportedHint: !ep.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use include_exported=true to audit them.` : undefined,
+                    exportedHint: !ep.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use include_exported=true to audit them.` : undefined,
                     externalContractHint: !ep.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use include_exported=true to include them.` : undefined
                 });
-                if (dcNote) dcText += '\n\n' + dcNote;
+                if (dcNote) dcText += '\n\n' + mn(dcNote);
                 return tr(dcText);
             }
 
@@ -588,7 +627,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'entrypoints', ep);
                 if (!ok) return te(error);
                 let epText = output.formatEntrypoints(result);
-                if (note) epText += '\n\n' + note;
+                if (note) epText += '\n\n' + mn(note);
                 return tr(epText);
             }
 
@@ -597,7 +636,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'endpoints', ep);
                 if (!ok) return te(error);
                 let endText = output.formatEndpoints(result, { bridge: result._bridge, unmatched: result._unmatched });
-                if (note) endText += '\n\n' + note;
+                if (note) endText += '\n\n' + mn(note);
                 return tr(endText);
             }
 
@@ -664,7 +703,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'diffImpact', ep);
                 if (!ok) return te(error);
                 let diText = output.formatDiffImpact(result, { all: ep.all });
-                if (note) diText += '\n\n' + note;
+                if (note) diText += '\n\n' + mn(note);
                 return tr(diText);
             }
 
@@ -689,7 +728,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'api', ep);
                 if (!ok) return te(error);
                 let apiText = output.formatApi(result, ep.file || '.');
-                if (note) apiText += '\n\n' + note;
+                if (note) apiText += '\n\n' + mn(note);
                 return tr(apiText);
             }
 
@@ -698,7 +737,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'stats', ep);
                 if (!ok) return te(error);
                 let statsText = output.formatStats(result, { top: ep.top || 0 });
-                if (note) statsText += '\n\n' + note;
+                if (note) statsText += '\n\n' + mn(note);
                 return tr(statsText);
             }
 
@@ -707,7 +746,7 @@ server.registerTool(
                 const { ok, result, error, note } = execute(index, 'auditAsync', ep);
                 if (!ok) return te(error);
                 let text = output.formatAuditAsync(result);
-                if (note) text += '\n\n' + note;
+                if (note) text += '\n\n' + mn(note);
                 return tr(text);
             }
 
@@ -722,7 +761,7 @@ server.registerTool(
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
                     if (typeof check !== 'string') return check;
                 }
-                const fnText = (note ? note + '\n\n' : '') + output.formatFnResult(result);
+                const fnText = (note ? mn(note) + '\n\n' : '') + output.formatFnResult(result);
                 return tr(fnText);
             }
 
@@ -735,7 +774,7 @@ server.registerTool(
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
                     if (typeof check !== 'string') return check;
                 }
-                const classText = (note ? note + '\n\n' : '') + output.formatClassResult(result);
+                const classText = (note ? mn(note) + '\n\n' : '') + output.formatClassResult(result);
                 return tr(classText);
             }
 
@@ -791,7 +830,9 @@ server.registerTool(
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('UCN MCP server running on stdio');
+    // Print the running version so MCP-vs-CLI drift is visible (field-report #3:
+    // a stale `npx -y ucn` cache can silently run an older engine than the CLI).
+    console.error(`UCN MCP server v${require('../package.json').version} running on stdio`);
 }
 
 main().catch(e => {