gitnexus 1.6.12 → 1.6.13-rc.2

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

@@ -11,6 +11,8 @@ import { warnIfQueryTextUnbounded } from './query-batch.js';
 import { escapeCypherString } from './cypher-escape.js';
 import { withConnLock } from './conn-lock.js';
 import { isWalDriverActive } from './wal-driver-state.js';
+import { loadMeta } from '../../storage/repo-meta.js';
+import { allowsFtsCrashWalPark, hasRecoveredInPlaceFtsAbort } from '../search/fts-crash-marker.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
 // Analyze-only, but reached from MCP startup via `pool-adapter.js`. #2802
 // proposed lazy-importing it; rejected — `core/search/bm25-index.ts` statically
@@ -25,9 +27,10 @@ import { EMBEDDABLE_LABELS } from '../embeddings/types.js';
 import { extensionManager, getFtsCapability, resolveAnalyzeInstallPolicy, } from './extension-loader.js';
 // Remedy classification for LOAD failures (#2374/#2383). Pure + node:fs only, so
 // this adds no cycle: `extension-loader.ts` already depends on it.
-import { diagnoseExtensionLoad } from './extension-load-error.js';
+import { diagnoseExtensionLoad, extractExtensionPath } from './extension-load-error.js';
+import { resolveFtsVersionPair } from './vendored-extension-path.js';
 import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isStorageVersionMismatchError, isWalCorruptionError, throwIfStorageVersionMismatch, bufferPoolExhaustionRemedy, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
-import { cleanQuarantinedMissingShadowWals, finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, lbugLockRemediation, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, sidecarPreflightDisabled, } from './sidecar-recovery.js';
+import { assertReadOnlyFtsCrashSafe, cleanQuarantinedMissingShadowWals, finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, lbugLockRemediation, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, sidecarPreflightDisabled, } from './sidecar-recovery.js';
 import { isProcessAlive } from '../../utils/process-identity.js';
 import { logger } from '../logger.js';
 import { SPRING_AUTO_CONFIGURATION_REASONS, SPRING_AUTO_CONFIGURATION_SYNTHETIC_ID_PREFIX, } from '../ingestion/frameworks/spring/auto-configuration.js';
@@ -196,10 +199,9 @@ const DB_LOCK_RETRY_DELAY_MS = 500;
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
- * so any path that calls a `CREATE_*` procedure there will surface this
- * (e.g. defensive `ensureFTSIndex` calls). Owners of the writable analyze
- * path should ignore this error — index creation is owned by `gitnexus
- * analyze` and either already happened or will happen on the next run.
+ * so any path that calls a `CREATE_*` procedure there will surface this.
+ * Index creation is owned by `gitnexus analyze` and either already happened
+ * or will happen on the next run.
  */
 export const isReadOnlyDbError = (err) => {
     // Walk the `cause` chain (bounded) so a wrapped read-only error — e.g. the
@@ -426,8 +428,10 @@ const READ_ONLY_SHADOW_REPLAY_PROBE = 'MATCH (n) RETURN n LIMIT 1';
  * `guardWalQuarantine` (sidecar-recovery.ts) so serve and the MCP pool share
  * one source of truth (PR #1747 review D2; issue #2382 review, Finding B).
  */
-const refuseLargeWalQuarantine = async (dbPath, mode, triggeringErr) => {
-    await guardWalQuarantine(dbPath, mode, triggeringErr, logger);
+const refuseLargeWalQuarantine = async (dbPath, mode, triggeringErr, crashEvidence) => {
+    // Latitude defaults to refusal. Only the analyze writer passes
+    // `fts-inplace-checkpointed`; serve never does (R9).
+    await guardWalQuarantine(dbPath, mode, triggeringErr, logger, crashEvidence);
 };
 const reopenReadOnlyAfterMissingShadow = async (dbPath, err) => {
     await refuseLargeWalQuarantine(dbPath, 'read-only', err);
@@ -454,8 +458,25 @@ const reopenReadOnlyAfterMissingShadow = async (dbPath, err) => {
         throw retryErr;
     }
 };
+const writableFtsCrashWalEvidence = async (dbPath) => {
+    try {
+        const meta = await loadMeta(path.dirname(dbPath));
+        if (meta &&
+            (allowsFtsCrashWalPark(meta.incrementalInProgress) ||
+                hasRecoveredInPlaceFtsAbort(meta.capabilities?.fts))) {
+            return { kind: 'fts-inplace-checkpointed' };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+};
 const reopenWritableAfterMissingShadow = async (dbPath, err) => {
-    await refuseLargeWalQuarantine(dbPath, 'writable', err);
+    // Analyze writers may park a leftover in-place FTS abort WAL. Serve/embed
+    // refuse first via assertReadOnlyFtsCrashSafe and must not pass this
+    // evidence themselves (R9); read-only reopen never parks.
+    await refuseLargeWalQuarantine(dbPath, 'writable', err, await writableFtsCrashWalEvidence(dbPath));
     try {
         await quarantineWalForMissingShadow(dbPath, {
             logger,
@@ -662,6 +683,7 @@ const doInitLbug = async (dbPath, options = {}) => {
     // create databases and don't need the lock.
     // ---------------------------------------------------------------------------
     if (readOnly) {
+        await assertReadOnlyFtsCrashSafe(dbPath);
         await preflightLbugSidecars(dbPath, {
             mode: 'read-only',
             logger,
@@ -2984,8 +3006,8 @@ export const loadVectorExtension = async (targetConn, opts = {}) => {
 };
 /**
  * Default stemmer for FTS indexes. Single source so the analyze path
- * (`getSearchFTSStemmer`) and the read-only `createFTSIndex`/`ensureFTSIndex`
- * defaults can never silently diverge.
+ * (`getSearchFTSStemmer`) and `createFTSIndex` defaults can never silently
+ * diverge.
  */
 export const DEFAULT_FTS_STEMMER = 'porter';
 /**
@@ -3284,41 +3306,6 @@ export const ensureFtsRowDmlSafe = async (indexRows, options = {}) => {
         return false;
     return await loadFTSExtension(undefined, { policy: resolveAnalyzeInstallPolicy() });
 };
-/**
- * Lazy-create an FTS index, caching the fact in-process.
- *
- * Kept for writable maintenance paths that need to lazily materialize an
- * index. Read-only query paths must not call this; production analysis owns
- * creating the configured search indexes before the database is served.
- *
- * Safe to call repeatedly — the in-process Set guarantees only the first
- * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
- *
- * Defense in depth: if the active connection is read-only (e.g. the MCP
- * pool adapter), `CREATE_FTS_INDEX` will fail with "Cannot execute write
- * operations in a read-only database". Treat that as a no-op and cache
- * the key so callers don't loop on a path that can never succeed here —
- * the index is owned by `gitnexus analyze` (writable) and either already
- * exists or will be created on the next analyze.
- */
-export const ensureFTSIndex = async (tableName, indexName, properties, stemmer = DEFAULT_FTS_STEMMER) => {
-    const key = ftsIndexKey(tableName, indexName);
-    if (ensuredFTSIndexes.has(key))
-        return;
-    try {
-        await createFTSIndex(tableName, indexName, properties, stemmer);
-    }
-    catch (e) {
-        // Read-only DB: writable analyze owns index creation; silently skip
-        // and cache so callers don't loop on a path that can never succeed
-        // here (the MCP query pool opens DBs read-only by design).
-        if (isReadOnlyDbError(e)) {
-            ensuredFTSIndexes.add(key);
-            return;
-        }
-        throw e;
-    }
-};
 /**
  * Classify a `QUERY_FTS_INDEX` failure so a genuinely-missing index (normal —
  * this table's FTS index hasn't been built yet) is distinguished from a real
@@ -3541,7 +3528,9 @@ export const dropFTSIndex = async (tableName, indexName) => {
             // extension binary is not re-inspected, falling back to a fresh structural
             // diagnosis when nothing recorded one.
             const ftsCapability = getFtsCapability();
-            const { remedy } = ftsCapability?.diagnosis ?? diagnoseExtensionLoad(ftsCapability?.reason);
+            const inspectPath = extractExtensionPath(ftsCapability?.reason);
+            const { remedy } = ftsCapability?.diagnosis ??
+                diagnoseExtensionLoad(ftsCapability?.reason, 'FTS', inspectPath, resolveFtsVersionPair(inspectPath));
             // Deliberately message-only: `remedy` is generated text (fixed system paths
             // at most), and LadybugDB's own path-bearing `reason` is NEVER interpolated
             // here — the #2374/#2375 redaction contract.

package/dist/core/lbug/native-check.d.ts

@@ -29,7 +29,11 @@ export interface FtsProbeResult {
     loaded: boolean;
     /** Collapsed LadybugDB error when `loaded` is false. */
     reason?: string;
+    /** Policy `never` refused the probe — not a load failure. */
+    suppressed?: boolean;
 }
+export type FtsAvailabilityLabel = 'available' | 'unavailable' | 'suppressed';
+export declare const ftsAvailabilityLabel: (probe: FtsProbeResult) => FtsAvailabilityLabel;
 /** Same shape for every optional extension; `FtsProbeResult` is the legacy name. */
 export type ExtensionProbeResult = FtsProbeResult;
 /**
@@ -48,7 +52,16 @@ export type ExtensionProbeResult = FtsProbeResult;
  * cannot cancel an in-flight native call, so a future thread-blocking case
  * would need an out-of-process probe.
  */
-export declare function probeFtsExtensionLoad(timeoutMs?: number): Promise<FtsProbeResult>;
+/** Local copy of the env policy parse — must not import extension-loader
+ *  (that module statically pulls lbug-config, which would break doctor when
+ *  the native addon is missing). */
+type ProbeInstallPolicy = 'auto' | 'load-only' | 'never';
+export interface FtsProbeOptions {
+    policy?: ProbeInstallPolicy;
+    /** Injected vendored path. `null` skips path-LOAD; omit to resolve from disk. */
+    vendoredPath?: string | null;
+}
+export declare function probeFtsExtensionLoad(timeoutMs?: number, opts?: FtsProbeOptions): Promise<FtsProbeResult>;
 /**
  * Live-probe `LOAD EXTENSION vector`, the VECTOR counterpart of the FTS probe.
  *
@@ -65,3 +78,4 @@ export declare function probeFtsExtensionLoad(timeoutMs?: number): Promise<FtsPr
  * as the FTS one above.
  */
 export declare function probeVectorExtensionLoad(timeoutMs?: number): Promise<ExtensionProbeResult>;
+export {};

package/dist/core/lbug/native-check.js

@@ -2,6 +2,8 @@ import fs from 'fs';
 import path from 'path';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
+import { escapeCypherString } from './cypher-escape.js';
+import { resolveVendoredFtsPath } from './vendored-extension-path.js';
 /** Cap the out-of-process native load probe so a hung filesystem cannot wedge a
  *  CLI startup gate (same bounding rationale as the extension probe below). */
 const NATIVE_LOAD_PROBE_TIMEOUT_MS = 15_000;
@@ -334,6 +336,13 @@ export function glibcTooOldMessage(stderr) {
         '  - Or use the GitNexus container image, which bundles a current glibc.',
     ].join('\n');
 }
+export const ftsAvailabilityLabel = (probe) => {
+    if (probe.loaded)
+        return 'available';
+    if (probe.suppressed)
+        return 'suppressed';
+    return 'unavailable';
+};
 const DEFAULT_FTS_PROBE_TIMEOUT_MS = 10_000;
 /** Close each result, swallowing close-time errors so a successful LOAD is not
  *  misreported as a failure (native-check keeps no static lbug dependency, so it
@@ -349,24 +358,23 @@ const closeProbeResults = (result) => {
         }
     }
 };
-/**
- * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
- *
- * `doctor` used to print the static platform capability, which contradicted
- * analyze whenever the extension file was missing or unloadable (#2374).
- * LOAD never touches the network, so the probe is safe offline, and it
- * surfaces LadybugDB's real error — which distinguishes a missing extension
- * file from a present-but-broken one (wrong platform, truncated download).
- * Dynamic import so doctor still runs when the native module itself is broken.
- *
- * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
- * network home dir) must never freeze `doctor` — the tool the degradation
- * warnings send users to. `Promise.race` lets doctor report and move on; it
- * cannot cancel an in-flight native call, so a future thread-blocking case
- * would need an out-of-process probe.
- */
-export async function probeFtsExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIMEOUT_MS) {
-    return await probeExtensionLoad('fts', timeoutMs);
+const resolveProbeInstallPolicy = () => {
+    const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'load-only';
+};
+export async function probeFtsExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIMEOUT_MS, opts) {
+    const policy = opts?.policy ?? resolveProbeInstallPolicy();
+    if (policy === 'never') {
+        return {
+            loaded: false,
+            suppressed: true,
+            reason: 'suppressed by policy GITNEXUS_LBUG_EXTENSION_INSTALL=never',
+        };
+    }
+    const vendoredPath = opts?.vendoredPath !== undefined ? opts.vendoredPath : resolveVendoredFtsPath();
+    return await probeExtensionLoad('fts', timeoutMs, vendoredPath);
 }
 /**
  * Live-probe `LOAD EXTENSION vector`, the VECTOR counterpart of the FTS probe.
@@ -389,7 +397,7 @@ export async function probeVectorExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIM
 /**
  * Shared LOAD probe. `extension` is a fixed internal literal, never user input.
  */
-async function probeExtensionLoad(extension, timeoutMs) {
+async function probeExtensionLoad(extension, timeoutMs, vendoredPath) {
     let timer;
     const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve({
@@ -397,6 +405,11 @@ async function probeExtensionLoad(extension, timeoutMs) {
             reason: 'probe timed out — extension file or filesystem unresponsive',
         }), timeoutMs);
     });
+    const statements = [];
+    if (extension === 'fts' && vendoredPath) {
+        statements.push(`LOAD EXTENSION '${escapeCypherString(path.resolve(vendoredPath))}'`);
+    }
+    statements.push(`LOAD EXTENSION ${extension}`);
     const probe = (async () => {
         try {
             const { default: lbug } = await import('@ladybugdb/core');
@@ -405,9 +418,19 @@ async function probeExtensionLoad(extension, timeoutMs) {
             try {
                 const conn = new lbug.Connection(db);
                 try {
-                    const result = await conn.query(`LOAD EXTENSION ${extension}`);
-                    closeProbeResults(result);
-                    return { loaded: true };
+                    let lastReason;
+                    for (const sql of statements) {
+                        try {
+                            const result = await conn.query(sql);
+                            closeProbeResults(result);
+                            return { loaded: true };
+                        }
+                        catch (err) {
+                            const message = err instanceof Error ? err.message : String(err);
+                            lastReason = message.replace(/\s+/g, ' ').trim();
+                        }
+                    }
+                    return { loaded: false, reason: lastReason };
                 }
                 finally {
                     await conn.close().catch(() => { });

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

@@ -20,7 +20,7 @@ import { isReadOnlyDbError, loadFTSExtension, loadVectorExtension } from './lbug
 import { closeQueryResults } from './query-result-utils.js';
 import { warnIfQueryTextUnbounded } from './query-batch.js';
 import { createLbugDatabase, isWalCorruptionError, sleep, throwIfStorageVersionMismatch, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
-import { guardWalQuarantine, isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
+import { assertReadOnlyFtsCrashSafe, FtsReaderUnrepairableError, guardWalQuarantine, isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
 export async function statDbIdentity(dbPath) {
     try {
         const s = await fs.stat(dbPath);
@@ -439,6 +439,9 @@ async function tryQuarantineForMissingShadow(dbPath, opts) {
     // refuseLargeWalQuarantine (issue #2382 review, Finding B). Kept OUTSIDE the
     // try so the actionable recovery message propagates to the MCP caller rather
     // than being re-wrapped as a rename failure.
+    // Never pass crash evidence: the pool is a reader/MCP surface and must
+    // keep today's large-WAL refusal (R9). Analyze parks via the dirty-recovery
+    // family before it opens.
     await guardWalQuarantine(dbPath, opts.reason, opts.err, poolSidecarLogger);
     try {
         const quarantinePath = await quarantineWalForMissingShadow(dbPath, {
@@ -502,6 +505,7 @@ async function openReadOnlyDatabase(dbPath) {
     let db;
     silenceStdout();
     try {
+        await assertReadOnlyFtsCrashSafe(dbPath);
         await preflightLbugSidecars(dbPath, {
             mode: 'read-only',
             logger: poolSidecarLogger,
@@ -706,6 +710,9 @@ async function doInitLbug(repoId, dbPath) {
             // Not retryable: the on-disk file's storage version doesn't change
             // on its own. Fail immediately with an actionable message.
             throwIfStorageVersionMismatch(lastError);
+            if (lastError instanceof FtsReaderUnrepairableError) {
+                throw lastError;
+            }
             if (isWalCorruptionError(lastError)) {
                 try {
                     const db = await tryQuarantineAndReopen(dbPath, repoId);

package/dist/core/lbug/sidecar-recovery.d.ts

@@ -25,6 +25,31 @@ export interface SidecarRecoveryLogger {
     debug?: (message: string) => void;
 }
 export declare const TINY_ORPHAN_WAL_BYTES: number;
+/**
+ * Analyze-writer crash evidence for WAL quarantine latitude (KTD5).
+ * `mode` is a warning label only and must not carry this. Omit on serve
+ * and the MCP pool — those keep today's large-WAL refusal.
+ */
+export type WalCrashEvidence = {
+    readonly kind: 'fts-inplace-checkpointed';
+};
+export declare const CLEAN_LBUG_SIDECARS_COMMAND = "gitnexus clean --lbug-sidecars";
+export declare const FTS_READER_REPAIR_COMMAND = "gitnexus analyze --repair-fts";
+export declare const ftsReaderRefuseMessage: (dbPath: string) => string;
+export declare class FtsReaderUnrepairableError extends Error {
+    readonly code: "FTS_READER_UNREPAIRABLE";
+    constructor(dbPath: string);
+}
+/**
+ * Advisory reader gate (KTD10 / R9b). When meta names an in-place FTS
+ * abort (live dirty flag, or a persisted in-place `native-abort`) and a
+ * WAL is still live, refuse before the native open. Does not write,
+ * rename, or repair. Parking still requires the conjunctive
+ * `allowsFtsCrashWalPark` warrant. Missing or unreadable meta falls
+ * through to today's open path.
+ */
+export declare const assertReadOnlyFtsCrashSafe: (dbPath: string) => Promise<void>;
+export declare const ftsCrashParkFailureMessage: (failedPath: string, err?: unknown) => string;
 export declare const isMissingFsError: (err: unknown) => boolean;
 export declare const sidecarPreflightDisabled: () => boolean;
 export declare const statIfExists: (filePath: string) => Promise<{
@@ -96,7 +121,7 @@ export declare function inspectLbugSidecars(dbPath: string): Promise<LbugSidecar
  * the existing recovery path is safe to proceed. `mode` is a label used only in
  * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').
  */
-export declare const guardWalQuarantine: (dbPath: string, mode: string, triggeringErr: unknown, logger: SidecarRecoveryLogger) => Promise<void>;
+export declare const guardWalQuarantine: (dbPath: string, mode: string, triggeringErr: unknown, logger: SidecarRecoveryLogger, crashEvidence?: WalCrashEvidence) => Promise<void>;
 export declare function quarantineWalForMissingShadow(dbPath: string, options: {
     logger: SidecarRecoveryLogger;
     level?: 'debug' | 'info' | 'warn';
@@ -175,6 +200,12 @@ export declare function finalizeLbugSidecarsAfterClose(dbPath: string, options:
  * every subsequent open this run performs is replay-free — or the entry is
  * in `failed` and the caller MUST abort before any DB open.
  *
+ * Retention: these parks are not reclaimed on the next writable open
+ * (unlike missing-shadow quarantines). FTS-phase parks stay until
+ * `gitnexus clean --lbug-sidecars` or the next park overwrites the same
+ * fixed `.dirty-recovery` name. That is intentional — the parked bytes
+ * are the only forensic copy of a proven in-place abort.
+ *
  * @returns `moved` — destination paths now holding the parked bytes;
  * `removed` — source sidecars whose bytes are GONE (forensics lost, replay
  * risk eliminated); `failed` — source sidecars still in place: a

package/dist/core/lbug/sidecar-recovery.js

@@ -1,7 +1,56 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { loadMeta } from '../../storage/repo-meta.js';
+import { shouldRefuseFtsCrashWal } from '../search/fts-crash-marker.js';
 import { HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, sleep, } from './lbug-config.js';
 export const TINY_ORPHAN_WAL_BYTES = 4 * 1024;
+export const CLEAN_LBUG_SIDECARS_COMMAND = 'gitnexus clean --lbug-sidecars';
+export const FTS_READER_REPAIR_COMMAND = 'gitnexus analyze --repair-fts';
+export const ftsReaderRefuseMessage = (dbPath) => `Cannot open ${path.basename(dbPath)} read-only after an in-place FTS abort. ` +
+    `The leftover WAL would replay and kill this process. ` +
+    `Run \`${FTS_READER_REPAIR_COMMAND}\` after stopping any GitNexus MCP or serve process.`;
+export class FtsReaderUnrepairableError extends Error {
+    code = 'FTS_READER_UNREPAIRABLE';
+    constructor(dbPath) {
+        super(ftsReaderRefuseMessage(dbPath));
+        this.name = 'FtsReaderUnrepairableError';
+    }
+}
+const sidecarHasLiveWal = (state) => state.kind === 'orphan-wal' ||
+    state.kind === 'tiny-orphan-wal' ||
+    state.kind === 'wal-with-shadow';
+/**
+ * Advisory reader gate (KTD10 / R9b). When meta names an in-place FTS
+ * abort (live dirty flag, or a persisted in-place `native-abort`) and a
+ * WAL is still live, refuse before the native open. Does not write,
+ * rename, or repair. Parking still requires the conjunctive
+ * `allowsFtsCrashWalPark` warrant. Missing or unreadable meta falls
+ * through to today's open path.
+ */
+export const assertReadOnlyFtsCrashSafe = async (dbPath) => {
+    let meta;
+    try {
+        meta = await loadMeta(path.dirname(dbPath));
+    }
+    catch {
+        return;
+    }
+    if (!meta || !shouldRefuseFtsCrashWal(meta.incrementalInProgress, meta.capabilities?.fts)) {
+        return;
+    }
+    const state = await inspectLbugSidecars(dbPath);
+    if (!sidecarHasLiveWal(state))
+        return;
+    throw new FtsReaderUnrepairableError(dbPath);
+};
+export const ftsCrashParkFailureMessage = (failedPath, err) => {
+    const detail = err instanceof Error ? err.message : err != null ? String(err) : '';
+    return (`Cannot park ${path.basename(failedPath)} after an in-place FTS abort` +
+        (detail ? ` (${detail})` : '') +
+        `. The database was not opened. Run \`${CLEAN_LBUG_SIDECARS_COMMAND}\` ` +
+        'after stopping any GitNexus MCP or serve process, then retry ' +
+        '`gitnexus analyze` or `gitnexus analyze --repair-fts`.');
+};
 /**
  * Counter-based warn anti-spam (PR #1747 review, Finding 6).
  *
@@ -251,7 +300,7 @@ export async function inspectLbugSidecars(dbPath) {
  * the existing recovery path is safe to proceed. `mode` is a label used only in
  * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').
  */
-export const guardWalQuarantine = async (dbPath, mode, triggeringErr, logger) => {
+export const guardWalQuarantine = async (dbPath, mode, triggeringErr, logger, crashEvidence) => {
     const state = await inspectLbugSidecars(dbPath);
     if (state.kind === 'wal-with-shadow') {
         warnOnce(logger, `${dbPath}:present-shadow-refuse:${mode}`, `GitNexus: refusing to quarantine WAL at ${dbPath}.wal during ${mode} recovery — ` +
@@ -260,6 +309,13 @@ export const guardWalQuarantine = async (dbPath, mode, triggeringErr, logger) =>
         throw new Error(presentShadowUnreachableMessage(dbPath, triggeringErr));
     }
     if (state.kind === 'orphan-wal') {
+        if (crashEvidence?.kind === 'fts-inplace-checkpointed') {
+            const { failed } = await quarantineSidecarsForDirtyRecovery(dbPath, (message) => logger.warn(message));
+            if (failed.length > 0) {
+                throw new Error(ftsCrashParkFailureMessage(failed[0]));
+            }
+            return;
+        }
         warnOnce(logger, `${dbPath}:large-wal-refuse:${mode}`, `GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +
             'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.');
         throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));
@@ -449,6 +505,12 @@ const dirtyRecoveryParkedNames = (dbPath) => DIRTY_RECOVERY_SIDECAR_SUFFIXES.fla
  * every subsequent open this run performs is replay-free — or the entry is
  * in `failed` and the caller MUST abort before any DB open.
  *
+ * Retention: these parks are not reclaimed on the next writable open
+ * (unlike missing-shadow quarantines). FTS-phase parks stay until
+ * `gitnexus clean --lbug-sidecars` or the next park overwrites the same
+ * fixed `.dirty-recovery` name. That is intentional — the parked bytes
+ * are the only forensic copy of a proven in-place abort.
+ *
  * @returns `moved` — destination paths now holding the parked bytes;
  * `removed` — source sidecars whose bytes are GONE (forensics lost, replay
  * risk eliminated); `failed` — source sidecars still in place: a

package/dist/core/lbug/vendored-extension-path.d.ts

@@ -0,0 +1,26 @@
+export declare const defaultVendorRoot: () => string;
+export declare const nodePlatformTuple: (platform?: NodeJS.Platform, arch?: string) => string;
+export interface FtsArtifactManifest {
+    coreVersion?: string;
+    extensionVersion?: string;
+    filename?: string;
+    unsupportedTuples?: Array<{
+        tuple: string;
+        reason?: string;
+    }>;
+}
+export declare const readFtsArtifactManifest: (vendorRoot?: string) => FtsArtifactManifest;
+export declare const isUnsupportedFtsTuple: (tuple: string, vendorRoot?: string) => boolean;
+/** Relative-path containment — not a prefix match (rejects `vendor-evil`). */
+export declare const isPathInsideRoot: (root: string, candidate: string) => boolean;
+export declare const validateVendoredExtensionPath: (candidate: string, vendorRoot: string) => string | null;
+export declare const inferExtensionVersionFromPath: (filePath: string | null | undefined) => string | undefined;
+export declare const resolveFtsVersionPair: (inspectPath?: string | null, vendorRoot?: string) => {
+    expected?: string;
+    found?: string;
+};
+export declare const resolveVendoredFtsPath: (opts?: {
+    tuple?: string;
+    vendorRoot?: string;
+    filename?: string;
+}) => string | null;

package/dist/core/lbug/vendored-extension-path.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { VENDOR_ROOT } from '../vendor-root.js';
+/**
+ * Resolve the packaged FTS extension for this process's Node platform tuple.
+ *
+ * Lives here (not in extension-loader) so the doctor startup probe can share
+ * the same path without importing the loader, which statically pulls lbug-config.
+ */
+const DEFAULT_FILENAME = 'libfts.lbug_extension';
+export const defaultVendorRoot = () => VENDOR_ROOT;
+export const nodePlatformTuple = (platform = process.platform, arch = process.arch) => `${platform}-${arch}`;
+const asOptionalString = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+/** Drop non-array / non-object entries so `.some(entry => entry.tuple)` cannot throw. */
+const asUnsupportedTuples = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const tuple = entry.tuple;
+        if (typeof tuple !== 'string' || tuple.length === 0)
+            continue;
+        const reason = entry.reason;
+        entries.push({
+            tuple,
+            ...(typeof reason === 'string' ? { reason } : {}),
+        });
+    }
+    return entries;
+};
+export const readFtsArtifactManifest = (vendorRoot = defaultVendorRoot()) => {
+    const manifestPath = path.join(vendorRoot, 'lbug-fts', 'manifest.json');
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const rec = parsed;
+            return {
+                coreVersion: asOptionalString(rec.coreVersion),
+                extensionVersion: asOptionalString(rec.extensionVersion),
+                filename: asOptionalString(rec.filename),
+                unsupportedTuples: asUnsupportedTuples(rec.unsupportedTuples),
+            };
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+};
+export const isUnsupportedFtsTuple = (tuple, vendorRoot = defaultVendorRoot()) => (readFtsArtifactManifest(vendorRoot).unsupportedTuples ?? []).some((entry) => entry.tuple === tuple);
+/** Relative-path containment — not a prefix match (rejects `vendor-evil`). */
+export const isPathInsideRoot = (root, candidate) => {
+    const relative = path.relative(root, candidate);
+    if (path.isAbsolute(relative))
+        return false;
+    return relative !== '' && !relative.startsWith(`..${path.sep}`) && relative !== '..';
+};
+export const validateVendoredExtensionPath = (candidate, vendorRoot) => {
+    let realFile;
+    let realRoot;
+    try {
+        realFile = realpathSync(candidate);
+        realRoot = realpathSync(vendorRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!/\.lbug_extension$/i.test(realFile))
+        return null;
+    if (!isPathInsideRoot(realRoot, realFile))
+        return null;
+    return realFile;
+};
+export const inferExtensionVersionFromPath = (filePath) => {
+    if (!filePath)
+        return undefined;
+    const home = /[/\\]extension[/\\](\d+\.\d+\.\d+)[/\\]/.exec(filePath);
+    return home?.[1];
+};
+export const resolveFtsVersionPair = (inspectPath, vendorRoot) => {
+    // Ladybug's home path is `~/.lbdb/extension/<coreVersion>/…`. Compare that
+    // directory to the packaged core pin, not the (often different) artifact
+    // version, or a matching runtime looks skewed.
+    const expected = readFtsArtifactManifest(vendorRoot).coreVersion;
+    const found = inferExtensionVersionFromPath(inspectPath);
+    return { expected, found };
+};
+export const resolveVendoredFtsPath = (opts) => {
+    const vendorRoot = opts?.vendorRoot ?? defaultVendorRoot();
+    const tuple = opts?.tuple ?? nodePlatformTuple();
+    const filename = opts?.filename ?? readFtsArtifactManifest(vendorRoot).filename ?? DEFAULT_FILENAME;
+    const candidate = path.resolve(vendorRoot, 'lbug-fts', 'prebuilds', tuple, filename);
+    if (!existsSync(candidate))
+        return null;
+    return validateVendoredExtensionPath(candidate, vendorRoot);
+};

package/dist/core/lbug/wal-checkpoint-driver.d.ts

@@ -65,9 +65,12 @@ export declare const runCheckpointWithRetry: (options?: {
  *
  * Honors the `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` opt-out so operators can
  * disable the manual path if it ever interacts badly with a future
- * Ladybug release.
+ * Ladybug release. Returns true only when a CHECKPOINT actually flushed
+ * (`tryFlushWAL` → true). Opt-out and a no-op flush (no open connection)
+ * both return false so an FTS park warrant cannot treat a skipped
+ * checkpoint as success.
  */
-export declare const checkpointOnce: () => Promise<void>;
+export declare const checkpointOnce: () => Promise<boolean>;
 /**
  * Start a periodic manual checkpoint driver. The returned handle has a
  * `stop()` method that resolves once the in-flight checkpoint (if any)

package/dist/core/lbug/wal-checkpoint-driver.js

@@ -108,12 +108,16 @@ export const runCheckpointWithRetry = async (options = {}) => {
  *
  * Honors the `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` opt-out so operators can
  * disable the manual path if it ever interacts badly with a future
- * Ladybug release.
+ * Ladybug release. Returns true only when a CHECKPOINT actually flushed
+ * (`tryFlushWAL` → true). Opt-out and a no-op flush (no open connection)
+ * both return false so an FTS park warrant cannot treat a skipped
+ * checkpoint as success.
  */
 export const checkpointOnce = async () => {
     if (!isManualCheckpointEnabled())
-        return;
-    await runCheckpointWithRetry();
+        return false;
+    const { flushed } = await runCheckpointWithRetry();
+    return flushed;
 };
 /** Default cadence (ms) for the periodic driver. */
 const DEFAULT_PERIOD_MS = 5_000;

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

@@ -228,8 +228,10 @@ export interface AnalyzeResult {
      * `extension-unavailable` (the LadybugDB FTS extension could not load — the
      * offline-first case, remedied by installing it) vs `build-failed` (the
      * 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.
+     * `--repair-fts`, not by installing the extension) vs `native-abort` (inferred
+     * on the next run from an FTS-phase crash) vs `tuple-missing` (no packaged
+     * artifact for this platform). 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.
      */