Materialization Aware Refresh Escalation

SKILL: Materialization-Aware Refresh Escalation

Domain: extensions-mcp
Trigger: When background plugin installation reconcilers detect that declared marketplaces differ from what is materialized, use the diff to decide whether to auto-refresh plugins or escalate to a manual refresh prompt. Source Pattern: Distilled from reviewed extension lifecycle and source-reconciliation patterns.

Core Method

1. Before reconciling, read the declared marketplaces (getDeclaredMarketplaces()), the previously materialized config (loadKnownMarketplacesConfig()), and compute diffMarketplaces() so you know which names are missing or changed.
2. Build pendingNames from diff.missing plus diff.sourceChanged so the UI reports exactly which marketplaces are still being processed; return early when that array is empty so no work runs unless there is material change.
3. Call reconcileMarketplaces({ onProgress }), map the installing/installed/failed events to AppState, track metrics for installed/updated/failed/up-to-date counts, and log them via logEvent and diagnostics helpers.
4. After reconciliation, inspect the result:
   • When result.installed.length > 0, clear the marketplace cache, log the auto-refresh path, and await refreshActivePlugins(setAppState) inside a try/catch so MCP caches are rebuilt. On refresh failure, log the error, clear the plugin cache, and set plugins.needsRefresh via AppState only if it was previously false.
   • When there are no fresh installs but result.updated.length > 0, clear both marketplace and plugin caches and set the needsRefresh flag so the UI invites /reload-plugins while avoiding an automatic refresh.
   • When there are neither installs nor updates, skip cache invalidation and refresh so the reconciliation stays lightweight.

Key Rules

• Only auto-refresh when brand-new marketplaces were installed; updates-only reconciliations should not trigger the refresh path.
• Clear both marketplace and plugin caches before touching refreshActivePlugins or setting needsRefresh so stale artifacts cannot leak into the new plugin state.
• Always wrap refreshActivePlugins in a try/catch, log failures (logError, logForDebugging), and fall back to needsRefresh rather than silently suppressing the error.
• Guard the needsRefresh setter so it only flips once per failure path and never reassigns while the flag is already true.

Example Application

Installing a curated marketplace during background startup on a fresh homespace uses this path so the new tools become available without forcing the user to manually run /reload-plugins.

Anti-Patterns (What NOT to do)

• Do not refresh plugin state when result.installed.length === 0; the caches were already populated and redundant refreshes slow startup.
• Do not swallow refresh failures; the fallback needsRefresh flag exists so the UI can surface /reload-plugins once the auto-path fails.
• Do not clear caches only after calling refreshActivePlugins; stale cache entries must be removed before the refresh attempt or the refresh may still resolve to old code.