dsh-agent-plugins-market 0.5.3 → 0.6.0

package/lib/application/catalog.js

@@ -7,18 +7,26 @@
  * project snapshots use their own persisted state files and share the same
  * source-selection and suite-scanning rules.
  */
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readdir, rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { repoName } from '../catalog/manifests.js';
-import { discoverSourceList } from '../catalog/source-catalog.js';
+import { canonicalGitUrl } from '../catalog/scan-resolvers.js';
+import { discoverSourceListWithNotes } from '../catalog/source-catalog.js';
 import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
-import { gitClone, gitHead, gitPull, gitRemove } from '../catalog/git.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 { loadSuiteOverrides, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { buildLspStatus } from '../runtime/lsp-status.js';
+import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
+import { loadSuiteOverrides, mergeOverridePatch, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { probeHostMcpClient } from '../runtime/mcp-backend.js';
+import { githubCloneUrl, resolveRegion } from '../runtime/regions.js';
+import { readLocalePreference } from '../runtime/host-locale.js';
+import { redactMcpOverrides } from '../runtime/mcp-redaction.js';
 import { buildSuiteDetail, readSkillContent } from './details.js';
-import { deriveSourceId, expandHome, isDirectory, resolveProjectRoot, sanitizeId, sourceCheckoutDir, sourcesDir, STATE_FILE_NAME } from '../catalog/paths.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 } from '../model/types.js';
+import { effectiveSurfaces, SUITE_SURFACE_KEYS, resolveSourceKind } from '../model/types.js';
 export class Catalog {
     options;
     state = EMPTY_STATE;
@@ -28,23 +36,102 @@ export class Catalog {
     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) set {@link scanCacheDirty}, which bypasses the cache
+     * until the next scan; the TTL bounds staleness for in-place working-tree
+     * edits of local sources.
+     */
+    scanCache = new Map();
+    scanCacheDirty = true;
+    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';
     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;
+    }
     /** Subscribe to completed catalog mutations; returns an unsubscribe function. */
     subscribe(listener) {
         this.listeners.add(listener);
@@ -55,12 +142,31 @@ export class Catalog {
         const snapshot = await this.readUserCatalog();
         return buildMcpStatus(snapshot.suites, this.mcpDiagnostics, this.toolSnapshotProvider(), await this.allMcpOverrides());
     }
-    /** One suite's persisted MCP overrides. */
-    async mcpOverrides(suiteId) {
+    /** The LSP status surface: declared servers merged with mount diagnostics. */
+    async lspStatus() {
         const snapshot = await this.readUserCatalog();
-        if (!snapshot.suites.some(suite => suite.id === suiteId))
-            throw new Error(`suite "${suiteId}" not found`);
-        return loadSuiteOverrides(this.options.dataRoot, suiteId);
+        const direct = await loadLspServers(this.options.dataRoot);
+        return buildLspStatus(snapshot.suites, this.lspStatusSource ?? { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false }, direct);
+    }
+    /** The user's direct LSP server table (normalized specs). */
+    async lspServers() {
+        return (await loadLspServers(this.options.dataRoot)).servers;
+    }
+    /** 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;
+        });
+    }
+    /** 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));
     }
     /**
      * Set or clear one server's MCP override and remount it. `override === null`
@@ -69,43 +175,93 @@ export class Catalog {
      */
     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);
             if (source === undefined)
                 throw new Error(`unknown source "${sourceId}"`);
             const checkout = this.sourceCheckoutPath(source);
             if (!(await isDirectory(checkout)))
-                await this.ensureClone(source);
-            const suites = await discoverSuitesInSource(checkout, sourceId, 'user');
+                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.mcp?.servers[serverKey] === undefined)
                 throw new Error(`server "${serverKey}" is not defined by suite "${suiteId}"`);
-            const overrides = await loadSuiteOverrides(this.options.dataRoot, 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 {
-                overrides[serverKey] = override;
+                // 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, suiteId, overrides);
-            this.notifyChanged();
+            await saveSuiteOverrides(this.options.dataRoot, suiteKey, overrides);
+            await this.notifyChanged(true);
         });
     }
-    /** All persisted MCP overrides keyed by suite id (mount-time provider). */
+    /**
+     * Re-run the MCP reconcile pass: retries failed mounts and clears residual
+     * tools, without changing any catalog state.
+     */
+    async retryMounts() {
+        await this.notifyChanged(true);
+    }
+    /** The persisted backend choice without the host-client probe (mount-time provider). */
+    async mcpBackend() {
+        return this.mcpBackendProvider();
+    }
+    /**
+     * 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.
+     */
+    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) } };
+    }
+    /**
+     * 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.
+     */
+    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;
+    }
+    /** All persisted MCP overrides keyed by qualified suite id (mount-time provider). */
     async allMcpOverrides() {
         const snapshot = await this.readUserCatalog();
         const map = new Map();
         for (const suite of snapshot.suites) {
-            const overrides = await loadSuiteOverrides(this.options.dataRoot, suite.id);
+            const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
+            const overrides = await loadSuiteOverrides(this.options.dataRoot, suiteKey);
             if (Object.keys(overrides).length > 0)
-                map.set(suite.id, overrides);
+                map.set(suiteKey, overrides);
         }
         return map;
     }
     /** Load persisted user state once at plugin activation. */
     async load() {
         this.state = await loadState(this.statePath);
+        this.scanCacheDirty = true;
         this.invalidateSnapshot(false);
     }
     get sources() {
@@ -117,11 +273,16 @@ export class Catalog {
     }
     /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
     async readUserCatalog() {
-        if (this.userSnapshot !== undefined)
+        // 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;
         this.userSnapshotPromise ??= this.buildSnapshot(this.state, 'user', this.options.userRoot)
             .then(snapshot => {
             this.userSnapshot = snapshot;
+            this.userSnapshotExpiresAt = Date.now() + this.userSnapshotTtlMs;
             return snapshot;
         })
             .finally(() => {
@@ -153,7 +314,9 @@ export class Catalog {
     }
     async buildProjectSnapshot(projectRoot) {
         const state = await loadState(join(projectRoot, STATE_FILE_NAME));
-        return this.buildSnapshot(state, 'project', projectRoot);
+        // 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);
     }
     /** One suite's full detail for the market detail modal. */
     async suiteDetail(sourceId, suiteId) {
@@ -161,7 +324,8 @@ export class Catalog {
         const suite = snapshot.suites.find(entry => entry.sourceId === sourceId && entry.id === suiteId);
         if (suite === undefined)
             throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
-        return buildSuiteDetail(suite, this.state.installed[installKey(sourceId, suiteId)], this.mcpDiagnostics, await loadSuiteOverrides(this.options.dataRoot, suiteId));
+        const suiteKey = qualifiedSuiteId(sourceId, suiteId);
+        return buildSuiteDetail(suite, this.state.installed[installKey(sourceId, suiteId)], this.mcpDiagnostics, await loadSuiteOverrides(this.options.dataRoot, suiteKey));
     }
     /** One skill's full SKILL.md text for the market detail modal. */
     async skillContent(sourceId, suiteId, skillName) {
@@ -178,14 +342,19 @@ export class Catalog {
         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 (source.local === true) {
+            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));
@@ -209,14 +378,18 @@ export class Catalog {
                 }
             }
             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)
             });
         }
@@ -246,7 +419,8 @@ export class Catalog {
                 installed: cards.filter(card => card.installed).length,
                 enabled: cards.filter(card => card.enabled).length
             },
-            roots: { user: this.options.userRoot, data: this.options.dataRoot }
+            roots: { user: this.options.userRoot, data: this.options.dataRoot },
+            unmanaged: await this.unmanagedSources()
         };
     }
     /** Enabled user-dimension suites from one user snapshot. */
@@ -263,25 +437,57 @@ export class Catalog {
         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 clone it immediately. */
+    /**
+     * 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.
+     */
     async addSource(input) {
         return this.enqueue(async () => {
-            const baseId = this.uniqueSourceId(deriveSourceId(input.url));
+            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 }),
-                ...(input.local === true ? { local: true } : {})
+                ...(kind === 'local' ? { local: true } : { kind }),
+                ...(input.kind === 'archive' && input.sha256 !== undefined && input.sha256 !== '' ? { sha256: input.sha256 } : {})
             };
-            const checkout = this.sourceCheckoutPath(source);
-            if (input.local === true) {
+            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, 'cloning', false);
+                this.beginSourceState(baseId, kind === 'archive' ? 'downloading' : 'cloning', false);
                 try {
-                    await this.ensureClone(source);
+                    const lock = await this.acquire(source);
+                    if (lock !== undefined)
+                        this.headCache.set(source.id, lock);
                 }
                 catch (error) {
                     this.endSourceState();
@@ -289,17 +495,112 @@ export class Catalog {
                 }
                 this.updateSourceStep('reading');
             }
-            source.id = this.uniqueSourceId(sanitizeId(await repoName(checkout)));
-            const head = await tryHead(checkout);
-            if (head !== undefined)
-                this.headCache.set(source.id, head);
+            // 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);
-            this.notifyChanged();
+            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;
+    }
+    /** 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;
+        });
+    }
+    /** 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;
+    }
     /** Progress snapshot of the source mutation currently in flight. */
     currentSourceState;
     /** Begin reporting progress for a source mutation. */
@@ -320,35 +621,64 @@ export class Catalog {
         const state = this.currentSourceState;
         return state === undefined ? { active: false, sourceId: '', step: '' } : { active: true, sourceId: state.sourceId, step: state.step };
     }
-    uniqueSourceId(derived) {
-        if (!this.state.sources.some(source => source.id === derived))
-            return derived;
+    /**
+     * 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 = `${derived}-${suffix}`;
-            if (!this.state.sources.some(source => source.id === candidate))
+            const candidate = `${candidates[0]}-${suffix}`;
+            if (await free(candidate))
                 return candidate;
         }
     }
-    /** Update one source's URL, branch, or local flag. */
+    /** 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 }),
-                ...(patch.local !== undefined ? { local: patch.local } : current.local === undefined ? {} : { local: current.local })
+                ...(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 } : {})
             };
-            if (current.local !== true && patch.url !== undefined && patch.url !== current.url) {
+            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);
-            this.notifyChanged();
+            await this.notifyChanged();
         });
     }
     /** Remove a source, its install entries, and its managed checkout. */
@@ -362,9 +692,12 @@ export class Catalog {
             };
             await saveState(this.statePath, this.state);
             this.headCache.delete(sourceId);
-            if (source === undefined || source.local !== true)
+            // Adopted checkouts (manual clones) and local paths are user-owned
+            // directories; only self-acquired checkouts are deleted.
+            const userOwned = source !== undefined && (source.local === true || source.adopted === true);
+            if (!userOwned)
                 await gitRemove(sourceCheckoutDir(this.options.userRoot, sourceId));
-            this.notifyChanged();
+            await this.notifyChanged();
         });
     }
     /** Refresh one source checkout, or every source when sourceId is omitted. */
@@ -372,18 +705,26 @@ export class Catalog {
         return this.enqueue(async () => {
             const targets = sourceId === undefined ? this.state.sources : this.state.sources.filter(source => source.id === sourceId);
             for (const source of targets) {
-                if (source.local === true) {
+                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);
-                try {
-                    await gitHead(checkout);
+                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;
                 }
-                catch {
-                    await this.ensureClone(source);
+                // 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));
                     }
@@ -392,7 +733,44 @@ export class Catalog {
                     }
                     continue;
                 }
-                await gitPull(checkout);
+                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));
                 }
@@ -400,7 +778,7 @@ export class Catalog {
                     // A failed HEAD read means the next overview re-probes.
                 }
             }
-            this.notifyChanged();
+            await this.notifyChanged();
         });
     }
     /** Install a suite from a source and enable it. The client confirms the
@@ -412,16 +790,20 @@ export class Catalog {
             if (source === undefined)
                 throw new Error(`unknown source "${sourceId}"`);
             const checkout = this.sourceCheckoutPath(source);
+            let freshLock;
             if (!(await isDirectory(checkout)))
-                await this.ensureClone(source);
-            const suites = await discoverSuitesInSource(checkout, sourceId, 'user');
+                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`);
-            await this.setInstalled(sourceId, suiteId, { enabled: true, installedAt: new Date().toISOString(), lockCommit: await tryHead(checkout) });
-            this.notifyChanged();
+            // 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);
         });
     }
     /** Uninstall a suite while retaining the source checkout. */
@@ -433,7 +815,7 @@ export class Catalog {
             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);
-            this.notifyChanged();
+            await this.notifyChanged(true);
         });
     }
     /** Enable or disable an installed suite. */
@@ -444,7 +826,7 @@ export class Catalog {
             if (entry === undefined)
                 throw new Error(`suite "${suiteId}" is not installed`);
             await this.setInstalled(sourceId, suiteId, { ...entry, enabled });
-            this.notifyChanged();
+            await this.notifyChanged(true);
         });
     }
     /** Enable or disable one runtime surface of an installed suite. */
@@ -458,7 +840,7 @@ export class Catalog {
                 throw new Error(`surface "${surface}" is not toggleable`);
             const surfaces = { ...(entry.surfaces ?? {}), [surface]: enabled };
             await this.setInstalled(sourceId, suiteId, { ...entry, surfaces });
-            this.notifyChanged();
+            await this.notifyChanged(true);
         });
     }
     /** Append config-seeded sources missing from user state and persist them. */
@@ -469,28 +851,88 @@ export class Catalog {
             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.scanCacheDirty = true;
         this.invalidateSnapshot(true);
     }
     async setInstalled(sourceId, suiteId, entry) {
         this.state = { ...this.state, installed: { ...this.state.installed, [installKey(sourceId, suiteId)]: entry } };
         await saveState(this.statePath, this.state);
     }
-    async ensureClone(source) {
-        if (source.local === true) {
+    /**
+     * 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.
+     */
+    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;
+            return undefined;
         }
         const checkout = sourceCheckoutDir(this.options.userRoot, source.id);
         await mkdir(sourcesDir(this.options.userRoot), { recursive: true });
-        await gitClone(source.url, source.branch, checkout);
+        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;
+        }
     }
     /** The filesystem location of one source. */
     sourceCheckoutPath(source) {
         return source.local === true ? expandHome(source.url) : sourceCheckoutDir(this.options.userRoot, source.id);
     }
-    async buildSnapshot(state, dimension, dimensionRoot) {
-        const discovered = await discoverSourceList(state.sources, dimension, dimensionRoot);
+    async buildSnapshot(state, dimension, dimensionRoot, skipScanCache = false) {
+        const fingerprint = JSON.stringify([dimension, dimensionRoot, state.sources]);
+        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 && !this.scanCacheDirty && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
+        let discovered;
+        let scanNotes;
+        if (cacheFresh && cached !== undefined) {
+            discovered = cached.discovered;
+            scanNotes = cached.scanNotes;
+        }
+        else {
+            const result = await discoverSourceListWithNotes(state.sources, dimension, dimensionRoot);
+            discovered = result.suites;
+            scanNotes = result.scanNotes;
+            // The fresh scan satisfies the invalidation: content mutations mark the
+            // cache dirty, and the next scan (this one) makes it clean again.
+            this.scanCacheDirty = false;
+            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
@@ -508,19 +950,29 @@ export class Catalog {
             revision: this.revision,
             sources: [...state.sources],
             suites,
-            enabledSuites: suites.filter(suite => suite.enabled)
+            enabledSuites: suites.filter(suite => suite.enabled),
+            ...(Object.keys(scanNotes).length > 0 ? { scanNotes } : {})
         };
     }
     invalidateSnapshot(increment) {
         if (increment)
             this.revision++;
         this.userSnapshot = undefined;
+        this.userSnapshotExpiresAt = 0;
         this.userSnapshotPromise = undefined;
         this.projectSnapshots.clear();
     }
-    notifyChanged() {
+    /**
+     * 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.
+     */
+    async notifyChanged(keepScanCache = false) {
+        if (!keepScanCache)
+            this.scanCacheDirty = true;
         this.invalidateSnapshot(true);
-        this.options.onChanged();
+        await this.options.onChanged();
         for (const listener of this.listeners)
             listener();
     }
@@ -542,3 +994,17 @@ async function tryHead(dir) {
         return undefined;
     }
 }
+/**
+ * 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}`}`;
+}