agentic-qe 3.8.14 → 3.9.1

package/dist/hooks/security/exit-codes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hook Exit Code Semantics
+ *
+ * Defines exit-code conventions for hook processes so the runtime
+ * can distinguish success, user-visible errors, and model-blocking
+ * failures that should halt agent execution.
+ *
+ * @module hooks/security/exit-codes
+ * @see IMP-07 Hook Security Hardening
+ */
+export declare const HOOK_EXIT_CODES: {
+    /** Hook completed successfully. */
+    readonly SUCCESS: 0;
+    /** Hook failed with user-visible error (non-blocking). */
+    readonly USER_VISIBLE: 1;
+    /** Hook failed and must block the model from proceeding. */
+    readonly MODEL_BLOCKING: 2;
+};
+export type HookExitCode = typeof HOOK_EXIT_CODES[keyof typeof HOOK_EXIT_CODES];
+/**
+ * Classify a numeric process exit code into a semantic category.
+ *
+ * - 0  -> 'success'
+ * - 2  -> 'model_blocking' (halts agent execution)
+ * - anything else -> 'user_error' (logged, non-blocking)
+ */
+export declare function classifyHookExit(code: number): 'success' | 'user_error' | 'model_blocking';
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/hooks/security/exit-codes.js

@@ -0,0 +1,33 @@
+/**
+ * Hook Exit Code Semantics
+ *
+ * Defines exit-code conventions for hook processes so the runtime
+ * can distinguish success, user-visible errors, and model-blocking
+ * failures that should halt agent execution.
+ *
+ * @module hooks/security/exit-codes
+ * @see IMP-07 Hook Security Hardening
+ */
+export const HOOK_EXIT_CODES = {
+    /** Hook completed successfully. */
+    SUCCESS: 0,
+    /** Hook failed with user-visible error (non-blocking). */
+    USER_VISIBLE: 1,
+    /** Hook failed and must block the model from proceeding. */
+    MODEL_BLOCKING: 2,
+};
+/**
+ * Classify a numeric process exit code into a semantic category.
+ *
+ * - 0  -> 'success'
+ * - 2  -> 'model_blocking' (halts agent execution)
+ * - anything else -> 'user_error' (logged, non-blocking)
+ */
+export function classifyHookExit(code) {
+    if (code === 0)
+        return 'success';
+    if (code === 2)
+        return 'model_blocking';
+    return 'user_error';
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/hooks/security/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hook Security Module
+ *
+ * Re-exports all security primitives for the hook system:
+ * - Config snapshot (deep-freeze at startup)
+ * - SSRF guard (private IP / DNS rebinding protection)
+ * - Exit code semantics (success / user_error / model_blocking)
+ *
+ * @module hooks/security
+ * @see IMP-07 Hook Security Hardening
+ */
+export { captureHooksConfigSnapshot, deepFreeze } from './config-snapshot.js';
+export { validateHookUrl, isPrivateIp, type SsrfValidationResult } from './ssrf-guard.js';
+export { HOOK_EXIT_CODES, classifyHookExit, type HookExitCode } from './exit-codes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/security/index.js

@@ -0,0 +1,15 @@
+/**
+ * Hook Security Module
+ *
+ * Re-exports all security primitives for the hook system:
+ * - Config snapshot (deep-freeze at startup)
+ * - SSRF guard (private IP / DNS rebinding protection)
+ * - Exit code semantics (success / user_error / model_blocking)
+ *
+ * @module hooks/security
+ * @see IMP-07 Hook Security Hardening
+ */
+export { captureHooksConfigSnapshot, deepFreeze } from './config-snapshot.js';
+export { validateHookUrl, isPrivateIp } from './ssrf-guard.js';
+export { HOOK_EXIT_CODES, classifyHookExit } from './exit-codes.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/security/ssrf-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SSRF Guard for Hook URLs
+ *
+ * Blocks hooks from hitting private/internal IP ranges.
+ * Validates both direct IP addresses and DNS-resolved addresses
+ * to prevent DNS rebinding attacks.
+ *
+ * @module hooks/security/ssrf-guard
+ * @see IMP-07 Hook Security Hardening
+ */
+export interface SsrfValidationResult {
+    safe: boolean;
+    reason?: string;
+}
+/**
+ * Check if an IP address is in a private/reserved range.
+ */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Validate a hook URL for SSRF safety.
+ * Blocks private IPs both as direct addresses and via DNS resolution.
+ * Disabled via AQE_HOOKS_SSRF_DISABLED=true (dev mode only).
+ */
+export declare function validateHookUrl(url: string): Promise<SsrfValidationResult>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/hooks/security/ssrf-guard.js

@@ -0,0 +1,69 @@
+/**
+ * SSRF Guard for Hook URLs
+ *
+ * Blocks hooks from hitting private/internal IP ranges.
+ * Validates both direct IP addresses and DNS-resolved addresses
+ * to prevent DNS rebinding attacks.
+ *
+ * @module hooks/security/ssrf-guard
+ * @see IMP-07 Hook Security Hardening
+ */
+import { isIP } from 'net';
+import { lookup } from 'dns/promises';
+const PRIVATE_RANGES = [
+    /^10\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^192\.168\./,
+    /^127\./,
+    /^0\./,
+    /^169\.254\./,
+    /^::1$/,
+    /^fc00:/,
+    /^fe80:/,
+    /^fd[0-9a-f]{2}:/i,
+];
+/**
+ * Check if an IP address is in a private/reserved range.
+ */
+export function isPrivateIp(ip) {
+    return PRIVATE_RANGES.some(r => r.test(ip));
+}
+/**
+ * Validate a hook URL for SSRF safety.
+ * Blocks private IPs both as direct addresses and via DNS resolution.
+ * Disabled via AQE_HOOKS_SSRF_DISABLED=true (dev mode only).
+ */
+export async function validateHookUrl(url) {
+    if (process.env.AQE_HOOKS_SSRF_DISABLED === 'true') {
+        return { safe: true };
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { safe: false, reason: `Invalid URL: ${url}` };
+    }
+    // Strip IPv6 brackets — URL.hostname wraps IPv6 as "[::1]" but
+    // isIP() and our regex patterns expect the bare address "::1".
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+    // Direct IP check
+    if (isIP(hostname)) {
+        if (isPrivateIp(hostname)) {
+            return { safe: false, reason: `Private IP blocked: ${hostname}` };
+        }
+        return { safe: true };
+    }
+    // DNS resolution check (prevents DNS rebinding)
+    try {
+        const resolved = await lookup(hostname);
+        if (isPrivateIp(resolved.address)) {
+            return { safe: false, reason: `DNS resolves to private IP: ${resolved.address}` };
+        }
+    }
+    catch (err) {
+        return { safe: false, reason: `DNS lookup failed for ${hostname}: ${err.message}` };
+    }
+    return { safe: true };
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/init/agents-installer.d.ts

@@ -44,9 +44,11 @@ export declare class AgentsInstaller {
     private sourceAgentsDir;
     constructor(options: AgentsInstallerOptions);
     /**
-     * Find the source agents directory
-     * Looks in multiple locations to support different installation scenarios
-     * PRIORITY: assets directory (has helpers) > root .claude (no helpers)
+     * Find the source agents directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/agents/v3/ (canonical npm source with helpers/) over .claude/agents/v3/.
      */
     private findSourceAgentsDir;
     /**

package/dist/init/agents-installer.js

@@ -6,11 +6,11 @@
  * Agents are copied from .claude/agents/v3/ to the project's .claude/agents/v3/.
  */
 import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { loadOverlays, applyOverlayToContent } from '../agents/overlay-loader.js';
 import { validateFleetMcpDeps } from '../validation/steps/agent-mcp-validator.js';
+import { findPackageRoot } from './find-package-root.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -147,47 +147,22 @@ export class AgentsInstaller {
         this.sourceAgentsDir = this.findSourceAgentsDir();
     }
     /**
-     * Find the source agents directory
-     * Looks in multiple locations to support different installation scenarios
-     * PRIORITY: assets directory (has helpers) > root .claude (no helpers)
+     * Find the source agents directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/agents/v3/ (canonical npm source with helpers/) over .claude/agents/v3/.
      */
     findSourceAgentsDir() {
-        // Try relative to this module (development)
-        const moduleDir = dirname(fileURLToPath(import.meta.url));
-        // Possible locations for agents - PRIORITY ORDER MATTERS
-        // Assets directory is canonical source (contains helpers/)
-        const possiblePaths = [
-            // NPM package: assets directory at package root (dist/init -> dist -> package root)
-            // This is the canonical source with helpers/ directory
-            join(moduleDir, '../../assets/agents/v3'),
-            // Development: src/init/ or dist/init/ -> project root .claude/agents/v3
-            join(moduleDir, '../../.claude/agents/v3'),
-            // Local install: in node_modules
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'),
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'),
-        ];
-        // For global npm installs, add common global node_modules paths
-        // Note: We use platform-based heuristics instead of npm prefix lookup
-        // to avoid dynamic require issues in ESM bundles
-        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-        const isWindows = process.platform === 'win32';
-        if (isWindows) {
-            // Windows: npm global is typically in AppData
-            const appData = process.env.APPDATA || join(homeDir, 'AppData', 'Roaming');
-            possiblePaths.push(join(appData, 'npm/node_modules/agentic-qe/assets/agents/v3'), join(appData, 'npm/node_modules/agentic-qe/.claude/agents/v3'));
-        }
-        else {
-            // Unix/Linux/macOS: common global prefixes
-            const globalPrefixes = [
-                '/usr/local',
-                '/usr',
-                join(homeDir, '.npm-global'),
-                join(homeDir, '.nvm/versions/node', process.version),
-            ];
-            for (const prefix of globalPrefixes) {
-                possiblePaths.push(join(prefix, 'lib/node_modules/agentic-qe/assets/agents/v3'), join(prefix, 'lib/node_modules/agentic-qe/.claude/agents/v3'), join(prefix, 'node_modules/agentic-qe/assets/agents/v3'), join(prefix, 'node_modules/agentic-qe/.claude/agents/v3'));
-            }
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            // Canonical npm source — assets/ contains helpers/ directory
+            possiblePaths.push(join(pkgRoot, 'assets/agents/v3'));
+            possiblePaths.push(join(pkgRoot, '.claude/agents/v3'));
         }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'));
         for (const agentsPath of possiblePaths) {
             if (existsSync(agentsPath)) {
                 return agentsPath;
@@ -209,10 +184,9 @@ export class AgentsInstaller {
         const exampleDest = join(overridesDir, '_example.yaml');
         if (!existsSync(exampleDest)) {
             try {
-                const moduleDir = dirname(fileURLToPath(import.meta.url));
+                const pkgRoot = findPackageRoot(import.meta.url);
                 const templateSources = [
-                    join(moduleDir, '..', '..', 'assets', 'templates', 'agent-override-example.yaml'),
-                    join(moduleDir, '..', 'assets', 'templates', 'agent-override-example.yaml'),
+                    ...(pkgRoot ? [join(pkgRoot, 'assets', 'templates', 'agent-override-example.yaml')] : []),
                     join(this.projectRoot, 'node_modules', 'agentic-qe', 'assets', 'templates', 'agent-override-example.yaml'),
                 ];
                 for (const src of templateSources) {

package/dist/init/find-package-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared utility: find the agentic-qe package root directory.
+ *
+ * When esbuild bundles the CLI with code-splitting, `import.meta.url`
+ * resolves to `dist/cli/chunks/chunk-XXX.js` (3+ levels deep) instead
+ * of the expected `dist/init/skills-installer.js` (2 levels deep).
+ * Fixed `../../` traversals land at `dist/` instead of the package root,
+ * so skills/agents/helpers can't be found.
+ *
+ * This module walks up from the caller's directory until it finds a
+ * `package.json` with `name === "agentic-qe"`, which works regardless
+ * of how deep the bundle puts the calling file.
+ */
+/**
+ * Find the agentic-qe package root by walking up from `import.meta.url`.
+ *
+ * @param callerMetaUrl – pass `import.meta.url` from the calling module
+ * @param maxDepth      – how many parent directories to check (default 10)
+ * @returns absolute path to the package root, or null if not found
+ */
+export declare function findPackageRoot(callerMetaUrl: string, maxDepth?: number): string | null;
+//# sourceMappingURL=find-package-root.d.ts.map

package/dist/init/find-package-root.js

@@ -0,0 +1,46 @@
+/**
+ * Shared utility: find the agentic-qe package root directory.
+ *
+ * When esbuild bundles the CLI with code-splitting, `import.meta.url`
+ * resolves to `dist/cli/chunks/chunk-XXX.js` (3+ levels deep) instead
+ * of the expected `dist/init/skills-installer.js` (2 levels deep).
+ * Fixed `../../` traversals land at `dist/` instead of the package root,
+ * so skills/agents/helpers can't be found.
+ *
+ * This module walks up from the caller's directory until it finds a
+ * `package.json` with `name === "agentic-qe"`, which works regardless
+ * of how deep the bundle puts the calling file.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Find the agentic-qe package root by walking up from `import.meta.url`.
+ *
+ * @param callerMetaUrl – pass `import.meta.url` from the calling module
+ * @param maxDepth      – how many parent directories to check (default 10)
+ * @returns absolute path to the package root, or null if not found
+ */
+export function findPackageRoot(callerMetaUrl, maxDepth = 10) {
+    let dir = dirname(fileURLToPath(callerMetaUrl));
+    for (let i = 0; i < maxDepth; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === 'agentic-qe') {
+                    return dir;
+                }
+            }
+            catch {
+                // Malformed JSON — keep walking
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return null;
+}
+//# sourceMappingURL=find-package-root.js.map

package/dist/init/n8n-installer.d.ts

@@ -42,11 +42,13 @@ export declare class N8nInstaller {
     private sourceSkillsDir;
     constructor(options: N8nInstallerOptions);
     /**
-     * Find the source n8n agents directory
+     * Find the source n8n agents directory.
+     * n8n agents live under .claude/agents/n8n/ in the package root.
      */
     private findSourceAgentsDir;
     /**
-     * Find the source skills directory
+     * Find the source skills directory.
+     * Skills are in assets/skills/ (canonical npm source).
      */
     private findSourceSkillsDir;
     /**

package/dist/init/n8n-installer.js

@@ -6,12 +6,9 @@
  * Copies agent definitions from .claude/agents/n8n/ and installs n8n-specific skills.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
-// ESM compatibility - __dirname is not available in ES modules
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { findPackageRoot } from './find-package-root.js';
 // ============================================================================
 // N8n Agent Categories
 // ============================================================================
@@ -78,40 +75,43 @@ export class N8nInstaller {
     // Source Directory Detection
     // ==========================================================================
     /**
-     * Find the source n8n agents directory
+     * Find the source n8n agents directory.
+     * n8n agents live under .claude/agents/n8n/ in the package root.
      */
     findSourceAgentsDir() {
-        const possiblePaths = [
-            // Development: src/init/ or dist/init/ -> project root
-            join(__dirname, '../../.claude/agents/n8n'),
-            // From project root
-            join(process.cwd(), '.claude/agents/n8n'),
-            // NPM package location
-            join(__dirname, '../../assets/agents/n8n'),
-        ];
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            possiblePaths.push(join(pkgRoot, '.claude/agents/n8n'));
+        }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/.claude/agents/n8n'));
         for (const path of possiblePaths) {
             if (existsSync(path)) {
                 return path;
             }
         }
-        // Default to project root location
-        return join(process.cwd(), '.claude/agents/n8n');
+        return possiblePaths[0];
     }
     /**
-     * Find the source skills directory
+     * Find the source skills directory.
+     * Skills are in assets/skills/ (canonical npm source).
      */
     findSourceSkillsDir() {
-        const possiblePaths = [
-            join(__dirname, '../../.claude/skills'),
-            join(process.cwd(), '.claude/skills'),
-            join(__dirname, '../../assets/skills'),
-        ];
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            possiblePaths.push(join(pkgRoot, 'assets/skills'));
+            possiblePaths.push(join(pkgRoot, '.claude/skills'));
+        }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/assets/skills'));
         for (const path of possiblePaths) {
             if (existsSync(path)) {
                 return path;
             }
         }
-        return join(process.cwd(), '.claude/skills');
+        return possiblePaths[0];
     }
     // ==========================================================================
     // Installation

package/dist/init/opencode-installer.d.ts

@@ -37,11 +37,6 @@ export declare class OpenCodeInstaller {
      * globally-installed and bundled CLI paths all work correctly (#361).
      */
     private findSourceDir;
-    /**
-     * Try to find the package root via require.resolve on our own package.json,
-     * then return <root>/.opencode. Returns null if resolution fails.
-     */
-    private resolveViaPackageJson;
     /**
      * Check if a directory is a valid source for OpenCode assets
      * (must exist and contain at least an agents/ or skills/ subdirectory)

package/dist/init/opencode-installer.js

@@ -5,13 +5,10 @@
  * Installs OpenCode agents, skills, tools, and permissions to user projects
  * when --with-opencode flag is used. Follows the N8n installer pattern.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { existsSync, mkdirSync, readdirSync, writeFileSync, copyFileSync, } from 'fs';
+import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
-// ESM compatibility
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { findPackageRoot } from './find-package-root.js';
 // ============================================================================
 // OpenCode Installer Class
 // ============================================================================
@@ -40,14 +37,14 @@ export class OpenCodeInstaller {
      */
     findSourceDir() {
         const targetDir = join(this.projectRoot, '.opencode');
-        const possiblePaths = [
-            // From dist/init/ or src/init/ → package root .opencode/
-            join(__dirname, '../../.opencode'),
-            // From dist/cli/ (bundle) → package root .opencode/
-            join(__dirname, '../.opencode'),
-            // require.resolve fallback: find the package root via its package.json
-            this.resolveViaPackageJson(),
-        ].filter((p) => p !== null);
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            // OpenCode assets live at the package root .opencode/ directory
+            possiblePaths.push(join(pkgRoot, '.opencode'));
+        }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/.opencode'));
         for (const path of possiblePaths) {
             // Never use the target directory as the source
             if (path === targetDir)
@@ -57,31 +54,7 @@ export class OpenCodeInstaller {
             }
         }
         // Return the first package path even if not found — install() will report the error
-        return possiblePaths[0] ?? join(__dirname, '../../.opencode');
-    }
-    /**
-     * Try to find the package root via require.resolve on our own package.json,
-     * then return <root>/.opencode. Returns null if resolution fails.
-     */
-    resolveViaPackageJson() {
-        try {
-            // Walk up from __dirname to find the nearest package.json with our name
-            let dir = __dirname;
-            for (let i = 0; i < 5; i++) {
-                const pkgPath = join(dir, 'package.json');
-                if (existsSync(pkgPath)) {
-                    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-                    if (pkg.name === 'agentic-qe') {
-                        return join(dir, '.opencode');
-                    }
-                }
-                dir = dirname(dir);
-            }
-        }
-        catch {
-            // resolution failed
-        }
-        return null;
+        return possiblePaths[0] ?? join(this.projectRoot, 'node_modules/agentic-qe/.opencode');
     }
     /**
      * Check if a directory is a valid source for OpenCode assets

package/dist/init/skills-installer.d.ts

@@ -40,8 +40,11 @@ export declare class SkillsInstaller {
     private sourceSkillsDir;
     constructor(options: SkillsInstallerOptions);
     /**
-     * Find the source skills directory
-     * Looks in multiple locations to support different installation scenarios
+     * Find the source skills directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/skills/ (canonical npm source) over .claude/skills/.
      */
     private findSourceSkillsDir;
     /**

package/dist/init/skills-installer.js

@@ -6,9 +6,9 @@
  * Skills are copied from the bundled skills directory to the project's .claude/skills/.
  */
 import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, rmdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { findPackageRoot } from './find-package-root.js';
 // ============================================================================
 // Skill Categories (QE Skills Only - Claude Flow skills are managed separately)
 // ============================================================================
@@ -135,44 +135,22 @@ export class SkillsInstaller {
         this.sourceSkillsDir = this.findSourceSkillsDir();
     }
     /**
-     * Find the source skills directory
-     * Looks in multiple locations to support different installation scenarios
+     * Find the source skills directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/skills/ (canonical npm source) over .claude/skills/.
      */
     findSourceSkillsDir() {
-        // Try relative to this module (development)
-        const moduleDir = dirname(fileURLToPath(import.meta.url));
-        // Possible locations for skills
-        const possiblePaths = [
-            // Development: relative to src/init/ or dist/init/ (2 levels up to project root)
-            join(moduleDir, '../../.claude/skills'),
-            // NPM package: assets directory at package root (dist/init -> dist -> package root)
-            join(moduleDir, '../../assets/skills'),
-            // Local install: in node_modules
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/skills'),
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/skills'),
-        ];
-        // For global npm installs, add common global node_modules paths
-        // Note: We use platform-based heuristics instead of npm prefix lookup
-        // to avoid dynamic require issues in ESM bundles
-        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-        const isWindows = process.platform === 'win32';
-        if (isWindows) {
-            // Windows: npm global is typically in AppData
-            const appData = process.env.APPDATA || join(homeDir, 'AppData', 'Roaming');
-            possiblePaths.push(join(appData, 'npm/node_modules/agentic-qe/assets/skills'), join(appData, 'npm/node_modules/agentic-qe/.claude/skills'));
-        }
-        else {
-            // Unix/Linux/macOS: common global prefixes
-            const globalPrefixes = [
-                '/usr/local',
-                '/usr',
-                join(homeDir, '.npm-global'),
-                join(homeDir, '.nvm/versions/node', process.version),
-            ];
-            for (const prefix of globalPrefixes) {
-                possiblePaths.push(join(prefix, 'lib/node_modules/agentic-qe/assets/skills'), join(prefix, 'lib/node_modules/agentic-qe/.claude/skills'), join(prefix, 'node_modules/agentic-qe/assets/skills'), join(prefix, 'node_modules/agentic-qe/.claude/skills'));
-            }
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            // Canonical npm source — assets/ is never a dotfile, always extracted
+            possiblePaths.push(join(pkgRoot, 'assets/skills'));
+            possiblePaths.push(join(pkgRoot, '.claude/skills'));
         }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/assets/skills'));
         for (const skillsPath of possiblePaths) {
             if (existsSync(skillsPath)) {
                 return skillsPath;