magus-cli 7.11.7 → 7.11.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.11.7",
+  "version": "7.11.8",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -65,8 +65,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.11.7",
-    "magus-cli-darwin-x64": "7.11.7",
-    "magus-cli-linux-x64": "7.11.7"
+    "magus-cli-darwin-arm64": "7.11.8",
+    "magus-cli-darwin-x64": "7.11.8",
+    "magus-cli-linux-x64": "7.11.8"
   }
 }

package/src/__tests__/marketplace-refresh.test.ts

@@ -15,18 +15,36 @@ import path from "node:path";
 // --- Mock the marketplace registry (the only magus dep of the refresher) ---
 let configured: Record<string, { source: { source: string; repo?: string } }>;
 let autoUpdate: Record<string, boolean | undefined>;
+/**
+ * USER-scope `enabledPlugins`. `null` means "one USER plugin from every
+ * registered marketplace", so the cases written before the needed-only rule
+ * keep exercising the pull itself; the needed-only cases set it explicitly.
+ */
+let userEnabled: Record<string, boolean> | null;
 
 mock.module("../services/claude-settings.js", () => ({
 	getConfiguredMarketplaces: async () => configured,
 	getMarketplaceAutoUpdate: async (name: string) => autoUpdate[name],
+	getGlobalEnabledPlugins: async () =>
+		userEnabled ??
+		Object.fromEntries(Object.keys(configured).map((n) => [`p@${n}`, true])),
 	// The refresher resolves clone paths via this helper; point it at our temp
 	// home so no real ~/.claude marketplace is ever touched. (Bun's os.homedir()
 	// ignores runtime $HOME changes, so mocking the helper is the reliable seam.)
 	getGlobalClaudeDir: () => path.join(tmp, ".claude"),
 }));
 
-const { refreshRegisteredMarketplaces, fastForwardCloneIfPresent } =
-	await import("../services/marketplace-refresh.js");
+const {
+	refreshRegisteredMarketplaces,
+	reportRegisteredMarketplaces,
+	fastForwardCloneIfPresent,
+} = await import("../services/marketplace-refresh.js");
+const {
+	CATALOG_TTL_MS,
+	clearCloneRefreshes,
+	readCloneRefreshAge,
+	resetCatalogCacheMemo,
+} = await import("../services/catalog-cache-store.js");
 
 const gh = (repo = "MadAppGang/magus") => ({
 	source: { source: "github", repo },
@@ -110,6 +128,7 @@ beforeEach(() => {
 
 	configured = {};
 	autoUpdate = {};
+	userEnabled = null;
 });
 
 afterEach(() => {
@@ -457,3 +476,193 @@ describe("fastForwardCloneIfPresent — per-clone deadline", () => {
 		expect(await goneWithin(readPid(pullPid), 1_000)).toBe(true);
 	}, 10_000);
 });
+
+/** The clone's HEAD and origin's main, to tell "pulled" from "left behind". */
+function headOf(dir: string): string {
+	return git(dir, "rev-parse", "HEAD").trim();
+}
+function originHead(): string {
+	return git(origin, "rev-parse", "main").trim();
+}
+
+describe("refreshRegisteredMarketplaces — needed only (MTL-367)", () => {
+	it("does not pull a registered marketplace no installed plugin comes from, and reports it skipped", async () => {
+		const used = installClone("magus");
+		const unused = installClone("unused");
+		publishV2();
+		configured = { magus: gh(), unused: gh("x/unused") };
+		userEnabled = {};
+
+		const r = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ pluginIds: ["dev@magus"] },
+		);
+
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(r.skipped).toEqual(["unused"]);
+		expect(headOf(used)).toBe(originHead());
+		expect(headOf(unused)).not.toBe(originHead()); // left behind
+	});
+
+	it("pulls a marketplace used only by a USER-scope plugin", async () => {
+		const dir = installClone("userland");
+		installClone("unused");
+		publishV2();
+		configured = { userland: gh("x/userland"), unused: gh("x/unused") };
+		// `false` is not installed: only `true` counts.
+		userEnabled = { "tool@userland": true, "off@unused": false };
+
+		const r = await refreshRegisteredMarketplaces([], {}, { pluginIds: [] });
+
+		expect(r.refreshed).toEqual(["userland"]);
+		expect(r.skipped).toEqual(["unused"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("report-only applies the same selection: an unused marketplace is skipped, a used one pending", async () => {
+		installClone("magus");
+		installClone("unused");
+		configured = { magus: gh(), unused: gh("x/unused") };
+		userEnabled = {};
+
+		const r = await reportRegisteredMarketplaces([], {
+			pluginIds: ["dev@magus"],
+		});
+
+		expect(r.refreshed).toEqual([]);
+		expect(r.pending).toEqual(["magus"]);
+		expect(r.skipped).toEqual(["unused"]);
+	});
+});
+
+describe("refreshRegisteredMarketplaces — at most once an hour, machine-wide (MTL-367)", () => {
+	let prevConfigDir: string | undefined;
+	const T0 = 1_790_000_000_000;
+
+	beforeEach(() => {
+		prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
+		// The store lives under the temp home, never the operator's.
+		process.env.CLAUDE_CONFIG_DIR = path.join(tmp, ".claude");
+		resetCatalogCacheMemo();
+	});
+	afterEach(() => {
+		// biome-ignore lint/performance/noDelete: assigning undefined stores the string "undefined"
+		if (prevConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+		else process.env.CLAUDE_CONFIG_DIR = prevConfigDir;
+		resetCatalogCacheMemo();
+	});
+
+	it("does not pull again within the hour, and reports it fresh", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+
+		const first = await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(first.refreshed).toEqual(["magus"]);
+
+		publishV2(); // origin advances after the first pull
+		resetCatalogCacheMemo(); // a second process, same machine
+		const before = headOf(dir);
+		const second = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + 10 * 60 * 1000 },
+		);
+
+		expect(second.refreshed).toEqual([]);
+		expect(second.fresh).toEqual(["magus"]);
+		expect(second.skipped).toEqual([]);
+		expect(headOf(dir)).toBe(before);
+		expect(headOf(dir)).not.toBe(originHead());
+	});
+
+	it("pulls again once the TTL has passed", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		publishV2();
+		const r = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + CATALOG_TTL_MS + 1 },
+		);
+
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(r.fresh).toEqual([]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("a failed pull records no time, so the next call pulls again", async () => {
+		const dir = installClone("magus");
+		git(dir, "remote", "set-url", "origin", path.join(tmp, "gone.git"));
+		configured = { magus: gh() };
+
+		const failed = await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(failed.failed).toEqual(["magus"]);
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+
+		git(dir, "remote", "set-url", "origin", origin);
+		publishV2();
+		const retry = await refreshRegisteredMarketplaces(
+			[],
+			{},
+			{ now: T0 + 60_000 },
+		);
+		expect(retry.refreshed).toEqual(["magus"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("an explicit refresh (the TUI's `r`) clears the record, so the next call pulls", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		// `r` -> refreshAllMarketplaces -> clearPersistedCatalogs.
+		const { clearPersistedCatalogs } = await import(
+			"../services/marketplace-fetcher.js"
+		);
+		await clearPersistedCatalogs();
+
+		publishV2();
+		resetCatalogCacheMemo();
+		const r = await refreshRegisteredMarketplaces([], {}, { now: T0 + 60_000 });
+		expect(r.refreshed).toEqual(["magus"]);
+		expect(headOf(dir)).toBe(originHead());
+	});
+
+	it("clearCloneRefreshes drops the record", async () => {
+		installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBe(1);
+
+		await clearCloneRefreshes();
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+	});
+
+	it("report-only writes no time, and the next writing run pulls", async () => {
+		const dir = installClone("magus");
+		configured = { magus: gh() };
+		publishV2();
+
+		const report = await reportRegisteredMarketplaces([], { now: T0 });
+		expect(report.pending).toEqual(["magus"]);
+		resetCatalogCacheMemo();
+		expect(await readCloneRefreshAge("magus", T0 + 1)).toBeNull();
+		expect(headOf(dir)).not.toBe(originHead());
+
+		const r = await refreshRegisteredMarketplaces([], {}, { now: T0 + 1 });
+		expect(r.refreshed).toEqual(["magus"]);
+	});
+
+	it("report-only reports a clone refreshed within the hour as fresh", async () => {
+		installClone("magus");
+		configured = { magus: gh() };
+		await refreshRegisteredMarketplaces([], {}, { now: T0 });
+
+		const report = await reportRegisteredMarketplaces([], { now: T0 + 1000 });
+		expect(report.fresh).toEqual(["magus"]);
+		expect(report.pending).toEqual([]);
+	});
+});

package/src/cli/update.ts

@@ -364,36 +364,53 @@ async function updateProfile(
 	// own output, which is where this was caught. A read-only run plans against
 	// the clone as it stands; the notice below says so, so an unrefreshed
 	// catalog is never mistaken for a current one.
+	//
+	// Only marketplaces some installed plugin comes from are pulled: this
+	// profile's plugins, plus whatever is installed at USER scope (the refresher
+	// reads that itself). And each clone at most once an hour, machine-wide.
+	const readOnly = flags.dryRun || flags.check;
+	const pluginIds = Object.keys(closure.plugins);
 	const refresh = await runStep(steps.marketplaces, async (say) => {
-		if (flags.dryRun || flags.check) {
+		if (readOnly) {
 			say("read-only — selecting, not pulling");
-			// Report-only, NOT a skip: the autoUpdate-disabled verdict is a pure
-			// read and is the one diagnostic a read-only run must not lose.
-			const report = await reportRegisteredMarketplaces();
-			steps.marketplaces.detail = `not refreshed (read-only) · ${report.skipped.length} eligible`;
-			return report;
+			// Report-only, NOT a skip: the selection is a pure read, so a read-only
+			// run can still say exactly what a real run would pull.
+			return reportRegisteredMarketplaces([], { pluginIds });
 		}
 		let settled = 0;
-		return refreshRegisteredMarketplaces([], {
-			onStart: (names) => {
-				// Only now is there a denominator; until `onStart` fires the step
-				// shows a sweep rather than a meter that would have to guess one.
-				steps.marketplaces.progress = { done: 0, total: names.length };
-				say(
-					names.length === 0 ? "none eligible" : `pulling ${names.join(", ")}`,
-				);
-			},
-			onSettled: (name, status) => {
-				settled++;
-				if (steps.marketplaces.progress)
-					steps.marketplaces.progress.done = settled;
-				say(`${name} ${status}`);
+		return refreshRegisteredMarketplaces(
+			[],
+			{
+				onStart: (names) => {
+					// Only now is there a denominator; until `onStart` fires the step
+					// shows a sweep rather than a meter that would have to guess one.
+					steps.marketplaces.progress = { done: 0, total: names.length };
+					say(
+						names.length === 0
+							? "none eligible"
+							: `pulling ${names.join(", ")}`,
+					);
+				},
+				onSettled: (name, status) => {
+					settled++;
+					if (steps.marketplaces.progress)
+						steps.marketplaces.progress.done = settled;
+					say(`${name} ${status}`);
+				},
 			},
-		});
+			{ pluginIds },
+		);
 	});
 	steps.marketplaces.detail = [
-		`${refresh.refreshed.length} refreshed`,
+		readOnly
+			? `not refreshed (read-only) · ${refresh.pending.length} would refresh`
+			: `${refresh.refreshed.length} refreshed`,
 		refresh.failed.length > 0 ? `${refresh.failed.length} failed` : "",
+		// Not "up to date": the clone was pulled within the hour, and upstream
+		// may have moved since. Say what is known.
+		refresh.fresh.length > 0
+			? `${refresh.fresh.length} refreshed in the last hour`
+			: "",
 		refresh.skipped.length > 0 ? `${refresh.skipped.length} skipped` : "",
 	]
 		.filter(Boolean)

package/src/services/catalog-cache-store.ts

@@ -37,10 +37,11 @@ import type { MarketplacePlugin } from "./marketplace-catalog.js";
  *
  * This is the ONLY refresh rhythm magus has, and it applies to both surfaces:
  * `magus update` and the TUI read a catalog written here within the hour
- * before they go to the network. `update` pulls the marketplace clones and
- * drops its in-process memo before planning, but it does NOT clear this file,
- * so a release published inside the TTL is not seen by `update` either. Only
- * an explicit refresh (`r` in the TUI) clears it. Anything that reports "no
+ * before they go to the network. `update` pulls the marketplace clones (each
+ * at most once per TTL, machine-wide — see `cloneRefreshes`) and drops its
+ * in-process memo before planning, but it does NOT clear this file, so a
+ * release published inside the TTL is not seen by `update` either. Only an
+ * explicit refresh (`r` in the TUI) clears it, clone refresh times included. Anything that reports "no
  * update" — or decides a plugin is no longer published — off a cached catalog
  * is working from an answer up to an hour old, by design.
  */
@@ -93,14 +94,24 @@ interface StoreShape {
 	catalogs: Record<string, StoredCatalog>;
 	cooldowns: Record<string, StoredCooldown>;
 	communityStyles: Record<string, StoredCommunityCheck>;
+	/**
+	 * Per marketplace: wall-clock ms of the last SUCCESSFUL fast-forward of its
+	 * on-disk clone. Machine-wide, so one project's `magus update` spares every
+	 * other project's the same pull within CATALOG_TTL_MS.
+	 */
+	cloneRefreshes: Record<string, number>;
 }
 
-const EMPTY: StoreShape = {
-	version: 1,
-	catalogs: {},
-	cooldowns: {},
-	communityStyles: {},
-};
+/** A fresh empty store. A function, so no caller can share and mutate one object. */
+function emptyStore(): StoreShape {
+	return {
+		version: 1,
+		catalogs: {},
+		cooldowns: {},
+		communityStyles: {},
+		cloneRefreshes: {},
+	};
+}
 
 /**
  * Resolved per call, honouring CLAUDE_CONFIG_DIR — same reasoning as
@@ -124,29 +135,24 @@ let memo: { path: string; data: StoreShape } | null = null;
 
 async function load(): Promise<StoreShape> {
 	const file = storePath();
-	if (!file)
-		return { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+	if (!file) return emptyStore();
 	if (memo?.path === file) return memo.data;
 	try {
 		const parsed = JSON.parse(await fs.readFile(file, "utf-8")) as StoreShape;
 		// A cache from a future/unknown layout is discarded rather than migrated:
 		// it is regenerable by definition, so guessing at it buys nothing.
-		const data = parsed?.version === 1 ? parsed : { ...EMPTY };
+		const data = parsed?.version === 1 ? parsed : emptyStore();
 		data.catalogs ??= {};
 		data.cooldowns ??= {};
-		// Absent in every file written before community styles existed, so this
+		// Absent in every file written before these sections existed, so the
 		// default is the migration — an upgrade must not read as a corrupt cache.
 		data.communityStyles ??= {};
+		data.cloneRefreshes ??= {};
 		memo = { path: file, data };
 		return data;
 	} catch {
 		// Absent or corrupt. A cache must never be a failure mode — start empty.
-		const data: StoreShape = {
-			...EMPTY,
-			catalogs: {},
-			cooldowns: {},
-			communityStyles: {},
-		};
+		const data = emptyStore();
 		memo = { path: file, data };
 		return data;
 	}
@@ -179,15 +185,11 @@ async function mutate(fn: (data: StoreShape) => void): Promise<void> {
 								catalogs: parsed.catalogs ?? {},
 								cooldowns: parsed.cooldowns ?? {},
 								communityStyles: parsed.communityStyles ?? {},
+								cloneRefreshes: parsed.cloneRefreshes ?? {},
 							}
-						: { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+						: emptyStore();
 			} catch {
-				onDisk = {
-					version: 1,
-					catalogs: {},
-					cooldowns: {},
-					communityStyles: {},
-				};
+				onDisk = emptyStore();
 			}
 			fn(onDisk);
 			// Temp + rename, so a crash mid-write cannot leave a half-written file
@@ -312,6 +314,44 @@ export async function clearCommunityChecks(): Promise<void> {
 	});
 }
 
+// ─── Marketplace clone refreshes ─────────────────────────────────────────────
+
+/**
+ * Milliseconds since this marketplace's clone was last fast-forwarded
+ * successfully, or null when that was never, longer ago than CATALOG_TTL_MS, or
+ * in the future (a clock that moved back must not freeze the clone).
+ *
+ * Same TTL as the catalogs, on purpose: the clone and the catalog answer the
+ * same question, so they go stale on one rhythm and `r` clears both.
+ */
+export async function readCloneRefreshAge(
+	marketplace: string,
+	now: number = Date.now(),
+): Promise<number | null> {
+	const at = (await load()).cloneRefreshes[marketplace];
+	if (typeof at !== "number") return null;
+	const ageMs = now - at;
+	if (ageMs < 0 || ageMs > CATALOG_TTL_MS) return null;
+	return ageMs;
+}
+
+/** Record a successful fast-forward. Never called for a failed or skipped pull. */
+export async function writeCloneRefreshed(
+	marketplace: string,
+	now: number = Date.now(),
+): Promise<void> {
+	await mutate((data) => {
+		data.cloneRefreshes[marketplace] = now;
+	});
+}
+
+/** Drop every clone refresh time. Backs the explicit refresh (`r`). */
+export async function clearCloneRefreshes(): Promise<void> {
+	await mutate((data) => {
+		data.cloneRefreshes = {};
+	});
+}
+
 /** Test seam: forget this process's memo so the next read hits disk. */
 export function resetCatalogCacheMemo(): void {
 	memo = null;

package/src/services/marketplace-fetcher.ts

@@ -10,6 +10,7 @@
 import { isValidGitHubRepo } from "../utils/string-utils.js";
 import {
 	clearCachedCatalogs,
+	clearCloneRefreshes,
 	readCachedCatalog,
 	writeCachedCatalog,
 } from "./catalog-cache-store.js";
@@ -145,6 +146,9 @@ export function clearMarketplaceCache(): void {
  */
 export async function clearPersistedCatalogs(): Promise<void> {
 	await clearCachedCatalogs();
+	// The clone refresh times too: an explicit refresh means "ask again now", so
+	// the next `magus update` pulls every needed clone instead of trusting the hour.
+	await clearCloneRefreshes();
 }
 
 /**

package/src/services/marketplace-refresh.ts

@@ -20,9 +20,15 @@
 import fs from "node:fs";
 import path from "node:path";
 import { runBounded } from "../utils/spawn-bounded.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import {
+	readCloneRefreshAge,
+	writeCloneRefreshed,
+} from "./catalog-cache-store.js";
 import {
 	getConfiguredMarketplaces,
 	getGlobalClaudeDir,
+	getGlobalEnabledPlugins,
 	getMarketplaceAutoUpdate,
 } from "./claude-settings.js";
 
@@ -37,10 +43,54 @@ export interface RefreshResult {
 	refreshed: string[];
 	/** Pull errored (network, diverged, timeout) — clone left intact and stale. */
 	failed: string[];
-	/** Nothing to do: no clone on disk, not a git repo, or dirty tree. */
+	/**
+	 * Not pulled because this machine already refreshed the clone successfully
+	 * within CATALOG_TTL_MS — by this project's run or any other.
+	 */
+	fresh: string[];
+	/**
+	 * Report-only: selected, and a writing run would pull it. Always empty when
+	 * the refresh actually ran.
+	 */
+	pending: string[];
+	/**
+	 * Not pulled, and not a failure: no installed plugin comes from it, not a
+	 * github source, autoUpdate off, no clone on disk, or dirty tree.
+	 */
 	skipped: string[];
 }
 
+export interface RefreshOptions {
+	/**
+	 * Plugin ids (`name@marketplace`) this run installs — the profile's
+	 * PROJECT/LOCAL set. Unioned with every plugin installed at USER scope;
+	 * a marketplace none of them comes from is not pulled.
+	 */
+	pluginIds?: Iterable<string>;
+	/** Clock seam for the once-an-hour rule. */
+	now?: number;
+}
+
+/**
+ * The marketplaces some installed plugin comes from: the ones passed in
+ * (PROJECT/LOCAL, from the profile) plus every plugin turned on at USER scope.
+ * A USER entry set to `false` is not installed and does not count.
+ */
+async function neededMarketplaces(
+	pluginIds: Iterable<string>,
+): Promise<Set<string>> {
+	const ids = [...pluginIds];
+	for (const [id, on] of Object.entries(await getGlobalEnabledPlugins())) {
+		if (on === true) ids.push(id);
+	}
+	const needed = new Set<string>();
+	for (const id of ids) {
+		const parsed = parsePluginId(id);
+		if (parsed) needed.add(parsed.marketplace);
+	}
+	return needed;
+}
+
 function cloneDir(name: string): string {
 	return path.join(getGlobalClaudeDir(), "plugins", "marketplaces", name);
 }
@@ -170,46 +220,62 @@ function tap(fn: (() => void) | undefined): void {
 	}
 }
 
-/**
- * Non-destructively fast-forward the on-disk clone of every registered,
- * auto-update-enabled, github-sourced marketplace.
- *
- * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
- *   so they aren't pulled twice.
- * @param progress optional taps for a live progress display.
- * @returns which marketplaces were refreshed, which failed (clone left intact),
- *   and which were skipped. Failures and skips are collected rather than thrown —
- *   one unreachable marketplace must not block launching Claude. Pulls run
- *   concurrently, so a slow one doesn't serialize the rest onto the launch path.
- */
 /**
  * Select and report, writing nothing.
  *
- * Everything above the pull loop is a read — the marketplace registry and each
- * entry's `autoUpdate` flag — so a read-only caller can have the full selection
- * verdict for free. `--dry-run` and `--check` promise to write nothing and
- * therefore cannot pull, but they must still be able to say "your magus clone
- * has autoUpdate off, so its catalog will never advance". Gating the whole call
- * off silently dropped that warning, which is the same "no signal reads as no
- * problem" failure the flag exists to prevent.
+ * Everything above the pull loop is a read — the marketplace registry, each
+ * entry's `autoUpdate` flag, which marketplaces installed plugins come from,
+ * and when each clone was last refreshed — so a read-only caller can have the
+ * full selection verdict for free. `--dry-run` and `--check` promise to write
+ * nothing and therefore cannot pull (nor record a refresh time), but their
+ * report must name the same set a writing run would pull: that set is
+ * `pending`.
  */
 export async function reportRegisteredMarketplaces(
 	skip: Iterable<string> = [],
+	options: RefreshOptions = {},
 ): Promise<RefreshResult> {
-	return refreshRegisteredMarketplaces(skip, {}, { reportOnly: true });
+	return selectAndRefresh(skip, {}, { ...options, reportOnly: true });
 }
 
+/**
+ * Non-destructively fast-forward the on-disk clone of every registered,
+ * auto-update-enabled, github-sourced marketplace that some installed plugin
+ * comes from (USER scope, or `options.pluginIds`), unless this machine already
+ * refreshed it within CATALOG_TTL_MS. A successful pull records its time; a
+ * failed one does not, so the next run retries.
+ *
+ * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
+ *   so they aren't pulled twice.
+ * @param progress optional taps for a live progress display.
+ * @returns which marketplaces were refreshed, which failed (clone left intact),
+ *   which were fresh, and which were skipped. Failures and skips are collected
+ *   rather than thrown — one unreachable marketplace must not block launching
+ *   Claude. Pulls run concurrently, so a slow one doesn't serialize the rest
+ *   onto the launch path.
+ */
 export async function refreshRegisteredMarketplaces(
 	skip: Iterable<string> = [],
 	progress: RefreshProgress = {},
-	options: { reportOnly?: boolean } = {},
+	options: RefreshOptions = {},
+): Promise<RefreshResult> {
+	return selectAndRefresh(skip, progress, { ...options, reportOnly: false });
+}
+
+async function selectAndRefresh(
+	skip: Iterable<string>,
+	progress: RefreshProgress,
+	options: RefreshOptions & { reportOnly: boolean },
 ): Promise<RefreshResult> {
 	const refreshed: string[] = [];
 	const failed: string[] = [];
+	const fresh: string[] = [];
 	const skipped: string[] = [];
+	const now = options.now ?? Date.now();
 
 	const configured = await getConfiguredMarketplaces();
 	const skipSet = new Set(skip);
+	const needed = await neededMarketplaces(options.pluginIds ?? []);
 
 	// Select eligible marketplaces first so the pulls can run concurrently.
 	const eligible: string[] = [];
@@ -228,18 +294,25 @@ export async function refreshRegisteredMarketplaces(
 			skipped.push(name);
 			continue;
 		}
+		// Nothing installed at any scope comes from it, so a pull buys nothing.
+		if (!needed.has(name)) {
+			skipped.push(name);
+			continue;
+		}
+		// Refreshed on this machine within the hour, by any project's run.
+		if ((await readCloneRefreshAge(name, now)) !== null) {
+			fresh.push(name);
+			continue;
+		}
 		eligible.push(name);
 	}
 
 	// A read-only caller stops here, with the selection verdict intact and not
-	// one clone touched. `eligible` becomes `skipped`: nothing was refreshed, so
-	// claiming otherwise would be the false "all current" this module guards.
+	// one clone touched. `eligible` becomes `pending`, never `refreshed`: nothing
+	// was pulled, so claiming otherwise would be the false "all current" this
+	// module guards.
 	if (options.reportOnly) {
-		return {
-			refreshed: [],
-			failed: [],
-			skipped: [...skipped, ...eligible],
-		};
+		return { refreshed: [], failed: [], fresh, pending: eligible, skipped };
 	}
 
 	// Fast-forward every eligible clone in parallel so a slow one doesn't
@@ -261,5 +334,9 @@ export async function refreshRegisteredMarketplaces(
 		else skipped.push(name); // absent | skipped
 	});
 
-	return { refreshed, failed, skipped };
+	// Only a successful pull earns the hour. A failed, absent or dirty clone
+	// records nothing, so the next run — from any project — tries again.
+	for (const name of refreshed) await writeCloneRefreshed(name, now);
+
+	return { refreshed, failed, fresh, pending: [], skipped };
 }