@iaforged/context-code 1.0.63 → 1.0.65

package/dist/src/utils/plugins/pluginLoader.js

@@ -1,2426 +0,0 @@
-/**
- * Plugin Loader Module
- *
- * This module is responsible for discovering, loading, and validating Context Code plugins
- * from various sources including marketplaces and git repositories.
- *
- * NPM packages are also supported but must be referenced through marketplaces - the marketplace
- * entry contains the NPM package information.
- *
- * Plugin Discovery Sources (in order of precedence):
- * 1. Marketplace-based plugins (plugin@marketplace format in settings)
- * 2. Session-only plugins (from --plugin-dir CLI flag or SDK plugins option)
- *
- * Plugin Directory Structure:
- * ```
- * my-plugin/
- * ├── plugin.json          # Optional manifest with metadata
- * ├── commands/            # Custom slash commands
- * │   ├── build.md
- * │   └── deploy.md
- * ├── agents/              # Custom AI agents
- * │   └── test-runner.md
- * └── hooks/               # Hook configurations
- *     └── hooks.json       # Hook definitions
- * ```
- *
- * The loader handles:
- * - Plugin manifest validation
- * - Hooks configuration loading and variable resolution
- * - Duplicate name detection
- * - Enable/disable state management
- * - Error collection and reporting
- */
-import { copyFile, readdir, readFile, readlink, realpath, rename, rm, rmdir, stat, symlink, } from 'fs/promises';
-import memoize from 'lodash-es/memoize.js';
-import { basename, dirname, join, relative, resolve, sep } from 'path';
-import { getInlinePlugins } from '../../bootstrap/state.js';
-import { BUILTIN_MARKETPLACE_NAME, getBuiltinPlugins, } from '../../plugins/builtinPlugins.js';
-import { logForDebugging } from '../debug.js';
-import { isEnvTruthy } from '../envUtils.js';
-import { errorMessage, getErrnoPath, isENOENT, isFsInaccessible, toError, } from '../errors.js';
-import { execFileNoThrow, execFileNoThrowWithCwd } from '../execFileNoThrow.js';
-import { pathExists } from '../file.js';
-import { getFsImplementation } from '../fsOperations.js';
-import { gitExe } from '../git.js';
-import { lazySchema } from '../lazySchema.js';
-import { logError } from '../log.js';
-import { getSettings_DEPRECATED } from '../settings/settings.js';
-import { clearPluginSettingsBase, getPluginSettingsBase, resetSettingsCache, setPluginSettingsBase, } from '../settings/settingsCache.js';
-import { SettingsSchema } from '../settings/types.js';
-import { jsonParse, jsonStringify } from '../slowOperations.js';
-import { getAddDirEnabledPlugins } from './addDirPluginSettings.js';
-import { verifyAndDemote } from './dependencyResolver.js';
-import { classifyFetchError, logPluginFetch } from './fetchTelemetry.js';
-import { checkGitAvailable } from './gitAvailability.js';
-import { getInMemoryInstalledPlugins } from './installedPluginsManager.js';
-import { getManagedPluginNames } from './managedPlugins.js';
-import { formatSourceForDisplay, getBlockedMarketplaces, getStrictKnownMarketplaces, isSourceAllowedByPolicy, isSourceInBlocklist, } from './marketplaceHelpers.js';
-import { getMarketplaceCacheOnly, getPluginByIdCacheOnly, loadKnownMarketplacesConfigSafe, } from './marketplaceManager.js';
-import { getPluginSeedDirs, getPluginsDirectory } from './pluginDirectories.js';
-import { parsePluginIdentifier } from './pluginIdentifier.js';
-import { validatePathWithinBase } from './pluginInstallationHelpers.js';
-import { calculatePluginVersion } from './pluginVersioning.js';
-import { PluginHooksSchema, PluginIdSchema, PluginManifestSchema, } from './schemas.js';
-import { convertDirectoryToZipInPlace, extractZipToDirectory, getSessionPluginCachePath, isPluginZipCacheEnabled, } from './zipCache.js';
-/**
- * Get the path where plugin cache is stored
- */
-export function getPluginCachePath() {
-    return join(getPluginsDirectory(), 'cache');
-}
-/**
- * Compute the versioned cache path under a specific base plugins directory.
- * Used to probe both primary and seed caches.
- *
- * @param baseDir - Base plugins directory (e.g. getPluginsDirectory() or seed dir)
- * @param pluginId - Plugin identifier in format "name@marketplace"
- * @param version - Version string (semver, git SHA, etc.)
- * @returns Absolute path to versioned plugin directory under baseDir
- */
-export function getVersionedCachePathIn(baseDir, pluginId, version) {
-    const { name: pluginName, marketplace } = parsePluginIdentifier(pluginId);
-    const sanitizedMarketplace = (marketplace || 'unknown').replace(/[^a-zA-Z0-9\-_]/g, '-');
-    const sanitizedPlugin = (pluginName || pluginId).replace(/[^a-zA-Z0-9\-_]/g, '-');
-    // Sanitize version to prevent path traversal attacks
-    const sanitizedVersion = version.replace(/[^a-zA-Z0-9\-_.]/g, '-');
-    return join(baseDir, 'cache', sanitizedMarketplace, sanitizedPlugin, sanitizedVersion);
-}
-/**
- * Get versioned cache path for a plugin under the primary plugins directory.
- * Format: ~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/
- *
- * @param pluginId - Plugin identifier in format "name@marketplace"
- * @param version - Version string (semver, git SHA, etc.)
- * @returns Absolute path to versioned plugin directory
- */
-export function getVersionedCachePath(pluginId, version) {
-    return getVersionedCachePathIn(getPluginsDirectory(), pluginId, version);
-}
-/**
- * Get versioned ZIP cache path for a plugin.
- * This is the zip cache variant of getVersionedCachePath.
- */
-export function getVersionedZipCachePath(pluginId, version) {
-    return `${getVersionedCachePath(pluginId, version)}.zip`;
-}
-/**
- * Probe seed directories for a populated cache at this plugin version.
- * Seeds are checked in precedence order; first hit wins. Returns null if no
- * seed is configured or none contains a populated directory at this version.
- */
-async function probeSeedCache(pluginId, version) {
-    for (const seedDir of getPluginSeedDirs()) {
-        const seedPath = getVersionedCachePathIn(seedDir, pluginId, version);
-        try {
-            const entries = await readdir(seedPath);
-            if (entries.length > 0)
-                return seedPath;
-        }
-        catch {
-            // Try next seed
-        }
-    }
-    return null;
-}
-/**
- * When the computed version is 'unknown', probe seed/cache/<m>/<p>/ for an
- * actual version dir. Handles the first-boot chicken-and-egg where the
- * version can only be known after cloning, but seed already has the clone.
- *
- * Per seed, only matches when exactly one version exists (typical BYOC case).
- * Multiple versions within a single seed → ambiguous → try next seed.
- * Seeds are checked in precedence order; first match wins.
- */
-export async function probeSeedCacheAnyVersion(pluginId) {
-    for (const seedDir of getPluginSeedDirs()) {
-        // The parent of the version dir — computed the same way as
-        // getVersionedCachePathIn, just without the version component.
-        const pluginDir = dirname(getVersionedCachePathIn(seedDir, pluginId, '_'));
-        try {
-            const versions = await readdir(pluginDir);
-            if (versions.length !== 1)
-                continue;
-            const versionDir = join(pluginDir, versions[0]);
-            const entries = await readdir(versionDir);
-            if (entries.length > 0)
-                return versionDir;
-        }
-        catch {
-            // Try next seed
-        }
-    }
-    return null;
-}
-/**
- * Get legacy (non-versioned) cache path for a plugin.
- * Format: ~/.claude/plugins/cache/{plugin-name}/
- *
- * Used for backward compatibility with existing installations.
- *
- * @param pluginName - Plugin name (without marketplace suffix)
- * @returns Absolute path to legacy plugin directory
- */
-export function getLegacyCachePath(pluginName) {
-    const cachePath = getPluginCachePath();
-    return join(cachePath, pluginName.replace(/[^a-zA-Z0-9\-_]/g, '-'));
-}
-/**
- * Resolve plugin path with fallback to legacy location.
- *
- * Always:
- * 1. Try versioned path first if version is provided
- * 2. Fall back to legacy path for existing installations
- * 3. Return versioned path for new installations
- *
- * @param pluginId - Plugin identifier in format "name@marketplace"
- * @param version - Optional version string
- * @returns Absolute path to plugin directory
- */
-export async function resolvePluginPath(pluginId, version) {
-    // Try versioned path first
-    if (version) {
-        const versionedPath = getVersionedCachePath(pluginId, version);
-        if (await pathExists(versionedPath)) {
-            return versionedPath;
-        }
-    }
-    // Fall back to legacy path for existing installations
-    const pluginName = parsePluginIdentifier(pluginId).name || pluginId;
-    const legacyPath = getLegacyCachePath(pluginName);
-    if (await pathExists(legacyPath)) {
-        return legacyPath;
-    }
-    // Return versioned path for new installations
-    return version ? getVersionedCachePath(pluginId, version) : legacyPath;
-}
-/**
- * Recursively copy a directory.
- * Exported for testing purposes.
- */
-export async function copyDir(src, dest) {
-    await getFsImplementation().mkdir(dest);
-    const entries = await readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = join(src, entry.name);
-        const destPath = join(dest, entry.name);
-        if (entry.isDirectory()) {
-            await copyDir(srcPath, destPath);
-        }
-        else if (entry.isFile()) {
-            await copyFile(srcPath, destPath);
-        }
-        else if (entry.isSymbolicLink()) {
-            const linkTarget = await readlink(srcPath);
-            // Resolve the symlink to get the actual target path
-            // This prevents circular symlinks when src and dest overlap (e.g., via symlink chains)
-            let resolvedTarget;
-            try {
-                resolvedTarget = await realpath(srcPath);
-            }
-            catch {
-                // Broken symlink - copy the raw link target as-is
-                await symlink(linkTarget, destPath);
-                continue;
-            }
-            // Resolve the source directory to handle symlinked source dirs
-            let resolvedSrc;
-            try {
-                resolvedSrc = await realpath(src);
-            }
-            catch {
-                resolvedSrc = src;
-            }
-            // Check if target is within the source tree (using proper path prefix matching)
-            const srcPrefix = resolvedSrc.endsWith(sep)
-                ? resolvedSrc
-                : resolvedSrc + sep;
-            if (resolvedTarget.startsWith(srcPrefix) ||
-                resolvedTarget === resolvedSrc) {
-                // Target is within source tree - create relative symlink that preserves
-                // the same structure in the destination
-                const targetRelativeToSrc = relative(resolvedSrc, resolvedTarget);
-                const destTargetPath = join(dest, targetRelativeToSrc);
-                const relativeLinkPath = relative(dirname(destPath), destTargetPath);
-                await symlink(relativeLinkPath, destPath);
-            }
-            else {
-                // Target is outside source tree - use absolute resolved path
-                await symlink(resolvedTarget, destPath);
-            }
-        }
-    }
-}
-/**
- * Copy plugin files to versioned cache directory.
- *
- * For local plugins: Uses entry.source from marketplace.json as the single source of truth.
- * For remote plugins: Falls back to copying sourcePath (the downloaded content).
- *
- * @param sourcePath - Path to the plugin source (used as fallback for remote plugins)
- * @param pluginId - Plugin identifier in format "name@marketplace"
- * @param version - Version string for versioned path
- * @param entry - Optional marketplace entry containing the source field
- * @param marketplaceDir - Marketplace directory for resolving entry.source (undefined for remote plugins)
- * @returns Path to the cached plugin directory
- * @throws Error if the source directory is not found
- * @throws Error if the destination directory is empty after copy
- */
-export async function copyPluginToVersionedCache(sourcePath, pluginId, version, entry, marketplaceDir) {
-    // When zip cache is enabled, the canonical format is a ZIP file
-    const zipCacheMode = isPluginZipCacheEnabled();
-    const cachePath = getVersionedCachePath(pluginId, version);
-    const zipPath = getVersionedZipCachePath(pluginId, version);
-    // If cache already exists (directory or ZIP), return it
-    if (zipCacheMode) {
-        if (await pathExists(zipPath)) {
-            logForDebugging(`Plugin ${pluginId} version ${version} already cached at ${zipPath}`);
-            return zipPath;
-        }
-    }
-    else if (await pathExists(cachePath)) {
-        const entries = await readdir(cachePath);
-        if (entries.length > 0) {
-            logForDebugging(`Plugin ${pluginId} version ${version} already cached at ${cachePath}`);
-            return cachePath;
-        }
-        // Directory exists but is empty, remove it so we can recreate with content
-        logForDebugging(`Removing empty cache directory for ${pluginId} at ${cachePath}`);
-        await rmdir(cachePath);
-    }
-    // Seed cache hit — return seed path in place (read-only, no copy).
-    // Callers handle both directory and .zip paths; this returns a directory.
-    const seedPath = await probeSeedCache(pluginId, version);
-    if (seedPath) {
-        logForDebugging(`Using seed cache for ${pluginId}@${version} at ${seedPath}`);
-        return seedPath;
-    }
-    // Create parent directories
-    await getFsImplementation().mkdir(dirname(cachePath));
-    // For local plugins: copy entry.source directory (the single source of truth)
-    // For remote plugins: marketplaceDir is undefined, fall back to copying sourcePath
-    if (entry && typeof entry.source === 'string' && marketplaceDir) {
-        const sourceDir = validatePathWithinBase(marketplaceDir, entry.source);
-        logForDebugging(`Copying source directory ${entry.source} for plugin ${pluginId}`);
-        try {
-            await copyDir(sourceDir, cachePath);
-        }
-        catch (e) {
-            // Only remap ENOENT from the top-level sourceDir itself — nested ENOENTs
-            // from recursive copyDir (broken symlinks, raced deletes) should preserve
-            // their original path in the error.
-            if (isENOENT(e) && getErrnoPath(e) === sourceDir) {
-                throw new Error(`Plugin source directory not found: ${sourceDir} (from entry.source: ${entry.source})`);
-            }
-            throw e;
-        }
-    }
-    else {
-        // Fallback for remote plugins (already downloaded) or plugins without entry.source
-        logForDebugging(`Copying plugin ${pluginId} to versioned cache (fallback to full copy)`);
-        await copyDir(sourcePath, cachePath);
-    }
-    // Remove .git directory from cache if present
-    const gitPath = join(cachePath, '.git');
-    await rm(gitPath, { recursive: true, force: true });
-    // Validate that cache has content - if empty, throw so fallback can be used
-    const cacheEntries = await readdir(cachePath);
-    if (cacheEntries.length === 0) {
-        throw new Error(`Failed to copy plugin ${pluginId} to versioned cache: destination is empty after copy`);
-    }
-    // Zip cache mode: convert directory to ZIP and remove the directory
-    if (zipCacheMode) {
-        await convertDirectoryToZipInPlace(cachePath, zipPath);
-        logForDebugging(`Successfully cached plugin ${pluginId} as ZIP at ${zipPath}`);
-        return zipPath;
-    }
-    logForDebugging(`Successfully cached plugin ${pluginId} at ${cachePath}`);
-    return cachePath;
-}
-/**
- * Validate a git URL using Node.js URL parsing
- */
-function validateGitUrl(url) {
-    try {
-        const parsed = new URL(url);
-        if (!['https:', 'http:', 'file:'].includes(parsed.protocol)) {
-            if (!/^git@[a-zA-Z0-9.-]+:/.test(url)) {
-                throw new Error(`Invalid git URL protocol: ${parsed.protocol}. Only HTTPS, HTTP, file:// and SSH (git@) URLs are supported.`);
-            }
-        }
-        return url;
-    }
-    catch {
-        if (/^git@[a-zA-Z0-9.-]+:/.test(url)) {
-            return url;
-        }
-        throw new Error(`Invalid git URL: ${url}`);
-    }
-}
-/**
- * Install a plugin from npm using a global cache (exported for testing)
- */
-export async function installFromNpm(packageName, targetPath, options = {}) {
-    const npmCachePath = join(getPluginsDirectory(), 'npm-cache');
-    await getFsImplementation().mkdir(npmCachePath);
-    const packageSpec = options.version
-        ? `${packageName}@${options.version}`
-        : packageName;
-    const packagePath = join(npmCachePath, 'node_modules', packageName);
-    const needsInstall = !(await pathExists(packagePath));
-    if (needsInstall) {
-        logForDebugging(`Installing npm package ${packageSpec} to cache`);
-        const args = ['install', packageSpec, '--prefix', npmCachePath];
-        if (options.registry) {
-            args.push('--registry', options.registry);
-        }
-        const result = await execFileNoThrow('npm', args, { useCwd: false });
-        if (result.code !== 0) {
-            throw new Error(`Failed to install npm package: ${result.stderr}`);
-        }
-    }
-    await copyDir(packagePath, targetPath);
-    logForDebugging(`Copied npm package ${packageName} from cache to ${targetPath}`);
-}
-/**
- * Clone a git repository (exported for testing)
- *
- * @param gitUrl - The git URL to clone
- * @param targetPath - Where to clone the repository
- * @param ref - Optional branch or tag to checkout
- * @param sha - Optional specific commit SHA to checkout
- */
-export async function gitClone(gitUrl, targetPath, ref, sha) {
-    // Use --recurse-submodules to initialize submodules
-    // Always start with shallow clone for efficiency
-    const args = [
-        'clone',
-        '--depth',
-        '1',
-        '--recurse-submodules',
-        '--shallow-submodules',
-    ];
-    // Add --branch flag for specific ref (works for both branches and tags)
-    if (ref) {
-        args.push('--branch', ref);
-    }
-    // If sha is specified, use --no-checkout since we'll checkout the SHA separately
-    if (sha) {
-        args.push('--no-checkout');
-    }
-    args.push(gitUrl, targetPath);
-    const cloneStarted = performance.now();
-    const cloneResult = await execFileNoThrow(gitExe(), args);
-    if (cloneResult.code !== 0) {
-        logPluginFetch('plugin_clone', gitUrl, 'failure', performance.now() - cloneStarted, classifyFetchError(cloneResult.stderr));
-        throw new Error(`Failed to clone repository: ${cloneResult.stderr}`);
-    }
-    // If sha is specified, fetch and checkout that specific commit
-    if (sha) {
-        // Try shallow fetch of the specific SHA first (most efficient)
-        const shallowFetchResult = await execFileNoThrowWithCwd(gitExe(), ['fetch', '--depth', '1', 'origin', sha], { cwd: targetPath });
-        if (shallowFetchResult.code !== 0) {
-            // Some servers don't support fetching arbitrary SHAs
-            // Fall back to unshallow fetch to get full history
-            logForDebugging(`Shallow fetch of SHA ${sha} failed, falling back to unshallow fetch`);
-            const unshallowResult = await execFileNoThrowWithCwd(gitExe(), ['fetch', '--unshallow'], { cwd: targetPath });
-            if (unshallowResult.code !== 0) {
-                logPluginFetch('plugin_clone', gitUrl, 'failure', performance.now() - cloneStarted, classifyFetchError(unshallowResult.stderr));
-                throw new Error(`Failed to fetch commit ${sha}: ${unshallowResult.stderr}`);
-            }
-        }
-        // Checkout the specific commit
-        const checkoutResult = await execFileNoThrowWithCwd(gitExe(), ['checkout', sha], { cwd: targetPath });
-        if (checkoutResult.code !== 0) {
-            logPluginFetch('plugin_clone', gitUrl, 'failure', performance.now() - cloneStarted, classifyFetchError(checkoutResult.stderr));
-            throw new Error(`Failed to checkout commit ${sha}: ${checkoutResult.stderr}`);
-        }
-    }
-    // Fire success only after ALL network ops (clone + optional SHA fetch)
-    // complete — same telemetry-scope discipline as mcpb and marketplace_url.
-    logPluginFetch('plugin_clone', gitUrl, 'success', performance.now() - cloneStarted);
-}
-/**
- * Install a plugin from a git URL
- */
-async function installFromGit(gitUrl, targetPath, ref, sha) {
-    const safeUrl = validateGitUrl(gitUrl);
-    await gitClone(safeUrl, targetPath, ref, sha);
-    const refMessage = ref ? ` (ref: ${ref})` : '';
-    logForDebugging(`Cloned repository from ${safeUrl}${refMessage} to ${targetPath}`);
-}
-/**
- * Install a plugin from GitHub
- */
-async function installFromGitHub(repo, targetPath, ref, sha) {
-    if (!/^[a-zA-Z0-9-_.]+\/[a-zA-Z0-9-_.]+$/.test(repo)) {
-        throw new Error(`Invalid GitHub repository format: ${repo}. Expected format: owner/repo`);
-    }
-    // Use HTTPS for CCR (no SSH keys), SSH for normal CLI
-    const gitUrl = isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)
-        ? `https://github.com/${repo}.git`
-        : `git@github.com:${repo}.git`;
-    return installFromGit(gitUrl, targetPath, ref, sha);
-}
-/**
- * Resolve a git-subdir `url` field to a clonable git URL.
- * Accepts GitHub owner/repo shorthand (converted to ssh or https depending on
- * CLAUDE_CODE_REMOTE) or any URL that passes validateGitUrl (https, http,
- * file, git@ ssh).
- */
-function resolveGitSubdirUrl(url) {
-    if (/^[a-zA-Z0-9-_.]+\/[a-zA-Z0-9-_.]+$/.test(url)) {
-        return isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)
-            ? `https://github.com/${url}.git`
-            : `git@github.com:${url}.git`;
-    }
-    return validateGitUrl(url);
-}
-/**
- * Install a plugin from a subdirectory of a git repository (exported for
- * testing).
- *
- * Uses partial clone (--filter=tree:0) + sparse-checkout so only the tree
- * objects along the path and the blobs under it are downloaded. For large
- * monorepos this is dramatically cheaper than a full clone — the tree objects
- * for a million-file repo can be hundreds of MB, all avoided here.
- *
- * Sequence:
- * 1. clone --depth 1 --filter=tree:0 --no-checkout [--branch ref]
- * 2. sparse-checkout set --cone -- <path>
- * 3. If sha: fetch --depth 1 origin <sha> (fallback: --unshallow), then
- *    checkout <sha>. The partial-clone filter is stored in remote config so
- *    subsequent fetches respect it; --unshallow gets all commits but trees
- *    and blobs remain lazy.
- *    If no sha: checkout HEAD (points to ref if --branch was used).
- * 4. Move <cloneDir>/<path> to targetPath and discard the clone.
- *
- * The clone is ephemeral — it goes into a sibling temp directory and is
- * removed after the subdir is extracted. targetPath ends up containing only
- * the plugin files with no .git directory.
- */
-export async function installFromGitSubdir(url, targetPath, subdirPath, ref, sha) {
-    if (!(await checkGitAvailable())) {
-        throw new Error('git-subdir plugin source requires git to be installed and on PATH. ' +
-            'Install git (version 2.25 or later for sparse-checkout cone mode) and try again.');
-    }
-    const gitUrl = resolveGitSubdirUrl(url);
-    // Clone into a sibling temp dir (same filesystem → rename works, no EXDEV).
-    const cloneDir = `${targetPath}.clone`;
-    const cloneArgs = [
-        'clone',
-        '--depth',
-        '1',
-        '--filter=tree:0',
-        '--no-checkout',
-    ];
-    if (ref) {
-        cloneArgs.push('--branch', ref);
-    }
-    cloneArgs.push(gitUrl, cloneDir);
-    const cloneResult = await execFileNoThrow(gitExe(), cloneArgs);
-    if (cloneResult.code !== 0) {
-        throw new Error(`Failed to clone repository for git-subdir source: ${cloneResult.stderr}`);
-    }
-    try {
-        const sparseResult = await execFileNoThrowWithCwd(gitExe(), ['sparse-checkout', 'set', '--cone', '--', subdirPath], { cwd: cloneDir });
-        if (sparseResult.code !== 0) {
-            throw new Error(`git sparse-checkout set failed (git >= 2.25 required for cone mode): ${sparseResult.stderr}`);
-        }
-        // Capture the resolved commit SHA before discarding the clone. The
-        // extracted subdir has no .git, so the caller can't rev-parse it later.
-        // If the source specified a full 40-char sha we already know it; otherwise
-        // read HEAD (which points to ref's tip after --branch, or the remote
-        // default branch if no ref was given).
-        let resolvedSha;
-        if (sha) {
-            const fetchSha = await execFileNoThrowWithCwd(gitExe(), ['fetch', '--depth', '1', 'origin', sha], { cwd: cloneDir });
-            if (fetchSha.code !== 0) {
-                logForDebugging(`Shallow fetch of SHA ${sha} failed for git-subdir, falling back to unshallow fetch`);
-                const unshallow = await execFileNoThrowWithCwd(gitExe(), ['fetch', '--unshallow'], { cwd: cloneDir });
-                if (unshallow.code !== 0) {
-                    throw new Error(`Failed to fetch commit ${sha}: ${unshallow.stderr}`);
-                }
-            }
-            const checkout = await execFileNoThrowWithCwd(gitExe(), ['checkout', sha], { cwd: cloneDir });
-            if (checkout.code !== 0) {
-                throw new Error(`Failed to checkout commit ${sha}: ${checkout.stderr}`);
-            }
-            resolvedSha = sha;
-        }
-        else {
-            // checkout HEAD materializes the working tree (this is where blobs are
-            // lazy-fetched — the slow, network-bound step). It doesn't move HEAD;
-            // --branch at clone time already positioned it. rev-parse HEAD is a
-            // purely read-only ref lookup (no index lock), so it runs safely in
-            // parallel with checkout and we avoid waiting on the network for it.
-            const [checkout, revParse] = await Promise.all([
-                execFileNoThrowWithCwd(gitExe(), ['checkout', 'HEAD'], {
-                    cwd: cloneDir,
-                }),
-                execFileNoThrowWithCwd(gitExe(), ['rev-parse', 'HEAD'], {
-                    cwd: cloneDir,
-                }),
-            ]);
-            if (checkout.code !== 0) {
-                throw new Error(`git checkout after sparse-checkout failed: ${checkout.stderr}`);
-            }
-            if (revParse.code === 0) {
-                resolvedSha = revParse.stdout.trim();
-            }
-        }
-        // Path traversal guard: resolve+verify the subdir stays inside cloneDir
-        // before moving it out. rename ENOENT is wrapped with a friendlier
-        // message that references the source path, not internal temp dirs.
-        const resolvedSubdir = validatePathWithinBase(cloneDir, subdirPath);
-        try {
-            await rename(resolvedSubdir, targetPath);
-        }
-        catch (e) {
-            if (isENOENT(e)) {
-                throw new Error(`Subdirectory '${subdirPath}' not found in repository ${gitUrl}${ref ? ` (ref: ${ref})` : ''}. ` +
-                    'Check that the path is correct and exists at the specified ref/sha.');
-            }
-            throw e;
-        }
-        const refMsg = ref ? ` ref=${ref}` : '';
-        const shaMsg = resolvedSha ? ` sha=${resolvedSha}` : '';
-        logForDebugging(`Extracted subdir ${subdirPath} from ${gitUrl}${refMsg}${shaMsg} to ${targetPath}`);
-        return resolvedSha;
-    }
-    finally {
-        await rm(cloneDir, { recursive: true, force: true });
-    }
-}
-/**
- * Install a plugin from a local path
- */
-async function installFromLocal(sourcePath, targetPath) {
-    if (!(await pathExists(sourcePath))) {
-        throw new Error(`Source path does not exist: ${sourcePath}`);
-    }
-    await copyDir(sourcePath, targetPath);
-    const gitPath = join(targetPath, '.git');
-    await rm(gitPath, { recursive: true, force: true });
-}
-/**
- * Generate a temporary cache name for a plugin
- */
-export function generateTemporaryCacheNameForPlugin(source) {
-    const timestamp = Date.now();
-    const random = Math.random().toString(36).substring(2, 8);
-    let prefix;
-    if (typeof source === 'string') {
-        prefix = 'local';
-    }
-    else {
-        switch (source.source) {
-            case 'npm':
-                prefix = 'npm';
-                break;
-            case 'pip':
-                prefix = 'pip';
-                break;
-            case 'github':
-                prefix = 'github';
-                break;
-            case 'url':
-                prefix = 'git';
-                break;
-            case 'git-subdir':
-                prefix = 'subdir';
-                break;
-            default:
-                prefix = 'unknown';
-        }
-    }
-    return `temp_${prefix}_${timestamp}_${random}`;
-}
-/**
- * Cache a plugin from an external source
- */
-export async function cachePlugin(source, options) {
-    const cachePath = getPluginCachePath();
-    await getFsImplementation().mkdir(cachePath);
-    const tempName = generateTemporaryCacheNameForPlugin(source);
-    const tempPath = join(cachePath, tempName);
-    let shouldCleanup = false;
-    let gitCommitSha;
-    try {
-        logForDebugging(`Caching plugin from source: ${jsonStringify(source)} to temporary path ${tempPath}`);
-        shouldCleanup = true;
-        if (typeof source === 'string') {
-            await installFromLocal(source, tempPath);
-        }
-        else {
-            switch (source.source) {
-                case 'npm':
-                    await installFromNpm(source.package, tempPath, {
-                        registry: source.registry,
-                        version: source.version,
-                    });
-                    break;
-                case 'github':
-                    await installFromGitHub(source.repo, tempPath, source.ref, source.sha);
-                    break;
-                case 'url':
-                    await installFromGit(source.url, tempPath, source.ref, source.sha);
-                    break;
-                case 'git-subdir':
-                    gitCommitSha = await installFromGitSubdir(source.url, tempPath, source.path, source.ref, source.sha);
-                    break;
-                case 'pip':
-                    throw new Error('Python package plugins are not yet supported');
-                default:
-                    throw new Error(`Unsupported plugin source type`);
-            }
-        }
-    }
-    catch (error) {
-        if (shouldCleanup && (await pathExists(tempPath))) {
-            logForDebugging(`Cleaning up failed installation at ${tempPath}`);
-            try {
-                await rm(tempPath, { recursive: true, force: true });
-            }
-            catch (cleanupError) {
-                logForDebugging(`Failed to clean up installation: ${cleanupError}`, {
-                    level: 'error',
-                });
-            }
-        }
-        throw error;
-    }
-    const manifestPath = join(tempPath, '.claude-plugin', 'plugin.json');
-    const legacyManifestPath = join(tempPath, 'plugin.json');
-    let manifest;
-    if (await pathExists(manifestPath)) {
-        try {
-            const content = await readFile(manifestPath, { encoding: 'utf-8' });
-            const parsed = jsonParse(content);
-            const result = PluginManifestSchema().safeParse(parsed);
-            if (result.success) {
-                manifest = result.data;
-            }
-            else {
-                // Manifest exists but is invalid - throw error
-                const errors = result.error.issues
-                    .map(err => `${err.path.join('.')}: ${err.message}`)
-                    .join(', ');
-                logForDebugging(`Invalid manifest at ${manifestPath}: ${errors}`, {
-                    level: 'error',
-                });
-                throw new Error(`Plugin has an invalid manifest file at ${manifestPath}. Validation errors: ${errors}`);
-            }
-        }
-        catch (error) {
-            // Check if this is a validation error we just threw
-            if (error instanceof Error &&
-                error.message.includes('invalid manifest file')) {
-                throw error;
-            }
-            // JSON parse error
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to parse manifest at ${manifestPath}: ${errorMsg}`, {
-                level: 'error',
-            });
-            throw new Error(`Plugin has a corrupt manifest file at ${manifestPath}. JSON parse error: ${errorMsg}`);
-        }
-    }
-    else if (await pathExists(legacyManifestPath)) {
-        try {
-            const content = await readFile(legacyManifestPath, {
-                encoding: 'utf-8',
-            });
-            const parsed = jsonParse(content);
-            const result = PluginManifestSchema().safeParse(parsed);
-            if (result.success) {
-                manifest = result.data;
-            }
-            else {
-                // Manifest exists but is invalid - throw error
-                const errors = result.error.issues
-                    .map(err => `${err.path.join('.')}: ${err.message}`)
-                    .join(', ');
-                logForDebugging(`Invalid legacy manifest at ${legacyManifestPath}: ${errors}`, { level: 'error' });
-                throw new Error(`Plugin has an invalid manifest file at ${legacyManifestPath}. Validation errors: ${errors}`);
-            }
-        }
-        catch (error) {
-            // Check if this is a validation error we just threw
-            if (error instanceof Error &&
-                error.message.includes('invalid manifest file')) {
-                throw error;
-            }
-            // JSON parse error
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to parse legacy manifest at ${legacyManifestPath}: ${errorMsg}`, {
-                level: 'error',
-            });
-            throw new Error(`Plugin has a corrupt manifest file at ${legacyManifestPath}. JSON parse error: ${errorMsg}`);
-        }
-    }
-    else {
-        manifest = options?.manifest || {
-            name: tempName,
-            description: `Plugin cached from ${typeof source === 'string' ? source : source.source}`,
-        };
-    }
-    const finalName = manifest.name.replace(/[^a-zA-Z0-9-_]/g, '-');
-    const finalPath = join(cachePath, finalName);
-    if (await pathExists(finalPath)) {
-        logForDebugging(`Removing old cached version at ${finalPath}`);
-        await rm(finalPath, { recursive: true, force: true });
-    }
-    await rename(tempPath, finalPath);
-    logForDebugging(`Successfully cached plugin ${manifest.name} to ${finalPath}`);
-    return {
-        path: finalPath,
-        manifest,
-        ...(gitCommitSha && { gitCommitSha }),
-    };
-}
-/**
- * Loads and validates a plugin manifest from a JSON file.
- *
- * The manifest provides metadata about the plugin including name, version,
- * description, author, and other optional fields. If no manifest exists,
- * a minimal one is created to allow the plugin to function.
- *
- * Example plugin.json:
- * ```json
- * {
- *   "name": "code-assistant",
- *   "version": "1.2.0",
- *   "description": "AI-powered code assistance tools",
- *   "author": {
- *     "name": "John Doe",
- *     "email": "john@example.com"
- *   },
- *   "keywords": ["coding", "ai", "assistant"],
- *   "homepage": "https://example.com/code-assistant",
- *   "hooks": "./custom-hooks.json",
- *   "commands": ["./extra-commands/*.md"]
- * }
- * ```
- */
-/**
- * Loads and validates a plugin manifest from a JSON file.
- *
- * The manifest provides metadata about the plugin including name, version,
- * description, author, and other optional fields. If no manifest exists,
- * a minimal one is created to allow the plugin to function.
- *
- * Unknown keys in the manifest are silently stripped (PluginManifestSchema
- * uses zod's default strip behavior, not .strict()). Type mismatches and
- * other validation errors still fail.
- *
- * Behavior:
- * - Missing file: Creates default with provided name and source
- * - Invalid JSON: Throws error with parse details
- * - Schema validation failure: Throws error with validation details
- *
- * @param manifestPath - Full path to the plugin.json file
- * @param pluginName - Name to use in default manifest (e.g., "my-plugin")
- * @param source - Source description for default manifest (e.g., "git:repo" or ".claude-plugin/name")
- * @returns A valid PluginManifest object (either loaded or default)
- * @throws Error if manifest exists but is invalid (corrupt JSON or schema validation failure)
- */
-export async function loadPluginManifest(manifestPath, pluginName, source) {
-    // Check if manifest file exists
-    // If not, create a minimal manifest to allow plugin to function
-    if (!(await pathExists(manifestPath))) {
-        // Return default manifest with provided name and source
-        return {
-            name: pluginName,
-            description: `Plugin from ${source}`,
-        };
-    }
-    try {
-        // Read and parse the manifest JSON file
-        const content = await readFile(manifestPath, { encoding: 'utf-8' });
-        const parsedJson = jsonParse(content);
-        // Validate against the PluginManifest schema
-        const result = PluginManifestSchema().safeParse(parsedJson);
-        if (result.success) {
-            // Valid manifest - return the validated data
-            return result.data;
-        }
-        // Schema validation failed but JSON was valid
-        const errors = result.error.issues
-            .map(err => err.path.length > 0
-            ? `${err.path.join('.')}: ${err.message}`
-            : err.message)
-            .join(', ');
-        logForDebugging(`Plugin ${pluginName} has an invalid manifest file at ${manifestPath}. Validation errors: ${errors}`, { level: 'error' });
-        throw new Error(`Plugin ${pluginName} has an invalid manifest file at ${manifestPath}.\n\nValidation errors: ${errors}`);
-    }
-    catch (error) {
-        // Check if this is the error we just threw (validation error)
-        if (error instanceof Error &&
-            error.message.includes('invalid manifest file')) {
-            throw error;
-        }
-        // JSON parsing failed or file read error
-        const errorMsg = errorMessage(error);
-        logForDebugging(`Plugin ${pluginName} has a corrupt manifest file at ${manifestPath}. Parse error: ${errorMsg}`, { level: 'error' });
-        throw new Error(`Plugin ${pluginName} has a corrupt manifest file at ${manifestPath}.\n\nJSON parse error: ${errorMsg}`);
-    }
-}
-/**
- * Loads and validates plugin hooks configuration from a JSON file.
- * IMPORTANT: Only call this when the hooks file is expected to exist.
- *
- * @param hooksConfigPath - Full path to the hooks.json file
- * @param pluginName - Plugin name for error messages
- * @returns Validated HooksSettings
- * @throws Error if file doesn't exist or is invalid
- */
-async function loadPluginHooks(hooksConfigPath, pluginName) {
-    if (!(await pathExists(hooksConfigPath))) {
-        throw new Error(`Hooks file not found at ${hooksConfigPath} for plugin ${pluginName}. If the manifest declares hooks, the file must exist.`);
-    }
-    const content = await readFile(hooksConfigPath, { encoding: 'utf-8' });
-    const rawHooksConfig = jsonParse(content);
-    // The hooks.json file has a wrapper structure with description and hooks
-    // Use PluginHooksSchema to validate and extract the hooks property
-    const validatedPluginHooks = PluginHooksSchema().parse(rawHooksConfig);
-    return validatedPluginHooks.hooks;
-}
-/**
- * Validate a list of plugin component relative paths by checking existence in parallel.
- *
- * This helper parallelizes the pathExists checks (the expensive async part) while
- * preserving deterministic error/log ordering by iterating results sequentially.
- *
- * Introduced to fix a perf regression from the sync→async fs migration: sequential
- * `for { await pathExists }` loops add ~1-5ms of event-loop overhead per iteration.
- * With many plugins × several component types, this compounds to hundreds of ms.
- *
- * @param relPaths - Relative paths from the manifest/marketplace entry to validate
- * @param pluginPath - Plugin root directory to resolve relative paths against
- * @param pluginName - Plugin name for error messages
- * @param source - Source identifier for PluginError records
- * @param component - Which component these paths belong to (for error records)
- * @param componentLabel - Human-readable label for log messages (e.g. "Agent", "Skill")
- * @param contextLabel - Where the path came from, for log messages
- *   (e.g. "specified in manifest but", "from marketplace entry")
- * @param errors - Error array to push path-not-found errors into (mutated)
- * @returns Array of full paths that exist on disk, in original order
- */
-async function validatePluginPaths(relPaths, pluginPath, pluginName, source, component, componentLabel, contextLabel, errors) {
-    // Parallelize the async pathExists checks
-    const checks = await Promise.all(relPaths.map(async (relPath) => {
-        const fullPath = join(pluginPath, relPath);
-        return { relPath, fullPath, exists: await pathExists(fullPath) };
-    }));
-    // Process results in original order to keep error/log ordering deterministic
-    const validPaths = [];
-    for (const { relPath, fullPath, exists } of checks) {
-        if (exists) {
-            validPaths.push(fullPath);
-        }
-        else {
-            logForDebugging(`${componentLabel} path ${relPath} ${contextLabel} not found at ${fullPath} for ${pluginName}`, { level: 'warn' });
-            logError(new Error(`Plugin component file not found: ${fullPath} for ${pluginName}`));
-            errors.push({
-                type: 'path-not-found',
-                source,
-                plugin: pluginName,
-                path: fullPath,
-                component,
-            });
-        }
-    }
-    return validPaths;
-}
-/**
- * Creates a LoadedPlugin object from a plugin directory path.
- *
- * This is the central function that assembles a complete plugin representation
- * by scanning the plugin directory structure and loading all components.
- * It handles both fully-featured plugins with manifests and minimal plugins
- * with just commands or agents directories.
- *
- * Directory structure it looks for:
- * ```
- * plugin-directory/
- * ├── plugin.json          # Optional: Plugin manifest
- * ├── commands/            # Optional: Custom slash commands
- * │   ├── build.md         # /build command
- * │   └── test.md          # /test command
- * ├── agents/              # Optional: Custom AI agents
- * │   ├── reviewer.md      # Code review agent
- * │   └── optimizer.md     # Performance optimization agent
- * └── hooks/               # Optional: Hook configurations
- *     └── hooks.json       # Hook definitions
- * ```
- *
- * Component detection:
- * - Manifest: Loaded from plugin.json if present, otherwise creates default
- * - Commands: Sets commandsPath if commands/ directory exists
- * - Agents: Sets agentsPath if agents/ directory exists
- * - Hooks: Loads from hooks/hooks.json if present
- *
- * The function is tolerant of missing components - a plugin can have
- * any combination of the above directories/files. Missing component files
- * are reported as errors but don't prevent plugin loading.
- *
- * @param pluginPath - Absolute path to the plugin directory
- * @param source - Source identifier (e.g., "git:repo", ".claude-plugin/my-plugin")
- * @param enabled - Initial enabled state (may be overridden by settings)
- * @param fallbackName - Name to use if manifest doesn't specify one
- * @param strict - When true, adds errors for duplicate hook files (default: true)
- * @returns Object containing the LoadedPlugin and any errors encountered
- */
-export async function createPluginFromPath(pluginPath, source, enabled, fallbackName, strict = true) {
-    const errors = [];
-    // Step 1: Load or create the plugin manifest
-    // This provides metadata about the plugin (name, version, etc.)
-    const manifestPath = join(pluginPath, '.claude-plugin', 'plugin.json');
-    const manifest = await loadPluginManifest(manifestPath, fallbackName, source);
-    // Step 2: Create the base plugin object
-    // Start with required fields from manifest and parameters
-    const plugin = {
-        name: manifest.name, // Use name from manifest (or fallback)
-        manifest, // Store full manifest for later use
-        path: pluginPath, // Absolute path to plugin directory
-        source, // Source identifier (e.g., "git:repo" or ".claude-plugin/name")
-        repository: source, // For backward compatibility with Plugin Repository
-        enabled, // Current enabled state
-    };
-    // Step 3: Auto-detect optional directories in parallel
-    const [commandsDirExists, agentsDirExists, skillsDirExists, outputStylesDirExists,] = await Promise.all([
-        !manifest.commands ? pathExists(join(pluginPath, 'commands')) : false,
-        !manifest.agents ? pathExists(join(pluginPath, 'agents')) : false,
-        !manifest.skills ? pathExists(join(pluginPath, 'skills')) : false,
-        !manifest.outputStyles
-            ? pathExists(join(pluginPath, 'output-styles'))
-            : false,
-    ]);
-    const commandsPath = join(pluginPath, 'commands');
-    if (commandsDirExists) {
-        plugin.commandsPath = commandsPath;
-    }
-    // Step 3a: Process additional command paths from manifest
-    if (manifest.commands) {
-        // Check if it's an object mapping (record of command name → metadata)
-        const firstValue = Object.values(manifest.commands)[0];
-        if (typeof manifest.commands === 'object' &&
-            !Array.isArray(manifest.commands) &&
-            firstValue &&
-            typeof firstValue === 'object' &&
-            ('source' in firstValue || 'content' in firstValue)) {
-            // Object mapping format: { "about": { "source": "./README.md", ... } }
-            const commandsMetadata = {};
-            const validPaths = [];
-            // Parallelize pathExists checks; process results in order to keep
-            // error/log ordering deterministic.
-            const entries = Object.entries(manifest.commands);
-            const checks = await Promise.all(entries.map(async ([commandName, metadata]) => {
-                if (!metadata || typeof metadata !== 'object') {
-                    return { commandName, metadata, kind: 'skip' };
-                }
-                if (metadata.source) {
-                    const fullPath = join(pluginPath, metadata.source);
-                    return {
-                        commandName,
-                        metadata,
-                        kind: 'source',
-                        fullPath,
-                        exists: await pathExists(fullPath),
-                    };
-                }
-                if (metadata.content) {
-                    return { commandName, metadata, kind: 'content' };
-                }
-                return { commandName, metadata, kind: 'skip' };
-            }));
-            for (const check of checks) {
-                if (check.kind === 'skip')
-                    continue;
-                if (check.kind === 'content') {
-                    // For inline content commands, add metadata without path
-                    commandsMetadata[check.commandName] = check.metadata;
-                    continue;
-                }
-                // kind === 'source'
-                if (check.exists) {
-                    validPaths.push(check.fullPath);
-                    commandsMetadata[check.commandName] = check.metadata;
-                }
-                else {
-                    logForDebugging(`Command ${check.commandName} path ${check.metadata.source} specified in manifest but not found at ${check.fullPath} for ${manifest.name}`, { level: 'warn' });
-                    logError(new Error(`Plugin component file not found: ${check.fullPath} for ${manifest.name}`));
-                    errors.push({
-                        type: 'path-not-found',
-                        source,
-                        plugin: manifest.name,
-                        path: check.fullPath,
-                        component: 'commands',
-                    });
-                }
-            }
-            // Set commandsPaths if there are file-based commands
-            if (validPaths.length > 0) {
-                plugin.commandsPaths = validPaths;
-            }
-            // Set commandsMetadata if there are any commands (file-based or inline)
-            if (Object.keys(commandsMetadata).length > 0) {
-                plugin.commandsMetadata = commandsMetadata;
-            }
-        }
-        else {
-            // Path or array of paths format
-            const commandPaths = Array.isArray(manifest.commands)
-                ? manifest.commands
-                : [manifest.commands];
-            // Parallelize pathExists checks; process results in order.
-            const checks = await Promise.all(commandPaths.map(async (cmdPath) => {
-                if (typeof cmdPath !== 'string') {
-                    return { cmdPath, kind: 'invalid' };
-                }
-                const fullPath = join(pluginPath, cmdPath);
-                return {
-                    cmdPath,
-                    kind: 'path',
-                    fullPath,
-                    exists: await pathExists(fullPath),
-                };
-            }));
-            const validPaths = [];
-            for (const check of checks) {
-                if (check.kind === 'invalid') {
-                    logForDebugging(`Unexpected command format in manifest for ${manifest.name}`, { level: 'error' });
-                    continue;
-                }
-                if (check.exists) {
-                    validPaths.push(check.fullPath);
-                }
-                else {
-                    logForDebugging(`Command path ${check.cmdPath} specified in manifest but not found at ${check.fullPath} for ${manifest.name}`, { level: 'warn' });
-                    logError(new Error(`Plugin component file not found: ${check.fullPath} for ${manifest.name}`));
-                    errors.push({
-                        type: 'path-not-found',
-                        source,
-                        plugin: manifest.name,
-                        path: check.fullPath,
-                        component: 'commands',
-                    });
-                }
-            }
-            if (validPaths.length > 0) {
-                plugin.commandsPaths = validPaths;
-            }
-        }
-    }
-    // Step 4: Register agents directory if detected
-    const agentsPath = join(pluginPath, 'agents');
-    if (agentsDirExists) {
-        plugin.agentsPath = agentsPath;
-    }
-    // Step 4a: Process additional agent paths from manifest
-    if (manifest.agents) {
-        const agentPaths = Array.isArray(manifest.agents)
-            ? manifest.agents
-            : [manifest.agents];
-        const validPaths = await validatePluginPaths(agentPaths, pluginPath, manifest.name, source, 'agents', 'Agent', 'specified in manifest but', errors);
-        if (validPaths.length > 0) {
-            plugin.agentsPaths = validPaths;
-        }
-    }
-    // Step 4b: Register skills directory if detected
-    const skillsPath = join(pluginPath, 'skills');
-    if (skillsDirExists) {
-        plugin.skillsPath = skillsPath;
-    }
-    // Step 4c: Process additional skill paths from manifest
-    if (manifest.skills) {
-        const skillPaths = Array.isArray(manifest.skills)
-            ? manifest.skills
-            : [manifest.skills];
-        const validPaths = await validatePluginPaths(skillPaths, pluginPath, manifest.name, source, 'skills', 'Skill', 'specified in manifest but', errors);
-        if (validPaths.length > 0) {
-            plugin.skillsPaths = validPaths;
-        }
-    }
-    // Step 4d: Register output-styles directory if detected
-    const outputStylesPath = join(pluginPath, 'output-styles');
-    if (outputStylesDirExists) {
-        plugin.outputStylesPath = outputStylesPath;
-    }
-    // Step 4e: Process additional output style paths from manifest
-    if (manifest.outputStyles) {
-        const outputStylePaths = Array.isArray(manifest.outputStyles)
-            ? manifest.outputStyles
-            : [manifest.outputStyles];
-        const validPaths = await validatePluginPaths(outputStylePaths, pluginPath, manifest.name, source, 'output-styles', 'Output style', 'specified in manifest but', errors);
-        if (validPaths.length > 0) {
-            plugin.outputStylesPaths = validPaths;
-        }
-    }
-    // Step 5: Load hooks configuration
-    let mergedHooks;
-    const loadedHookPaths = new Set(); // Track loaded hook files
-    // Load from standard hooks/hooks.json if it exists
-    const standardHooksPath = join(pluginPath, 'hooks', 'hooks.json');
-    if (await pathExists(standardHooksPath)) {
-        try {
-            mergedHooks = await loadPluginHooks(standardHooksPath, manifest.name);
-            // Track the normalized path to prevent duplicate loading
-            try {
-                loadedHookPaths.add(await realpath(standardHooksPath));
-            }
-            catch {
-                // If realpathSync fails, use original path
-                loadedHookPaths.add(standardHooksPath);
-            }
-            logForDebugging(`Loaded hooks from standard location for plugin ${manifest.name}: ${standardHooksPath}`);
-        }
-        catch (error) {
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to load hooks for ${manifest.name}: ${errorMsg}`, {
-                level: 'error',
-            });
-            logError(toError(error));
-            errors.push({
-                type: 'hook-load-failed',
-                source,
-                plugin: manifest.name,
-                hookPath: standardHooksPath,
-                reason: errorMsg,
-            });
-        }
-    }
-    // Load and merge hooks from manifest.hooks if specified
-    if (manifest.hooks) {
-        const manifestHooksArray = Array.isArray(manifest.hooks)
-            ? manifest.hooks
-            : [manifest.hooks];
-        for (const hookSpec of manifestHooksArray) {
-            if (typeof hookSpec === 'string') {
-                // Path to additional hooks file
-                const hookFilePath = join(pluginPath, hookSpec);
-                if (!(await pathExists(hookFilePath))) {
-                    logForDebugging(`Hooks file ${hookSpec} specified in manifest but not found at ${hookFilePath} for ${manifest.name}`, { level: 'error' });
-                    logError(new Error(`Plugin component file not found: ${hookFilePath} for ${manifest.name}`));
-                    errors.push({
-                        type: 'path-not-found',
-                        source,
-                        plugin: manifest.name,
-                        path: hookFilePath,
-                        component: 'hooks',
-                    });
-                    continue;
-                }
-                // Check if this path resolves to an already-loaded hooks file
-                let normalizedPath;
-                try {
-                    normalizedPath = await realpath(hookFilePath);
-                }
-                catch {
-                    // If realpathSync fails, use original path
-                    normalizedPath = hookFilePath;
-                }
-                if (loadedHookPaths.has(normalizedPath)) {
-                    logForDebugging(`Skipping duplicate hooks file for plugin ${manifest.name}: ${hookSpec} ` +
-                        `(resolves to already-loaded file: ${normalizedPath})`);
-                    if (strict) {
-                        const errorMsg = `Duplicate hooks file detected: ${hookSpec} resolves to already-loaded file ${normalizedPath}. The standard hooks/hooks.json is loaded automatically, so manifest.hooks should only reference additional hook files.`;
-                        logError(new Error(errorMsg));
-                        errors.push({
-                            type: 'hook-load-failed',
-                            source,
-                            plugin: manifest.name,
-                            hookPath: hookFilePath,
-                            reason: errorMsg,
-                        });
-                    }
-                    continue;
-                }
-                try {
-                    const additionalHooks = await loadPluginHooks(hookFilePath, manifest.name);
-                    try {
-                        mergedHooks = mergeHooksSettings(mergedHooks, additionalHooks);
-                        loadedHookPaths.add(normalizedPath);
-                        logForDebugging(`Loaded and merged hooks from manifest for plugin ${manifest.name}: ${hookSpec}`);
-                    }
-                    catch (mergeError) {
-                        const mergeErrorMsg = errorMessage(mergeError);
-                        logForDebugging(`Failed to merge hooks from ${hookSpec} for ${manifest.name}: ${mergeErrorMsg}`, { level: 'error' });
-                        logError(toError(mergeError));
-                        errors.push({
-                            type: 'hook-load-failed',
-                            source,
-                            plugin: manifest.name,
-                            hookPath: hookFilePath,
-                            reason: `Failed to merge: ${mergeErrorMsg}`,
-                        });
-                    }
-                }
-                catch (error) {
-                    const errorMsg = errorMessage(error);
-                    logForDebugging(`Failed to load hooks from ${hookSpec} for ${manifest.name}: ${errorMsg}`, { level: 'error' });
-                    logError(toError(error));
-                    errors.push({
-                        type: 'hook-load-failed',
-                        source,
-                        plugin: manifest.name,
-                        hookPath: hookFilePath,
-                        reason: errorMsg,
-                    });
-                }
-            }
-            else if (typeof hookSpec === 'object') {
-                // Inline hooks
-                mergedHooks = mergeHooksSettings(mergedHooks, hookSpec);
-            }
-        }
-    }
-    if (mergedHooks) {
-        plugin.hooksConfig = mergedHooks;
-    }
-    // Step 6: Load plugin settings
-    // Settings can come from settings.json in the plugin directory or from manifest.settings
-    // Only allowlisted keys are kept (currently: agent)
-    const pluginSettings = await loadPluginSettings(pluginPath, manifest);
-    if (pluginSettings) {
-        plugin.settings = pluginSettings;
-    }
-    return { plugin, errors };
-}
-/**
- * Schema derived from SettingsSchema that only keeps keys plugins are allowed to set.
- * Uses .strip() so unknown keys are silently removed during parsing.
- */
-const PluginSettingsSchema = lazySchema(() => SettingsSchema()
-    .pick({
-    agent: true,
-})
-    .strip());
-/**
- * Parse raw settings through PluginSettingsSchema, returning only allowlisted keys.
- * Returns undefined if parsing fails or all keys are filtered out.
- */
-function parsePluginSettings(raw) {
-    const result = PluginSettingsSchema().safeParse(raw);
-    if (!result.success) {
-        return undefined;
-    }
-    const data = result.data;
-    if (Object.keys(data).length === 0) {
-        return undefined;
-    }
-    return data;
-}
-/**
- * Load plugin settings from settings.json file or manifest.settings.
- * settings.json takes priority over manifest.settings when both exist.
- * Only allowlisted keys are included in the result.
- */
-async function loadPluginSettings(pluginPath, manifest) {
-    // Try loading settings.json from the plugin directory
-    const settingsJsonPath = join(pluginPath, 'settings.json');
-    try {
-        const content = await readFile(settingsJsonPath, { encoding: 'utf-8' });
-        const parsed = jsonParse(content);
-        if (isRecord(parsed)) {
-            const filtered = parsePluginSettings(parsed);
-            if (filtered) {
-                logForDebugging(`Loaded settings from settings.json for plugin ${manifest.name}`);
-                return filtered;
-            }
-        }
-    }
-    catch (e) {
-        // Missing/inaccessible is expected - settings.json is optional
-        if (!isFsInaccessible(e)) {
-            logForDebugging(`Failed to parse settings.json for plugin ${manifest.name}: ${e}`, { level: 'warn' });
-        }
-    }
-    // Fall back to manifest.settings
-    if (manifest.settings) {
-        const filtered = parsePluginSettings(manifest.settings);
-        if (filtered) {
-            logForDebugging(`Loaded settings from manifest for plugin ${manifest.name}`);
-            return filtered;
-        }
-    }
-    return undefined;
-}
-/**
- * Merge two HooksSettings objects
- */
-function mergeHooksSettings(base, additional) {
-    if (!base) {
-        return additional;
-    }
-    const merged = { ...base };
-    for (const [event, matchers] of Object.entries(additional)) {
-        if (!merged[event]) {
-            merged[event] = matchers;
-        }
-        else {
-            // Merge matchers for this event
-            merged[event] = [
-                ...(merged[event] || []),
-                ...matchers,
-            ];
-        }
-    }
-    return merged;
-}
-/**
- * Shared discovery/policy/merge pipeline for both load modes.
- *
- * Resolves enabledPlugins → marketplace entries, runs enterprise policy
- * checks, pre-loads catalogs, then dispatches each entry to the full or
- * cache-only per-entry loader. The ONLY difference between loadAllPlugins
- * and loadAllPluginsCacheOnly is which loader runs — discovery and policy
- * are identical.
- */
-async function loadPluginsFromMarketplaces({ cacheOnly, }) {
-    const settings = getSettings_DEPRECATED();
-    // Merge --add-dir plugins at lowest priority; standard settings win on conflict
-    const enabledPlugins = {
-        ...getAddDirEnabledPlugins(),
-        ...(settings.enabledPlugins || {}),
-    };
-    const plugins = [];
-    const errors = [];
-    // Filter to plugin@marketplace format and validate
-    const marketplacePluginEntries = Object.entries(enabledPlugins).filter(([key, value]) => {
-        // Check if it's in plugin@marketplace format (includes both enabled and disabled)
-        const isValidFormat = PluginIdSchema().safeParse(key).success;
-        if (!isValidFormat || value === undefined)
-            return false;
-        // Skip built-in plugins — handled separately by getBuiltinPlugins()
-        const { marketplace } = parsePluginIdentifier(key);
-        return marketplace !== BUILTIN_MARKETPLACE_NAME;
-    });
-    // Load known marketplaces config to look up sources for policy checking.
-    // Use the Safe variant so a corrupted config file doesn't crash all plugin
-    // loading — this is a read-only path, so returning {} degrades gracefully.
-    const knownMarketplaces = await loadKnownMarketplacesConfigSafe();
-    // Fail-closed guard for enterprise policy: if a policy IS configured and we
-    // cannot resolve a marketplace's source (config returned {} due to corruption,
-    // or entry missing), we must NOT silently skip the policy check and load the
-    // plugin anyway. Before Safe, a corrupted config crashed everything (loud,
-    // fail-closed). With Safe + no guard, the policy check short-circuits on
-    // undefined marketplaceConfig and the fallback path (getPluginByIdCacheOnly)
-    // loads the plugin unchecked — a silent fail-open. This guard restores
-    // fail-closed: unknown source + active policy → block.
-    //
-    // Allowlist: any value (including []) is active — empty allowlist = deny all.
-    // Blocklist: empty [] is a semantic no-op — only non-empty counts as active.
-    const strictAllowlist = getStrictKnownMarketplaces();
-    const blocklist = getBlockedMarketplaces();
-    const hasEnterprisePolicy = strictAllowlist !== null || (blocklist !== null && blocklist.length > 0);
-    // Pre-load marketplace catalogs once per marketplace rather than re-reading
-    // known_marketplaces.json + marketplace.json for every plugin. This is the
-    // hot path — with N plugins across M marketplaces, the old per-plugin
-    // getPluginByIdCacheOnly() did 2N config reads + N catalog reads; this does M.
-    const uniqueMarketplaces = new Set(marketplacePluginEntries
-        .map(([pluginId]) => parsePluginIdentifier(pluginId).marketplace)
-        .filter((m) => !!m));
-    const marketplaceCatalogs = new Map();
-    await Promise.all([...uniqueMarketplaces].map(async (name) => {
-        marketplaceCatalogs.set(name, await getMarketplaceCacheOnly(name));
-    }));
-    // Look up installed versions once so the first-pass ZIP cache check
-    // can hit even when the marketplace entry omits `version`.
-    const installedPluginsData = getInMemoryInstalledPlugins();
-    // Load all marketplace plugins in parallel for faster startup
-    const results = await Promise.allSettled(marketplacePluginEntries.map(async ([pluginId, enabledValue]) => {
-        const { name: pluginName, marketplace: marketplaceName } = parsePluginIdentifier(pluginId);
-        // Check if marketplace source is allowed by enterprise policy
-        const marketplaceConfig = knownMarketplaces[marketplaceName];
-        // Fail-closed: if enterprise policy is active and we can't look up the
-        // marketplace source (config corrupted/empty, or entry missing), block
-        // rather than silently skip the policy check. See hasEnterprisePolicy
-        // comment above for the fail-open hazard this guards against.
-        //
-        // This also fires for the "stale enabledPlugins entry with no registered
-        // marketplace" case, which is a UX trade-off: the user gets a policy
-        // error instead of plugin-not-found. Accepted because the fallback path
-        // (getPluginByIdCacheOnly) does a raw cast of known_marketplaces.json
-        // with NO schema validation — if one entry is malformed enough to fail
-        // our validation but readable enough for the raw cast, it would load
-        // unchecked. Unverifiable source + active policy → block, always.
-        if (!marketplaceConfig && hasEnterprisePolicy) {
-            // We can't know whether the unverifiable source would actually be in
-            // the blocklist or not in the allowlist — so pick the error variant
-            // that matches whichever policy IS configured. If an allowlist exists,
-            // "not in allowed list" is the right framing; if only a blocklist
-            // exists, "blocked by blocklist" is less misleading than showing an
-            // empty allowed-sources list.
-            errors.push({
-                type: 'marketplace-blocked-by-policy',
-                source: pluginId,
-                plugin: pluginName,
-                marketplace: marketplaceName,
-                blockedByBlocklist: strictAllowlist === null,
-                allowedSources: (strictAllowlist ?? []).map(s => formatSourceForDisplay(s)),
-            });
-            return null;
-        }
-        if (marketplaceConfig &&
-            !isSourceAllowedByPolicy(marketplaceConfig.source)) {
-            // Check if explicitly blocked vs not in allowlist for better error context
-            const isBlocked = isSourceInBlocklist(marketplaceConfig.source);
-            const allowlist = getStrictKnownMarketplaces() || [];
-            errors.push({
-                type: 'marketplace-blocked-by-policy',
-                source: pluginId,
-                plugin: pluginName,
-                marketplace: marketplaceName,
-                blockedByBlocklist: isBlocked,
-                allowedSources: isBlocked
-                    ? []
-                    : allowlist.map(s => formatSourceForDisplay(s)),
-            });
-            return null;
-        }
-        // Look up plugin entry from pre-loaded marketplace catalog (no per-plugin I/O).
-        // Fall back to getPluginByIdCacheOnly if the catalog couldn't be pre-loaded.
-        let result = null;
-        const marketplace = marketplaceCatalogs.get(marketplaceName);
-        if (marketplace && marketplaceConfig) {
-            const entry = marketplace.plugins.find(p => p.name === pluginName);
-            if (entry) {
-                result = {
-                    entry,
-                    marketplaceInstallLocation: marketplaceConfig.installLocation,
-                };
-            }
-        }
-        else {
-            result = await getPluginByIdCacheOnly(pluginId);
-        }
-        if (!result) {
-            errors.push({
-                type: 'plugin-not-found',
-                source: pluginId,
-                pluginId: pluginName,
-                marketplace: marketplaceName,
-            });
-            return null;
-        }
-        // installed_plugins.json records what's actually cached on disk
-        // (version for the full loader's first-pass probe, installPath for
-        // the cache-only loader's direct read).
-        const installEntry = installedPluginsData.plugins[pluginId]?.[0];
-        return cacheOnly
-            ? loadPluginFromMarketplaceEntryCacheOnly(result.entry, result.marketplaceInstallLocation, pluginId, enabledValue === true, errors, installEntry?.installPath)
-            : loadPluginFromMarketplaceEntry(result.entry, result.marketplaceInstallLocation, pluginId, enabledValue === true, errors, installEntry?.version);
-    }));
-    for (const [i, result] of results.entries()) {
-        if (result.status === 'fulfilled' && result.value) {
-            plugins.push(result.value);
-        }
-        else if (result.status === 'rejected') {
-            const err = toError(result.reason);
-            logError(err);
-            const pluginId = marketplacePluginEntries[i][0];
-            errors.push({
-                type: 'generic-error',
-                source: pluginId,
-                plugin: pluginId.split('@')[0],
-                error: err.message,
-            });
-        }
-    }
-    return { plugins, errors };
-}
-/**
- * Cache-only variant of loadPluginFromMarketplaceEntry.
- *
- * Skips network (cachePlugin) and disk-copy (copyPluginToVersionedCache).
- * Reads directly from the recorded installPath; if missing, emits
- * 'plugin-cache-miss'. Still extracts ZIP-cached plugins (local, fast).
- */
-async function loadPluginFromMarketplaceEntryCacheOnly(entry, marketplaceInstallLocation, pluginId, enabled, errorsOut, installPath) {
-    let pluginPath;
-    if (typeof entry.source === 'string') {
-        // Local relative path — read from the marketplace source dir directly.
-        // Skip copyPluginToVersionedCache; startup doesn't need a fresh copy.
-        let marketplaceDir;
-        try {
-            marketplaceDir = (await stat(marketplaceInstallLocation)).isDirectory()
-                ? marketplaceInstallLocation
-                : join(marketplaceInstallLocation, '..');
-        }
-        catch {
-            errorsOut.push({
-                type: 'plugin-cache-miss',
-                source: pluginId,
-                plugin: entry.name,
-                installPath: marketplaceInstallLocation,
-            });
-            return null;
-        }
-        pluginPath = join(marketplaceDir, entry.source);
-        // finishLoadingPluginFromPath reads pluginPath — its error handling
-        // surfaces ENOENT as a load failure, no need to pre-check here.
-    }
-    else {
-        // External source (npm/github/url/git-subdir) — use recorded installPath.
-        if (!installPath || !(await pathExists(installPath))) {
-            errorsOut.push({
-                type: 'plugin-cache-miss',
-                source: pluginId,
-                plugin: entry.name,
-                installPath: installPath ?? '(not recorded)',
-            });
-            return null;
-        }
-        pluginPath = installPath;
-    }
-    // Zip cache extraction — must still happen in cacheOnly mode (invariant 4)
-    if (isPluginZipCacheEnabled() && pluginPath.endsWith('.zip')) {
-        const sessionDir = await getSessionPluginCachePath();
-        const extractDir = join(sessionDir, pluginId.replace(/[^a-zA-Z0-9@\-_]/g, '-'));
-        try {
-            await extractZipToDirectory(pluginPath, extractDir);
-            pluginPath = extractDir;
-        }
-        catch (error) {
-            logForDebugging(`Failed to extract plugin ZIP ${pluginPath}: ${error}`, {
-                level: 'error',
-            });
-            errorsOut.push({
-                type: 'plugin-cache-miss',
-                source: pluginId,
-                plugin: entry.name,
-                installPath: pluginPath,
-            });
-            return null;
-        }
-    }
-    // Delegate to the shared tail — identical to the full loader from here
-    return finishLoadingPluginFromPath(entry, pluginId, enabled, errorsOut, pluginPath);
-}
-/**
- * Load a plugin from a marketplace entry based on its source configuration.
- *
- * Handles different source types:
- * - Relative path: Loads from marketplace repo directory
- * - npm/github/url: Caches then loads from cache
- *
- * @param installedVersion - Version from installed_plugins.json, used as a
- *   first-pass hint for the versioned cache lookup when the marketplace entry
- *   omits `version`. Avoids re-cloning external plugins just to discover the
- *   version we already recorded at install time.
- *
- * Returns both the loaded plugin and any errors encountered during loading.
- * Errors include missing component files and hook load failures.
- */
-async function loadPluginFromMarketplaceEntry(entry, marketplaceInstallLocation, pluginId, enabled, errorsOut, installedVersion) {
-    logForDebugging(`Loading plugin ${entry.name} from source: ${jsonStringify(entry.source)}`);
-    let pluginPath;
-    if (typeof entry.source === 'string') {
-        // Relative path - resolve relative to marketplace install location
-        const marketplaceDir = (await stat(marketplaceInstallLocation)).isDirectory()
-            ? marketplaceInstallLocation
-            : join(marketplaceInstallLocation, '..');
-        const sourcePluginPath = join(marketplaceDir, entry.source);
-        if (!(await pathExists(sourcePluginPath))) {
-            const error = new Error(`Plugin path not found: ${sourcePluginPath}`);
-            logForDebugging(`Plugin path not found: ${sourcePluginPath}`, {
-                level: 'error',
-            });
-            logError(error);
-            errorsOut.push({
-                type: 'generic-error',
-                source: pluginId,
-                error: `Plugin directory not found at path: ${sourcePluginPath}. Check that the marketplace entry has the correct path.`,
-            });
-            return null;
-        }
-        // Always copy local plugins to versioned cache
-        try {
-            // Try to load manifest from plugin directory to check for version field first
-            const manifestPath = join(sourcePluginPath, '.claude-plugin', 'plugin.json');
-            let pluginManifest;
-            try {
-                pluginManifest = await loadPluginManifest(manifestPath, entry.name, entry.source);
-            }
-            catch {
-                // Manifest loading failed - will fall back to provided version or git SHA
-            }
-            // Calculate version with fallback order:
-            // 1. Plugin manifest version, 2. Marketplace entry version, 3. Git SHA, 4. 'unknown'
-            const version = await calculatePluginVersion(pluginId, entry.source, pluginManifest, marketplaceDir, entry.version);
-            // Copy to versioned cache
-            pluginPath = await copyPluginToVersionedCache(sourcePluginPath, pluginId, version, entry, marketplaceDir);
-            logForDebugging(`Resolved local plugin ${entry.name} to versioned cache: ${pluginPath}`);
-        }
-        catch (error) {
-            // If copy fails, fall back to loading from marketplace directly
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to copy plugin ${entry.name} to versioned cache: ${errorMsg}. Using marketplace path.`, { level: 'warn' });
-            pluginPath = sourcePluginPath;
-        }
-    }
-    else {
-        // External source (npm, github, url, pip) - always use versioned cache
-        try {
-            // Calculate version with fallback order:
-            // 1. No manifest yet, 2. installed_plugins.json version,
-            //    3. Marketplace entry version, 4. source.sha (pinned commits — the
-            //    exact value the post-clone call at cached.gitCommitSha would see),
-            //    5. 'unknown' → ref-tracked, falls through to clone by design.
-            const version = await calculatePluginVersion(pluginId, entry.source, undefined, undefined, installedVersion ?? entry.version, 'sha' in entry.source ? entry.source.sha : undefined);
-            const versionedPath = getVersionedCachePath(pluginId, version);
-            // Check for cached version — ZIP file (zip cache mode) or directory
-            const zipPath = getVersionedZipCachePath(pluginId, version);
-            if (isPluginZipCacheEnabled() && (await pathExists(zipPath))) {
-                logForDebugging(`Using versioned cached plugin ZIP ${entry.name} from ${zipPath}`);
-                pluginPath = zipPath;
-            }
-            else if (await pathExists(versionedPath)) {
-                logForDebugging(`Using versioned cached plugin ${entry.name} from ${versionedPath}`);
-                pluginPath = versionedPath;
-            }
-            else {
-                // Seed cache probe (CCR pre-baked images, read-only). Seed content is
-                // frozen at image build time — no freshness concern, 'whatever's there'
-                // is what the image builder put there. Primary cache is NOT probed
-                // here; ref-tracked sources fall through to clone (the re-clone IS
-                // the freshness mechanism). If the clone fails, the plugin is simply
-                // disabled for this session — errorsOut.push below surfaces it.
-                const seedPath = (await probeSeedCache(pluginId, version)) ??
-                    (version === 'unknown'
-                        ? await probeSeedCacheAnyVersion(pluginId)
-                        : null);
-                if (seedPath) {
-                    pluginPath = seedPath;
-                    logForDebugging(`Using seed cache for external plugin ${entry.name} at ${seedPath}`);
-                }
-                else {
-                    // Download to temp location, then copy to versioned cache
-                    const cached = await cachePlugin(entry.source, {
-                        manifest: { name: entry.name },
-                    });
-                    // If the pre-clone version was deterministic (source.sha /
-                    // entry.version / installedVersion), REUSE it. The post-clone
-                    // recomputation with cached.manifest can return a DIFFERENT value
-                    // — manifest.version (step 1) outranks gitCommitSha (step 3) —
-                    // which would cache at e.g. "2.0.0/" while every warm start
-                    // probes "{sha12}-{hash}/". Mismatched keys = re-clone forever.
-                    // Recomputation is only needed when pre-clone was 'unknown'
-                    // (ref-tracked, no hints) — the clone is the ONLY way to learn.
-                    const actualVersion = version !== 'unknown'
-                        ? version
-                        : await calculatePluginVersion(pluginId, entry.source, cached.manifest, cached.path, installedVersion ?? entry.version, cached.gitCommitSha);
-                    // Copy to versioned cache
-                    // For external sources, marketplaceDir is not applicable (already downloaded)
-                    pluginPath = await copyPluginToVersionedCache(cached.path, pluginId, actualVersion, entry, undefined);
-                    // Clean up temp path
-                    if (cached.path !== pluginPath) {
-                        await rm(cached.path, { recursive: true, force: true });
-                    }
-                }
-            }
-        }
-        catch (error) {
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to cache plugin ${entry.name}: ${errorMsg}`, {
-                level: 'error',
-            });
-            logError(toError(error));
-            errorsOut.push({
-                type: 'generic-error',
-                source: pluginId,
-                error: `Failed to download/cache plugin ${entry.name}: ${errorMsg}`,
-            });
-            return null;
-        }
-    }
-    // Zip cache mode: extract ZIP to session temp dir before loading
-    if (isPluginZipCacheEnabled() && pluginPath.endsWith('.zip')) {
-        const sessionDir = await getSessionPluginCachePath();
-        const extractDir = join(sessionDir, pluginId.replace(/[^a-zA-Z0-9@\-_]/g, '-'));
-        try {
-            await extractZipToDirectory(pluginPath, extractDir);
-            logForDebugging(`Extracted plugin ZIP to session dir: ${extractDir}`);
-            pluginPath = extractDir;
-        }
-        catch (error) {
-            // Corrupt ZIP: delete it so next install attempt re-creates it
-            logForDebugging(`Failed to extract plugin ZIP ${pluginPath}, deleting corrupt file: ${error}`);
-            await rm(pluginPath, { force: true }).catch(() => { });
-            throw error;
-        }
-    }
-    return finishLoadingPluginFromPath(entry, pluginId, enabled, errorsOut, pluginPath);
-}
-/**
- * Shared tail of both loadPluginFromMarketplaceEntry variants.
- *
- * Once pluginPath is resolved (via clone, cache, or installPath lookup),
- * the rest of the load — manifest probe, createPluginFromPath, marketplace
- * entry supplementation — is identical. Extracted so the cache-only path
- * doesn't duplicate ~500 lines.
- */
-async function finishLoadingPluginFromPath(entry, pluginId, enabled, errorsOut, pluginPath) {
-    const errors = [];
-    // Check if plugin.json exists to determine if we should use marketplace manifest
-    const manifestPath = join(pluginPath, '.claude-plugin', 'plugin.json');
-    const hasManifest = await pathExists(manifestPath);
-    const { plugin, errors: pluginErrors } = await createPluginFromPath(pluginPath, pluginId, enabled, entry.name, entry.strict ?? true);
-    errors.push(...pluginErrors);
-    // Set sha from source if available (for github and url source types)
-    if (typeof entry.source === 'object' &&
-        'sha' in entry.source &&
-        entry.source.sha) {
-        plugin.sha = entry.source.sha;
-    }
-    // If there's no plugin.json, use marketplace entry as manifest (regardless of strict mode)
-    if (!hasManifest) {
-        plugin.manifest = {
-            ...entry,
-            id: undefined,
-            source: undefined,
-            strict: undefined,
-        };
-        plugin.name = plugin.manifest.name;
-        // Process commands from marketplace entry
-        if (entry.commands) {
-            // Check if it's an object mapping
-            const firstValue = Object.values(entry.commands)[0];
-            if (typeof entry.commands === 'object' &&
-                !Array.isArray(entry.commands) &&
-                firstValue &&
-                typeof firstValue === 'object' &&
-                ('source' in firstValue || 'content' in firstValue)) {
-                // Object mapping format
-                const commandsMetadata = {};
-                const validPaths = [];
-                // Parallelize pathExists checks; process results in order.
-                const entries = Object.entries(entry.commands);
-                const checks = await Promise.all(entries.map(async ([commandName, metadata]) => {
-                    if (!metadata || typeof metadata !== 'object' || !metadata.source) {
-                        return { commandName, metadata, skip: true };
-                    }
-                    const fullPath = join(pluginPath, metadata.source);
-                    return {
-                        commandName,
-                        metadata,
-                        skip: false,
-                        fullPath,
-                        exists: await pathExists(fullPath),
-                    };
-                }));
-                for (const check of checks) {
-                    if (check.skip)
-                        continue;
-                    if (check.exists) {
-                        validPaths.push(check.fullPath);
-                        commandsMetadata[check.commandName] = check.metadata;
-                    }
-                    else {
-                        logForDebugging(`Command ${check.commandName} path ${check.metadata.source} from marketplace entry not found at ${check.fullPath} for ${entry.name}`, { level: 'warn' });
-                        logError(new Error(`Plugin component file not found: ${check.fullPath} for ${entry.name}`));
-                        errors.push({
-                            type: 'path-not-found',
-                            source: pluginId,
-                            plugin: entry.name,
-                            path: check.fullPath,
-                            component: 'commands',
-                        });
-                    }
-                }
-                if (validPaths.length > 0) {
-                    plugin.commandsPaths = validPaths;
-                    plugin.commandsMetadata = commandsMetadata;
-                }
-            }
-            else {
-                // Path or array of paths format
-                const commandPaths = Array.isArray(entry.commands)
-                    ? entry.commands
-                    : [entry.commands];
-                // Parallelize pathExists checks; process results in order.
-                const checks = await Promise.all(commandPaths.map(async (cmdPath) => {
-                    if (typeof cmdPath !== 'string') {
-                        return { cmdPath, kind: 'invalid' };
-                    }
-                    const fullPath = join(pluginPath, cmdPath);
-                    return {
-                        cmdPath,
-                        kind: 'path',
-                        fullPath,
-                        exists: await pathExists(fullPath),
-                    };
-                }));
-                const validPaths = [];
-                for (const check of checks) {
-                    if (check.kind === 'invalid') {
-                        logForDebugging(`Unexpected command format in marketplace entry for ${entry.name}`, { level: 'error' });
-                        continue;
-                    }
-                    if (check.exists) {
-                        validPaths.push(check.fullPath);
-                    }
-                    else {
-                        logForDebugging(`Command path ${check.cmdPath} from marketplace entry not found at ${check.fullPath} for ${entry.name}`, { level: 'warn' });
-                        logError(new Error(`Plugin component file not found: ${check.fullPath} for ${entry.name}`));
-                        errors.push({
-                            type: 'path-not-found',
-                            source: pluginId,
-                            plugin: entry.name,
-                            path: check.fullPath,
-                            component: 'commands',
-                        });
-                    }
-                }
-                if (validPaths.length > 0) {
-                    plugin.commandsPaths = validPaths;
-                }
-            }
-        }
-        // Process agents from marketplace entry
-        if (entry.agents) {
-            const agentPaths = Array.isArray(entry.agents)
-                ? entry.agents
-                : [entry.agents];
-            const validPaths = await validatePluginPaths(agentPaths, pluginPath, entry.name, pluginId, 'agents', 'Agent', 'from marketplace entry', errors);
-            if (validPaths.length > 0) {
-                plugin.agentsPaths = validPaths;
-            }
-        }
-        // Process skills from marketplace entry
-        if (entry.skills) {
-            logForDebugging(`Processing ${Array.isArray(entry.skills) ? entry.skills.length : 1} skill paths for plugin ${entry.name}`);
-            const skillPaths = Array.isArray(entry.skills)
-                ? entry.skills
-                : [entry.skills];
-            // Parallelize pathExists checks; process results in order.
-            // Note: previously this loop called pathExists() TWICE per iteration
-            // (once in a debug log template, once in the if) — now called once.
-            const checks = await Promise.all(skillPaths.map(async (skillPath) => {
-                const fullPath = join(pluginPath, skillPath);
-                return { skillPath, fullPath, exists: await pathExists(fullPath) };
-            }));
-            const validPaths = [];
-            for (const { skillPath, fullPath, exists } of checks) {
-                logForDebugging(`Checking skill path: ${skillPath} -> ${fullPath} (exists: ${exists})`);
-                if (exists) {
-                    validPaths.push(fullPath);
-                }
-                else {
-                    logForDebugging(`Skill path ${skillPath} from marketplace entry not found at ${fullPath} for ${entry.name}`, { level: 'warn' });
-                    logError(new Error(`Plugin component file not found: ${fullPath} for ${entry.name}`));
-                    errors.push({
-                        type: 'path-not-found',
-                        source: pluginId,
-                        plugin: entry.name,
-                        path: fullPath,
-                        component: 'skills',
-                    });
-                }
-            }
-            logForDebugging(`Found ${validPaths.length} valid skill paths for plugin ${entry.name}, setting skillsPaths`);
-            if (validPaths.length > 0) {
-                plugin.skillsPaths = validPaths;
-            }
-        }
-        else {
-            logForDebugging(`Plugin ${entry.name} has no entry.skills defined`);
-        }
-        // Process output styles from marketplace entry
-        if (entry.outputStyles) {
-            const outputStylePaths = Array.isArray(entry.outputStyles)
-                ? entry.outputStyles
-                : [entry.outputStyles];
-            const validPaths = await validatePluginPaths(outputStylePaths, pluginPath, entry.name, pluginId, 'output-styles', 'Output style', 'from marketplace entry', errors);
-            if (validPaths.length > 0) {
-                plugin.outputStylesPaths = validPaths;
-            }
-        }
-        // Process inline hooks from marketplace entry
-        if (entry.hooks) {
-            plugin.hooksConfig = entry.hooks;
-        }
-    }
-    else if (!entry.strict &&
-        hasManifest &&
-        (entry.commands ||
-            entry.agents ||
-            entry.skills ||
-            entry.hooks ||
-            entry.outputStyles)) {
-        // In non-strict mode with plugin.json, marketplace entries for commands/agents/skills/hooks/outputStyles are conflicts
-        const error = new Error(`Plugin ${entry.name} has both plugin.json and marketplace manifest entries for commands/agents/skills/hooks/outputStyles. This is a conflict.`);
-        logForDebugging(`Plugin ${entry.name} has both plugin.json and marketplace manifest entries for commands/agents/skills/hooks/outputStyles. This is a conflict.`, { level: 'error' });
-        logError(error);
-        errorsOut.push({
-            type: 'generic-error',
-            source: pluginId,
-            error: `Plugin ${entry.name} has conflicting manifests: both plugin.json and marketplace entry specify components. Set strict: true in marketplace entry or remove component specs from one location.`,
-        });
-        return null;
-    }
-    else if (hasManifest) {
-        // Has plugin.json - marketplace can supplement commands/agents/skills/hooks/outputStyles
-        // Supplement commands from marketplace entry
-        if (entry.commands) {
-            // Check if it's an object mapping
-            const firstValue = Object.values(entry.commands)[0];
-            if (typeof entry.commands === 'object' &&
-                !Array.isArray(entry.commands) &&
-                firstValue &&
-                typeof firstValue === 'object' &&
-                ('source' in firstValue || 'content' in firstValue)) {
-                // Object mapping format - merge metadata
-                const commandsMetadata = {
-                    ...(plugin.commandsMetadata || {}),
-                };
-                const validPaths = [];
-                // Parallelize pathExists checks; process results in order.
-                const entries = Object.entries(entry.commands);
-                const checks = await Promise.all(entries.map(async ([commandName, metadata]) => {
-                    if (!metadata || typeof metadata !== 'object' || !metadata.source) {
-                        return { commandName, metadata, skip: true };
-                    }
-                    const fullPath = join(pluginPath, metadata.source);
-                    return {
-                        commandName,
-                        metadata,
-                        skip: false,
-                        fullPath,
-                        exists: await pathExists(fullPath),
-                    };
-                }));
-                for (const check of checks) {
-                    if (check.skip)
-                        continue;
-                    if (check.exists) {
-                        validPaths.push(check.fullPath);
-                        commandsMetadata[check.commandName] = check.metadata;
-                    }
-                    else {
-                        logForDebugging(`Command ${check.commandName} path ${check.metadata.source} from marketplace entry not found at ${check.fullPath} for ${entry.name}`, { level: 'warn' });
-                        logError(new Error(`Plugin component file not found: ${check.fullPath} for ${entry.name}`));
-                        errors.push({
-                            type: 'path-not-found',
-                            source: pluginId,
-                            plugin: entry.name,
-                            path: check.fullPath,
-                            component: 'commands',
-                        });
-                    }
-                }
-                if (validPaths.length > 0) {
-                    plugin.commandsPaths = [
-                        ...(plugin.commandsPaths || []),
-                        ...validPaths,
-                    ];
-                    plugin.commandsMetadata = commandsMetadata;
-                }
-            }
-            else {
-                // Path or array of paths format
-                const commandPaths = Array.isArray(entry.commands)
-                    ? entry.commands
-                    : [entry.commands];
-                // Parallelize pathExists checks; process results in order.
-                const checks = await Promise.all(commandPaths.map(async (cmdPath) => {
-                    if (typeof cmdPath !== 'string') {
-                        return { cmdPath, kind: 'invalid' };
-                    }
-                    const fullPath = join(pluginPath, cmdPath);
-                    return {
-                        cmdPath,
-                        kind: 'path',
-                        fullPath,
-                        exists: await pathExists(fullPath),
-                    };
-                }));
-                const validPaths = [];
-                for (const check of checks) {
-                    if (check.kind === 'invalid') {
-                        logForDebugging(`Unexpected command format in marketplace entry for ${entry.name}`, { level: 'error' });
-                        continue;
-                    }
-                    if (check.exists) {
-                        validPaths.push(check.fullPath);
-                    }
-                    else {
-                        logForDebugging(`Command path ${check.cmdPath} from marketplace entry not found at ${check.fullPath} for ${entry.name}`, { level: 'warn' });
-                        logError(new Error(`Plugin component file not found: ${check.fullPath} for ${entry.name}`));
-                        errors.push({
-                            type: 'path-not-found',
-                            source: pluginId,
-                            plugin: entry.name,
-                            path: check.fullPath,
-                            component: 'commands',
-                        });
-                    }
-                }
-                if (validPaths.length > 0) {
-                    plugin.commandsPaths = [
-                        ...(plugin.commandsPaths || []),
-                        ...validPaths,
-                    ];
-                }
-            }
-        }
-        // Supplement agents from marketplace entry
-        if (entry.agents) {
-            const agentPaths = Array.isArray(entry.agents)
-                ? entry.agents
-                : [entry.agents];
-            const validPaths = await validatePluginPaths(agentPaths, pluginPath, entry.name, pluginId, 'agents', 'Agent', 'from marketplace entry', errors);
-            if (validPaths.length > 0) {
-                plugin.agentsPaths = [...(plugin.agentsPaths || []), ...validPaths];
-            }
-        }
-        // Supplement skills from marketplace entry
-        if (entry.skills) {
-            const skillPaths = Array.isArray(entry.skills)
-                ? entry.skills
-                : [entry.skills];
-            const validPaths = await validatePluginPaths(skillPaths, pluginPath, entry.name, pluginId, 'skills', 'Skill', 'from marketplace entry', errors);
-            if (validPaths.length > 0) {
-                plugin.skillsPaths = [...(plugin.skillsPaths || []), ...validPaths];
-            }
-        }
-        // Supplement output styles from marketplace entry
-        if (entry.outputStyles) {
-            const outputStylePaths = Array.isArray(entry.outputStyles)
-                ? entry.outputStyles
-                : [entry.outputStyles];
-            const validPaths = await validatePluginPaths(outputStylePaths, pluginPath, entry.name, pluginId, 'output-styles', 'Output style', 'from marketplace entry', errors);
-            if (validPaths.length > 0) {
-                plugin.outputStylesPaths = [
-                    ...(plugin.outputStylesPaths || []),
-                    ...validPaths,
-                ];
-            }
-        }
-        // Supplement hooks from marketplace entry
-        if (entry.hooks) {
-            plugin.hooksConfig = {
-                ...(plugin.hooksConfig || {}),
-                ...entry.hooks,
-            };
-        }
-    }
-    errorsOut.push(...errors);
-    return plugin;
-}
-/**
- * Load session-only plugins from --plugin-dir CLI flag.
- *
- * These plugins are loaded directly without going through the marketplace system.
- * They appear with source='plugin-name@inline' and are always enabled for the current session.
- *
- * @param sessionPluginPaths - Array of plugin directory paths from CLI
- * @returns LoadedPlugin objects and any errors encountered
- */
-async function loadSessionOnlyPlugins(sessionPluginPaths) {
-    if (sessionPluginPaths.length === 0) {
-        return { plugins: [], errors: [] };
-    }
-    const plugins = [];
-    const errors = [];
-    for (const [index, pluginPath] of sessionPluginPaths.entries()) {
-        try {
-            const resolvedPath = resolve(pluginPath);
-            if (!(await pathExists(resolvedPath))) {
-                logForDebugging(`Plugin path does not exist: ${resolvedPath}, skipping`, { level: 'warn' });
-                errors.push({
-                    type: 'path-not-found',
-                    source: `inline[${index}]`,
-                    path: resolvedPath,
-                    component: 'commands',
-                });
-                continue;
-            }
-            const dirName = basename(resolvedPath);
-            const { plugin, errors: pluginErrors } = await createPluginFromPath(resolvedPath, `${dirName}@inline`, // temporary, will be updated after we know the real name
-            true, // always enabled
-            dirName);
-            // Update source to use the actual plugin name from manifest
-            plugin.source = `${plugin.name}@inline`;
-            plugin.repository = `${plugin.name}@inline`;
-            plugins.push(plugin);
-            errors.push(...pluginErrors);
-            logForDebugging(`Loaded inline plugin from path: ${plugin.name}`);
-        }
-        catch (error) {
-            const errorMsg = errorMessage(error);
-            logForDebugging(`Failed to load session plugin from ${pluginPath}: ${errorMsg}`, { level: 'warn' });
-            errors.push({
-                type: 'generic-error',
-                source: `inline[${index}]`,
-                error: `Failed to load plugin: ${errorMsg}`,
-            });
-        }
-    }
-    if (plugins.length > 0) {
-        logForDebugging(`Loaded ${plugins.length} session-only plugins from --plugin-dir`);
-    }
-    return { plugins, errors };
-}
-/**
- * Merge plugins from session (--plugin-dir), marketplace (installed), and
- * builtin sources. Session plugins override marketplace plugins with the
- * same name — the user explicitly pointed at a directory for this session.
- *
- * Exception: marketplace plugins locked by managed settings (policySettings)
- * cannot be overridden. Enterprise admin intent beats local dev convenience.
- * When a session plugin collides with a managed one, the session copy is
- * dropped and an error is returned for surfacing.
- *
- * Without this dedup, both versions sat in the array and marketplace won
- * on first-match, making --plugin-dir useless for iterating on an
- * installed plugin.
- */
-export function mergePluginSources(sources) {
-    const errors = [];
-    const managed = sources.managedNames;
-    // Managed settings win over --plugin-dir. Drop session plugins whose
-    // name appears in policySettings.enabledPlugins (whether force-enabled
-    // OR force-disabled — both are admin intent that --plugin-dir must not
-    // bypass). Surface an error so the user knows why their dev copy was
-    // ignored.
-    //
-    // NOTE: managedNames contains the pluginId prefix (entry.name), which is
-    // expected to equal manifest.name by convention (schema description at
-    // schemas.ts PluginMarketplaceEntry.name). If a marketplace publishes a
-    // plugin where entry.name ≠ manifest.name, this guard will silently miss —
-    // but that's a marketplace misconfiguration that breaks other things too
-    // (e.g., ManagePlugins constructs pluginIds from manifest.name).
-    const sessionPlugins = sources.session.filter(p => {
-        if (managed?.has(p.name)) {
-            logForDebugging(`Plugin "${p.name}" from --plugin-dir is blocked by managed settings`, { level: 'warn' });
-            errors.push({
-                type: 'generic-error',
-                source: p.source,
-                plugin: p.name,
-                error: `--plugin-dir copy of "${p.name}" ignored: plugin is locked by managed settings`,
-            });
-            return false;
-        }
-        return true;
-    });
-    const sessionNames = new Set(sessionPlugins.map(p => p.name));
-    const marketplacePlugins = sources.marketplace.filter(p => {
-        if (sessionNames.has(p.name)) {
-            logForDebugging(`Plugin "${p.name}" from --plugin-dir overrides installed version`);
-            return false;
-        }
-        return true;
-    });
-    // Session first, then non-overridden marketplace, then builtin.
-    // Downstream first-match consumers see session plugins before
-    // installed ones for any that slipped past the name filter.
-    return {
-        plugins: [...sessionPlugins, ...marketplacePlugins, ...sources.builtin],
-        errors,
-    };
-}
-/**
- * Main plugin loading function that discovers and loads all plugins.
- *
- * This function is memoized to avoid repeated filesystem scanning and is
- * the primary entry point for the plugin system. It discovers plugins from
- * multiple sources and returns categorized results.
- *
- * Loading order and precedence (see mergePluginSources):
- * 1. Session-only plugins (from --plugin-dir CLI flag) — override
- *    installed plugins with the same name, UNLESS that plugin is
- *    locked by managed settings (policySettings, either force-enabled
- *    or force-disabled)
- * 2. Marketplace-based plugins (plugin@marketplace format from settings)
- * 3. Built-in plugins shipped with the CLI
- *
- * Name collision: session plugin wins over installed. The user explicitly
- * pointed at a directory for this session — that intent beats whatever
- * is installed. Exception: managed settings (enterprise policy) win over
- * --plugin-dir. Admin intent beats local dev convenience.
- *
- * Error collection:
- * - Non-fatal errors are collected and returned
- * - System continues loading other plugins on errors
- * - Errors include source information for debugging
- *
- * @returns Promise resolving to categorized plugin results:
- *   - enabled: Array of enabled LoadedPlugin objects
- *   - disabled: Array of disabled LoadedPlugin objects
- *   - errors: Array of loading errors with source information
- */
-export const loadAllPlugins = memoize(async () => {
-    const result = await assemblePluginLoadResult(() => loadPluginsFromMarketplaces({ cacheOnly: false }));
-    // A fresh full-load result is strictly valid for cache-only callers
-    // (both variants share assemblePluginLoadResult). Warm the separate
-    // memoize so refreshActivePlugins()'s downstream getPluginCommands() /
-    // getAgentDefinitionsWithOverrides() — which now call
-    // loadAllPluginsCacheOnly — see just-cloned plugins instead of reading
-    // an installed_plugins.json that nothing writes mid-session.
-    loadAllPluginsCacheOnly.cache?.set(undefined, Promise.resolve(result));
-    return result;
-});
-/**
- * Cache-only variant of loadAllPlugins.
- *
- * Same merge/dependency/settings logic, but the marketplace loader never
- * hits the network (no cachePlugin, no copyPluginToVersionedCache). Reads
- * from installed_plugins.json's installPath. Plugins not on disk emit
- * 'plugin-cache-miss' and are skipped.
- *
- * Use this in startup consumers (getCommands, loadPluginAgents, MCP/LSP
- * config) so interactive startup never blocks on git clones for ref-tracked
- * plugins. Use loadAllPlugins() in explicit refresh paths (/plugins,
- * refresh.ts, headlessPluginInstall) where fresh source is the intent.
- *
- * CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 delegates to the full loader — that
- * mode explicitly opts into blocking install before first query, and
- * main.tsx's getClaudeCodeMcpConfigs()/getInitialSettings().agent run
- * BEFORE runHeadless() can warm this cache. First-run CCR/headless has
- * no installed_plugins.json, so cache-only would miss plugin MCP servers
- * and plugin settings (the agent key). The interactive startup win is
- * preserved since interactive mode doesn't set SYNC_PLUGIN_INSTALL.
- *
- * Separate memoize cache from loadAllPlugins — a cache-only result must
- * never satisfy a caller that wants fresh source. The reverse IS valid:
- * loadAllPlugins warms this cache on completion so refresh paths that run
- * the full loader don't get plugin-cache-miss from their downstream
- * cache-only consumers.
- */
-export const loadAllPluginsCacheOnly = memoize(async () => {
-    if (isEnvTruthy(process.env.CLAUDE_CODE_SYNC_PLUGIN_INSTALL)) {
-        return loadAllPlugins();
-    }
-    return assemblePluginLoadResult(() => loadPluginsFromMarketplaces({ cacheOnly: true }));
-});
-/**
- * Shared body of loadAllPlugins and loadAllPluginsCacheOnly.
- *
- * The only difference between the two is which marketplace loader runs —
- * session plugins, builtins, merge, verifyAndDemote, and cachePluginSettings
- * are identical (invariants 1-3).
- */
-async function assemblePluginLoadResult(marketplaceLoader) {
-    // Load marketplace plugins and session-only plugins in parallel.
-    // getInlinePlugins() is a synchronous state read with no dependency on
-    // marketplace loading, so these two sources can be fetched concurrently.
-    const inlinePlugins = getInlinePlugins();
-    const [marketplaceResult, sessionResult] = await Promise.all([
-        marketplaceLoader(),
-        inlinePlugins.length > 0
-            ? loadSessionOnlyPlugins(inlinePlugins)
-            : Promise.resolve({ plugins: [], errors: [] }),
-    ]);
-    // 3. Load built-in plugins that ship with the CLI
-    const builtinResult = getBuiltinPlugins();
-    // Session plugins (--plugin-dir) override installed ones by name,
-    // UNLESS the installed plugin is locked by managed settings
-    // (policySettings). See mergePluginSources() for details.
-    const { plugins: allPlugins, errors: mergeErrors } = mergePluginSources({
-        session: sessionResult.plugins,
-        marketplace: marketplaceResult.plugins,
-        builtin: [...builtinResult.enabled, ...builtinResult.disabled],
-        managedNames: getManagedPluginNames(),
-    });
-    const allErrors = [
-        ...marketplaceResult.errors,
-        ...sessionResult.errors,
-        ...mergeErrors,
-    ];
-    // Verify dependencies. Runs AFTER the parallel load — deps are presence
-    // checks, not load-order, so no topological sort needed. Demotion is
-    // session-local: does NOT write settings (user fixes intent via /doctor).
-    const { demoted, errors: depErrors } = verifyAndDemote(allPlugins);
-    for (const p of allPlugins) {
-        if (demoted.has(p.source))
-            p.enabled = false;
-    }
-    allErrors.push(...depErrors);
-    const enabledPlugins = allPlugins.filter(p => p.enabled);
-    logForDebugging(`Found ${allPlugins.length} plugins (${enabledPlugins.length} enabled, ${allPlugins.length - enabledPlugins.length} disabled)`);
-    // 3. Cache plugin settings for synchronous access by the settings cascade
-    cachePluginSettings(enabledPlugins);
-    return {
-        enabled: enabledPlugins,
-        disabled: allPlugins.filter(p => !p.enabled),
-        errors: allErrors,
-    };
-}
-/**
- * Clears the memoized plugin cache.
- *
- * Call this when plugins are installed, removed, or settings change
- * to force a fresh scan on the next loadAllPlugins call.
- *
- * Use cases:
- * - After installing/uninstalling plugins
- * - After modifying .claude-plugin/ directory (for export)
- * - After changing enabledPlugins settings
- * - When debugging plugin loading issues
- */
-export function clearPluginCache(reason) {
-    if (reason) {
-        logForDebugging(`clearPluginCache: invalidating loadAllPlugins cache (${reason})`);
-    }
-    loadAllPlugins.cache?.clear?.();
-    loadAllPluginsCacheOnly.cache?.clear?.();
-    // If a plugin previously contributed settings, the session settings cache
-    // holds a merged result that includes them. cachePluginSettings() on reload
-    // won't bust the cache when the new base is empty (the startup perf win),
-    // so bust it here to drop stale plugin overrides. When the base is already
-    // undefined (startup, or no prior plugin settings) this is a no-op.
-    if (getPluginSettingsBase() !== undefined) {
-        resetSettingsCache();
-    }
-    clearPluginSettingsBase();
-    // TODO: Clear installed plugins cache when installedPluginsManager is implemented
-}
-/**
- * Merge settings from all enabled plugins into a single record.
- * Later plugins override earlier ones for the same key.
- * Only allowlisted keys are included (filtering happens at load time).
- */
-function mergePluginSettings(plugins) {
-    let merged;
-    for (const plugin of plugins) {
-        if (!plugin.settings) {
-            continue;
-        }
-        if (!merged) {
-            merged = {};
-        }
-        for (const [key, value] of Object.entries(plugin.settings)) {
-            if (key in merged) {
-                logForDebugging(`Plugin "${plugin.name}" overrides setting "${key}" (previously set by another plugin)`);
-            }
-            merged[key] = value;
-        }
-    }
-    return merged;
-}
-/**
- * Store merged plugin settings in the synchronous cache.
- * Called after loadAllPlugins resolves.
- */
-export function cachePluginSettings(plugins) {
-    const settings = mergePluginSettings(plugins);
-    setPluginSettingsBase(settings);
-    // Only bust the session settings cache if there are actually plugin settings
-    // to merge. In the common case (no plugins, or plugins without settings) the
-    // base layer is empty and loadSettingsFromDisk would produce the same result
-    // anyway — resetting here would waste ~17ms on startup re-reading and
-    // re-validating every settings file on the next getSettingsWithErrors() call.
-    if (settings && Object.keys(settings).length > 0) {
-        resetSettingsCache();
-        logForDebugging(`Cached plugin settings with keys: ${Object.keys(settings).join(', ')}`);
-    }
-}
-/**
- * Type predicate: check if a value is a non-null, non-array object (i.e., a record).
- */
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}