gitnexus 1.6.10-rc.13 → 1.6.10-rc.15

package/dist/cli/analyze.js

@@ -12,13 +12,14 @@ import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
-import { isLbugReady } from '../core/lbug/lbug-adapter.js';
+import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
-import { isLbugCheckpointIoError, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
+import { getOsPageSize, isLbugCheckpointIoError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './optional-grammars.js';
 import { glob } from 'glob';
@@ -1237,6 +1238,63 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // DB-family wipe failure (#2409, tri-review 4669518496 P2-4): the rebuild
+        // could not verify the LadybugDB file family was removed — usually another
+        // process (MCP server, serve worker, antivirus) holding the index open.
+        // Keyed on the error *type* (repo norm from #2385), never message text.
+        // The message itself is fully self-contained (survivor paths + stop-MCP /
+        // AV-exclusion / re-run guidance) because the serve worker forwards only
+        // `err.message` over IPC — this branch just renders it without the
+        // raw-stack fallback below.
+        if (err instanceof LbugWipeError) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'lbug-wipe-failed',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Buffer-manager frame-release failure on non-4K-page kernels (#1231).
+        // LadybugDB <= 0.17.x assumed 4 KiB OS pages when releasing evicted
+        // frames; Raspberry Pi 5 (16 KiB kernel pages) and other arm64 systems
+        // crash mid-COPY with a raw native message. 0.18.0 detects the page size
+        // at runtime, so the actionable fix depends on which side of that
+        // boundary the installed @ladybugdb/core is.
+        if (isLbugPageSizeFrameError(err)) {
+            const pageSize = getOsPageSize();
+            const ladybug = getRuntimeFingerprint().ladybugdb;
+            const pageLine = pageSize !== undefined && pageSize !== 4096
+                ? `  Detected OS page size: ${pageSize} bytes (non-4K — e.g. Raspberry Pi 5 16K kernel, Asahi Linux).\n`
+                : '';
+            // The upgrade variant must not assert version facts about an unknown
+            // version — mirror the doctor-side wording rule (#2424 review R2).
+            const upgradeIntro = ladybug === undefined
+                ? `  The installed @ladybugdb/core version is unknown — it may predate the\n` +
+                    `  runtime OS-page-size detection added in 0.18.0.\n`
+                : `  The installed @ladybugdb/core (${ladybug}) assumes 4 KiB pages in its buffer\n` +
+                    `  manager.\n`;
+            const guidance = isPageSizeAwareLadybug(ladybug)
+                ? `  The installed @ladybugdb/core (${ladybug}) already detects the OS page size at runtime,\n` +
+                    `  so this configuration was expected to work. Please report it:\n` +
+                    `    https://github.com/abhigyanpatwari/GitNexus/issues/1231\n` +
+                    `  and include: gitnexus --version, node --version, getconf PAGE_SIZE, uname -a,\n` +
+                    `  and the full error message above.\n`
+                : upgradeIntro +
+                    `  Upgrade GitNexus to a release that bundles @ladybugdb/core >= 0.18.0\n` +
+                    `  (gitnexus >= 1.6.9), which detects the OS page size at runtime:\n` +
+                    `    npm install -g gitnexus@latest\n` +
+                    `  Last-resort workaround on Raspberry Pi 5: boot the 4 KiB-page kernel\n` +
+                    `  (config.txt: kernel=kernel8.img), at the cost of Pi 5 optimizations.\n`;
+            // Embed the raw native text (indented, no stack) so "the full error
+            // message above" is fulfillable — same idiom as the LbugWipeError
+            // branch. The errno suffix and the 0.18.0 guard's frame/granule numbers
+            // are the discriminating triage content (#2424 review P2).
+            cliError(`  LadybugDB's buffer manager failed to release frame memory.\n` +
+                `    ${msg.replace(/\n/g, '\n    ')}\n` +
+                pageLine +
+                guidance, { recoveryHint: 'lbug-page-size', pageSize, ladybugVersion: ladybug });
+            process.exitCode = 1;
+            return;
+        }
         // Local embedding runtime unsupported on this platform (macOS Intel ships no
         // darwin/x64 ONNX native binding, #1515). The guard threw before importing
         // transformers.js, so this is a clean, actionable GitNexus message. Checked

package/dist/cli/clean.js

@@ -8,7 +8,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { logger } from '../core/logger.js';
 import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, getStoragePaths, removeBranchIndex, UnsafeStoragePathError, } from '../storage/repo-manager.js';
-import { cleanQuarantinedMissingShadowWals, inspectLbugSidecars, listQuarantinedMissingShadowWals, } from '../core/lbug/sidecar-recovery.js';
+import { cleanParkedLbugSidecars, inspectLbugSidecars, listParkedLbugSidecars, } from '../core/lbug/sidecar-recovery.js';
 import { t } from './i18n/index.js';
 export const cleanCommand = async (options) => {
     // --branch <name>: remove a single non-primary branch's index (#2106 R7).
@@ -62,7 +62,13 @@ export const cleanCommand = async (options) => {
         }
         const lbugPath = path.join(repo.storagePath, 'lbug');
         const state = await inspectLbugSidecars(lbugPath);
-        const quarantined = await listQuarantinedMissingShadowWals(lbugPath);
+        // Single roster authority (this shipping review, FIX 5): the aggregate
+        // covers both parked-sidecar families — the timestamped missing-shadow
+        // WAL quarantines AND the fixed-name `.dirty-recovery` parks (`.next`
+        // residues included) left by a dirty-flag recovery rebuild (#2409). The
+        // previous inline concatenations here were how the `.next` residue
+        // stayed invisible to this surface.
+        const quarantined = await listParkedLbugSidecars(lbugPath);
         console.log(t('clean.lbugSidecars.state', { state: state.kind }));
         if (quarantined.length === 0) {
             console.log(t('clean.lbugSidecars.none'));
@@ -76,8 +82,16 @@ export const cleanCommand = async (options) => {
             console.log(`\n${t('common.runForceConfirm')}`);
             return;
         }
-        const deleted = await cleanQuarantinedMissingShadowWals(lbugPath);
+        const { deleted, failed } = await cleanParkedLbugSidecars(lbugPath);
         console.log(t('clean.lbugSidecars.deleted', { count: deleted.length }));
+        // A locked parked file no longer crashes the clean mid-command (FIX 5)
+        // — the rest were deleted above; report what remains and why.
+        if (failed.length > 0) {
+            console.log(t('clean.lbugSidecars.failed', { count: failed.length }));
+            for (const file of failed) {
+                console.log(`  - ${file}`);
+            }
+        }
         return;
     }
     // --all flag: clean all indexed repos

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -23,4 +23,17 @@ export declare function localEmbeddingDoctorStatus(opts: {
     status: string;
     detail: string | null;
 };
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybugVersion: string | undefined): string[];
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -5,6 +5,7 @@ import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage,
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
 import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
+import { getOsPageSize, isPageSizeAwareLadybug } from '../core/lbug/lbug-config.js';
 import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
@@ -87,6 +88,33 @@ export function localEmbeddingDoctorStatus(opts) {
     }
     return { status: '✓ local embeddings supported', detail: null };
 }
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export function pageSizeDoctorLines(pageSize, ladybugVersion) {
+    if (pageSize === undefined)
+        return [];
+    const lines = [`  ${padDisplayEnd('page size', 10)}${pageSize}`];
+    if (pageSize > 4096 && !isPageSizeAwareLadybug(ladybugVersion)) {
+        // Don't assert "< 0.18.0" as fact when the version is unresolvable
+        // (#2424 review R2) — name the unknown state instead.
+        const versionClause = ladybugVersion === undefined
+            ? 'an unknown @ladybugdb/core version (may predate 0.18.0)'
+            : `@ladybugdb/core < 0.18.0`;
+        lines.push(`  ${padDisplayEnd('', 10)}⚠ non-4K page size with ${versionClause} — ` +
+            `'gitnexus analyze' may fail during COPY (#1231). Upgrade gitnexus (npm install -g gitnexus@latest).`);
+    }
+    return lines;
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -97,6 +125,13 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.node', 10)}${fingerprint.node}`);
     console.log(`  ${label('doctor.labels.gitnexus', 10)}${fingerprint.gitnexus}`);
     console.log(`  ${label('doctor.labels.ladybugdb', 10)}${fingerprint.ladybugdb ?? 'unknown'}`);
+    // OS page size next to the LadybugDB version because the two interact:
+    // @ladybugdb/core < 0.18.0 assumed 4 KiB pages in its buffer manager and
+    // crashes mid-COPY on 16 KiB/64 KiB-page kernels (#1231). Literal label
+    // (like the 'native' line below) to avoid adding i18n keys.
+    for (const line of pageSizeDoctorLines(getOsPageSize(), fingerprint.ladybugdb)) {
+        console.log(line);
+    }
     const nativeCheck = checkLbugNative();
     if (nativeCheck.ok) {
         console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);

package/dist/cli/i18n/en.d.ts

@@ -40,9 +40,10 @@ export declare const en: {
     readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
     readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
     readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
-    readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
-    readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
-    readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).";
+    readonly 'clean.lbugSidecars.none': "No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).";
+    readonly 'clean.lbugSidecars.preview': "This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):";
+    readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} parked LadybugDB recovery sidecar(s).";
+    readonly 'clean.lbugSidecars.failed': "Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:";
     readonly 'remove.nothingToRemove': "Nothing to remove: {{message}}";
     readonly 'remove.deleteTarget': "This will delete the GitNexus index for: {{name}}";
     readonly 'remove.removed': "Removed: {{name}}";
@@ -175,7 +176,7 @@ export declare const en: {
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
     readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
-    readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
+    readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
     readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
     readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";

package/dist/cli/i18n/en.js

@@ -40,9 +40,10 @@ export const en = {
     'clean.deleteBranch': 'This will delete the branch index "{{branch}}" at: {{path}}',
     'clean.deletedBranch': 'Deleted branch index: {{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar state: {{state}}',
-    'clean.lbugSidecars.none': 'No quarantined LadybugDB missing-shadow WAL sidecars found.',
-    'clean.lbugSidecars.preview': 'This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):',
-    'clean.lbugSidecars.deleted': 'Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).',
+    'clean.lbugSidecars.none': 'No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).',
+    'clean.lbugSidecars.preview': 'This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):',
+    'clean.lbugSidecars.deleted': 'Deleted {{count}} parked LadybugDB recovery sidecar(s).',
+    'clean.lbugSidecars.failed': 'Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:',
     'remove.nothingToRemove': 'Nothing to remove: {{message}}',
     'remove.deleteTarget': 'This will delete the GitNexus index for: {{name}}',
     'remove.removed': 'Removed: {{name}}',
@@ -175,7 +176,7 @@ export const en = {
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
-    'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
+    'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',
     'help.option.wiki.model': 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)',

package/dist/cli/i18n/resources.d.ts

@@ -41,9 +41,10 @@ export declare const cliResources: {
         readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
         readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
         readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
-        readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
-        readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
-        readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).";
+        readonly 'clean.lbugSidecars.none': "No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).";
+        readonly 'clean.lbugSidecars.preview': "This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):";
+        readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} parked LadybugDB recovery sidecar(s).";
+        readonly 'clean.lbugSidecars.failed': "Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:";
         readonly 'remove.nothingToRemove': "Nothing to remove: {{message}}";
         readonly 'remove.deleteTarget': "This will delete the GitNexus index for: {{name}}";
         readonly 'remove.removed': "Removed: {{name}}";
@@ -176,7 +177,7 @@ export declare const cliResources: {
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
         readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
-        readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
+        readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
         readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
         readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
@@ -290,6 +291,7 @@ export declare const cliResources: {
         'clean.lbugSidecars.none': string;
         'clean.lbugSidecars.preview': string;
         'clean.lbugSidecars.deleted': string;
+        'clean.lbugSidecars.failed': string;
         'remove.nothingToRemove': string;
         'remove.deleteTarget': string;
         'remove.removed': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -43,6 +43,7 @@ export declare const zhCN: {
     'clean.lbugSidecars.none': string;
     'clean.lbugSidecars.preview': string;
     'clean.lbugSidecars.deleted': string;
+    'clean.lbugSidecars.failed': string;
     'remove.nothingToRemove': string;
     'remove.deleteTarget': string;
     'remove.removed': string;

package/dist/cli/i18n/zh-CN.js

@@ -40,9 +40,10 @@ export const zhCN = {
     'clean.deleteBranch': '将删除分支索引 “{{branch}}”，路径：{{path}}',
     'clean.deletedBranch': '已删除分支索引：{{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar 状态：{{state}}',
-    'clean.lbugSidecars.none': '未找到已隔离的 LadybugDB missing-shadow WAL sidecar。',
-    'clean.lbugSidecars.preview': '将删除 {{count}} 个已隔离的 LadybugDB missing-shadow WAL sidecar：',
-    'clean.lbugSidecars.deleted': '已删除 {{count}} 个已隔离的 LadybugDB missing-shadow WAL sidecar。',
+    'clean.lbugSidecars.none': '未找到已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件或 dirty-recovery 暂存文件）。',
+    'clean.lbugSidecars.preview': '将删除 {{count}} 个已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）：',
+    'clean.lbugSidecars.deleted': '已删除 {{count}} 个已暂存的 LadybugDB 恢复 sidecar。',
+    'clean.lbugSidecars.failed': '有 {{count}} 个文件被锁定而无法删除 — 请停止占用它们的进程（GitNexus MCP/serve 或杀毒软件扫描）后重试：',
     'remove.nothingToRemove': '无需移除：{{message}}',
     'remove.deleteTarget': '将删除该仓库的 GitNexus 索引：{{name}}',
     'remove.removed': '已移除：{{name}}',
@@ -175,7 +176,7 @@ export const zhCN = {
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
-    'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
+    'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
     'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：openai）',
     'help.option.wiki.model': 'LLM 模型或 Azure deployment 名称（默认：minimax/minimax-m2.5）',

package/dist/cli/index.js

@@ -170,7 +170,7 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .option('--branch <name>', 'Delete only the named branch index (not the workspace index)')
-    .option('--lbug-sidecars', 'Clean quarantined LadybugDB missing-shadow WAL sidecars')
+    .option('--lbug-sidecars', 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program
     .command('remove <target>')

package/dist/core/augmentation/engine.js

@@ -15,6 +15,7 @@
  */
 import path from 'path';
 import { listRegisteredRepos } from '../../storage/repo-manager.js';
+import { escapeCypherString } from '../lbug/cypher-escape.js';
 /**
  * Find the best matching repo for a given working directory.
  * Matches by checking if cwd is within the repo's path.
@@ -76,7 +77,7 @@ async function findRepoForCwd(cwd) {
 export async function augment(pattern, cwd) {
     if (!pattern || pattern.length < 3)
         return '';
-    const patternFirstWord = pattern.trim().replace(/'/g, "''").split(/\s+/)[0];
+    const patternFirstWord = escapeCypherString(pattern.trim()).split(/\s+/)[0];
     if (!patternFirstWord || patternFirstWord.length < 2)
         return '';
     const workDir = cwd || process.cwd();
@@ -97,7 +98,7 @@ export async function augment(pattern, cwd) {
         // Step 2: Map BM25 file results to symbols
         const symbolMatches = [];
         for (const result of bm25Results.slice(0, 5)) {
-            const escaped = result.filePath.replace(/'/g, "''");
+            const escaped = escapeCypherString(result.filePath);
             try {
                 const symbols = await executeQuery(repoId, `
           MATCH (n) WHERE n.filePath = '${escaped}'
@@ -147,7 +148,7 @@ export async function augment(pattern, cwd) {
             .filter((sym, i, arr) => arr.findIndex((s) => s.nodeId === sym.nodeId) === i);
         if (uniqueSymbols.length === 0)
             return '';
-        const idList = uniqueSymbols.map((s) => `'${s.nodeId.replace(/'/g, "''")}'`).join(', ');
+        const idList = uniqueSymbols.map((s) => `'${escapeCypherString(s.nodeId)}'`).join(', ');
         // Batch fetch callers
         const callersMap = new Map();
         try {

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -51,6 +51,26 @@ export declare const batchInsertEmbeddings: (executeWithReusedStatement: (cypher
     embedding: number[];
     contentHash?: string;
 }>) => Promise<void>;
+/**
+ * Create the vector index for semantic search (indexes the CodeEmbedding table).
+ *
+ * Keeps the embedding-specific extension-install policy gate here
+ * (ensureVectorExtensionAvailable → resolveEmbeddingInstallPolicy, default
+ * `auto` for the analyze write path), then delegates the actual
+ * `CALL CREATE_VECTOR_INDEX(...)` to the adapter, which runs it through the
+ * unprepared `conn.query()` path. It must NOT go through the injected
+ * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
+ * procedure and fails with "We do not support prepare multiple statements" —
+ * the silent degrade in #2114.
+ *
+ * Exported for run-analyze's wipe-and-restore seam (tri-review 4669518496
+ * P1): a full-rebuild/escalated write wipes the DB files — index included —
+ * and a preserve-only run restores embedding ROWS without ever reaching the
+ * pipeline call sites below, so the orchestrator recreates the index through
+ * this same policy-gated, warn-on-failure entry point. Consumed there via
+ * dynamic import only (lazy-embeddings convention, #2370).
+ */
+export declare const buildVectorIndex: () => Promise<boolean>;
 export interface EmbeddingPipelineResult {
     nodesProcessed: number;
     chunksProcessed: number;

package/dist/core/embeddings/embedding-pipeline.js

@@ -18,6 +18,7 @@ import { DEFAULT_VECTOR_MAX_DISTANCE, getVectorMaxDistance, resolveEmbeddingConf
 import { rankExactEmbeddingRows } from './exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, STALE_HASH_SENTINEL } from '../lbug/schema.js';
 import { loadVectorExtension, createVectorIndex } from '../lbug/lbug-adapter.js';
+import { escapeCypherString } from '../lbug/cypher-escape.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 const isDev = process.env.NODE_ENV === 'development';
@@ -163,8 +164,15 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
  * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
  * procedure and fails with "We do not support prepare multiple statements" —
  * the silent degrade in #2114.
+ *
+ * Exported for run-analyze's wipe-and-restore seam (tri-review 4669518496
+ * P1): a full-rebuild/escalated write wipes the DB files — index included —
+ * and a preserve-only run restores embedding ROWS without ever reaching the
+ * pipeline call sites below, so the orchestrator recreates the index through
+ * this same policy-gated, warn-on-failure entry point. Consumed there via
+ * dynamic import only (lazy-embeddings convention, #2370).
  */
-const buildVectorIndex = async () => {
+export const buildVectorIndex = async () => {
     // This pre-check applies the embedding-specific install policy
     // (resolveEmbeddingInstallPolicy, default `auto` for analyze) before reaching
     // the adapter. The adapter's createVectorIndex() calls loadVectorExtension()
@@ -536,7 +544,7 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     // Batch-fetch metadata per label
     const results = [];
     for (const [label, items] of byLabel) {
-        const idList = items.map((i) => `'${i.nodeId.replace(/'/g, "''")}'`).join(', ');
+        const idList = items.map((i) => `'${escapeCypherString(i.nodeId)}'`).join(', ');
         try {
             const nodeQuery = `
         MATCH (n:\`${label}\`) WHERE n.id IN [${idList}]

package/dist/core/incremental/escalation-gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Escalation gate for the incremental DB writeback (#2409).
+ *
+ * When the effective write set covers most of the repo, per-file surgery is
+ * strictly worse than the proven wipe-and-bulk-COPY plan — the same data
+ * volume lands either way, but the surgical plan pays per-table deletes plus
+ * COPY-into-non-empty tables, and at that size it measured SLOWER than a full
+ * DB load. The orchestrator (`run-analyze.ts`) consults this predicate to
+ * decide which write plan to run; only the DB write plan changes on
+ * escalation — fileHashes/meta bookkeeping is identical.
+ *
+ * Extracted to a pure module (tri-review 4669518496) so the AND-gate's
+ * boundary corners are pinned by unit tests without multi-minute
+ * orchestration permutations — an `&&`→`||` mutation here can no longer
+ * survive CI.
+ */
+export declare const INCREMENTAL_MAX_WRITE_FRACTION = 0.5;
+export declare const INCREMENTAL_ESCALATION_MIN_FILES = 50;
+/**
+ * Should the incremental writeback escalate from per-file surgery to a full
+ * wipe-and-bulk-COPY write plan?
+ *
+ * @param deleteCount        Files whose rows will be DETACH-DELETEd
+ *                           (effective write set ∪ deleted files, deduped).
+ * @param effectiveWriteCount Size of the effective write set (toWrite ∪
+ *                           importer-BFS expansion ∪ boundary-crossing files).
+ * @param totalFiles         Current repo file count (denominator).
+ *
+ * POPULATION MISMATCH (tri-review 4669518496, documented not "fixed"): the
+ * numerator counts effective-write-set members, which include importer-BFS
+ * results read from the PRE-pipeline DB — those can be now-DELETED paths that
+ * the CURRENT file list (the denominator) no longer contains. The fraction is
+ * therefore not a true subset ratio and can exceed 1 on delete-heavy runs.
+ * That errs toward escalation, which is the safe direction (the full write
+ * plan is always correct); the valve's log line clamps the DISPLAYED
+ * percentage to 100 so operators aren't shown ">100% of the repo".
+ */
+export declare const shouldEscalateIncrementalWrite: (deleteCount: number, effectiveWriteCount: number, totalFiles: number) => boolean;

package/dist/core/incremental/escalation-gate.js

@@ -0,0 +1,48 @@
+/**
+ * Escalation gate for the incremental DB writeback (#2409).
+ *
+ * When the effective write set covers most of the repo, per-file surgery is
+ * strictly worse than the proven wipe-and-bulk-COPY plan — the same data
+ * volume lands either way, but the surgical plan pays per-table deletes plus
+ * COPY-into-non-empty tables, and at that size it measured SLOWER than a full
+ * DB load. The orchestrator (`run-analyze.ts`) consults this predicate to
+ * decide which write plan to run; only the DB write plan changes on
+ * escalation — fileHashes/meta bookkeeping is identical.
+ *
+ * Extracted to a pure module (tri-review 4669518496) so the AND-gate's
+ * boundary corners are pinned by unit tests without multi-minute
+ * orchestration permutations — an `&&`→`||` mutation here can no longer
+ * survive CI.
+ */
+// Escalation cap (#2409): above this fraction of the repo's files, the
+// surgical delete-and-COPY writeback is replaced by the full-rebuild write
+// plan (wipe + bulk COPY of the already-built graph). 0.5 is a coarse
+// crossover knob, not a tuned constant — lower it if surgical writebacks
+// above ~30% ever measure slower than the full COPY.
+export const INCREMENTAL_MAX_WRITE_FRACTION = 0.5;
+// …but only at a scale where the surgical plan's overhead is real. Tiny
+// repos hit huge fractions from a single edit (7 files → one touch can
+// pull in 5) while both write plans finish in well under a second there —
+// escalating would churn the DB files for nothing.
+export const INCREMENTAL_ESCALATION_MIN_FILES = 50;
+/**
+ * Should the incremental writeback escalate from per-file surgery to a full
+ * wipe-and-bulk-COPY write plan?
+ *
+ * @param deleteCount        Files whose rows will be DETACH-DELETEd
+ *                           (effective write set ∪ deleted files, deduped).
+ * @param effectiveWriteCount Size of the effective write set (toWrite ∪
+ *                           importer-BFS expansion ∪ boundary-crossing files).
+ * @param totalFiles         Current repo file count (denominator).
+ *
+ * POPULATION MISMATCH (tri-review 4669518496, documented not "fixed"): the
+ * numerator counts effective-write-set members, which include importer-BFS
+ * results read from the PRE-pipeline DB — those can be now-DELETED paths that
+ * the CURRENT file list (the denominator) no longer contains. The fraction is
+ * therefore not a true subset ratio and can exceed 1 on delete-heavy runs.
+ * That errs toward escalation, which is the safe direction (the full write
+ * plan is always correct); the valve's log line clamps the DISPLAYED
+ * percentage to 100 so operators aren't shown ">100% of the repo".
+ */
+export const shouldEscalateIncrementalWrite = (deleteCount, effectiveWriteCount, totalFiles) => deleteCount >= INCREMENTAL_ESCALATION_MIN_FILES &&
+    effectiveWriteCount / Math.max(1, totalFiles) > INCREMENTAL_MAX_WRITE_FRACTION;

package/dist/core/incremental/shadow-candidates.d.ts

@@ -2,9 +2,9 @@
  * Shadow-candidate path derivation for incremental indexing.
  *
  * Background — Bugbot review on PR #1479:
- *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
- *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
- *   written yet. But pre-existing files may have IMPORTS edges that
+ *   the importer BFS (queryImportersBatch) on a NEWLY ADDED file returns
+ *   0 importers in the pre-pipeline DB, because the new file's IMPORTS
+ *   rows haven't been written yet. But pre-existing files may have IMPORTS edges that
  *   *resolved to a sibling path*, and the newcomer can now steal that
  *   resolution under standard JS/TS module-resolution rules. Without
  *   pulling those pre-existing files into the writable set, their

package/dist/core/incremental/shadow-candidates.js

@@ -2,9 +2,9 @@
  * Shadow-candidate path derivation for incremental indexing.
  *
  * Background — Bugbot review on PR #1479:
- *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
- *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
- *   written yet. But pre-existing files may have IMPORTS edges that
+ *   the importer BFS (queryImportersBatch) on a NEWLY ADDED file returns
+ *   0 importers in the pre-pipeline DB, because the new file's IMPORTS
+ *   rows haven't been written yet. But pre-existing files may have IMPORTS edges that
  *   *resolved to a sibling path*, and the newcomer can now steal that
  *   resolution under standard JS/TS module-resolution rules. Without
  *   pulling those pre-existing files into the writable set, their

package/dist/core/incremental/subgraph-extract.d.ts

@@ -22,7 +22,7 @@
  *
  * `extractChangedSubgraph` intentionally does NOT expand the set it is
  * given — expansion is the orchestrator's job, so the SAME expanded set
- * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * can be fed to both `deleteNodesForFiles` and this function (asymmetry
  * between the delete set and the write set silently corrupts the DB).
  * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
  * walk; the orchestrator composes it with its importer-BFS expansion and
@@ -57,7 +57,7 @@ export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWrite
  * deleted + rewritten in lockstep with the changed side.
  *
  * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
- * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * orchestrator MUST feed the returned set to both `deleteNodesForFiles`
  * and `extractChangedSubgraph` — feeding the unexpanded set to either
  * one leaves stale rows or PK-conflicts at COPY time.
  */

package/dist/core/incremental/subgraph-extract.js

@@ -22,7 +22,7 @@
  *
  * `extractChangedSubgraph` intentionally does NOT expand the set it is
  * given — expansion is the orchestrator's job, so the SAME expanded set
- * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * can be fed to both `deleteNodesForFiles` and this function (asymmetry
  * between the delete set and the write set silently corrupts the DB).
  * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
  * walk; the orchestrator composes it with its importer-BFS expansion and
@@ -118,7 +118,7 @@ export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
  * deleted + rewritten in lockstep with the changed side.
  *
  * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
- * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * orchestrator MUST feed the returned set to both `deleteNodesForFiles`
  * and `extractChangedSubgraph` — feeding the unexpanded set to either
  * one leaves stale rows or PK-conflicts at COPY time.
  */

package/dist/core/lbug/cypher-escape.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Escape a value for embedding in a single-quoted Cypher string literal.
+ *
+ * LadybugDB's parser uses backslash escapes and REJECTS SQL-style `''`
+ * doubling — `'we''ird'` is a parser error, not an escaped quote (#2409
+ * review). Every call site that used doubling produced a query that never
+ * parsed; the failures were invisible wherever the site swallowed errors
+ * (per-file deletes skipping quoted paths, importer BFS returning [],
+ * augment/wiki batch lookups silently missing rows).
+ *
+ * Backslashes are escaped first, then quotes — reversing the order would
+ * double the backslash that the quote escape just introduced. For values
+ * inside single-quoted literals only; table/label names go through
+ * `escapeTableName` in lbug-adapter instead.
+ *
+ * NOT for CSV emission: the COPY path (csv-generator.ts) quotes fields for
+ * LadybugDB's CSV reader (`ESCAPE='"'`), a different grammar with its own
+ * rules — its `''` usages are not this bug.
+ */
+export declare const escapeCypherString: (value: string) => string;