claudeup 4.7.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",

package/src/__tests__/gap-fill-versions.test.ts

@@ -0,0 +1,382 @@
+/**
+ * Tests for gapFillInstalledPluginVersions()
+ *
+ * This function ensures global installedPluginVersions is at least as high as
+ * the highest version found across project and local scopes. When a plugin is
+ * updated at project scope (e.g. by `claude plugin marketplace update` in a
+ * project directory), global may lag behind, causing Claude Code to resolve
+ * stale cache paths.
+ *
+ * Each test uses a real temp filesystem with mocked os.homedir() to exercise
+ * the actual read/write paths in claude-settings.ts.
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  afterAll,
+  mock,
+} from "bun:test";
+import fs from "fs-extra";
+import path from "node:path";
+
+// We need real os functions (tmpdir, etc.) but must mock homedir().
+// Since mock.module is hoisted and replaces the module for ALL consumers,
+// we grab the real os module via require before the mock takes effect.
+const realOs = await import("node:os");
+const realTmpdir = realOs.tmpdir();
+const realHomedir = realOs.homedir();
+
+// ---------------------------------------------------------------------------
+// Temp directory helpers
+// ---------------------------------------------------------------------------
+
+// Initialize tmpHome eagerly so module-level os.homedir() calls in
+// claude-settings.ts (for INSTALLED_PLUGINS_FILE, KNOWN_MARKETPLACES_FILE)
+// get a valid path during import. The mock closure reads this variable.
+const initTmpHome = fs.mkdtempSync(path.join(realTmpdir, "gfill-init-"));
+let tmpHome: string = initTmpHome;
+let tmpProject: string;
+
+/** Write a global settings file at <tmpHome>/.claude/settings.json */
+async function writeGlobalSettings(settings: Record<string, unknown>) {
+  const dir = path.join(tmpHome, ".claude");
+  await fs.ensureDir(dir);
+  await fs.writeJson(path.join(dir, "settings.json"), settings, { spaces: 2 });
+}
+
+/** Read back global settings after function execution */
+async function readGlobalSettingsFromDisk(): Promise<Record<string, unknown>> {
+  const p = path.join(tmpHome, ".claude", "settings.json");
+  if (await fs.pathExists(p)) {
+    return fs.readJson(p);
+  }
+  return {};
+}
+
+/** Write project settings at <tmpProject>/.claude/settings.json */
+async function writeProjectSettings(settings: Record<string, unknown>) {
+  const dir = path.join(tmpProject, ".claude");
+  await fs.ensureDir(dir);
+  await fs.writeJson(path.join(dir, "settings.json"), settings, { spaces: 2 });
+}
+
+/** Write local settings at <tmpProject>/.claude/settings.local.json */
+async function writeLocalSettings(settings: Record<string, unknown>) {
+  const dir = path.join(tmpProject, ".claude");
+  await fs.ensureDir(dir);
+  await fs.writeJson(path.join(dir, "settings.local.json"), settings, {
+    spaces: 2,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Mock os.homedir() so getGlobalClaudeDir() points to our temp dir.
+//
+// Bun hoists mock.module() calls, so this must come before the import of the
+// module under test.
+// ---------------------------------------------------------------------------
+
+mock.module("node:os", () => {
+  // Build a proxy that preserves all real os functions but overrides homedir
+  const mocked = { ...realOs, homedir: () => tmpHome };
+  return {
+    ...mocked,
+    default: mocked,
+  };
+});
+
+// Import function under test AFTER mock registration
+const { gapFillInstalledPluginVersions } = await import(
+  "../services/claude-settings.js"
+);
+
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+
+describe("gapFillInstalledPluginVersions", () => {
+  beforeEach(async () => {
+    // Create isolated temp dirs for each test
+    tmpHome = await fs.mkdtemp(path.join(realTmpdir, "gfill-home-"));
+    tmpProject = await fs.mkdtemp(path.join(realTmpdir, "gfill-proj-"));
+    // Ensure the global .claude dir exists
+    await fs.ensureDir(path.join(tmpHome, ".claude"));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpHome);
+    await fs.remove(tmpProject);
+  });
+
+  afterAll(async () => {
+    // Clean up the initial temp home created for module-level evaluation
+    await fs.remove(initTmpHome).catch(() => {});
+  });
+
+  // Scenario 1: "The kanban bug" — project has newer version, global is stale
+  it("bumps global when project has a newer version (the kanban bug)", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "kanban@magus": "1.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "1.3.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([
+      {
+        pluginId: "kanban@magus",
+        oldVersion: "1.0.0",
+        newVersion: "1.3.0",
+      },
+    ]);
+
+    // Verify the file was actually updated
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe(
+      "1.3.0",
+    );
+  });
+
+  // Scenario 2: Global is already current — no changes needed
+  it("returns empty array when global is already at the highest version", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "kanban@magus": "1.3.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "1.3.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([]);
+
+    // Verify global was NOT rewritten (check original content is intact)
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe(
+      "1.3.0",
+    );
+  });
+
+  // Scenario 3: Multiple plugins with mixed staleness
+  it("handles multiple plugins with mixed staleness correctly", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: {
+        "a@mp": "1.0.0",
+        "b@mp": "2.0.0",
+      },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: {
+        "a@mp": "2.0.0",
+        "b@mp": "2.0.0",
+        "c@mp": "1.0.0",
+      },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    // a@mp should be bumped, b@mp unchanged, c@mp added (missing from global)
+    const bumped = result.map((r) => r.pluginId).sort();
+    expect(bumped).toEqual(["a@mp", "c@mp"]);
+
+    const aEntry = result.find((r) => r.pluginId === "a@mp");
+    expect(aEntry).toEqual({
+      pluginId: "a@mp",
+      oldVersion: "1.0.0",
+      newVersion: "2.0.0",
+    });
+
+    const cEntry = result.find((r) => r.pluginId === "c@mp");
+    expect(cEntry).toEqual({
+      pluginId: "c@mp",
+      oldVersion: "(missing)",
+      newVersion: "1.0.0",
+    });
+
+    // Verify file state
+    const global = await readGlobalSettingsFromDisk();
+    const versions = (global as any).installedPluginVersions;
+    expect(versions["a@mp"]).toBe("2.0.0");
+    expect(versions["b@mp"]).toBe("2.0.0");
+    expect(versions["c@mp"]).toBe("1.0.0");
+  });
+
+  // Scenario 4: Local scope has the highest version
+  it("uses the highest version across all 3 scopes (local wins)", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "x@mp": "1.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "x@mp": "1.5.0" },
+    });
+    await writeLocalSettings({
+      installedPluginVersions: { "x@mp": "2.0.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([
+      {
+        pluginId: "x@mp",
+        oldVersion: "1.0.0",
+        newVersion: "2.0.0",
+      },
+    ]);
+
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["x@mp"]).toBe("2.0.0");
+  });
+
+  // Scenario 5: No project path — only global scope
+  it("returns empty array when called with no projectPath", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "a@mp": "1.0.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions();
+
+    expect(result).toEqual([]);
+  });
+
+  // Scenario 6: Idempotency — running twice is a no-op
+  it("is idempotent — second call returns empty array", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "a@mp": "1.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "a@mp": "2.0.0" },
+    });
+
+    // First call: should bump
+    const first = await gapFillInstalledPluginVersions(tmpProject);
+    expect(first).toHaveLength(1);
+    expect(first[0].newVersion).toBe("2.0.0");
+
+    // Second call: global is now at 2.0.0, so nothing to do
+    const second = await gapFillInstalledPluginVersions(tmpProject);
+    expect(second).toEqual([]);
+  });
+
+  // Scenario 7: Invalid semver versions are skipped
+  it("skips invalid semver versions in project scope", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "a@mp": "1.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "a@mp": "not-a-version" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([]);
+
+    // Global should remain unchanged
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["a@mp"]).toBe("1.0.0");
+  });
+
+  // Scenario 8: Project settings file doesn't exist (new project)
+  it("returns empty array when project settings file does not exist", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "a@mp": "1.0.0" },
+    });
+
+    // Use a path that doesn't have any .claude directory
+    const nonExistentProject = path.join(tmpProject, "no-such-project");
+
+    const result = await gapFillInstalledPluginVersions(nonExistentProject);
+
+    expect(result).toEqual([]);
+  });
+
+  // Scenario 9: Global version is higher than project — no downgrade
+  it("does not downgrade global when global is higher than project", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "kanban@magus": "2.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "1.0.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([]);
+
+    // Verify global was NOT downgraded
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe("2.0.0");
+  });
+
+  // Scenario 10: Preserves unrelated settings fields during write
+  it("preserves other global settings fields when bumping versions", async () => {
+    await writeGlobalSettings({
+      enabledPlugins: { "kanban@magus": true, "dev@magus": true },
+      env: { SOME_VAR: "value" },
+      installedPluginVersions: { "kanban@magus": "1.0.0" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "2.0.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toHaveLength(1);
+
+    // Verify other fields are preserved
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).enabledPlugins).toEqual({ "kanban@magus": true, "dev@magus": true });
+    expect((global as any).env).toEqual({ SOME_VAR: "value" });
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe("2.0.0");
+  });
+
+  // Scenario 11: Invalid semver in GLOBAL scope gets overwritten
+  it("overwrites corrupted global version when project has valid semver", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "kanban@magus": "not-a-version" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "1.3.0" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([
+      {
+        pluginId: "kanban@magus",
+        oldVersion: "not-a-version",
+        newVersion: "1.3.0",
+      },
+    ]);
+
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe(
+      "1.3.0",
+    );
+  });
+
+  // Scenario 12: Both global and project have invalid semver — no crash, no change
+  it("does nothing when all versions are invalid semver", async () => {
+    await writeGlobalSettings({
+      installedPluginVersions: { "kanban@magus": "broken" },
+    });
+    await writeProjectSettings({
+      installedPluginVersions: { "kanban@magus": "also-broken" },
+    });
+
+    const result = await gapFillInstalledPluginVersions(tmpProject);
+
+    expect(result).toEqual([]);
+
+    // Global unchanged
+    const global = await readGlobalSettingsFromDisk();
+    expect((global as any).installedPluginVersions["kanban@magus"]).toBe(
+      "broken",
+    );
+  });
+});

package/src/prerunner/index.js

@@ -4,10 +4,10 @@ import os from "node:os";
 import { UpdateCache } from "../services/update-cache.js";
 import { getAvailablePlugins, clearMarketplaceCache, } from "../services/plugin-manager.js";
 import { runClaude } from "../services/claude-runner.js";
-import { recoverMarketplaceSettings, migrateMarketplaceRename, cleanupExtraKnownMarketplaces, getGlobalEnabledPlugins, getEnabledPlugins, getLocalEnabledPlugins, readGlobalSettings, writeGlobalSettings, saveGlobalInstalledPluginVersion, } from "../services/claude-settings.js";
+import { recoverMarketplaceSettings, migrateMarketplaceRename, cleanupExtraKnownMarketplaces, getGlobalEnabledPlugins, getEnabledPlugins, getLocalEnabledPlugins, readGlobalSettings, writeGlobalSettings, saveGlobalInstalledPluginVersion, gapFillInstalledPluginVersions, } from "../services/claude-settings.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { defaultMarketplaces } from "../data/marketplaces.js";
-import { updatePlugin, addMarketplace, updateMarketplace, isClaudeAvailable, } from "../services/claude-cli.js";
+import { updatePlugin, addMarketplace, isClaudeAvailable, } from "../services/claude-cli.js";
 const MARKETPLACES_DIR = path.join(os.homedir(), ".claude", "plugins", "marketplaces");
 /**
  * Collect all unique marketplace names from enabled plugins across all settings scopes.
@@ -56,10 +56,16 @@ async function getReferencedMarketplaces(projectPath) {
  * Check which referenced marketplaces are missing locally and auto-add them.
  * Only adds marketplaces with known repos (from defaultMarketplaces).
  *
- * Uses `marketplace update` (not `marketplace add`) for recovery because
- * `add` short-circuits when the marketplace is already declared in settings
- * — even if the directory was deleted. `update` detects the missing dir and
- * re-clones automatically.
+ * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
+ * Claude Code's `marketplace update` calls cacheMarketplaceFromGit() which
+ * deletes the marketplace directory before re-cloning. If the clone fails
+ * (network timeout, auth error), the directory stays permanently deleted
+ * and ALL plugins from that marketplace break. See:
+ * ai-docs/plugin-marketplace-bug-investigation.md
+ *
+ * Claude Code's own background autoupdate handles marketplace refreshing
+ * after session start — claudeup should only recover genuinely missing
+ * marketplaces, not trigger additional refresh cycles.
  */
 async function autoAddMissingMarketplaces(projectPath) {
     const referenced = await getReferencedMarketplaces(projectPath);
@@ -74,19 +80,11 @@ async function autoAddMissingMarketplaces(projectPath) {
         if (!defaultMp?.source.repo)
             continue;
         try {
-            // Try `marketplace update` first — it re-clones missing directories
-            await updateMarketplace(mpName);
+            await addMarketplace(defaultMp.source.repo);
             added.push(mpName);
         }
-        catch {
-            // If update fails (marketplace not in settings yet), try add
-            try {
-                await addMarketplace(defaultMp.source.repo);
-                added.push(mpName);
-            }
-            catch (error) {
-                console.warn(`⚠ Failed to auto-add marketplace ${mpName}:`, error instanceof Error ? error.message : "Unknown error");
-            }
+        catch (error) {
+            console.warn(`⚠ Failed to auto-add marketplace ${mpName}:`, error instanceof Error ? error.message : "Unknown error");
         }
     }
     return added;
@@ -186,6 +184,22 @@ export async function prerunClaude(claudeArgs, options = {}) {
         if (addedHooks) {
             console.log(`✓ Added tmux-claude-continuity hooks to ~/.claude/settings.json`);
         }
+        // STEP 0.7: Gap-fill installedPluginVersions across scopes
+        // When a plugin is updated at project/local scope, global may lag behind.
+        // Sync the highest version from any scope up to global so Claude Code
+        // resolves the latest cached plugin paths at session startup.
+        try {
+            const gapFilled = await gapFillInstalledPluginVersions(process.cwd());
+            if (gapFilled.length > 0) {
+                console.log(`✓ Synced ${gapFilled.length} plugin version(s) to global:`);
+                for (const { pluginId, oldVersion, newVersion } of gapFilled) {
+                    console.log(`  - ${pluginId}: ${oldVersion} → ${newVersion}`);
+                }
+            }
+        }
+        catch {
+            // Non-fatal: gap-fill is best-effort
+        }
         // STEP 1: Check if we should update (time-based cache, or forced)
         const shouldUpdate = options.force || (await cache.shouldCheckForUpdates());
         if (options.force) {

package/src/prerunner/index.ts

@@ -17,13 +17,13 @@ import {
 	readGlobalSettings,
 	writeGlobalSettings,
 	saveGlobalInstalledPluginVersion,
+	gapFillInstalledPluginVersions,
 } from "../services/claude-settings.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { defaultMarketplaces } from "../data/marketplaces.js";
 import {
 	updatePlugin,
 	addMarketplace,
-	updateMarketplace,
 	isClaudeAvailable,
 } from "../services/claude-cli.js";
 
@@ -88,10 +88,16 @@ async function getReferencedMarketplaces(
  * Check which referenced marketplaces are missing locally and auto-add them.
  * Only adds marketplaces with known repos (from defaultMarketplaces).
  *
- * Uses `marketplace update` (not `marketplace add`) for recovery because
- * `add` short-circuits when the marketplace is already declared in settings
- * — even if the directory was deleted. `update` detects the missing dir and
- * re-clones automatically.
+ * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
+ * Claude Code's `marketplace update` calls cacheMarketplaceFromGit() which
+ * deletes the marketplace directory before re-cloning. If the clone fails
+ * (network timeout, auth error), the directory stays permanently deleted
+ * and ALL plugins from that marketplace break. See:
+ * ai-docs/plugin-marketplace-bug-investigation.md
+ *
+ * Claude Code's own background autoupdate handles marketplace refreshing
+ * after session start — claudeup should only recover genuinely missing
+ * marketplaces, not trigger additional refresh cycles.
  */
 async function autoAddMissingMarketplaces(
 	projectPath?: string,
@@ -109,20 +115,13 @@ async function autoAddMissingMarketplaces(
 		if (!defaultMp?.source.repo) continue;
 
 		try {
-			// Try `marketplace update` first — it re-clones missing directories
-			await updateMarketplace(mpName);
+			await addMarketplace(defaultMp.source.repo);
 			added.push(mpName);
-		} catch {
-			// If update fails (marketplace not in settings yet), try add
-			try {
-				await addMarketplace(defaultMp.source.repo);
-				added.push(mpName);
-			} catch (error) {
-				console.warn(
-					`⚠ Failed to auto-add marketplace ${mpName}:`,
-					error instanceof Error ? error.message : "Unknown error",
-				);
-			}
+		} catch (error) {
+			console.warn(
+				`⚠ Failed to auto-add marketplace ${mpName}:`,
+				error instanceof Error ? error.message : "Unknown error",
+			);
 		}
 	}
 
@@ -256,6 +255,24 @@ export async function prerunClaude(
 			);
 		}
 
+		// STEP 0.7: Gap-fill installedPluginVersions across scopes
+		// When a plugin is updated at project/local scope, global may lag behind.
+		// Sync the highest version from any scope up to global so Claude Code
+		// resolves the latest cached plugin paths at session startup.
+		try {
+			const gapFilled = await gapFillInstalledPluginVersions(process.cwd());
+			if (gapFilled.length > 0) {
+				console.log(
+					`✓ Synced ${gapFilled.length} plugin version(s) to global:`,
+				);
+				for (const { pluginId, oldVersion, newVersion } of gapFilled) {
+					console.log(`  - ${pluginId}: ${oldVersion} → ${newVersion}`);
+				}
+			}
+		} catch {
+			// Non-fatal: gap-fill is best-effort
+		}
+
 		// STEP 1: Check if we should update (time-based cache, or forced)
 		const shouldUpdate = options.force || (await cache.shouldCheckForUpdates());
 

package/src/services/claude-settings.js

@@ -1,6 +1,7 @@
 import fs from "fs-extra";
 import path from "node:path";
 import os from "node:os";
+import semver from "semver";
 import { parsePluginId } from "../utils/string-utils.js";
 const CLAUDE_DIR = ".claude";
 const SETTINGS_FILE = "settings.json";
@@ -377,6 +378,79 @@ export async function saveGlobalInstalledPluginVersion(pluginId, version) {
     // Update registry for user scope
     await updateInstalledPluginsRegistry(pluginId, version, "user");
 }
+/**
+ * Gap-fill: ensure global installedPluginVersions is at least as high as
+ * project and local scopes. When a plugin is updated at project scope,
+ * global may lag behind, causing Claude Code to resolve stale cache paths.
+ *
+ * @returns Array of { pluginId, oldVersion, newVersion } for plugins that were bumped
+ */
+export async function gapFillInstalledPluginVersions(projectPath) {
+    const globalVersions = await getGlobalInstalledPluginVersions();
+    // Collect versions from project and local scopes
+    const allVersions = {};
+    // Start with global versions
+    for (const [id, ver] of Object.entries(globalVersions)) {
+        allVersions[id] = [ver];
+    }
+    // Add project scope versions
+    if (projectPath) {
+        try {
+            const settings = await readSettings(projectPath);
+            for (const [id, ver] of Object.entries(settings.installedPluginVersions || {})) {
+                if (!allVersions[id])
+                    allVersions[id] = [];
+                allVersions[id].push(ver);
+            }
+        }
+        catch {
+            /* skip unreadable */
+        }
+        // Add local scope versions
+        try {
+            const localSettings = await readLocalSettings(projectPath);
+            for (const [id, ver] of Object.entries(localSettings.installedPluginVersions || {})) {
+                if (!allVersions[id])
+                    allVersions[id] = [];
+                allVersions[id].push(ver);
+            }
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    // Find plugins where global needs bumping
+    const bumped = [];
+    for (const [pluginId, versions] of Object.entries(allVersions)) {
+        // Filter to valid semver versions and sort descending
+        const valid = versions.filter((v) => semver.valid(v));
+        if (valid.length === 0)
+            continue;
+        const highest = valid.sort((a, b) => semver.rcompare(a, b))[0];
+        const globalVer = globalVersions[pluginId];
+        // If global is missing, invalid semver, or lower than the highest, bump it
+        if (!globalVer ||
+            !semver.valid(globalVer) ||
+            semver.lt(globalVer, highest)) {
+            bumped.push({
+                pluginId,
+                oldVersion: globalVer || "(missing)",
+                newVersion: highest,
+            });
+        }
+    }
+    // Apply bumps in a single write
+    if (bumped.length > 0) {
+        const settings = await readGlobalSettings();
+        settings.installedPluginVersions =
+            settings.installedPluginVersions || {};
+        for (const { pluginId, newVersion } of bumped) {
+            settings.installedPluginVersions[pluginId] = newVersion;
+        }
+        await writeGlobalSettings(settings);
+    }
+    return bumped;
+}
 export async function removeGlobalInstalledPluginVersion(pluginId) {
     const settings = await readGlobalSettings();
     if (settings.installedPluginVersions) {

package/src/services/claude-settings.ts

@@ -1,6 +1,7 @@
 import fs from "fs-extra";
 import path from "node:path";
 import os from "node:os";
+import semver from "semver";
 import type {
 	ClaudeSettings,
 	ClaudeLocalSettings,
@@ -544,6 +545,97 @@ export async function saveGlobalInstalledPluginVersion(
 	await updateInstalledPluginsRegistry(pluginId, version, "user");
 }
 
+/**
+ * Gap-fill: ensure global installedPluginVersions is at least as high as
+ * project and local scopes. When a plugin is updated at project scope,
+ * global may lag behind, causing Claude Code to resolve stale cache paths.
+ *
+ * @returns Array of { pluginId, oldVersion, newVersion } for plugins that were bumped
+ */
+export async function gapFillInstalledPluginVersions(
+	projectPath?: string,
+): Promise<Array<{ pluginId: string; oldVersion: string; newVersion: string }>> {
+	const globalVersions = await getGlobalInstalledPluginVersions();
+
+	// Collect versions from project and local scopes
+	const allVersions: Record<string, string[]> = {};
+
+	// Start with global versions
+	for (const [id, ver] of Object.entries(globalVersions)) {
+		allVersions[id] = [ver];
+	}
+
+	// Add project scope versions
+	if (projectPath) {
+		try {
+			const settings = await readSettings(projectPath);
+			for (const [id, ver] of Object.entries(
+				settings.installedPluginVersions || {},
+			)) {
+				if (!allVersions[id]) allVersions[id] = [];
+				allVersions[id].push(ver);
+			}
+		} catch {
+			/* skip unreadable */
+		}
+
+		// Add local scope versions
+		try {
+			const localSettings = await readLocalSettings(projectPath);
+			for (const [id, ver] of Object.entries(
+				localSettings.installedPluginVersions || {},
+			)) {
+				if (!allVersions[id]) allVersions[id] = [];
+				allVersions[id].push(ver);
+			}
+		} catch {
+			/* skip unreadable */
+		}
+	}
+
+	// Find plugins where global needs bumping
+	const bumped: Array<{
+		pluginId: string;
+		oldVersion: string;
+		newVersion: string;
+	}> = [];
+
+	for (const [pluginId, versions] of Object.entries(allVersions)) {
+		// Filter to valid semver versions and sort descending
+		const valid = versions.filter((v) => semver.valid(v));
+		if (valid.length === 0) continue;
+
+		const highest = valid.sort((a, b) => semver.rcompare(a, b))[0];
+		const globalVer = globalVersions[pluginId];
+
+		// If global is missing, invalid semver, or lower than the highest, bump it
+		if (
+			!globalVer ||
+			!semver.valid(globalVer) ||
+			semver.lt(globalVer, highest)
+		) {
+			bumped.push({
+				pluginId,
+				oldVersion: globalVer || "(missing)",
+				newVersion: highest,
+			});
+		}
+	}
+
+	// Apply bumps in a single write
+	if (bumped.length > 0) {
+		const settings = await readGlobalSettings();
+		settings.installedPluginVersions =
+			settings.installedPluginVersions || {};
+		for (const { pluginId, newVersion } of bumped) {
+			settings.installedPluginVersions[pluginId] = newVersion;
+		}
+		await writeGlobalSettings(settings);
+	}
+
+	return bumped;
+}
+
 export async function removeGlobalInstalledPluginVersion(
 	pluginId: string,
 ): Promise<void> {

package/src/services/plugin-manager.js

@@ -5,7 +5,6 @@ import { getConfiguredMarketplaces, getEnabledPlugins, readSettings, writeSettin
 import { defaultMarketplaces } from "../data/marketplaces.js";
 import { scanLocalMarketplaces, repairAllMarketplaces, } from "./local-marketplace.js";
 import { formatMarketplaceName, isValidGitHubRepo, parsePluginId, } from "../utils/string-utils.js";
-import { updateMarketplace } from "./claude-cli.js";
 // Cache for local marketplaces (session-level) - Promise-based to prevent race conditions
 let localMarketplacesPromise = null;
 // Session-level cache for fetched marketplace data (no TTL - persists until explicit refresh)
@@ -434,9 +433,14 @@ export async function getLocalMarketplacesInfo() {
 const autoSyncedMarketplaces = new Set();
 /**
  * If the remote manifest lists plugins that aren't in the local cache,
- * the local clone is stale. Silently run `claude plugin marketplace update`
- * to pull the latest, then invalidate the local cache so the next scan
- * picks up the new plugins.
+ * the local clone is stale. Log a warning but do NOT trigger a marketplace
+ * update from claudeup.
+ *
+ * Previously this called `updateMarketplace()` which invokes Claude Code's
+ * `cacheMarketplaceFromGit()` — a non-atomic delete-then-clone that can
+ * permanently delete the marketplace directory on clone failure.
+ * Claude Code's own background autoupdate handles marketplace refreshing
+ * after session start. See: ai-docs/plugin-marketplace-bug-investigation.md
  */
 async function autoSyncIfStale(mpName, remotePluginNames, localMarketplaces) {
     if (autoSyncedMarketplaces.has(mpName))
@@ -445,20 +449,13 @@ async function autoSyncIfStale(mpName, remotePluginNames, localMarketplaces) {
     if (!localMp)
         return localMarketplaces;
     const localNames = new Set(localMp.plugins.map((p) => p.name));
-    const hasMissing = remotePluginNames.some((name) => !localNames.has(name));
-    if (!hasMissing)
+    const missingPlugins = remotePluginNames.filter((name) => !localNames.has(name));
+    if (missingPlugins.length === 0)
         return localMarketplaces;
     autoSyncedMarketplaces.add(mpName);
-    try {
-        await updateMarketplace(mpName);
-        // Invalidate local cache so re-scan picks up new plugins
-        localMarketplacesPromise = null;
-        return getLocalMarketplaces();
-    }
-    catch {
-        // Update failed (no network, CLI missing, etc.) — continue with stale data
-        return localMarketplaces;
-    }
+    // Log stale state but don't trigger update — Claude Code handles refresh
+    console.log(`ℹ Marketplace ${mpName} is stale (missing: ${missingPlugins.join(", ")}). Claude Code will auto-update on next session start.`);
+    return localMarketplaces;
 }
 /**
  * Refresh claudeup's internal cache

package/src/services/plugin-manager.ts

@@ -27,8 +27,6 @@ import {
 	isValidGitHubRepo,
 	parsePluginId,
 } from "../utils/string-utils.js";
-import { updateMarketplace } from "./claude-cli.js";
-
 // Cache for local marketplaces (session-level) - Promise-based to prevent race conditions
 let localMarketplacesPromise: Promise<Map<string, LocalMarketplace>> | null =
 	null;
@@ -619,9 +617,14 @@ const autoSyncedMarketplaces = new Set<string>();
 
 /**
  * If the remote manifest lists plugins that aren't in the local cache,
- * the local clone is stale. Silently run `claude plugin marketplace update`
- * to pull the latest, then invalidate the local cache so the next scan
- * picks up the new plugins.
+ * the local clone is stale. Log a warning but do NOT trigger a marketplace
+ * update from claudeup.
+ *
+ * Previously this called `updateMarketplace()` which invokes Claude Code's
+ * `cacheMarketplaceFromGit()` — a non-atomic delete-then-clone that can
+ * permanently delete the marketplace directory on clone failure.
+ * Claude Code's own background autoupdate handles marketplace refreshing
+ * after session start. See: ai-docs/plugin-marketplace-bug-investigation.md
  */
 async function autoSyncIfStale(
 	mpName: string,
@@ -634,19 +637,17 @@ async function autoSyncIfStale(
 	if (!localMp) return localMarketplaces;
 
 	const localNames = new Set(localMp.plugins.map((p) => p.name));
-	const hasMissing = remotePluginNames.some((name) => !localNames.has(name));
-	if (!hasMissing) return localMarketplaces;
+	const missingPlugins = remotePluginNames.filter(
+		(name) => !localNames.has(name),
+	);
+	if (missingPlugins.length === 0) return localMarketplaces;
 
 	autoSyncedMarketplaces.add(mpName);
-	try {
-		await updateMarketplace(mpName);
-		// Invalidate local cache so re-scan picks up new plugins
-		localMarketplacesPromise = null;
-		return getLocalMarketplaces();
-	} catch {
-		// Update failed (no network, CLI missing, etc.) — continue with stale data
-		return localMarketplaces;
-	}
+	// Log stale state but don't trigger update — Claude Code handles refresh
+	console.log(
+		`ℹ Marketplace ${mpName} is stale (missing: ${missingPlugins.join(", ")}). Claude Code will auto-update on next session start.`,
+	);
+	return localMarketplaces;
 }
 
 export interface RefreshAndRepairResult {