gitnexus 1.6.6-rc.2 → 1.6.6-rc.21

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

@@ -8,7 +8,7 @@ import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
-import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, openLbugConnection, waitForWindowsHandleRelease, } from './lbug-config.js';
+import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 /**
@@ -112,6 +112,7 @@ export const splitRelCsvByLabelPair = async (csvPath, csvDir, validTables, getNo
 let db = null;
 let conn = null;
 let currentDbPath = null;
+let currentDbReadOnly = false;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
 /**
@@ -367,12 +368,13 @@ export const initLbug = async (dbPath) => {
  * database is busy (e.g. `gitnexus analyze` holds the write lock).
  * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
-export const withLbugDb = async (dbPath, operation) => {
+export const withLbugDb = async (dbPath, operation, options = {}) => {
     let lastError;
+    const readOnly = options.readOnly === true;
     for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
         try {
             return await runWithSessionLock(async () => {
-                await ensureLbugInitialized(dbPath);
+                await ensureLbugInitialized(dbPath, readOnly);
                 return operation();
             });
         }
@@ -402,14 +404,14 @@ export const withLbugDb = async (dbPath, operation) => {
     // but TypeScript needs an explicit throw to satisfy the return type.
     throw lastError;
 };
-const ensureLbugInitialized = async (dbPath) => {
-    if (conn && currentDbPath === dbPath) {
+const ensureLbugInitialized = async (dbPath, readOnly = false) => {
+    if (conn && currentDbPath === dbPath && currentDbReadOnly === readOnly) {
         return { db, conn };
     }
-    await doInitLbug(dbPath);
+    await doInitLbug(dbPath, readOnly);
     return { db, conn };
 };
-const doInitLbug = async (dbPath) => {
+const doInitLbug = async (dbPath, readOnly = false) => {
     // Different database requested — close the old one first
     if (conn || db) {
         await safeClose();
@@ -486,9 +488,12 @@ const doInitLbug = async (dbPath) => {
         // Ensure parent directory exists
         const parentDir = path.dirname(dbPath);
         await fs.mkdir(parentDir, { recursive: true });
-        const opened = await openLbugConnection(lbug, dbPath);
+        const opened = readOnly
+            ? await openLbugConnection(lbug, dbPath, { readOnly: true })
+            : await openLbugConnection(lbug, dbPath);
         db = opened.db;
         conn = opened.conn;
+        currentDbReadOnly = readOnly;
     }
     finally {
         await releaseInitLock();
@@ -508,7 +513,23 @@ const doInitLbug = async (dbPath) => {
             //     anyway and any genuine cross-process lock contention surfaces
             //     on the next operation via withLbugDb's retry. Logging it here
             //     would just be noise in CI.
-            if (!msg.includes('already exists') && !isDbBusyError(err)) {
+            //
+            // WAL corruption: the first DDL write after DB open triggers WAL
+            // replay — if the WAL file was left in a corrupt state by an
+            // interrupted previous run, the native engine throws here. Rather
+            // than logging a WARN and continuing in a broken state, close the
+            // DB cleanly and surface an actionable error so the caller (serve,
+            // MCP, analyze) can exit with a clear recovery message.
+            if (isWalCorruptionError(err)) {
+                await safeClose();
+                currentDbPath = null;
+                ftsLoaded = false;
+                vectorExtensionLoaded = false;
+                ensuredFTSIndexes.clear();
+                throw new Error(`LadybugDB WAL corruption detected at ${dbPath}. ${WAL_RECOVERY_SUGGESTION}\n` +
+                    `  Original error: ${msg.slice(0, 200)}`);
+            }
+            if (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {
                 logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
             }
         }
@@ -915,11 +936,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
     return { inserted, failed };
 };
 export const executeQuery = async (cypher) => {
-    if (!conn) {
-        throw new Error('LadybugDB not initialized. Call initLbug first.');
-    }
-    const queryResult = await conn.query(cypher);
-    return await readQueryRows(queryResult);
+    return await executePrepared(cypher, {});
 };
 export const streamQuery = async (cypher, onRow) => {
     if (!conn) {
@@ -1501,17 +1518,14 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    // Escape backslashes and single quotes to prevent Cypher injection
-    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
-    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := ${conjunctive})
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', $query, conjunctive := ${conjunctive})
     RETURN node, score
     ORDER BY score DESC
     LIMIT ${limit}
   `;
     try {
-        const queryResult = await conn.query(cypher);
-        const rows = await readQueryRows(queryResult);
+        const rows = await executePrepared(cypher, { query });
         return rows.map((row) => {
             const node = row.node || row[0] || {};
             const score = row.score ?? row[1] ?? 0;

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

@@ -32,7 +32,7 @@ import type lbug from '@ladybugdb/core';
  * integer; anything invalid falls back to the default.
  */
 export declare const LBUG_MAX_DB_SIZE: number;
-export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze` to rebuild the index.";
+export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.";
 export declare function isWalCorruptionError(err: unknown): boolean;
 type LbugModule = typeof lbug;
 export interface LbugDatabaseOptions {

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

@@ -44,7 +44,7 @@ export const LBUG_MAX_DB_SIZE = (() => {
 })();
 /** Matches WAL corruption errors from the LadybugDB engine. */
 const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
-export const WAL_RECOVERY_SUGGESTION = 'WAL corruption detected. Run `gitnexus analyze` to rebuild the index.';
+export const WAL_RECOVERY_SUGGESTION = 'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.';
 export function isWalCorruptionError(err) {
     if (!err)
         return false;

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

@@ -15,6 +15,25 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import lbug from '@ladybugdb/core';
+/**
+ * Probe whether a Windows FTS extension binary is locally installed under
+ * ~/.lbdb/extension/<any-version>/win_amd64/fts/. Returns true on the first
+ * version dir whose libfts.lbug_extension exists on disk; false if the
+ * extension root is missing or contains no FTS binary.
+ *
+ * Gates the Windows skip-FTS-load guard below so we only skip the load
+ * when no extension binary is present. When at least one binary exists,
+ * loadFTSExtension is called with policy: 'load-only' — LadybugDB resolves
+ * LOAD EXTENSION fts to its version-specific path internally, and the
+ * ExtensionManager's tryLoad try/catch handles version-mismatch errors
+ * cleanly without ever attempting dlopen of a stale binary. The install
+ * path that the #1199/#1217 SIGSEGV documented is never exercised at
+ * query time.
+ *
+ * Exported so unit tests can exercise the probe directly against a
+ * temp-dir plus spied `os.homedir()` — see lbug-pool-win-fts-probe.test.ts.
+ */
+export declare function hasLocalWinFtsExtension(): Promise<boolean>;
 /**
  * Listeners notified when a pool entry is torn down (LRU eviction, idle
  * timeout, explicit close). Used by upper layers (e.g. the BM25 search
@@ -81,10 +100,3 @@ export declare const closeLbug: (repoId?: string) => Promise<void>;
  * Check if a specific repo's pool is active
  */
 export declare const isLbugReady: (repoId: string) => boolean;
-/** Regex to detect write operations in user-supplied Cypher queries.
- * Note: CALL is NOT blocked — it's used for read-only FTS (CALL QUERY_FTS_INDEX)
- * and vector search (CALL QUERY_VECTOR_INDEX). The database is opened in
- * read-only mode as defense-in-depth against write procedures. */
-export declare const CYPHER_WRITE_RE: RegExp;
-/** Check if a Cypher query contains write operations */
-export declare function isWriteQuery(query: string): boolean;

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

@@ -15,9 +15,48 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
 import lbug from '@ladybugdb/core';
-import { loadFTSExtension } from './lbug-adapter.js';
-import { createLbugDatabase, isWalCorruptionError } from './lbug-config.js';
+import { isReadOnlyDbError, loadFTSExtension } from './lbug-adapter.js';
+import { createLbugDatabase, isWalCorruptionError, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
+/**
+ * Probe whether a Windows FTS extension binary is locally installed under
+ * ~/.lbdb/extension/<any-version>/win_amd64/fts/. Returns true on the first
+ * version dir whose libfts.lbug_extension exists on disk; false if the
+ * extension root is missing or contains no FTS binary.
+ *
+ * Gates the Windows skip-FTS-load guard below so we only skip the load
+ * when no extension binary is present. When at least one binary exists,
+ * loadFTSExtension is called with policy: 'load-only' — LadybugDB resolves
+ * LOAD EXTENSION fts to its version-specific path internally, and the
+ * ExtensionManager's tryLoad try/catch handles version-mismatch errors
+ * cleanly without ever attempting dlopen of a stale binary. The install
+ * path that the #1199/#1217 SIGSEGV documented is never exercised at
+ * query time.
+ *
+ * Exported so unit tests can exercise the probe directly against a
+ * temp-dir plus spied `os.homedir()` — see lbug-pool-win-fts-probe.test.ts.
+ */
+export async function hasLocalWinFtsExtension() {
+    try {
+        const extRoot = path.join(os.homedir(), '.lbdb', 'extension');
+        const versions = await fs.readdir(extRoot);
+        for (const v of versions) {
+            try {
+                await fs.stat(path.join(extRoot, v, 'win_amd64', 'fts', 'libfts.lbug_extension'));
+                return true;
+            }
+            catch {
+                /* missing for this version, keep looking */
+            }
+        }
+    }
+    catch {
+        /* no .lbdb/extension dir */
+    }
+    return false;
+}
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -310,8 +349,7 @@ async function doInitLbug(repoId, dbPath) {
                         break;
                     }
                     catch (retryErr) {
-                        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ` +
-                            `Run \`gitnexus analyze\` to rebuild the index. ` +
+                        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ${WAL_RECOVERY_SUGGESTION} ` +
                             `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`);
                     }
                 }
@@ -348,14 +386,24 @@ async function doInitLbug(repoId, dbPath) {
     // install; analyze owns extension installation. If LOAD fails, search
     // features degrade gracefully and the user-facing query path proceeds.
     if (!shared.ftsLoaded) {
-        // Windows guard: LOAD EXTENSION fts crashes with SIGSEGV on Windows when
-        // the FTS extension binary is not installed locally (@ladybugdb/core native
-        // bug — the extension loader hits an unhandled error path that signals SIGSEGV
-        // rather than throwing a JS exception, so try/catch cannot protect here).
-        // Skip the load on Windows; bm25-index.js catches the resulting Kuzu catalog
-        // errors and returns empty BM25 results gracefully. Graph queries are unaffected.
+        // Windows guard: LOAD EXTENSION fts crashes with SIGSEGV on Windows during
+        // *install* — the @ladybugdb/core out-of-process installer hits an unhandled
+        // error path that signals SIGSEGV instead of throwing (see #1199, #1217).
+        // The previous unconditional skip was over-broad: it also disabled FTS on
+        // hosts where the binary was already on disk and only needed LOAD, leaving
+        // BM25 silently degraded with no error path (see #1690).
+        //
+        // Probe ~/.lbdb/extension/*/win_amd64/fts/ first. If any binary is on disk
+        // we run loadFTSExtension(..., 'load-only'); the install path is never
+        // exercised, and LadybugDB's version-specific resolution + ExtensionManager
+        // try/catch handle stale/zero-byte siblings cleanly (verified empirically
+        // on Win10 + Node 22.19 + gitnexus 1.6.5 + @ladybugdb/core 0.16.1). With
+        // no binary at all, we fall back to the upstream skip so install-time
+        // SIGSEGV continues to be avoided.
         if (process.platform === 'win32') {
-            shared.ftsLoaded = true;
+            shared.ftsLoaded = (await hasLocalWinFtsExtension())
+                ? await loadFTSExtension(available[0], { policy: 'load-only' })
+                : true;
         }
         else {
             shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
@@ -415,10 +463,12 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     // Load FTS extension if not already loaded on this Database.
     // policy: 'load-only' — same contract as initLbug above; the read pool
     // must not block on a network install during query execution.
-    // Windows guard: same SIGSEGV risk as doInitLbug above — skip on Windows.
+    // Windows guard: same probe-then-load policy as doInitLbug above.
     if (!shared.ftsLoaded) {
         if (process.platform === 'win32') {
-            shared.ftsLoaded = true;
+            shared.ftsLoaded = (await hasLocalWinFtsExtension())
+                ? await loadFTSExtension(available[0], { policy: 'load-only' })
+                : true;
         }
         else {
             shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
@@ -506,28 +556,7 @@ function withTimeout(promise, ms, label) {
     return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 export const executeQuery = async (repoId, cypher) => {
-    const entry = pool.get(repoId);
-    if (!entry) {
-        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
-    }
-    if (isWriteQuery(cypher)) {
-        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
-    }
-    entry.lastUsed = Date.now();
-    const conn = await checkout(entry);
-    silenceStdout();
-    activeQueryCount++;
-    try {
-        const queryResult = await withTimeout(conn.query(cypher), QUERY_TIMEOUT_MS, 'Query');
-        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-        const rows = await result.getAll();
-        return rows;
-    }
-    finally {
-        activeQueryCount--;
-        restoreStdout();
-        checkin(entry, conn);
-    }
+    return await executeParameterized(repoId, cypher, {});
 };
 /**
  * Execute a parameterized query on a specific repo's connection pool.
@@ -553,6 +582,12 @@ export const executeParameterized = async (repoId, cypher, params) => {
         const rows = await result.getAll();
         return rows;
     }
+    catch (err) {
+        if (isReadOnlyDbError(err)) {
+            throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+        }
+        throw err;
+    }
     finally {
         activeQueryCount--;
         restoreStdout();
@@ -581,12 +616,3 @@ export const closeLbug = async (repoId) => {
  * Check if a specific repo's pool is active
  */
 export const isLbugReady = (repoId) => pool.has(repoId);
-/** Regex to detect write operations in user-supplied Cypher queries.
- * Note: CALL is NOT blocked — it's used for read-only FTS (CALL QUERY_FTS_INDEX)
- * and vector search (CALL QUERY_VECTOR_INDEX). The database is opened in
- * read-only mode as defense-in-depth against write procedures. */
-export const CYPHER_WRITE_RE = /(?<!:)\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH|FOREACH|INSTALL|LOAD)\b/i;
-/** Check if a Cypher query contains write operations */
-export function isWriteQuery(query) {
-    return CYPHER_WRITE_RE.test(query);
-}

package/dist/core/lbug/query-params.d.ts

@@ -0,0 +1 @@
+export declare const isValidQueryParams: (value: unknown) => value is Record<string, unknown>;

package/dist/core/lbug/query-params.js

@@ -0,0 +1,21 @@
+/**
+ * Return true only for plain-object payloads that can be safely used as
+ * named parameter maps in prepared Cypher execution.
+ *
+ * Validation criteria:
+ * - must be a JavaScript object (`typeof value === 'object'`)
+ * - must not be `null`
+ * - must not be an array
+ * - must have a plain-object prototype
+ * - values must be scalar bindable values (string | number | boolean | null)
+ *
+ * Rationale: prepared-statement params are key/value maps; rejecting null/array
+ * and non-plain objects keeps binding behavior predictable and avoids passing
+ * complex host objects to Ladybug parameter binding.
+ */
+const isBindableScalar = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+export const isValidQueryParams = (value) => value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+    Object.values(value).every(isBindableScalar);

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

@@ -12,16 +12,14 @@ import { FTS_INDEXES } from './fts-schema.js';
  * caller can distinguish "zero matches" from "index missing".
  */
 async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
-    // Escape single quotes and backslashes to prevent Cypher injection
-    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
-    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := false)
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', $query, conjunctive := false)
     RETURN node, score
     ORDER BY score DESC
     LIMIT ${limit}
   `;
     try {
-        const rows = await executor(cypher);
+        const rows = await executor(cypher, { query });
         return rows.map((row) => {
             const node = row.node || row[0] || {};
             const score = row.score ?? row[1] ?? 0;
@@ -55,8 +53,8 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
         const poolMod = await import('../lbug/pool-adapter.js');
-        const { executeQuery } = poolMod;
-        const executor = (cypher) => executeQuery(repoId, cypher);
+        const { executeParameterized } = poolMod;
+        const executor = (cypher, params) => executeParameterized(repoId, cypher, params);
         for (const { table, indexName } of FTS_INDEXES) {
             const result = await queryFTSViaExecutor(executor, table, indexName, query, limit);
             if (result !== null) {

package/dist/core/wiki/generator.d.ts

@@ -16,11 +16,14 @@ export interface WikiOptions {
     concurrency?: number;
     /** If true, stop after building module tree for user review */
     reviewOnly?: boolean;
+    /** Output language for generated documentation (e.g. 'english', 'chinese', 'spanish') */
+    lang?: string;
 }
 export interface WikiMeta {
     fromCommit: string;
     generatedAt: string;
     model: string;
+    lang: string;
     moduleFiles: Record<string, string[]>;
     moduleTree: ModuleTreeNode[];
 }
@@ -62,6 +65,16 @@ export declare class WikiGenerator {
      * Also touches the DB connection periodically to prevent idle timeout.
      */
     private streamOpts;
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    private effectiveLang;
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    private buildSystemPrompt;
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */

package/dist/core/wiki/generator.js

@@ -89,6 +89,27 @@ export class WikiGenerator {
             },
         };
     }
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    effectiveLang() {
+        const lang = (this.options.lang ?? '')
+            .replace(/[\x00-\x1F\x7F]/g, '')
+            .trim()
+            .slice(0, 50);
+        return /^[a-zA-Z -]+$/.test(lang) ? lang : '';
+    }
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    buildSystemPrompt(base) {
+        const lang = this.effectiveLang();
+        if (!lang)
+            return base;
+        return `${base}\n\nIMPORTANT: Write ALL documentation content in ${lang}. This includes prose, code comments in examples, and diagram labels. Note: page titles (H1 headings) are generated separately and will remain in English.`;
+    }
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */
@@ -112,6 +133,13 @@ export class WikiGenerator {
         const forceMode = this.options.force;
         // Up-to-date check (skip if --force)
         if (!forceMode && existingMeta && existingMeta.fromCommit === currentCommit) {
+            const currentLang = this.effectiveLang();
+            const metaLang = existingMeta.lang ?? '';
+            if (currentLang !== metaLang) {
+                const prevDisplay = metaLang || 'english (default)';
+                const nextDisplay = currentLang || 'english (default)';
+                throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+            }
             // Still regenerate the HTML viewer in case it's missing
             await this.ensureHTMLViewer();
             return { pagesGenerated: 0, mode: 'up-to-date', failedModules: [] };
@@ -139,6 +167,13 @@ export class WikiGenerator {
         let result;
         try {
             if (!forceMode && existingMeta && existingMeta.fromCommit) {
+                const currentLang = this.effectiveLang();
+                const metaLang = existingMeta.lang ?? '';
+                if (currentLang !== metaLang) {
+                    const prevDisplay = metaLang || 'english (default)';
+                    const nextDisplay = currentLang || 'english (default)';
+                    throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+                }
                 result = await this.incrementalUpdate(existingMeta, currentCommit);
             }
             else {
@@ -257,6 +292,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
             moduleFiles,
             moduleTree,
         });
@@ -298,6 +334,9 @@ export class WikiGenerator {
             FILE_LIST: fileList,
             DIRECTORY_TREE: dirTree,
         });
+        // Grouping is a structured-data phase (JSON output), not documentation.
+        // Do NOT apply buildSystemPrompt here — a language instruction would risk
+        // translating module-name keys, breaking slug stability and JSON parsing.
         const response = await this.invokeLLM(prompt, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15, 13));
         const grouping = this.parseGroupingResponse(response.content, files);
         // Convert to tree nodes
@@ -444,8 +483,8 @@ export class WikiGenerator {
             INCOMING_CALLS: formatCallEdges(interCalls.incoming),
             PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
-        // Write page with front matter
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(MODULE_SYSTEM_PROMPT), this.streamOpts(node.name));
+        // H1 uses the English module name (stable slug source); body is LLM-translated.
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -480,7 +519,7 @@ export class WikiGenerator {
             CROSS_MODULE_CALLS: formatCallEdges(crossCalls),
             CROSS_PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(PARENT_SYSTEM_PROMPT), this.streamOpts(node.name));
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -516,7 +555,7 @@ export class WikiGenerator {
             MODULE_EDGES: edgesText,
             TOP_PROCESSES: formatProcesses(topProcesses),
         });
-        const response = await this.invokeLLM(prompt, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(OVERVIEW_SYSTEM_PROMPT), this.streamOpts('Generating overview', 88));
         const pageContent = sanitizeMermaidMarkdown(`# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8');
     }
@@ -538,6 +577,7 @@ export class WikiGenerator {
                 ...existingMeta,
                 fromCommit: currentCommit,
                 generatedAt: new Date().toISOString(),
+                lang: this.effectiveLang(),
             });
             return { pagesGenerated: 0, mode: 'incremental', failedModules: [] };
         }
@@ -627,6 +667,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
         });
         this.onProgress('done', 100, 'Incremental update complete');
         return { pagesGenerated, mode: 'incremental', failedModules: [...this.failedModules] };

package/dist/core/wiki/llm-client.d.ts

@@ -19,7 +19,7 @@ export interface LLMConfig {
     apiVersion?: string;
     /** When true, strips sampling params and uses max_completion_tokens instead of max_tokens */
     isReasoningModel?: boolean;
-    /** Per-attempt fetch timeout in ms (default: 60_000). */
+    /** Per-attempt fetch timeout in ms. Omit to disable request timeouts. */
     requestTimeoutMs?: number;
     /** Max fetch attempts before giving up (default: 3). */
     maxAttempts?: number;

package/dist/core/wiki/llm-client.js

@@ -38,6 +38,19 @@ export async function resolveLLMConfig(overrides) {
 export function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
+function formatTimeoutDuration(timeoutMs) {
+    if (timeoutMs >= 1000 && timeoutMs % 1000 === 0) {
+        return `${timeoutMs / 1000}s`;
+    }
+    return `${timeoutMs}ms`;
+}
+function isTimeoutLikeError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === 'TimeoutError' || err.name === 'AbortError')
+        return true;
+    return /time(d)?\s*out|timeout/i.test(err.message);
+}
 /**
  * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
  * endpoint (CWE-918 / CodeQL js/http-to-file-access).
@@ -166,12 +179,12 @@ export async function callLLM(prompt, config, systemPrompt, options) {
                 ...authHeaders,
             },
             body: JSON.stringify(body),
-            // Per-attempt timeout. Without this each retry can hang
-            // indefinitely on a frozen TCP connection — the per-call
-            // signal is the only timeout `resilientFetch` honors;
-            // `capDelayMs` only bounds the *backoff* between attempts.
-            // Default 60s; raise via --timeout for slow models or large pages.
-            signal: AbortSignal.timeout(config.requestTimeoutMs ?? 60_000),
+            // Request timeout is opt-in for wiki generation. Large local
+            // model runs can legitimately take well over a minute, so the
+            // default runtime path must not impose a hidden 60s ceiling.
+            signal: config.requestTimeoutMs !== undefined
+                ? AbortSignal.timeout(config.requestTimeoutMs)
+                : undefined,
         }, {
             breakerKey: `wiki-llm-${new URL(url).host}`,
             retry: { maxAttempts: config.maxAttempts ?? 3, baseDelayMs: 2_000, capDelayMs: 30_000 },
@@ -185,6 +198,10 @@ export async function callLLM(prompt, config, systemPrompt, options) {
             const errorText = await err.response.text().catch(() => 'unknown error');
             throw new Error(`LLM API error (${err.response.status} after retries): ${errorText.slice(0, 500)}`);
         }
+        if (config.requestTimeoutMs !== undefined && isTimeoutLikeError(err)) {
+            throw new Error(`LLM request timed out after ${formatTimeoutDuration(config.requestTimeoutMs)}. ` +
+                'Increase --timeout or omit it to disable the request timeout.');
+        }
         throw err;
     }
     if (!response.ok) {

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

@@ -5,8 +5,6 @@
  * Supports multiple indexed repositories via a global registry.
  * LadybugDB connections are opened lazily per repo on first query.
  */
-import { isWriteQuery } from '../../core/lbug/pool-adapter.js';
-export { isWriteQuery };
 import { type RegistryEntry } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 /**
@@ -59,6 +57,22 @@ interface RepoHandle {
     remoteUrl?: string;
     stats?: RegistryEntry['stats'];
 }
+/**
+ * Resolve the git diff cwd for detect_changes, auto-detecting linked worktrees.
+ *
+ * When `launchCwd` is a linked worktree of the same canonical repository as
+ * `repoPath` (i.e. `getGitRoot(launchCwd)` differs from `repoPath` but both
+ * share the same `getCanonicalRepoRoot`), returns the worktree's git root so
+ * that `git diff` sees the correct working directory and index.
+ *
+ * Returns `repoPath` unchanged in all other cases (non-worktree, git
+ * unavailable, unrelated repo).
+ *
+ * Extracted as a module-level export so tests can pass any `launchCwd` instead
+ * of relying on `process.cwd()`, which is fixed to the server launch directory
+ * and cannot be changed mid-process.
+ */
+export declare function resolveWorktreeCwd(repoPath: string, launchCwd: string): string;
 export declare class LocalBackend {
     private repos;
     private contextCache;
@@ -192,7 +206,7 @@ export declare class LocalBackend {
      * Semantic vector search helper
      */
     private semanticSearch;
-    executeCypher(repoName: string, query: string): Promise<any>;
+    executeCypher(repoName: string, query: string, params?: Record<string, unknown>): Promise<any>;
     private cypher;
     /**
      * Format raw Cypher result rows as a markdown table for LLM readability.
@@ -354,3 +368,4 @@ export declare class LocalBackend {
     queryProcessDetail(name: string, repoName?: string): Promise<any>;
     disconnect(): Promise<void>;
 }
+export {};