dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/packages/market-bundle/src/session-extension.js

@@ -0,0 +1,337 @@
+/** Session-owned selection, cached project readers, tool gates and scoped registration. */
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { pluginPathEnvironment, pluginRootOf, suiteDataDir } from '../../market-catalog/src/index.js';
+import { loadDisabledLspServers } from '../../market-lsp/src/index.js';
+import { HOOK_RUN_NO_COMMAND, HOOK_RUN_SHELL_UNAVAILABLE, HOOK_RUN_UNKNOWN_DECLARATION, ExtensionRuntime, ScopedExtensionContributors, attachExtensionToolGates, extensionWorkspace, hookRunFailure, hookRunShellOf, projectExtensionSuites, readExtensionSuiteDeclarations, runHookDryRun, shellSeamOf, projectAgentRoles } from '../../market-runtime/src/index.js';
+import { createProjectExtensionResources } from './application/extension-project.js';
+import { readExtensionInventory } from './application/extension-inventory.js';
+import { mountExtensionPresetRoutes } from './routes-extension-presets.js';
+import { createMcpMount } from './runtime-adapters.js';
+/** One suite per owner: a second copy would publish the same hook id twice. */
+function dedupeSuites(suites) {
+    const byOwner = new Map();
+    for (const suite of suites)
+        byOwner.set(suite.sourceId + '/' + suite.id, suite);
+    return [...byOwner.values()];
+}
+/**
+ * The settings Hooks page's read: one row per declared command hook.
+ *
+ * `enabledUserSuites()` already carries the Agent layout root's synthetic hook
+ * suite whenever it declares events, so this read lists that result as it
+ * stands: the suite enters once and each declaration publishes one id.
+ */
+async function readHookRows(catalog, suites) {
+    const rows = await readExtensionInventory({
+        catalog: { overview: () => catalog.overview(), mcpStatus: async () => catalog.mcpStatus(), lspStatus: async () => catalog.lspStatus() },
+        panels: { skills: { list: async () => [] }, commands: { list: async () => [] }, agents: { list: async () => [] } }
+    }, { projectSuites: suites });
+    return rows.filter(row => row.face === 'hooks');
+}
+export async function readHooksOverview(catalog) {
+    return { rows: await readHookRows(catalog, await catalog.enabledUserSuites()) };
+}
+/**
+ * Resolve one dry run's declaration from the same rows the Hooks overview
+ * publishes.
+ *
+ * The caller passes the suites to search, so a session's project hooks join
+ * user and installed rows without changing how identity is built. The command
+ * comes from the scanned declaration; the request carries identity only.
+ * @param catalog - the catalog status reads the overview uses.
+ * @param suites - the suites whose hook rows the lookup may match.
+ * @param input - the declaration address from the client.
+ * @returns the resolved command with its suite, or a stable error code.
+ */
+export async function resolveHookDeclaration(catalog, suites, input) {
+    const row = (await readHookRows(catalog, suites)).find(candidate => {
+        const detail = candidate.detail;
+        return detail.kind === 'hook' && detail.sourceId === input.sourceId && detail.suiteId === input.suiteId && detail.event === input.event && detail.hookIndex === input.hookIndex;
+    });
+    if (row === undefined)
+        return { error: HOOK_RUN_UNKNOWN_DECLARATION };
+    const detail = row.detail;
+    if (detail.kind !== 'hook' || detail.command === undefined || detail.hookIndex === undefined)
+        return { error: HOOK_RUN_NO_COMMAND };
+    const suite = suites.find(candidate => candidate.sourceId === input.sourceId && candidate.id === input.suiteId);
+    if (suite === undefined)
+        return { error: HOOK_RUN_UNKNOWN_DECLARATION };
+    return { command: detail.command, ...(detail.timeoutSec === undefined ? {} : { timeoutSec: detail.timeoutSec }), suite };
+}
+/**
+ * Create the stable readers before catalog initialization. Mount only after its sources are loaded.
+ * Call mount once. Host injection owns start and disposal; construction registers nothing.
+ */
+export function createSessionExtensions({ ctx, dataRoot, runtime, hostLocale }) {
+    let extensionPresets;
+    let scopedContributors;
+    let selectedRoleSuites;
+    let suiteSession;
+    let listRoles = async () => ({
+        entries: [],
+        complete: false
+    });
+    const mount = ({ catalog, panels, resources, readUserDeclarations }) => {
+        ctx.inject(['agents', 'sessions', 'sessionQuery', 'tools'], hostCtx => {
+            const eligible = (agent) => {
+                const cwd = agent.session.header.cwd;
+                return typeof cwd === 'string' && isAbsolute(cwd);
+            };
+            const gates = new Map();
+            const attachGate = (agent) => {
+                // An ineligible agent is never gated: the service does not own an agent
+                // whose workspace it cannot even read.
+                if (!eligible(agent))
+                    return undefined;
+                const mounted = gates.get(agent);
+                if (mounted)
+                    return mounted;
+                const gate = attachExtensionToolGates(agent, {
+                    mcpTools: () => [...runtime.mcpToolOwnership(), ...(scopedContributors?.toolOwnership(agent) ?? [])],
+                    lspProviders: () => runtime.lsp.providerOwnership(),
+                    ownsLspTool: () => runtime.lsp.ownsTool()
+                }, {
+                    ready: candidate => extensionRuntime.ready(candidate),
+                    allows: (candidate, resourceId, suiteId) => extensionRuntime.allows(candidate, resourceId, suiteId)
+                });
+                gates.set(agent, gate);
+                return gate;
+            };
+            const projectReaders = new Map();
+            const getProjectReader = (agent) => {
+                const existing = projectReaders.get(agent);
+                if (existing !== undefined)
+                    return existing;
+                const created = createProjectExtensionResources(catalog, panels, extensionWorkspace(agent));
+                projectReaders.set(agent, created);
+                return created;
+            };
+            const pendingSelections = new Map();
+            const readCandidates = async (agent) => {
+                const [user, project] = await Promise.all([readUserDeclarations(), catalog.readProjectCatalog(extensionWorkspace(agent))]);
+                return [...user, ...(await readExtensionSuiteDeclarations(project.enabledSuites))];
+            };
+            const selectedSuites = async (agent, selection) => {
+                const chosen = selection ?? pendingSelections.get(agent) ?? extensionRuntime.state.read(agent)?.selection;
+                if (!chosen)
+                    return [];
+                const enabledIds = [...chosen.enabledIds];
+                if (enabledIds.some(id => id.startsWith('mcp:plugin:@user-mcp/user-mcp/')))
+                    enabledIds.push('market:@user-mcp/user-mcp');
+                return projectExtensionSuites(await readCandidates(agent), { ...chosen, enabledIds }).map(row => row.suite);
+            };
+            const extensionRuntime = new ExtensionRuntime(hostCtx, {
+                dataRoot,
+                // Only an agent with a real absolute workspace is governed. Every other
+                // agent keeps the host's own lifecycle: no selection, no gate, no delay.
+                eligible,
+                // One reader per agent: it owns panel stores whose row caches must survive
+                // across reads, so every caller shares the same instance.
+                inventory: async (agent) => {
+                    const project = getProjectReader(agent);
+                    const [projectSuites, candidates, backend, lspDisabledIds] = await Promise.all([
+                        project.suites(),
+                        readCandidates(agent),
+                        catalog.mcpBackend(),
+                        loadDisabledLspServers(dataRoot)
+                    ]);
+                    const listedSuites = [...projectSuites, ...candidates.map(row => row.suite).filter(suite => suite.sourceId === '@user-hooks')];
+                    // Hook rows search one more list than the suite rows: an installed
+                    // user-dimension suite publishes no hook row of its own, so the
+                    // manager lists its declarations beside the project and @user-hooks
+                    // ones. The list stays separate from projectSuites, so project owner
+                    // addressing is unaffected.
+                    const hookSuites = dedupeSuites([...projectSuites, ...candidates.map(row => row.suite).filter(suite => suite.dimension === 'user')]);
+                    const mcpOverrides = await catalog.allMcpOverrides(candidates.map(row => row.suite));
+                    return readExtensionInventory({
+                        catalog: {
+                            overview: () => catalog.overview(),
+                            mcpStatus: async () => {
+                                const [global, local] = await Promise.all([catalog.mcpStatus(), project.mcpStatus()]);
+                                return { ...global, entries: [...global.entries, ...local.entries] };
+                            },
+                            lspStatus: async () => {
+                                const [global, local] = await Promise.all([catalog.lspStatus(), project.lspStatus()]);
+                                return { ...global, entries: [...global.entries, ...local.entries] };
+                            }
+                        },
+                        panels: Object.fromEntries(['skills', 'commands', 'agents'].map(kind => [
+                            kind,
+                            { list: async () => [...(await resources[kind].list(true)), ...(await project.panels[kind].list(true))] }
+                        ]))
+                    }, { projectSuites: listedSuites, hookSuites, candidates, mcpOverrides, lspDisabledIds, sessionId: agent.id, mcpSessionControl: backend === 'builtin' });
+                },
+                // The settings Hooks tab: hook declarations belong to the user Agent
+                // layout root. Installed suites' declared hooks join them: the page
+                // shows both sources, provenance on every row. The same
+                // readExtensionInventory fan-out produces the rows the manager's Hooks
+                // tab renders, so both surfaces agree on identity and support verdicts.
+                hooksOverview: () => readHooksOverview(catalog),
+                // The dry run resolves the declaration from the catalog, then runs it in the
+                // home directory. A named session only widens the lookup to that workspace's
+                // project hooks; it never supplies the run directory.
+                hookRun: async (input) => {
+                    const suites = [...(await catalog.enabledUserSuites())];
+                    if (input.sessionId !== undefined) {
+                        const agent = hostCtx.agents.get(SessionId(input.sessionId));
+                        const cwd = agent?.session.header.cwd;
+                        if (typeof cwd === 'string' && isAbsolute(cwd))
+                            suites.push(...(await catalog.readProjectCatalog(cwd)).suites);
+                    }
+                    const resolved = await resolveHookDeclaration(catalog, suites, input);
+                    if ('error' in resolved)
+                        return hookRunFailure(resolved.error);
+                    const shell = hookRunShellOf(shellSeamOf(hostCtx));
+                    if (shell === undefined)
+                        return hookRunFailure(HOOK_RUN_SHELL_UNAVAILABLE);
+                    const root = pluginRootOf(resolved.suite);
+                    const data = root === undefined ? undefined : suiteDataDir(dataRoot, resolved.suite.sourceId, resolved.suite.id);
+                    const env = pluginPathEnvironment({
+                        ...(root === undefined ? {} : { root }),
+                        ...(data === undefined ? {} : { data }),
+                        projectDir: homedir()
+                    });
+                    return runHookDryRun(shell, resolved.command, {
+                        event: input.event,
+                        ...(resolved.timeoutSec === undefined ? {} : { timeoutSec: resolved.timeoutSec }),
+                        ...(Object.keys(env).length === 0 ? {} : { env })
+                    });
+                },
+                // A session change touches that session only: its own contributions and its
+                // own gate. The global pipeline belongs to catalog changes, which the change
+                // hook drives for every agent.
+                applySelection: async (agent, selection) => {
+                    pendingSelections.set(agent, selection);
+                    let receipt;
+                    try {
+                        const [candidates, globalSuites, suites, backend] = await Promise.all([
+                            readUserDeclarations(),
+                            catalog.enabledUserSuites(),
+                            selectedSuites(agent, selection),
+                            catalog.mcpBackend()
+                        ]);
+                        runtime.setCatalogAuthority(candidates, globalSuites);
+                        const shared = suites
+                            .filter(suite => suite.dimension === 'user')
+                            .map(suite => (backend === 'builtin' ? suite : { ...suite, mcp: undefined, activeSurfaces: { ...suite.activeSurfaces, mcp: false } }));
+                        receipt = await runtime.stageSessionDemand(agent, shared, selection.enabledIds.filter(id => id.startsWith('lsp:direct/')).map(id => id.slice(4)));
+                        attachGate(agent)?.refresh();
+                        await contributors.reconcile(agent, selection);
+                        return receipt;
+                    }
+                    catch (error) {
+                        try {
+                            await receipt?.rollback();
+                        }
+                        catch (cleanupError) {
+                            ctx.logger.warn(String(cleanupError));
+                        }
+                        throw error;
+                    }
+                    finally {
+                        pendingSelections.delete(agent);
+                    }
+                },
+                committed: agent => {
+                    contributors.committed(agent);
+                    attachGate(agent)?.refresh();
+                },
+                ready: async (agent, source) => {
+                    if (!eligible(agent))
+                        return;
+                    attachGate(agent)?.refresh();
+                    if (!extensionRuntime.ready(agent))
+                        return;
+                    await contributors.ready(agent, source);
+                }
+            });
+            const contributors = new ScopedExtensionContributors({
+                mcpMounts: createMcpMount,
+                dataRoot,
+                catalog,
+                // Resolved lazily: the seam reader below is declared later in this scope,
+                // and the agents fiber can activate before that declaration runs.
+                shell: () => shellSeamOf(ctx),
+                allows: (agent, resourceId, suiteId) => extensionRuntime.allows(agent, resourceId, suiteId),
+                registrationAllows: (agent, resourceId) => extensionRuntime.registrationAllows(agent, resourceId),
+                panels,
+                suites: agent => selectedSuites(agent),
+                hostContext: hostCtx,
+                t: key => hostLocale.t(key)
+            });
+            scopedContributors = contributors;
+            selectedRoleSuites = agent => selectedSuites(agent);
+            hostCtx.on('agent/disposed', ({ agent }) => {
+                gates.get(agent)?.dispose();
+                gates.delete(agent);
+                projectReaders.delete(agent);
+                pendingSelections.delete(agent);
+                void runtime.releaseSessionDemand(agent).catch(error => ctx.logger.warn(String(error)));
+                void contributors.dispose(agent).catch(error => ctx.logger.warn('extension disposal: ' + String(error)));
+            });
+            // The route resolver shares the very same per-agent reader as the inventory,
+            // so a detail read and an inventory read never build two panel caches.
+            suiteSession = {
+                agent: sessionId => hostCtx.agents.get(SessionId(sessionId)),
+                project: getProjectReader
+            };
+            hostCtx.effect(() => () => {
+                projectReaders.clear();
+            }, 'dsh-agent-plugins-market: project readers');
+            hostCtx.inject(['webServer', 'loader'], webCtx => {
+                webCtx.effect(() => mountExtensionPresetRoutes(webCtx, extensionRuntime), 'dsh-agent-plugins-market: extension preset routes');
+            });
+            hostCtx.effect(() => {
+                extensionPresets = extensionRuntime;
+                for (const agent of hostCtx.agents.list())
+                    attachGate(agent);
+                void extensionRuntime.start().catch(error => {
+                    ctx.logger?.warn?.('[dsh-agent-plugins-market] extension presets: ' + (error instanceof Error ? error.message : String(error)));
+                });
+                return async () => {
+                    if (extensionPresets === extensionRuntime)
+                        extensionPresets = undefined;
+                    if (scopedContributors === contributors)
+                        scopedContributors = undefined;
+                    await extensionRuntime.dispose();
+                    await contributors.disposeAll();
+                    for (const gate of gates.values())
+                        gate.dispose();
+                    gates.clear();
+                };
+            }, 'dsh-agent-plugins-market: extension presets');
+        });
+        listRoles = async (parent) => {
+            const agent = parent;
+            // "Not ready" is not "no roles": the extension runtime may still be
+            // initializing or recovering, so an empty answer must not replace the
+            // published catalog. A read failure propagates for the same reason, and
+            // the catalog publisher turns both into "no new information".
+            if (!agent || !extensionPresets?.ready(agent))
+                return { entries: [], complete: false };
+            const user = (await resources.agents.list(true))
+                .filter(entry => entry.origin === 'user' && extensionPresets?.allows(agent, 'agents:' + (entry.id ?? entry.name)))
+                .map(entry => ({ ...entry, title: entry.name, name: entry.id ?? entry.name, selectionEnabled: true }));
+            const project = await projectAgentRoles(catalog, parent, {
+                suites: () => selectedRoleSuites?.(agent) ?? Promise.resolve([]),
+                selected: role => extensionPresets?.allows(agent, 'agents:' + role.name) === true
+            });
+            return { entries: [...user, ...project], complete: true };
+        };
+    };
+    return {
+        mount,
+        /** Preserve revocation before default-provider invalidation and contributor refresh. */
+        invalidate(invalidateDefaultSkills) {
+            extensionPresets?.invalidate();
+            invalidateDefaultSkills();
+            scopedContributors?.invalidateAll();
+        },
+        refresh: () => extensionPresets?.refreshAll(),
+        commandRegistrations: () => scopedContributors?.registrations() ?? [],
+        roles: (parent) => listRoles(parent),
+        session: () => suiteSession
+    };
+}

package/lib/{application → packages/market-catalog/src/application}/catalog-context.js

@@ -8,11 +8,11 @@
  * notification path — have a single owner.
  */
 import { join } from 'node:path';
-import { MARKET_SETTINGS_DEFAULTS } from '../contracts/settings.js';
-import { STATE_FILE_NAME } from '../catalog/paths.js';
+import { MARKET_SETTINGS_DEFAULTS } from '../../../market-contracts/src/contracts/settings.js';
+import { STATE_FILE_NAME } from '../scanning/paths.js';
 import { settlesWithin } from './deadline.js';
 import { EMPTY_STATE, loadState, saveState } from './state/state-store.js';
-import { effectiveSurfaces } from '../model/types.js';
+import { effectiveSurfaces } from '../../../market-contracts/src/model/types.js';
 import { SCAN_CACHE_TTL_MS, SnapshotCache } from './snapshot-cache.js';
 /** Key of one install entry in the persisted `installed` record. */
 export function installKey(sourceId, suiteId) {
@@ -46,6 +46,8 @@ export class CatalogContext {
     git;
     /** Discovery scans and dimension snapshots derived from {@link state}. */
     snapshots;
+    /** The clock every TTL and window in this context is measured against. */
+    now;
     onChanged;
     constructor(options) {
         this.statePath = join(options.userRoot, STATE_FILE_NAME);
@@ -54,10 +56,11 @@ export class CatalogContext {
         this.agentsRoot = options.agentsRoot;
         this.git = options.git ?? {};
         this.onChanged = options.onChanged;
+        this.now = options.now ?? Date.now;
         this.snapshots = new SnapshotCache(this, {
             user: options.userSnapshotTtlMs ?? SCAN_CACHE_TTL_MS,
             project: options.projectSnapshotTtlMs ?? 5_000
-        });
+        }, this.now);
     }
     get state() {
         return this.currentState;

package/lib/{application → packages/market-catalog/src/application}/install-store.js

@@ -6,9 +6,9 @@
  * The checkout a suite is read from stays source-owned: installing writes an
  * entry, never a file inside the source.
  */
-import { isDirectory } from '../catalog/fs-probes.js';
-import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
-import { SUITE_SURFACE_KEYS } from '../model/types.js';
+import { isDirectory } from '../scanning/fs-probes.js';
+import { discoverSuitesInSource } from '../scanning/suite-scanner.js';
+import { SUITE_SURFACE_KEYS } from '../../../market-contracts/src/model/types.js';
 import { installKey } from './catalog-context.js';
 import { tryHead } from './source-store.js';
 export class InstallStore {

package/lib/{application → packages/market-catalog/src/application}/snapshot-cache.js

@@ -10,25 +10,53 @@
  * for in-place working-tree edits of local sources.
  */
 import { join, resolve } from 'node:path';
-import { resolveProjectRoot, STATE_FILE_NAME } from '../catalog/paths.js';
-import { discoverSourceListWithNotes } from '../catalog/source-catalog.js';
+import { resolveProjectRoot, STATE_FILE_NAME } from '../scanning/paths.js';
+import { discoverSourceListWithNotes } from '../scanning/source-catalog.js';
 import { loadState } from './state/state-store.js';
 export const SCAN_CACHE_TTL_MS = 30_000;
 const SCAN_CACHE_MAX_ENTRIES = 8;
+/**
+ * When the background refresh of the user snapshot runs, as a fraction of its
+ * TTL. Refreshing before the snapshot expires is what keeps the TTL a
+ * *staleness* bound rather than a cost every read pays: a read arriving after
+ * the refresh lands is served from the cache, where it used to trigger the
+ * whole discovery scan itself.
+ */
+const USER_REFRESH_LEAD_RATIO = 0.8;
+/**
+ * How long the background refresh keeps running after the last user-dimension
+ * read, in TTLs. The TTL exists to bound how long an out-of-band working-tree
+ * edit stays invisible, so the refresh has to stay frequent while the catalog
+ * is in use; this multiple is what stops it from scanning a 2,500-suite
+ * catalog forever once nobody is reading. A read after the window pays exactly
+ * one scan — the cost every read paid before the window existed — and warms
+ * the cache up again.
+ */
+const USER_KEEP_WARM_TTL_MULTIPLE = 10;
 export class SnapshotCache {
     host;
     ttls;
+    now;
     scanCache = new Map();
     scanPromises = new Map();
     userSnapshot;
     userSnapshotExpiresAt = 0;
     userSnapshotPromise;
+    /** The armed keep-warm refresh, or undefined when none is scheduled. */
+    userRefreshTimer;
+    /** Set by {@link dispose}: the keep-warm chain is over and never re-arms. */
+    disposed = false;
+    /** When the user dimension was last read; the keep-warm window closes from here. */
+    lastUserReadAt = 0;
     /** Project-dimension snapshots keyed by project root, with TTL freshness. */
     projectSnapshots = new Map();
     projectSnapshotPromises = new Map();
-    constructor(host, ttls) {
+    constructor(host, ttls, 
+    /** Clock seam; tests drive TTL expiry, the scan cache, and the idle window through it. */
+    now = Date.now) {
         this.host = host;
         this.ttls = ttls;
+        this.now = now;
     }
     /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
     async readUserCatalog() {
@@ -36,17 +64,31 @@ export class SnapshotCache {
         // mirroring the project dimension's caching-disabled semantics.
         if (this.ttls.user <= 0)
             return this.build(this.host.state, 'user', this.host.userRoot);
-        if (this.userSnapshot !== undefined && Date.now() < this.userSnapshotExpiresAt)
-            return this.userSnapshot;
+        this.lastUserReadAt = this.now();
+        const snapshot = await this.loadUserSnapshot(false);
+        this.armUserRefresh();
+        return snapshot;
+    }
+    /**
+     * Build the user snapshot, or join the build already in flight.
+     *
+     * `forceRescan` is the keep-warm refresh's entry point: it re-reads the
+     * working tree even while the discovery cache would still answer, because
+     * replaying that cache would let one scan outlive the freshness bound the
+     * TTL states.
+     */
+    loadUserSnapshot(forceRescan) {
+        if (!forceRescan && this.userSnapshot !== undefined && this.now() < this.userSnapshotExpiresAt)
+            return Promise.resolve(this.userSnapshot);
         if (this.userSnapshotPromise !== undefined)
             return this.userSnapshotPromise;
         const revision = this.host.revision;
         const generation = this.host.scanGeneration;
-        const promise = this.build(this.host.state, 'user', this.host.userRoot)
+        const promise = this.build(this.host.state, 'user', this.host.userRoot, forceRescan)
             .then(snapshot => {
             if (revision === this.host.revision && generation === this.host.scanGeneration) {
                 this.userSnapshot = snapshot;
-                this.userSnapshotExpiresAt = Date.now() + this.ttls.user;
+                this.userSnapshotExpiresAt = this.now() + this.ttls.user;
             }
             return snapshot;
         })
@@ -57,6 +99,36 @@ export class SnapshotCache {
         this.userSnapshotPromise = promise;
         return promise;
     }
+    /**
+     * Keep the user snapshot warm while the catalog is in use.
+     *
+     * Without this, the first read after the TTL lapses pays the full discovery
+     * scan — the normal case for a panel opened minutes apart. The refresh runs
+     * {@link USER_REFRESH_LEAD_RATIO} of the TTL before the snapshot expires, so
+     * a read never waits for it, and it is armed by reads: the chain ends
+     * {@link USER_KEEP_WARM_TTL_MULTIPLE} TTLs after the last one.
+     */
+    armUserRefresh() {
+        if (this.disposed || this.ttls.user <= 0 || this.userRefreshTimer !== undefined)
+            return;
+        const delay = Math.max(1, Math.round(this.ttls.user * USER_REFRESH_LEAD_RATIO));
+        const timer = setTimeout(() => {
+            if (this.userRefreshTimer === timer)
+                this.userRefreshTimer = undefined;
+            this.refreshUserSnapshot();
+        }, delay);
+        // A waiting refresh must not hold the host process open.
+        timer.unref?.();
+        this.userRefreshTimer = timer;
+    }
+    /** Run one background refresh unless the catalog has been idle past its window. */
+    refreshUserSnapshot() {
+        if (this.disposed || this.now() - this.lastUserReadAt > this.ttls.user * USER_KEEP_WARM_TTL_MULTIPLE)
+            return;
+        void this.loadUserSnapshot(true)
+            .catch(() => undefined)
+            .finally(() => this.armUserRefresh());
+    }
     /** Read one coherent project-dimension snapshot for a workspace cwd. */
     async readProjectCatalog(cwd) {
         const projectRoot = await resolveProjectRoot(cwd);
@@ -70,7 +142,7 @@ export class SnapshotCache {
         if (this.ttls.project <= 0)
             return this.buildProjectSnapshot(projectRoot);
         const cached = this.projectSnapshots.get(projectRoot);
-        if (cached !== undefined && cached.expiresAt > Date.now())
+        if (cached !== undefined && cached.expiresAt > this.now())
             return cached.snapshot;
         const inFlight = this.projectSnapshotPromises.get(projectRoot);
         if (inFlight !== undefined)
@@ -80,7 +152,7 @@ export class SnapshotCache {
         const promise = this.buildProjectSnapshot(projectRoot)
             .then(snapshot => {
             if (revision === this.host.revision && generation === this.host.scanGeneration) {
-                this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: Date.now() + this.ttls.project });
+                this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: this.now() + this.ttls.project });
             }
             return snapshot;
         })
@@ -98,7 +170,7 @@ export class SnapshotCache {
         // 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.ttls.user, SCAN_CACHE_TTL_MS) : SCAN_CACHE_TTL_MS;
-        const cacheFresh = !skipScanCache && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
+        const cacheFresh = !skipScanCache && cached !== undefined && this.now() - cached.at < scanCacheTtl;
         let discovered;
         let scanNotes;
         if (cacheFresh && cached !== undefined) {
@@ -126,7 +198,7 @@ export class SnapshotCache {
             if (generation === this.host.scanGeneration) {
                 if (this.scanCache.size >= SCAN_CACHE_MAX_ENTRIES)
                     this.scanCache.clear();
-                this.scanCache.set(fingerprint, { at: Date.now(), discovered, scanNotes });
+                this.scanCache.set(fingerprint, { at: this.now(), discovered, scanNotes });
             }
         }
         const suites = this.host.project(discovered, state, dimension);
@@ -146,6 +218,23 @@ export class SnapshotCache {
         this.projectSnapshots.clear();
         this.projectSnapshotPromises.clear();
     }
+    /**
+     * End the keep-warm refresh for good.
+     *
+     * Clearing the armed timer is not enough on its own: a refresh already in
+     * flight re-arms through its own `.finally()`, so a teardown landing while
+     * one runs would leave the chain scanning the whole catalog every 0.8 TTL
+     * with nobody reading it. Disposal is therefore terminal — the chain end is
+     * checked before it arms and before it runs — and reads after it still answer
+     * from the cache or rebuild one, they just no longer keep it warm.
+     */
+    dispose() {
+        this.disposed = true;
+        if (this.userRefreshTimer !== undefined) {
+            clearTimeout(this.userRefreshTimer);
+            this.userRefreshTimer = undefined;
+        }
+    }
     /** Drop cached discovery and its in-flight dedupe slots. */
     invalidateScans() {
         this.scanCache.clear();

package/lib/{application → packages/market-catalog/src/application}/source-store.js

@@ -9,14 +9,14 @@
  */
 import { mkdir, readdir, rename } from 'node:fs/promises';
 import { join } from 'node:path';
-import { archiveInstall } from '../catalog/archive.js';
-import { gitClone, gitCurrentBranch, gitHead, gitRemoteUrl, gitRemove, gitSetRemoteUrl, gitSync } from '../catalog/git.js';
-import { repoName } from '../catalog/manifests.js';
-import { deriveSourceIdCandidates, expandHome, sanitizeId, sourceCheckoutDir, sourcesDir } from '../catalog/paths.js';
-import { isDirectory, pathExists } from '../catalog/fs-probes.js';
-import { canonicalGitUrl } from '../catalog/scan-resolvers.js';
+import { archiveInstall } from '../scanning/archive.js';
+import { gitClone, gitCurrentBranch, gitHead, gitRemoteUrl, gitRemove, gitSetRemoteUrl, gitSync } from '../scanning/git.js';
+import { repoName } from '../scanning/manifests.js';
+import { deriveSourceIdCandidates, expandHome, sanitizeId, sourceCheckoutDir, sourcesDir } from '../scanning/paths.js';
+import { isDirectory, pathExists } from '../scanning/fs-probes.js';
+import { canonicalGitUrl } from '../scanning/scan-resolvers.js';
 import { githubCloneUrl, resolveRegion } from './regions.js';
-import { resolveSourceKind } from '../model/types.js';
+import { resolveSourceKind } from '../../../market-contracts/src/model/types.js';
 export class SourceStore {
     context;
     ports;
@@ -224,6 +224,10 @@ export class SourceStore {
     async refresh(sourceId) {
         return this.context.enqueue(async () => {
             const targets = sourceId === undefined ? this.context.state.sources : this.context.state.sources.filter(source => source.id === sourceId);
+            // One route for the whole pass: resolving it reads the host locale
+            // preference, so asking per source made a refresh of N sources pay N
+            // whole-profile projections.
+            const route = await this.downloadRoute();
             for (const source of targets) {
                 const kind = resolveSourceKind(source);
                 if (kind === 'local') {
@@ -279,8 +283,7 @@ export class SourceStore {
                 // 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.ports.downloadRegion(), this.ports.localePreference());
-                        const routed = githubCloneUrl(region, source.url);
+                        const routed = githubCloneUrl(route, source.url);
                         const origin = await gitRemoteUrl(checkout);
                         if (origin !== routed && (origin === source.url || origin === githubCloneUrl('china', source.url))) {
                             await gitSetRemoteUrl(checkout, routed);
@@ -301,6 +304,17 @@ export class SourceStore {
             await this.context.notifyChanged();
         });
     }
+    /**
+     * The download route one acquisition pass applies to its sources.
+     *
+     * Reading it resolves the host locale preference, which the host answers by
+     * projecting every active profile entry's live configuration. A pass over
+     * several sources reads it once and reuses the value, so a refresh's cost
+     * follows its work instead of its source count.
+     */
+    async downloadRoute() {
+        return resolveRegion(await this.ports.downloadRegion(), this.ports.localePreference());
+    }
     /** Progress snapshot for the progress route. */
     progress() {
         const state = this.currentSourceState;
@@ -400,8 +414,7 @@ export class SourceStore {
         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.ports.downloadRegion(), this.ports.localePreference());
-            await gitClone(githubCloneUrl(region, source.url), source.branch, checkout, this.context.git);
+            await gitClone(githubCloneUrl(await this.downloadRoute(), source.url), source.branch, checkout, this.context.git);
             return undefined;
         }
         catch (error) {

package/lib/{application → packages/market-catalog/src/application}/state/state-store.js

@@ -8,7 +8,7 @@
  * in `src/model/types.ts`; only the reading and writing live here.
  */
 import { readJsonFile, writeJsonDocument } from '../json-file.js';
-import { SUITE_SURFACE_KEYS } from '../../model/types.js';
+import { SUITE_SURFACE_KEYS } from '../../../../market-contracts/src/model/types.js';
 export const EMPTY_STATE = { version: 1, sources: [], installed: {} };
 /** Parse persisted state; unreadable or wrong-version files yield a contained empty state. */
 export async function loadState(statePath) {