gitnexus 1.6.6-rc.113 → 1.6.6-rc.115

package/README.md

@@ -24,6 +24,14 @@ npx gitnexus analyze
 
 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
+> **On npm 11.x?** `npx` can crash during install (`Cannot destructure property 'package' of 'node.target'`). Use the pnpm form instead:
+>
+> ```bash
+> pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
+> ```
+>
+> See [Troubleshooting → `npx gitnexus` crashes with `node.target is null` (npm 11)](#cannot-destructure-property-package-of-nodetarget-as-it-is-null) for the full matrix (global install, npm downgrade).
+
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
 `gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
@@ -273,22 +281,27 @@ for the full list; stable `latest` is unaffected.
 
 ### `Cannot destructure property 'package' of 'node.target' as it is null`
 
-This crash was caused by a dependency URL format that is incompatible with
-certain npm/arborist versions ([npm/cli#8126](https://github.com/npm/cli/issues/8126)).
-It is fixed in **gitnexus v1.6.2+**. Upgrade to the latest version:
+This error comes from **npm 11.x's arborist** while installing gitnexus (often via `npx`), before gitnexus code runs. It is triggered by platform-filtered `optionalDependencies` in native packages such as `onnxruntime-node` / `@huggingface/transformers` (used when indexing with `--embeddings`). GitNexus cannot catch it at runtime — use one of these workarounds:
 
 ```bash
-npx gitnexus@latest analyze          # always uses the newest release
-# — or —
-npm install -g gitnexus@latest       # upgrade a global install
+pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze       # auto-selected when pnpm + npm 11+
+npm install -g gitnexus@latest         # global install avoids per-run npx reify
+gitnexus analyze                       # if already installed globally
+```
+
+On **pnpm 10+**, lifecycle scripts are blocked unless explicitly allowed — the resolver adds `--allow-build` for `@ladybugdb/core`, `gitnexus`, and `tree-sitter` automatically when it picks `pnpm dlx`.
+
+If you must stay on npm 11.x without pnpm, downgrade npm toolchain-wide (last resort):
+
+```bash
+npm install -g npm@10.9.0
 ```
 
-If you still hit npm install issues after upgrading, these generic workarounds
-may help:
+See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939) and the original [#819](https://github.com/abhigyanpatwari/GitNexus/issues/819) thread. An older variant of this crash (tree-sitter-dart tarball URL) was fixed in gitnexus v1.6.2+ ([#820](https://github.com/abhigyanpatwari/GitNexus/pull/820)); if you still see install failures after upgrading, clear cache:
 
 ```bash
-npm install -g npm@latest            # update npm itself
-npm cache clean --force              # clear a possibly corrupt cache
+npm cache clean --force
+npx gitnexus@latest analyze
 ```
 
 ### `ERR_DLOPEN_FAILED` / `lbugjs.node` missing (pnpm dlx, pnpx)

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

@@ -19,10 +19,11 @@ export interface AIContextOptions {
     noStats?: boolean;
     skipSkills?: boolean;
 }
+export declare function generateGitNexusContent(projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], groupNames?: string[], noStats?: boolean, skipSkills?: boolean, runnerPath?: string): string;
 /**
  * Generate AI context files after indexing
  */
-export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], options?: AIContextOptions): Promise<{
+export declare function generateAIContextFiles(repoPath: string, storagePath: string, projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], options?: AIContextOptions): Promise<{
     files: string[];
 }>;
 export {};

package/dist/cli/ai-context.js

@@ -68,7 +68,11 @@ async function findGroupsContainingRegistryName(registryName) {
     }
     return hits;
 }
-function generateGitNexusContent(projectName, stats, generatedSkills, groupNames, noStats, skipSkills) {
+export function generateGitNexusContent(projectName, stats, generatedSkills, groupNames, noStats, skipSkills, 
+// Project-relative path to the runner `gitnexus analyze` drops next to the
+// index (#1945). Referenced by docs so a single CLI-neutral command resolves
+// the available runner (global `gitnexus` → `pnpm dlx` → `npx`) at call time.
+runnerPath = '.gitnexus/run.cjs') {
     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\` |`)
@@ -93,12 +97,20 @@ function generateGitNexusContent(projectName, stats, generatedSkills, groupNames
 |------|---------------------|
 ${tableBody}`
         : '';
+    // Docs reference the project-local runner `gitnexus analyze` writes (#1945):
+    // a single, CLI-neutral, machine-independent command (no per-machine churn,
+    // #1706) that auto-selects the available runner at call time. Kept terse to
+    // stay under the CLAUDE.md block token budget (#856); the cli skill carries the
+    // full bootstrap + npm-11 fallback (`node.target is null` npx install crash).
+    const runner = `node ${runnerPath}`;
+    const bootstrapNote = `No \`${runnerPath}\` yet? \`npx gitnexus analyze\` ` +
+        '(npm 11 crash → `npm i -g gitnexus`; #1939).';
     return `${GITNEXUS_START_MARKER}
 # GitNexus — Code Intelligence
 
 This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
-> If any GitNexus tool warns the index is stale, run \`npx gitnexus analyze\` in terminal first.
+> Index stale? Run \`${runner} analyze\` from the project root — it auto-selects an available runner. ${bootstrapNote}
 
 ## Always Do
 
@@ -127,7 +139,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
 
-This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the project root: \`${runner} group list\`, \`${runner} group sync <name>\`, \`${runner} group impact <name> --target <symbol> --repo <group-path>\` (the \`${runnerPath}\` path is repo-root-relative).
 
 `
         : ''}${skillsTable
@@ -302,9 +314,24 @@ Use GitNexus tools to accomplish this task.
 /**
  * Generate AI context files after indexing
  */
-export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills, options) {
+export async function generateAIContextFiles(repoPath, storagePath, projectName, stats, generatedSkills, options) {
     const groupNames = await findGroupsContainingRegistryName(projectName);
-    const content = generateGitNexusContent(projectName, stats, generatedSkills, groupNames, options?.noStats, options?.skipSkills);
+    // Drop a project-local runner next to the index (#1945) so the generated docs
+    // can reference one CLI-neutral command that resolves the available runner at
+    // call time. It is a copy of the canonical self-contained resolver, which the
+    // CLI and hooks already share; failure to copy is non-fatal (docs carry a
+    // bootstrap fallback). `runnerPath` is project-relative with POSIX separators
+    // so the emitted command is identical across platforms.
+    const runnerPath = path.relative(repoPath, path.join(storagePath, 'run.cjs')).replace(/\\/g, '/');
+    try {
+        const runnerSrc = path.join(__dirname, '..', '..', 'hooks', 'claude', 'resolve-analyze-cmd.cjs');
+        await fs.mkdir(storagePath, { recursive: true });
+        await fs.copyFile(runnerSrc, path.join(storagePath, 'run.cjs'));
+    }
+    catch (err) {
+        logger.warn(`Could not write GitNexus runner to ${runnerPath}: ${String(err)}`);
+    }
+    const content = generateGitNexusContent(projectName, stats, generatedSkills, groupNames, options?.noStats, options?.skipSkills, runnerPath);
     const createdFiles = [];
     if (!options?.skipAgentsMd) {
         // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)

package/dist/cli/analyze.js

@@ -23,6 +23,7 @@ import fs from 'fs/promises';
 import { cliError } from './cli-message.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.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
 // fatal handlers below MUST reach the user even when the analyze path
@@ -433,6 +434,10 @@ export const analyzeCommand = async (inputPath, options) => {
     // async error that escapes the try/catch below (#1169) surfaces with
     // a stack trace and a non-zero exit code instead of a silent exit 0.
     installFatalHandlers();
+    // npm-11 npx-crash nudge (#1939). Runs here, after the heap re-exec guard,
+    // so it fires once in the working process and never on the lazy-startup path
+    // of other commands (e.g. `gitnexus mcp`).
+    warnIfNpm11NpxRisk();
     // Snapshot the GITNEXUS_* env vars that the impl writes for downstream
     // consumption, so they don't leak across `analyzeCommand` invocations in
     // programmatic callers (tests, long-running hosts). `process.exit(0)` on

package/dist/cli/resolve-invocation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * npm 11.x npx-install-crash nudge for the `analyze` command (#1939).
+ *
+ * The gitnexus/pnpm/npx selection itself lives in the canonical hook helper
+ * (hooks/claude/resolve-analyze-cmd.cjs) — self-contained CJS because the copied
+ * hook runtime cannot import from the package. We reuse it here via createRequire
+ * instead of re-implementing it, so there is one source of truth for the
+ * invocation decision. This module adds only the npm-version probe and the
+ * warning, which are CLI-only. The relative path resolves identically from
+ * src/cli/ (tsx, vitest) and dist/cli/ (shipped), since both sit one level under
+ * the package root and `hooks/` is published.
+ */
+declare const NPX_REF: string;
+export { NPX_REF };
+export declare function getNpmMajorVersion(): number | null;
+/**
+ * One-line stderr nudge when an npm 11+ user is on the npx install path (#1939).
+ * Skipped when a global `gitnexus` or `pnpm` is already preferred, so it never
+ * nags users who are not exposed to the npx/arborist crash.
+ */
+export declare function warnIfNpm11NpxRisk(): void;

package/dist/cli/resolve-invocation.js

@@ -0,0 +1,68 @@
+/**
+ * npm 11.x npx-install-crash nudge for the `analyze` command (#1939).
+ *
+ * The gitnexus/pnpm/npx selection itself lives in the canonical hook helper
+ * (hooks/claude/resolve-analyze-cmd.cjs) — self-contained CJS because the copied
+ * hook runtime cannot import from the package. We reuse it here via createRequire
+ * instead of re-implementing it, so there is one source of truth for the
+ * invocation decision. This module adds only the npm-version probe and the
+ * warning, which are CLI-only. The relative path resolves identically from
+ * src/cli/ (tsx, vitest) and dist/cli/ (shipped), since both sit one level under
+ * the package root and `hooks/` is published.
+ */
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+const { resolveInvocationMode, formatDocumentationDlxCommand, NPX_REF } = createRequire(import.meta.url)('../../hooks/claude/resolve-analyze-cmd.cjs');
+// Fail loud at module load if the canonical cjs export shape drifts (e.g. a
+// renamed export), rather than as a late TypeError inside warnIfNpm11NpxRisk.
+if (typeof resolveInvocationMode !== 'function' ||
+    typeof formatDocumentationDlxCommand !== 'function' ||
+    typeof NPX_REF !== 'string') {
+    throw new Error('resolve-analyze-cmd.cjs must export resolveInvocationMode (function), formatDocumentationDlxCommand (function), and NPX_REF (string)');
+}
+export { NPX_REF };
+// Re-implemented here (rather than reusing the cjs export) so vitest's
+// `vi.mock('node:child_process')` intercepts it — the cjs uses bare
+// `require('child_process')`, which the mock cannot reach. Timeout matches the
+// cjs PROBE_TIMEOUT_MS (1s) so this CLI probe shares the same hook-budget cap;
+// `npm --version` is a sub-second local call.
+export function getNpmMajorVersion() {
+    try {
+        const output = execFileSync('npm', ['--version'], {
+            encoding: 'utf-8',
+            timeout: 1000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            // Windows `npm` is a `.cmd` shim; without a shell execFileSync ENOENTs
+            // (CVE-2024-27980) and the npm-11 npx-crash warning below would never
+            // fire on Windows. Mirrors probeVersion in resolve-analyze-cmd.cjs.
+            shell: process.platform === 'win32',
+        });
+        // Read the first version-shaped line so a Corepack/update banner on stdout
+        // doesn't defeat the parse (mirrors the cjs probeVersion hardening).
+        const major = output
+            .split('\n')
+            .map((l) => l.trim())
+            .find((l) => /^v?\d+\./.test(l))
+            ?.match(/^v?(\d+)\./);
+        return major ? Number(major[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One-line stderr nudge when an npm 11+ user is on the npx install path (#1939).
+ * Skipped when a global `gitnexus` or `pnpm` is already preferred, so it never
+ * nags users who are not exposed to the npx/arborist crash.
+ */
+export function warnIfNpm11NpxRisk() {
+    if (resolveInvocationMode() !== 'npx')
+        return;
+    const major = getNpmMajorVersion();
+    if (major === null || major < 11)
+        return;
+    process.stderr.write(`Warning: npm ${major}.x can crash while installing gitnexus via npx ` +
+        `(npm/arborist "node.target is null"). Prefer: ${formatDocumentationDlxCommand('analyze')} ` +
+        `or npm install -g ${NPX_REF}. See https://github.com/abhigyanpatwari/GitNexus/issues/1939\n`);
+}

package/dist/cli/setup.d.ts

@@ -5,4 +5,37 @@
  * Detects installed AI editors and writes the appropriate MCP config
  * so the GitNexus MCP server is available in all projects.
  */
+/**
+ * Build the `command` string written into an editor's hook settings, which the
+ * editor shell-evaluates. `hookPath` is already forward-slash-normalized.
+ *
+ * On POSIX, single-quote the path: a single-quoted shell string expands nothing,
+ * so spaces and metacharacters ($, backtick, ;, |, &, newline, parens) in the
+ * install path cannot run as commands. The only character needing escaping
+ * inside single quotes is the single quote, via the standard `'\''` idiom
+ * (close, literal-quote, reopen). The previous double-quoted `node "..."` form
+ * left $/backtick live — a code-execution risk for an adversarial $HOME.
+ *
+ * On Windows, filenames cannot contain these POSIX metacharacters and the path
+ * is forward-slashed, so keep the double-quoted form with backslash-then-quote
+ * escaping (CodeQL js/incomplete-sanitization safe ordering).
+ */
+export declare function formatHookCommand(hookPath: string, isWindows?: boolean): string;
+interface SetupResult {
+    configured: string[];
+    skipped: string[];
+    errors: string[];
+}
+/**
+ * Copy the shared hook helpers from `srcDir` into `destDir`. The adapters
+ * top-level `require()` the `.cjs` helpers, so a missing required helper makes
+ * the installed hook crash with MODULE_NOT_FOUND. A failed copy is recorded as a
+ * setup error, and the names of any failed REQUIRED helpers are returned so the
+ * caller can fail closed (skip hook registration) instead of registering a hook
+ * that crashes at runtime. `win-rm-list-json.ps1` is best-effort — its absence is
+ * recorded but does not gate registration. Both the Claude and Antigravity
+ * install paths copy this same list from hooks/claude/ (the canonical source).
+ */
+export declare function copyHookHelpers(srcDir: string, destDir: string, label: string, result: SetupResult): Promise<string[]>;
 export declare const setupCommand: () => Promise<void>;
+export {};

package/dist/cli/setup.js

@@ -28,7 +28,38 @@ const _pkg = _require('../../package.json');
 if (typeof _pkg.version !== 'string' || !_pkg.version) {
     throw new Error('gitnexus/package.json#version is missing or not a string — cannot generate MCP fallback config.');
 }
-const NPX_REF = `gitnexus@${_pkg.version}`;
+// Version-pinned ref for the persisted MCP entry — deliberately distinct from
+// the cjs's exported `gitnexus@latest` hint ref (resolve-analyze-cmd.cjs); the
+// two are not unified (see the comment above and that file's MCP_PINNED_REF).
+const MCP_PINNED_REF = `gitnexus@${_pkg.version}`;
+/**
+ * Build the `command` string written into an editor's hook settings, which the
+ * editor shell-evaluates. `hookPath` is already forward-slash-normalized.
+ *
+ * On POSIX, single-quote the path: a single-quoted shell string expands nothing,
+ * so spaces and metacharacters ($, backtick, ;, |, &, newline, parens) in the
+ * install path cannot run as commands. The only character needing escaping
+ * inside single quotes is the single quote, via the standard `'\''` idiom
+ * (close, literal-quote, reopen). The previous double-quoted `node "..."` form
+ * left $/backtick live — a code-execution risk for an adversarial $HOME.
+ *
+ * On Windows, filenames cannot contain these POSIX metacharacters and the path
+ * is forward-slashed, so keep the double-quoted form with backslash-then-quote
+ * escaping (CodeQL js/incomplete-sanitization safe ordering).
+ */
+export function formatHookCommand(hookPath, isWindows = process.platform === 'win32') {
+    if (isWindows) {
+        const escaped = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `node "${escaped}"`;
+    }
+    return `node '${hookPath.replace(/'/g, "'\\''")}'`;
+}
+// The exact source line each hook adapter ships, rewritten at install time to
+// point cliPath at the installed CLI. Kept as a named constant so the install
+// patch and its drift guard reference one string — if the adapter source ever
+// changes this literal, the guard records an actionable error instead of
+// silently shipping a hook with an unresolved relative cliPath.
+const CLI_PATH_SOURCE_LITERAL = "let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');";
 /**
  * Resolve the absolute path to the `gitnexus` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -83,12 +114,12 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],
+            args: ['/c', 'npx', '-y', MCP_PINNED_REF, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', NPX_REF, 'mcp'],
+        args: ['-y', MCP_PINNED_REF, 'mcp'],
     };
 }
 /**
@@ -101,9 +132,9 @@ function getOpenCodeMcpEntry() {
         return { type: 'local', command: [bin, 'mcp'] };
     }
     if (process.platform === 'win32') {
-        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', NPX_REF, 'mcp'] };
+        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', MCP_PINNED_REF, 'mcp'] };
     }
-    return { type: 'local', command: ['npx', '-y', NPX_REF, 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', MCP_PINNED_REF, 'mcp'] };
 }
 /**
  * Detect indentation style from file content.
@@ -281,6 +312,42 @@ async function mergeHooksJsonc(filePath, entries) {
     await fs.writeFile(filePath, current, 'utf-8');
     return true;
 }
+const HOOK_HELPERS = [
+    'hook-lock.cjs',
+    'hook-db-lock-probe.cjs',
+    'win-rm-list-json.ps1',
+    'resolve-analyze-cmd.cjs',
+];
+// win-rm-list-json.ps1 is best-effort: it is read (not require()'d) by
+// hook-db-lock-probe.cjs only on Windows, and that probe fails open when the
+// script is absent. Every other helper is top-level require()'d by the adapters,
+// so its absence crashes the installed hook — those are the ones a failed copy
+// must gate hook registration on (see copyHookHelpers' return value).
+const BEST_EFFORT_HOOK_HELPERS = new Set(['win-rm-list-json.ps1']);
+/**
+ * Copy the shared hook helpers from `srcDir` into `destDir`. The adapters
+ * top-level `require()` the `.cjs` helpers, so a missing required helper makes
+ * the installed hook crash with MODULE_NOT_FOUND. A failed copy is recorded as a
+ * setup error, and the names of any failed REQUIRED helpers are returned so the
+ * caller can fail closed (skip hook registration) instead of registering a hook
+ * that crashes at runtime. `win-rm-list-json.ps1` is best-effort — its absence is
+ * recorded but does not gate registration. Both the Claude and Antigravity
+ * install paths copy this same list from hooks/claude/ (the canonical source).
+ */
+export async function copyHookHelpers(srcDir, destDir, label, result) {
+    const failedRequired = [];
+    for (const helper of HOOK_HELPERS) {
+        try {
+            await fs.copyFile(path.join(srcDir, helper), path.join(destDir, helper));
+        }
+        catch {
+            result.errors.push(`${label}: failed to copy ${helper} — hook may crash at runtime`);
+            if (!BEST_EFFORT_HOOK_HELPERS.has(helper))
+                failedRequired.push(helper);
+        }
+    }
+    return failedRequired;
+}
 /**
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
  * Merges hook config without overwriting existing hooks, preserving
@@ -304,37 +371,32 @@ async function installClaudeCodeHooks(result) {
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
-            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            if (!content.includes(CLI_PATH_SOURCE_LITERAL)) {
+                result.errors.push('Claude Code hooks: gitnexus-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.');
+            }
+            content = content.replace(CLI_PATH_SOURCE_LITERAL, `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
             // Script not found in source — skip
         }
+        // Fail closed: registering the hook without its adapter would crash on every
+        // tool invocation. Mirrors the Antigravity adapter guard below (this path
+        // previously registered regardless of whether the adapter wrote).
         try {
-            await fs.copyFile(path.join(pluginHooksPath, 'hook-lock.cjs'), path.join(destHooksDir, 'hook-lock.cjs'));
+            await fs.access(dest);
         }
         catch {
-            // Helper not found in source — skip
-        }
-        try {
-            await fs.copyFile(path.join(pluginHooksPath, 'hook-db-lock-probe.cjs'), path.join(destHooksDir, 'hook-db-lock-probe.cjs'));
-        }
-        catch {
-            // Helper not found in source — skip
-        }
-        try {
-            await fs.copyFile(path.join(pluginHooksPath, 'win-rm-list-json.ps1'), path.join(destHooksDir, 'win-rm-list-json.ps1'));
+            result.errors.push('Claude Code hooks: adapter script was not installed — skipping hook registration');
+            return;
         }
-        catch {
-            // Helper not found in source — skip
+        const failedRequired = await copyHookHelpers(pluginHooksPath, destHooksDir, 'Claude Code hooks', result);
+        if (failedRequired.length > 0) {
+            result.errors.push(`Claude Code hooks: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
+            return;
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
-        // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
-        // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`
-        // become `path\with\"quote`, where the trailing `\` before `"` could
-        // unescape the quote inside the surrounding double-quoted shell context.
-        const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const hookCmd = `node "${escapedHookPath}"`;
+        const hookCmd = formatHookCommand(hookPath);
         // Check which hook events need entries (idempotent: skip if already registered)
         const parsed = await (async () => {
             try {
@@ -483,7 +545,10 @@ async function installAntigravityHooks(result) {
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
-            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            if (!content.includes(CLI_PATH_SOURCE_LITERAL)) {
+                result.errors.push('Antigravity hooks: gitnexus-antigravity-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.');
+            }
+            content = content.replace(CLI_PATH_SOURCE_LITERAL, `let cliPath = ${jsonCli};`);
             await fs.writeFile(adapterDest, content, 'utf-8');
         }
         catch {
@@ -503,17 +568,13 @@ async function installAntigravityHooks(result) {
         // required by hook-db-lock-probe.cjs on Windows — without it, the MCP
         // server ownership probe silently fails open and the hook may contend
         // with the MCP server on the LadybugDB.
-        for (const helper of ['hook-lock.cjs', 'hook-db-lock-probe.cjs', 'win-rm-list-json.ps1']) {
-            try {
-                await fs.copyFile(path.join(pluginClaudeDir, helper), path.join(destHooksDir, helper));
-            }
-            catch {
-                result.errors.push(`Antigravity hooks: failed to copy ${helper} — hook may crash at runtime`);
-            }
+        const failedRequired = await copyHookHelpers(pluginClaudeDir, destHooksDir, 'Antigravity hooks', result);
+        if (failedRequired.length > 0) {
+            result.errors.push(`Antigravity hooks: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
+            return;
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-antigravity-hook.cjs').replace(/\\/g, '/');
-        const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const hookCmd = `node "${escapedHookPath}"`;
+        const hookCmd = formatHookCommand(hookPath);
         const parsed = await (async () => {
             try {
                 const r = await fs.readFile(settingsPath, 'utf-8');

package/dist/core/ingestion/languages/python/query.js

@@ -11,11 +11,35 @@ const PYTHON_SCOPE_QUERY = `
 (module) @scope.module
 (class_definition) @scope.class
 (function_definition) @scope.function
+(lambda) @scope.function
 
 ;; Declarations
 (class_definition
   name: (identifier) @declaration.name) @declaration.class
 
+;; Heritage — bare identifier
+;; NOTE: captures.ts on main already synthesizes @reference.inherits for
+;; qualified bases via #1951/#1956. These @heritage.* patterns are redundant
+;; with that synthesis but kept as documentation and a safety net for the
+;; generic heritage extractor path. They produce topicOf edges that the
+;; resolution pipeline ignores when the synthesis path wins.
+(class_definition
+  name: (identifier) @heritage.class
+  superclasses: (argument_list
+    (identifier) @heritage.extends)) @heritage
+
+;; Heritage — qualified base (module.Class)
+(class_definition
+  name: (identifier) @heritage.class
+  superclasses: (argument_list
+    (attribute) @heritage.extends)) @heritage
+
+;; Heritage — subscripted/generic base (Generic[T])
+(class_definition
+  name: (identifier) @heritage.class
+  superclasses: (argument_list
+    (subscript) @heritage.extends)) @heritage
+
 (function_definition
   name: (identifier) @declaration.name) @declaration.function
 
@@ -232,6 +256,22 @@ const PYTHON_SCOPE_QUERY = `
   name: (identifier) @type-binding.name
   return_type: (type) @type-binding.type) @type-binding.return
 
+;; Decorators — simple @decorator
+(decorator
+  (identifier) @reference.name) @reference.call.free
+
+;; Decorators — @obj.decorator (single attribute, identifier receiver)
+(decorator
+  (attribute
+    object: (identifier) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
+;; Decorators — @a.b.decorator (nested attributes)
+(decorator
+  (attribute
+    object: (attribute) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
 ;; References — calls
 (call
   function: (identifier) @reference.name) @reference.call.free

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -25,6 +25,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
 const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 function readInput() {
   try {
@@ -315,7 +316,7 @@ function buildStaleIndexHint(gitNexusDir, cwd) {
 
   if (currentHead === lastCommit) return '';
 
-  const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
   return (
     `[GitNexus] index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
     `Run \`${analyzeCmd}\` to refresh the knowledge graph.`

package/hooks/claude/gitnexus-hook.cjs

@@ -16,6 +16,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
 const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -340,7 +341,7 @@ function handlePostToolUse(input) {
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
-  const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
   sendHookResponse(
     'PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +

package/hooks/claude/resolve-analyze-cmd.cjs

@@ -0,0 +1,295 @@
+/**
+ * Single source of truth for how docs, hooks, and warnings invoke gitnexus.
+ *
+ * Automatically selects a working invocation path:
+ * 1. Global `gitnexus` on PATH (best — no install step)
+ * 2. npm 11+ with pnpm on PATH → `pnpm --allow-build=… dlx` (avoids the npx
+ *    arborist crash *and* pnpm 10+ ignored-build-script failures, #1939)
+ * 3. npm < 11 with npm on PATH → `npx` (works; simpler than pnpm dlx)
+ * 4. pnpm-only → `pnpm --allow-build=… dlx`
+ * 5. Last resort → `npx` (warned on npm 11+ from analyze.ts)
+ *
+ * The `--allow-build` flags MUST precede the `dlx` token. pnpm < 10.14 keeps
+ * `dlx` in its argv escape list, so flags placed *after* `dlx` are parsed as
+ * package specs (ERR_PNPM_SPEC_NOT_SUPPORTED). The pre-`dlx` position parses
+ * into dlx's allow-build option and has been honored since pnpm 10.2.0 (#1939).
+ *
+ * This stays self-contained CJS because the Claude/Antigravity hooks run as
+ * standalone files copied into the user's hook dir, where no package import is
+ * available. The CLI reuses this module from src/cli/resolve-invocation.ts via
+ * createRequire rather than re-implementing it. Two committed copies must stay
+ * byte-identical (enforced by resolve-invocation.test.ts) — edit both together:
+ * gitnexus/hooks/claude/ (the canonical copy the CLI and `gitnexus setup` read)
+ * and gitnexus-claude-plugin/hooks/. A THIRD copy is written at runtime to
+ * `<repo>/.gitnexus/run.cjs` by `gitnexus analyze` (ai-context.ts) so docs can
+ * reference it directly via the `require.main === module` exec tail below; that
+ * copy is gitignored and refreshed on every analyze, so it cannot drift for long.
+ */
+
+const { execFileSync } = require('child_process');
+
+const NPX_REF = 'gitnexus@latest';
+
+// Native packages whose postinstall must run under pnpm 10+ (blocked by default).
+const PNPM_ALLOW_BUILD_BASE = ['@ladybugdb/core', 'gitnexus', 'tree-sitter'];
+const PNPM_ALLOW_BUILD_EMBEDDINGS = ['onnxruntime-node'];
+
+// Probe timeout, kept under Claude Code's 10s hook budget. In a linked worktree
+// the stale-index hook first runs `git rev-parse --git-common-dir` (~2s) and
+// `git rev-parse HEAD` (~3s); the pnpm path then adds up to four 1s probes
+// (which gitnexus, npm --version, which pnpm, pnpm --version), so the worst case
+// is ~9s — within budget but tight. A healthy `which`/`where`/`--version`
+// returns in well under a second, so the realistic cost is far lower.
+const PROBE_TIMEOUT_MS = 1000;
+
+/**
+ * Pick the best match from `where`/`which` output. A global `gitnexus` may be a
+ * `.cmd`/`.bat` (npm), a `.exe`, or an extensionless shim (Volta, scoop), so on
+ * Windows we prefer a recognized executable extension but accept any hit — the
+ * emitted hint is `gitnexus analyze` regardless of which shim resolves it. Pure
+ * and exported so the shim-matching can be unit-tested without spawning.
+ */
+function pickPathMatch(output, { isWin, gitnexusWrapper } = {}) {
+  const lines = output
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (isWin && gitnexusWrapper) {
+    return lines.find((l) => /\.(cmd|bat|exe)$/i.test(l)) || lines[0] || null;
+  }
+  return lines[0] || null;
+}
+
+/** Absolute path to `command` on PATH, or null. `gitnexusWrapper` enables the Windows shim match. */
+function resolveOnPath(command, gitnexusWrapper = false) {
+  const isWin = process.platform === 'win32';
+  try {
+    const output = execFileSync(isWin ? 'where' : 'which', [command], {
+      encoding: 'utf-8',
+      timeout: PROBE_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    return pickPathMatch(output, { isWin, gitnexusWrapper });
+  } catch {
+    return null;
+  }
+}
+
+// One spawn of `<command> --version` → { major, minor } (each null when
+// unreadable). Version injection happens at the resolver seam (getNpmMajorVersion
+// / formatPnpmAllowBuildArgs), so this stays a pure real-process probe.
+function probeVersion(command) {
+  try {
+    const output = execFileSync(command, ['--version'], {
+      encoding: 'utf-8',
+      timeout: PROBE_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      // On Windows, npm/pnpm resolve to `.cmd` shims; execFileSync does no
+      // PATHEXT resolution and Node refuses to spawn `.cmd`/`.bat` without a
+      // shell (CVE-2024-27980), so a bare `<command> --version` ENOENTs and the
+      // probe would wrongly report a present tool as absent. A shell lets the OS
+      // resolve the shim. POSIX needs no shell (direct PATH lookup works).
+      shell: process.platform === 'win32',
+    });
+    // Find the first line that starts with a version token (`MAJOR.MINOR`,
+    // optional `v` prefix) rather than splitting the whole output — pnpm/npm
+    // under Corepack or with an update notice can print a banner line on stdout
+    // before the version (stderr is already dropped via the stdio config).
+    const versionLine = output
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => /^v?\d+\.\d+/.test(l));
+    const match = versionLine ? versionLine.match(/^v?(\d+)\.(\d+)/) : null;
+    return {
+      major: match ? Number(match[1]) : null,
+      minor: match ? Number(match[2]) : null,
+    };
+  } catch {
+    return { major: null, minor: null };
+  }
+}
+
+// `deps` is the single injection seam: an explicitly provided key — including a
+// `null` value, detected via `in` — is honored as-is so tests can simulate an
+// absent tool without spawning; an absent key falls through to the real probe.
+function getNpmMajorVersion(deps = {}) {
+  return 'npmMajor' in deps ? deps.npmMajor : probeVersion('npm').major;
+}
+
+/**
+ * `--allow-build` flags for the pre-`dlx` position. Emitted for pnpm >= 10.2
+ * (where the flag exists, and pnpm 10+ blocks build scripts by default). Omitted
+ * below 10.2: pnpm < 10 runs build scripts anyway, and pnpm 10.0/10.1 lack the
+ * flag (it would be rejected as an unknown option). `alwaysAllowBuild` forces the
+ * flags for committed documentation, which cannot probe the reader's pnpm.
+ */
+function formatPnpmAllowBuildArgs(options = {}, deps = {}) {
+  if (!options.alwaysAllowBuild) {
+    const { major, minor } =
+      'pnpmMajor' in deps
+        ? { major: deps.pnpmMajor, minor: 'pnpmMinor' in deps ? deps.pnpmMinor : null }
+        : probeVersion('pnpm');
+    const lacksAllowBuild =
+      major !== null && (major < 10 || (major === 10 && minor !== null && minor < 2));
+    if (lacksAllowBuild) return [];
+  }
+  const pkgs = [...PNPM_ALLOW_BUILD_BASE];
+  if (options.embeddings) pkgs.push(...PNPM_ALLOW_BUILD_EMBEDDINGS);
+  return pkgs.map((p) => `--allow-build=${p}`);
+}
+
+/** Fixed install-free command for committed AGENTS.md / SKILL.md (pnpm >= 10.2). */
+function formatDocumentationDlxCommand(gitnexusArgs, options = {}) {
+  const flags = formatPnpmAllowBuildArgs({ ...options, alwaysAllowBuild: true }).join(' ');
+  const prefix = flags ? `${flags} ` : '';
+  return `pnpm ${prefix}dlx ${NPX_REF} ${gitnexusArgs}`;
+}
+
+/**
+ * Resolve `gitnexus` | `pnpm` | `npx`. `GITNEXUS_INVOCATION` forces a mode
+ * (test/escape hatch). `probe` is injectable so the preference order can be
+ * unit-tested without spawning; it defaults to the real PATH probe. `deps` can
+ * inject `{ npmMajor, pnpmMajor }` for tests.
+ */
+function resolveInvocationMode(probe = resolveOnPath, deps = {}) {
+  const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
+  if (forced === 'gitnexus' || forced === 'pnpm' || forced === 'npx') {
+    return forced;
+  }
+  if (probe('gitnexus', true)) return 'gitnexus';
+
+  const npmMajor = getNpmMajorVersion(deps);
+  // pnpm presence: prefer an explicit `pnpmPresent` flag (set by
+  // formatAnalyzeCommand, which falls back to a PATH probe when the version is
+  // unreadable) so a present-but-unparseable pnpm — slow probe, Corepack
+  // banner — still selects pnpm instead of the npx crash path. Otherwise an
+  // injected version (a successful `pnpm --version` proves presence)
+  // short-circuits the `which pnpm` probe; failing both, fall back to PATH.
+  const hasPnpm =
+    'pnpmPresent' in deps
+      ? deps.pnpmPresent
+      : 'pnpmMajor' in deps
+        ? deps.pnpmMajor !== null
+        : Boolean(probe('pnpm'));
+
+  // npm 11+ npx install crash (#1939) — prefer pnpm dlx when available.
+  if (hasPnpm && npmMajor !== null && npmMajor >= 11) return 'pnpm';
+  // npm 10 and earlier: npx works; prefer it over pnpm dlx when npm is present.
+  if (npmMajor !== null && npmMajor < 11) return 'npx';
+  // npm absent or unreadable — use pnpm if present (with allow-build flags).
+  if (hasPnpm) return 'pnpm';
+
+  return 'npx';
+}
+
+function formatPnpmDlxCommand(gitnexusArgs, options = {}, deps = {}) {
+  const flags = formatPnpmAllowBuildArgs(options, deps).join(' ');
+  const prefix = flags ? `${flags} ` : '';
+  return `pnpm ${prefix}dlx ${NPX_REF} ${gitnexusArgs}`;
+}
+
+function formatAnalyzeCommand(options = {}, deps = {}) {
+  const suffix = options.embeddings ? ' --embeddings' : '';
+  // Keep the stale-index hook budget tight by querying each tool at most once.
+  // A memoized PATH probe is shared with resolveInvocationMode (so `gitnexus`
+  // isn't probed twice), and pnpm's version is captured by a single
+  // `pnpm --version` that proves both presence (for mode resolution) and
+  // version (for the allow-build gate) — replacing the former `which pnpm` +
+  // `pnpm --version` double spawn. Injected deps (tests) and forced/global
+  // modes skip the pnpm probe.
+  const cache = new Map();
+  const probe = (command, gitnexusWrapper) => {
+    const key = `${command}:${gitnexusWrapper ? 1 : 0}`;
+    if (!cache.has(key)) cache.set(key, resolveOnPath(command, gitnexusWrapper));
+    return cache.get(key);
+  };
+  let resolved = deps;
+  if (!('pnpmMajor' in deps)) {
+    const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
+    // pnpm is only consulted when no non-pnpm mode is already certain: forced
+    // gitnexus/npx never use pnpm, and a present global gitnexus wins outright.
+    const mightUsePnpm = forced === 'pnpm' || (forced !== 'gitnexus' && forced !== 'npx');
+    if (mightUsePnpm && (forced === 'pnpm' || !probe('gitnexus', true))) {
+      const { major, minor } = probeVersion('pnpm');
+      // Carry presence separately from version: when the version probe fails
+      // (timeout, Corepack banner) but pnpm is on PATH, still treat it as
+      // present so mode resolution picks pnpm over the npx crash path. The
+      // PATH probe is memoized and only runs when the version is unreadable.
+      const pnpmPresent = major !== null || Boolean(probe('pnpm'));
+      resolved = { ...deps, pnpmMajor: major, pnpmMinor: minor, pnpmPresent };
+    }
+  }
+  const mode = resolveInvocationMode(probe, resolved);
+  if (mode === 'gitnexus') return `gitnexus analyze${suffix}`;
+  if (mode === 'pnpm') return `${formatPnpmDlxCommand(`analyze${suffix}`, options, resolved)}`;
+  return `npx ${NPX_REF} analyze${suffix}`;
+}
+
+/**
+ * Resolve `mode` into a concrete { program, args } pair for a set of gitnexus
+ * subcommand arguments. Shared by the direct-exec entrypoint below; pure (no
+ * spawn) so it is unit-testable. `--embeddings` widens the pnpm allow-build set.
+ */
+function buildRunnerArgv(mode, gitnexusArgs, deps = {}) {
+  // Match both the space form (`--embeddings`) and the equals form
+  // (`--embeddings=5000`) Commander accepts, so the pnpm allow-build set still
+  // widens to onnxruntime-node when a user hand-types the equals form.
+  const embeddings = gitnexusArgs.some(
+    (a) => a === '--embeddings' || a.startsWith('--embeddings='),
+  );
+  if (mode === 'gitnexus') return { program: 'gitnexus', args: [...gitnexusArgs] };
+  if (mode === 'pnpm') {
+    return {
+      program: 'pnpm',
+      args: [...formatPnpmAllowBuildArgs({ embeddings }, deps), 'dlx', NPX_REF, ...gitnexusArgs],
+    };
+  }
+  return { program: 'npx', args: [NPX_REF, ...gitnexusArgs] };
+}
+
+module.exports = {
+  formatAnalyzeCommand,
+  formatDocumentationDlxCommand,
+  formatPnpmAllowBuildArgs,
+  formatPnpmDlxCommand,
+  resolveInvocationMode,
+  buildRunnerArgv,
+  pickPathMatch,
+  getNpmMajorVersion,
+  NPX_REF,
+  PNPM_ALLOW_BUILD_BASE,
+};
+
+// Direct-exec entrypoint (#1945): `node run.cjs <gitnexus args…>` resolves the
+// best available runner (global `gitnexus` → `pnpm dlx` → `npx`) at call time and
+// runs it, inheriting stdio and propagating the child's exit code. This lets the
+// committed skills and generated AGENTS.md/CLAUDE.md reference ONE stable,
+// CLI-neutral command without baking in a package-manager assumption. `gitnexus
+// analyze` drops a copy of this file at `.gitnexus/run.cjs`. Skipped on require()
+// (the CLI and tests reuse the exports above), so it runs only when invoked as a
+// script.
+if (require.main === module) {
+  const gitnexusArgs = process.argv.slice(2);
+  const { program, args } = buildRunnerArgv(resolveInvocationMode(), gitnexusArgs);
+  try {
+    execFileSync(program, args, {
+      stdio: 'inherit',
+      windowsHide: true,
+      // On Windows, `npx`/`pnpm`/`gitnexus` resolve to `.cmd`/`.ps1`/`.exe`
+      // shims (npm, Volta, Corepack, scoop). execFileSync does not do PATHEXT
+      // resolution and Node refuses to spawn `.cmd`/`.bat` without a shell
+      // (CVE-2024-27980), so a bare program name ENOENTs. A shell lets the OS
+      // resolve the shim; POSIX needs no shell (direct PATH lookup works).
+      shell: process.platform === 'win32',
+    });
+  } catch (err) {
+    // Make spawn failures (resolved program absent from PATH) self-explanatory
+    // instead of a silent exit 1, then propagate the runner's own exit code.
+    if (typeof err.status !== 'number') {
+      process.stderr.write(`gitnexus runner: could not launch \`${program}\` — ${err.message}\n`);
+    }
+    process.exit(typeof err.status === 'number' ? err.status : 1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.113",
+  "version": "1.6.6-rc.115",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/scripts/cross-platform-tests.ts

@@ -30,6 +30,7 @@ const PLATFORM_LOGIC = [
   'test/unit/setup-jsonc.test.ts',
   'test/unit/setup-codex.test.ts',
   'test/unit/setup-antigravity.test.ts',
+  'test/unit/resolve-invocation.test.ts',
   'test/unit/platform-capabilities.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
   'test/unit/lbug-pool-win-fts-probe.test.ts',
@@ -84,6 +85,7 @@ const SPAWN_CLI = [
   'test/integration/setup-antigravity.test.ts',
   'test/integration/antigravity-hook-e2e.test.ts',
   'test/unit/local-cli-subprocess.test.ts',
+  'test/unit/runner-exec-tail.test.ts',
 ];
 
 // Worker threads tests — exercise real worker_threads which have

package/skills/gitnexus-cli.md

@@ -5,14 +5,16 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-All commands work via `npx` — no global install required.
+Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required.
+
+> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
 
 ## Commands
 
 ### analyze — Build or refresh the index
 
 ```bash
-npx gitnexus analyze
+node .gitnexus/run.cjs analyze
 ```
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
@@ -28,7 +30,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 ### status — Check index freshness
 
 ```bash
-npx gitnexus status
+node .gitnexus/run.cjs status
 ```
 
 Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
@@ -36,7 +38,7 @@ Shows whether the current repo has a GitNexus index, when it was last updated, a
 ### clean — Delete the index
 
 ```bash
-npx gitnexus clean
+node .gitnexus/run.cjs clean
 ```
 
 Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
@@ -49,7 +51,7 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
 ### wiki — Generate documentation from the graph
 
 ```bash
-npx gitnexus wiki
+node .gitnexus/run.cjs wiki
 ```
 
 Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
@@ -66,7 +68,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 ### list — Show all indexed repos
 
 ```bash
-npx gitnexus list
+node .gitnexus/run.cjs list
 ```
 
 Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.

package/skills/gitnexus-debugging.md

@@ -22,7 +22,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 

package/skills/gitnexus-exploring.md

@@ -23,7 +23,7 @@ description: "Use when the user asks how code works, wants to understand archite
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 

package/skills/gitnexus-guide.md

@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+> If step 1 warns the index is stale, run `node .gitnexus/run.cjs analyze` in the terminal first.
 
 ## Skills
 

package/skills/gitnexus-impact-analysis.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to know what will break if they change som
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 

package/skills/gitnexus-pr-review.md

@@ -26,7 +26,7 @@ description: "Use when the user wants to review a pull request, understand what
 6. Summarize findings with risk assessment
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal before reviewing.
 
 ## Checklist
 

package/skills/gitnexus-refactoring.md

@@ -22,7 +22,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 4. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklists