magus-cli 7.11.7 → 7.12.0

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/data/alias-flags.ts

@@ -72,6 +72,18 @@ export interface AliasFlag {
 	 * token. See `TEMPLATE_TOKENS` for the supported placeholder set.
 	 */
 	templated?: boolean;
+	/**
+	 * Environment assignment (`NAME=VALUE`) the alias sets before `claude`,
+	 * instead of an argv token. Only for `kind: "boolean"`: enabled emits the
+	 * assignment, disabled emits nothing. `flag` carries the same string so
+	 * lookups by `flag` keep working.
+	 */
+	env?: string;
+	/**
+	 * Value check for `kind: "text"` flags, run when the user enters a value.
+	 * Returns null when the value is valid, otherwise the reason it is not.
+	 */
+	validateValue?: (value: string) => string | null;
 	/** UI grouping; rendered as section headers in the list. */
 	group: FlagGroup;
 }
@@ -100,7 +112,8 @@ export type FlagGroup =
 	| "channels"
 	| "debug"
 	| "integration"
-	| "worktree";
+	| "worktree"
+	| "agents";
 
 export const FLAG_GROUPS: Array<{ id: FlagGroup; label: string }> = [
 	{ id: "danger", label: "Permissions" },
@@ -110,8 +123,81 @@ export const FLAG_GROUPS: Array<{ id: FlagGroup; label: string }> = [
 	{ id: "debug", label: "Debug" },
 	{ id: "integration", label: "Integrations" },
 	{ id: "worktree", label: "Worktree" },
+	{ id: "agents", label: "Agent teams" },
 ];
 
+/** Smallest auto-compact window Claude Code accepts, in tokens. */
+export const AUTOCOMPACT_MIN_TOKENS = 100_000;
+/** Largest auto-compact window Claude Code accepts, in tokens. */
+export const AUTOCOMPACT_MAX_TOKENS = 1_000_000;
+
+/** Claude Code's own wording when it refuses an `--autocompact` value. */
+export const AUTOCOMPACT_INVALID_REASON =
+	"It must be 'auto', or between 100k and 1M (e.g. 500k, 200000, or 200 as shorthand)";
+
+const EXPONENT_NUMBER = /^[+-]?(\d+(\.\d*)?|\.\d+)[eE][+-]?\d+$/;
+const GROUPED_DIGITS = /^[+-]?\d{1,3}([_,   ])\d{3}(?:\1\d{3})*$/;
+const DIGIT_SEPARATORS = /[_,   ]/g;
+
+/**
+ * Read an unsuffixed number the way Claude Code does: exponent notation
+ * (`2e5`) when it is an integer, digit groups (`200,000`, `200_000`), and
+ * otherwise `parseInt`, which keeps the leading digits of the string.
+ */
+function parsePlainNumber(text: string): number {
+	if (text.length <= 32) {
+		if (EXPONENT_NUMBER.test(text)) {
+			const n = Number(text);
+			return Number.isInteger(n) ? n : Number.NaN;
+		}
+		if (GROUPED_DIGITS.test(text)) {
+			return Number.parseInt(text.replace(DIGIT_SEPARATORS, ""), 10);
+		}
+	}
+	return Number.parseInt(text, 10);
+}
+
+/**
+ * Parse an `--autocompact` value exactly as Claude Code's option parser does.
+ *
+ * `auto` (any case) stays `"auto"`. A trailing `k` or `m` multiplies by a
+ * thousand or a million; an unsuffixed number from 100 to 1000 is read as
+ * thousands (`200` is 200,000 tokens). The result must fall between
+ * {@link AUTOCOMPACT_MIN_TOKENS} and {@link AUTOCOMPACT_MAX_TOKENS}.
+ *
+ * Returns the token count, `"auto"`, or `undefined` when Claude Code would
+ * refuse the value.
+ */
+export function parseAutocompactSize(
+	value: string,
+): number | "auto" | undefined {
+	if (value.trim().toLowerCase() === "auto") return "auto";
+	const text = value.trim();
+	const suffix = text.slice(-1).toLowerCase();
+	const multiplier =
+		suffix === "m" ? 1_000_000 : suffix === "k" ? 1_000 : undefined;
+	const parsed =
+		multiplier === undefined
+			? parsePlainNumber(text)
+			: Number.parseFloat(text) * multiplier;
+	const tokens =
+		multiplier === undefined && parsed >= 100 && parsed <= 1000
+			? parsed * 1000
+			: parsed;
+	if (Number.isNaN(tokens) || tokens < 1) return undefined;
+	if (tokens < AUTOCOMPACT_MIN_TOKENS || tokens > AUTOCOMPACT_MAX_TOKENS) {
+		return undefined;
+	}
+	return Math.round(tokens);
+}
+
+/** `validateValue` for the context window size: Claude Code's reason, or null. */
+export function validateAutocompactSize(value: string): string | null {
+	return parseAutocompactSize(value) === undefined
+		? AUTOCOMPACT_INVALID_REASON
+		: null;
+}
+
 export const ALIAS_FLAGS: AliasFlag[] = [
 	{
 		id: "dangerously-skip-permissions",
@@ -222,6 +308,16 @@ export const ALIAS_FLAGS: AliasFlag[] = [
 		description:
 			"Path to a file whose contents are appended to the default system prompt.",
 	},
+	{
+		id: "autocompact",
+		label: "Context window size",
+		flag: "--autocompact",
+		kind: "text",
+		group: "context",
+		validateValue: validateAutocompactSize,
+		description:
+			"The window size Claude Code compacts the conversation at: auto, or 100k to 1M tokens (e.g. 200k, 500k, 1m, 200000, or 200 as shorthand for 200k).",
+	},
 	{
 		id: "channels",
 		label: "Channels (approved)",
@@ -291,6 +387,32 @@ export const ALIAS_FLAGS: AliasFlag[] = [
 			{ label: "classic", value: "classic" },
 		],
 	},
+	{
+		id: "agent-teams",
+		label: "Agent teams",
+		flag: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
+		env: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
+		kind: "boolean",
+		group: "agents",
+		description:
+			"Turn on agent teams, so the session can start teammates. Claude Code has no flag for this: the alias sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 before claude.",
+	},
+	{
+		id: "teammate-mode",
+		label: "Teammate panes",
+		flag: "--teammate-mode",
+		kind: "select",
+		group: "agents",
+		requires: "agent-teams",
+		description:
+			"Where teammates run. tmux opens each teammate in a split pane, but only when the session starts inside tmux. iterm2 uses iTerm2 panes, in-process keeps them in this terminal, auto picks for you. Requires agent teams.",
+		options: [
+			{ label: "tmux", value: "tmux" },
+			{ label: "iterm2", value: "iterm2" },
+			{ label: "in-process", value: "in-process" },
+			{ label: "auto", value: "auto" },
+		],
+	},
 ];
 
 /** Look up a flag by id. Throws if missing — keeps callers honest. */

package/src/services/alias-shell-writer.ts

@@ -125,6 +125,8 @@ export function renderArgs(config: AliasConfig): Segment[] {
 	const seenXor = new Set<string>();
 
 	for (const flag of ALIAS_FLAGS) {
+		// Env flags are assignments before `claude`, never argv: see renderEnv.
+		if (flag.env) continue;
 		if (flag.requires) {
 			const dep = config.flags[flag.requires];
 			if (!isFlagEnabled(dep)) continue;
@@ -154,18 +156,35 @@ export function renderArgs(config: AliasConfig): Segment[] {
 }
 
 /**
- * Convenience: render each segment to its literal-token approximation.
- * Composite segments are stringified by joining their literal parts with
- * `<sub>` placeholders for raw parts. Used by tests and validation summaries
- * where the actual shell substitution doesn't matter.
+ * The environment assignments (`NAME=VALUE`) the alias sets before `claude`,
+ * one per enabled env flag, in catalog order. `requires` applies here as it
+ * does to argv flags. Pure function.
+ */
+export function renderEnv(config: AliasConfig): string[] {
+	const out: string[] = [];
+	for (const flag of ALIAS_FLAGS) {
+		if (!flag.env) continue;
+		if (flag.requires && !isFlagEnabled(config.flags[flag.requires])) continue;
+		if (isFlagEnabled(config.flags[flag.id])) out.push(flag.env);
+	}
+	return out;
+}
+
+/**
+ * Convenience: the whole command after the alias name as literal tokens, env
+ * assignments first, then argv. Composite segments are stringified by joining
+ * their literal parts with `<sub>` placeholders for raw parts. Used by the
+ * adoption fixpoint check, tests and validation summaries, where the actual
+ * shell substitution doesn't matter.
  */
 export function renderArgsAsTokens(config: AliasConfig): string[] {
-	return renderArgs(config).map((seg) => {
+	const argv = renderArgs(config).map((seg) => {
 		if (seg.kind === "literal") return seg.text;
 		return seg.parts
 			.map((p) => (p.kind === "literal" ? p.text : `<${p.posix}>`))
 			.join("");
 	});
+	return [...renderEnv(config), ...argv];
 }
 
 function isFlagEnabled(value: FlagValue | undefined): boolean {
@@ -345,24 +364,32 @@ export function renderAlias(
 	shell: ShellKind,
 ): RenderedAlias {
 	const args = renderArgs(config);
+	const env = renderEnv(config);
 	const name = config.aliasName;
 	if (shell === "fish") {
-		return { shell, block: renderFishBlock(name, args) };
+		return { shell, block: renderFishBlock(name, env, args) };
 	}
-	return { shell, block: renderPosixBlock(name, args) };
+	return { shell, block: renderPosixBlock(name, env, args) };
 }
 
-function renderPosixBlock(name: string, segments: Segment[]): string {
+function renderPosixBlock(
+	name: string,
+	env: string[],
+	segments: Segment[],
+): string {
 	// The alias body lives inside outer single quotes:
-	//   alias <name>='claude … '
-	// Each segment becomes one shell-arg inside that body. Composite segments
+	//   alias <name>='NAME=VALUE claude … '
+	// Env assignments lead, so the shell exports them to `claude` alone. Each
+	// segment becomes one shell-arg inside that body. Composite segments
 	// (templated values) interleave literal text with double-quoted shell
 	// substitutions via close-outer + double-quote + reopen-outer.
+	const prefix =
+		env.length === 0 ? "" : `${env.map(quoteInsidePosixAlias).join(" ")} `;
 	const body =
 		segments.length === 0
 			? ""
 			: ` ${segments.map(renderPosixSegment).join(" ")}`;
-	const line = `alias ${name}='claude${body}'`;
+	const line = `alias ${name}='${prefix}claude${body}'`;
 	return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
 }
 
@@ -425,13 +452,22 @@ export function findUnquotableTokens(segments: Segment[]): string[] {
 	return out;
 }
 
-function renderFishBlock(name: string, segments: Segment[]): string {
+function renderFishBlock(
+	name: string,
+	env: string[],
+	segments: Segment[],
+): string {
 	// Fish: `alias <name> 'claude --foo bar'` — outer single quotes, no `=`.
+	// Env assignments go through `env NAME=VALUE claude …`: the bare
+	// `NAME=VALUE cmd` form needs fish 3.1, `env` works on every version. The
+	// assignments are catalog constants of `[A-Za-z0-9_=]`, so they need no
+	// quoting inside the outer single quotes.
+	const prefix = env.length === 0 ? "" : `env ${env.join(" ")} `;
 	const body =
 		segments.length === 0
 			? ""
 			: ` ${segments.map(renderFishSegment).join(" ")}`;
-	const line = `alias ${name} 'claude${body}'`;
+	const line = `alias ${name} '${prefix}claude${body}'`;
 	return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
 }
 
@@ -604,9 +640,33 @@ export function validateConfig(config: AliasConfig): FlagValidationIssue[] {
 
 export interface ParseResult {
 	aliasName: string | null;
+	/**
+	 * The env assignments before `claude` (`NAME=VALUE`), then the argv after
+	 * it — the shape {@link argsToFlagValuesWithLeftovers} reads.
+	 */
 	args: string[];
 }
 
+/** A shell environment assignment token: `NAME=VALUE`. */
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/**
+ * Split an alias command into the tokens {@link argsToFlagValuesWithLeftovers}
+ * reads: leading env assignments, then the argv after `claude`. Accepts the
+ * POSIX `NAME=VALUE claude …` form and the `env NAME=VALUE claude …` form the
+ * fish renderer writes. Returns null when the command is not `claude`.
+ */
+function commandTokensAfterEnv(tokens: string[]): string[] | null {
+	let i = tokens[0] === "env" ? 1 : 0;
+	const env: string[] = [];
+	while (i < tokens.length && ENV_ASSIGNMENT_RE.test(tokens[i])) {
+		env.push(tokens[i]);
+		i += 1;
+	}
+	if (tokens[i] !== "claude") return null;
+	return [...env, ...tokens.slice(i + 1)];
+}
+
 /**
  * Find the managed block in shell rc text, parse the alias line, and return
  * the alias name plus the argv tokens after `claude`.
@@ -644,10 +704,11 @@ export function parseAliasLine(line: string): ParseResult | null {
 	const match = ALIAS_LINE_RE.exec(line);
 	if (!match) return null;
 	const [, aliasName, body] = match;
-	// First token is the command itself (claude). Drop it; we only want argv.
-	const tokens = tokenizePosixAliasBody(body);
-	if (tokens.length === 0 || tokens[0] !== "claude") return null;
-	return { aliasName, args: tokens.slice(1) };
+	// The command is `claude`, optionally preceded by env assignments. Drop
+	// `claude` itself; keep the assignments ahead of the argv.
+	const args = commandTokensAfterEnv(tokenizePosixAliasBody(body));
+	if (!args) return null;
+	return { aliasName, args };
 }
 
 /**
@@ -793,13 +854,25 @@ export interface ParsedFlagsWithLeftovers {
  * catalog flag. Unknown `--flag value` pairs contribute BOTH tokens to
  * `leftovers` (the flag and its consumed value) so the adoption gate sees the
  * full extent of what wouldn't round-trip.
+ *
+ * Leading `NAME=VALUE` tokens are the env assignments set before `claude`.
+ * Each matches an env flag by its assignment string; an assignment the
+ * catalog does not know lands in `leftovers` on its own, so adoption never
+ * removes a line it cannot reproduce. Env flags are matched only in that
+ * leading run, never among the argv after it.
  */
 export function argsToFlagValuesWithLeftovers(
 	args: string[],
 ): ParsedFlagsWithLeftovers {
-	// Index every flag by its primary `flag` string AND its triStateOff variant.
+	// Index argv flags by their primary `flag` string AND their triStateOff
+	// variant, and env flags by their assignment string.
 	const byFlag = new Map<string, { flag: AliasFlag; off?: boolean }>();
+	const byEnv = new Map<string, AliasFlag>();
 	for (const flag of ALIAS_FLAGS) {
+		if (flag.env) {
+			byEnv.set(flag.env, flag);
+			continue;
+		}
 		byFlag.set(flag.flag, { flag, off: false });
 		if (flag.triStateOff) {
 			byFlag.set(flag.triStateOff, { flag, off: true });
@@ -809,6 +882,12 @@ export function argsToFlagValuesWithLeftovers(
 	const out: Record<string, FlagValue> = {};
 	const leftovers: string[] = [];
 	let i = 0;
+	while (i < args.length && ENV_ASSIGNMENT_RE.test(args[i])) {
+		const envFlag = byEnv.get(args[i]);
+		if (envFlag) out[envFlag.id] = { kind: "boolean", enabled: true };
+		else leftovers.push(args[i]);
+		i += 1;
+	}
 	while (i < args.length) {
 		const tok = args[i];
 		const entry = byFlag.get(tok);
@@ -1122,9 +1201,9 @@ function parseAdoptableLine(
 	if (!match) return null;
 	const [, name, , body] = match;
 	const tokens = tokenizeGeneralAliasBody(body);
-	if (!tokens || tokens.length === 0 || tokens[0] !== "claude") return null;
-
-	const args = tokens.slice(1);
+	if (!tokens) return null;
+	const args = commandTokensAfterEnv(tokens);
+	if (!args) return null;
 	const { flags, leftovers } = argsToFlagValuesWithLeftovers(args);
 
 	// Fixpoint: render the parsed flags back to tokens and re-parse. If the

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();
 }
 
 /**