gitnexus 1.6.12-rc.32 → 1.6.12-rc.34

package/dist/cli/analyze-options.d.ts

@@ -23,6 +23,7 @@ export interface AnalyzeOptions {
     /** Commander negated flag: false only when --no-parse-cache is passed. */
     parseCache?: boolean;
     repairFts?: boolean;
+    skipFts?: boolean;
     /**
      * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
      *   - `undefined` when the flag is omitted

package/dist/cli/analyze-watch.js

@@ -127,6 +127,7 @@ export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnored
     setEnvironment('GITNEXUS_VERBOSE', merged.verbose ? '1' : baseline.verbose);
     return {
         pdg: merged.pdg,
+        skipFts: merged.skipFts,
         branch,
         registryName: merged.name,
         allowDuplicateName: merged.allowDuplicateName,

package/dist/cli/analyze.js

@@ -12,6 +12,7 @@ import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
+import { FTS_DISABLED_MESSAGE, isExplicitFtsDisablement } from '../core/search/fts-policy.js';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
 import { findUndeclaredRelationPairError } from '../core/lbug/rel-pair-routing.js';
@@ -1089,6 +1090,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             force: options.force || options.skills || options.parseCache === false,
             useParseCache: options.parseCache !== false,
             repairFts: options.repairFts,
+            skipFts: options.skipFts,
             embeddings: embeddingsEnabled,
             embeddingsNodeLimit,
             dropEmbeddings: options.dropEmbeddings,
@@ -1187,6 +1189,8 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
+            if (result.ftsSkipped)
+                console.log(`  ${FTS_DISABLED_MESSAGE}\n`);
             if (runOptions.registryName) {
                 console.log(`  Registry name: ${result.repoName}\n`);
             }
@@ -1319,7 +1323,10 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         if (result.ftsSkipped) {
             // #2658 review L2: a build/verify failure is NOT an extension-unavailable
             // problem — sending the user to install the extension is the wrong remedy.
-            if (result.ftsSkipReason === 'build-failed') {
+            if (isExplicitFtsDisablement(result.ftsSkipReason)) {
+                console.log(`\n  ${FTS_DISABLED_MESSAGE}`);
+            }
+            else if (result.ftsSkipReason === 'build-failed') {
                 console.log(`\n  Warning: full-text/BM25 search is disabled — the search index build failed this run.\n` +
                     `  The FTS extension is available; rerun \`gitnexus analyze --repair-fts\`. If it persists,\n` +
                     `  check the disk for space or corruption. Run \`gitnexus doctor\` for details.`);

package/dist/cli/index.js

@@ -51,6 +51,7 @@ program
     .option('-f, --force', 'Force graph and FTS rebuild; unchanged parser output may be reused')
     .option('--no-parse-cache', 'Re-parse every source file instead of replaying cached parser output')
     .option('--repair-fts', 'Repair/rebuild search FTS indexes without full re-analysis')
+    .option('--skip-fts', 'Skip FTS extension loading and keyword search indexes')
     .option('--embeddings [limit]', 'Enable embedding generation for semantic search (off by default). ' +
     'Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.')
     .option('--drop-embeddings', 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +

package/dist/cli/status.js

@@ -8,6 +8,7 @@ import { findRepo, getStoragePaths, loadMeta, hasKuzuIndex } from '../storage/re
 import { getCurrentCommit, getCurrentBranch, isGitRepo, getGitRoot, isWorkingTreeDirty, } from '../storage/git.js';
 import { analyzerRunnerIdentitiesEqual, resolveAnalyzerRunnerIdentity, } from '../core/analyzer-identity.js';
 import { getIndexIncompleteReasons } from '../core/index-freshness.js';
+import { getFtsDisabledReason, FTS_DISABLED_MESSAGE } from '../core/search/fts-policy.js';
 import { detectIndexContentDrift } from '../core/index-content-drift.js';
 import { t } from './i18n/index.js';
 /** How many drifted paths the report names before summarizing the rest. */
@@ -149,6 +150,7 @@ export const statusCommand = async (options = {}) => {
             index: {
                 indexedAt: activeMeta.indexedAt,
                 commit: activeMeta.lastCommit,
+                ...(activeMeta.capabilities ? { capabilities: activeMeta.capabilities } : {}),
                 runnerIdentity: activeMeta.runnerIdentity ?? null,
                 runnerIdentityStatus: runnerIdentityIsCurrent ? 'current' : 'stale-or-unknown',
                 incompleteReasons,
@@ -170,6 +172,8 @@ export const statusCommand = async (options = {}) => {
     console.log(`${t('status.indexed')}: ${new Date(activeMeta.indexedAt).toLocaleString()}`);
     console.log(`${t('status.indexedCommit')}: ${activeMeta.lastCommit?.slice(0, 7)}`);
     console.log(`${t('status.currentCommit')}: ${currentCommit?.slice(0, 7)}`);
+    if (getFtsDisabledReason(activeMeta.capabilities?.fts))
+        console.log(FTS_DISABLED_MESSAGE);
     // Emit the complete, versioned receipt as JSON so humans can inspect it and
     // automation can compare it without reverse-engineering a display string.
     // `null` is the backward-compatible signal for pre-receipt metadata.

package/dist/core/lbug/lbug-adapter.d.ts

@@ -40,7 +40,9 @@ export declare const isReadOnlyDbError: (err: unknown) => boolean;
 export declare const acquireInitLock: (dbPath: string) => Promise<() => Promise<void>>;
 /** Exported for testing — returns the lock file path for a given dbPath. */
 export declare const _initLockPathForTest: (dbPath: string) => string;
-export declare const initLbug: (dbPath: string) => Promise<{
+export declare const initLbug: (dbPath: string, options?: {
+    skipFts?: boolean;
+}) => Promise<{
     db: lbug.Database;
     conn: lbug.Connection;
 }>;
@@ -54,6 +56,7 @@ export declare const initLbug: (dbPath: string) => Promise<{
  */
 export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>, options?: {
     readOnly?: boolean;
+    skipFts?: boolean;
 }) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;
 /**
@@ -839,7 +842,9 @@ export declare const ensureEmbeddingRowDmlSafe: (indexRows?: IndexCatalogSnapsho
  * read once per run. {@link INDEX_CATALOG_UNREADABLE} fails closed here without
  * a second read; omitting the argument makes the gate read for itself.
  */
-export declare const ensureFtsRowDmlSafe: (indexRows?: IndexCatalogSnapshot) => Promise<boolean>;
+export declare const ensureFtsRowDmlSafe: (indexRows?: IndexCatalogSnapshot, options?: {
+    skipFts?: boolean;
+}) => Promise<boolean>;
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *

package/dist/core/lbug/lbug-adapter.js

@@ -576,8 +576,8 @@ const runSchemaCreationQueries = async (dbPath) => {
     }
     return null;
 };
-export const initLbug = async (dbPath) => {
-    return runWithSessionLock(() => ensureLbugInitialized(dbPath));
+export const initLbug = async (dbPath, options = {}) => {
+    return runWithSessionLock(() => ensureLbugInitialized(dbPath, options));
 };
 /**
  * Execute multiple queries against one repo DB atomically.
@@ -593,7 +593,7 @@ export const withLbugDb = async (dbPath, operation, options = {}) => {
     for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
         try {
             return await runWithSessionLock(async () => {
-                await ensureLbugInitialized(dbPath, readOnly);
+                await ensureLbugInitialized(dbPath, { readOnly, skipFts: options.skipFts });
                 return operation();
             });
         }
@@ -624,14 +624,22 @@ export const withLbugDb = async (dbPath, operation, options = {}) => {
     // but TypeScript needs an explicit throw to satisfy the return type.
     throw lastError;
 };
-const ensureLbugInitialized = async (dbPath, readOnly = false) => {
-    if (conn && currentDbPath === dbPath && currentDbReadOnly === readOnly) {
+let currentDbSkipFts = false;
+const ensureLbugInitialized = async (dbPath, options = {}) => {
+    const readOnly = options.readOnly === true;
+    const skipFts = options.skipFts === true;
+    if (conn &&
+        currentDbPath === dbPath &&
+        currentDbReadOnly === readOnly &&
+        currentDbSkipFts === skipFts) {
         return { db, conn };
     }
-    await doInitLbug(dbPath, readOnly);
+    await doInitLbug(dbPath, { readOnly, skipFts });
     return { db, conn };
 };
-const doInitLbug = async (dbPath, readOnly = false) => {
+const doInitLbug = async (dbPath, options = {}) => {
+    const readOnly = options.readOnly === true;
+    const skipFts = options.skipFts === true;
     // Different database requested — close the old one first
     if (conn || db) {
         await safeClose();
@@ -790,7 +798,10 @@ const doInitLbug = async (dbPath, readOnly = false) => {
     // Phase 3 installs it moments later in the same run. Warning here reported a
     // degradation that never happened — the run went on to build every FTS index.
     // Phase 3 (and the read-only branch) still warn for real failures.
-    await loadFTSExtension(undefined, readOnly ? { policy: 'load-only' } : { quiet: true });
+    if (!skipFts) {
+        await loadFTSExtension(undefined, readOnly ? { policy: 'load-only' } : { quiet: true });
+    }
+    currentDbSkipFts = skipFts;
     currentDbPath = dbPath;
     return { db, conn };
 };
@@ -3204,7 +3215,7 @@ export const ensureEmbeddingRowDmlSafe = async (indexRows) => {
  * read once per run. {@link INDEX_CATALOG_UNREADABLE} fails closed here without
  * a second read; omitting the argument makes the gate read for itself.
  */
-export const ensureFtsRowDmlSafe = async (indexRows) => {
+export const ensureFtsRowDmlSafe = async (indexRows, options = {}) => {
     // Unconditional precondition, same regression as the VECTOR twin's (#2841
     // review §5.B): a caller-supplied snapshot must not let a closed DB be
     // answered `true`.
@@ -3231,6 +3242,10 @@ export const ensureFtsRowDmlSafe = async (indexRows) => {
         });
     if (!indexGatesDml)
         return true;
+    // Existing/unknown native indexes still gate writes. Rebuild into a fresh
+    // database rather than loading FTS or issuing unsafe DML when opted out.
+    if (options.skipFts)
+        return false;
     return await loadFTSExtension(undefined, { policy: resolveAnalyzeInstallPolicy() });
 };
 /**

package/dist/core/run-analyze.d.ts

@@ -9,6 +9,7 @@
  * wrapper or server worker) is responsible for process lifecycle.
  */
 import { type GraphWriteCollapseVerdict } from './index-freshness.js';
+import { type FtsSkipReason } from './search/fts-policy.js';
 import type { KnowledgeGraph } from './graph/types.js';
 import { type AnalyzerRunnerIdentity, type RepoMeta } from '../storage/repo-manager.js';
 export interface AnalyzeCallbacks {
@@ -32,6 +33,7 @@ export interface AnalyzeOptions {
     useParseCache?: boolean;
     /** Repair only search indexes without re-running full parsing/indexing. */
     repairFts?: boolean;
+    skipFts?: boolean;
     /** Emit per-index FTS create logs. */
     verbose?: boolean;
     embeddings?: boolean;
@@ -226,8 +228,10 @@ export interface AnalyzeResult {
      * extension loaded but the index build/verify failed non-fatally — remedied by
      * `--repair-fts`, not by installing the extension). Lets the CLI show the
      * correct recovery hint instead of always blaming a missing extension.
+     * `disabled-by-flag` and `disabled-by-env` record intentional opt-out;
+     * neither calls for extension installation or repair.
      */
-    ftsSkipReason?: 'extension-unavailable' | 'build-failed';
+    ftsSkipReason?: FtsSkipReason;
     /**
      * True when the index this run produced/validated is the flat workspace
      * slot (#2106 R2, inverted by #2354 to follow the checked-out branch).

package/dist/core/run-analyze.js

@@ -9,6 +9,7 @@
  * wrapper or server worker) is responsible for process lifecycle.
  */
 import { detectGraphWriteCollapse } from './index-freshness.js';
+import { resolveFtsDisableReason, getFtsDisabledReason, withExplicitFtsDisablement, FTS_DISABLED_MESSAGE, } from './search/fts-policy.js';
 import { PDG_EDGE_TYPES } from './lbug/pdg-emit-sink.js';
 import path from 'path';
 import fs from 'fs/promises';
@@ -584,6 +585,9 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     // Validate operator-provided FTS config before anything else — a typo fails
     // here in ms, without taking the lock. (createSearchFTSIndexes reuses the
     // cached value via getSearchFTSStemmer.)
+    if (options.repairFts && resolveFtsDisableReason(options.skipFts)) {
+        throw new Error('--repair-fts cannot be used with --skip-fts or GITNEXUS_SKIP_FTS=1.');
+    }
     initialiseSearchFTSStemmer();
     initialiseSearchFTSCjkSegmentation();
     // Scope the degraded-parse log throttle to this run (module-level counter
@@ -635,6 +639,8 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     }
 }
 async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, runnerIdentityAtBootstrap) {
+    const ftsDisabledReason = resolveFtsDisableReason(options.skipFts);
+    const initAnalysisLbug = (dbPath) => ftsDisabledReason ? initLbug(dbPath, { skipFts: true }) : initLbug(dbPath);
     const log = (msg) => callbacks.onLog?.(stripControlCharacters(msg));
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
     // FTS-config validation and the degraded-parse counter reset happen in the
@@ -668,7 +674,19 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         const code = err?.code;
         log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);
     }
-    const existingMeta = await loadMeta(metaDir);
+    const loadedMeta = await loadMeta(metaDir);
+    const previousFtsDisabledReason = getFtsDisabledReason(loadedMeta?.capabilities?.fts);
+    // Flag and env are equivalent disablements. Only a true enable↔disable flip
+    // needs a write plan; a discriminator-only change restamps on the
+    // already-up-to-date path.
+    const ftsModeChanged = Boolean(ftsDisabledReason) !== Boolean(previousFtsDisabledReason);
+    // Fold explicit disablement into the in-memory prior meta so every later
+    // saveMeta that spreads it (dirty flag, incremental phase stamps) advertises
+    // "FTS disabled" instead of leftover available/build-failed while a wipe is
+    // in flight. Re-enable leaves the prior stamp untouched.
+    const existingMeta = loadedMeta
+        ? withExplicitFtsDisablement(loadedMeta, ftsDisabledReason)
+        : undefined;
     // ── FTS-only repair path ────────────────────────────────────────────
     if (options.repairFts) {
         if (!existingMeta) {
@@ -713,7 +731,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 'Run `gitnexus analyze` (full) to rebuild from scratch.');
         }
         try {
-            await initLbug(lbugPath);
+            await initAnalysisLbug(lbugPath);
             // Gate on FTS availability BEFORE touching any index. createSearchFTSIndexes
             // now DROPs each index before recreating it (so schema changes reach existing
             // DBs); if the extension were unavailable, the drops would run and leave the
@@ -1192,7 +1210,8 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     if (existingMeta &&
         !existingMeta.embeddingCheckpoint &&
         !options.force &&
-        existingMeta.lastCommit === currentCommit) {
+        existingMeta.lastCommit === currentCommit &&
+        !ftsModeChanged) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             // For git repos, even if HEAD matches lastCommit, the working tree
@@ -1293,6 +1312,19 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                         log(`Warning: could not restamp the workspace branch label (${reason}); will retry on the next run.`);
                     }
                 }
+                else if (ftsDisabledReason && ftsDisabledReason !== previousFtsDisabledReason) {
+                    // Discriminator-only restamp (flag↔env). `existingMeta` already
+                    // carries the folded skipReason; persist it without a write plan.
+                    try {
+                        await saveMeta(metaDir, existingMeta);
+                    }
+                    catch (err) {
+                        const reason = isReadOnlyFilesystemError(err)
+                            ? `${err.message} — storage may be read-only (#1549)`
+                            : err.message;
+                        log(`Warning: could not restamp the FTS skip reason (${reason}); will retry on the next run.`);
+                    }
+                }
                 await ensureGitNexusIgnored(repoPath);
                 return {
                     // `resolveRepoIdentityRoot` collapses worktree roots to the
@@ -1304,6 +1336,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     repoPath,
                     stats: existingMeta.stats ?? {},
                     alreadyUpToDate: true,
+                    ...(ftsDisabledReason ? { ftsSkipped: true, ftsSkipReason: ftsDisabledReason } : {}),
                     isPrimaryBranch: !placement.branch,
                 };
             }
@@ -1361,7 +1394,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     if (shouldLoadCache && existingMeta) {
         try {
             progress('embeddings', 0, 'Caching embeddings...');
-            await initLbug(lbugPath);
+            await initAnalysisLbug(lbugPath);
             const cached = await loadCachedEmbeddings();
             cachedEmbeddingNodeIds = cached.embeddingNodeIds;
             cachedEmbeddings = cached.embeddings;
@@ -1707,7 +1740,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     // Full rebuild (POSIX) builds into the temp `buildPath`; incremental and
     // Windows use `buildPath === lbugPath` in place.
     try {
-        await initLbug(buildPath);
+        await initAnalysisLbug(buildPath);
     }
     catch (error) {
         if (liveIndexMutationStarted)
@@ -1990,7 +2023,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             // creates or drops an index.
             const indexCatalogRows = await readIndexCatalogSnapshot();
             const embeddingRowDmlSafe = await ensureEmbeddingRowDmlSafe(indexCatalogRows);
-            const ftsRowDmlSafe = await ensureFtsRowDmlSafe(indexCatalogRows);
+            const ftsRowDmlSafe = ftsDisabledReason
+                ? await ensureFtsRowDmlSafe(indexCatalogRows, { skipFts: true })
+                : await ensureFtsRowDmlSafe(indexCatalogRows);
             const extensionForcedRebuild = !embeddingRowDmlSafe || !ftsRowDmlSafe;
             // `!options.dropEmbeddings` (H1): this rescue reads the rows back OUT of
             // the DB, so it must never fire on the one path whose entire purpose is to
@@ -2074,7 +2109,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 // catalog read happened to fail still had both gates answer "safe"
                 // (both extensions loaded), and claiming otherwise would trade one
                 // invented cause for another.
-                if (extensionForcedRebuild && indexCatalogUnreadable) {
+                if (extensionForcedRebuild && indexCatalogUnreadable && !ftsDisabledReason) {
                     const blockedExtensions = [
                         !embeddingRowDmlSafe ? 'VECTOR' : undefined,
                         !ftsRowDmlSafe ? 'FTS' : undefined,
@@ -2092,7 +2127,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     }
                     degradedEffects.push('Semantic search falls back to exact scan until VECTOR is available.');
                 }
-                if (!ftsRowDmlSafe) {
+                if (!ftsRowDmlSafe && ftsDisabledReason) {
+                    escalationCauses.push('FTS is explicitly disabled and existing search indexes could not be ruled out; ' +
+                        'a fresh graph store is required before writing rows without the extension');
+                }
+                else if (!ftsRowDmlSafe) {
                     if (!indexCatalogUnreadable) {
                         // Self-contained subject (H5): `join('; and ')` used to render "…the
                         // CodeEmbedding vector index exists … and THIS INDEX carries FTS
@@ -2139,7 +2178,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     !embeddingRowDmlSafe
                         ? { reason: getExtensionCapability('VECTOR')?.reason, label: 'VECTOR' }
                         : undefined,
-                    !ftsRowDmlSafe ? { reason: getFtsCapability()?.reason, label: 'FTS' } : undefined,
+                    !ftsRowDmlSafe && !ftsDisabledReason
+                        ? { reason: getFtsCapability()?.reason, label: 'FTS' }
+                        : undefined,
                 ]
                     .filter((e) => e !== undefined)
                     .map(({ reason, label }) => diagnoseExtensionLoad(reason, label).remedy);
@@ -2219,7 +2260,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 if (buildPath === lbugPath)
                     liveIndexMutationStarted = true;
                 await wipeLbugDbFiles(buildPath);
-                await initLbug(buildPath);
+                await initAnalysisLbug(buildPath);
                 walCheckpointDriver = startWalCheckpointDriver();
                 await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
                     lbugMsgCount++;
@@ -2429,20 +2470,23 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         // analyze still produces a fully queryable graph; only full-text/BM25
         // search falls back. `--repair-fts` (whose sole job is FTS) still fails
         // loudly on its own path above.
-        progress('fts', 85, 'Creating search indexes...');
-        const ftsAvailable = await loadFTSExtension(undefined, {
-            policy: resolveAnalyzeInstallPolicy(),
-        });
+        progress('fts', 85, ftsDisabledReason ? 'Skipping search indexes...' : 'Creating search indexes...');
+        const ftsAvailable = !ftsDisabledReason &&
+            (await loadFTSExtension(undefined, {
+                policy: resolveAnalyzeInstallPolicy(),
+            }));
         // Tracks whether search indexes actually ended up usable this run — starts
         // as ftsAvailable (extension loaded) but flips to false below when the
         // build/verify step itself fails, so capabilities.fts.status / ftsSkipped
         // stay honest even though that failure no longer aborts the whole analyze.
         let ftsReady = ftsAvailable;
-        // Why FTS ended up skipped (#2658 review L2): extension-unavailable up front,
-        // or build-failed in the degrade branch below.
+        // Why FTS ended up skipped (#2658 review L2): an explicit opt-out
+        // (`disabled-by-flag` / `disabled-by-env`, #3091) when one was recorded,
+        // else extension-unavailable up front, or build-failed in the degrade
+        // branch below.
         let ftsSkipReason = ftsAvailable
             ? undefined
-            : 'extension-unavailable';
+            : (ftsDisabledReason ?? 'extension-unavailable');
         if (ftsAvailable) {
             // Degrade rather than throw: createSearchFTSIndexes re-tokenizes every
             // stored row on every run, so a native tokenizer error on a single
@@ -2482,6 +2526,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 progress('fts', 90, 'Search indexes skipped (build failed)');
             }
         }
+        else if (ftsDisabledReason) {
+            log(FTS_DISABLED_MESSAGE);
+            progress('fts', 90, 'Search indexes skipped (explicitly disabled)');
+        }
         else {
             // For a missing runtime dependency (#2374) the file is present, so the
             // generic "install it with network access" tail in FTS_UNAVAILABLE_MESSAGE

package/dist/core/search/bm25-index.d.ts

@@ -2,8 +2,12 @@
  * Full-Text Search via LadybugDB FTS
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
- * Always reads from the database (no cached state to drift).
+ * Reads from the database on every query it runs (no cached state to drift).
+ * The one exception is an explicit opt-out (#3091): when a caller passes an
+ * `FtsDisabledReason`, the search short-circuits to an empty, unavailable
+ * response without opening or querying the database at all.
  */
+import type { FtsDisabledReason } from './fts-policy.js';
 export interface BM25SearchResult {
     filePath: string;
     score: number;
@@ -27,14 +31,20 @@ export interface FTSSearchResponse {
     nonBenignErrors?: string[];
 }
 /**
- * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
+ * Search using LadybugDB's built-in FTS (fresh, reads from disk)
  *
  * Queries multiple node tables (File, Function, Class, Method) in parallel
  * and merges results by filePath, summing scores for the same file.
  *
+ * When `disabledReason` is set the index intentionally has no FTS (#3091), so
+ * this returns an empty `ftsAvailable: false` response immediately and never
+ * touches the database — callers render that as deliberate disablement rather
+ * than as a missing index or a failed extension load.
+ *
  * @param query - Search query string
  * @param limit - Maximum results
  * @param repoId - If provided, queries will be routed via the MCP connection pool
+ * @param disabledReason - Explicit FTS opt-out recorded for this index; short-circuits the search
  * @returns Ranked search results from FTS indexes
  */
-export declare const searchFTSFromLbug: (query: string, limit?: number, repoId?: string) => Promise<FTSSearchResponse>;
+export declare const searchFTSFromLbug: (query: string, limit?: number, repoId?: string, disabledReason?: FtsDisabledReason) => Promise<FTSSearchResponse>;

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

@@ -2,7 +2,10 @@
  * Full-Text Search via LadybugDB FTS
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
- * Always reads from the database (no cached state to drift).
+ * Reads from the database on every query it runs (no cached state to drift).
+ * The one exception is an explicit opt-out (#3091): when a caller passes an
+ * `FtsDisabledReason`, the search short-circuits to an empty, unavailable
+ * response without opening or querying the database at all.
  */
 // tri-review Residual-1: `classifyFtsQueryError` now lives in lbug-adapter.ts
 // (see its doc comment) so `queryFTS`'s own catch can share the SAME
@@ -46,17 +49,25 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
     }
 }
 /**
- * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
+ * Search using LadybugDB's built-in FTS (fresh, reads from disk)
  *
  * Queries multiple node tables (File, Function, Class, Method) in parallel
  * and merges results by filePath, summing scores for the same file.
  *
+ * When `disabledReason` is set the index intentionally has no FTS (#3091), so
+ * this returns an empty `ftsAvailable: false` response immediately and never
+ * touches the database — callers render that as deliberate disablement rather
+ * than as a missing index or a failed extension load.
+ *
  * @param query - Search query string
  * @param limit - Maximum results
  * @param repoId - If provided, queries will be routed via the MCP connection pool
+ * @param disabledReason - Explicit FTS opt-out recorded for this index; short-circuits the search
  * @returns Ranked search results from FTS indexes
  */
-export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
+export const searchFTSFromLbug = async (query, limit = 20, repoId, disabledReason) => {
+    if (disabledReason)
+        return { results: [], ftsAvailable: false };
     // 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

package/dist/core/search/fts-indexes.d.ts

@@ -1,4 +1,5 @@
 import { type IndexCatalogSnapshot } from '../lbug/lbug-adapter.js';
+import { type FtsDisabledReason } from './fts-policy.js';
 /**
  * Strip filesystem paths from a LadybugDB error before it reaches the HTTP
  * `/api/search` and MCP query surfaces (#2374, PR #2375): the raw LOAD error
@@ -44,7 +45,7 @@ export interface FtsWarningContext {
  * text itself (#2767). Optional and additive: omitting it reproduces today's
  * exact message.
  */
-export declare const ftsDegradedWarning: (context?: FtsWarningContext) => string;
+export declare const ftsDegradedWarning: (context?: FtsWarningContext, disabledReason?: FtsDisabledReason) => string;
 /**
  * Warning for when the FTS extension is loaded and indexes exist, but every
  * configured table's query failed for a real, non-benign reason (timeout,

package/dist/core/search/fts-indexes.js

@@ -1,5 +1,6 @@
 import { createFTSIndex, dropFTSIndex, indexRowName, indexRowTable, resolveGateRows, DEFAULT_FTS_STEMMER, } from '../lbug/lbug-adapter.js';
 import { getFtsCapability } from '../lbug/extension-loader.js';
+import { FTS_DISABLED_MESSAGE } from './fts-policy.js';
 import { classifyExtensionLoadError } from '../lbug/extension-load-error.js';
 import { FTS_INDEXES } from './fts-schema.js';
 /**
@@ -45,8 +46,10 @@ const formatWarningContext = (context) => {
  * text itself (#2767). Optional and additive: omitting it reproduces today's
  * exact message.
  */
-export const ftsDegradedWarning = (context) => {
+export const ftsDegradedWarning = (context, disabledReason) => {
     const suffix = context ? formatWarningContext(context) : '';
+    if (disabledReason)
+        return FTS_DISABLED_MESSAGE + suffix;
     const fts = getFtsCapability();
     if (fts && !fts.loaded) {
         const reason = fts.reason ? redactPaths(fts.reason).replace(/\.$/, '') : undefined;

package/dist/core/search/fts-policy.d.ts

@@ -0,0 +1,16 @@
+import type { RepoMeta } from '../../storage/repo-meta.js';
+export type FtsDisabledReason = 'disabled-by-flag' | 'disabled-by-env';
+export type FtsSkipReason = FtsDisabledReason | 'extension-unavailable' | 'build-failed';
+type RepoCapabilities = NonNullable<RepoMeta['capabilities']>;
+export declare function resolveFtsDisableReason(skipFts?: boolean, envValue?: string): FtsDisabledReason | undefined;
+export declare function isExplicitFtsDisablement(reason: string | undefined): reason is FtsDisabledReason;
+export declare function getFtsDisabledReason(capability: RepoCapabilities['fts'] | undefined): FtsDisabledReason | undefined;
+/**
+ * Overlay an explicit FTS opt-out onto an existing meta snapshot without
+ * touching freshness (`indexedAt` / `lastCommit`) or sibling capabilities.
+ * Flag and env are equivalent disablements; only the discriminator changes.
+ * Returns `meta` unchanged when `reason` is absent (re-enable) or already stamped.
+ */
+export declare function withExplicitFtsDisablement(meta: RepoMeta, reason: FtsDisabledReason | undefined): RepoMeta;
+export declare const FTS_DISABLED_MESSAGE: string;
+export {};

package/dist/core/search/fts-policy.js

@@ -0,0 +1,56 @@
+const DEFAULT_GRAPH_CAPABILITY = {
+    provider: 'ladybugdb',
+    status: 'available',
+};
+const DEFAULT_VECTOR_SEARCH_CAPABILITY = {
+    provider: 'exact-scan',
+    status: 'unavailable',
+    exactScanLimit: 0,
+};
+export function resolveFtsDisableReason(skipFts, envValue = process.env.GITNEXUS_SKIP_FTS) {
+    if (skipFts === true)
+        return 'disabled-by-flag';
+    if (envValue === '1')
+        return 'disabled-by-env';
+    return undefined;
+}
+export function isExplicitFtsDisablement(reason) {
+    return reason === 'disabled-by-flag' || reason === 'disabled-by-env';
+}
+export function getFtsDisabledReason(capability) {
+    if (capability?.status !== 'unavailable')
+        return undefined;
+    return isExplicitFtsDisablement(capability.skipReason) ? capability.skipReason : undefined;
+}
+/**
+ * Overlay an explicit FTS opt-out onto an existing meta snapshot without
+ * touching freshness (`indexedAt` / `lastCommit`) or sibling capabilities.
+ * Flag and env are equivalent disablements; only the discriminator changes.
+ * Returns `meta` unchanged when `reason` is absent (re-enable) or already stamped.
+ */
+export function withExplicitFtsDisablement(meta, reason) {
+    if (!reason)
+        return meta;
+    const existing = meta.capabilities;
+    const existingFts = existing?.fts;
+    if (existingFts?.status === 'unavailable' &&
+        existingFts.skipReason === reason &&
+        existing?.graph &&
+        existing.vectorSearch) {
+        return meta;
+    }
+    return {
+        ...meta,
+        capabilities: {
+            graph: existing?.graph ?? DEFAULT_GRAPH_CAPABILITY,
+            fts: {
+                provider: existingFts?.provider ?? 'ladybugdb-fts',
+                status: 'unavailable',
+                skipReason: reason,
+            },
+            vectorSearch: existing?.vectorSearch ?? DEFAULT_VECTOR_SEARCH_CAPABILITY,
+        },
+    };
+}
+export const FTS_DISABLED_MESSAGE = 'FTS disabled for this index. To enable keyword search, run gitnexus analyze ' +
+    'without --skip-fts and with GITNEXUS_SKIP_FTS unset.';

package/dist/core/search/hybrid-search.d.ts

@@ -9,6 +9,7 @@
  */
 import { type BM25SearchResult } from './bm25-index.js';
 import type { SemanticSearchResult } from '../embeddings/types.js';
+import type { FtsDisabledReason } from './fts-policy.js';
 export interface HybridSearchResult {
     filePath: string;
     score: number;
@@ -44,10 +45,12 @@ export declare const isHybridSearchReady: () => boolean;
 export declare const formatHybridResults: (results: HybridSearchResult[]) => string;
 /**
  * Execute BM25 + semantic search and merge with RRF.
- * Uses LadybugDB FTS for always-fresh BM25 results (no cached data).
+ * Uses LadybugDB FTS for fresh BM25 results (no cached data).
  * The semanticSearch function is injected to keep this module environment-agnostic.
  *
- * When FTS is unavailable (e.g. read-only MCP connection, missing indexes),
- * falls back to semantic-only results instead of crashing (#1489).
+ * When FTS is unavailable (e.g. read-only MCP connection, missing indexes) or
+ * explicitly disabled for this index (`disabledReason`, #3091), falls back to
+ * semantic-only results instead of crashing (#1489). In the disabled case no
+ * BM25 query is issued at all.
  */
-export declare const hybridSearch: (query: string, limit: number, executeQuery: (cypher: string) => Promise<any[]>, semanticSearch: (executeQuery: (cypher: string) => Promise<any[]>, query: string, k?: number) => Promise<SemanticSearchResult[]>) => Promise<HybridSearchResult[]>;
+export declare const hybridSearch: (query: string, limit: number, executeQuery: (cypher: string) => Promise<any[]>, semanticSearch: (executeQuery: (cypher: string) => Promise<any[]>, query: string, k?: number) => Promise<SemanticSearchResult[]>, disabledReason?: FtsDisabledReason) => Promise<HybridSearchResult[]>;

package/dist/core/search/hybrid-search.js

@@ -113,19 +113,22 @@ export const formatHybridResults = (results) => {
 };
 /**
  * Execute BM25 + semantic search and merge with RRF.
- * Uses LadybugDB FTS for always-fresh BM25 results (no cached data).
+ * Uses LadybugDB FTS for fresh BM25 results (no cached data).
  * The semanticSearch function is injected to keep this module environment-agnostic.
  *
- * When FTS is unavailable (e.g. read-only MCP connection, missing indexes),
- * falls back to semantic-only results instead of crashing (#1489).
+ * When FTS is unavailable (e.g. read-only MCP connection, missing indexes) or
+ * explicitly disabled for this index (`disabledReason`, #3091), falls back to
+ * semantic-only results instead of crashing (#1489). In the disabled case no
+ * BM25 query is issued at all.
  */
-export const hybridSearch = async (query, limit, executeQuery, semanticSearch) => {
-    // Use LadybugDB FTS for always-fresh BM25 results.
+export const hybridSearch = async (query, limit, executeQuery, semanticSearch, disabledReason) => {
+    // Use LadybugDB FTS for fresh BM25 results — skipped entirely when this
+    // index recorded an explicit FTS opt-out (`disabledReason`, #3091).
     // If FTS fails (e.g. extension not loaded in MCP process), fall back to
     // semantic-only search instead of crashing with "bm25Results is not iterable".
     let bm25Results = [];
     try {
-        const ftsResponse = await searchFTSFromLbug(query, limit);
+        const ftsResponse = await searchFTSFromLbug(query, limit, undefined, disabledReason);
         bm25Results = ftsResponse?.results ?? [];
     }
     catch {

package/dist/mcp/local/local-backend.d.ts

@@ -497,6 +497,23 @@ export declare class LocalBackend {
      *   - `remoteUrl`: the canonical origin URL recorded at index time.
      */
     listRepos(): Promise<RepoListing[]>;
+    /**
+     * Lightweight registry count for schema-introspection callers that only
+     * need to know "one repo or many?" without paying the full staleness fan-out
+     * cost that listRepos() incurs. Uses the same validated registry
+     * `refreshRepos` / `selectToolRepository` see (`validate: true` prunes
+     * entries whose metadata is provably gone) so tools/list cannot advertise a
+     * multi-repo schema for ENOENT ghosts. No git processes are spawned.
+     */
+    countRepos(): Promise<number>;
+    /**
+     * In-memory validated registry size after the last `refreshRepos` / init /
+     * `selectToolRepository` refresh. `countRepos()` does not populate this map.
+     * Schema introspection uses this after a refreshed cwd probe so cardinality
+     * and the probe share one snapshot — without putting `refreshRepos()` (and
+     * its kuzu cleanup) on the 0–1 `countRepos` path.
+     */
+    cachedRepoCount(): number;
     /**
      * Paginated view over {@link listRepos} for the `list_repos` MCP tool (#2119).
      *

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

@@ -48,6 +48,7 @@ import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, embeddingDimsMismatch, } fr
 import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { ftsDegradedWarning, ftsQueryFailedWarning } from '../../core/search/fts-indexes.js';
+import { getFtsDisabledReason } from '../../core/search/fts-policy.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 { stalenessPayload, } from '../../core/staleness-status.js';
@@ -1841,6 +1842,28 @@ export class LocalBackend {
             };
         });
     }
+    /**
+     * Lightweight registry count for schema-introspection callers that only
+     * need to know "one repo or many?" without paying the full staleness fan-out
+     * cost that listRepos() incurs. Uses the same validated registry
+     * `refreshRepos` / `selectToolRepository` see (`validate: true` prunes
+     * entries whose metadata is provably gone) so tools/list cannot advertise a
+     * multi-repo schema for ENOENT ghosts. No git processes are spawned.
+     */
+    async countRepos() {
+        const entries = await listRegisteredRepos({ validate: true });
+        return entries.length;
+    }
+    /**
+     * In-memory validated registry size after the last `refreshRepos` / init /
+     * `selectToolRepository` refresh. `countRepos()` does not populate this map.
+     * Schema introspection uses this after a refreshed cwd probe so cardinality
+     * and the probe share one snapshot — without putting `refreshRepos()` (and
+     * its kuzu cleanup) on the 0–1 `countRepos` path.
+     */
+    cachedRepoCount() {
+        return this.repos.size;
+    }
     /**
      * Paginated view over {@link listRepos} for the `list_repos` MCP tool (#2119).
      *
@@ -2193,8 +2216,10 @@ export class LocalBackend {
         // each so both get independent wall-time records without fighting
         // over a single `current` phase slot.
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
+        const meta = await loadMeta(path.dirname(repo.lbugPath));
+        const ftsDisabledReason = getFtsDisabledReason(meta?.capabilities?.fts);
         const [bm25SearchResult, semanticResults] = await Promise.all([
-            timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
+            timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit, ftsDisabledReason)),
             timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
         ]);
         // Guard against undefined results (#1489) — when FTS is entirely
@@ -2486,7 +2511,7 @@ export class LocalBackend {
             // instead of burying the real cause as a trailing suffix on bad advice.
             warnings.push(ftsQueryErrors
                 ? ftsQueryFailedWarning({ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] })
-                : ftsDegradedWarning(warningContext));
+                : ftsDegradedWarning(warningContext, ftsDisabledReason));
         }
         else if (ftsQueryErrors) {
             // #2767: at least one FTS table succeeded (ftsUsed=true) but another
@@ -2534,7 +2559,6 @@ export class LocalBackend {
         // GITNEXUS_FTS_CJK_SEGMENTATION (the only thing that actually throws in
         // there) cannot take an unrelated diagnostic down with it. Needs no guard
         // of its own: loadMeta() returns null on any read/parse failure.
-        const meta = await loadMeta(path.dirname(repo.lbugPath));
         try {
             // meta.json is on-disk state inside the analyzed repo, read via a
             // schema-less JSON.parse — not trusted input. Validate before
@@ -2623,7 +2647,9 @@ export class LocalBackend {
     /**
      * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
      */
-    async bm25Search(repo, query, limit) {
+    async bm25Search(repo, query, limit, disabledReason) {
+        if (disabledReason)
+            return { results: [], ftsUsed: false };
         let searchFTSFromLbug;
         try {
             ({ searchFTSFromLbug } = await import('../../core/search/bm25-index.js'));

package/dist/mcp/repository-policy.js

@@ -148,26 +148,28 @@ export class McpRepositoryPolicy {
                 mutatingRequiresRepo: requiresRepo,
             };
         }
-        // One fresh listing supplies both schema decisions. Besides keeping the
-        // advertised contract internally consistent, this avoids doing two full
-        // per-repo staleness fan-outs for every tools/list request.
-        const visibleRepos = await this.listAllowedRepos(backend);
-        if (visibleRepos.length <= 1) {
+        // Validated registry cardinality only — no listRepos() staleness git.
+        // The 0–1 arm stays a cheap countRepos() (no refreshRepos / kuzu cleanup).
+        const repoCount = await backend.countRepos();
+        if (repoCount <= 1) {
             return { readOnlyRequiresRepo: false, mutatingRequiresRepo: false };
         }
         try {
-            // listAllowedRepos() refreshed this backend immediately above. Resolve
-            // against that exact cache snapshot instead of racing another registry
-            // read; only read-only schemas may advertise the cwd-derived default.
+            // countRepos() does not refresh the backend; this cwd probe must.
             await backend.selectToolRepository(undefined, undefined, {
                 allowCwdDefault: true,
-                refreshRegistry: false,
+                refreshRegistry: true,
             });
-            return { readOnlyRequiresRepo: false, mutatingRequiresRepo: true };
         }
         catch {
             return { readOnlyRequiresRepo: true, mutatingRequiresRepo: true };
         }
+        // The probe just refreshed. If that snapshot is now a singleton, match the
+        // <=1 arm rather than advertising a split mutating-only schema.
+        if (backend.cachedRepoCount() <= 1) {
+            return { readOnlyRequiresRepo: false, mutatingRequiresRepo: false };
+        }
+        return { readOnlyRequiresRepo: false, mutatingRequiresRepo: true };
     }
     async listReposPage(backend, params) {
         const { limit, offset } = parseListReposPagination(params, {

package/dist/server/api.js

@@ -18,6 +18,7 @@ import { NODE_TABLES } from '../_shared/index.js';
 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 { getFtsDisabledReason } from '../core/search/fts-policy.js';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { installServeMcpAuth, mountMCPEndpoints } from './mcp-http.js';
 import { fileURLToPath } from 'url';
@@ -574,6 +575,18 @@ export const handleFileRequest = async (req, res, repoPath) => {
         }
     }
 };
+async function loadFtsSession(storagePath) {
+    const meta = await loadMeta(storagePath);
+    const ftsDisabledReason = getFtsDisabledReason(meta?.capabilities?.fts);
+    return {
+        meta,
+        ftsDisabledReason,
+        ...(ftsDisabledReason ? { skipFts: true } : {}),
+    };
+}
+function readOnlyFtsOptions(skipFts) {
+    return skipFts ? { readOnly: true, skipFts: true } : { readOnly: true };
+}
 export const handleQueryRequest = async (req, res, resolveRepo) => {
     try {
         const cypher = req.body.cypher;
@@ -594,9 +607,8 @@ export const handleQueryRequest = async (req, res, resolveRepo) => {
             return;
         }
         const lbugPath = path.join(entry.storagePath, 'lbug');
-        const result = await withLbugDb(lbugPath, () => executePrepared(cypher, queryParams ?? {}), {
-            readOnly: true,
-        });
+        const { skipFts } = await loadFtsSession(entry.storagePath);
+        const result = await withLbugDb(lbugPath, () => executePrepared(cypher, queryParams ?? {}), readOnlyFtsOptions(skipFts));
         res.json({ result });
     }
     catch (err) {
@@ -950,6 +962,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             const lbugPath = path.join(entry.storagePath, 'lbug');
             const includeContent = req.query.includeContent === 'true';
             const stream = req.query.stream === 'true';
+            const { skipFts } = await loadFtsSession(entry.storagePath);
             if (stream) {
                 const abortController = new AbortController();
                 let responseFinished = false;
@@ -974,7 +987,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     // "Cannot open file ... lbug.shadow - Error 2". See pool-adapter.ts
                     // which already opens read-only for the same reason, and the
                     // /api/query precedent in PR #1655.
-                    await withLbugDb(lbugPath, async () => streamGraphNdjson(res, includeContent, abortController.signal), { readOnly: true });
+                    await withLbugDb(lbugPath, async () => streamGraphNdjson(res, includeContent, abortController.signal), readOnlyFtsOptions(skipFts));
                     if (!abortController.signal.aborted && !res.writableEnded) {
                         res.end();
                     }
@@ -986,9 +999,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 }
                 return;
             }
-            const graph = await withLbugDb(lbugPath, async () => buildGraph(includeContent), {
-                readOnly: true,
-            });
+            const graph = await withLbugDb(lbugPath, async () => buildGraph(includeContent), readOnlyFtsOptions(skipFts));
             res.json(graph);
         }
         catch (err) {
@@ -1028,6 +1039,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             }
             const lbugPath = path.join(entry.storagePath, 'lbug');
             const parsedLimit = Number(req.body.limit ?? 10);
+            const { ftsDisabledReason, skipFts } = await loadFtsSession(entry.storagePath);
             const limit = Number.isFinite(parsedLimit)
                 ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
                 : 10;
@@ -1052,7 +1064,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     }));
                 }
                 else if (mode === 'bm25') {
-                    const ftsResponse = await searchFTSFromLbug(query, limit);
+                    const ftsResponse = await searchFTSFromLbug(query, limit, undefined, ftsDisabledReason);
                     ftsAvailable = ftsResponse.ftsAvailable;
                     searchResults = ftsResponse.results.map((r, i) => ({
                         ...r,
@@ -1065,10 +1077,12 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
                     if (isEmbedderReady()) {
                         const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
-                        searchResults = await hybridSearch(query, limit, executeQuery, semSearch);
+                        searchResults = await hybridSearch(query, limit, executeQuery, semSearch, ftsDisabledReason);
+                        if (ftsDisabledReason)
+                            ftsAvailable = false;
                     }
                     else {
-                        const ftsResponse = await searchFTSFromLbug(query, limit);
+                        const ftsResponse = await searchFTSFromLbug(query, limit, undefined, ftsDisabledReason);
                         ftsAvailable = ftsResponse.ftsAvailable;
                         searchResults = ftsResponse.results;
                     }
@@ -1141,10 +1155,10 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     return { ...r, ...enrichment };
                 }));
                 return { searchResults: enriched, ftsAvailable };
-            }, { readOnly: true });
+            }, readOnlyFtsOptions(skipFts));
             const response = { results: results.searchResults ?? results };
             if (results.ftsAvailable === false) {
-                response.warning = ftsDegradedWarning();
+                response.warning = ftsDegradedWarning(undefined, ftsDisabledReason);
             }
             res.json(response);
         }
@@ -1179,8 +1193,9 @@ export const createServer = async (port, host = '127.0.0.1') => {
             // cut a stuck regex.test() when the wall-clock budget expires.
             const { regex, fileFilter, limit } = parseGrepQuery(req.query);
             const repoRoot = path.resolve(entry.path);
+            const { skipFts } = await loadFtsSession(entry.storagePath);
             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 });
+            const fileRows = await withLbugDb(lbugPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`), readOnlyFtsOptions(skipFts));
             const filePaths = [];
             for (const row of fileRows) {
                 const filePath = row.filePath || '';
@@ -1512,11 +1527,12 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 let partialRunDetail;
                 try {
                     const lbugPath = path.join(entry.storagePath, 'lbug');
+                    const ftsSession = await loadFtsSession(entry.storagePath);
+                    let embeddingMeta = ftsSession.meta;
                     await withLbugDb(lbugPath, async () => {
                         const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
                         const { resolveEmbeddingIdentity } = await import('../core/embeddings/embedding-identity.js');
                         const embeddingIdentity = resolveEmbeddingIdentity();
-                        let embeddingMeta = await loadMeta(entry.storagePath);
                         if (!embeddingMeta) {
                             throw new Error('Repository metadata is missing; run gitnexus analyze first');
                         }
@@ -1654,7 +1670,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         partialRunDetail = outcome.partial;
                         embeddingMeta = withMeasuredEmbeddingCount({ ...finalMeta, embeddingCheckpoint: outcome.checkpoint }, measuredEmbeddings);
                         await saveMeta(entry.storagePath, embeddingMeta);
-                    });
+                    }, { ...(ftsSession.skipFts ? { skipFts: true } : {}) });
                     // Don't overwrite 'failed' if the job was cancelled while the pipeline was running
                     const current = embedJobManager.getJob(job.id);
                     if (!current || current.status !== 'failed') {

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

@@ -159,23 +159,24 @@ export interface RepoMeta {
              * `'unavailable'` (#2841). Mirrors `AnalysisResult.ftsSkipReason` in
              * core/run-analyze.ts — the same discriminator that surface already
              * reports to the CLI, persisted rather than re-derived because the two
-             * causes need OPPOSITE handling on the next run:
+             * causes need distinct diagnostics and recovery handling:
              *
              *  - `extension-unavailable` — the FTS extension could not load. Healable
-             *    from outside the repo (install it), so the up-to-date fast path
-             *    probes whether it loads now and re-analyzes when it does.
+             *    from outside the repo (install it), then rebuild with --repair-fts.
              *  - `build-failed` — the extension loaded fine and the index BUILD
              *    failed (e.g. one un-tokenizable pre-existing row, #2544/#2546).
              *    Deterministic: the same probe would "heal" it into a full
              *    re-analysis that degrades identically and restamps, forever. Only
              *    `--repair-fts` or a content change addresses it.
+             *  - `disabled-by-flag` / `disabled-by-env` — deliberate opt-out.
+             *    A later analyze without the opt-out rebuilds FTS at the same commit.
              *
              * Collapsing both into `status: 'unavailable'` is exactly what made that
              * loop reachable. ABSENT on indexes written before #2841 and on the
              * `--repair-fts` stamp (which writes `status: 'available'`); `undefined`
              * therefore reads as "cause unknown" and keeps the pre-#2841 behaviour.
              */
-            skipReason?: 'extension-unavailable' | 'build-failed';
+            skipReason?: 'extension-unavailable' | 'build-failed' | 'disabled-by-flag' | 'disabled-by-env';
         };
         vectorSearch: {
             provider: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.12-rc.32",
+  "version": "1.6.12-rc.34",
   "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",

package/scripts/cross-platform-tests.ts

@@ -142,6 +142,7 @@ const PLATFORM_LOGIC = [
 // N-API addon which has known platform-specific behavior (Windows
 // file-lock lag after close, macOS N-API destructor segfaults)
 const LBUG_NATIVE = [
+  'test/integration/skip-fts.test.ts',
   'test/integration/lbug-core-adapter.test.ts',
   'test/integration/lbug-vector-extension.test.ts',
   'test/integration/lbug-pool.test.ts',