magus-cli 7.11.6 → 7.11.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.11.6",
+  "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.6",
-    "magus-cli-darwin-x64": "7.11.6",
-    "magus-cli-linux-x64": "7.11.6"
+    "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(() => {
@@ -344,3 +363,306 @@ describe("fastForwardCloneIfPresent — single-clone helper (shared with claude-
 		expect(readPin(dir).pin).toBe("x@dirty");
 	});
 });
+
+/**
+ * Point the clone's origin at a fake ssh that hangs. git pull -> git fetch ->
+ * ssh: the fake ssh is NOT runBounded's direct child, so killing `git pull`
+ * leaves it holding the inherited stdout/stderr open. It records its own pid and
+ * its grandparent's (the `git pull` runBounded spawned) so the case can check
+ * them and the cleanup can kill them by pid, never by pattern.
+ */
+function hangSshTransport(dir: string): { sshPid: string; pullPid: string } {
+	const sshPid = path.join(tmp, "fake-ssh.pid");
+	const pullPid = path.join(tmp, "git-pull.pid");
+	const fakeSsh = path.join(tmp, "fake-ssh.sh");
+	fs.writeFileSync(
+		fakeSsh,
+		[
+			"#!/bin/sh",
+			`echo $$ > '${sshPid}'`,
+			`ps -o ppid= -p $PPID | tr -d ' ' > '${pullPid}'`,
+			`ps -o command= -p "$(cat '${pullPid}')" > '${pullPid}.cmd'`,
+			"exec sleep 60",
+			"",
+		].join("\n"),
+		{ mode: 0o755 },
+	);
+	git(dir, "remote", "set-url", "origin", "ssh://example.invalid/repo.git");
+	git(dir, "config", "core.sshCommand", fakeSsh);
+	hungPidFiles = [sshPid, pullPid];
+	return { sshPid, pullPid };
+}
+
+function readPid(file: string): number {
+	return Number(fs.readFileSync(file, "utf8").trim());
+}
+
+/** True once `pid` no longer exists, polling briefly to let the runtime reap it. */
+async function goneWithin(pid: number, ms: number): Promise<boolean> {
+	const until = Date.now() + ms;
+	for (;;) {
+		try {
+			process.kill(pid, 0);
+		} catch {
+			return true;
+		}
+		if (Date.now() > until) return false;
+		await Bun.sleep(20);
+	}
+}
+
+// pid files written by hangSshTransport; killed by pid after each case.
+let hungPidFiles: string[] = [];
+
+afterEach(() => {
+	for (const file of hungPidFiles) {
+		if (!fs.existsSync(file)) continue;
+		const pid = readPid(file);
+		if (pid > 0) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				// already gone
+			}
+		}
+	}
+	hungPidFiles = [];
+});
+
+describe("fastForwardCloneIfPresent — a hung ssh transport", () => {
+	// REGRESSION: magus update stalls on the marketplaces step past the 30 s git timeout (ssh grandchild holds the pipes) — Fixed in /dev:fix session dev-fix-20261102-160435-22278 (MTL-365)
+	it("settles as 'failed' near the 30 s git timeout when ssh (a grandchild of git pull) holds the pipes", async () => {
+		const dir = installClone("magus");
+		hangSshTransport(dir);
+
+		const started = Date.now();
+		const status = await fastForwardCloneIfPresent("magus");
+		const elapsed = Date.now() - started;
+
+		expect(status).toBe("failed");
+		// 30 s timeout + grace. On the bug it settles only when ssh exits (~60 s).
+		expect(elapsed).toBeLessThan(40_000);
+		expect(fs.existsSync(dir)).toBe(true);
+	}, 45_000);
+});
+
+describe("fastForwardCloneIfPresent — per-clone deadline", () => {
+	// REGRESSION: the marketplaces step ran 56 min — a per-clone deadline bounds it whatever hangs (MTL-365)
+	it("returns 'failed' at the deadline while ssh still hangs, clone intact", async () => {
+		const dir = installClone("magus");
+		hangSshTransport(dir);
+
+		const started = Date.now();
+		const status = await fastForwardCloneIfPresent("magus", 1_000);
+		const elapsed = Date.now() - started;
+
+		expect(status).toBe("failed");
+		// Deadline 1 s plus slack. Without the deadline it settles at the 30 s git timeout.
+		expect(elapsed).toBeLessThan(3_000);
+		expect(fs.existsSync(dir)).toBe(true);
+	}, 10_000);
+
+	it("kills the in-flight git pull when the deadline wins, rather than leaving it running", async () => {
+		const dir = installClone("magus");
+		const { pullPid } = hangSshTransport(dir);
+
+		const status = await fastForwardCloneIfPresent("magus", 1_000);
+
+		expect(status).toBe("failed");
+		// The fake ssh got far enough to record its grandparent, the git pull.
+		expect(fs.existsSync(pullPid)).toBe(true);
+		expect(fs.readFileSync(`${pullPid}.cmd`, "utf8")).toContain("pull");
+		// Without the abort, git pull lives on until its own 30 s timeout.
+		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/__tests__/spawn-bounded.test.ts

@@ -0,0 +1,211 @@
+/**
+ * runBounded settles on its deadline even when a descendant of the child keeps
+ * the stdout/stderr pipes open — the shape of `git pull` -> `git fetch` -> `ssh`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runBounded } from "../utils/spawn-bounded.js";
+
+let tmp: string;
+let pidFile: string;
+
+beforeEach(() => {
+	tmp = fs.mkdtempSync(path.join(os.tmpdir(), "spawn-bounded-"));
+	pidFile = path.join(tmp, "grandchild.pid");
+});
+
+afterEach(() => {
+	// Kill the leftover grandchild by pid, never by pattern.
+	if (fs.existsSync(pidFile)) {
+		const pid = Number(fs.readFileSync(pidFile, "utf8").trim());
+		if (pid > 0) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				// already gone
+			}
+		}
+	}
+	fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+function writeScript(name: string, body: string): string {
+	const file = path.join(tmp, name);
+	fs.writeFileSync(file, `#!/bin/sh\n${body}`, { mode: 0o755 });
+	return file;
+}
+
+/**
+ * `sh -c` argv: background a `sleep 30` that inherits stdout, then exit 0.
+ * Run through /bin/sh rather than a freshly written script: macOS's first exec
+ * of a new file can take ~300 ms, which would push the exit past a 200 ms
+ * deadline and turn a normal exit into a timeout.
+ */
+function exitLeavingHolder(): string[] {
+	return ["-c", `sleep 30 & echo $! > '${pidFile}'; exit 0`];
+}
+
+describe("runBounded", () => {
+	it("settles at the deadline while a grandchild still holds the pipes", async () => {
+		const script = writeScript(
+			"holder.sh",
+			`sleep 30 &\necho $! > '${pidFile}'\nwait\n`,
+		);
+
+		const started = Date.now();
+		const r = await runBounded(script, [], { timeoutMs: 300 });
+		const elapsed = Date.now() - started;
+
+		expect(r.timedOut).toBe(true);
+		expect(r.signal).toBe("SIGKILL");
+		expect(r.code).not.toBe(0);
+		expect(elapsed).toBeLessThan(2_000);
+	}, 5_000);
+
+	it("settles at the deadline with stdout-only pipes, too", async () => {
+		const script = writeScript(
+			"holder.sh",
+			`sleep 30 &\necho $! > '${pidFile}'\nwait\n`,
+		);
+
+		const started = Date.now();
+		const r = await runBounded(script, [], {
+			timeoutMs: 300,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+
+		expect(r.timedOut).toBe(true);
+		expect(r.signal).toBe("SIGKILL");
+		expect(Date.now() - started).toBeLessThan(2_000);
+	}, 5_000);
+
+	it("returns the full stdout of a child that exits normally", async () => {
+		const lines = Array.from({ length: 2000 }, (_, i) => `line ${i}`);
+		const script = writeScript(
+			"talker.sh",
+			`i=0\nwhile [ $i -lt 2000 ]; do echo "line $i"; i=$((i+1)); done\necho oops >&2\n`,
+		);
+
+		const r = await runBounded(script, [], { timeoutMs: 5_000 });
+
+		expect(r.code).toBe(0);
+		expect(r.signal).toBeNull();
+		expect(r.timedOut).toBe(false);
+		expect(r.spawnError).toBeUndefined();
+		expect(r.stdout).toBe(`${lines.join("\n")}\n`);
+		expect(r.stderr.trim()).toBe("oops");
+	}, 5_000);
+
+	it("reports a non-zero exit code without timing out", async () => {
+		const script = writeScript("fail.sh", "exit 3\n");
+
+		const r = await runBounded(script, [], { timeoutMs: 5_000 });
+
+		expect(r.code).toBe(3);
+		expect(r.timedOut).toBe(false);
+	}, 5_000);
+
+	it("after a normal exit with a background descendant holding stdout, settles after the close grace", async () => {
+		const started = Date.now();
+		const r = await runBounded("/bin/sh", exitLeavingHolder(), {
+			timeoutMs: 20_000,
+		});
+		const elapsed = Date.now() - started;
+
+		expect(r.timedOut).toBe(false);
+		expect(r.code).toBe(0);
+		// CLOSE_GRACE_MS is 1_500: not before it, and not much after it.
+		expect(elapsed).toBeGreaterThanOrEqual(1_400);
+		expect(elapsed).toBeLessThan(2_500);
+	}, 5_000);
+
+	it("never extends a normal exit's close grace past the deadline", async () => {
+		const started = Date.now();
+		const r = await runBounded("/bin/sh", exitLeavingHolder(), {
+			timeoutMs: 200,
+		});
+		const elapsed = Date.now() - started;
+
+		// The child exited by itself, so this is not a timeout.
+		expect(r.timedOut).toBe(false);
+		expect(r.code).toBe(0);
+		// Deadline 200 ms; the 1_500 ms grace must not outlive it.
+		expect(elapsed).toBeLessThan(700);
+	}, 5_000);
+
+	it("an abort mid-run kills the child and settles at once", async () => {
+		const script = writeScript(
+			"sleeper.sh",
+			`echo $$ > '${pidFile}'\nexec sleep 30\n`,
+		);
+		const controller = new AbortController();
+
+		const started = Date.now();
+		const pending = runBounded(script, [], {
+			timeoutMs: 20_000,
+			signal: controller.signal,
+		});
+		// Abort once the child is really running (it has written its pid).
+		while (!fs.existsSync(pidFile) || !fs.readFileSync(pidFile, "utf8")) {
+			await Bun.sleep(10);
+		}
+		const pid = Number(fs.readFileSync(pidFile, "utf8").trim());
+		const abortedAt = Date.now();
+		controller.abort();
+		const r = await pending;
+		const settledAfterAbort = Date.now() - abortedAt;
+
+		expect(r.aborted).toBe(true);
+		expect(r.code).not.toBe(0);
+		expect(settledAfterAbort).toBeLessThan(300);
+		expect(Date.now() - started).toBeLessThan(2_000);
+
+		// The child is dead. Poll briefly: a SIGKILLed child is a zombie until the
+		// runtime reaps it, and signal 0 still succeeds on a zombie.
+		const dead = async (): Promise<boolean> => {
+			for (let i = 0; i < 50; i++) {
+				try {
+					process.kill(pid, 0);
+				} catch {
+					return true;
+				}
+				await Bun.sleep(20);
+			}
+			return false;
+		};
+		expect(await dead()).toBe(true);
+	}, 5_000);
+
+	it("an already-aborted signal settles at once and spawns nothing", async () => {
+		const marker = path.join(tmp, "ran");
+		const script = writeScript("marker.sh", `touch '${marker}'\n`);
+		const controller = new AbortController();
+		controller.abort();
+
+		const started = Date.now();
+		const r = await runBounded(script, [], {
+			timeoutMs: 5_000,
+			signal: controller.signal,
+		});
+		const elapsed = Date.now() - started;
+
+		expect(r.aborted).toBe(true);
+		expect(r.code).toBeNull();
+		expect(elapsed).toBeLessThan(100);
+		// Give a spawned child every chance to run before checking it did not.
+		await Bun.sleep(300);
+		expect(fs.existsSync(marker)).toBe(false);
+	}, 5_000);
+
+	it("settles with spawnError, never throws, for a command that does not exist", async () => {
+		const r = await runBounded(path.join(tmp, "no-such-command"), [], {
+			timeoutMs: 5_000,
+		});
+
+		expect(r.spawnError).toBeInstanceOf(Error);
+		expect(r.timedOut).toBe(false);
+	}, 5_000);
+});

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)