gitnexus 1.6.11-rc.2 → 1.6.11-rc.21

package/dist/mcp/resources.js

@@ -254,7 +254,8 @@ async function getReposResource(backend) {
     }
     if (repos.length > 1) {
         lines.push('');
-        lines.push('# Multiple repos indexed. Use repo parameter in tool calls:');
+        lines.push('# Multiple repos indexed. Read-only tools may omit repo when an MCP default is configured or GitNexus process.cwd() is inside one listed path without crossing an unindexed nested Git checkout.');
+        lines.push('# Otherwise—and for mutating tools without an MCP default—pass repo explicitly:');
         lines.push(`# query({search_query: "auth", repo: "${repos[0].name}"})`);
     }
     return lines.join('\n');

package/dist/mcp/server.js

@@ -136,11 +136,11 @@ export function createMCPServer(backend, options = {}) {
             };
         }
     });
-    // With multiple visible repositories and no process-wide default, make the
-    // routing requirement machine-readable. Agents then supply `repo` before the
-    // call instead of discovering the ambiguity through a failed tool response.
+    // Make the effective routing contract machine-readable. Read-only tools may
+    // use a cwd-derived default; mutating rename remains explicit unless policy
+    // supplies a single/default repository.
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const requireRepo = await repositoryPolicy.requiresExplicitRepo(backend);
+        const { readOnlyRequiresRepo, mutatingRequiresRepo } = await repositoryPolicy.toolSchemaRepoRequirements(backend);
         return {
             tools: GITNEXUS_TOOLS.filter((tool) => (!readOnly || MCP_READ_ONLY_TOOLS.has(tool.name)) &&
                 repositoryPolicy.toolAllowed(tool.name))
@@ -148,7 +148,8 @@ export function createMCPServer(backend, options = {}) {
                 .map((tool) => ({
                 name: tool.name,
                 description: tool.description,
-                inputSchema: requireRepo && REPO_SCOPED_TOOLS.has(tool.name)
+                inputSchema: (tool.name === 'rename' ? mutatingRequiresRepo : readOnlyRequiresRepo) &&
+                    REPO_SCOPED_TOOLS.has(tool.name)
                     ? {
                         ...tool.inputSchema,
                         required: [...new Set([...tool.inputSchema.required, 'repo'])],

package/dist/mcp/tools.js

@@ -49,6 +49,8 @@ export const PDG_QUERY_MAX_LIMIT = 200;
 // Shared impact traversal depth cap. The MCP schema advertises this bound;
 // PDG direct backend callers also enforce it before running traversal.
 export const IMPACT_MAX_DEPTH = 32;
+const CWD_AWARE_REPO_OMISSION = 'Omit when only one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing an unindexed nested Git checkout; otherwise specify it explicitly.';
+const MUTATING_REPO_OMISSION = 'Omit only when one repo is indexed or an MCP default is configured; otherwise mutating tools require an explicit repo.';
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
@@ -61,8 +63,10 @@ PAGINATION: Results are paginated so a large registry is not truncated by MCP/LL
 WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
 AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
 
-When multiple repos are indexed, you MUST specify the "repo" parameter
-on other tools (query, context, impact, etc.) to target the correct one.`,
+When multiple repos are indexed, repo-scoped read-only tools use the configured
+MCP default or the registered path containing the GitNexus process cwd, unless
+cwd has crossed into an unindexed nested Git checkout. If neither applies,
+specify the "repo" parameter explicitly.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -148,7 +152,7 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
                 },
                 repo: {
                     type: 'string',
-                    description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>" (member path keys from group.yaml). Omit when only one indexed repo exists.',
+                    description: `Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>" (member path keys from group.yaml). ${CWD_AWARE_REPO_OMISSION}`,
                 },
                 service: {
                     type: 'string',
@@ -227,7 +231,7 @@ TIPS:
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: ['statement'],
@@ -290,7 +294,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                 },
                 repo: {
                     type: 'string',
-                    description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". Omit if only one repo is indexed.',
+                    description: `Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". ${CWD_AWARE_REPO_OMISSION}`,
                 },
                 service: {
                     type: 'string',
@@ -334,7 +338,7 @@ Returns: changed symbols, affected processes, and a risk summary.
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],
@@ -373,7 +377,7 @@ A graph too large to analyze at all returns \`{ error, truncated: true }\` with
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],
@@ -410,7 +414,7 @@ Handles disambiguation via context()'s payload verbatim: an ambiguous symbol_nam
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${MUTATING_REPO_OMISSION}`,
                 },
             },
             required: ['new_name'],
@@ -425,17 +429,19 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
 
-PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:3 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:3, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
 
 Output includes:
-- risk: LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN. An upstream walk that resolved ZERO callers reports UNKNOWN, never LOW, and carries riskNote: "safe to change" is a claim about callers and there were none to reason about, so the symbol is either genuinely unused OR reached only through a reference class the index does not record (plain-object property access, a bare-identifier read of a module-scope const). Confirm with a text search before acting on it. Downstream walks are unaffected — an empty downstream result reports resolved callees, not safety.
+- risk: LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN. This is the HIGH/CRITICAL edit-gate field. File targets lack process/community membership, so their risk is not directly comparable with symbol risk; use riskSharedAxes to compare the direct/total axes common to both. Group-mode (\`repo: "@…"\`) results lift the same fields to the top-level envelope. The web Graph-RAG impact tool expands File targets to in-file symbols before enrichment, so process/cluster axes remain comparable there. An upstream walk that resolved ZERO callers reports UNKNOWN, never LOW, and carries riskNote: "safe to change" is a claim about callers and there were none to reason about, so the symbol is either genuinely unused OR reached only through a reference class the index does not record (plain-object property access, a bare-identifier read of a module-scope const). Confirm with a text search before acting on it. Downstream walks are unaffected — an empty downstream result reports resolved callees, not safety.
+- riskSharedAxes: single-repo risk computed only from direct and total impact. Group mode then applies the cross-repo crossing overlay to that local value. Suitable for comparing File and symbol targets within the same mode. Never substitute it for \`risk\` when deciding whether to warn before edits.
+- riskScale: { comparableAcrossKinds, unusedAxes } — names process/module axes that were structurally unavailable, skipped, budget-exhausted (\`IMPACT_MAX_CHUNKS=0\`), truncated (sampled a subset of impacted symbols), or failed at query time. Failed-query and truncated-sample counts are lower bounds: known HIGH/CRITICAL warnings survive, otherwise risk is UNKNOWN. Group impact copies this metadata from the local leg.
 - riskNote: string — present only when risk is UNKNOWN; states why the verdict is withheld.
 - summary: direct callers, processes affected, modules affected
 - affected_processes: which execution flows break and at which step
-- affected_modules: which functional areas are hit (direct vs indirect)
+- affected_modules: which functional areas are hit (direct vs indirect; classification-unavailable when that secondary query fails)
 - byDepth: affected symbols grouped by traversal depth (paginated by limit/offset; omitted when summaryOnly:true — use byDepthCounts for totals per depth, pagination object when truncated). Each item includes a processes:[{id,label,processType,step}] field listing the execution flows that symbol participates in. Empty when the symbol has no process membership. Can ALSO be empty when partial:true is set — either the process-aggregation pass hit its cap before detecting affected processes, or per-symbol enrichment was capped on a very large page. When partial:true, do NOT treat processes:[] as proof of no participation; cross-check the top-level affected_processes list.
 - epistemic: 'exact' | 'lower-bound' — whether impactedCount is the whole story. 'lower-bound' means the walk provably missed callers, so the count is a floor. Absent only on skipped probes (ambiguous-candidate lists, group fan-out).
 - boundaries: string[] — one plain-language sentence per reason the count is short. Prose for humans; branch on causes instead.
@@ -540,7 +546,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                 },
                 repo: {
                     type: 'string',
-                    description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". Omit if only one repo is indexed.',
+                    description: `Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". ${CWD_AWARE_REPO_OMISSION}`,
                 },
                 service: {
                     type: 'string',
@@ -628,7 +634,7 @@ Findings are deliberately NOT part of impact()'s traversal or the web schema —
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],
@@ -677,7 +683,7 @@ CONTRACT CAVEATS:
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: ['mode', 'target'],
@@ -701,7 +707,7 @@ Returns: route nodes with their handlers, middleware wrapper chains (e.g., withA
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],
@@ -719,7 +725,10 @@ Returns: tool nodes with their handler files and descriptions.`,
             type: 'object',
             properties: {
                 tool: { type: 'string', description: 'Filter by tool name. Omit for all tools.' },
-                repo: { type: 'string', description: 'Repository name or path.' },
+                repo: {
+                    type: 'string',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
+                },
             },
             required: [],
         },
@@ -742,7 +751,7 @@ Returns routes that have both detected response keys AND consumers. Shows top-le
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],
@@ -767,7 +776,10 @@ Response shape is keyed on how many routes match, not on the data: exactly one m
                     type: 'string',
                     description: 'Optional HTTP verb — GET, POST, PUT, PATCH, DELETE, etc. — to narrow a multi-verb route or file lookup to a single method. Returns an error if no matched route uses that verb.',
                 },
-                repo: { type: 'string', description: 'Repository name or path.' },
+                repo: {
+                    type: 'string',
+                    description: `Repository name or path. ${CWD_AWARE_REPO_OMISSION}`,
+                },
             },
             required: [],
         },
@@ -877,7 +889,7 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
                 },
                 repo: {
                     type: 'string',
-                    description: 'Repository name or path, or "@groupName" / "@groupName/memberPath" for a cross-repo trace over a group. Omit if only one repo is indexed.',
+                    description: `Repository name or path, or "@groupName" / "@groupName/memberPath" for a cross-repo trace over a group. ${CWD_AWARE_REPO_OMISSION}`,
                 },
             },
             required: [],

package/dist/server/api.js

@@ -20,14 +20,16 @@ import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
 import { ftsDegradedWarning } from '../core/search/fts-indexes.js';
 import { LocalBackend } from '../mcp/local/local-backend.js';
-import { mountMCPEndpoints } from './mcp-http.js';
+import { installServeMcpAuth, mountMCPEndpoints } from './mcp-http.js';
 import { fileURLToPath } from 'url';
 import { isTerminalJobStatus, JobManager } from './analyze-job.js';
 import { mountSSEProgress } from './sse-progress.js';
 import { resolveEmbedRunOutcome, withMeasuredEmbeddingCount, } from './embed-run-outcome.js';
 import { decideEmbeddingResume, mintInterruptedCheckpoint } from '../core/embedding-checkpoint.js';
 import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } from '../core/embedding-count.js';
-import { assertString, escapeRegExp, BadRequestError, createRouteLimiter } from './validation.js';
+import { assertString, BadRequestError, createRouteLimiter } from './validation.js';
+import { parseGrepQuery, GREP_TIME_BUDGET_MS } from './grep-params.js';
+import { runGrepScanInWorker } from './grep-scan.js';
 import { extractRepoName, getCloneDir, cloneOrPull, warnIfInsecureAzureConfig, GITHUB_TOKEN_HOSTS, } from './git-clone.js';
 import { createAnalyzeUploadHandler } from './analyze-upload.js';
 import { assertServeAuthForPublicOrigin, createPublicOriginMatcher, createWriteOriginGuard, logOriginPolicy, PUBLIC_ORIGIN_ENV, resolveTrustProxy, TRUST_PROXY_ENV, warnIfRateLimitKeysCollapse, } from './middleware.js';
@@ -616,6 +618,9 @@ export const createServer = async (port, host = '127.0.0.1') => {
             callback(null, isAllowedOrigin(origin));
         },
     }));
+    // Optional protocol-layer auth for the MCP route. Keep this before the
+    // global body parser so rejected requests do not consume the JSON budget.
+    installServeMcpAuth(app);
     app.use(express.json({ limit: '10mb' }));
     // Origin guard for write routes: loopback, the server's own bound host, and
     // any configured public origin — prevents CSRF from other devices.
@@ -1126,75 +1131,29 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(404).json({ error: 'Repository not found' });
                 return;
             }
-            // Type-confusion guard (CodeQL js/type-confusion-through-parameter-tampering):
-            // req.query.pattern is `string | string[] | ParsedQs` — without an explicit
-            // type check, the `.length` guard below counts array elements instead of
-            // characters, allowing arbitrarily long patterns through.
-            const rawPattern = req.query.pattern;
-            if (rawPattern === undefined) {
-                res.status(400).json({ error: 'Missing "pattern" query parameter' });
-                return;
-            }
-            const pattern = assertString(rawPattern, 'pattern');
-            if (pattern.length === 0) {
-                res.status(400).json({ error: 'Missing "pattern" query parameter' });
-                return;
-            }
-            // Length cap: applies to both literal and regex modes as a defense-in-depth
-            // bound against pathological input.
-            if (pattern.length > 200) {
-                res.status(400).json({ error: 'Pattern too long (max 200 characters)' });
-                return;
-            }
-            // Treat user input as a literal substring in all cases to prevent
-            // regex-injection/ReDoS via attacker-controlled regex syntax.
-            const effectivePattern = escapeRegExp(pattern);
-            // Validate regex syntax (catches both opt-in user regex and any escapeRegExp bug)
-            let regex;
-            try {
-                regex = new RegExp(effectivePattern, 'gim');
-            }
-            catch {
-                res.status(400).json({ error: 'Invalid regex pattern' });
-                return;
-            }
-            const parsedLimit = Number(req.query.limit ?? 50);
-            const limit = Number.isFinite(parsedLimit)
-                ? Math.max(1, Math.min(200, Math.trunc(parsedLimit)))
-                : 50;
-            const results = [];
+            // Pattern parsing lives in grep-params.ts (unit-testable without
+            // Express + LadybugDB). Matching runs in a worker so terminate() can
+            // cut a stuck regex.test() when the wall-clock budget expires.
+            const { regex, fileFilter, limit } = parseGrepQuery(req.query);
             const repoRoot = path.resolve(entry.path);
-            // Get file paths from the graph (lightweight — no content loaded)
             const lbugPath = path.join(entry.storagePath, 'lbug');
             const fileRows = await withLbugDb(lbugPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`), { readOnly: true });
-            // Search files on disk one at a time (constant memory)
+            const filePaths = [];
             for (const row of fileRows) {
-                if (results.length >= limit)
-                    break;
                 const filePath = row.filePath || '';
-                const fullPath = path.resolve(repoRoot, filePath);
-                // Path traversal guard
-                const safeRepoRoot = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep;
-                if (!fullPath.startsWith(safeRepoRoot) && fullPath !== repoRoot)
+                if (fileFilter && !filePath.toLowerCase().includes(fileFilter))
                     continue;
-                let content;
-                try {
-                    content = await fs.readFile(fullPath, 'utf-8');
-                }
-                catch {
-                    continue; // File may have been deleted since indexing
-                }
-                const lines = content.split('\n');
-                for (let i = 0; i < lines.length; i++) {
-                    if (results.length >= limit)
-                        break;
-                    if (regex.test(lines[i])) {
-                        results.push({ filePath, line: i + 1, text: lines[i].trim().slice(0, 200) });
-                    }
-                    regex.lastIndex = 0;
-                }
+                filePaths.push(filePath);
             }
-            res.json({ results });
+            const { results, timedOut } = await runGrepScanInWorker({
+                repoRoot,
+                filePaths,
+                pattern: regex.source,
+                flags: regex.flags,
+                limit,
+                deadlineMs: Date.now() + GREP_TIME_BUDGET_MS,
+            });
+            res.json({ results, ...(timedOut ? { timedOut: true } : {}) });
         }
         catch (err) {
             res.status(statusFromError(err)).json({ error: err.message || 'Grep failed' });

package/dist/server/grep-params.d.ts

@@ -0,0 +1,18 @@
+/** Hard cap on pattern length — unchanged from the literal-only era. */
+export declare const GREP_PATTERN_MAX_LENGTH = 200;
+/** Wall-clock budget for one /api/grep call; parent terminate()s the scan worker. */
+export declare const GREP_TIME_BUDGET_MS = 5000;
+export declare const GREP_DEFAULT_LIMIT = 50;
+export declare const GREP_MAX_LIMIT = 200;
+export interface ParsedGrepQuery {
+    regex: RegExp;
+    /** Lowercased path substring; '' disables path filtering. */
+    fileFilter: string;
+    limit: number;
+}
+/**
+ * Parse /api/grep query parameters into a ready-to-use regex + filters.
+ * Throws BadRequestError (mapped to HTTP 400 by statusFromError) on
+ * missing/over-long patterns or invalid regex syntax.
+ */
+export declare function parseGrepQuery(query: Record<string, unknown>): ParsedGrepQuery;

package/dist/server/grep-params.js

@@ -0,0 +1,83 @@
+/**
+ * Query-parameter parsing for GET /api/grep.
+ *
+ * Extracted from api.ts so the contract is unit-testable without pulling
+ * Express + the LadybugDB native adapter into the test run (same rationale
+ * as the #2790 helper extraction).
+ *
+ * Contract fix (Patch 12): the grep tool schema in gitnexus-web has always
+ * promised regex search with an optional path-substring filter and
+ * case-sensitivity control, but the handler used to escapeRegExp() every
+ * pattern into a literal substring — an agent asking for "sign|Sign" got
+ * zero hits and concluded the code didn't exist, and the schema's own
+ * example ("console\.log") could never match. This restores the promised
+ * semantics. Matching runs in a worker_threads worker (`grep-worker.ts`) so
+ * `terminate()` can interrupt a catastrophic `regex.test()` when the
+ * wall-clock budget expires; the parent event loop stays responsive.
+ * Bounded mitigations:
+ *   - pattern length cap (200 chars, unchanged from the literal-only era)
+ *   - line-by-line matching (each regex.test call sees one source line)
+ *   - a wall-clock budget the parent enforces via worker terminate()
+ *   - result cap unchanged (limit, max 200)
+ *   - literal=1 opt-out restores the old escaped-substring immunity
+ */
+import { assertString, escapeRegExp, BadRequestError } from './validation.js';
+/** Hard cap on pattern length — unchanged from the literal-only era. */
+export const GREP_PATTERN_MAX_LENGTH = 200;
+/** Wall-clock budget for one /api/grep call; parent terminate()s the scan worker. */
+export const GREP_TIME_BUDGET_MS = 5_000;
+export const GREP_DEFAULT_LIMIT = 50;
+export const GREP_MAX_LIMIT = 200;
+const isFlagTrue = (value, name) => {
+    const s = assertString(value ?? '', name).toLowerCase();
+    return s === '1' || s === 'true';
+};
+/**
+ * Parse /api/grep query parameters into a ready-to-use regex + filters.
+ * Throws BadRequestError (mapped to HTTP 400 by statusFromError) on
+ * missing/over-long patterns or invalid regex syntax.
+ */
+export function parseGrepQuery(query) {
+    if (query.pattern === undefined) {
+        throw new BadRequestError('Missing "pattern" query parameter');
+    }
+    const pattern = assertString(query.pattern, 'pattern');
+    if (pattern.length === 0) {
+        throw new BadRequestError('Missing "pattern" query parameter');
+    }
+    if (pattern.length > GREP_PATTERN_MAX_LENGTH) {
+        throw new BadRequestError(`Pattern too long (max ${GREP_PATTERN_MAX_LENGTH} characters)`);
+    }
+    // Regex semantics by default — what the tool schema always promised.
+    // literal=1 opts back into the escaped-substring behaviour of the
+    // literal-only era for callers that want it verbatim.
+    const caseSensitive = isFlagTrue(query.caseSensitive, 'caseSensitive');
+    const flags = caseSensitive ? '' : 'i';
+    let regex;
+    try {
+        // Deliberately no 'g' flag: the handler tests line-by-line and a
+        // stateful lastIndex across lines would skip matches (the old handler
+        // had to reset it manually). No 'm' either: each test receives a
+        // single line, so ^/$ already anchor at string boundaries — 'm'
+        // would be a no-op.
+        if (isFlagTrue(query.literal, 'literal')) {
+            regex = new RegExp(escapeRegExp(pattern), flags);
+        }
+        else {
+            // Intentional: /api/grep advertises real regex (see file header + SECURITY.md).
+            // ReDoS is mitigated by running the scan in a worker and terminate()-ing it.
+            // codeql[js/regex-injection]
+            regex = new RegExp(pattern, flags);
+        }
+    }
+    catch {
+        throw new BadRequestError('Invalid regex pattern');
+    }
+    // Path-substring filter, case-insensitive ("Controller.java", "src/api").
+    const fileFilter = assertString(query.fileFilter ?? '', 'fileFilter').toLowerCase();
+    const parsedLimit = Number(query.limit ?? GREP_DEFAULT_LIMIT);
+    const limit = Number.isFinite(parsedLimit)
+        ? Math.max(1, Math.min(GREP_MAX_LIMIT, Math.trunc(parsedLimit)))
+        : GREP_DEFAULT_LIMIT;
+    return { regex, fileFilter, limit };
+}

package/dist/server/grep-scan.d.ts

@@ -0,0 +1,23 @@
+export interface GrepHit {
+    filePath: string;
+    line: number;
+    text: string;
+}
+export interface GrepScanInput {
+    repoRoot: string;
+    /** Repo-relative paths already filtered by fileFilter. */
+    filePaths: string[];
+    pattern: string;
+    flags: string;
+    limit: number;
+    /** Absolute Date.now() deadline. */
+    deadlineMs: number;
+}
+export interface GrepScanResult {
+    results: GrepHit[];
+    timedOut: boolean;
+}
+export type GrepProgress = (partial: GrepScanResult) => void;
+export declare function scanGrepFiles(input: GrepScanInput, onProgress?: GrepProgress): Promise<GrepScanResult>;
+export declare function grepWorkerPath(): string;
+export declare function runGrepScanInWorker(input: GrepScanInput): Promise<GrepScanResult>;

package/dist/server/grep-scan.js

@@ -0,0 +1,107 @@
+/**
+ * Filesystem grep scan used by GET /api/grep.
+ *
+ * Matching runs in a worker_threads worker (see grep-worker.ts) so a
+ * catastrophic `regex.test()` can be killed with terminate() when the
+ * wall-clock budget expires. The parent event loop stays responsive.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+export async function scanGrepFiles(input, onProgress) {
+    const regex = new RegExp(input.pattern, input.flags);
+    const results = [];
+    const repoRoot = path.resolve(input.repoRoot);
+    const safeRepoRoot = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep;
+    let timedOut = false;
+    files: for (const filePath of input.filePaths) {
+        if (results.length >= input.limit)
+            break;
+        if (Date.now() > input.deadlineMs) {
+            timedOut = true;
+            break;
+        }
+        const fullPath = path.resolve(repoRoot, filePath);
+        if (!fullPath.startsWith(safeRepoRoot) && fullPath !== repoRoot)
+            continue;
+        let content;
+        try {
+            content = await fs.readFile(fullPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (results.length >= input.limit)
+                break files;
+            if ((i & 255) === 0 && Date.now() > input.deadlineMs) {
+                timedOut = true;
+                break files;
+            }
+            regex.lastIndex = 0;
+            if (regex.test(lines[i])) {
+                results.push({ filePath, line: i + 1, text: lines[i].trim().slice(0, 200) });
+            }
+        }
+        onProgress?.({ results: results.slice(), timedOut });
+    }
+    return { results, timedOut };
+}
+const _require = createRequire(import.meta.url);
+export function grepWorkerPath() {
+    const callerPath = fileURLToPath(import.meta.url);
+    const isDev = callerPath.endsWith('.ts');
+    return path.join(path.dirname(callerPath), isDev ? 'grep-worker.ts' : 'grep-worker.js');
+}
+export function runGrepScanInWorker(input) {
+    const callerPath = fileURLToPath(import.meta.url);
+    const isDev = callerPath.endsWith('.ts');
+    const tsxHookArgs = isDev
+        ? ['--import', pathToFileURL(_require.resolve('tsx/esm')).href]
+        : [];
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let latest = { results: [], timedOut: false };
+        const worker = new Worker(grepWorkerPath(), {
+            workerData: input,
+            execArgv: tsxHookArgs,
+        });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            resolve(result);
+        };
+        const remain = Math.max(1, input.deadlineMs - Date.now());
+        const timer = setTimeout(() => {
+            finish({ results: latest.results, timedOut: true });
+        }, remain);
+        worker.on('message', (msg) => {
+            if (msg.type === 'progress') {
+                latest = { results: msg.results, timedOut: msg.timedOut };
+                return;
+            }
+            if (msg.type === 'done') {
+                finish({ results: msg.results, timedOut: msg.timedOut });
+            }
+        });
+        worker.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            reject(err);
+        });
+        worker.on('exit', () => {
+            if (settled)
+                return;
+            finish({ results: latest.results, timedOut: true });
+        });
+    });
+}

package/dist/server/grep-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/grep-worker.js

@@ -0,0 +1,12 @@
+import { parentPort, workerData } from 'node:worker_threads';
+if (!parentPort) {
+    throw new Error('grep-worker must run as a worker_threads worker');
+}
+const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+const { scanGrepFiles } = await import(new URL(`./grep-scan${ext}`, import.meta.url).href);
+const port = parentPort;
+const input = workerData;
+const out = await scanGrepFiles(input, (partial) => {
+    port.postMessage({ type: 'progress', ...partial });
+});
+port.postMessage({ type: 'done', ...out });

package/dist/server/mcp-http.d.ts

@@ -9,4 +9,12 @@
  */
 import type { Express } from 'express';
 import type { LocalBackend } from '../mcp/local/local-backend.js';
+/**
+ * Protect serve's /api/mcp route when the shared MCP bearer token is configured.
+ *
+ * This middleware must be installed before Express's global JSON parser so an
+ * unauthenticated request body is rejected before it is parsed. The standalone
+ * `gitnexus mcp --http` server resolves the same environment variable.
+ */
+export declare function installServeMcpAuth(app: Express, env?: NodeJS.ProcessEnv): boolean;
 export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): Promise<() => Promise<void>>;

package/dist/server/mcp-http.js

@@ -7,9 +7,24 @@
  *
  * Used by server/api.ts to wire up the full web server.
  */
-import { createStreamableHttpHandler } from '../mcp/http-transport.js';
+import { createAuthMiddleware, createStreamableHttpHandler, resolveAuthToken, } from '../mcp/http-transport.js';
 import { createMcpRepositoryPolicy } from '../mcp/repository-policy.js';
 import { logger } from '../core/logger.js';
+/**
+ * Protect serve's /api/mcp route when the shared MCP bearer token is configured.
+ *
+ * This middleware must be installed before Express's global JSON parser so an
+ * unauthenticated request body is rejected before it is parsed. The standalone
+ * `gitnexus mcp --http` server resolves the same environment variable.
+ */
+export function installServeMcpAuth(app, env = process.env) {
+    const authToken = resolveAuthToken(undefined, env);
+    if (!authToken)
+        return false;
+    app.use('/api/mcp', createAuthMiddleware(authToken));
+    logger.info('Bearer authentication enabled for serve /api/mcp');
+    return true;
+}
 export async function mountMCPEndpoints(app, backend) {
     const repositoryPolicy = await createMcpRepositoryPolicy(backend);
     const { handler, cleanup } = createStreamableHttpHandler(backend, { repositoryPolicy });