dsh-agent-plugins-market 0.6.2 → 0.7.1

package/lib/application/catalog.js

@@ -1,464 +1,146 @@
 /**
- * Catalog application module: the host-authoritative owner of source state,
- * discovery, install mutations, and coherent suite snapshots.
+ * Catalog application module: the use-case surface the HTTP routes, the host
+ * entry, and the runtime mount adapters call.
  *
- * The module deliberately keeps the existing filesystem and Git operations
- * behind one interface while callers migrate from SuiteManager. User and
- * project snapshots use their own persisted state files and share the same
- * source-selection and suite-scanning rules.
+ * The class is a thin facade. Persisted state, the serialized mutation queue,
+ * the revision and scan generations, and the change pipeline live in
+ * {@link CatalogContext}; discovery caching in {@link SnapshotCache}; and each
+ * use-case family in its own collaborator (source acquisition, install state,
+ * MCP, LSP). The facade composes them and forwards, so a caller never has to
+ * know which collaborator owns a given invariant.
  */
-import { mkdir, readdir, rename } from 'node:fs/promises';
-import { join } from 'node:path';
-import { repoName } from '../catalog/manifests.js';
-import { canonicalGitUrl } from '../catalog/scan-resolvers.js';
-import { discoverSourceListWithNotes } from '../catalog/source-catalog.js';
-import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
-import { archiveInstall } from '../catalog/archive.js';
-import { gitClone, gitCurrentBranch, gitHead, gitRemoteUrl, gitRemove, gitSetRemoteUrl, gitSync } from '../catalog/git.js';
-import { buildMcpStatus } from '../runtime/mcp-status.js';
-import { addUserMcpServer, loadUserMcpSuite, USER_MCP_SOURCE, USER_MCP_SUITE } from '../runtime/mcp-direct-config.js';
-import { buildLspStatus } from '../runtime/lsp-status.js';
-import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
-import { loadDisabledLspServers, saveDisabledLspServers } from '../runtime/lsp-server-state.js';
-import { applyOverride, loadSuiteOverrides, mergeOverridePatch, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
-import { applyLspOverrides, lspConfig, restoreRedactedConfig, saveLspOverride, validateServerLsp, validateServerMcp } from '../runtime/server-config.js';
-import { probeHostMcpClient } from '../runtime/mcp-backend.js';
-import { githubCloneUrl, resolveRegion } from '../runtime/regions.js';
-import { readLocalePreference } from '../runtime/host-locale.js';
-import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
+import { qualifiedSuiteId } from '../catalog/paths.js';
+import { loadUserMcpSuite } from '../runtime/mcp-direct-config.js';
+import { loadSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { applyLspOverrides } from '../runtime/server-config.js';
 import { buildSuiteDetail, readSkillContent } from './details.js';
-import { deriveSourceIdCandidates, expandHome, isDirectory, pathExists, qualifiedSuiteId, resolveProjectRoot, sanitizeId, sourceCheckoutDir, sourcesDir, STATE_FILE_NAME } from '../catalog/paths.js';
-import { loadState, saveState, EMPTY_STATE } from '../model/state.js';
-import { effectiveSurfaces, SUITE_SURFACE_KEYS, resolveSourceKind } from '../model/types.js';
+import { CatalogContext } from './catalog-context.js';
+import { InstallStore } from './install-store.js';
+import { LspService } from './lsp-service.js';
+import { McpService } from './mcp-service.js';
+import { resolveCatalogPorts } from './ports.js';
+import { SourceStore, codeloadTarballUrl } from './source-store.js';
 export class Catalog {
-    options;
-    state = EMPTY_STATE;
-    mutationQueue = Promise.resolve();
-    statePath;
-    headCache = new Map();
-    listeners = new Set();
-    revision = 0;
-    userSnapshot;
-    userSnapshotExpiresAt = 0;
-    userSnapshotPromise;
-    /**
-     * Discovery scan cache: per-sources-fingerprint scan results with a TTL.
-     * Install / enable / surface toggles re-derive the snapshot from cached
-     * discovery (cheap mapping) instead of re-walking every checkout — a full
-     * rescan of a 2,500-suite catalog costs ~1s and UI mutations happen in
-     * bursts. Content-changing mutations (add / update / remove / adopt /
-     * refresh / acquire) clear every cached discovery generation; the TTL
-     * bounds staleness for in-place working-tree
-     * edits of local sources.
-     */
-    scanCache = new Map();
-    scanGeneration = 0;
-    scanPromises = new Map();
-    static SCAN_CACHE_TTL_MS = 30_000;
-    static SCAN_CACHE_MAX_ENTRIES = 8;
-    /**
-     * User-dimension snapshot TTL: bounded staleness for edits made outside the
-     * plugin (a new skill dropped into a local source's working tree, a hand
-     * edit in a project layout) becomes visible on the next read past the TTL
-     * instead of living until the next mutation. Configurable; a 0 value
-     * disables snapshot caching entirely.
-     */
-    userSnapshotTtlMs;
-    /** Project-dimension snapshots keyed by project root, with TTL freshness. */
-    projectSnapshots = new Map();
-    projectSnapshotPromises = new Map();
-    projectSnapshotTtlMs;
-    /** Latest MCP mount diagnostics (suiteId -> reasons), fed by host reconcile. */
-    mcpDiagnostics = [];
-    /** Latest LSP mount diagnostics source, wired by the host entry. */
-    lspStatusSource;
-    /** Credential-store seam for dropping a grant record (MCP re-authorize). */
-    credentialsStore;
-    toolSnapshotProvider = () => [];
-    /** Mount-registry seam: flags a mount key for an explicit rebuild (re-authorize). */
-    mcpRemount = () => { };
-    /** Resolves the mount key owning one derived serverName; absent when the server is not mounted. */
-    mcpServerOwner = () => undefined;
-    /** Backend source (the host settings namespace scope); default is the built-in client. */
-    mcpBackendProvider = async () => 'builtin';
-    /** Backend writer (a scope update); absent until the settings service resolves. */
-    mcpBackendWriter = async () => {
-        throw new Error('the settings service is not mounted');
-    };
-    /** Download-region source (the host settings namespace scope). */
-    downloadRegionProvider = async () => 'auto';
-    scanProjectLayouts = true;
-    /** Apply the host's project-layout switch and invalidate every project snapshot. */
-    async setScanProjectLayouts(enabled) {
-        if (this.scanProjectLayouts === enabled)
-            return;
-        this.scanProjectLayouts = enabled;
-        await this.notifyChanged();
-    }
+    context;
+    ports;
+    snapshots;
+    sourceStore;
+    installs;
+    mcp;
+    lsp;
     constructor(options) {
-        this.options = options;
-        this.statePath = join(options.userRoot, STATE_FILE_NAME);
-        this.projectSnapshotTtlMs = options.projectSnapshotTtlMs ?? 5_000;
-        this.userSnapshotTtlMs = options.userSnapshotTtlMs ?? Catalog.SCAN_CACHE_TTL_MS;
-    }
-    /** Install the host tool snapshot provider used by the MCP status surface. */
-    setMcpToolSnapshotProvider(provider) {
-        this.toolSnapshotProvider = provider;
-    }
-    /** Install the credential-store seam backing the MCP re-authorize action. */
-    setCredentialsStore(store) {
-        this.credentialsStore = store;
-    }
-    /**
-     * Drop one MCP server's OAuth grant record so the next mount re-runs the
-     * browser authorization — the path for "I picked too narrow a scope".
-     * @param serverName - the derived serverName whose folded form keys the record.
-     * @throws when the credentials service is not mounted.
-     */
-    async reauthorizeMcpServer(serverName) {
-        await this.enqueue(async () => {
-            await this.credentialsStore?.deleteGrantRecord(serverName);
-            // Dropping a grant changes no resolved config field, so a fingerprint
-            // reconcile would keep the live bridge — with its in-memory tokens —
-            // untouched. The serverName maps back to exactly one mount key (the
-            // registry reserved the name), so flag it for an explicit rebuild.
-            const key = this.mcpServerOwner(serverName);
-            if (key !== undefined)
-                this.mcpRemount?.(key.suiteId, key.serverKey);
-            await this.notifyChanged(true);
-        });
-    }
-    /**
-     * Install the MCP remount seam used by re-authorize: the registry flags the
-     * mount so the next reconcile tears the live bridge down and rebuilds it.
-     */
-    setMcpRemountHook(hook, serverOwner) {
-        this.mcpRemount = hook;
-        this.mcpServerOwner = serverOwner;
-    }
-    /** Whether the re-authorize action can run in this composition. */
-    mcpReauthorizeAvailable() {
-        return this.credentialsStore !== undefined;
-    }
-    /** Install the LSP mount status source used by the LSP status surface. */
-    setLspStatusSource(source) {
-        this.lspStatusSource = source;
+        this.context = new CatalogContext(options);
+        this.ports = resolveCatalogPorts(options.ports);
+        this.snapshots = this.context.snapshots;
+        this.sourceStore = new SourceStore(this.context, this.ports);
+        this.installs = new InstallStore(this.context, this.sourceStore);
+        this.mcp = new McpService(this.context, this.ports, this.sourceStore);
+        this.lsp = new LspService(this.context, this.ports);
     }
-    /** Subscribe to completed catalog mutations; returns an unsubscribe function. */
-    subscribe(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
-    }
-    /** Build the flat MCP service inventory for the status surface. */
-    async mcpStatus() {
-        const snapshot = await this.readUserCatalog();
-        const suites = [...snapshot.suites, await loadUserMcpSuite(this.options.dataRoot)];
-        const payload = buildMcpStatus(suites, this.mcpDiagnostics, this.toolSnapshotProvider(), await this.allMcpOverrides(suites));
-        for (const entry of payload.entries)
-            if (entry.suiteId === `${USER_MCP_SOURCE}/${USER_MCP_SUITE}`) {
-                entry.kind = 'direct';
-                entry.managed = true;
-            }
-        const oauthBackend = (await this.mcpBackend()) === 'builtin' && this.mcpReauthorizeAvailable();
-        for (const entry of payload.entries) {
-            const auth = entry.config?.auth;
-            entry.canReauthorize =
-                oauthBackend &&
-                    (entry.kind === 'plugin' || entry.managed === true) &&
-                    (entry.transport === 'sse' || entry.transport === 'streamable-http') &&
-                    auth?.enabled !== false &&
-                    !['disabled', 'foreign', 'orphaned'].includes(entry.state);
-        }
-        return payload;
-    }
-    /** Persist a user-owned MCP service and reconcile its bridge mount. */
-    async addMcpServer(name, server) {
-        return this.enqueue(async () => {
-            await addUserMcpServer(this.options.dataRoot, name, server);
-            await this.notifyChanged(true);
-        });
-    }
-    /** Read effective service configuration without exposing credential literals. */
-    async serverConfig(kind, id) {
-        const config = await this.resolveServerConfig(kind, id);
-        return { kind, id, editable: true, config: redactMcpConfig(config.value) };
-    }
-    async resolveServerConfig(kind, id) {
-        if (kind === 'lsp' && id.startsWith('direct/')) {
-            const key = id.slice(7);
-            const server = (await loadLspServers(this.options.dataRoot)).servers[key];
-            if (server === undefined)
-                throw new Error('LSP server not found');
-            return { key, suiteKey: 'direct', root: this.options.dataRoot, value: lspConfig(server) };
-        }
-        const suites = [...(await this.readUserCatalog()).suites, await loadUserMcpSuite(this.options.dataRoot)];
-        for (const suite of await applyLspOverrides(this.options.dataRoot, suites)) {
-            const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
-            if (kind === 'mcp') {
-                for (const [key, server] of Object.entries(suite.mcp?.servers ?? {})) {
-                    if (id !== `plugin:${suiteKey}/${key}`)
-                        continue;
-                    const overrides = await loadSuiteOverrides(this.options.dataRoot, suiteKey);
-                    return { key, suiteKey, root: suite.root, value: { ...applyOverride(server, overrides[key]) } };
-                }
-            }
-            else {
-                for (const [key, server] of Object.entries(suite.lsp?.servers ?? {})) {
-                    if (id === `${suiteKey}/${key}`)
-                        return { key, suiteKey, root: suite.root, value: lspConfig(server) };
-                }
-            }
-        }
-        throw new Error('service configuration is not managed by this plugin');
-    }
-    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
-    async saveServerConfig(kind, id, config) {
-        return this.enqueue(async () => {
-            const current = await this.resolveServerConfig(kind, id);
-            const value = restoreRedactedConfig(config, current.value);
-            if (kind === 'mcp') {
-                const server = await validateServerMcp(current.root, current.key, value);
-                const overrides = await loadSuiteOverrides(this.options.dataRoot, current.suiteKey);
-                const enabled = overrides[current.key]?.enabled;
-                overrides[current.key] = { config: server, ...(enabled === undefined ? {} : { enabled }) };
-                await saveSuiteOverrides(this.options.dataRoot, current.suiteKey, overrides);
-            }
-            else {
-                const server = validateServerLsp(current.key, value);
-                if (current.suiteKey === 'direct') {
-                    const direct = await loadLspServers(this.options.dataRoot);
-                    if (direct.errors.length > 0)
-                        throw new Error(direct.errors.join('; '));
-                    direct.servers[current.key] = server;
-                    await saveLspServers(this.options.dataRoot, { lspServers: Object.fromEntries(Object.entries(direct.servers).map(([key, spec]) => [key, lspConfig(spec)])) });
-                }
-                else
-                    await saveLspOverride(this.options.dataRoot, id, server);
-            }
-            await this.notifyChanged(true);
-        });
-    }
-    /** The LSP status surface: declared servers merged with mount diagnostics. */
-    async lspStatus() {
-        const snapshot = await this.readUserCatalog();
-        const direct = await loadLspServers(this.options.dataRoot);
-        return buildLspStatus(await applyLspOverrides(this.options.dataRoot, snapshot.suites), this.lspStatusSource ?? { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false }, direct);
+    /** Latest MCP mount diagnostics (suiteId -> reasons), fed by host reconcile. */
+    get mcpDiagnostics() {
+        return this.mcp.diagnostics;
     }
-    /** The user's direct LSP server table (normalized specs). */
-    async lspServers() {
-        return (await loadLspServers(this.options.dataRoot)).servers;
+    set mcpDiagnostics(value) {
+        this.mcp.diagnostics = value;
     }
-    /** Create one direct LSP declaration without replacing other user servers. */
-    async addLspServer(name, config) {
-        return this.enqueue(async () => {
-            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name))
-                throw new Error('invalid LSP server name');
-            const direct = await loadLspServers(this.options.dataRoot);
-            if (direct.errors.length > 0)
-                throw new Error(direct.errors.join('; '));
-            if (Object.hasOwn(direct.servers, name))
-                throw new Error('LSP server already exists');
-            const spec = validateServerLsp(name, config);
-            await saveLspServers(this.options.dataRoot, {
-                lspServers: { ...Object.fromEntries(Object.entries(direct.servers).map(([key, value]) => [key, lspConfig(value)])), [name]: lspConfig(spec) }
-            });
-            await this.notifyChanged(true);
-        });
+    /** The user-dimension suite root this catalog operates. */
+    get userRoot() {
+        return this.context.userRoot;
     }
-    /** Validate and persist the user's direct LSP server table. */
-    async setLspServers(raw) {
-        return this.enqueue(async () => {
-            const { servers } = await saveLspServers(this.options.dataRoot, raw);
-            await this.notifyChanged(true);
-            return servers;
-        });
+    /** The plugin storage root holding per-suite `${PLUGIN_DATA}` directories and overrides. */
+    get dataRoot() {
+        return this.context.dataRoot;
     }
-    async setLspServerEnabled(id, enabled) {
-        return this.enqueue(async () => {
-            const disabled = await loadDisabledLspServers(this.options.dataRoot);
-            if (enabled)
-                disabled.delete(id);
-            else
-                disabled.add(id);
-            await saveDisabledLspServers(this.options.dataRoot, disabled);
-            await this.notifyChanged(true);
-        });
+    get sources() {
+        return this.context.state.sources;
     }
-    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
-    async mcpOverrides(sourceId, suiteId) {
-        const suiteKey = qualifiedSuiteId(sourceId, suiteId);
-        const snapshot = await this.readUserCatalog();
-        if (!snapshot.suites.some(suite => suite.sourceId === sourceId && suite.id === suiteId))
-            throw new Error(`suite "${suiteKey}" not found`);
-        return redactMcpOverrides(await loadSuiteOverrides(this.options.dataRoot, suiteKey));
+    /** Whether one suite currently carries an install entry. */
+    isInstalled(sourceId, suiteId) {
+        return this.context.installed(sourceId, suiteId) !== undefined;
     }
-    /**
-     * Set or clear one server's MCP override and remount it. `override === null`
-     * clears the override (back to the source config). The serverKey must exist
-     * in the suite's parsed mcp.json.
-     */
-    async setMcpOverride(sourceId, suiteId, serverKey, override) {
-        return this.enqueue(async () => {
-            const suiteKey = qualifiedSuiteId(sourceId, suiteId);
-            const source = this.state.sources.find(entry => entry.id === sourceId);
-            let suites;
-            if (sourceId === USER_MCP_SOURCE && suiteId === USER_MCP_SUITE) {
-                suites = [await loadUserMcpSuite(this.options.dataRoot)];
-            }
-            else {
-                if (source === undefined)
-                    throw new Error(`unknown source "${sourceId}"`);
-                const checkout = this.sourceCheckoutPath(source);
-                if (!(await isDirectory(checkout)))
-                    await this.acquire(source);
-                suites = await discoverSuitesInSource(checkout, sourceId, 'user', source.url);
-            }
-            const suite = suites.find(entry => entry.id === suiteId);
-            if (suite === undefined)
-                throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
-            if (suite.mcp?.servers[serverKey] === undefined)
-                throw new Error(`server "${serverKey}" is not defined by suite "${suiteId}"`);
-            // Override files are keyed by the qualified id so two sources' same-named
-            // suites never share one override record.
-            const overrides = await loadSuiteOverrides(this.options.dataRoot, suiteKey);
-            if (override === null) {
-                delete overrides[serverKey];
-            }
-            else {
-                // Merge onto the stored record: the UI never receives literal secret
-                // values, so a verbatim write would drop keys it simply redacted.
-                overrides[serverKey] = mergeOverridePatch(overrides[serverKey] ?? {}, override);
-            }
-            await saveSuiteOverrides(this.options.dataRoot, suiteKey, overrides);
-            await this.notifyChanged(true);
-        });
+    /** Apply the host's project-layout switch and invalidate every project snapshot. */
+    async setScanProjectLayouts(enabled) {
+        await this.context.setScanProjectLayouts(enabled);
     }
-    /**
-     * Re-run the MCP reconcile pass: retries failed mounts and clears residual
-     * tools, without changing any catalog state.
-     */
-    async retryMounts() {
-        await this.notifyChanged(true);
+    /** Load persisted user state once at plugin activation. */
+    async load() {
+        await this.context.load();
     }
-    /** The persisted backend choice without the host-client probe (mount-time provider). */
-    async mcpBackend() {
-        return this.mcpBackendProvider();
+    /** Append config-seeded sources missing from user state and persist them. */
+    async mergeSources(sources) {
+        await this.installs.mergeSources(sources);
     }
     /**
-     * The active MCP mount backend plus a live probe of the host client, and
-     * the download-region setting with its locale-resolved effective route —
-     * everything the plugin-config card renders.
+     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
+     * (skills / commands / agent personas). Catalog state is untouched — this
+     * only runs the change pipeline so the runtime remounts commands and the
+     * skill providers re-read their catalogs.
      */
-    async mcpBackendInfo() {
-        const [backend, hostClient, regionSetting, locale] = await Promise.all([this.mcpBackendProvider(), probeHostMcpClient(), this.downloadRegionProvider(), readLocalePreference()]);
-        return { backend, hostClient, downloadRegion: { setting: regionSetting, effective: resolveRegion(regionSetting, locale) } };
+    async notifyPanelsChanged() {
+        await this.context.notifyChanged();
     }
     /**
-     * Switch the MCP mount backend and remount every suite server through it.
-     * A host-client switch takes effect only where the host package resolves;
-     * unresolvable or unsupported transports surface as per-server diagnostics.
+     * Wait for the derived refresh triggered by the latest change, bounded so a
+     * stuck mount reports back instead of holding an explicit retry open.
      */
-    async setMcpBackend(backend) {
-        return this.enqueue(async () => {
-            await this.mcpBackendWriter(backend);
-            await this.notifyChanged(true);
-        });
-    }
-    /** Install the backend source (the host settings namespace's scope). */
-    setMcpBackendProvider(provider) {
-        this.mcpBackendProvider = provider;
-    }
-    /** Install the backend writer (a scope update on the same namespace). */
-    setMcpBackendWriter(writer) {
-        this.mcpBackendWriter = writer;
-    }
-    /** Install the download-region source (the host settings namespace scope). */
-    setDownloadRegionProvider(provider) {
-        this.downloadRegionProvider = provider;
-    }
-    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
-    async allMcpOverrides(suites) {
-        const map = new Map();
-        for (const suite of suites ?? (await this.readUserCatalog()).suites) {
-            const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
-            const overrides = await loadSuiteOverrides(this.options.dataRoot, suiteKey);
-            if (Object.keys(overrides).length > 0)
-                map.set(suiteKey, overrides);
-        }
-        return map;
-    }
-    /** Load persisted user state once at plugin activation. */
-    async load() {
-        this.state = await loadState(this.statePath);
-        this.invalidateScans();
-        this.invalidateSnapshot(false);
-    }
-    get sources() {
-        return this.state.sources;
-    }
-    /** The user-dimension suite root this catalog operates. */
-    get userRoot() {
-        return this.options.userRoot;
+    async refreshSettled(deadlineMs) {
+        return this.context.refreshSettled(deadlineMs);
     }
     /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
     async readUserCatalog() {
-        // TTL 0 disables snapshot caching: every read observes fresh discovery,
-        // mirroring the project dimension's caching-disabled semantics.
-        if (this.userSnapshotTtlMs <= 0)
-            return this.buildSnapshot(this.state, 'user', this.options.userRoot);
-        if (this.userSnapshot !== undefined && Date.now() < this.userSnapshotExpiresAt)
-            return this.userSnapshot;
-        if (this.userSnapshotPromise !== undefined)
-            return this.userSnapshotPromise;
-        const revision = this.revision;
-        const generation = this.scanGeneration;
-        const promise = this.buildSnapshot(this.state, 'user', this.options.userRoot)
-            .then(snapshot => {
-            if (revision === this.revision && generation === this.scanGeneration) {
-                this.userSnapshot = snapshot;
-                this.userSnapshotExpiresAt = Date.now() + this.userSnapshotTtlMs;
-            }
-            return snapshot;
-        })
-            .finally(() => {
-            if (this.userSnapshotPromise === promise)
-                this.userSnapshotPromise = undefined;
-        });
-        this.userSnapshotPromise = promise;
-        return promise;
+        return this.snapshots.readUserCatalog();
     }
     /** Read one coherent project-dimension snapshot for a workspace cwd. */
     async readProjectCatalog(cwd) {
-        const projectRoot = await resolveProjectRoot(cwd);
-        if (this.projectSnapshotTtlMs <= 0)
-            return this.buildProjectSnapshot(projectRoot);
-        const cached = this.projectSnapshots.get(projectRoot);
-        if (cached !== undefined && cached.expiresAt > Date.now())
-            return cached.snapshot;
-        const inFlight = this.projectSnapshotPromises.get(projectRoot);
-        if (inFlight !== undefined)
-            return inFlight;
-        const revision = this.revision;
-        const generation = this.scanGeneration;
-        const promise = this.buildProjectSnapshot(projectRoot)
-            .then(snapshot => {
-            if (revision === this.revision && generation === this.scanGeneration) {
-                this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: Date.now() + this.projectSnapshotTtlMs });
-            }
-            return snapshot;
-        })
-            .finally(() => {
-            if (this.projectSnapshotPromises.get(projectRoot) === promise)
-                this.projectSnapshotPromises.delete(projectRoot);
-        });
-        this.projectSnapshotPromises.set(projectRoot, promise);
-        return promise;
+        return this.snapshots.readProjectCatalog(cwd);
     }
-    async buildProjectSnapshot(projectRoot) {
-        const state = await loadState(join(projectRoot, STATE_FILE_NAME));
-        // TTL 0 means caching is disabled for this dimension: bypass the scan
-        // cache so every read observes the working tree as it stands.
-        return this.buildSnapshot(state, 'project', projectRoot, this.projectSnapshotTtlMs <= 0);
+    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
+    async enabledUserSuites() {
+        const state = this.context.state;
+        const enabledSources = new Set(Object.entries(state.installed)
+            .filter(([, entry]) => entry.enabled)
+            .map(([key]) => key.slice(0, key.indexOf('/'))));
+        const sources = state.sources.filter(source => enabledSources.has(source.id));
+        const suites = sources.length === 0 ? [] : (await this.snapshots.build({ ...state, sources }, 'user', this.context.userRoot)).enabledSuites;
+        const direct = await loadUserMcpSuite(this.context.agentsRoot);
+        return applyLspOverrides(this.context.dataRoot, Object.keys(direct.mcp.servers).length === 0 ? suites : [...suites, direct]);
+    }
+    /** The full market overview from one user snapshot. */
+    async overview() {
+        const snapshot = await this.readUserCatalog();
+        const sourceRows = await this.sourceStore.overviewRows(snapshot);
+        const cards = snapshot.suites.map(suite => {
+            const isInstalled = this.isInstalled(suite.sourceId, suite.id);
+            return {
+                sourceId: suite.sourceId,
+                suiteId: suite.id,
+                name: suite.manifest.name,
+                version: suite.manifest.version,
+                description: suite.manifest.description,
+                keywords: suite.manifest.keywords ?? [],
+                surfaces: suite.surfaces,
+                enabled: suite.enabled,
+                installed: isInstalled,
+                ...(isInstalled ? { surfaceToggles: suite.activeSurfaces } : {}),
+                ...(suite.remote === undefined ? {} : { remoteUrl: suite.remote.url }),
+                dimension: suite.dimension,
+                layout: suite.manifest.layout,
+                errors: suite.errors,
+                mcpErrors: this.mcp.diagnostics.filter(diagnostic => diagnostic.suiteId === suite.id).map(diagnostic => `${diagnostic.serverKey}: ${diagnostic.reason}`)
+            };
+        });
+        return {
+            sources: sourceRows,
+            suites: cards,
+            totals: {
+                all: cards.length,
+                installed: cards.filter(card => card.installed).length,
+                enabled: cards.filter(card => card.enabled).length
+            },
+            roots: { user: this.context.userRoot, data: this.context.dataRoot },
+            unmanaged: await this.sourceStore.unmanaged()
+        };
     }
     /** One suite's full detail for the market detail modal. */
     async suiteDetail(sourceId, suiteId) {
@@ -467,7 +149,7 @@ export class Catalog {
         if (suite === undefined)
             throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
         const suiteKey = qualifiedSuiteId(sourceId, suiteId);
-        return buildSuiteDetail(suite, this.state.installed[installKey(sourceId, suiteId)], this.mcpDiagnostics, await loadSuiteOverrides(this.options.dataRoot, suiteKey));
+        return buildSuiteDetail(suite, this.context.installed(sourceId, suiteId), this.mcp.diagnostics, await loadSuiteOverrides(this.context.dataRoot, suiteKey));
     }
     /** One skill's full SKILL.md text for the market detail modal. */
     async skillContent(sourceId, suiteId, skillName) {
@@ -477,723 +159,161 @@ export class Catalog {
             throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
         return readSkillContent(suite, skillName);
     }
-    /** The full market overview from one user snapshot. */
-    async overview() {
-        const snapshot = await this.readUserCatalog();
-        const sourceRows = [];
-        for (const source of snapshot.sources) {
-            const inFlight = this.currentSourceState?.sourceId === source.id ? this.currentSourceState : undefined;
-            const checkout = this.sourceCheckoutPath(source);
-            const kind = resolveSourceKind(source);
-            let cloned = false;
-            let lockCommit;
-            let error;
-            if (kind === 'local') {
-                cloned = await isDirectory(checkout);
-                if (!cloned)
-                    error = `local source directory ${checkout} is missing`;
-            }
-            else if (kind === 'archive') {
-                cloned = await isDirectory(checkout);
-                lockCommit = this.headCache.get(source.id);
-            }
-            else if (inFlight !== undefined) {
-                // A mutation owns this source right now: do not race git against its checkout.
-                cloned = inFlight.cloned || (await isDirectory(checkout));
-                lockCommit = inFlight.head;
-            }
-            else {
-                const cachedHead = this.headCache.get(source.id);
-                if (cachedHead !== undefined && (await isDirectory(checkout))) {
-                    cloned = true;
-                    lockCommit = cachedHead;
-                }
-                else {
-                    try {
-                        lockCommit = await gitHead(checkout);
-                        cloned = true;
-                        this.headCache.set(source.id, lockCommit);
-                    }
-                    catch {
-                        // Not cloned yet or a broken checkout; refresh reports the actionable error.
-                    }
-                }
-            }
-            const sourceSuites = snapshot.suites.filter(suite => suite.sourceId === source.id);
-            const scanNotes = snapshot.scanNotes?.[source.id];
-            sourceRows.push({
-                id: source.id,
-                url: source.url,
-                ...(source.branch === undefined ? {} : { branch: source.branch }),
-                ...(source.local === true ? { local: true } : {}),
-                kind,
-                ...(source.adopted === true ? { adopted: true } : {}),
-                cloned,
-                ...(lockCommit === undefined ? {} : { lockCommit }),
-                ...(error === undefined ? {} : { error }),
-                ...(scanNotes === undefined ? {} : { scanNotes }),
-                suiteIds: sourceSuites.map(suite => suite.id)
-            });
-        }
-        const installed = new Set(Object.keys(this.state.installed));
-        const cards = snapshot.suites.map(suite => ({
-            sourceId: suite.sourceId,
-            suiteId: suite.id,
-            name: suite.manifest.name,
-            version: suite.manifest.version,
-            description: suite.manifest.description,
-            keywords: suite.manifest.keywords ?? [],
-            surfaces: suite.surfaces,
-            enabled: suite.enabled,
-            installed: installed.has(installKey(suite.sourceId, suite.id)),
-            ...(installed.has(installKey(suite.sourceId, suite.id)) ? { surfaceToggles: suite.activeSurfaces } : {}),
-            ...(suite.remote === undefined ? {} : { remoteUrl: suite.remote.url }),
-            dimension: suite.dimension,
-            layout: suite.manifest.layout,
-            errors: suite.errors,
-            mcpErrors: this.mcpDiagnostics.filter(diagnostic => diagnostic.suiteId === suite.id).map(diagnostic => `${diagnostic.serverKey}: ${diagnostic.reason}`)
-        }));
-        return {
-            sources: sourceRows,
-            suites: cards,
-            totals: {
-                all: cards.length,
-                installed: cards.filter(card => card.installed).length,
-                enabled: cards.filter(card => card.enabled).length
-            },
-            roots: { user: this.options.userRoot, data: this.options.dataRoot },
-            unmanaged: await this.unmanagedSources()
-        };
-    }
-    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
-    async enabledUserSuites() {
-        const enabledSources = new Set(Object.entries(this.state.installed)
-            .filter(([, entry]) => entry.enabled)
-            .map(([key]) => key.slice(0, key.indexOf('/'))));
-        const sources = this.state.sources.filter(source => enabledSources.has(source.id));
-        const suites = sources.length === 0 ? [] : (await this.buildSnapshot({ ...this.state, sources }, 'user', this.options.userRoot)).enabledSuites;
-        const direct = await loadUserMcpSuite(this.options.dataRoot);
-        return applyLspOverrides(this.options.dataRoot, Object.keys(direct.mcp.servers).length === 0 ? suites : [...suites, direct]);
-    }
-    /** Enabled user- and project-dimension suites for a workspace cwd. */
-    async enabledSuitesForCwd(cwd) {
-        const [user, project] = await Promise.all([this.enabledUserSuites(), this.readProjectCatalog(cwd)]);
-        return { user, project: project.enabledSuites };
-    }
-    /** All suites of one dimension. */
-    async suitesForDimension(dimension, dimensionRoot) {
-        const state = dimension === 'user' && dimensionRoot === this.options.userRoot ? this.state : await loadState(join(dimensionRoot, STATE_FILE_NAME));
-        return (await this.buildSnapshot(state, dimension, dimensionRoot)).suites;
-    }
-    /**
-     * Add a source and acquire it immediately (clone, download, or in-place).
-     *
-     * Git sources with an already-present checkout whose `origin` matches the
-     * input URL are adopted in place — the manual-clone repair path — so no
-     * second clone is made and no `-2` suffixed id is invented. Adopted
-     * checkouts are never deleted on source removal.
-     */
+    // ---- Source acquisition and CRUD ----
+    /** Add a source and acquire it immediately (clone, download, or in-place). */
     async addSource(input) {
-        return this.enqueue(async () => {
-            const kind = input.local === true ? 'local' : resolveSourceKind({ url: input.url, kind: input.kind });
-            if (kind === 'git') {
-                // Adoption first: a pre-existing checkout with a matching origin URL
-                // is registered as-is, skipping the clone entirely.
-                const adoptable = await this.findAdoptableCheckout(input.url, deriveSourceIdCandidates(input.url));
-                if (adoptable !== undefined) {
-                    const source = {
-                        id: adoptable,
-                        url: input.url,
-                        ...(input.branch === undefined ? {} : { branch: input.branch }),
-                        kind: 'git',
-                        adopted: true
-                    };
-                    const head = await tryHead(sourceCheckoutDir(this.options.userRoot, adoptable));
-                    if (head !== undefined)
-                        this.headCache.set(source.id, head);
-                    this.state = { ...this.state, sources: [...this.state.sources, source] };
-                    await saveState(this.statePath, this.state);
-                    await this.notifyChanged();
-                    return source;
-                }
-            }
-            const baseId = await this.pickSourceId(deriveSourceIdCandidates(input.url), kind === 'local');
-            const source = {
-                id: baseId,
-                url: input.url,
-                ...(input.branch === undefined ? {} : { branch: input.branch }),
-                ...(kind === 'local' ? { local: true } : { kind }),
-                ...(input.kind === 'archive' && input.sha256 !== undefined && input.sha256 !== '' ? { sha256: input.sha256 } : {})
-            };
-            let checkout = this.sourceCheckoutPath(source);
-            if (kind === 'local') {
-                if (!(await isDirectory(checkout)))
-                    throw new Error(`local source directory ${checkout} is missing`);
-            }
-            else {
-                this.beginSourceState(baseId, kind === 'archive' ? 'downloading' : 'cloning', false);
-                try {
-                    const lock = await this.acquire(source);
-                    if (lock !== undefined)
-                        this.headCache.set(source.id, lock);
-                }
-                catch (error) {
-                    this.endSourceState();
-                    throw error;
-                }
-                this.updateSourceStep('reading');
-            }
-            // The repo's own manifest names the source; move the checkout along so
-            // the registered id and its `.sources/` directory stay coherent. URL
-            // derived candidates stay as readable fallbacks before numeric suffixes.
-            const named = [...new Set([sanitizeId(await repoName(checkout)), ...deriveSourceIdCandidates(input.url)])];
-            const finalId = await this.pickSourceId(named, kind === 'local', kind === 'local' ? undefined : checkout);
-            if (kind !== 'local' && finalId !== baseId) {
-                const targetDir = sourceCheckoutDir(this.options.userRoot, finalId);
-                await rename(checkout, targetDir);
-                checkout = targetDir;
-            }
-            source.id = finalId;
-            if (resolveSourceKind(source) === 'git') {
-                const head = await tryHead(checkout);
-                if (head !== undefined)
-                    this.headCache.set(source.id, head);
-            }
-            this.endSourceState();
-            this.state = { ...this.state, sources: [...this.state.sources, source] };
-            await saveState(this.statePath, this.state);
-            await this.notifyChanged();
-            return source;
-        });
-    }
-    /**
-     * First candidate id whose `.sources/` checkout already exists and whose
-     * `origin` remote matches the input URL (canonical-form equality) — the
-     * signature of a manual clone of the very same repository. Registered ids
-     * and checkouts of differently-origined directories never adopt.
-     */
-    async findAdoptableCheckout(url, candidates) {
-        const registered = new Set(this.state.sources.map(source => source.id));
-        for (const candidate of candidates) {
-            if (registered.has(candidate))
-                continue;
-            const dir = sourceCheckoutDir(this.options.userRoot, candidate);
-            if (!(await isDirectory(dir)))
-                continue;
-            let origin;
-            try {
-                origin = await gitRemoteUrl(dir);
-            }
-            catch {
-                continue;
-            }
-            if (origin !== '' && canonicalGitUrl(origin) === canonicalGitUrl(url))
-                return candidate;
-        }
-        return undefined;
+        return this.sourceStore.add(input);
     }
     /** Register one unmanaged `.sources/` checkout as a source without touching its files. */
     async adoptSource(id) {
-        return this.enqueue(async () => {
-            if (this.state.sources.some(source => source.id === id))
-                throw new Error(`source "${id}" is already registered`);
-            // The id becomes one path segment under `.sources/`: only flat safe
-            // names qualify. Anything else (separators, `..`, leading dots) could
-            // traverse out of the checkouts root and register an outside directory.
-            if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || id.includes('..')) {
-                throw new Error(`invalid checkout id "${id}" — use letters, digits, dots, dashes, or underscores`);
-            }
-            const dir = sourceCheckoutDir(this.options.userRoot, id);
-            if (!(await isDirectory(dir)))
-                throw new Error(`no checkout directory at ${dir}`);
-            let source;
-            try {
-                const origin = await gitRemoteUrl(dir);
-                source = { id, url: origin, kind: 'git', adopted: true };
-                const head = await tryHead(dir);
-                if (head !== undefined)
-                    this.headCache.set(id, head);
-            }
-            catch {
-                // Not a git checkout: read it in place, like a local source.
-                source = { id, url: dir, local: true, adopted: true };
-            }
-            this.state = { ...this.state, sources: [...this.state.sources, source] };
-            await saveState(this.statePath, this.state);
-            await this.notifyChanged();
-            return source;
-        });
+        return this.sourceStore.adopt(id);
     }
     /** Unmanaged `.sources/` checkouts: present on disk, absent from state. */
     async unmanagedSources() {
-        const checkoutRoot = sourcesDir(this.options.userRoot);
-        let entries;
-        try {
-            entries = await readdir(checkoutRoot, { withFileTypes: true });
-        }
-        catch {
-            return [];
-        }
-        const registered = new Set(this.state.sources.map(source => source.id));
-        const unmanaged = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.') || registered.has(entry.name))
-                continue;
-            const dir = join(checkoutRoot, entry.name);
-            try {
-                unmanaged.push({ id: entry.name, url: await gitRemoteUrl(dir) });
-            }
-            catch {
-                unmanaged.push({ id: entry.name });
-            }
-        }
-        return unmanaged;
+        return this.sourceStore.unmanaged();
     }
-    /** Progress snapshot of the source mutation currently in flight. */
-    currentSourceState;
-    /** Begin reporting progress for a source mutation. */
-    beginSourceState(sourceId, step, cloned) {
-        this.currentSourceState = { sourceId, step, cloned };
+    /** Update one source's URL, branch, kind, or archive digest. */
+    async updateSource(sourceId, patch) {
+        await this.sourceStore.update(sourceId, patch);
     }
-    /** Advance the in-flight source mutation step. */
-    updateSourceStep(step) {
-        if (this.currentSourceState !== undefined)
-            this.currentSourceState = { ...this.currentSourceState, step };
+    /** Remove a source and its install entries; `deleteCheckout` also deletes the managed checkout. */
+    async removeSource(sourceId, deleteCheckout = false) {
+        await this.sourceStore.remove(sourceId, deleteCheckout);
     }
-    /** Stop reporting source mutation progress. */
-    endSourceState() {
-        this.currentSourceState = undefined;
+    /** Refresh one source checkout, or every source when sourceId is omitted. */
+    async refreshSource(sourceId) {
+        await this.sourceStore.refresh(sourceId);
     }
     /** Progress snapshot for the progress route. */
     sourceProgress() {
-        const state = this.currentSourceState;
-        return state === undefined ? { active: false, sourceId: '', step: '' } : { active: true, sourceId: state.sourceId, step: state.step };
-    }
-    /**
-     * First candidate id not claimed by a registered source; for git candidates
-     * the checkout directory must also be free, so a stale or foreign directory
-     * under `.sources/` is never cloned over (it would fail `git clone` with a
-     * confusing "destination exists" error). `ownedCheckout` marks the directory
-     * the in-flight mutation already controls, keeping a rename onto it legal.
-     * Local sources skip the disk check: they read their own path in place and
-     * never occupy `.sources/`.
-     */
-    async pickSourceId(candidates, skipDisk, ownedCheckout) {
-        const free = async (id) => {
-            if (this.state.sources.some(source => source.id === id))
-                return false;
-            if (skipDisk)
-                return true;
-            const dir = sourceCheckoutDir(this.options.userRoot, id);
-            return dir === ownedCheckout || !(await pathExists(dir));
-        };
-        for (const candidate of candidates) {
-            if (await free(candidate))
-                return candidate;
-        }
-        for (let suffix = 2;; suffix++) {
-            const candidate = `${candidates[0]}-${suffix}`;
-            if (await free(candidate))
-                return candidate;
-        }
+        return this.sourceStore.progress();
     }
-    /** Update one source's URL, branch, kind, or archive digest. */
-    async updateSource(sourceId, patch) {
-        return this.enqueue(async () => {
-            const index = this.state.sources.findIndex(source => source.id === sourceId);
-            if (index === -1)
-                throw new Error(`unknown source "${sourceId}"`);
-            const current = this.state.sources[index];
-            const nextLocal = patch.local !== undefined ? patch.local : current.local === true;
-            // A local source carries the legacy flag only; `kind` stays unwritten
-            // so the persisted shape matches the pre-kind records.
-            const nextKind = nextLocal ? undefined : (patch.kind ?? current.kind);
-            const next = {
-                id: sourceId,
-                url: patch.url ?? current.url,
-                ...(patch.branch !== undefined ? { branch: patch.branch } : current.branch === undefined ? {} : { branch: current.branch }),
-                ...(nextLocal ? { local: true } : {}),
-                ...(nextKind === undefined ? {} : { kind: nextKind }),
-                ...(patch.sha256 !== undefined ? (patch.sha256 === '' ? {} : { sha256: patch.sha256 }) : current.sha256 === undefined ? {} : { sha256: current.sha256 }),
-                ...(current.adopted === true ? { adopted: true } : {})
-            };
-            const urlChanged = patch.url !== undefined && patch.url !== current.url;
-            // A URL change invalidates the old checkout — except for adopted (user
-            // cloned) and local sources, whose directories we never own.
-            if (urlChanged && current.local !== true && current.adopted !== true) {
-                this.headCache.delete(sourceId);
-                await gitRemove(sourceCheckoutDir(this.options.userRoot, sourceId));
-            }
-            this.state = { ...this.state, sources: this.state.sources.map((source, i) => (i === index ? next : source)) };
-            await saveState(this.statePath, this.state);
-            await this.notifyChanged();
-        });
+    /** Begin reporting progress for a source mutation. */
+    beginSourceState(sourceId, step, cloned) {
+        this.sourceStore.beginSourceState(sourceId, step, cloned);
     }
-    /**
-     * Remove a source and its install entries. `deleteCheckout` (the UI's
-     * "also delete the managed market directory" option) physically removes the
-     * `.sources/<id>` checkout — including an adopted one, since a directory
-     * under `.sources` is manager-owned storage. A `local` source whose URL
-     * points outside `.sources` is registration-only: its directory is never
-     * touched. Deleting the checkout is what keeps a removed source from
-     * reappearing as an unmanaged entry.
-     */
-    async removeSource(sourceId, deleteCheckout = false) {
-        return this.enqueue(async () => {
-            const source = this.state.sources.find(entry => entry.id === sourceId);
-            this.state = {
-                ...this.state,
-                sources: this.state.sources.filter(entry => entry.id !== sourceId),
-                installed: Object.fromEntries(Object.entries(this.state.installed).filter(([key]) => !key.startsWith(`${sourceId}/`)))
-            };
-            await saveState(this.statePath, this.state);
-            this.headCache.delete(sourceId);
-            // A checkout under `.sources` is manager-owned even when it was first
-            // discovered/adopted. Only an explicit local path points outside the
-            // manager's storage and must remain untouched.
-            const externalLocal = source?.local === true && source.url !== sourceCheckoutDir(this.options.userRoot, sourceId);
-            if (!externalLocal && deleteCheckout)
-                await gitRemove(sourceCheckoutDir(this.options.userRoot, sourceId));
-            await this.notifyChanged();
-        });
+    /** Advance the in-flight source mutation step. */
+    updateSourceStep(step) {
+        this.sourceStore.updateSourceStep(step);
     }
-    /** Refresh one source checkout, or every source when sourceId is omitted. */
-    async refreshSource(sourceId) {
-        return this.enqueue(async () => {
-            const targets = sourceId === undefined ? this.state.sources : this.state.sources.filter(source => source.id === sourceId);
-            for (const source of targets) {
-                const kind = resolveSourceKind(source);
-                if (kind === 'local') {
-                    if (!(await isDirectory(expandHome(source.url))))
-                        throw new Error(`local source directory ${expandHome(source.url)} is missing`);
-                    continue;
-                }
-                const checkout = sourceCheckoutDir(this.options.userRoot, source.id);
-                this.headCache.delete(source.id);
-                if (kind === 'archive') {
-                    // Re-download and swap; the fresh digest becomes the lock value.
-                    const lock = await this.acquire(source);
-                    if (lock !== undefined)
-                        this.headCache.set(source.id, lock);
-                    continue;
-                }
-                // Adopted checkouts are user-owned working trees: no `reset --hard`
-                // (it would destroy uncommitted work), and no re-acquire either —
-                // a broken HEAD means the user repairs the checkout, not that the
-                // manager may clone or extract over their directory.
-                if (source.adopted === true) {
-                    try {
-                        this.headCache.set(source.id, await gitHead(checkout));
-                    }
-                    catch {
-                        // A failed HEAD read means the next overview re-probes.
-                    }
-                    continue;
-                }
-                try {
-                    await gitHead(checkout);
-                }
-                catch {
-                    const lock = await this.acquire(source);
-                    if (lock !== undefined) {
-                        this.headCache.set(source.id, lock);
-                    }
-                    else {
-                        try {
-                            this.headCache.set(source.id, await gitHead(checkout));
-                        }
-                        catch {
-                            // A failed HEAD read means the next overview re-probes.
-                        }
-                    }
-                    continue;
-                }
-                // Shallow-friendly sync: fetch depth 1 into FETCH_HEAD, hard reset.
-                const branch = source.branch ?? (await gitCurrentBranch(checkout).catch(() => undefined));
-                // Keep origin on the region's route: a clone made before a region
-                // switch (or an explicit flip) re-points origin so the fetch follows.
-                // Only origins this plugin itself wrote (the direct or proxied
-                // source.url) are re-pointed — a foreign remote is left untouched.
-                if (source.kind === 'git' || (source.kind === undefined && source.local !== true)) {
-                    try {
-                        const region = resolveRegion(await this.downloadRegionProvider(), await readLocalePreference());
-                        const routed = githubCloneUrl(region, source.url);
-                        const origin = await gitRemoteUrl(checkout);
-                        if (origin !== routed && (origin === source.url || origin === githubCloneUrl('china', source.url))) {
-                            await gitSetRemoteUrl(checkout, routed);
-                        }
-                    }
-                    catch {
-                        // Origin reconciliation is best effort; plain sync still runs.
-                    }
-                }
-                await gitSync(checkout, branch, this.options.git ?? {});
-                try {
-                    this.headCache.set(source.id, await gitHead(checkout));
-                }
-                catch {
-                    // A failed HEAD read means the next overview re-probes.
-                }
-            }
-            await this.notifyChanged();
-        });
+    /** Stop reporting source mutation progress. */
+    endSourceState() {
+        this.sourceStore.endSourceState();
     }
-    /** Install a suite from a source and enable it. The client confirms the
-     * injected surfaces (skills / MCP / hooks / commands) in a pre-install
-     * dialog before this runs; disabling afterwards is always available. */
+    // ---- Install state ----
+    /** Install a suite from a source and enable it. */
     async install(sourceId, suiteId) {
-        return this.enqueue(async () => {
-            const source = this.state.sources.find(entry => entry.id === sourceId);
-            if (source === undefined)
-                throw new Error(`unknown source "${sourceId}"`);
-            const checkout = this.sourceCheckoutPath(source);
-            let freshLock;
-            if (!(await isDirectory(checkout)))
-                freshLock = await this.acquire(source);
-            const suites = await discoverSuitesInSource(checkout, sourceId, 'user', source.url);
-            const suite = suites.find(entry => entry.id === suiteId);
-            if (suite === undefined)
-                throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
-            if (suite.remote !== undefined)
-                throw new Error(`suite "${suiteId}" is a remote reference (${suite.remote.url}); add its repository as a source before installing`);
-            // Archive (or tarball-fallback) sources have no git HEAD; their digest
-            // is the lock value.
-            const lockCommit = (await tryHead(checkout)) ?? freshLock ?? this.headCache.get(sourceId);
-            await this.setInstalled(sourceId, suiteId, { enabled: true, installedAt: new Date().toISOString(), lockCommit });
-            await this.notifyChanged(true);
-        });
+        await this.installs.install(sourceId, suiteId);
     }
     /** Uninstall a suite while retaining the source checkout. */
     async uninstall(sourceId, suiteId) {
-        return this.enqueue(async () => {
-            const key = installKey(sourceId, suiteId);
-            if (this.state.installed[key] === undefined)
-                throw new Error(`suite "${suiteId}" is not installed`);
-            const rest = Object.fromEntries(Object.entries(this.state.installed).filter(([entryKey]) => entryKey !== key));
-            this.state = { ...this.state, installed: rest };
-            await saveState(this.statePath, this.state);
-            await this.notifyChanged(true);
-        });
+        await this.installs.uninstall(sourceId, suiteId);
     }
     /** Enable or disable an installed suite. */
     async setEnabled(sourceId, suiteId, enabled) {
-        return this.enqueue(async () => {
-            const key = installKey(sourceId, suiteId);
-            const entry = this.state.installed[key];
-            if (entry === undefined)
-                throw new Error(`suite "${suiteId}" is not installed`);
-            await this.setInstalled(sourceId, suiteId, { ...entry, enabled });
-            await this.notifyChanged(true);
-        });
+        await this.installs.setEnabled(sourceId, suiteId, enabled);
     }
     /** Enable or disable one runtime surface of an installed suite. */
     async setSurface(sourceId, suiteId, surface, enabled) {
-        return this.enqueue(async () => {
-            const key = installKey(sourceId, suiteId);
-            const entry = this.state.installed[key];
-            if (entry === undefined)
-                throw new Error(`suite "${suiteId}" is not installed`);
-            if (!SUITE_SURFACE_KEYS.includes(surface))
-                throw new Error(`surface "${surface}" is not toggleable`);
-            const surfaces = { ...(entry.surfaces ?? {}), [surface]: enabled };
-            await this.setInstalled(sourceId, suiteId, { ...entry, surfaces });
-            await this.notifyChanged(true);
-        });
+        await this.installs.setSurface(sourceId, suiteId, surface, enabled);
     }
-    /** Append config-seeded sources missing from user state and persist them. */
-    async mergeSources(sources) {
-        const existing = new Set(this.state.sources.map(source => source.id));
-        const additions = sources.filter(source => !existing.has(source.id));
-        if (additions.length === 0)
-            return;
-        this.state = { ...this.state, sources: [...this.state.sources, ...additions] };
-        await saveState(this.statePath, this.state);
-        // New sources change the fingerprint, but their content arrives through
-        // an acquire, so mark the scan cache dirty conservatively.
-        this.invalidateScans();
-        this.invalidateSnapshot(true);
+    // ---- MCP ----
+    /** Build the flat MCP service inventory for the status surface. */
+    async mcpStatus() {
+        return this.mcp.status();
     }
-    /**
-     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
-     * (skills / commands / agent personas). Catalog state is untouched — this
-     * only runs the change pipeline so the runtime remounts commands and the
-     * skill providers re-read their catalogs.
-     */
-    async notifyPanelsChanged() {
-        await this.notifyChanged();
+    /** Persist a user-owned MCP service and reconcile its bridge mount. */
+    async addMcpServer(name, server) {
+        await this.mcp.addServer(name, server);
     }
-    async setInstalled(sourceId, suiteId, entry) {
-        this.state = { ...this.state, installed: { ...this.state.installed, [installKey(sourceId, suiteId)]: entry } };
-        await saveState(this.statePath, this.state);
+    /** Read effective service configuration without exposing credential literals. */
+    async serverConfig(kind, id) {
+        return this.mcp.serverConfig(kind, id);
+    }
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    async saveServerConfig(kind, id, config) {
+        await this.mcp.saveServerConfig(kind, id, config);
+    }
+    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
+    async mcpOverrides(sourceId, suiteId) {
+        return this.mcp.overrides(sourceId, suiteId);
+    }
+    /** Set or clear one server's MCP override and remount it. */
+    async setMcpOverride(sourceId, suiteId, serverKey, override) {
+        await this.mcp.setOverride(sourceId, suiteId, serverKey, override);
     }
     /**
-     * Acquire one source's content by kind: clone (git), download+extract
-     * (archive), or an in-place existence check (local). Returns a lock value
-     * when the acquisition yields one (archive SHA-256, tarball fallback
-     * digest); git HEAD is read separately by the callers.
+     * Enable or disable one declared MCP server, addressed by the same
+     * source-qualified suite id its status row carries. Disabling writes an
+     * override rather than editing the suite's `mcp.json`, so a refresh cannot
+     * clobber the user's choice.
      */
-    async acquire(source) {
-        const kind = resolveSourceKind(source);
-        if (kind === 'local') {
-            if (!(await isDirectory(expandHome(source.url))))
-                throw new Error(`local source directory ${expandHome(source.url)} is missing`);
-            return undefined;
-        }
-        const checkout = sourceCheckoutDir(this.options.userRoot, source.id);
-        await mkdir(sourcesDir(this.options.userRoot), { recursive: true });
-        if (kind === 'archive') {
-            const { sha256 } = await archiveInstall(source.url, checkout, {
-                ...(source.sha256 === undefined ? {} : { sha256: source.sha256 }),
-                ...(this.options.git?.timeoutMs === undefined ? {} : { timeoutMs: this.options.git.timeoutMs }),
-                ...(this.options.git?.allowHttpArchives === true ? { allowHttp: true } : {})
-            });
-            return sha256;
-        }
-        try {
-            // The region routes github.com clones through the China mirror prefix;
-            // the proxied URL becomes `origin`, so refreshes follow the same route.
-            const region = resolveRegion(await this.downloadRegionProvider(), await readLocalePreference());
-            await gitClone(githubCloneUrl(region, source.url), source.branch, checkout, this.options.git ?? {});
-            return undefined;
-        }
-        catch (error) {
-            if (this.options.git?.fallbackTarball !== true)
-                throw error;
-            const tarballUrl = codeloadTarballUrl(source.url, source.branch);
-            if (tarballUrl === undefined)
-                throw error;
-            // The codeload URL ends in a branch path, not `.tar.gz`, so the format
-            // must be stated explicitly — extension detection cannot see it.
-            const { sha256 } = await archiveInstall(tarballUrl, checkout, {
-                ...(this.options.git?.timeoutMs === undefined ? {} : { timeoutMs: this.options.git.timeoutMs }),
-                format: 'targz'
-            });
-            return sha256;
-        }
+    async setMcpServerEnabled(suiteKey, serverKey, enabled) {
+        await this.mcp.setServerEnabled(suiteKey, serverKey, enabled);
     }
-    /** The filesystem location of one source. */
-    sourceCheckoutPath(source) {
-        return source.local === true ? expandHome(source.url) : sourceCheckoutDir(this.options.userRoot, source.id);
+    /** Re-run the MCP reconcile pass without changing any catalog state. */
+    async retryMounts() {
+        await this.mcp.retryMounts();
     }
-    async buildSnapshot(state, dimension, dimensionRoot, skipScanCache = false) {
-        const fingerprint = JSON.stringify([dimension, dimensionRoot, state.sources, this.scanProjectLayouts]);
-        const cached = this.scanCache.get(fingerprint);
-        // The user snapshot's TTL also bounds scan reuse: a snapshot rebuild that
-        // replays a 30s scan cache would silently outlive its own staleness bound.
-        const scanCacheTtl = dimension === 'user' ? Math.min(this.userSnapshotTtlMs, Catalog.SCAN_CACHE_TTL_MS) : Catalog.SCAN_CACHE_TTL_MS;
-        const cacheFresh = !skipScanCache && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
-        let discovered;
-        let scanNotes;
-        if (cacheFresh && cached !== undefined) {
-            discovered = cached.discovered;
-            scanNotes = cached.scanNotes;
-        }
-        else {
-            const generation = this.scanGeneration;
-            let pending = this.scanPromises.get(fingerprint);
-            if (pending === undefined) {
-                pending = discoverSourceListWithNotes(state.sources, dimension, dimensionRoot, this.scanProjectLayouts);
-                this.scanPromises.set(fingerprint, pending);
-            }
-            let result;
-            try {
-                result = await pending;
-            }
-            finally {
-                if (this.scanPromises.get(fingerprint) === pending)
-                    this.scanPromises.delete(fingerprint);
-            }
-            discovered = result.suites;
-            scanNotes = result.scanNotes;
-            // A scan started before a content mutation must not repopulate its cache.
-            if (generation === this.scanGeneration) {
-                if (this.scanCache.size >= Catalog.SCAN_CACHE_MAX_ENTRIES)
-                    this.scanCache.clear();
-                this.scanCache.set(fingerprint, { at: Date.now(), discovered, scanNotes });
-            }
-        }
-        const suites = discovered.map(suite => {
-            const installed = state.installed[installKey(suite.sourceId, suite.id)];
-            // Native project layouts (`.claude/`, `.agents/`) are the repository's
-            // own files read in place: they carry no install state and stay enabled.
-            const enabled = suite.manifest.layout === 'project-native' || installed?.enabled === true;
-            return {
-                ...suite,
-                enabled,
-                activeSurfaces: {
-                    ...effectiveSurfaces(installed?.surfaces),
-                    ...(suite.manifest.layout === 'project-native' ? suite.activeSurfaces : {}),
-                    ...(dimension === 'project' ? { lsp: false } : {})
-                },
-                ...(installed?.lockCommit === undefined ? {} : { lockCommit: installed.lockCommit }),
-                ...(installed?.installedAt === undefined ? {} : { installedAt: installed.installedAt })
-            };
-        });
-        return {
-            revision: this.revision,
-            sources: [...state.sources],
-            suites,
-            enabledSuites: suites.filter(suite => suite.enabled),
-            ...(Object.keys(scanNotes).length > 0 ? { scanNotes } : {})
-        };
+    /** The persisted MCP backend choice without the host-client probe. */
+    async mcpBackend() {
+        return this.mcp.backend();
     }
-    invalidateSnapshot(increment) {
-        if (increment)
-            this.revision++;
-        this.userSnapshot = undefined;
-        this.userSnapshotExpiresAt = 0;
-        this.userSnapshotPromise = undefined;
-        this.projectSnapshots.clear();
-        this.projectSnapshotPromises.clear();
+    /**
+     * The active MCP mount backend plus a live probe of the host client, and
+     * the download-region setting with its locale-resolved effective route.
+     */
+    async mcpBackendInfo() {
+        return this.mcp.backendInfo();
     }
-    invalidateScans() {
-        this.scanGeneration++;
-        this.scanCache.clear();
-        this.scanPromises.clear();
+    /** Switch the MCP mount backend and remount every suite server through it. */
+    async setMcpBackend(backend) {
+        await this.mcp.setBackend(backend);
     }
     /**
-     * Invalidate snapshots and run the change pipeline. `keepScanCache` marks
-     * state-only mutations (install, enable, surface toggles, MCP overrides)
-     * whose inputs leave every checkout untouched, so the next snapshot
-     * re-derives from cached discovery instead of rescanning the filesystem.
+     * Drop one MCP server's OAuth grant record so the next mount re-runs the
+     * browser authorization.
+     * @throws when the credentials service is not mounted.
      */
-    async notifyChanged(keepScanCache = false) {
-        if (!keepScanCache)
-            this.invalidateScans();
-        this.invalidateSnapshot(true);
-        await this.options.onChanged();
-        for (const listener of this.listeners)
-            listener();
+    async reauthorizeMcpServer(serverName) {
+        await this.mcp.reauthorize(serverName);
     }
-    enqueue(operation) {
-        const result = this.mutationQueue.then(operation, operation);
-        this.mutationQueue = result.catch(() => { });
-        return result;
+    /** Whether the re-authorize action can run in this composition. */
+    mcpReauthorizeAvailable() {
+        return this.mcp.reauthorizeAvailable();
     }
-}
-function installKey(sourceId, suiteId) {
-    return `${sourceId}/${suiteId}`;
-}
-/** Read a checkout's HEAD when it is a Git repository. */
-async function tryHead(dir) {
-    try {
-        return await gitHead(dir);
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    async allMcpOverrides(suites) {
+        return this.mcp.allOverrides(suites);
     }
-    catch {
-        return undefined;
+    // ---- LSP ----
+    /** The LSP status surface: declared servers merged with mount diagnostics. */
+    async lspStatus() {
+        return this.lsp.status();
+    }
+    /** The user's direct LSP server table (normalized specs). */
+    async lspServers() {
+        return this.lsp.servers();
+    }
+    /** Create one direct LSP declaration without replacing other user servers. */
+    async addLspServer(name, config) {
+        await this.lsp.addServer(name, config);
+    }
+    /** Validate and persist the user's direct LSP server table. */
+    async setLspServers(raw) {
+        return this.lsp.setServers(raw);
+    }
+    /** Enable or disable one declared language server by row id. */
+    async setLspServerEnabled(id, enabled) {
+        await this.lsp.setEnabled(id, enabled);
+    }
+    /**
+     * Remove one profile's legacy LSP layer — the hand-written
+     * `cordis.patch.yml` rows an older release told users to add, which now
+     * register a seam this plugin owns.
+     */
+    async migrateLegacyLspSeam(profile) {
+        return this.lsp.migrateLegacySeam(profile);
     }
 }
-/**
- * The codeload tarball URL of a GitHub repository, or undefined for any
- * other host. `https://github.com/<owner>/<repo>` maps to
- * `https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/<branch>`
- * (or `/tar.gz/HEAD` for the default branch) — the git-protocol fallback
- * when a clone cannot get through but plain HTTPS file download can.
- */
-export function codeloadTarballUrl(url, branch) {
-    const match = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
-    if (match === null)
-        return undefined;
-    const [, owner, repo] = match;
-    return `https://codeload.github.com/${owner}/${repo}/tar.gz/${branch === undefined ? 'HEAD' : `refs/heads/${branch}`}`;
-}
+export { codeloadTarballUrl };