gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/cli/eval-server.js

@@ -29,6 +29,7 @@
  *   POST /shutdown     — Graceful shutdown.
  */
 import http from 'http';
+import crypto from 'node:crypto';
 import { isIPv4, isIPv6 } from 'node:net';
 import { writeSync } from 'node:fs';
 import { LocalBackend, } from '../mcp/local/local-backend.js';
@@ -146,6 +147,14 @@ export function formatContextResult(result) {
     }
     return lines.join('\n').trim();
 }
+function formatTruncationSuffix(result) {
+    const label = Array.isArray(result.truncatedByReasons)
+        ? result.truncatedByReasons.join(', ')
+        : typeof result.truncatedBy === 'string'
+            ? result.truncatedBy
+            : '';
+    return label ? ` (by ${label})` : '';
+}
 export function formatImpactResult(result) {
     if (result.error) {
         const suggestion = result.suggestion ? `\nSuggestion: ${result.suggestion}` : '';
@@ -160,6 +169,25 @@ export function formatImpactResult(result) {
     // mirroring formatContextResult, so the real impact under whichever symbol the
     // caller meant is visible on the text surface, not just in the JSON.
     if (result.status === 'ambiguous') {
+        if (result.mode === 'pdg') {
+            const shown = result.candidates?.length ?? 0;
+            const totalCandidates = result.totalCandidates ?? shown;
+            const countPhrase = totalCandidates > shown
+                ? `${totalCandidates} symbols (showing ${shown})`
+                : `${totalCandidates} symbols`;
+            const lines = [
+                `${target?.name || '?'}: AMBIGUOUS — ${countPhrase} share this name. ` +
+                    `PDG impact was not computed until the target is disambiguated. ` +
+                    `Use --uid, file_path, or kind for one authoritative PDG result.`,
+            ];
+            if (result.message)
+                lines.push(String(result.message));
+            for (const c of result.candidates || []) {
+                const score = typeof c.score === 'number' ? ` score ${c.score}` : '';
+                lines.push(`  ${c.kind} ${c.name} → ${c.filePath}:${c.line || '?'}${score}  (uid: ${c.uid})`);
+            }
+            return lines.join('\n');
+        }
         // #2129 review F11 — report the FULL match count (`totalCandidates`), not the
         // truncated `candidates[]` length; note when the candidate list is capped.
         const shown = result.candidates?.length ?? 0;
@@ -180,6 +208,176 @@ export function formatImpactResult(result) {
         }
         return lines.join('\n');
     }
+    // ─── PDG mode (mode:'pdg') ────────────────────────────────────────────
+    // KTD8 presentation half. PDG results are intra-procedural Program
+    // Dependence Graph blast radii: the single collapsed `byDepth[1]` bucket
+    // has NO call-hop depth meaning (block-hops ≠ call-hops), so we must NOT
+    // reuse the callgraph "depth N / WILL BREAK (direct)" framing, the
+    // callgraph DI/dynamic-dispatch lower-bound copy, or the confident
+    // "isolated" zero. A degraded / no-body PDG result is INCONCLUSIVE, not
+    // safe-to-refactor — it gets the explicit caveat + remediation, never an
+    // empty blast radius. Detect on `mode:'pdg'` (every PDG return path —
+    // findings, degradation, no-body, no-dependence — carries it). Ambiguous
+    // PDG results carry `status:'ambiguous'` and are handled above; they never
+    // reach here.
+    if (result.mode === 'pdg') {
+        const name = target?.name || '?';
+        const appendPdgInterproceduralSymbols = (lines) => {
+            const byDepth = result.interproceduralByDepth || result.pdgInterprocedural?.byDepth || result.byDepth || {};
+            const byDepthCounts = result.interproceduralByDepthCounts ||
+                result.pdgInterprocedural?.byDepthCounts ||
+                result.byDepthCounts ||
+                {};
+            const depthKeys = Array.from(new Set([...Object.keys(byDepthCounts), ...Object.keys(byDepth)]))
+                .map((d) => Number(d))
+                .filter((d) => Number.isFinite(d))
+                .sort((a, b) => a - b);
+            const hasReach = depthKeys.some((depth) => {
+                const items = byDepth[depth] || byDepth[String(depth)] || [];
+                const count = byDepthCounts[depth] ?? byDepthCounts[String(depth)] ?? items.length;
+                return count > 0;
+            });
+            if (!hasReach)
+                return false;
+            const totalSymbols = result.pdgInterprocedural?.impactedCount ??
+                (typeof result.impactedCount === 'number' ? result.impactedCount : 0);
+            lines.push('');
+            lines.push(`Inter-procedural symbol reach (${totalSymbols}):`);
+            for (const depth of depthKeys) {
+                const items = byDepth[depth] || byDepth[String(depth)] || [];
+                const count = byDepthCounts[depth] ?? byDepthCounts[String(depth)] ?? items.length;
+                if (count <= 0)
+                    continue;
+                lines.push(`  d=${depth} (${count})`);
+                const shown = Math.min(items.length, 12);
+                for (const item of items.slice(0, shown)) {
+                    const flags = [];
+                    if (item.unresolved)
+                        flags.push('unresolved');
+                    if (item.ambiguous)
+                        flags.push('ambiguous');
+                    const flagStr = flags.length ? ` [${flags.join(', ')}]` : '';
+                    lines.push(`    ${item.type || ''} ${item.name} → ${item.filePath}${flagStr}`);
+                }
+                if (count > shown)
+                    lines.push(`    ... and ${count - shown} more`);
+            }
+            return true;
+        };
+        // (1) Degradation — the PDG layer (or a sub-layer) is absent/unreadable.
+        // `pdgLayer` is the non-'ready' state from `pdgLayerStatus`. Print the
+        // honest remediation, NOT a zero/empty blast radius.
+        if (result.pdgLayer) {
+            const subLayer = result.missingSubLayer
+                ? ` (missing sub-layer: ${result.missingSubLayer})`
+                : '';
+            return (`${name}: PDG impact unavailable — the index has no usable PDG layer ` +
+                `[${result.pdgLayer}]${subLayer}. This is NOT "no impact". ` +
+                `Re-index with \`gitnexus analyze --pdg\` to build the control/data ` +
+                `dependence layer, or use \`--mode callgraph\` for the call-graph blast radius.` +
+                (result.note ? `\n${result.note}` : ''));
+        }
+        // (2) No-body symbol (KTD6) — interface / type alias / abstract / ambient
+        // member / one-line declaration with no CFG. Show the caveat, never
+        // "isolated / no dependencies".
+        if (result.epistemic === 'no-pdg-body') {
+            const noBodyLines = [
+                `${name}: local PDG slice not applicable to this symbol — it has no PDG body ` +
+                    `(no control/data dependence edges; e.g. an interface, type alias, ` +
+                    `abstract/ambient member, or a one-line declaration). This is NOT a ` +
+                    `confident "no impact".`,
+            ];
+            appendPdgInterproceduralSymbols(noBodyLines);
+            if (result.note)
+                noBodyLines.push(result.note);
+            return noBodyLines.join('\n');
+        }
+        // (2b) STATEMENT-ANCHORED SLICE (mode:'pdg' + line). When `criterionLine` is
+        // present the result is a statement slice: the seeded line plus the list of
+        // dependent statements (`affectedStatements: {line,filePath,text}[]`). Render
+        // those statements directly — this IS the useful output of statement mode —
+        // rather than the symbol-projection bucket below. Empty cases:
+        //   - `pdg-no-block-at-line`: the line is blank / a comment / outside the
+        //     body (no statement block) — print the steering note.
+        //   - empty `affectedStatements` with `pdg-intra-procedural`: the line has no
+        //     dependents in this direction — print the steering note.
+        // Each non-empty case also surfaces truncation honestly.
+        if (typeof result.criterionLine === 'number') {
+            const slice = Array.isArray(result.affectedStatements)
+                ? result.affectedStatements
+                : [];
+            const count = typeof result.affectedStatementCount === 'number'
+                ? result.affectedStatementCount
+                : slice.length;
+            // File anchor for the heading — the seeded statement's file (every slice
+            // statement shares the function's file). Fall back to the target's file.
+            const anchorFile = slice[0]?.filePath || target?.filePath || name;
+            if (count === 0 || slice.length === 0) {
+                // No statement block at the line, or no dependents in this direction.
+                // Print the honest note (pdg-no-block-at-line or the no-dependence note)
+                // verbatim — never an empty "isolated" headline.
+                const emptySliceLines = [
+                    `No statements ${direction}-dependent on ${anchorFile}:${result.criterionLine}.`,
+                ];
+                if (result.truncated) {
+                    const by = formatTruncationSuffix(result);
+                    emptySliceLines.push(`⚠️  Truncated${by} — the dependence slice was bounded; deeper PDG-dependent statements may exist.`);
+                }
+                appendPdgInterproceduralSymbols(emptySliceLines);
+                if (result.note)
+                    emptySliceLines.push(result.note);
+                return emptySliceLines.join('\n');
+            }
+            const slLines = [];
+            slLines.push(`Statements ${direction}-dependent on ${anchorFile}:${result.criterionLine} (${count}):`);
+            for (const s of slice) {
+                const text = typeof s.text === 'string' ? s.text : '';
+                slLines.push(`  L${s.line}: ${text}`);
+            }
+            // Truncation honesty — the slice may be a lower bound (depth or per-step
+            // LIMIT bound). Surface it the same way the symbol render does.
+            if (result.truncated) {
+                const by = formatTruncationSuffix(result);
+                slLines.push(`⚠️  Truncated${by} — the dependence slice was bounded; deeper PDG-dependent statements may exist.`);
+            }
+            appendPdgInterproceduralSymbols(slLines);
+            if (result.note) {
+                slLines.push('');
+                slLines.push(`ℹ️  ${result.note}`);
+            }
+            return slLines.join('\n').trim();
+        }
+        const pdgLines = [];
+        if (!appendPdgInterproceduralSymbols(pdgLines)) {
+            pdgLines.push(`${name} (${direction}): no inter-procedural symbols reached. ` +
+                `The local PDG statement slice may still report affectedStatements when seeded with line:<N>.`);
+        }
+        // The assembled note carries the local-PDG framing plus the unified
+        // inter-procedural symbol-reach contract; surface it verbatim so the CLI
+        // reader sees the same honesty the JSON consumer does.
+        if (result.note) {
+            pdgLines.push('');
+            pdgLines.push(`ℹ️  ${result.note}`);
+        }
+        else {
+            pdgLines.push('');
+            pdgLines.push('ℹ️  Program Dependence Graph result — statement reach is reported in affectedStatements and inter-procedural symbol reach in interproceduralByDepth/byDepth.');
+        }
+        // Honest incompleteness signals (block-attribution + truncation).
+        if (result.ambiguousProjectionCount > 0) {
+            pdgLines.push(`⚠️  ${result.ambiguousProjectionCount} block(s) could not be attributed to a ` +
+                `unique owning symbol (same-line functions) — all colliding symbols are shown.`);
+        }
+        if (result.unresolvedBlockCount > 0) {
+            pdgLines.push(`⚠️  ${result.unresolvedBlockCount} dependence block(s) map to no owning ` +
+                `Function/Method/Constructor (top-level statement / closure) — surfaced under their file.`);
+        }
+        if (result.truncated) {
+            const by = formatTruncationSuffix(result);
+            pdgLines.push(`⚠️  Truncated${by} — the dependence traversal was bounded; deeper PDG impacts may exist.`);
+        }
+        return pdgLines.join('\n').trim();
+    }
     if (total === 0) {
         // #1858 — "isolated" is a confident claim. If an interface / indirection
         // boundary is on the path, the true count is a lower bound, not zero;
@@ -317,13 +515,20 @@ function formatToolResult(toolName, result) {
 // ─── Next-Step Hints ──────────────────────────────────────────────────
 // Guide the agent to the logical next tool call.
 // Critical for tool chaining: query → context → impact → fix.
-function getNextStepHint(toolName) {
+export function getNextStepHint(toolName, result) {
     switch (toolName) {
         case 'query':
             return '\n---\nNext: Pick a symbol above and run gitnexus-context "<name>" to see all its callers, callees, and execution flows.';
         case 'context':
             return '\n---\nNext: To check what breaks if you change this, run gitnexus-impact "<name>" upstream';
         case 'impact':
+            if (result?.error ||
+                result?.status === 'ambiguous' ||
+                result?.mode === 'pdg' ||
+                result?.pdgLayer ||
+                typeof result?.criterionLine === 'number') {
+                return '';
+            }
             return '\n---\nNext: Review d=1 items first (WILL BREAK). Read the source with cat to understand the code, then make your fix.';
         case 'cypher':
             return '\n---\nNext: To explore a result symbol in depth, run gitnexus-context "<name>"';
@@ -376,6 +581,13 @@ export async function evalServerCommand(options) {
             process.exit(0);
         }, idleTimeoutSec * 1000);
     }
+    // Startup-generated shutdown token: a `POST /shutdown` must present it in the
+    // X-Shutdown-Token header. The local agent that launches the server reads it
+    // from the GITNEXUS_EVAL_SERVER_SHUTDOWN_TOKEN line on fd 1 (next to the READY
+    // signal); a client on another VM under `--host 0.0.0.0` cannot guess it, so it
+    // can no longer kill the server. (SIGINT/SIGTERM and the idle timeout still
+    // shut down locally without a token.)
+    const shutdownToken = crypto.randomBytes(24).toString('hex');
     const server = http.createServer(async (req, res) => {
         resetIdleTimer();
         try {
@@ -388,6 +600,12 @@ export async function evalServerCommand(options) {
             }
             // Shutdown
             if (req.method === 'POST' && req.url === '/shutdown') {
+                if (req.headers['x-shutdown-token'] !== shutdownToken) {
+                    res.setHeader('Content-Type', 'application/json');
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ error: 'forbidden: missing or invalid X-Shutdown-Token' }));
+                    return;
+                }
                 res.setHeader('Content-Type', 'application/json');
                 res.writeHead(200);
                 res.end(JSON.stringify({ status: 'shutting_down' }));
@@ -402,6 +620,12 @@ export async function evalServerCommand(options) {
             const toolMatch = req.url?.match(/^\/tool\/(\w+)$/);
             if (req.method === 'POST' && toolMatch) {
                 const toolName = toolMatch[1];
+                if (!EVAL_SERVER_TOOLS.has(toolName)) {
+                    res.setHeader('Content-Type', 'text/plain');
+                    res.writeHead(400);
+                    res.end(`Error: unsupported tool '${toolName}'. Supported: ${[...EVAL_SERVER_TOOLS].sort().join(', ')}`);
+                    return;
+                }
                 const body = await readBody(req);
                 let args = {};
                 if (body.trim()) {
@@ -418,7 +642,7 @@ export async function evalServerCommand(options) {
                 // Call tool, format result as text, append next-step hint
                 const result = await backend.callTool(toolName, args);
                 const formatted = formatToolResult(toolName, result);
-                const hint = getNextStepHint(toolName);
+                const hint = getNextStepHint(toolName, result);
                 res.setHeader('Content-Type', 'text/plain');
                 res.writeHead(200);
                 res.end(formatted + hint);
@@ -518,6 +742,8 @@ export async function evalServerCommand(options) {
         try {
             // Use fd 1 directly — LadybugDB captures process.stdout (#324)
             writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${displayHost}:${boundPort}\n`);
+            // The launching agent reads this to authorize POST /shutdown.
+            writeSync(1, `GITNEXUS_EVAL_SERVER_SHUTDOWN_TOKEN:${shutdownToken}\n`);
         }
         catch {
             // stdout may not be available (e.g., broken pipe)
@@ -533,6 +759,20 @@ export async function evalServerCommand(options) {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+/**
+ * Tools the eval-server exposes over HTTP — the read-only query surface the
+ * banner advertises. `LocalBackend.callTool` ALSO dispatches write-side / heavier
+ * tools (rename, shape_check, tool_map, …); the allowlist keeps a stray
+ * `POST /tool/<name>` from reaching those through this Docker/eval-harness server.
+ */
+export const EVAL_SERVER_TOOLS = new Set([
+    'query',
+    'context',
+    'impact',
+    'cypher',
+    'detect_changes',
+    'list_repos',
+]);
 export const MAX_BODY_SIZE = 1024 * 1024; // 1MB
 function readBody(req) {
     return new Promise((resolve, reject) => {

package/dist/cli/help-i18n.js

@@ -27,6 +27,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     impact: 'help.command.impact.description',
     cypher: 'help.command.cypher.description',
     'detect-changes': 'help.command.detectChanges.description',
+    check: 'help.command.check.description',
+    trace: 'help.command.trace.description',
     'eval-server': 'help.command.evalServer.description',
     group: 'help.command.group.description',
     'group create': 'help.command.group.create.description',
@@ -41,6 +43,7 @@ const COMMAND_DESCRIPTION_KEYS = {
 };
 const OPTION_DESCRIPTION_KEYS = {
     '|-V, --version': 'help.option.version',
+    'setup|-c, --coding-agent <agents>': 'help.option.setup.codingAgent',
     'analyze|-f, --force': 'help.option.analyze.force',
     'analyze|--repair-fts': 'help.option.analyze.repairFts',
     'analyze|--embeddings [limit]': 'help.option.analyze.embeddings',
@@ -64,6 +67,10 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--embedding-device <device>': 'help.option.analyze.embeddingDevice',
     'index|-f, --force': 'help.option.index.force',
     'index|--allow-non-git': 'help.option.index.allowNonGit',
+    'mcp|--http': 'help.option.mcp.http',
+    'mcp|-p, --port <port>': 'help.option.port',
+    'mcp|--host <host>': 'help.option.mcp.host',
+    'mcp|--auth-token <token>': 'help.option.mcp.authToken',
     'serve|-p, --port <port>': 'help.option.port',
     'serve|--host <host>': 'help.option.serve.host',
     'uninstall|-f, --force': 'help.option.uninstall.force',
@@ -117,6 +124,18 @@ const OPTION_DESCRIPTION_KEYS = {
     'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',
     'detect-changes|-r, --repo <name>': 'help.option.repo.target',
     'detect-changes|--branch <name>': 'help.option.branch',
+    'check|--cycles': 'help.option.check.cycles',
+    'check|--json': 'help.option.json',
+    'check|-r, --repo <name>': 'help.option.repo.target',
+    'check|--branch <name>': 'help.option.branch',
+    'trace|--from-uid <uid>': 'help.option.trace.fromUid',
+    'trace|--from-file <path>': 'help.option.trace.fromFile',
+    'trace|--to-uid <uid>': 'help.option.trace.toUid',
+    'trace|--to-file <path>': 'help.option.trace.toFile',
+    'trace|--depth <n>': 'help.option.trace.depth',
+    'trace|--include-tests': 'help.option.trace.includeTests',
+    'trace|-r, --repo <name>': 'help.option.repo.target',
+    'trace|--branch <name>': 'help.option.branch',
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',

package/dist/cli/i18n/en.d.ts

@@ -51,6 +51,7 @@ export declare const en: {
     readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
     readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
     readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
+    readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
     readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
     readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': "No changes detected.";
@@ -112,7 +113,7 @@ export declare const en: {
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
-    readonly 'help.command.mcp.description': "Start MCP server (stdio) — serves all indexed repos";
+    readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
@@ -124,8 +125,10 @@ export declare const en: {
     readonly 'help.command.query.description': "Search the knowledge graph for execution flows related to a concept";
     readonly 'help.command.context.description': "360-degree view of a code symbol: callers, callees, processes";
     readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
+    readonly 'help.command.trace.description': "Find the shortest directed path between two symbols (call + class-member edges)";
     readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
     readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+    readonly 'help.command.check.description': "Run structural checks against the indexed graph";
     readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
     readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
     readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -137,6 +140,7 @@ export declare const en: {
     readonly 'help.command.group.impact.description': "Cross-repo impact for a symbol in one member repo of a group";
     readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
     readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
+    readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
     readonly 'help.option.analyze.force': "Force full re-index even if up to date";
     readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
     readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
@@ -162,6 +166,9 @@ export declare const en: {
     readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
     readonly 'help.option.port': "Port number";
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
+    readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
+    readonly 'help.option.mcp.host': "HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.";
+    readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
@@ -198,8 +205,15 @@ export declare const en: {
     readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
     readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
     readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
+    readonly 'help.option.trace.fromUid': "Source symbol UID (zero-ambiguity lookup)";
+    readonly 'help.option.trace.fromFile': "Source file path to disambiguate common names";
+    readonly 'help.option.trace.toUid': "Target symbol UID (zero-ambiguity lookup)";
+    readonly 'help.option.trace.toFile': "Target file path to disambiguate common names";
+    readonly 'help.option.trace.depth': "Max path length in hops (default: 10)";
+    readonly 'help.option.trace.includeTests': "Traverse through test-file symbols (default: false)";
     readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
     readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+    readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
     readonly 'help.option.group.create.force': "Overwrite existing group";

package/dist/cli/i18n/en.js

@@ -51,6 +51,7 @@ export const en = {
     'tool.usage.query': 'Usage: gitnexus query <search_query>',
     'tool.usage.context': 'Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]',
     'tool.usage.impact': 'Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]',
+    'tool.usage.trace': 'Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
     'tool.usage.cypher': 'Usage: gitnexus cypher <cypher_query>',
     'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
@@ -112,7 +113,7 @@ export const en = {
     'help.command.analyze.description': 'Index a repository (full analysis)',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',
-    'help.command.mcp.description': 'Start MCP server (stdio) — serves all indexed repos',
+    'help.command.mcp.description': 'Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).',
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
@@ -124,8 +125,10 @@ export const en = {
     'help.command.query.description': 'Search the knowledge graph for execution flows related to a concept',
     'help.command.context.description': '360-degree view of a code symbol: callers, callees, processes',
     'help.command.impact.description': 'Blast radius analysis: what breaks if you change a symbol',
+    'help.command.trace.description': 'Find the shortest directed path between two symbols (call + class-member edges)',
     'help.command.cypher.description': 'Execute raw Cypher query against the knowledge graph',
     'help.command.detectChanges.description': 'Map git diff hunks to indexed symbols and affected execution flows',
+    'help.command.check.description': 'Run structural checks against the indexed graph',
     'help.command.evalServer.description': 'Start lightweight HTTP server for fast tool calls during evaluation',
     'help.command.group.description': 'Manage repository groups for cross-index impact analysis',
     'help.command.group.create.description': 'Create a new group with template group.yaml',
@@ -137,6 +140,7 @@ export const en = {
     'help.command.group.impact.description': 'Cross-repo impact for a symbol in one member repo of a group',
     'help.command.group.query.description': 'Search execution flows across all repos in a group',
     'help.command.group.contracts.description': 'Inspect Contract Registry',
+    'help.option.setup.codingAgent': 'Configure only these coding agents (comma-separated or repeatable)',
     'help.option.analyze.force': 'Force full re-index even if up to date',
     'help.option.analyze.repairFts': 'Repair/rebuild search FTS indexes without full re-analysis',
     'help.option.analyze.embeddings': 'Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.',
@@ -162,6 +166,9 @@ export const en = {
     'help.option.index.allowNonGit': 'Allow registering folders that are not Git repositories',
     'help.option.port': 'Port number',
     'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)',
+    'help.option.mcp.http': 'Serve MCP over HTTP instead of stdio (for remote clients)',
+    'help.option.mcp.host': 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.',
+    'help.option.mcp.authToken': 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.',
     'help.option.force.confirmation': 'Skip confirmation prompt',
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
@@ -198,8 +205,15 @@ export const en = {
     'help.option.impact.limit': 'Max symbols per depth level (default: 100)',
     'help.option.impact.offset': 'Skip N symbols per depth level for pagination',
     'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
+    'help.option.trace.fromUid': 'Source symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.fromFile': 'Source file path to disambiguate common names',
+    'help.option.trace.toUid': 'Target symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.toFile': 'Target file path to disambiguate common names',
+    'help.option.trace.depth': 'Max path length in hops (default: 10)',
+    'help.option.trace.includeTests': 'Traverse through test-file symbols (default: false)',
     'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
     'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
+    'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
     'help.option.group.create.force': 'Overwrite existing group',

package/dist/cli/i18n/resources.d.ts

@@ -52,6 +52,7 @@ export declare const cliResources: {
         readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
         readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
         readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
+        readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
         readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
         readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
         readonly 'tool.detectChanges.noChanges': "No changes detected.";
@@ -113,7 +114,7 @@ export declare const cliResources: {
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
-        readonly 'help.command.mcp.description': "Start MCP server (stdio) — serves all indexed repos";
+        readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
@@ -125,8 +126,10 @@ export declare const cliResources: {
         readonly 'help.command.query.description': "Search the knowledge graph for execution flows related to a concept";
         readonly 'help.command.context.description': "360-degree view of a code symbol: callers, callees, processes";
         readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
+        readonly 'help.command.trace.description': "Find the shortest directed path between two symbols (call + class-member edges)";
         readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
         readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+        readonly 'help.command.check.description': "Run structural checks against the indexed graph";
         readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
         readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
         readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -138,6 +141,7 @@ export declare const cliResources: {
         readonly 'help.command.group.impact.description': "Cross-repo impact for a symbol in one member repo of a group";
         readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
         readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
+        readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
         readonly 'help.option.analyze.force': "Force full re-index even if up to date";
         readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
         readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
@@ -163,6 +167,9 @@ export declare const cliResources: {
         readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
         readonly 'help.option.port': "Port number";
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
+        readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
+        readonly 'help.option.mcp.host': "HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.";
+        readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
@@ -199,8 +206,15 @@ export declare const cliResources: {
         readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
         readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
         readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
+        readonly 'help.option.trace.fromUid': "Source symbol UID (zero-ambiguity lookup)";
+        readonly 'help.option.trace.fromFile': "Source file path to disambiguate common names";
+        readonly 'help.option.trace.toUid': "Target symbol UID (zero-ambiguity lookup)";
+        readonly 'help.option.trace.toFile': "Target file path to disambiguate common names";
+        readonly 'help.option.trace.depth': "Max path length in hops (default: 10)";
+        readonly 'help.option.trace.includeTests': "Traverse through test-file symbols (default: false)";
         readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
         readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+        readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
         readonly 'help.option.group.create.force': "Overwrite existing group";
@@ -276,6 +290,7 @@ export declare const cliResources: {
         'tool.usage.query': string;
         'tool.usage.context': string;
         'tool.usage.impact': string;
+        'tool.usage.trace': string;
         'tool.usage.cypher': string;
         'tool.warn.unknownKind': string;
         'tool.detectChanges.noChanges': string;
@@ -349,8 +364,10 @@ export declare const cliResources: {
         'help.command.query.description': string;
         'help.command.context.description': string;
         'help.command.impact.description': string;
+        'help.command.trace.description': string;
         'help.command.cypher.description': string;
         'help.command.detectChanges.description': string;
+        'help.command.check.description': string;
         'help.command.evalServer.description': string;
         'help.command.group.description': string;
         'help.command.group.create.description': string;
@@ -362,6 +379,7 @@ export declare const cliResources: {
         'help.command.group.impact.description': string;
         'help.command.group.query.description': string;
         'help.command.group.contracts.description': string;
+        'help.option.setup.codingAgent': string;
         'help.option.analyze.force': string;
         'help.option.analyze.repairFts': string;
         'help.option.analyze.embeddings': string;
@@ -387,6 +405,9 @@ export declare const cliResources: {
         'help.option.index.allowNonGit': string;
         'help.option.port': string;
         'help.option.serve.host': string;
+        'help.option.mcp.http': string;
+        'help.option.mcp.host': string;
+        'help.option.mcp.authToken': string;
         'help.option.force.confirmation': string;
         'help.option.uninstall.force': string;
         'help.option.clean.all': string;
@@ -423,8 +444,15 @@ export declare const cliResources: {
         'help.option.impact.limit': string;
         'help.option.impact.offset': string;
         'help.option.impact.summaryOnly': string;
+        'help.option.trace.fromUid': string;
+        'help.option.trace.fromFile': string;
+        'help.option.trace.toUid': string;
+        'help.option.trace.toFile': string;
+        'help.option.trace.depth': string;
+        'help.option.trace.includeTests': string;
         'help.option.detectChanges.scope': string;
         'help.option.detectChanges.baseRef': string;
+        'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
         'help.option.group.create.force': string;