gitnexus 1.6.11-rc.19 → 1.6.11-rc.20

package/dist/core/group/cross-impact.d.ts

@@ -62,6 +62,9 @@ export declare function validateGroupImpactParams(params: Record<string, unknown
     name: string;
     repoPath: string;
     target: string;
+    target_uid?: string;
+    file_path?: string;
+    kind?: string;
     direction: 'upstream' | 'downstream';
     maxDepth: number;
     crossDepth: number;

package/dist/core/group/cross-impact.js

@@ -103,13 +103,21 @@ export function clampTimeout(timeoutMs) {
 export function validateGroupImpactParams(params) {
     const name = String(params.name ?? '').trim();
     const repoPath = String(params.repo ?? '').trim();
-    const target = String(params.target ?? '').trim();
+    // Optional string, same helper shape as cross-trace's `str()`: empty/blank
+    // counts as absent so `target_uid: ''` degrades to the name lookup rather
+    // than a zero-ambiguity lookup of the empty uid. Parsed before the required
+    // check so UID-only callers (MCP impact schema requires `direction`, not
+    // `target`) are accepted.
+    const str = (v) => typeof v === 'string' && v.trim() !== '' ? v : undefined;
+    const targetName = String(params.target ?? '').trim();
+    const target_uidEarly = str(params.target_uid);
     if (!name)
         return { ok: false, error: 'name is required' };
     if (!repoPath)
         return { ok: false, error: 'repo is required (group repo path, e.g. app/backend)' };
-    if (!target)
-        return { ok: false, error: 'target is required' };
+    if (!targetName && !target_uidEarly)
+        return { ok: false, error: 'target or target_uid is required' };
+    const target = targetName || target_uidEarly;
     if (params.service !== undefined &&
         params.service !== null &&
         String(params.service).trim() === '') {
@@ -133,6 +141,9 @@ export function validateGroupImpactParams(params) {
         minConfidence = 1;
     const service = normalizeServicePrefix(params.service);
     const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+    const target_uid = target_uidEarly;
+    const file_path = str(params.file_path);
+    const kind = str(params.kind);
     // Clamp at the validate boundary so the downstream `deadline` (line
     // ~366) and `safeLocalImpact`'s `setTimeout` both see a single
     // bounded value. Without this, the outer deadline budgeted Phase-2
@@ -150,6 +161,9 @@ export function validateGroupImpactParams(params) {
         name,
         repoPath,
         target,
+        target_uid,
+        file_path,
+        kind,
         direction,
         maxDepth,
         crossDepth,
@@ -448,7 +462,7 @@ export async function runGroupImpact(deps, params) {
     const parsed = validateGroupImpactParams(params);
     if (parsed.ok === false)
         return { error: parsed.error };
-    const { name, repoPath, target, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
+    const { name, repoPath, target, target_uid, file_path, kind, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
     const groupDir = getGroupDir(deps.gitnexusDir, name);
     let config;
     try {
@@ -464,6 +478,14 @@ export async function runGroupImpact(deps, params) {
         return { error: resolved.error };
     const impactParams = {
         target,
+        // Selector params pass through to the member repo's impact (the port
+        // contract in service.ts documents them), so the single-repo tool's
+        // "re-call with target_uid to disambiguate" loop works unchanged in
+        // group mode. `undefined` keeps the call shape flat — same convention
+        // as the relationTypes line below.
+        target_uid,
+        file_path,
+        kind,
         direction,
         maxDepth,
         relationTypes: relationTypes && relationTypes.length > 0 ? relationTypes : undefined,

package/dist/core/group/normalization.d.ts

@@ -1,3 +1,40 @@
-import type { CrossLink, StoredContract } from './types.js';
+import type { CrossLink, CrossLinkEndpoint, StoredContract } from './types.js';
+/**
+ * True when a link endpoint carries no resolved graph symbol — empty
+ * `symbolUid` or a missing/empty `symbolRef`.
+ *
+ * Sync marks a cross-link `degraded: true` when this holds for the PROVIDER
+ * endpoint (`to`): the contract boundary is proven, but the empty uid can
+ * never match a Phase-1 impact symbol id, so cross-repo fan-out across the
+ * link silently yields nothing (the classic case is a provider whose handler
+ * failed to resolve, leaving `symbolName` degraded to the file name with one
+ * pseudo-symbol carrying every route in that file). Consumer-side (`from`)
+ * emptiness is deliberately NOT degraded — several extractors (topics, grpc)
+ * legitimately emit consumer contracts without a per-call symbol, and the
+ * anchor that matters for far-side fan-out is the provider's.
+ *
+ * Kept next to the endpoint merge logic because `dedupeCrossLinks` must
+ * re-derive the flag after a merge: `mergeEndpoints` backfills `symbolUid`
+ * from the losing twin, which can invalidate a flag carried in from the winner.
+ *
+ * NOT unresolved: a deterministic `manifest::<repo>::<contractId>` synthetic
+ * uid (see `manifestSymbolUid`). Manifest endpoints fall back to it precisely
+ * when the graph has no symbol for them — its empty `symbolRef.filePath` would
+ * otherwise trip the check below — yet cross-impact anchors those links by
+ * design (#2722: the crossing is preserved with `fanout_status:
+ * 'not_attempted'` instead of silently yielding cross=0). The prefix is the
+ * canonical discriminator — real indexer uids never start with `manifest::`
+ * — and `cross-impact.ts` branches on the same test. Encoding the exemption
+ * HERE (not at the sync marking call site) keeps marking and the post-merge
+ * re-derivation from drifting apart, and keeps the flag's meaning exactly what
+ * `types.ts` documents: "distinct from manifest::… synthetic UIDs".
+ */
+export declare function isUnresolvedEndpoint(endpoint: CrossLinkEndpoint): boolean;
+/**
+ * Derive `degraded` from the provider endpoint. Present (`true`) only when
+ * unresolved; deleted otherwise so contracts.json stays "carried only when
+ * meaningful" (`'degraded' in link === false` for anchored links).
+ */
+export declare function applyDegradedFlag(link: CrossLink): CrossLink;
 export declare function dedupeContracts(items: StoredContract[]): StoredContract[];
 export declare function dedupeCrossLinks(items: CrossLink[]): CrossLink[];

package/dist/core/group/normalization.js

@@ -83,6 +83,59 @@ function crossLinkKey(link) {
         endpointKey(link.to),
     ].join('\0');
 }
+/**
+ * True when a link endpoint carries no resolved graph symbol — empty
+ * `symbolUid` or a missing/empty `symbolRef`.
+ *
+ * Sync marks a cross-link `degraded: true` when this holds for the PROVIDER
+ * endpoint (`to`): the contract boundary is proven, but the empty uid can
+ * never match a Phase-1 impact symbol id, so cross-repo fan-out across the
+ * link silently yields nothing (the classic case is a provider whose handler
+ * failed to resolve, leaving `symbolName` degraded to the file name with one
+ * pseudo-symbol carrying every route in that file). Consumer-side (`from`)
+ * emptiness is deliberately NOT degraded — several extractors (topics, grpc)
+ * legitimately emit consumer contracts without a per-call symbol, and the
+ * anchor that matters for far-side fan-out is the provider's.
+ *
+ * Kept next to the endpoint merge logic because `dedupeCrossLinks` must
+ * re-derive the flag after a merge: `mergeEndpoints` backfills `symbolUid`
+ * from the losing twin, which can invalidate a flag carried in from the winner.
+ *
+ * NOT unresolved: a deterministic `manifest::<repo>::<contractId>` synthetic
+ * uid (see `manifestSymbolUid`). Manifest endpoints fall back to it precisely
+ * when the graph has no symbol for them — its empty `symbolRef.filePath` would
+ * otherwise trip the check below — yet cross-impact anchors those links by
+ * design (#2722: the crossing is preserved with `fanout_status:
+ * 'not_attempted'` instead of silently yielding cross=0). The prefix is the
+ * canonical discriminator — real indexer uids never start with `manifest::`
+ * — and `cross-impact.ts` branches on the same test. Encoding the exemption
+ * HERE (not at the sync marking call site) keeps marking and the post-merge
+ * re-derivation from drifting apart, and keeps the flag's meaning exactly what
+ * `types.ts` documents: "distinct from manifest::… synthetic UIDs".
+ */
+export function isUnresolvedEndpoint(endpoint) {
+    if (endpoint.symbolUid.startsWith('manifest::'))
+        return false;
+    return (!endpoint.symbolUid ||
+        !endpoint.symbolRef ||
+        !endpoint.symbolRef.filePath ||
+        !endpoint.symbolRef.name);
+}
+/**
+ * Derive `degraded` from the provider endpoint. Present (`true`) only when
+ * unresolved; deleted otherwise so contracts.json stays "carried only when
+ * meaningful" (`'degraded' in link === false` for anchored links).
+ */
+export function applyDegradedFlag(link) {
+    const next = { ...link };
+    if (isUnresolvedEndpoint(next.to)) {
+        next.degraded = true;
+    }
+    else {
+        delete next.degraded;
+    }
+    return next;
+}
 export function dedupeContracts(items) {
     const deduped = new Map();
     for (const contract of items) {
@@ -104,12 +157,15 @@ export function dedupeCrossLinks(items) {
         const keepIncoming = link.confidence > existing.confidence;
         const primary = keepIncoming ? link : existing;
         const secondary = keepIncoming ? existing : link;
-        deduped.set(key, {
+        const merged = {
             ...primary,
             confidence: Math.max(existing.confidence, link.confidence),
             from: mergeEndpoints(primary.from, secondary.from),
             to: mergeEndpoints(primary.to, secondary.to),
-        });
+        };
+        // Re-derive after mergeEndpoints: a richer twin can backfill `to.symbolUid`
+        // and must not leave a stale `degraded` flag on an now-anchored link.
+        deduped.set(key, applyDegradedFlag(merged));
     }
-    return [...deduped.values()];
+    return [...deduped.values()].map(applyDegradedFlag);
 }

package/dist/core/group/service.d.ts

@@ -15,6 +15,17 @@ export interface GroupToolPort {
     resolveRepo(repoParam?: string): Promise<GroupRepoHandle>;
     impact(repo: GroupRepoHandle, params: {
         target: string;
+        /**
+         * Target-selector params, same semantics as the single-repo `impact`
+         * tool: `target_uid` is the zero-ambiguity lookup (it wins over the
+         * name), `file_path`/`kind` narrow a name shared by several symbols
+         * (e.g. same-named Api/Impl/Controller layers). The port implementation
+         * consumes them directly; the Phase-1 caller in cross-impact.ts is
+         * responsible for threading them from the MCP `impact` args.
+         */
+        target_uid?: string;
+        file_path?: string;
+        kind?: string;
         direction: 'upstream' | 'downstream';
         maxDepth?: number;
         relationTypes?: string[];

package/dist/core/group/service.js

@@ -341,6 +341,14 @@ export class GroupService {
             // can otherwise see contract counts that disagree with this payload, with
             // nothing here explaining why the write was skipped.
             registryOutcome: result.registryOutcome,
+            // Data-quality signals surfaced from the sync run: links whose provider
+            // endpoint never resolved to a graph symbol, per-repo extraction
+            // failures with reasons, and operator warnings (e.g. bridge.lbug write
+            // failed after contracts.json was written). Always present so MCP
+            // consumers can branch on them without existence checks.
+            degradedLinks: result.degradedLinks,
+            failedRepos: result.failedRepos,
+            warnings: result.warnings,
         };
     }
     async groupContracts(params) {

package/dist/core/group/sync.d.ts

@@ -47,6 +47,27 @@ export interface SyncResult {
      * none of that repo's contracts are in `contracts`.
      */
     unreadableRepos: string[];
+    /**
+     * Cross-links whose provider endpoint has no resolved graph symbol
+     * (`degraded: true` on the link — see `isUnresolvedEndpoint`). The boundary
+     * is proven but cross-impact fan-out cannot anchor it; the usual remedy is
+     * re-analyzing the provider repo so its handlers resolve.
+     */
+    degradedLinks: number;
+    /**
+     * Repos whose per-repo extraction threw (init, an extractor, or the
+     * snapshot read). Each still lands in `unreadableRepos` (group path) —
+     * unchanged downstream semantics — but carries its failure reason here: the
+     * catch used to swallow the exception, leaving contracts already pushed by
+     * earlier extractors in this iteration as silent half-repo data. `repo` is
+     * that same group path (e.g. `app/backend`), not the registry display name.
+     */
+    failedRepos: Array<{
+        repo: string;
+        reason: string;
+    }>;
+    /** Operator-facing run warnings (e.g. bridge.lbug write failed after contracts.json was written). */
+    warnings: string[];
     repoSnapshots: Record<string, RepoSnapshot>;
     /**
      * Matching stages this run was asked to skip. Populated on EVERY outcome,

package/dist/core/group/sync.js

@@ -13,6 +13,7 @@ import { ManifestExtractor } from './extractors/manifest-extractor.js';
 import { discoverWorkspaceLinks } from './extractors/workspace-extractor.js';
 import { buildProviderIndex, runExactMatch, runWildcardMatch } from './matching.js';
 import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { applyDegradedFlag } from './normalization.js';
 import { getContractRegistryPath, readContractRegistry, writeContractRegistry } from './storage.js';
 import { markBridgeProvenanceUnknown, refreshPreservedBridgeMeta, writeBridgeUnlocked, } from './bridge-db.js';
 import { withGroupSyncLock } from './group-lock.js';
@@ -127,6 +128,8 @@ export function partitionManifestWindows(links, knownRepos, maxResident) {
 }
 export async function syncGroup(config, opts) {
     const missingRepos = [];
+    const failedRepos = [];
+    const warnings = [];
     // Repos that ARE registered but that we could not extract from — the index
     // would not open, or an extractor threw partway and the repo's staged
     // contracts were dropped. Kept separate from `missingRepos` because the two
@@ -309,6 +312,10 @@ export async function syncGroup(config, opts) {
                     // stack before logging it defeats the point.
                     logger.warn({ err, repo: regName, groupPath, lbugPath }, "⚠️ Could not read this repo's index; its contracts are omitted from this sync.");
                     unreadableRepos.push(groupPath);
+                    failedRepos.push({
+                        repo: groupPath,
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
                     // Forget the handle recorded above (present only if the failure came
                     // after initLbug). Deferred manifest resolution derives its known-repo
                     // set from this map, so leaving the entry here re-opens a repo this
@@ -459,7 +466,7 @@ export async function syncGroup(config, opts) {
     // manifest-declared link can also emit a matchType:'exact' CrossLink with the
     // same endpoints. Prefer the manifest version — it reflects operator intent
     // and carries matchType:'manifest' which downstream consumers may rely on.
-    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]);
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]).map(applyDegradedFlag);
     const allContracts = autoContracts;
     const registry = {
         version: 1,
@@ -671,10 +678,12 @@ export async function syncGroup(config, opts) {
                             'a lower bound rather than as complete.'
                         : 'Its metadata could NOT be marked provenance-unknown, so those answers may still ' +
                             'report as complete despite describing an older sync.';
-                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
+                    const writeBridgeWarn = '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
                         'but bridge.lbug was not replaced: cross-repo queries may still answer from ' +
                         `the previous sync's contracts. ${provenanceNote} ` +
-                        'Re-run `gitnexus group sync` to retry.');
+                        'Re-run `gitnexus group sync` to retry.';
+                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, writeBridgeWarn);
+                    warnings.push(writeBridgeWarn);
                 }
             }
         });
@@ -686,6 +695,9 @@ export async function syncGroup(config, opts) {
         unmatched: wildcard.remaining,
         missingRepos,
         unreadableRepos,
+        failedRepos,
+        warnings,
+        degradedLinks: crossLinks.filter((l) => l.degraded === true).length,
         repoSnapshots,
         registryOutcome,
     };

package/dist/core/group/types.d.ts

@@ -80,6 +80,19 @@ export interface CrossLink {
     contractId: string;
     matchType: MatchType;
     confidence: number;
+    /**
+     * `true` when the PROVIDER endpoint (`to`) has no resolved graph symbol —
+     * empty `symbolUid` / `symbolRef` at sync time (e.g. the handler failed to
+     * resolve and `symbolName` degraded to the file name). The contract boundary
+     * is still proven, but the link cannot anchor a cross-impact fan-out: an
+     * empty provider uid never matches a Phase-1 symbol id, and a downstream
+     * fan-out into it has no neighbor symbol to resolve. Derived once at the
+     * sync persistence boundary (`isUnresolvedEndpoint` in normalization.ts) and
+     * re-derived by `dedupeCrossLinks` when a merge backfills the uid. Absent on
+     * fully-anchored links. Distinct from manifest `manifest::…` synthetic UIDs,
+     * which have their own `fanout_status: 'not_attempted'` channel downstream.
+     */
+    degraded?: boolean;
 }
 export interface RepoSnapshot {
     indexedAt: string;

package/dist/mcp/local/local-backend.js

@@ -6783,6 +6783,17 @@ export class LocalBackend {
                 target: params.target,
                 direction: params.direction,
             };
+            // Forward the target-selector params like the trace branch above.
+            // @group impact used to drop target_uid/file_path/kind here, so a name
+            // shared by same-named Api/Impl/Controller layers resolved ambiguously
+            // in the member repo and the documented "re-call with target_uid"
+            // disambiguation loop (impact tool schema) never worked in group mode.
+            if (typeof params.target_uid === 'string')
+                impactArgs.target_uid = params.target_uid;
+            if (typeof params.file_path === 'string')
+                impactArgs.file_path = params.file_path;
+            if (typeof params.kind === 'string')
+                impactArgs.kind = params.kind;
             if (params.maxDepth !== undefined)
                 impactArgs.maxDepth = params.maxDepth;
             if (params.crossDepth !== undefined)

package/dist/mcp/tools.js

@@ -804,7 +804,7 @@ WHEN TO USE: Discover groups before group_sync. Optional "name" returns a single
 
 WHEN TO USE: After changing group.yaml or re-indexing member repos.
 
-READ THE RESULT: \`missingRepos\` are configured repos with no entry in the registry (index them, or drop them from group.yaml); \`unreadableRepos\` ARE registered but this sync could not extract from them — the index would not open (version skew, lock, corruption), or an extractor failed partway — so NONE of their contracts are in this sync and a following group_impact / group_contracts is a lower bound, not a verdict. \`registryOutcome\` says what happened to the file, and the three values a call here can return each need a different response: 'written' — this run's contracts replaced contracts.json; 'preserved' — nothing could be read, so contracts.json was rewritten keeping the previous sync's contracts and cross-links verbatim and refreshing only \`missingRepos\`/\`unreadableRepos\` to describe THIS run (the file changed, the contracts in it did not, and they are as old as the last sync that succeeded); 'superseded' — nothing could be read, and another sync replaced contracts.json while this one waited for the group lock; that file was left untouched and this run's lists were NOT recorded, because they describe an older group state than what is on disk (so the registry is fresher than this response's diagnostics, not staler); 'no-prior-registry' — nothing could be read AND there was no previous contracts.json to carry forward, so none was written and this group has no contract registry on disk. Only 'no-prior-registry' means there is nothing to read: after it, group_contracts / group_impact have no registry at all rather than a stale one, so fix the repos above and re-run before trusting either. \`suppressedMatchStages\` names matching stages this sync was ASKED to skip, with the same three states as the repo lists: ABSENT means a registry written before the field existed, \`[]\` means this sync suppressed nothing, and a populated list means the cross-link set is a lower bound BY REQUEST — a later group_impact / group_contracts on it reports truncationReason 'suppressed-stage'.\n\nPARAMETERS ARE VALIDATED: \`exactOnly\` must be a real boolean — the string "false" is rejected, not coerced to true. The retired \`skipEmbeddings\` and \`allowStale\` parameters are refused by name; drop them from the call.`,
+READ THE RESULT: \`missingRepos\` are configured repos with no entry in the registry (index them, or drop them from group.yaml); \`unreadableRepos\` ARE registered but this sync could not extract from them — the index would not open (version skew, lock, corruption), or an extractor failed partway — so NONE of their contracts are in this sync and a following group_impact / group_contracts is a lower bound, not a verdict. \`degradedLinks\` is the count of persisted cross-links whose provider endpoint has no resolved graph symbol (\`degraded: true\`); re-analyze the provider so handlers resolve. \`failedRepos\` is \`{ repo, reason }[]\` for per-repo extraction throws — each also appears in \`unreadableRepos\`; \`repo\` is that group path (e.g. app/backend), not the registry display name. \`warnings\` are operator-facing run notes (e.g. bridge.lbug write failed after contracts.json was written); \`[]\` means none this run. \`registryOutcome\` says what happened to the file, and the three values a call here can return each need a different response: 'written' — this run's contracts replaced contracts.json; 'preserved' — nothing could be read, so contracts.json was rewritten keeping the previous sync's contracts and cross-links verbatim and refreshing only \`missingRepos\`/\`unreadableRepos\` to describe THIS run (the file changed, the contracts in it did not, and they are as old as the last sync that succeeded); 'superseded' — nothing could be read, and another sync replaced contracts.json while this one waited for the group lock; that file was left untouched and this run's lists were NOT recorded, because they describe an older group state than what is on disk (so the registry is fresher than this response's diagnostics, not staler); 'no-prior-registry' — nothing could be read AND there was no previous contracts.json to carry forward, so none was written and this group has no contract registry on disk. Only 'no-prior-registry' means there is nothing to read: after it, group_contracts / group_impact have no registry at all rather than a stale one, so fix the repos above and re-run before trusting either. \`suppressedMatchStages\` names matching stages this sync was ASKED to skip, with the same three states as the repo lists: ABSENT means a registry written before the field existed, \`[]\` means this sync suppressed nothing, and a populated list means the cross-link set is a lower bound BY REQUEST — a later group_impact / group_contracts on it reports truncationReason 'suppressed-stage'.\n\nPARAMETERS ARE VALIDATED: \`exactOnly\` must be a real boolean — the string "false" is rejected, not coerced to true. The retired \`skipEmbeddings\` and \`allowStale\` parameters are refused by name; drop them from the call.`,
         // Usually writes contracts.json, so conservatively non-idempotent even
         // though output is deterministic for identical input. When no configured
         // repo could be read it still rewrites the file, keeping the previous

package/dist/server/api.js

@@ -27,7 +27,9 @@ 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';
@@ -1129,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>;