gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/_shared/scope-resolution/types.d.ts

@@ -27,8 +27,20 @@ import type { SymbolDefinition } from './symbol-definition.js';
 export type ScopeId = string;
 /** Stable symbol-definition identifier (graph nodeId). */
 export type DefId = string;
-/** Kinds of lexical scope a `Scope` node can represent. */
-export type ScopeKind = 'Module' | 'Namespace' | 'Class' | 'Function' | 'Block' | 'Expression';
+/**
+ * Kinds of lexical scope a `Scope` node can represent.
+ *
+ * `Object` is a hoist boundary ONLY: an object/record literal body
+ * (TS/JS `{...}`, Kotlin anonymous `object {...}`). Members are
+ * reachable via property access, never as bare identifiers, so
+ * scope-chain walkers (`scope/walkers.ts`) must skip an `Object`
+ * scope's own bindings while still traversing past it to the parent
+ * (#2545/#2551) -- unlike `Block`, where a nested closure legitimately
+ * DOES see a sibling `let`/`const` from an enclosing `if`/`for`/`while`,
+ * a nested closure inside an object literal must NOT see a sibling
+ * property's name as a free identifier.
+ */
+export type ScopeKind = 'Module' | 'Namespace' | 'Class' | 'Function' | 'Block' | 'Expression' | 'Object';
 /** Source-text range. 1-based `startLine`/`endLine`; 0-based `startCol`/`endCol`. */
 export interface Range {
     readonly startLine: number;
@@ -85,6 +97,9 @@ export type ParsedImport =
     readonly localName: string;
     readonly importedName: string;
     readonly targetRaw: string;
+    /** Provider-specific imported symbol category when module and symbol
+     * namespaces have distinct resolution rules (for example PHP). */
+    readonly importedSymbolKind?: 'type' | 'function' | 'const';
     /**
      * Set by providers when `targetRaw` already names the imported symbol
      * rather than only its containing module. Consumers that compose
@@ -107,6 +122,8 @@ export type ParsedImport =
     readonly alias: string;
     readonly targetRaw: string;
     /** See the same field on the `named` variant. */
+    readonly importedSymbolKind?: 'type' | 'function' | 'const';
+    /** See the same field on the `named` variant. */
     readonly targetIncludesImportedName?: boolean;
 }
 /**
@@ -372,7 +389,7 @@ export interface Reference {
     readonly toDef: DefId;
     /** Location of the reference in source. */
     readonly atRange: Range;
-    readonly kind: 'call' | 'read' | 'write' | 'type-reference' | 'inherits' | 'import-use' | 'macro';
+    readonly kind: 'call' | 'read' | 'write' | 'type-reference' | 'inherits' | 'import-use' | 'value-ref' | 'macro';
     readonly confidence: number;
     readonly evidence: readonly ResolutionEvidence[];
 }

package/dist/_shared/scope-resolution/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}

package/dist/cli/ai-context.d.ts

@@ -2,7 +2,7 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import { type GeneratedSkillInfo } from './skill-gen.js';

package/dist/cli/ai-context.js

@@ -2,12 +2,13 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { STANDARD_SKILL_CATALOG } from './standard-skills.js';
 import { logger } from '../core/logger.js';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -81,22 +82,19 @@ export function generateGitNexusContent(projectName, stats, opts = {}) {
     const { generatedSkills, groupNames, noStats, skipSkills, runnerPath = '.gitnexus/run.cjs', defaultBranch = 'main', hasPdg = false, } = opts;
     const generatedRows = generatedSkills && generatedSkills.length > 0
         ? generatedSkills
-            .map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`)
+            .map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/${s.name}/SKILL.md\` |`)
             .join('\n')
         : '';
     // Standard skill rows reference files installed by installSkills(). When
     // --skip-skills suppresses that install, these rows must be omitted — else
     // AGENTS.md/CLAUDE.md would direct agents to read files that don't exist.
-    // Community skills (generatedRows) live in .claude/skills/generated/ and
+    // Community skills (generatedRows) live directly under .claude/skills/ and
     // are independent of --skip-skills, so they remain when present.
     const standardSkillsRows = skipSkills
         ? ''
-        : `| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
-| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
-| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |`;
+        : STANDARD_SKILL_CATALOG.filter((skill) => skill.distributions.project)
+            .map((skill) => `| ${skill.agentTableTask} | \`.claude/skills/${skill.name}/SKILL.md\` |`)
+            .join('\n');
     const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
     const skillsTable = tableBody
         ? `| Task | Read this skill file |
@@ -253,40 +251,14 @@ async function upsertGitNexusSection(filePath, content, projectName, stats, noSt
     return 'appended';
 }
 /**
- * Install GitNexus skills to .claude/skills/gitnexus/
+ * Install GitNexus skills as direct children of .claude/skills/
  * Works natively with Claude Code, Cursor, and GitHub Copilot
  */
 async function installSkills(repoPath) {
-    const skillsDir = path.join(repoPath, '.claude', 'skills', 'gitnexus');
+    const skillsDir = path.join(repoPath, '.claude', 'skills');
+    const legacySkillsDir = path.join(skillsDir, 'gitnexus');
     const installedSkills = [];
-    // Skill definitions bundled with the package
-    const skills = [
-        {
-            name: 'gitnexus-exploring',
-            description: 'Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"',
-        },
-        {
-            name: 'gitnexus-debugging',
-            description: 'Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug"',
-        },
-        {
-            name: 'gitnexus-impact-analysis',
-            description: 'Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"',
-        },
-        {
-            name: 'gitnexus-refactoring',
-            description: 'Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"',
-        },
-        {
-            name: 'gitnexus-guide',
-            description: 'Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"',
-        },
-        {
-            name: 'gitnexus-cli',
-            description: 'Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"',
-        },
-    ];
-    for (const skill of skills) {
+    for (const skill of STANDARD_SKILL_CATALOG.filter((entry) => entry.distributions.project && entry.distributions.npm)) {
         const skillDir = path.join(skillsDir, skill.name);
         const skillPath = path.join(skillDir, 'SKILL.md');
         try {
@@ -302,18 +274,27 @@ async function installSkills(repoPath) {
                 // Fallback: generate minimal skill content
                 skillContent = `---
 name: ${skill.name}
-description: ${skill.description}
+description: ${skill.fallbackDescription}
 ---
 
 # ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
 
-${skill.description}
+${skill.fallbackDescription}
 
 Use GitNexus tools to accomplish this task.
 `;
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');
             installedSkills.push(skill.name);
+            // Previous releases installed these known standard skills one level too
+            // deep. Remove only the child owned by this installer; unknown siblings
+            // under the legacy grouping directory may be user-authored and survive.
+            try {
+                await fs.rm(path.join(legacySkillsDir, skill.name), { recursive: true, force: true });
+            }
+            catch (err) {
+                logger.warn({ err }, `Warning: Could not remove legacy skill ${skill.name}:`);
+            }
         }
         catch (err) {
             // Skip on error, don't fail the whole process
@@ -366,15 +347,15 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
         createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
         createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
     }
-    // Install skills to .claude/skills/gitnexus/ (unless --skip-skills)
+    // Install standard skills directly under .claude/skills/ (unless --skip-skills)
     if (!options?.skipSkills) {
         const installedSkills = await installSkills(repoPath);
         if (installedSkills.length > 0) {
-            createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
+            createdFiles.push(`.claude/skills/gitnexus-*/ (${installedSkills.length} skills)`);
         }
     }
     else {
-        createdFiles.push('.claude/skills/gitnexus/ (skipped via --skip-skills)');
+        createdFiles.push('.claude/skills/gitnexus-*/ (skipped via --skip-skills)');
     }
     return { files: createdFiles };
 }

package/dist/cli/analyze.d.ts

@@ -7,6 +7,7 @@
  * This CLI wrapper handles: heap management, progress bar, SIGINT,
  * skill generation (--skills), summary output, and process.exit().
  */
+import { type AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
 /**
  * RAM-aware re-exec heap cap (MB): `0.75 × effective RAM`, clamped to
  * `>= DEFAULT_HEAP_MB`. Kept BELOW physical RAM on purpose — a cap `>=` RAM makes
@@ -55,7 +56,7 @@ export interface AnalyzeOptions {
      * default-on case.
      */
     stats?: boolean;
-    /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
+    /** Skip installing standard GitNexus skill files directly under .claude/skills/. */
     skipSkills?: boolean;
     /**
      * Default branch for the generated regression-compare example (#243). From
@@ -138,4 +139,6 @@ export interface AnalyzeOptions {
  * without booting the full analyze pipeline (#742 review).
  */
 export declare const shouldGenerateCommunitySkillFiles: (options: Pick<AnalyzeOptions, "skills" | "indexOnly"> | undefined, pipelineResult: unknown) => boolean;
-export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions, runnerIdentityAtBootstrap?: AnalyzerRunnerIdentity) => Promise<void>;
+/** Commander entrypoint used only by the capture-before-import lazy bootstrap. */
+export declare const analyzeCommandWithRunnerIdentity: (runnerIdentityAtBootstrap: AnalyzerRunnerIdentity, inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

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, isLbugCheckpointBusyError, 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';
@@ -27,8 +28,9 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { safeUrl } from '../core/embeddings/http-client.js';
-import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { isHttpEmbeddingDimsError, isHttpEmbeddingError, isHttpMode, safeUrl, } from '../core/embeddings/http-client.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -39,6 +41,16 @@ import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 const realStderrWrite = process.stderr.write.bind(process.stderr);
 const realStdoutWrite = process.stdout.write.bind(process.stdout);
 const writeFatalToStderr = (label, err) => {
+    // Walk to the innermost error tagged `userActionable` (set on errors whose
+    // remediation is an operator action — missing/old external tool, stale
+    // config). Render those as a single line; stack/cause are noise for them.
+    for (let cur = err, depth = 0; cur instanceof Error && depth < 5; depth++) {
+        if (cur.userActionable) {
+            realStderrWrite(`\n  ${label}: ${cur.message}\n`);
+            return;
+        }
+        cur = cur.cause;
+    }
     const isErr = err instanceof Error;
     const message = isErr ? err.message : String(err);
     realStderrWrite(`\n  ${label}: ${message}\n`);
@@ -483,7 +495,7 @@ const restoreAnalyzeEnv = (snap) => {
  * without booting the full analyze pipeline (#742 review).
  */
 export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
-export const analyzeCommand = async (inputPath, options) => {
+export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstrap) => {
     if (await ensureHeap())
         return;
     forceHeapOOMForTestIfEnabled();
@@ -504,7 +516,7 @@ export const analyzeCommand = async (inputPath, options) => {
     // pre-call values.
     const envSnap = snapshotAnalyzeEnv();
     try {
-        await analyzeCommandImpl(inputPath, options);
+        await analyzeCommandImpl(inputPath, options, runnerIdentityAtBootstrap);
     }
     finally {
         restoreAnalyzeEnv(envSnap);
@@ -521,7 +533,9 @@ export const analyzeCommand = async (inputPath, options) => {
         process.exit(typeof process.exitCode === 'number' ? process.exitCode : 1);
     }
 };
-const analyzeCommandImpl = async (inputPath, cliOptions) => {
+/** Commander entrypoint used only by the capture-before-import lazy bootstrap. */
+export const analyzeCommandWithRunnerIdentity = async (runnerIdentityAtBootstrap, inputPath, options) => analyzeCommand(inputPath, options, runnerIdentityAtBootstrap);
+const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstrap) => {
     console.log('\n  GitNexus Analyzer\n');
     // ── Resolve the target repo root ──────────────────────────────────
     // Resolved FIRST because `.gitnexusrc` is read from the repo root (not the
@@ -797,6 +811,52 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: custom HTTP embeddings require BOTH --embedding-base-url and --embedding-model ' +
             '(or the matching env vars). Falling back to local ONNX embeddings.\n');
     }
+    // On-demand embedding runtime (#2370): when the optional stack was pruned at
+    // install time (proxy-blocked NuGet download in onnxruntime-node's
+    // postinstall), heal it here instead of failing later in the pipeline. The
+    // install goes through the user's npm registry config (mirrors/proxies
+    // apply) with --ignore-scripts, so no NuGet download is attempted. Runs
+    // before bar.start() like the sibling validations above.
+    if (embeddingsEnabled && !isHttpMode()) {
+        const resolved = resolveEmbeddingRuntime();
+        // Resolved-but-unloadable (a populated prefix on a Node with no
+        // module.registerHooks), or nothing installed on such a Node: fail fast with
+        // capability guidance instead of dying mid-pipeline over an unusable prefix
+        // or downloading a runtime the loader can't reach. A package-sourced stack
+        // never needs the hook, so it is excluded. --embeddings was explicitly
+        // requested and this failure is deterministic, so fail fast rather than
+        // silently degrading to BM25 (distinct from a transient install timeout).
+        if (!isPrefixRuntimeLoadable() && (resolved === null || resolved.source === 'runtime-prefix')) {
+            cliError(`  ${localEmbeddingPrefixUnloadableMessage().replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // On-demand embedding runtime (#2370): when the optional stack was pruned at
+        // install time (proxy-blocked NuGet download in onnxruntime-node's
+        // postinstall), heal it here instead of failing later in the pipeline. The
+        // install goes through the user's npm registry config (mirrors/proxies
+        // apply) with --ignore-scripts, so no NuGet download is attempted.
+        if (resolved === null) {
+            console.log(`  Local embedding runtime is not installed (optional packages were skipped at install time).\n` +
+                `  Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …\n` +
+                `  (one-time; rerun manually anytime with \`gitnexus embeddings install\`)\n`);
+            try {
+                // Short deadline (env override still wins): analyze is interactive, so a
+                // blackholed proxy must not stall the whole index run for the 10-minute
+                // default — fail over to the guidance below instead.
+                await installEmbeddingRuntime({}, getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS));
+                console.log('  Embedding runtime installed.\n');
+            }
+            catch (err) {
+                cliError(`  Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `  ${localEmbeddingStackMissingMessage().replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'local-embedding-stack-missing' });
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
@@ -940,7 +1000,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         const skipAll = options.indexOnly;
         const skipAgentsMd = skipAll || options.skipAgentsMd;
         const skipSkills = skipAll || options.skipSkills;
-        const result = await runFullAnalysis(repoPath, {
+        const runOptions = {
             // Pipeline re-index — OR'd with --skills because skill generation
             // needs a fresh pipelineResult. Has no bearing on the registry
             // collision guard (see allowDuplicateName below).
@@ -987,12 +1047,17 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // in LadybugDB's ClientContext destructor after --pdg writes (#2264). The
             // CHECKPOINT keeps the index durable; process exit reclaims the handles.
             skipNativeCloseOnExit: true,
-        }, {
+        };
+        const runCallbacks = {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
             },
             onLog: barLog,
-        });
+        };
+        const bootstrapArgs = runnerIdentityAtBootstrap
+            ? [runnerIdentityAtBootstrap]
+            : [];
+        const result = await runFullAnalysis(repoPath, runOptions, runCallbacks, ...bootstrapArgs);
         if (result.alreadyUpToDate) {
             // Even the fast path must prove the repo is discoverable. A prior
             // run can write meta.json and then fail before registerRepo(); in
@@ -1181,7 +1246,15 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             return;
         }
         if (isLbugCheckpointIoError(err)) {
+            // #2599: when the checkpoint IO error also looks busy/locked, another
+            // handle holds the store open — name that actionable cause alongside the
+            // threshold hint (the original error is preserved so the hint still fires).
+            const heldOpen = isLbugCheckpointBusyError(err)
+                ? `  Another process may hold the store open (a running \`gitnexus mcp\` server, or a\n` +
+                    `  stale reader) — close other GitNexus processes on this repo, then retry.\n`
+                : '';
             cliError(`  LadybugDB failed while rotating/removing WAL checkpoint files.\n` +
+                heldOpen +
                 `  This can happen when auto-checkpoint runs at the default threshold (~16MB).\n` +
                 `  Retry with a larger checkpoint threshold to reduce checkpoint frequency:\n` +
                 `    gitnexus analyze --wal-checkpoint-threshold ${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD}\n` +
@@ -1190,6 +1263,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
@@ -1203,10 +1333,66 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // The optional embedding stack (@huggingface/transformers → onnxruntime-node)
+        // was pruned at install time — usually a proxy-blocked NuGet download during
+        // onnxruntime-node's postinstall (#2370). Checked before the generic
+        // module-not-found "installation may be corrupt" hint below, which would
+        // otherwise misdiagnose a deliberate optional-dependency skip.
+        if (isMissingLocalEmbeddingStackMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Malformed GITNEXUS_EMBEDDING_DIMS env var (#2385). readConfig() throws a
+        // plain Error (a config mistake, not an endpoint failure), surfacing here from
+        // httpEmbed()->readConfig() inside the analysis run. Show a clean config
+        // message rather than a raw stack dump. The --embedding-dims CLI flag is
+        // validated up front (EMBEDDING_DIMS_ERROR); this covers the env-var path.
+        // Checked before the endpoint/HF branches: it is a plain Error, so
+        // isHttpEmbeddingError() is false and the HF network heuristic must not claim it.
+        if (isHttpEmbeddingDimsError(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'embedding-dims-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Custom HTTP embedding endpoint failure (#2385). When a `--embedding-base-url`
+        // is configured, HTTP mode never downloads a model — so a failure talking to
+        // that endpoint must NOT show the huggingface-download guidance. Keyed on the
+        // error *type* (HttpEmbeddingError), not its message text, so it stays correct
+        // regardless of locale or wording. Checked before the HF branch, whose network
+        // heuristic (`fetch failed` / `ECONNREFUSED`) would otherwise also match a
+        // wrapped endpoint-connection error. The header is deliberately neutral: this
+        // type covers both never-reached failures (connection/timeout/DNS) and
+        // reached-but-failed ones (4xx/5xx, dimension/shape mismatch), so it must not
+        // assert "unreachable". The thrown `msg` carries the specific reason (and the
+        // masked URL where one applies), so it is surfaced verbatim.
+        if (isHttpEmbeddingError(err)) {
+            cliError(`  The custom embedding endpoint request failed.\n` +
+                `  ${msg.replace(/\n/g, '\n  ')}\n` +
+                `  Suggestions:\n` +
+                `    1. Verify the endpoint URL is reachable and running ` +
+                `(--embedding-base-url / GITNEXUS_EMBEDDING_URL: host, port, /v1 path).\n` +
+                `    2. Confirm the model name and embedding dimensions match what the endpoint serves.\n` +
+                `    3. Re-run without --embeddings to index without vectors.\n`, { recoveryHint: 'http-embedding-endpoint-error' });
+            process.exitCode = 1;
+            return;
+        }
+        // isHttpMode() is a pure presence probe (URL+MODEL) that never throws — a
+        // malformed GITNEXUS_EMBEDDING_DIMS is handled by the dims branch above — so
+        // no defensive try/catch is needed here (#2385).
+        const inHttpMode = isHttpMode();
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.
-        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+        // Gated on !inHttpMode: with a custom endpoint configured no model download
+        // is ever attempted, so a network error there is the endpoint's, handled by
+        // the HttpEmbeddingError branch above — never HF's (#2385).
+        if ((isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) &&
+            !inHttpMode) {
             cliError(`  The embedding model could not be downloaded.\n` +
                 `  huggingface.co may be unreachable from your network\n` +
                 `  (e.g. behind a corporate proxy or a regional firewall).\n` +

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' | 'local-embedding-unsupported' | '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