gitnexus 1.6.6-rc.98 → 1.6.6

package/dist/core/tree-sitter/safe-parse.js

@@ -1,3 +1,4 @@
+import { logger } from '../logger.js';
 /**
  * tree-sitter 0.21.x's Node native binding crashes (SIGSEGV) on Windows when
  * `parser.parse(string, …)` is handed a JS string longer than 32 767 chars.
@@ -16,17 +17,219 @@ const SAFE_PARSE_CHUNK_CHARS = 16 * 1024;
  */
 const DIRECT_PARSE_LIMIT_CHARS = 16 * 1024;
 /**
- * Parse `sourceText` safely on every platform. See {@link SAFE_PARSE_CHUNK_CHARS}
- * for the underlying tree-sitter binding bug this works around.
+ * Default per-parse wall-clock budget in milliseconds. A pathological input
+ * (deeply nested / quadratic-grammar source) can spin tree-sitter for tens of
+ * seconds, stalling the worker that holds it. The pool's per-dispatch idle
+ * timeout is 30 s (`DEFAULT_SUB_BATCH_IDLE_TIMEOUT_MS` in
+ * `workers/worker-pool.ts`); this budget MUST stay below it so a single bad
+ * file is hard-skipped here rather than tripping the slower pool-level
+ * retry/respawn machinery. 15 s leaves comfortable headroom.
+ *
+ * Override via `GITNEXUS_PARSE_TIMEOUT_MS`; `0` disables the budget entirely
+ * (unlimited parse time — restore the historical behaviour for debugging).
+ */
+const DEFAULT_PARSE_TIMEOUT_MS = 15_000;
+/**
+ * Resolve the per-parse budget in milliseconds from the environment. A
+ * non-negative integer overrides the default; `0` disables the timeout.
+ * Unparseable / negative values fall back to the default rather than
+ * silently disabling the safety net.
+ */
+function resolveParseTimeoutMs() {
+    const raw = process.env.GITNEXUS_PARSE_TIMEOUT_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_PARSE_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_PARSE_TIMEOUT_MS;
+    return Math.floor(parsed);
+}
+/**
+ * Tiny shim around the runtime's parse-interruption knob so the future
+ * 0.25/0.26 swap (where `setTimeoutMicros` is removed in favour of
+ * `Parser.Options.progressCallback`) is a single-function change.
+ *
+ * Returns `true` when a budget was armed (caller must clear it afterwards),
+ * `false` when the runtime offers no interruption mechanism (older/newer
+ * runtimes) so the caller can skip the reset/clear dance.
+ *
+ * Only the `setTimeoutMicros` branch is implemented today; add the
+ * `progressCallback` branch here when the runtime moves to 0.25+.
+ */
+function armParseBudget(parser, budgetMs) {
+    if (budgetMs <= 0)
+        return false;
+    const cap = parser;
+    if (typeof cap.setTimeoutMicros !== 'function')
+        return false;
+    cap.setTimeoutMicros(Math.floor(budgetMs * 1000));
+    return true;
+}
+/**
+ * Clear any armed parse budget so it never leaks to the next parse on a
+ * reused/singleton parser. Safe to call when nothing was armed.
+ */
+function clearParseBudget(parser) {
+    const cap = parser;
+    cap.setTimeoutMicros?.(0);
+}
+/**
+ * Reset parser state after a timeout. tree-sitter RESUMES the interrupted
+ * parse on the next `parse()` call unless `reset()` is invoked first
+ * (tree-sitter `api.h`); skipping this corrupts the next file's tree on the
+ * shared singleton.
+ */
+function resetParser(parser) {
+    parser.reset?.();
+}
+/**
+ * Thrown when a parse exceeds its wall-clock budget (see
+ * {@link DEFAULT_PARSE_TIMEOUT_MS}). The parser has already been `reset()` and
+ * its budget cleared by the time this propagates, so callers may safely reuse
+ * the same parser for the next file.
+ *
+ * Hard-skip contract: a timeout is fatal for the offending file but MUST NOT
+ * abort the run. Every caller is responsible for catching this specific error
+ * (`instanceof ParseTimeoutError`), skipping that one file (degrade-and-
+ * continue), and re-throwing anything else. Catching it generically and
+ * swallowing all errors would mask real bugs, so callers match on the type.
+ */
+export class ParseTimeoutError extends Error {
+    budgetMs;
+    label;
+    constructor(budgetMs, label) {
+        super(`tree-sitter parse exceeded its ${budgetMs}ms budget` +
+            (label ? ` while parsing ${label}` : '') +
+            ' (set GITNEXUS_PARSE_TIMEOUT_MS=0 to disable, or raise the budget)');
+        this.name = 'ParseTimeoutError';
+        this.budgetMs = budgetMs;
+        this.label = label;
+    }
+}
+/**
+ * Per-run counter so a corpus full of minor-error files emits a bounded
+ * number of degraded-parse logs instead of one per file. The count is
+ * reported on the throttled records so operators still see the true scale.
  */
-export function parseSourceSafe(parser, sourceText, oldTree, options) {
-    if (sourceText.length <= DIRECT_PARSE_LIMIT_CHARS) {
-        return parser.parse(sourceText, oldTree, options);
+let degradedParseCount = 0;
+const DEGRADED_PARSE_LOG_LIMIT = 20;
+/**
+ * Reset the per-run degraded-parse log throttle. Called at the start of every
+ * analysis run (`runFullAnalysis`) so the first-N-then-suppress budget is
+ * scoped to a single run rather than to the lifetime of the module (which, on
+ * a reused process, would suppress all degraded-parse logs after the first
+ * run). Safe to call at any time.
+ */
+export function resetDegradedParseCounter() {
+    degradedParseCount = 0;
+}
+/**
+ * @internal Test-only alias for {@link resetDegradedParseCounter}, kept so the
+ * existing `safe-parse.test.ts` import keeps working. Prefer the public name.
+ */
+export function _resetDegradedParseCounter() {
+    resetDegradedParseCounter();
+}
+/**
+ * True when the parsed tree contains any ERROR or MISSING node — i.e. the
+ * source did not parse cleanly and tree-sitter applied error recovery.
+ * `parse` never throws on bad syntax (it recovers into ERROR/MISSING nodes),
+ * so this is the only signal callers have that a tree is degraded.
+ */
+export function parseHadErrors(tree) {
+    const root = tree.rootNode;
+    if (root == null)
+        return false;
+    return root.hasError || root.isMissing;
+}
+/**
+ * Structured diagnostics for a parsed tree. Cheap (reads boolean node
+ * properties only); callers that just want a yes/no use {@link parseHadErrors}.
+ */
+export function getParseDiagnostics(tree) {
+    const root = tree.rootNode;
+    if (root == null)
+        return { hasError: false, isMissing: false };
+    return { hasError: root.hasError, isMissing: root.isMissing };
+}
+/**
+ * Parse `sourceText` safely on every platform.
+ *
+ * This is the single "parse safely" entry point and its contract covers three
+ * concerns:
+ *
+ *  1. **Windows crash workaround.** Inputs longer than 32 767 chars are fed
+ *     through the chunked `Parser.Input` callback overload to dodge the
+ *     0.21.x string-to-buffer SIGSEGV. See {@link SAFE_PARSE_CHUNK_CHARS}.
+ *
+ *  2. **Runaway-parse timeout.** A per-parse budget (default 15 s, env
+ *     `GITNEXUS_PARSE_TIMEOUT_MS`, `0` disables) is armed before parsing on
+ *     both the direct and chunked paths. On timeout the runtime returns
+ *     `null`; this function `reset()`s the parser, clears the budget, and
+ *     throws {@link ParseTimeoutError}. The budget is always cleared in a
+ *     `finally` so it never leaks to the next parse on a reused/singleton
+ *     parser (`loadParser()` and the worker both reuse one `Parser`).
+ *
+ *  3. **Intrinsic error detection.** On a successful parse, a degraded tree
+ *     (`rootNode.hasError`) is logged at `debug` level with throttling, then
+ *     the tree is **returned anyway** — error recovery is a downgrade, never a
+ *     drop. Callers wanting the boolean use {@link parseHadErrors}.
+ *
+ * @param label optional context (e.g. file path) attached to timeout errors
+ *   and degraded-parse logs. Non-breaking trailing param.
+ */
+export function parseSourceSafe(parser, sourceText, oldTree, options, label) {
+    const budgetMs = resolveParseTimeoutMs();
+    const armed = armParseBudget(parser, budgetMs);
+    let tree;
+    try {
+        if (sourceText.length <= DIRECT_PARSE_LIMIT_CHARS) {
+            tree = parser.parse(sourceText, oldTree, options);
+        }
+        else {
+            const input = (index) => {
+                if (index >= sourceText.length)
+                    return null;
+                return sourceText.slice(index, index + SAFE_PARSE_CHUNK_CHARS);
+            };
+            tree = parser.parse(input, oldTree, options);
+        }
+    }
+    finally {
+        // Always clear the budget — otherwise it leaks onto the next parse on a
+        // reused singleton parser, prematurely killing an innocent file.
+        if (armed)
+            clearParseBudget(parser);
+    }
+    // A `null` return means the runtime hit the budget mid-parse. The parser
+    // would otherwise RESUME this parse on the next call, so reset it before
+    // surfacing the timeout as a typed throw (callers skip the file).
+    if (tree === null) {
+        if (armed)
+            resetParser(parser);
+        throw new ParseTimeoutError(budgetMs, label);
+    }
+    // Intrinsic ERROR detection. tree-sitter recovers from bad syntax into
+    // ERROR/MISSING nodes rather than throwing, so a clean return can still
+    // wrap a degraded tree. Log it (throttled, debug-level so common minor
+    // errors don't flood) but DOWNGRADE — never drop — and return the tree.
+    //
+    // Guard `rootNode` defensively: a real tree-sitter tree always exposes one,
+    // but stub parsers in tests (and any future non-standard `Parser.Tree`) may
+    // not. A missing root is treated as "no detectable errors" so detection
+    // never throws on the parse success path.
+    if (tree.rootNode != null && parseHadErrors(tree)) {
+        degradedParseCount += 1;
+        if (degradedParseCount <= DEGRADED_PARSE_LOG_LIMIT) {
+            logger.debug({
+                ...(label ? { file: label } : {}),
+                rootType: tree.rootNode.type,
+                degradedParseCount,
+                ...(degradedParseCount === DEGRADED_PARSE_LOG_LIMIT
+                    ? { note: 'further degraded-parse logs suppressed this run' }
+                    : {}),
+            }, 'tree-sitter parsed with errors (degraded tree)');
+        }
     }
-    const input = (index) => {
-        if (index >= sourceText.length)
-            return null;
-        return sourceText.slice(index, index + SAFE_PARSE_CHUNK_CHARS);
-    };
-    return parser.parse(input, oldTree, options);
+    return tree;
 }

package/dist/core/wiki/generator.js

@@ -17,7 +17,7 @@ import { generateHTMLViewer } from './html-viewer.js';
 import { sanitizeMermaidMarkdown } from './mermaid-sanitizer.js';
 import { callLLM, estimateTokens, } from './llm-client.js';
 import { callCursorLLM, resolveCursorConfig } from './cursor-client.js';
-import { callClaudeLLM, callCodexLLM, resolveLocalCLIConfig } from './local-cli-client.js';
+import { callClaudeLLM, callCodexLLM, callOpenCodeLLM, resolveLocalCLIConfig, } from './local-cli-client.js';
 import { GROUPING_SYSTEM_PROMPT, GROUPING_USER_PROMPT, MODULE_SYSTEM_PROMPT, MODULE_USER_PROMPT, PARENT_SYSTEM_PROMPT, PARENT_USER_PROMPT, OVERVIEW_SYSTEM_PROMPT, OVERVIEW_USER_PROMPT, fillTemplate, formatFileListForGrouping, formatDirectoryTree, formatCallEdges, formatProcesses, } from './prompts.js';
 import { shouldIgnorePath } from '../../config/ignore-service.js';
 // ─── Constants ────────────────────────────────────────────────────────
@@ -123,15 +123,23 @@ export class WikiGenerator {
             });
             return callCursorLLM(prompt, cursorConfig, systemPrompt, options);
         }
-        if (this.llmConfig.provider === 'claude' || this.llmConfig.provider === 'codex') {
+        if (this.llmConfig.provider === 'claude' ||
+            this.llmConfig.provider === 'codex' ||
+            this.llmConfig.provider === 'opencode') {
             const localConfig = resolveLocalCLIConfig({
                 model: this.llmConfig.model,
                 workingDirectory: this.repoPath,
                 requestTimeoutMs: this.llmConfig.requestTimeoutMs,
             });
-            return this.llmConfig.provider === 'claude'
-                ? callClaudeLLM(prompt, localConfig, systemPrompt, options)
-                : callCodexLLM(prompt, localConfig, systemPrompt, options);
+            if (this.llmConfig.provider === 'claude') {
+                return callClaudeLLM(prompt, localConfig, systemPrompt, options);
+            }
+            if (this.llmConfig.provider === 'codex') {
+                return callCodexLLM(prompt, localConfig, systemPrompt, options);
+            }
+            if (this.llmConfig.provider === 'opencode') {
+                return callOpenCodeLLM(prompt, localConfig, systemPrompt, options);
+            }
         }
         return callLLM(prompt, this.llmConfig, systemPrompt, options);
     }

package/dist/core/wiki/graph-queries.d.ts

@@ -43,6 +43,9 @@ export declare function initWikiDb(lbugPath: string): Promise<void>;
 export declare function closeWikiDb(): Promise<void>;
 /**
  * Get all source files with their exported symbol names and types.
+ * Includes top-level exports (File→DEFINES→n) and exported class members
+ * (File→DEFINES→Class→HAS_METHOD/HAS_PROPERTY→n) since class members no
+ * longer have a direct File→DEFINES edge.
  */
 export declare function getFilesWithExports(): Promise<FileWithExports[]>;
 /**

package/dist/core/wiki/graph-queries.js

@@ -26,13 +26,21 @@ export async function closeWikiDb() {
 }
 /**
  * Get all source files with their exported symbol names and types.
+ * Includes top-level exports (File→DEFINES→n) and exported class members
+ * (File→DEFINES→Class→HAS_METHOD/HAS_PROPERTY→n) since class members no
+ * longer have a direct File→DEFINES edge.
  */
 export async function getFilesWithExports() {
     const rows = await executeQuery(REPO_ID, `
     MATCH (f:File)-[:CodeRelation {type: 'DEFINES'}]->(n)
     WHERE n.isExported = true
     RETURN f.filePath AS filePath, n.name AS name, labels(n)[0] AS type
-    ORDER BY f.filePath
+    UNION
+    MATCH (f:File)-[:CodeRelation {type: 'DEFINES'}]->(c)
+          -[mr:CodeRelation]->(n)
+    WHERE mr.type IN ['HAS_METHOD', 'HAS_PROPERTY'] AND n.isExported = true
+    RETURN f.filePath AS filePath, n.name AS name, labels(n)[0] AS type
+    ORDER BY filePath
   `);
     const fileMap = new Map();
     for (const row of rows) {

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

@@ -6,7 +6,7 @@
  *
  * Config priority: CLI flags > env vars > defaults
  */
-export type LLMProvider = 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor' | 'claude' | 'codex';
+export type LLMProvider = 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor' | 'claude' | 'codex' | 'opencode';
 export interface LLMConfig {
     apiKey: string;
     baseUrl: string;

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

@@ -16,8 +16,13 @@ export async function resolveLLMConfig(overrides) {
             ? savedConfig.claudeModel
             : savedProvider === 'codex'
                 ? savedConfig.codexModel
-                : undefined;
-    const localProvider = savedProvider === 'cursor' || savedProvider === 'claude' || savedProvider === 'codex';
+                : savedProvider === 'opencode'
+                    ? savedConfig.opencodeModel
+                    : undefined;
+    const localProvider = savedProvider === 'cursor' ||
+        savedProvider === 'claude' ||
+        savedProvider === 'codex' ||
+        savedProvider === 'opencode';
     const apiKey = overrides?.apiKey ||
         process.env.GITNEXUS_API_KEY ||
         process.env.OPENAI_API_KEY ||

package/dist/core/wiki/local-cli-client.d.ts

@@ -5,7 +5,7 @@
  * an OpenAI-compatible HTTP API.
  */
 import type { LLMResponse, CallLLMOptions } from './llm-client.js';
-export type LocalAgentProvider = 'claude' | 'codex';
+export type LocalAgentProvider = 'claude' | 'codex' | 'opencode';
 export interface LocalCLIConfig {
     model?: string;
     workingDirectory?: string;
@@ -15,3 +15,4 @@ export declare function detectLocalCLI(provider: LocalAgentProvider): string | n
 export declare function resolveLocalCLIConfig(overrides?: Partial<LocalCLIConfig>): LocalCLIConfig;
 export declare function callClaudeLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;
 export declare function callCodexLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;
+export declare function callOpenCodeLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;

package/dist/core/wiki/local-cli-client.js

@@ -14,6 +14,7 @@ import { logger } from '../logger.js';
 const COMMANDS = {
     claude: 'claude',
     codex: 'codex',
+    opencode: 'opencode',
 };
 function killChildTree(child) {
     if (process.platform === 'win32' && child.pid !== undefined) {
@@ -121,6 +122,66 @@ export async function callCodexLLM(prompt, config, systemPrompt, options) {
         await fs.rm(outputDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
+function parseOpenCodeEventStream(output) {
+    const lines = output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const textParts = [];
+    for (const line of lines) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === 'error') {
+            const message = event.error?.data?.message ||
+                event.error?.name ||
+                event.message ||
+                event.part?.text ||
+                line;
+            throw new Error(`OpenCode CLI returned error event: ${message}`);
+        }
+        if (event.type === 'text' && typeof event.part?.text === 'string') {
+            textParts.push(event.part.text);
+        }
+    }
+    const content = textParts.join('').trim();
+    if (!content) {
+        throw new Error('OpenCode CLI returned no text output');
+    }
+    return content;
+}
+function buildChildEnv(provider) {
+    const env = {
+        ...process.env,
+        CI: '1',
+    };
+    if (provider === 'opencode') {
+        delete env.OPENCODE_SERVER_PASSWORD;
+        delete env.OPENCODE_SERVER_USERNAME;
+    }
+    return env;
+}
+export async function callOpenCodeLLM(prompt, config, systemPrompt, options) {
+    const commandInfo = getDetectedCommand('opencode');
+    if (!commandInfo) {
+        throw new Error('OpenCode CLI not found. Install OpenCode CLI and ensure `opencode` is on PATH.');
+    }
+    const workingDirectory = config.workingDirectory || process.cwd();
+    const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\n${prompt}` : prompt;
+    // OpenCode does not expose a Codex-style read-only sandbox / no-tools flag,
+    // so we rely on its non-interactive permission model and tolerate any
+    // non-JSON stdout warnings in the parser.
+    const args = ['run', '--format', 'json', '--dir', workingDirectory];
+    if (config.model) {
+        args.push('--model', config.model);
+    }
+    const response = await runLocalCLI('opencode', commandInfo, args, config, fullPrompt, options);
+    return { content: parseOpenCodeEventStream(response.content) };
+}
 function runLocalCLI(provider, commandInfo, args, config, stdinText, options) {
     const finalArgs = [...commandInfo.argsPrefix, ...args];
     verboseLog(provider, 'Spawning:', commandInfo.command, maskPromptArgs(provider, finalArgs).join(' '));
@@ -137,10 +198,7 @@ function runLocalCLI(provider, commandInfo, args, config, stdinText, options) {
             cwd: config.workingDirectory || process.cwd(),
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
-            env: {
-                ...process.env,
-                CI: '1',
-            },
+            env: buildChildEnv(provider),
         });
         verboseLog(provider, 'Process spawned with PID:', child.pid);
         let stdout = '';

package/dist/mcp/compatible-stdio-transport.d.ts

@@ -6,10 +6,13 @@ export declare class CompatibleStdioServerTransport implements Transport {
     private readonly _stdout;
     private _readBuffer;
     private _started;
+    private _closed;
     private _framing;
     onmessage?: (message: JSONRPCMessage) => void;
     onerror?: (error: Error) => void;
     onclose?: () => void;
+    /** Stable bound reference so `on`/`off` always use the same function. */
+    private readonly _boundClose;
     constructor(_stdin?: NodeJS.ReadableStream, _stdout?: NodeJS.WritableStream);
     private readonly _ondata;
     private readonly _onerror;

package/dist/mcp/compatible-stdio-transport.js

@@ -35,10 +35,13 @@ export class CompatibleStdioServerTransport {
     _stdout;
     _readBuffer;
     _started = false;
+    _closed = false;
     _framing = null;
     onmessage;
     onerror;
     onclose;
+    /** Stable bound reference so `on`/`off` always use the same function. */
+    _boundClose = this.close.bind(this);
     constructor(_stdin = process.stdin, _stdout = process.stdout) {
         this._stdin = _stdin;
         this._stdout = _stdout;
@@ -59,9 +62,23 @@ export class CompatibleStdioServerTransport {
         if (this._started) {
             throw new Error('CompatibleStdioServerTransport already started!');
         }
+        if (this._closed) {
+            throw new Error('CompatibleStdioServerTransport has been permanently closed');
+        }
+        // If stdin is already closed (parent died before we registered listeners),
+        // the 'end'/'close' event was already emitted and will never fire again.
+        // Close the transport immediately to avoid orphaned processes.
+        if (this._stdin.readableEnded ||
+            this._stdin.destroyed) {
+            this._started = true;
+            await this.close();
+            return;
+        }
         this._started = true;
         this._stdin.on('data', this._ondata);
         this._stdin.on('error', this._onerror);
+        this._stdin.on('end', this._boundClose);
+        this._stdin.on('close', this._boundClose);
     }
     detectFraming() {
         if (!this._readBuffer || this._readBuffer.length === 0) {
@@ -162,8 +179,13 @@ export class CompatibleStdioServerTransport {
         }
     }
     async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
         this._stdin.off('data', this._ondata);
         this._stdin.off('error', this._onerror);
+        this._stdin.off('end', this._boundClose);
+        this._stdin.off('close', this._boundClose);
         const remainingDataListeners = this._stdin.listenerCount('data');
         if (remainingDataListeners === 0) {
             this._stdin.pause();

package/dist/mcp/core/embedder.d.ts

@@ -4,7 +4,7 @@
  * Singleton factory for transformers.js embedding pipeline.
  * For MCP, we only need to compute query embeddings, not batch embed.
  */
-import { type FeatureExtractionPipeline } from '@huggingface/transformers';
+import type { FeatureExtractionPipeline } from '@huggingface/transformers';
 /**
  * Initialize the embedding model (lazy, on first search)
  */

package/dist/mcp/core/embedder.js

@@ -4,10 +4,10 @@
  * Singleton factory for transformers.js embedding pipeline.
  * For MCP, we only need to compute query embeddings, not batch embed.
  */
-import { pipeline, env } from '@huggingface/transformers';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
 import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry, } from '../../core/embeddings/hf-env.js';
+import { getLocalEmbeddingRuntimeBlocker } from '../../core/embeddings/runtime-support.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 import { logger } from '../../core/logger.js';
 // Model config
@@ -23,6 +23,15 @@ export const initEmbedder = async () => {
     if (isHttpMode()) {
         throw new Error('initEmbedder() should not be called in HTTP mode.');
     }
+    // Fail fast on platforms where the bundled native ONNX Runtime binding is not
+    // shipped (macOS Intel, #1515). Must run before any transformers.js /
+    // onnxruntime-node import or resolution — otherwise the native module load
+    // crashes with a raw "Cannot find module ...onnxruntime_binding.node" that
+    // ONNX_WEB_BACKEND=wasm cannot rescue (#1516).
+    const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();
+    if (runtimeBlocker) {
+        throw new Error(runtimeBlocker);
+    }
     if (embedderInstance) {
         return embedderInstance;
     }
@@ -32,6 +41,9 @@ export const initEmbedder = async () => {
     isInitializing = true;
     initPromise = (async () => {
         try {
+            // Lazy-load transformers.js only after the runtime guard has passed, so
+            // unsupported platforms never reach the native ONNX import (#1515).
+            const { pipeline, env } = await import('@huggingface/transformers');
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →
             // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in

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

@@ -74,9 +74,16 @@ interface RepoHandle {
  */
 export declare function resolveWorktreeCwd(repoPath: string, launchCwd: string): string;
 /**
- * Length of the base64url path hash appended to a colliding repo id.
+ * Length of the path-derived suffix appended to a colliding repo id.
  * Exported so tests can pin the suffix shape without re-deriving the
- * literal; see `repoId()` and the hashed-id resolution tier (#1658).
+ * literal; see `assignRepoId()` and the hashed-id resolution tier (#1658).
+ *
+ * Note: base64url is an *encoding*, not a hash — it preserves byte order, so
+ * two paths that share a long common prefix (sibling clones under one parent)
+ * collapse to the same sliced suffix. `assignRepoId()` keeps the legacy
+ * base64url suffix only for the first colliding duplicate (id compatibility)
+ * and falls back to a content hash of the resolved path on a real collision
+ * (#2054).
  */
 export declare const REPO_ID_HASH_LENGTH = 6;
 export declare class LocalBackend {
@@ -118,10 +125,25 @@ export declare class LocalBackend {
      */
     private refreshRepos;
     /**
-     * Generate a stable repo ID from name + path.
-     * If names collide, append a hash of the path.
+     * Assign a collision-free in-memory id for a registered repo.
+     *
+     * - Unique name → the bare lowercased name.
+     * - Duplicate name → a path-derived suffix. The *first* colliding clone keeps
+     *   the legacy `base64url(path)` suffix so ids generated before #2054 still
+     *   resolve (the #1658 hashed-id tier). base64url is an encoding, not a hash:
+     *   it preserves byte order, so sibling clones under one parent (e.g.
+     *   `.../REPO_2` and `.../REPO_3`) yield identical leading characters and thus
+     *   the same sliced suffix. Any further collision therefore falls back to a
+     *   content hash of the *resolved* path (order-insensitive), extended
+     *   deterministically until unique.
+     *
+     * `assigned` maps every id handed out in this refresh to its resolved path,
+     * so a candidate is "free" when it is unused or already owned by this exact
+     * path. This method records its own assignment into `assigned` before
+     * returning, so the map-update is the function's invariant, not a caller
+     * obligation. A returned id never overwrites a different path's handle (#2054).
      */
-    private repoId;
+    private assignRepoId;
     /**
      * Resolve which repo to use.
      * - If repoParam is given, match by name or path
@@ -148,6 +170,16 @@ export declare class LocalBackend {
      */
     private pickRepoHandleForCwd;
     private handleToRegistryEntry;
+    /**
+     * Ensure the LadybugDB pool is open for the *resolved* repo.
+     *
+     * Takes the `RepoHandle` the caller resolved — NOT a bare id — and keys the
+     * pool (and the init/staleness/reinit maps) by the immutable `lbugPath`. Two
+     * things matter for multi-clone correctness: (1) the handle is the one the
+     * caller resolved, so a concurrent `refreshRepos` can't substitute a different
+     * clone; (2) the pool key is the database path, so distinct clones never share
+     * a pool entry even when their name-derived id transiently collides (#2067).
+     */
     private ensureInitialized;
     /**
      * Get context for a specific repo (or the single repo if only one).