gitnexus 1.6.9-rc.34 → 1.6.9-rc.36

package/README.md

@@ -357,13 +357,14 @@ npm install -g gitnexus
 
 GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
 
-Configure the behavior with two environment variables:
+Configure the behavior with these environment variables:
 
 | Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                   |
 | -------------------------------------------- | ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                       |
 | `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                            |
 | `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.              |
+| `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`             | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. |
 
 ```bash
@@ -375,6 +376,11 @@ GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
 
 # CJK-heavy codebase: rebuild keyword indexes without English stemming
 GITNEXUS_FTS_STEMMER=none npx gitnexus analyze --repair-fts
+
+# CJK-heavy codebase: enable sub-phrase search over Chinese/Japanese Han text.
+# On an already-indexed repo, the first run after enabling this MUST be --force —
+# --repair-fts and plain incremental `analyze` both leave old files un-segmented.
+GITNEXUS_FTS_CJK_SEGMENTATION=bigram npx gitnexus analyze --force
 ```
 
 ### Analysis runs out of memory

package/dist/core/lbug/csv-generator.d.ts

@@ -3,7 +3,7 @@
  *
  * Streams CSV rows directly to disk files in a single pass over graph nodes.
  * File contents are lazy-read from disk per-node to avoid holding the entire
- * repo in RAM. Rows are buffered (FLUSH_EVERY) before writing to minimize
+ * repo in RAM. Rows are buffered (FLUSH_BYTES) before writing to minimize
  * per-row Promise overhead.
  *
  * RFC 4180 Compliant:
@@ -14,10 +14,69 @@
 import type { GraphNode, GraphRelationship } from '../../_shared/index.js';
 import { KnowledgeGraph } from '../graph/types.js';
 import { NodeTableName } from './schema.js';
+/**
+ * Flush buffered rows to disk once the buffered chunk reaches this many bytes.
+ * Byte-bounded rather than row-count-bounded: row size ranges from a few dozen
+ * bytes (typical symbol/relationship rows) up to a full File's content
+ * (#2317/#2323), so a row-count-only cap lets a handful of huge rows build an
+ * unbounded `buffer.join('\n')` string before ever tripping it.
+ *
+ * Not an env knob — fixed by a safety margin, not a preference. The one worst
+ * case that matters: one more oversized row lands right after the buffer was
+ * just under this threshold, before the flush fires. That row is capped at
+ * TREE_SITTER_MAX_BUFFER (32MB, hard-clamped — GITNEXUS_MAX_FILE_SIZE cannot
+ * raise it). Two transforms can each grow it before it reaches the buffer:
+ * `applyCjkSegmentationIfEnabled` (#2331, `CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR`
+ * on an all-CJK row when `GITNEXUS_FTS_CJK_SEGMENTATION=bigram` — the single
+ * source of truth for that ratio, imported by the paired test) and
+ * `escapeCSVField`'s worst-case quote-doubling (2x). So the peak joined-string
+ * size is bounded by
+ *   FLUSH_BYTES + 2 * CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR * TREE_SITTER_MAX_BUFFER
+ *     ≈ 8MB + 149MB ≈ 157MB,
+ * versus Node's `buffer.constants.MAX_STRING_LENGTH` (~512MB) — the test
+ * actually enforces half of that (~256MB), for a ~1.63x margin (see the
+ * `shouldFlushCSVBuffer stays within the V8 string-length ceiling` test,
+ * which fails loudly if any of these constants ever moves this margin the
+ * wrong way). With segmentation disabled (default), the old ~3.56x margin
+ * still applies. Raising FLUSH_BYTES trades fewer/larger flushes for less
+ * margin; lowering it trades the reverse for lower peak transient memory.
+ * Change the constant directly if a real workload needs a different point on
+ * that curve — a per-host env var would let the margin get silently
+ * reintroduced by an operator with no way to know why 512MB is dangerous.
+ */
+export declare const FLUSH_BYTES: number;
+export declare const shouldFlushCSVBuffer: (byteCount: number) => boolean;
 export declare const sanitizeUTF8: (str: string) => string;
 export declare const escapeCSVField: (value: string | number | undefined | null) => string;
 export declare const escapeCSVNumber: (value: number | undefined | null, defaultValue?: number) => string;
 export declare const isBinaryContent: (content: string) => boolean;
+/**
+ * Flatten newlines and tabs to single spaces for FTS-indexed text columns
+ * (`content`, `description`) — the real fix for #2317.
+ *
+ * Ladybug's full-text-search tokenizer splits ONLY on the space character —
+ * `\n`, `\r`, and `\t` are NOT token delimiters. So multiline text indexes as
+ * a handful of giant tokens (each whole line, joined across lines), and a
+ * word query matches none of them: `searchFTSFromLbug('foo')` misses a file
+ * whose content is `... \nfoo\n ...`. Removing the 10KB cap (#2333/#2317)
+ * stores the full body but leaves it unsearchable; collapsing intra-text
+ * whitespace to spaces is what actually makes every word searchable.
+ *
+ * This rewrites the STORED column too (the same value is COPYed in), so File
+ * content returned via the graph API is space-flattened — an accepted trade
+ * for making file/symbol text searchable. Leading/trailing/empty are no-ops.
+ *
+ * Callers apply `applyCjkSegmentationIfEnabled` (#2331) to the text *before*
+ * this flatten, so a CJK phrase split across a line-wrap loses its boundary
+ * bigram (run detection resets at whitespace) — an accepted limitation, see
+ * the plan's Scope Boundaries.
+ *
+ * Exported (#2339) so `bm25-index.ts`'s query path can compose it in the
+ * same order on incoming search queries, keeping index-time and query-time
+ * text transforms symmetric — a literal tab/newline in a query would
+ * otherwise fail to match whitespace-normalized indexed content.
+ */
+export declare const normalizeFtsText: (text: string) => string;
 /** Canonical relationship CSV header — shared by the emit pass and the
  * `splitRelCsvByLabelPair` differential oracle. */
 export declare const REL_CSV_HEADER = "from,to,type,confidence,reason,step";

package/dist/core/lbug/csv-generator.js

@@ -3,7 +3,7 @@
  *
  * Streams CSV rows directly to disk files in a single pass over graph nodes.
  * File contents are lazy-read from disk per-node to avoid holding the entire
- * repo in RAM. Rows are buffered (FLUSH_EVERY) before writing to minimize
+ * repo in RAM. Rows are buffered (FLUSH_BYTES) before writing to minimize
  * per-row Promise overhead.
  *
  * RFC 4180 Compliant:
@@ -17,6 +17,7 @@ import path from 'path';
 import { NODE_TABLES } from './schema.js';
 import { RelPairRouter } from './rel-pair-routing.js';
 import { parseTruthyEnv } from '../ingestion/utils/env.js';
+import { applyCjkSegmentationIfEnabled } from '../search/cjk-segmentation.js';
 /**
  * Deterministic output ordering — optional (out-of-core / windowed-resolve
  * enabler). When `GITNEXUS_SORT_GRAPH_OUTPUT` is set, nodes and relationships
@@ -31,8 +32,38 @@ import { parseTruthyEnv } from '../ingestion/utils/env.js';
 const byGraphId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
 const orderedNodes = (graph, sorted) => sorted ? [...graph.iterNodes()].sort(byGraphId) : graph.iterNodes();
 const orderedRelationships = (graph, sorted) => sorted ? [...graph.iterRelationships()].sort(byGraphId) : graph.iterRelationships();
-/** Flush buffered rows to disk every N rows */
-const FLUSH_EVERY = 500;
+/**
+ * Flush buffered rows to disk once the buffered chunk reaches this many bytes.
+ * Byte-bounded rather than row-count-bounded: row size ranges from a few dozen
+ * bytes (typical symbol/relationship rows) up to a full File's content
+ * (#2317/#2323), so a row-count-only cap lets a handful of huge rows build an
+ * unbounded `buffer.join('\n')` string before ever tripping it.
+ *
+ * Not an env knob — fixed by a safety margin, not a preference. The one worst
+ * case that matters: one more oversized row lands right after the buffer was
+ * just under this threshold, before the flush fires. That row is capped at
+ * TREE_SITTER_MAX_BUFFER (32MB, hard-clamped — GITNEXUS_MAX_FILE_SIZE cannot
+ * raise it). Two transforms can each grow it before it reaches the buffer:
+ * `applyCjkSegmentationIfEnabled` (#2331, `CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR`
+ * on an all-CJK row when `GITNEXUS_FTS_CJK_SEGMENTATION=bigram` — the single
+ * source of truth for that ratio, imported by the paired test) and
+ * `escapeCSVField`'s worst-case quote-doubling (2x). So the peak joined-string
+ * size is bounded by
+ *   FLUSH_BYTES + 2 * CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR * TREE_SITTER_MAX_BUFFER
+ *     ≈ 8MB + 149MB ≈ 157MB,
+ * versus Node's `buffer.constants.MAX_STRING_LENGTH` (~512MB) — the test
+ * actually enforces half of that (~256MB), for a ~1.63x margin (see the
+ * `shouldFlushCSVBuffer stays within the V8 string-length ceiling` test,
+ * which fails loudly if any of these constants ever moves this margin the
+ * wrong way). With segmentation disabled (default), the old ~3.56x margin
+ * still applies. Raising FLUSH_BYTES trades fewer/larger flushes for less
+ * margin; lowering it trades the reverse for lower peak transient memory.
+ * Change the constant directly if a real workload needs a different point on
+ * that curve — a per-host env var would let the margin get silently
+ * reintroduced by an operator with no way to know why 512MB is dangerous.
+ */
+export const FLUSH_BYTES = 8 * 1024 * 1024;
+export const shouldFlushCSVBuffer = (byteCount) => byteCount >= FLUSH_BYTES;
 /**
  * Yield the event loop every N relationship rows during the emit pass (#2226 F4)
  * so a concurrent node COPY (the overlap in loadGraphToLbug) and write-stream
@@ -127,6 +158,35 @@ class FileContentCache {
         this.accessOrder.push(key);
     }
 }
+/**
+ * Flatten newlines and tabs to single spaces for FTS-indexed text columns
+ * (`content`, `description`) — the real fix for #2317.
+ *
+ * Ladybug's full-text-search tokenizer splits ONLY on the space character —
+ * `\n`, `\r`, and `\t` are NOT token delimiters. So multiline text indexes as
+ * a handful of giant tokens (each whole line, joined across lines), and a
+ * word query matches none of them: `searchFTSFromLbug('foo')` misses a file
+ * whose content is `... \nfoo\n ...`. Removing the 10KB cap (#2333/#2317)
+ * stores the full body but leaves it unsearchable; collapsing intra-text
+ * whitespace to spaces is what actually makes every word searchable.
+ *
+ * This rewrites the STORED column too (the same value is COPYed in), so File
+ * content returned via the graph API is space-flattened — an accepted trade
+ * for making file/symbol text searchable. Leading/trailing/empty are no-ops.
+ *
+ * Callers apply `applyCjkSegmentationIfEnabled` (#2331) to the text *before*
+ * this flatten, so a CJK phrase split across a line-wrap loses its boundary
+ * bigram (run detection resets at whitespace) — an accepted limitation, see
+ * the plan's Scope Boundaries.
+ *
+ * Exported (#2339) so `bm25-index.ts`'s query path can compose it in the
+ * same order on incoming search queries, keeping index-time and query-time
+ * text transforms symmetric — a literal tab/newline in a query would
+ * otherwise fail to match whitespace-normalized indexed content.
+ */
+export const normalizeFtsText = (text) => text.replace(/[\r\n\t]+/g, ' ');
+/** Composes both FTS-text transforms for the `description` column — one place for the six emission sites below to call, instead of repeating the composition. */
+const formatFtsDescription = (description) => normalizeFtsText(applyCjkSegmentationIfEnabled(description));
 const extractContent = async (node, contentCache) => {
     const filePath = node.properties.filePath;
     const content = await contentCache.get(filePath);
@@ -136,11 +196,13 @@ const extractContent = async (node, contentCache) => {
         return '';
     if (isBinaryContent(content))
         return '[Binary file - content not stored]';
+    // File content is stored in full — intentionally NOT length-capped here, so
+    // text past the old 10KB cutoff stays FTS-searchable (#2317). It is already
+    // bounded upstream by the walker's max-file-size cap (512KB default / 32MB),
+    // and only whitespace-normalized for the tokenizer. The symbol snippet path
+    // below, by contrast, deliberately stays capped at MAX_SNIPPET.
     if (node.label === 'File') {
-        const MAX_FILE_CONTENT = 10000;
-        return content.length > MAX_FILE_CONTENT
-            ? content.slice(0, MAX_FILE_CONTENT) + '\n... [truncated]'
-            : content;
+        return normalizeFtsText(applyCjkSegmentationIfEnabled(content));
     }
     const startLine = node.properties.startLine;
     const endLine = node.properties.endLine;
@@ -151,9 +213,8 @@ const extractContent = async (node, contentCache) => {
     const end = Math.min(lines.length - 1, endLine + 2);
     const snippet = lines.slice(start, end + 1).join('\n');
     const MAX_SNIPPET = 5000;
-    return snippet.length > MAX_SNIPPET
-        ? snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]'
-        : snippet;
+    const capped = snippet.length > MAX_SNIPPET ? snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]' : snippet;
+    return normalizeFtsText(applyCjkSegmentationIfEnabled(capped));
 };
 // ============================================================================
 // BUFFERED CSV WRITER
@@ -161,15 +222,17 @@ const extractContent = async (node, contentCache) => {
 class BufferedCSVWriter {
     ws;
     buffer = [];
+    bufferedBytes = 0;
     rows = 0;
     constructor(filePath, header) {
         this.ws = createWriteStream(filePath, 'utf-8');
         // Large repos flush many times — raise listener cap to avoid MaxListenersExceededWarning
         this.ws.setMaxListeners(50);
         this.buffer.push(header);
+        this.bufferedBytes = Buffer.byteLength(header) + 1;
     }
     /**
-     * Buffer a row. Returns a promise ONLY when the buffer crossed FLUSH_EVERY
+     * Buffer a row. Returns a promise ONLY when the buffer crossed FLUSH_BYTES
      * and a disk write was issued; otherwise returns `undefined` so the caller
      * can skip awaiting (#2203 U3) — avoiding a microtask tick on every buffered
      * row (millions at scale). The flush promise still resolves on drain, so
@@ -177,8 +240,9 @@ class BufferedCSVWriter {
      */
     addRow(row) {
         this.buffer.push(row);
+        this.bufferedBytes += Buffer.byteLength(row) + 1;
         this.rows++;
-        if (this.buffer.length >= FLUSH_EVERY) {
+        if (shouldFlushCSVBuffer(this.bufferedBytes)) {
             return this.flush();
         }
         return undefined;
@@ -188,6 +252,7 @@ class BufferedCSVWriter {
             return Promise.resolve();
         const chunk = this.buffer.join('\n') + '\n';
         this.buffer.length = 0;
+        this.bufferedBytes = 0;
         return new Promise((resolve, reject) => {
             this.ws.once('error', reject);
             const ok = this.ws.write(chunk);
@@ -355,7 +420,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
             seenNodeIds.add(node.id);
             // addRow returns a promise only when it flushes; awaiting it once after the
             // switch (instead of `await`-ing every addRow) skips a per-row microtask
-            // tick on the ~FLUSH_EVERY-1 buffered rows between flushes (#2203 U3).
+            // tick on the rows buffered between byte-bounded flushes (#2203 U3).
             let pending;
             switch (node.label) {
                 case 'File': {
@@ -383,7 +448,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                         escapeCSVField(node.properties.name || ''),
                         escapeCSVField(node.properties.heuristicLabel || ''),
                         keywordsStr,
-                        escapeCSVField(node.properties.description || ''),
+                        escapeCSVField(formatFtsDescription(node.properties.description || '')),
                         escapeCSVField(node.properties.enrichedBy || 'heuristic'),
                         escapeCSVNumber(node.properties.cohesion, 0),
                         escapeCSVNumber(node.properties.symbolCount, 0),
@@ -415,7 +480,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                         escapeCSVNumber(node.properties.endLine, -1),
                         node.properties.isExported ? 'true' : 'false',
                         escapeCSVField(content),
-                        escapeCSVField(node.properties.description || ''),
+                        escapeCSVField(formatFtsDescription(node.properties.description || '')),
                         escapeCSVNumber(node.properties.parameterCount, 0),
                         escapeCSVField(node.properties.returnType || ''),
                     ].join(','));
@@ -431,7 +496,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                         escapeCSVNumber(node.properties.endLine, -1),
                         escapeCSVNumber(node.properties.level, 1),
                         escapeCSVField(content),
-                        escapeCSVField(node.properties.description || ''),
+                        escapeCSVField(formatFtsDescription(node.properties.description || '')),
                     ].join(','));
                     break;
                 }
@@ -461,7 +526,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                         escapeCSVField(node.id),
                         escapeCSVField(node.properties.name || ''),
                         escapeCSVField(node.properties.filePath || ''),
-                        escapeCSVField(node.properties.description || ''),
+                        escapeCSVField(formatFtsDescription(node.properties.description || '')),
                     ].join(','));
                     break;
                 case 'BasicBlock':
@@ -480,7 +545,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                             escapeCSVNumber(node.properties.endLine, -1),
                             node.properties.isExported ? 'true' : 'false',
                             escapeCSVField(content),
-                            escapeCSVField(node.properties.description || ''),
+                            escapeCSVField(formatFtsDescription(node.properties.description || '')),
                         ].join(','));
                     }
                     else {
@@ -495,7 +560,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                                 escapeCSVNumber(node.properties.startLine, -1),
                                 escapeCSVNumber(node.properties.endLine, -1),
                                 escapeCSVField(content),
-                                escapeCSVField(node.properties.description || ''),
+                                escapeCSVField(formatFtsDescription(node.properties.description || '')),
                                 ...(node.label === 'Property'
                                     ? [escapeCSVField(node.properties.declaredType || '')]
                                     : []),

package/dist/core/run-analyze.js

@@ -15,6 +15,7 @@ import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
+import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
@@ -259,6 +260,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // parse/load phases. A typo fails here in ms; createSearchFTSIndexes reuses
     // the cached value via getSearchFTSStemmer.
     initialiseSearchFTSStemmer();
+    initialiseSearchFTSCjkSegmentation();
     // Scope the degraded-parse log throttle to this run. On a reused process
     // (e.g. tests, or any host that calls runFullAnalysis more than once) the
     // module-level counter would otherwise stay saturated and suppress every
@@ -459,6 +461,13 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `forcing a full rebuild so persisted rows match the current schema.`);
         options = { ...options, force: true };
     }
+    if (existingMeta &&
+        cjkSegmentationModeMismatch(existingMeta.cjkSegmentation, getSearchFTSCjkSegmentation())) {
+        log(`CJK segmentation mode changed (index built with '${existingMeta.cjkSegmentation ?? 'none'}', ` +
+            `this run resolves '${getSearchFTSCjkSegmentation()}'); forcing a full rebuild so indexed ` +
+            `text and query-time segmentation stay in sync.`);
+        options = { ...options, force: true };
+    }
     // ── Early-return: already up to date ──────────────────────────────
     if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
@@ -1074,6 +1083,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // incrementalInProgress to undefined explicitly clears any prior
             // dirty flag (full and incremental success paths converge here).
             schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined,
+            // Always stamped with the live resolved mode (#2331/#2339) — unlike
+            // `pdg` below, 'none' is a meaningful value to compare, not an
+            // absence, so this is never conditionally omitted.
+            cjkSegmentation: getSearchFTSCjkSegmentation(),
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined,
             // This branch's full live chunk-key set (#2106 R6). `usedKeys` is every
             // chunk hash touched in this scan — cache HITS included (see parse-impl

package/dist/core/search/bm25-index.js

@@ -5,7 +5,9 @@
  * Always reads from the database (no cached state to drift).
  */
 import { queryFTS } from '../lbug/lbug-adapter.js';
+import { normalizeFtsText } from '../lbug/csv-generator.js';
 import { FTS_INDEXES } from './fts-schema.js';
+import { applyCjkSegmentationIfEnabled, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from './cjk-segmentation.js';
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
  * Returns `null` when the query fails (e.g. FTS index does not exist) so the
@@ -46,6 +48,21 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  * @returns Ranked search results from FTS indexes
  */
 export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
+    // Applied once, up front, so every downstream branch searches with the
+    // same text the index was built from (#2331/#2339) — index-time and
+    // query-time text transforms must never diverge, since QUERY_FTS_INDEX
+    // cannot derive a tokenizer from the index it queries. Composed in the
+    // SAME order as the write path (csv-generator.ts's formatFtsDescription /
+    // extractContent: normalizeFtsText(applyCjkSegmentationIfEnabled(text))):
+    // CJK segmentation is no-op when disabled (default); normalizeFtsText
+    // (collapsing \r\n\t to a space) applies unconditionally — it has no
+    // per-character cost concern, unlike CJK segmentation, so it's not gated
+    // by the length cap. Segmentation itself is skipped for pathologically
+    // long queries (see MAX_CJK_SEGMENTATION_QUERY_LENGTH) — the query still
+    // searches correctly, just without CJK sub-phrase segmentation.
+    const searchQuery = normalizeFtsText(query.length <= MAX_CJK_SEGMENTATION_QUERY_LENGTH
+        ? applyCjkSegmentationIfEnabled(query)
+        : query);
     const resultsByIndex = [];
     let queriesSucceeded = 0;
     if (repoId) {
@@ -56,7 +73,7 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         const { executeParameterized } = poolMod;
         const executor = (cypher, params) => executeParameterized(repoId, cypher, params);
         for (const { table, indexName } of FTS_INDEXES) {
-            const result = await queryFTSViaExecutor(executor, table, indexName, query, limit);
+            const result = await queryFTSViaExecutor(executor, table, indexName, searchQuery, limit);
             if (result !== null) {
                 queriesSucceeded++;
                 resultsByIndex.push(result);
@@ -67,7 +84,7 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
         for (const { table, indexName } of FTS_INDEXES) {
             try {
-                const result = await queryFTS(table, indexName, query, limit, false);
+                const result = await queryFTS(table, indexName, searchQuery, limit, false);
                 queriesSucceeded++;
                 resultsByIndex.push(result);
             }

package/dist/core/search/cjk-segmentation.d.ts

@@ -0,0 +1,126 @@
+/**
+ * CJK bigram segmentation for FTS search (#2331)
+ *
+ * LadybugDB's bundled FTS tokenizer splits only on the space character, so a
+ * contiguous CJK (Chinese/Japanese/Korean) span indexes as one giant token and
+ * sub-phrase queries never match. `segmentCjkSpans` addresses the Han-ideograph
+ * case (Chinese text and Japanese Kanji — see scope note below) by rewriting
+ * each contiguous run of CJK Unified Ideographs into space-separated overlapping character
+ * bigrams (`采购订单` -> `采购 购订 订单`), the same technique MySQL's `ngram`
+ * fulltext parser, Elasticsearch's `cjk` analyzer, and Lucene's
+ * `CJKBigramFilter` use by default. For any exact contiguous substring query
+ * of length >= 2, its bigram decomposition is a subset of the source text's
+ * bigram decomposition, so sub-phrase matching works without needing a
+ * dictionary or boundary-alignment luck.
+ *
+ * Scoped to the core CJK Unified Ideographs block (U+4E00-U+9FFF) only —
+ * covers Chinese text and Japanese Kanji. Hiragana, Katakana, and Hangul
+ * Syllables are deliberately excluded for now (see plan Scope Boundaries);
+ * extend `CJK_UNIFIED_IDEOGRAPHS` below if that need arises.
+ */
+/**
+ * Worst-case output/input byte ratio for `segmentCjkSpans` on an all-CJK run:
+ * each adjacent character pair becomes a 2-character bigram plus a 1-byte
+ * separator, i.e. ~7 output bytes per 3 input bytes of UTF-8 CJK text (each
+ * CJK character is 3 bytes). Single source of truth — imported by both the
+ * CSV-flush safety-margin test (`csv-pipeline.test.ts`) and the growth-factor
+ * regression guard (`cjk-segmentation.test.ts`), and referenced by name in
+ * `csv-generator.ts`'s `FLUSH_BYTES` margin comment, so all three stay in
+ * sync if the algorithm's expansion ratio ever changes.
+ */
+export declare const CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR: number;
+/**
+ * A real search query is always a short phrase — unlike indexed File content
+ * (deliberately uncapped, #2317/#2323), nothing else bounds a query's length
+ * before it reaches `segmentCjkSpans`. Without a cap, a pathologically long
+ * query string (accidental or adversarial) would pay `segmentCjkSpans`'s
+ * per-character allocation cost on every search request. 2000 characters
+ * comfortably covers any real natural-language query.
+ *
+ * Lives here rather than in `bm25-index.ts` (its only other consumer) so
+ * `local-backend.ts` can import it statically alongside this module's other
+ * symbols — `bm25-index.ts` transitively imports `@ladybugdb/core` (a native
+ * binding, via `lbug-adapter.js`), which is exactly the kind of module
+ * `local-backend.ts`'s `bm25Search` deliberately dynamic-imports instead of
+ * statically (#1489: can fail in sandboxed MCP contexts). A static import of
+ * even one constant from `bm25-index.ts` would force that native binding to
+ * load at MCP-server startup instead of at first query.
+ */
+export declare const MAX_CJK_SEGMENTATION_QUERY_LENGTH = 2000;
+/**
+ * True if `text` contains at least one CJK Unified Ideograph, including a
+ * single character. Generic presence check — for gating the "enable bigram
+ * mode" query warning specifically, use {@link containsSegmentableCjkRun}
+ * instead (#2339): a lone CJK character can never be bigram-segmented, so
+ * this broader check would misleadingly flag queries bigram mode can't help.
+ */
+export declare const containsCjkIdeograph: (text: string) => boolean;
+/**
+ * True if `text` contains a CJK run of 2+ contiguous ideographs —
+ * i.e. a span `segmentCjkSpans` can actually bigram-segment. A lone CJK
+ * character can never be segmented (no possible pairing), so callers
+ * warning "enable bigram mode" for a query should gate on this, not on
+ * `containsCjkIdeograph` (#2339). Uses its own non-global RegExp instance
+ * (see `CJK_SEGMENTABLE_RUN_RE` above) — never call `.test()` on the
+ * shared, global-flagged `CJK_RUN_RE` directly.
+ */
+export declare const containsSegmentableCjkRun: (text: string) => boolean;
+/**
+ * Rewrite contiguous CJK spans in `text` into space-separated overlapping
+ * bigrams (a run of exactly 2 chars becomes a single bigram; a lone CJK
+ * char has no possible pairing and passes through unchanged). Non-CJK text
+ * is never touched by `replace` in the first place, so a run's boundary
+ * spacing is decided by peeking at the *original* string's neighboring
+ * character (via the callback's `offset`/`full` args) rather than tracking
+ * state across matches — each match stays independent even when two CJK
+ * runs sit close together, and a space is added only when the neighbor
+ * isn't already whitespace, so the whitespace-splitting FTS tokenizer
+ * treats runs as separate tokens (`ERP审批流程` -> `ERP 审批 批流 流程`,
+ * not `ERP审批 批流 流程`).
+ */
+export declare const segmentCjkSpans: (text: string) => string;
+export declare const DEFAULT_FTS_CJK_SEGMENTATION = "none";
+/**
+ * True if `value` is one of the recognized segmentation modes. Callers that
+ * interpolate a persisted `RepoMeta.cjkSegmentation` value into agent-visible
+ * text (e.g. the MCP query-tool's mode-drift warning, #2339) must validate
+ * with this first — that field comes from `meta.json`, a schema-less
+ * `JSON.parse` of on-disk state inside the analyzed repo, not a trusted
+ * input, so an unvalidated value could otherwise be echoed verbatim into
+ * tool output an agent is expected to trust and act on.
+ */
+export declare const isSupportedCjkSegmentationMode: (value: unknown) => value is string;
+/**
+ * Resolve + validate `GITNEXUS_FTS_CJK_SEGMENTATION` once, up front at analyze
+ * startup, and cache it — mirrors `initialiseSearchFTSStemmer` so an invalid
+ * value fails in milliseconds instead of partway through a run. The cached
+ * value is what {@link getSearchFTSCjkSegmentation} returns for the rest of
+ * the run, so config is read and validated in exactly one place.
+ */
+export declare function initialiseSearchFTSCjkSegmentation(): string;
+/**
+ * Return the mode resolved by {@link initialiseSearchFTSCjkSegmentation}.
+ * Falls back to resolving on demand when init was never called (read-only
+ * hosts, unit tests) so validation always applies.
+ */
+export declare function getSearchFTSCjkSegmentation(): string;
+/**
+ * Whether the CJK segmentation mode an index was built under (as persisted in
+ * `RepoMeta.cjkSegmentation`) differs from the mode the live process resolves
+ * (#2331/#2339) — used by `run-analyze.ts` to force a full rebuild on drift,
+ * and by the MCP query path to warn when a repo's index and the serving
+ * process disagree. A single scalar, so a plain equality check suffices —
+ * unlike `pdgModeMismatch` in `run-analyze.ts`, no key-union comparator is
+ * needed. An absent recorded stamp defaults to 'none' (this feature's own
+ * default), so a repo that never touched this feature never mismatches.
+ * Pure + exported for testing. Lives here (not `run-analyze.ts`) so callers
+ * that only need this comparator — e.g. the MCP query path — don't have to
+ * pull in the full analyze-pipeline module.
+ */
+export declare const cjkSegmentationModeMismatch: (recorded: string | undefined, resolved: string) => boolean;
+/**
+ * The single entry point the write path (`csv-generator.ts`) and read path
+ * (`bm25-index.ts`) both call, so indexed text and query text are always
+ * segmented identically. No-ops when the resolved mode is `none` (default).
+ */
+export declare const applyCjkSegmentationIfEnabled: (text: string) => string;

package/dist/core/search/cjk-segmentation.js

@@ -0,0 +1,176 @@
+/**
+ * CJK bigram segmentation for FTS search (#2331)
+ *
+ * LadybugDB's bundled FTS tokenizer splits only on the space character, so a
+ * contiguous CJK (Chinese/Japanese/Korean) span indexes as one giant token and
+ * sub-phrase queries never match. `segmentCjkSpans` addresses the Han-ideograph
+ * case (Chinese text and Japanese Kanji — see scope note below) by rewriting
+ * each contiguous run of CJK Unified Ideographs into space-separated overlapping character
+ * bigrams (`采购订单` -> `采购 购订 订单`), the same technique MySQL's `ngram`
+ * fulltext parser, Elasticsearch's `cjk` analyzer, and Lucene's
+ * `CJKBigramFilter` use by default. For any exact contiguous substring query
+ * of length >= 2, its bigram decomposition is a subset of the source text's
+ * bigram decomposition, so sub-phrase matching works without needing a
+ * dictionary or boundary-alignment luck.
+ *
+ * Scoped to the core CJK Unified Ideographs block (U+4E00-U+9FFF) only —
+ * covers Chinese text and Japanese Kanji. Hiragana, Katakana, and Hangul
+ * Syllables are deliberately excluded for now (see plan Scope Boundaries);
+ * extend `CJK_UNIFIED_IDEOGRAPHS` below if that need arises.
+ */
+/** The core CJK Unified Ideographs block — single source of truth for both regexes below. */
+const CJK_UNIFIED_IDEOGRAPHS = '[\\u4e00-\\u9fff]';
+const CJK_CHAR_RE = new RegExp(CJK_UNIFIED_IDEOGRAPHS);
+const CJK_RUN_RE = new RegExp(`${CJK_UNIFIED_IDEOGRAPHS}{2,}`, 'g');
+// Same pattern as CJK_RUN_RE, but WITHOUT the 'g' flag — kept as a separate
+// instance deliberately. RegExp.prototype.test() on a global-flagged regex
+// is stateful (mutates lastIndex between calls); CJK_RUN_RE only stays safe
+// today because its one consumer (segmentCjkSpans) drives it exclusively via
+// String.prototype.replace, which always resets matching from index 0. A
+// second consumer calling .test() on that same shared instance would leak
+// state across calls (and across requests, in a long-lived process).
+const CJK_SEGMENTABLE_RUN_RE = new RegExp(`${CJK_UNIFIED_IDEOGRAPHS}{2,}`);
+const WHITESPACE_RE = /\s/;
+/**
+ * Worst-case output/input byte ratio for `segmentCjkSpans` on an all-CJK run:
+ * each adjacent character pair becomes a 2-character bigram plus a 1-byte
+ * separator, i.e. ~7 output bytes per 3 input bytes of UTF-8 CJK text (each
+ * CJK character is 3 bytes). Single source of truth — imported by both the
+ * CSV-flush safety-margin test (`csv-pipeline.test.ts`) and the growth-factor
+ * regression guard (`cjk-segmentation.test.ts`), and referenced by name in
+ * `csv-generator.ts`'s `FLUSH_BYTES` margin comment, so all three stay in
+ * sync if the algorithm's expansion ratio ever changes.
+ */
+export const CJK_BIGRAM_WORST_CASE_GROWTH_FACTOR = 7 / 3;
+/**
+ * A real search query is always a short phrase — unlike indexed File content
+ * (deliberately uncapped, #2317/#2323), nothing else bounds a query's length
+ * before it reaches `segmentCjkSpans`. Without a cap, a pathologically long
+ * query string (accidental or adversarial) would pay `segmentCjkSpans`'s
+ * per-character allocation cost on every search request. 2000 characters
+ * comfortably covers any real natural-language query.
+ *
+ * Lives here rather than in `bm25-index.ts` (its only other consumer) so
+ * `local-backend.ts` can import it statically alongside this module's other
+ * symbols — `bm25-index.ts` transitively imports `@ladybugdb/core` (a native
+ * binding, via `lbug-adapter.js`), which is exactly the kind of module
+ * `local-backend.ts`'s `bm25Search` deliberately dynamic-imports instead of
+ * statically (#1489: can fail in sandboxed MCP contexts). A static import of
+ * even one constant from `bm25-index.ts` would force that native binding to
+ * load at MCP-server startup instead of at first query.
+ */
+export const MAX_CJK_SEGMENTATION_QUERY_LENGTH = 2000;
+/**
+ * True if `text` contains at least one CJK Unified Ideograph, including a
+ * single character. Generic presence check — for gating the "enable bigram
+ * mode" query warning specifically, use {@link containsSegmentableCjkRun}
+ * instead (#2339): a lone CJK character can never be bigram-segmented, so
+ * this broader check would misleadingly flag queries bigram mode can't help.
+ */
+export const containsCjkIdeograph = (text) => CJK_CHAR_RE.test(text);
+/**
+ * True if `text` contains a CJK run of 2+ contiguous ideographs —
+ * i.e. a span `segmentCjkSpans` can actually bigram-segment. A lone CJK
+ * character can never be segmented (no possible pairing), so callers
+ * warning "enable bigram mode" for a query should gate on this, not on
+ * `containsCjkIdeograph` (#2339). Uses its own non-global RegExp instance
+ * (see `CJK_SEGMENTABLE_RUN_RE` above) — never call `.test()` on the
+ * shared, global-flagged `CJK_RUN_RE` directly.
+ */
+export const containsSegmentableCjkRun = (text) => CJK_SEGMENTABLE_RUN_RE.test(text);
+/**
+ * Rewrite contiguous CJK spans in `text` into space-separated overlapping
+ * bigrams (a run of exactly 2 chars becomes a single bigram; a lone CJK
+ * char has no possible pairing and passes through unchanged). Non-CJK text
+ * is never touched by `replace` in the first place, so a run's boundary
+ * spacing is decided by peeking at the *original* string's neighboring
+ * character (via the callback's `offset`/`full` args) rather than tracking
+ * state across matches — each match stays independent even when two CJK
+ * runs sit close together, and a space is added only when the neighbor
+ * isn't already whitespace, so the whitespace-splitting FTS tokenizer
+ * treats runs as separate tokens (`ERP审批流程` -> `ERP 审批 批流 流程`,
+ * not `ERP审批 批流 流程`).
+ */
+export const segmentCjkSpans = (text) => text.replace(CJK_RUN_RE, (run, offset, full) => {
+    const bigrams = [];
+    for (let i = 0; i < run.length - 1; i++)
+        bigrams.push(run.slice(i, i + 2));
+    const before = full[offset - 1];
+    const after = full[offset + run.length];
+    const leadingSpace = before !== undefined && !WHITESPACE_RE.test(before) ? ' ' : '';
+    const trailingSpace = after !== undefined && !WHITESPACE_RE.test(after) ? ' ' : '';
+    return leadingSpace + bigrams.join(' ') + trailingSpace;
+});
+// ============================================================================
+// GITNEXUS_FTS_CJK_SEGMENTATION — env var validation and the segmentation gate
+// ============================================================================
+/**
+ * Modes shipped by this plan. Deliberately does not include a `'jieba'`
+ * value: LadybugDB's native `tokenizer := 'jieba'` parameter FATAL-crashes
+ * the process without a bundled dictionary (no such dictionary ships with
+ * `@ladybugdb/core`), and `QUERY_FTS_INDEX` has no way to apply it to a query
+ * string anyway — see the plan's Key Technical Decision 1. Stubbing an
+ * unimplemented option here would misrepresent it as available.
+ */
+const SUPPORTED_FTS_CJK_SEGMENTATION_MODES = new Set(['none', 'bigram']);
+export const DEFAULT_FTS_CJK_SEGMENTATION = 'none';
+/**
+ * True if `value` is one of the recognized segmentation modes. Callers that
+ * interpolate a persisted `RepoMeta.cjkSegmentation` value into agent-visible
+ * text (e.g. the MCP query-tool's mode-drift warning, #2339) must validate
+ * with this first — that field comes from `meta.json`, a schema-less
+ * `JSON.parse` of on-disk state inside the analyzed repo, not a trusted
+ * input, so an unvalidated value could otherwise be echoed verbatim into
+ * tool output an agent is expected to trust and act on.
+ */
+export const isSupportedCjkSegmentationMode = (value) => typeof value === 'string' && SUPPORTED_FTS_CJK_SEGMENTATION_MODES.has(value);
+let resolvedCjkSegmentation;
+/** Read + validate `GITNEXUS_FTS_CJK_SEGMENTATION`. Throws on an unsupported value. */
+function resolveFTSCjkSegmentation() {
+    const raw = process.env.GITNEXUS_FTS_CJK_SEGMENTATION?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_FTS_CJK_SEGMENTATION;
+    if (SUPPORTED_FTS_CJK_SEGMENTATION_MODES.has(raw))
+        return raw;
+    throw new Error(`Invalid GITNEXUS_FTS_CJK_SEGMENTATION "${process.env.GITNEXUS_FTS_CJK_SEGMENTATION}". ` +
+        `Expected one of: ${[...SUPPORTED_FTS_CJK_SEGMENTATION_MODES].sort().join(', ')}.`);
+}
+/**
+ * Resolve + validate `GITNEXUS_FTS_CJK_SEGMENTATION` once, up front at analyze
+ * startup, and cache it — mirrors `initialiseSearchFTSStemmer` so an invalid
+ * value fails in milliseconds instead of partway through a run. The cached
+ * value is what {@link getSearchFTSCjkSegmentation} returns for the rest of
+ * the run, so config is read and validated in exactly one place.
+ */
+export function initialiseSearchFTSCjkSegmentation() {
+    resolvedCjkSegmentation = resolveFTSCjkSegmentation();
+    return resolvedCjkSegmentation;
+}
+/**
+ * Return the mode resolved by {@link initialiseSearchFTSCjkSegmentation}.
+ * Falls back to resolving on demand when init was never called (read-only
+ * hosts, unit tests) so validation always applies.
+ */
+export function getSearchFTSCjkSegmentation() {
+    return resolvedCjkSegmentation ?? resolveFTSCjkSegmentation();
+}
+/**
+ * Whether the CJK segmentation mode an index was built under (as persisted in
+ * `RepoMeta.cjkSegmentation`) differs from the mode the live process resolves
+ * (#2331/#2339) — used by `run-analyze.ts` to force a full rebuild on drift,
+ * and by the MCP query path to warn when a repo's index and the serving
+ * process disagree. A single scalar, so a plain equality check suffices —
+ * unlike `pdgModeMismatch` in `run-analyze.ts`, no key-union comparator is
+ * needed. An absent recorded stamp defaults to 'none' (this feature's own
+ * default), so a repo that never touched this feature never mismatches.
+ * Pure + exported for testing. Lives here (not `run-analyze.ts`) so callers
+ * that only need this comparator — e.g. the MCP query path — don't have to
+ * pull in the full analyze-pipeline module.
+ */
+export const cjkSegmentationModeMismatch = (recorded, resolved) => (recorded ?? 'none') !== resolved;
+/**
+ * The single entry point the write path (`csv-generator.ts`) and read path
+ * (`bm25-index.ts`) both call, so indexed text and query text are always
+ * segmented identically. No-ops when the resolved mode is `none` (default).
+ */
+export const applyCjkSegmentationIfEnabled = (text) => getSearchFTSCjkSegmentation() === 'bigram' ? segmentCjkSpans(text) : text;

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

@@ -26,6 +26,7 @@ import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { cjkSegmentationModeMismatch, containsSegmentableCjkRun, getSearchFTSCjkSegmentation, isSupportedCjkSegmentationMode, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from '../../core/search/cjk-segmentation.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
@@ -1579,6 +1580,68 @@ export class LocalBackend {
         if (!ftsUsed) {
             warnings.push('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.');
         }
+        // #2331: a CJK query against a server process resolving
+        // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
+        // matches with no other signal — this is the only place an agent driving
+        // GitNexus through the query tool can learn the capability exists.
+        try {
+            const cjkMode = getSearchFTSCjkSegmentation();
+            if (containsSegmentableCjkRun(searchQuery) && cjkMode !== 'bigram') {
+                warnings.push('Query contains CJK characters — sub-phrase matches require GITNEXUS_FTS_CJK_SEGMENTATION=bigram set for both `analyze` and this server process, then `gitnexus analyze --force`.');
+            }
+            else if (cjkMode === 'bigram' &&
+                searchQuery.length > MAX_CJK_SEGMENTATION_QUERY_LENGTH &&
+                containsSegmentableCjkRun(searchQuery)) {
+                // #2339: bigram mode is enabled, but the query exceeds the length
+                // cap that guards segmentCjkSpans's per-character allocation cost —
+                // applyCjkSegmentationIfEnabled silently skips segmentation above
+                // this length, so an over-cap CJK query returns zero results for
+                // text that IS indexed and present verbatim, with no other signal.
+                warnings.push(`Query exceeds the ${MAX_CJK_SEGMENTATION_QUERY_LENGTH}-character CJK segmentation cap — ` +
+                    'sub-phrase matches are skipped for this query even though GITNEXUS_FTS_CJK_SEGMENTATION=bigram is enabled. Shorten the query to search within the cap.');
+            }
+        }
+        catch (err) {
+            // Best-effort diagnostic only — never fail the query over it.
+            logQueryError('query:cjk-warning', err);
+        }
+        // #2339: the checks above only compare the QUERY's own content against
+        // the live process's mode — they can't detect "server mode is 'bigram'
+        // but the on-disk index was actually built under 'none'/legacy" (env var
+        // changed without a full --force re-analyze, or a plain/--repair-fts
+        // analyze ran instead). That mismatch affects every CJK query against
+        // this repo, not just one whose own text happens to contain CJK, so it's
+        // a separate, unconditional check — not folded into the branches above.
+        try {
+            const meta = await loadMeta(path.dirname(repo.lbugPath));
+            // meta.json is on-disk state inside the analyzed repo, read via a
+            // schema-less JSON.parse — not trusted input. Validate before
+            // interpolating it into agent-visible tool output (#2339): an
+            // unrecognized value is itself evidence of a corrupt/foreign index,
+            // reported generically rather than echoed verbatim.
+            const persistedMode = meta?.cjkSegmentation;
+            if (meta && persistedMode !== undefined && !isSupportedCjkSegmentationMode(persistedMode)) {
+                warnings.push("This repo's index metadata has an unrecognized CJK segmentation mode stamp — the index " +
+                    'may be corrupt or from an incompatible GitNexus version. Run `gitnexus analyze --force` to rebuild it.');
+            }
+            else if (meta &&
+                cjkSegmentationModeMismatch(meta.cjkSegmentation, getSearchFTSCjkSegmentation())) {
+                warnings.push(`Index was built with CJK segmentation mode '${meta.cjkSegmentation ?? 'none'}', but this ` +
+                    `server is resolving '${getSearchFTSCjkSegmentation()}' — sub-phrase CJK search results ` +
+                    'may be incomplete. Set GITNEXUS_FTS_CJK_SEGMENTATION to the same value for both the ' +
+                    '`analyze` process and this server, then run `gitnexus analyze --force` to rebuild under ' +
+                    "the agreed mode (do not assume the live server's mode is the one to keep — re-analyzing " +
+                    'under the wrong mode can strip an already-working bigram-segmented index back to `none`).');
+            }
+        }
+        catch (err) {
+            // loadMeta() itself never throws (it returns null on any read/parse
+            // failure) — the actual throw source here is getSearchFTSCjkSegmentation()
+            // on an invalid env value, same root cause as the catch above. This is
+            // a separate, independently-guarded diagnostic though, so it gets its
+            // own log context rather than sharing 'query:cjk-warning'.
+            logQueryError('query:cjk-mode-drift', err);
+        }
         if (enrichmentDegraded) {
             warnings.push('Symbol enrichment partially failed — some process/cohesion/content data may be missing from these results (see server logs).');
         }

package/dist/storage/repo-manager.d.ts

@@ -73,6 +73,16 @@ export interface RepoMeta {
      * full rebuild rather than risk an inconsistent incremental update.
      */
     schemaVersion?: number;
+    /**
+     * The resolved GITNEXUS_FTS_CJK_SEGMENTATION mode ('none' | 'bigram') the
+     * existing index's content/description columns were last written under
+     * (#2331/#2339). On mismatch with the live process's resolved mode,
+     * runFullAnalysis forces a full rebuild so indexed text and query-time
+     * segmentation never diverge. Always stamped (never omitted), unlike
+     * `pdg` below — the default 'none' is itself a meaningful value to
+     * compare, not an absence.
+     */
+    cjkSegmentation?: string;
     /**
      * SHA-256 of every file's content at the time of the last successful
      * indexing run. The next run computes current hashes and diffs against

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.34",
+  "version": "1.6.9-rc.36",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",