gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/mcp/local/pdg-impact.d.ts

@@ -34,8 +34,10 @@ export declare function splitCalleeIds(raw: unknown): string[];
  * Contract version of the mode:'pdg' impact result shape. A stable discriminator
  * for external MCP/agent consumers — distinct from the DB INCREMENTAL_SCHEMA_VERSION.
  * Bump on any breaking change to the PDG result fields.
+ * v2: `startLine` in the result is now 1-based display (#2380), matching the
+ * context/query/impact tools (was 0-based).
  */
-export declare const PDG_RESULT_VERSION: 1;
+export declare const PDG_RESULT_VERSION: 2;
 /** A reachable dependence block resolved to its source statement. */
 export interface PdgStatement {
     /** 1-based source line where the statement's block starts. */
@@ -105,7 +107,7 @@ export interface PdgInterproceduralImpact {
 export interface PdgImpactBaseResult extends PdgImpactParityFields {
     mode: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 1;
+    pdgResultVersion: 2;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';
     impactedCount: number;
@@ -172,7 +174,7 @@ export interface PdgImpactDegradedResult extends PdgImpactBaseResult {
 export interface PdgImpactErrorResult {
     mode?: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 1;
+    pdgResultVersion: 2;
     error: string;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';

package/dist/mcp/local/pdg-impact.js

@@ -9,6 +9,7 @@ import path from 'path';
 import { loadMeta } from '../../storage/repo-manager.js';
 import { IMPACT_MAX_DEPTH, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT } from '../tools.js';
 import { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from '../../core/ingestion/cfg/emit.js';
+import { toDisplayLine } from './line-display.js';
 import { decodeCallSummary } from '../../core/ingestion/taint/call-summary-codec.js';
 import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
 import { getProviderForFile } from '../../core/ingestion/languages/index.js';
@@ -84,8 +85,10 @@ export function splitCalleeIds(raw) {
  * Contract version of the mode:'pdg' impact result shape. A stable discriminator
  * for external MCP/agent consumers — distinct from the DB INCREMENTAL_SCHEMA_VERSION.
  * Bump on any breaking change to the PDG result fields.
+ * v2: `startLine` in the result is now 1-based display (#2380), matching the
+ * context/query/impact tools (was 0-based).
  */
-export const PDG_RESULT_VERSION = 1;
+export const PDG_RESULT_VERSION = 2;
 /**
  * FU-B-2 intra-block def→use line walk. Given a block's self REACHING_DEF
  * def→use line PAIRS (every `defLine → useLine` step decoded from the edge
@@ -519,7 +522,7 @@ function assemblePdgImpactResult(input) {
         name: s.name,
         type: s.type,
         filePath: s.filePath,
-        ...(s.startLine !== undefined ? { startLine: s.startLine } : {}),
+        ...(s.startLine !== undefined ? { startLine: toDisplayLine(s.startLine) } : {}),
         ...(s.ambiguous ? { ambiguous: true } : {}),
         ...(s.id === null ? { unresolved: true } : {}),
         pdgEvidence: (s.id === null ? 'degraded' : 'owner-projection'),

package/dist/mcp/output-budget.d.ts

@@ -0,0 +1,5 @@
+export declare const MCP_TOKEN_ESTIMATE_BYTES = 4;
+export declare const MCP_TRUNCATION_MARKER = "\n\u2026";
+export declare function resolveMcpMaxTokens(toolName: string, args: Record<string, unknown> | undefined, env?: NodeJS.ProcessEnv): number | undefined;
+export declare function applyMcpMaxTokens(text: string, maxTokens: number | undefined): string;
+export declare function withoutMcpBudgetArg(args: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/mcp/output-budget.js

@@ -0,0 +1,52 @@
+const BUDGETED_TOOLS = new Set(['query', 'context', 'impact']);
+export const MCP_TOKEN_ESTIMATE_BYTES = 4;
+export const MCP_TRUNCATION_MARKER = '\n…';
+function parsePositiveInteger(value, source) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === 'string' && /^[1-9]\d*$/.test(value.trim())) {
+        const parsed = Number(value.trim());
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    throw new Error(`${source} must be a positive integer.`);
+}
+export function resolveMcpMaxTokens(toolName, args, env = process.env) {
+    if (!BUDGETED_TOOLS.has(toolName))
+        return undefined;
+    if (args?.maxTokens !== undefined)
+        return parsePositiveInteger(args.maxTokens, 'maxTokens');
+    const configured = env.GITNEXUS_MCP_DEFAULT_MAX_TOKENS;
+    if (configured === undefined || configured.trim() === '')
+        return undefined;
+    return parsePositiveInteger(configured, 'GITNEXUS_MCP_DEFAULT_MAX_TOKENS');
+}
+function utf8Prefix(text, maxBytes) {
+    let bytes = 0;
+    const codePoints = [];
+    for (const codePoint of text) {
+        const codePointBytes = Buffer.byteLength(codePoint, 'utf8');
+        if (bytes + codePointBytes > maxBytes)
+            break;
+        codePoints.push(codePoint);
+        bytes += codePointBytes;
+    }
+    return codePoints.join('');
+}
+export function applyMcpMaxTokens(text, maxTokens) {
+    if (maxTokens === undefined)
+        return text;
+    const textBytes = Buffer.byteLength(text, 'utf8');
+    if (maxTokens >= Math.ceil(textBytes / MCP_TOKEN_ESTIMATE_BYTES))
+        return text;
+    const maxBytes = maxTokens * MCP_TOKEN_ESTIMATE_BYTES;
+    const markerBytes = Buffer.byteLength(MCP_TRUNCATION_MARKER, 'utf8');
+    return utf8Prefix(text, Math.max(0, maxBytes - markerBytes)) + MCP_TRUNCATION_MARKER;
+}
+export function withoutMcpBudgetArg(args) {
+    if (!args || !Object.prototype.hasOwnProperty.call(args, 'maxTokens'))
+        return args;
+    const backendArgs = { ...args };
+    delete backendArgs.maxTokens;
+    return backendArgs;
+}

package/dist/mcp/read-only-policy.d.ts

@@ -0,0 +1,12 @@
+import type { GITNEXUS_TOOLS } from './tools.js';
+type GitNexusTool = (typeof GITNEXUS_TOOLS)[number];
+export declare const MCP_READ_ONLY_TOOLS: Set<string>;
+export declare function resolveMcpReadOnlyMode(env?: NodeJS.ProcessEnv): boolean;
+export declare function assertMcpReadOnlyToolCall(toolName: string, args: Record<string, unknown> | undefined, readOnly: boolean): void;
+export declare function readOnlyResourceTemplateAllowed(uriTemplate: string, readOnly: boolean): boolean;
+export declare function assertMcpReadOnlyResource(uri: string, readOnly: boolean): void;
+export declare function filterMcpReadOnlyResourceContent(content: string, readOnly: boolean): string;
+/** Shared with repository-policy.ts so both policies scrub identically. */
+export declare function scrubGroupDescription(description: string): string;
+export declare function toolForReadOnlyMcp(tool: GitNexusTool, readOnly: boolean): GitNexusTool;
+export {};

package/dist/mcp/read-only-policy.js

@@ -0,0 +1,102 @@
+export const MCP_READ_ONLY_TOOLS = new Set([
+    'list_repos',
+    'query',
+    'context',
+    'detect_changes',
+    'check',
+    'impact',
+    'explain',
+    'pdg_query',
+    'route_map',
+    'tool_map',
+    'shape_check',
+    'api_impact',
+    'trace',
+]);
+const MCP_READ_ONLY_ALIASES = new Set(['search', 'explore', 'overview']);
+export function resolveMcpReadOnlyMode(env = process.env) {
+    const value = env.GITNEXUS_MCP_READ_ONLY?.trim();
+    if (value === undefined || value === '' || value === '0')
+        return false;
+    if (value === '1')
+        return true;
+    throw new Error('GITNEXUS_MCP_READ_ONLY must be 0 or 1.');
+}
+export function assertMcpReadOnlyToolCall(toolName, args, readOnly) {
+    if (!readOnly)
+        return;
+    if (!MCP_READ_ONLY_TOOLS.has(toolName) && !MCP_READ_ONLY_ALIASES.has(toolName)) {
+        throw new Error(`Tool "${toolName}" is not available in GitNexus MCP read-only mode.`);
+    }
+    if (typeof args?.repo === 'string' && args.repo.trim().startsWith('@')) {
+        throw new Error('Group routing is not available in GitNexus MCP read-only mode.');
+    }
+    // crossDepth/subgroup only do anything on the @group path rejected above,
+    // but rejecting them here keeps the advertised schema and the dispatch
+    // contract in agreement.
+    for (const groupOnlyArg of ['crossDepth', 'subgroup']) {
+        if (args?.[groupOnlyArg] !== undefined) {
+            throw new Error(`Parameter "${groupOnlyArg}" is not available in GitNexus MCP read-only mode.`);
+        }
+    }
+}
+export function readOnlyResourceTemplateAllowed(uriTemplate, readOnly) {
+    return !readOnly || !/^gitnexus:\/\/group\//iu.test(uriTemplate);
+}
+export function assertMcpReadOnlyResource(uri, readOnly) {
+    if (!readOnly)
+        return;
+    let isGroupResource = false;
+    try {
+        const parsed = new URL(uri);
+        isGroupResource =
+            parsed.protocol.toLowerCase() === 'gitnexus:' && parsed.hostname.toLowerCase() === 'group';
+    }
+    catch {
+        // Invalid resource URIs are rejected by the normal parser. This fallback
+        // keeps obviously group-shaped malformed inputs fail-closed as well.
+        isGroupResource = /^gitnexus:\/\/group(?:\/|$)/iu.test(uri);
+    }
+    if (isGroupResource) {
+        throw new Error('Group resources are not available in GitNexus MCP read-only mode.');
+    }
+}
+// Cosmetic only: dispatch enforcement above is the actual boundary. If the
+// generated resource format drifts and a hidden route slips through here, the
+// caller still gets a clean rejection at dispatch.
+export function filterMcpReadOnlyResourceContent(content, readOnly) {
+    if (!readOnly)
+        return content;
+    return content
+        .split('\n')
+        .filter((line) => !/^\s*-\s+(?:rename|cypher|group_sync|group_list):/u.test(line) &&
+        !/^\|\s*`(?:rename|cypher|group_sync|group_list)`\s*\|/u.test(line) &&
+        !line.includes('gitnexus://group/'))
+        .join('\n');
+}
+/** Shared with repository-policy.ts so both policies scrub identically. */
+export function scrubGroupDescription(description) {
+    return description
+        .replace(/\nGROUP MODE:[\s\S]*?(?=\n\n[A-Z][A-Z ()-]*:|$)/gu, '')
+        .replace(/\nCROSS-REPO \(experimental\):[\s\S]*?(?=\n\n[A-Z][A-Z ()-]*:|$)/gu, '')
+        .replace(/\nDESTINATION TRACE \(cross-repo\):[\s\S]*?(?=\n\n[A-Z][A-Z ()-]*:|$)/gu, '');
+}
+export function toolForReadOnlyMcp(tool, readOnly) {
+    if (!readOnly)
+        return tool;
+    const properties = { ...tool.inputSchema.properties };
+    const repo = properties.repo;
+    if (repo && typeof repo === 'object') {
+        properties.repo = {
+            ...repo,
+            description: 'Indexed repository name or path. Group-mode values beginning with @ are unavailable in MCP read-only mode.',
+        };
+    }
+    delete properties.subgroup;
+    delete properties.crossDepth;
+    return {
+        ...tool,
+        description: `${scrubGroupDescription(tool.description)}\n\nGitNexus MCP read-only mode excludes raw Cypher, mutation, and group routing.`,
+        inputSchema: { ...tool.inputSchema, properties },
+    };
+}

package/dist/mcp/repository-policy.d.ts

@@ -0,0 +1,34 @@
+import type { LocalBackend } from './local/local-backend.js';
+import type { GITNEXUS_TOOLS } from './tools.js';
+type GitNexusTool = (typeof GITNEXUS_TOOLS)[number];
+interface ResolvedRepository {
+    name: string;
+    path: string;
+    pathKey: string;
+}
+export declare class McpRepositoryPolicy {
+    readonly restricted: boolean;
+    readonly configured: boolean;
+    private readonly registry;
+    private readonly allowed;
+    private readonly allowedPathKeys;
+    private readonly defaultRepo?;
+    private readonly uniqueAllowedContextNames;
+    static unrestricted(): McpRepositoryPolicy;
+    constructor(registry: readonly ResolvedRepository[], allowed: readonly ResolvedRepository[] | undefined, defaultRepo: ResolvedRepository | undefined);
+    private resolveRuntimeRepo;
+    private repoForArgs;
+    private normalizeToolArgs;
+    private listAllowedRepos;
+    private listReposPage;
+    private callTool;
+    private resolveRepo;
+    assertResourceUri(uri: string): void;
+    resourceTemplateAllowed(uriTemplate: string): boolean;
+    toolAllowed(toolName: string): boolean;
+    toolForMcp(tool: GitNexusTool): GitNexusTool;
+    scopeBackend(backend: LocalBackend): LocalBackend;
+}
+export declare function mcpRepositoryPolicyConfigured(env?: NodeJS.ProcessEnv): boolean;
+export declare function createMcpRepositoryPolicy(backend: LocalBackend, env?: NodeJS.ProcessEnv): Promise<McpRepositoryPolicy>;
+export {};

package/dist/mcp/repository-policy.js

@@ -0,0 +1,328 @@
+import path from 'node:path';
+import { parseListReposPagination } from './local/local-backend.js';
+import { scrubGroupDescription } from './read-only-policy.js';
+import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from './tools.js';
+const CANONICAL_ALLOWED = 'GITNEXUS_MCP_ALLOWED_REPOS';
+const CANONICAL_DEFAULT = 'GITNEXUS_MCP_DEFAULT_REPO';
+function configuredValue(env, key) {
+    const value = env[key];
+    return value === undefined ? undefined : { key, value };
+}
+function parseRepositoryPolicy(env) {
+    const allowedRaw = configuredValue(env, CANONICAL_ALLOWED);
+    const defaultRaw = configuredValue(env, CANONICAL_DEFAULT);
+    let allowed;
+    if (allowedRaw) {
+        allowed = allowedRaw.value
+            .split(',')
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        if (allowed.length === 0)
+            throw new Error(`${allowedRaw.key} must not be blank.`);
+    }
+    let defaultRepo;
+    if (defaultRaw) {
+        defaultRepo = defaultRaw.value.trim();
+        if (!defaultRepo)
+            throw new Error(`${defaultRaw.key} must not be blank.`);
+    }
+    return { allowed, defaultRepo };
+}
+function normalizedPath(value) {
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function isAbsolutePath(value) {
+    return path.isAbsolute(value) || path.win32.isAbsolute(value);
+}
+function resolveSpecifier(specifier, registry) {
+    const trimmed = specifier.trim();
+    const matches = isAbsolutePath(trimmed)
+        ? registry.filter((repo) => repo.pathKey === normalizedPath(trimmed))
+        : registry.filter((repo) => repo.name.toLowerCase() === trimmed.toLowerCase());
+    if (matches.length === 0)
+        return { reason: 'invalid' };
+    if (matches.length > 1)
+        return { reason: 'ambiguous' };
+    return { repo: matches[0] };
+}
+function startupResolutionError(reason) {
+    return new Error(reason === 'ambiguous'
+        ? 'MCP repository configuration contains an ambiguous repository selection.'
+        : 'MCP repository configuration contains an invalid repository selection.');
+}
+function unavailableRepositoryError() {
+    return new Error('Repository is not available through this MCP server.');
+}
+export class McpRepositoryPolicy {
+    restricted;
+    configured;
+    registry;
+    allowed;
+    allowedPathKeys;
+    defaultRepo;
+    uniqueAllowedContextNames;
+    static unrestricted() {
+        return new McpRepositoryPolicy([], undefined, undefined);
+    }
+    constructor(registry, allowed, defaultRepo) {
+        this.registry = registry;
+        this.restricted = allowed !== undefined;
+        this.configured = this.restricted || defaultRepo !== undefined;
+        this.allowed = allowed ?? registry;
+        this.allowedPathKeys = new Set(this.allowed.map((repo) => repo.pathKey));
+        this.defaultRepo = defaultRepo;
+        const registryNameCounts = new Map();
+        for (const repo of registry) {
+            const name = repo.name.toLowerCase();
+            registryNameCounts.set(name, (registryNameCounts.get(name) ?? 0) + 1);
+        }
+        this.uniqueAllowedContextNames = new Set(this.allowed
+            .map((repo) => repo.name.toLowerCase())
+            .filter((name) => registryNameCounts.get(name) === 1));
+    }
+    resolveRuntimeRepo(specifier) {
+        const result = resolveSpecifier(specifier, this.registry);
+        if (!result.repo || (this.restricted && !this.allowedPathKeys.has(result.repo.pathKey))) {
+            throw unavailableRepositoryError();
+        }
+        return result.repo;
+    }
+    repoForArgs(args) {
+        const explicit = args?.repo;
+        if (explicit !== undefined) {
+            if (typeof explicit !== 'string')
+                throw unavailableRepositoryError();
+            if (explicit.trim().startsWith('@')) {
+                if (this.restricted) {
+                    throw new Error('Group routing is unavailable when an MCP repository allowlist is set.');
+                }
+                return undefined;
+            }
+            return this.resolveRuntimeRepo(explicit);
+        }
+        if (this.defaultRepo)
+            return this.defaultRepo;
+        if (this.restricted && this.allowed.length === 1)
+            return this.allowed[0];
+        if (this.restricted && this.allowed.length > 1) {
+            throw new Error('Specify an explicit repo because multiple repositories are allowed.');
+        }
+        return undefined;
+    }
+    normalizeToolArgs(args) {
+        if (!this.configured)
+            return args;
+        if (!this.restricted && args?.repo !== undefined)
+            return args;
+        const selected = this.repoForArgs(args);
+        if (!selected)
+            return args;
+        return { ...(args ?? {}), repo: selected.path };
+    }
+    async listAllowedRepos(backend) {
+        const current = await backend.listRepos();
+        if (!this.restricted)
+            return current;
+        return current
+            .filter((repo) => this.allowedPathKeys.has(normalizedPath(repo.path)))
+            .map((repo) => {
+            const siblings = repo.siblings?.filter((sibling) => this.allowedPathKeys.has(normalizedPath(sibling.path)));
+            return {
+                ...repo,
+                siblings: siblings && siblings.length > 0 ? siblings : undefined,
+            };
+        });
+    }
+    async listReposPage(backend, params) {
+        const { limit, offset } = parseListReposPagination(params, {
+            defaultLimit: LIST_REPOS_DEFAULT_LIMIT,
+            maxLimit: LIST_REPOS_MAX_LIMIT,
+        });
+        const repositories = await this.listAllowedRepos(backend);
+        repositories.sort((a, b) => {
+            const an = a.name.toLowerCase();
+            const bn = b.name.toLowerCase();
+            if (an !== bn)
+                return an < bn ? -1 : 1;
+            return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+        });
+        const total = repositories.length;
+        const page = repositories.slice(offset, offset + limit);
+        const returned = page.length;
+        const hasMore = offset + returned < total;
+        return {
+            repositories: page,
+            pagination: {
+                total,
+                limit,
+                offset,
+                returned,
+                hasMore,
+                ...(hasMore && { nextOffset: offset + returned }),
+            },
+        };
+    }
+    async callTool(backend, method, params) {
+        if (!this.configured)
+            return backend.callTool(method, params);
+        if (method === 'list_repos')
+            return this.listReposPage(backend, params);
+        if (this.restricted && method.startsWith('group_')) {
+            throw new Error('Group tools are unavailable when an MCP repository allowlist is set.');
+        }
+        return backend.callTool(method, this.normalizeToolArgs(params));
+    }
+    async resolveRepo(backend, repo, branch) {
+        if (!this.configured)
+            return backend.resolveRepo(repo, branch);
+        if (!this.restricted)
+            return backend.resolveRepo(repo ?? this.defaultRepo?.path, branch);
+        const selected = this.repoForArgs(repo === undefined ? undefined : { repo });
+        return backend.resolveRepo(selected?.path, branch);
+    }
+    assertResourceUri(uri) {
+        if (!this.restricted)
+            return;
+        let parsed;
+        try {
+            parsed = new URL(uri);
+        }
+        catch {
+            // resources.ts parses with the same URL call, so anything that fails
+            // here fails there too today. Keep obviously group- or repo-shaped
+            // malformed inputs fail-closed anyway in case the parsers ever drift.
+            if (/^gitnexus:\/\/group(?:\/|$)/iu.test(uri)) {
+                throw new Error('Group resources are unavailable when an MCP repository allowlist is set.');
+            }
+            const repoShaped = /^gitnexus:\/\/repo\/([^/]+)/iu.exec(uri);
+            if (repoShaped)
+                this.resolveRuntimeRepo(decodeURIComponent(repoShaped[1]));
+            return;
+        }
+        // gitnexus: is a non-special URL scheme, so the host is opaque and NOT
+        // lowercased by the parser — compare case-insensitively like
+        // read-only-policy.ts does.
+        if (parsed.protocol.toLowerCase() !== 'gitnexus:')
+            return;
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname === 'group') {
+            throw new Error('Group resources are unavailable when an MCP repository allowlist is set.');
+        }
+        if (hostname !== 'repo')
+            return;
+        const repoName = parsed.pathname.split('/').filter(Boolean)[0];
+        if (!repoName)
+            return;
+        this.resolveRuntimeRepo(decodeURIComponent(repoName));
+    }
+    resourceTemplateAllowed(uriTemplate) {
+        return !this.restricted || !uriTemplate.startsWith('gitnexus://group/');
+    }
+    toolAllowed(toolName) {
+        return !this.restricted || !toolName.startsWith('group_');
+    }
+    toolForMcp(tool) {
+        if (!this.restricted)
+            return tool;
+        const properties = { ...tool.inputSchema.properties };
+        const repo = properties.repo;
+        if (repo && typeof repo === 'object') {
+            properties.repo = {
+                ...repo,
+                description: 'Allowed indexed repository name or path. Group-mode values are unavailable.',
+            };
+        }
+        delete properties.subgroup;
+        delete properties.crossDepth;
+        const description = scrubGroupDescription(tool.description);
+        return { ...tool, description, inputSchema: { ...tool.inputSchema, properties } };
+    }
+    scopeBackend(backend) {
+        const policy = this;
+        return new Proxy(backend, {
+            get(target, property, receiver) {
+                if (property === 'callTool') {
+                    return (method, params) => policy.callTool(target, method, params);
+                }
+                if (property === 'listRepos')
+                    return () => policy.listAllowedRepos(target);
+                if (property === 'resolveRepo') {
+                    return (repo, branch) => policy.resolveRepo(target, repo, branch);
+                }
+                if (property === 'getContext' && policy.restricted) {
+                    return (repoId) => {
+                        if (!repoId || !policy.uniqueAllowedContextNames.has(repoId.toLowerCase()))
+                            return null;
+                        return target.getContext(repoId);
+                    };
+                }
+                if (policy.restricted &&
+                    (property === 'readGroupContractsResource' || property === 'readGroupStatusResource')) {
+                    return async () => {
+                        throw new Error('Group resources are unavailable when an MCP repository allowlist is set.');
+                    };
+                }
+                // Repo-scoped resource reads must not depend on assertResourceUri
+                // running first — enforce the allowlist on the query surface too.
+                if (policy.restricted && (property === 'queryClusters' || property === 'queryProcesses')) {
+                    return (repoName, limit) => {
+                        const selected = policy.repoForArgs(repoName === undefined ? undefined : { repo: repoName });
+                        return property === 'queryClusters'
+                            ? target.queryClusters(selected?.path ?? repoName, limit)
+                            : target.queryProcesses(selected?.path ?? repoName, limit);
+                    };
+                }
+                if (policy.restricted &&
+                    (property === 'queryClusterDetail' || property === 'queryProcessDetail')) {
+                    return (name, repoName) => {
+                        const selected = policy.repoForArgs(repoName === undefined ? undefined : { repo: repoName });
+                        return property === 'queryClusterDetail'
+                            ? target.queryClusterDetail(name, selected?.path ?? repoName)
+                            : target.queryProcessDetail(name, selected?.path ?? repoName);
+                    };
+                }
+                const value = Reflect.get(target, property, receiver);
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        });
+    }
+}
+export function mcpRepositoryPolicyConfigured(env = process.env) {
+    const raw = parseRepositoryPolicy(env);
+    return raw.allowed !== undefined || raw.defaultRepo !== undefined;
+}
+export async function createMcpRepositoryPolicy(backend, env = process.env) {
+    const raw = parseRepositoryPolicy(env);
+    if (!raw.allowed && !raw.defaultRepo) {
+        return McpRepositoryPolicy.unrestricted();
+    }
+    const registry = (await backend.listRepos()).map((repo) => ({
+        name: repo.name,
+        path: repo.path,
+        pathKey: normalizedPath(repo.path),
+    }));
+    let allowed;
+    if (raw.allowed) {
+        const byPath = new Map();
+        for (const specifier of raw.allowed) {
+            const result = resolveSpecifier(specifier, registry);
+            if (!result.repo)
+                throw startupResolutionError(result.reason ?? 'invalid');
+            byPath.set(result.repo.pathKey, result.repo);
+        }
+        allowed = [...byPath.values()];
+    }
+    let defaultRepo;
+    if (raw.defaultRepo) {
+        const result = resolveSpecifier(raw.defaultRepo, registry);
+        if (!result.repo)
+            throw startupResolutionError(result.reason ?? 'invalid');
+        defaultRepo = result.repo;
+    }
+    const defaultPathKey = defaultRepo?.pathKey;
+    if (defaultPathKey && allowed && !allowed.some((repo) => repo.pathKey === defaultPathKey)) {
+        throw new Error('The MCP default repository is not in the configured allowlist.');
+    }
+    return new McpRepositoryPolicy(registry, allowed, defaultRepo);
+}

package/dist/mcp/resources.js

@@ -5,6 +5,9 @@
  * All resources use repo-scoped URIs: gitnexus://repo/{name}/context
  */
 import { checkStaleness } from './staleness.js';
+import { loadMeta } from '../storage/repo-manager.js';
+import { ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION } from '../core/analyzer-identity.js';
+import { getIndexIncompleteReasons } from '../core/index-freshness.js';
 /**
  * Static resources — includes per-repo resources and the global repos list
  */
@@ -249,9 +252,16 @@ async function getContextResource(backend, repoName) {
     if (!context) {
         return 'error: No codebase loaded. Run: gitnexus analyze';
     }
-    // Check staleness
+    // Read fresh metadata from disk on every context resource read to avoid showing
+    // a stale staleness banner or outdated stats after an out-of-process
+    // `analyze --index-only` refresh. The RepoHandle is cached in-memory and only
+    // refreshes on registry misses, so its lastCommit/stats can lag behind the
+    // on-disk state (#2438). Mirrors the ensureInitialized hot-swap pattern.
+    const freshMeta = await loadMeta(repo.storagePath).catch(() => null);
+    const incompleteReasons = getIndexIncompleteReasons(freshMeta);
+    // Check staleness using the current on-disk lastCommit (not the cached handle)
     const repoPath = repo.repoPath;
-    const lastCommit = repo.lastCommit || 'HEAD';
+    const lastCommit = freshMeta?.lastCommit ?? repo.lastCommit ?? 'HEAD';
     const staleness = repoPath
         ? checkStaleness(repoPath, lastCommit)
         : { isStale: false, commitsBehind: 0 };
@@ -260,11 +270,27 @@ async function getContextResource(backend, repoName) {
         lines.push('');
         lines.push(`staleness: "${staleness.hint}"`);
     }
+    // A JSON object is also a valid YAML flow mapping. Keeping the versioned
+    // receipt intact lets agents compare every identity field without parsing a
+    // lossy human rendering; null explicitly means legacy/unknown provenance.
+    lines.push('');
+    lines.push('index:');
+    lines.push(`  commit: ${JSON.stringify(lastCommit)}`);
+    lines.push(`  indexed_at: ${JSON.stringify(freshMeta?.indexedAt ?? null)}`);
+    lines.push(`  runner_identity: ${JSON.stringify(freshMeta?.runnerIdentity ?? null)}`);
+    lines.push(`  incomplete_reasons: ${JSON.stringify(incompleteReasons)}`);
+    const indexedRunnerSchema = freshMeta?.runnerIdentity
+        ?.schemaVersion;
+    lines.push(`  runner_identity_schema_status: ${JSON.stringify(indexedRunnerSchema === ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION
+        ? 'current'
+        : 'legacy-or-unknown')}`);
+    // Use fresh stats from disk meta when available; fall back to cached context
+    const freshStats = freshMeta?.stats;
     lines.push('');
     lines.push('stats:');
-    lines.push(`  files: ${context.stats.fileCount}`);
-    lines.push(`  symbols: ${context.stats.functionCount}`);
-    lines.push(`  processes: ${context.stats.processCount}`);
+    lines.push(`  files: ${freshStats?.files ?? context.stats.fileCount}`);
+    lines.push(`  symbols: ${freshStats?.nodes ?? context.stats.functionCount}`);
+    lines.push(`  processes: ${freshStats?.processes ?? context.stats.processCount}`);
     lines.push('');
     lines.push('tools_available:');
     lines.push('  - query: Process-grouped code intelligence (execution flows related to a concept)');
@@ -365,6 +391,7 @@ additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Nam
 
 node_properties:
   common: "name (STRING), filePath (STRING), startLine (INT32), endLine (INT32)"
+  line_numbers: "startLine/endLine on symbol nodes are 0-BASED (tree-sitter rows) in storage AND in raw Cypher results. The context, query, impact, group/cross-repo trace, and explain/pdg_query (symbol anchor) tools present them 1-BASED (editor / sed / less -N aligned), so a symbol spans editor lines (startLine+1)..(endLine+1) — e.g. sed '<startLine+1>,<endLine+1>!d' <file>. Single-repo trace symbol lines stay 0-BASED for now (full-parity follow-up). content holds the exact symbol span. (BasicBlock / PDG statement lines are separately 1-based.) (#2377, #2380)"
   Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isVirtual (BOOL), isOverride (BOOL), isAsync (BOOL), isPartial (BOOL), requiredParameterCount (INT32), parameterTypes (STRING[]), annotations (STRING[])"
   Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isAsync (BOOL), parameterTypes (STRING[]), annotations (STRING[])"
   Property: "declaredType (STRING) — the field's type annotation (e.g., 'Address', 'City'). Used for field-access chain resolution."