one-code-extension 0.1.3 → 0.3.0

package/extensions/plan-mode/index.ts

@@ -1,41 +1,68 @@
 /**
  * plan-mode extension — Claude Code's EnterPlanMode / ExitPlanMode tools,
- * file-based: the plan lives at ~/.one-code/plans/<slug>.md, the one path plan
+ * file-based: the plan lives at ~/.onecode/plans/<slug>.md, the one path plan
  * mode may write. The path is announced to the model in an every-turn reminder
  * and to the permissions extension over the event bus, and exit_plan_mode
  * reads the file rather than taking the plan as a parameter.
  *
  * Mode state is owned by the permissions extension; this extension requests
  * changes over MODE_CHANNEL and reacts to transitions it observes on
- * PERMISSION_STATUS_CHANNEL (which fires on every setMode). Plan-file
- * allocation happens lazily in before_agent_start — the one hook that covers
- * all three ways into plan mode (the tool, ctrl+q, defaultMode: "plan") and
- * runs after every extension's session_start, so restoring a previous path
- * from the session branch can never race a fresh allocation.
+ * PERMISSION_STATUS_CHANNEL (which fires on every setMode). The plan block is
+ * (re)installed at two points: synchronously on the transition INTO plan mode
+ * (the status handler, with the last context seen), so a ctrl+q during a long
+ * turn puts the block on the queue before the turn's next request — until
+ * 2026-09-05 the mid-turn requests ran with no plan reminder while every edit
+ * was denied "see the plan-mode reminder" (STEERING-REVIEW-2026-09-05 M3) —
+ * and on before_agent_start, which covers a session that STARTS in plan mode
+ * before this extension has seen a context (defaultMode: "plan"; permissions'
+ * session_start runs first) and runs after every extension's session_start,
+ * so restoring a previous path from the session branch never races a fresh
+ * allocation.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { oneCodeStateDir } from "../lib/paths.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
 import { ccToolRenderers, safeThemePaint } from "../lib/tui-render.ts";
+import type { PermissionMode } from "../permissions/matcher.ts";
 import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
 import { buildPlanModeReminder } from "./reminder.ts";
 import { randomSlug } from "./slug.ts";
-import { clampOffset, decodeViewerKey, type PlanChoice, renderPlanViewer, wrapPlanText } from "./viewer.ts";
+import { clampOffset, decodeViewerKey, initialPlanChoice, type PlanChoice, renderPlanViewer, wrapPlanText } from "./viewer.ts";
 
-export const MODE_CHANNEL = "one-code:set-permission-mode";
-/** Announces plan mode's one writable file; the permissions matcher consumes it. */
-export const PLAN_FILE_CHANNEL = "one-code:plan-file-path";
+import { MODE_CHANNEL, PLAN_FILE_CHANNEL } from "../lib/plan-mode-channels.ts";
+export { MODE_CHANNEL, PLAN_FILE_CHANNEL };
 /** Session entry type persisting the allocated path across resume/branch. */
-const PLAN_FILE_ENTRY = "plan-mode-file";
+const PLAN_FILE_ENTRY = "one-code:plan-mode-file";
 
 const PLANS_DIR = () => join(oneCodeStateDir(), "plans");
 
+/** How each mode is named in the approval choices. */
+const MODE_NAMES: Record<PermissionMode, string> = {
+	default: "manual approvals",
+	acceptEdits: "auto-accept edits",
+	plan: "plan mode",
+	auto: "auto mode",
+	bypassPermissions: "bypass permissions",
+	dontAsk: "dontAsk",
+};
+
 export default function planModeExtension(pi: ExtensionAPI) {
-	let currentMode = "default";
+	/** The last mode broadcast by permissions; undefined until the first status arrives. */
+	let currentMode: string | undefined;
+	/**
+	 * The mode the session was in when it entered plan mode, offered first on
+	 * exit (Claude Code's ExitPlanMode restores `prePlanMode`). Unknown for a
+	 * session that STARTED in plan mode — the first status seen is plan itself —
+	 * so that session gets the fixed list. Until 2026-09-05 the exit could only
+	 * escalate: a default-mode session that planned was offered auto
+	 * (PERMISSIONS-REVIEW-2026-09-05 M4).
+	 */
+	let modeBeforePlan: PermissionMode | undefined;
 	let planFilePath: string | undefined;
 
 	/** Restore the branch's plan file, else allocate a fresh slug. */
@@ -63,18 +90,37 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		const path = ensurePlanFile(ctx);
 		pi.events.emit(PLAN_FILE_CHANNEL, { path });
 		pi.events.emit(REMINDER_CHANNEL, {
-			text: buildPlanModeReminder({ filePath: path, fileExists: existsSync(path) }),
+			text: buildPlanModeReminder(path),
 			scope: "every-turn",
 			key: "permission-mode",
+			placement: "sticky-append",
 		});
 	};
 
+	/** The last context seen, for a refresh triggered off the bus (no ctx of its own). */
+	let lastCtx: ExtensionContext | undefined;
+
 	pi.events.on(PERMISSION_STATUS_CHANNEL, (data) => {
 		const status = data as PermissionStatus;
-		if (typeof status?.mode === "string") currentMode = status.mode;
+		if (typeof status?.mode !== "string") return;
+		const previous = currentMode;
+		currentMode = status.mode;
+		if (currentMode === "plan" && previous !== "plan") modeBeforePlan = previous as PermissionMode | undefined;
+		// Entering plan mode mid-turn: permissions' setMode has just dropped the
+		// shared "permission-mode" key (before broadcasting this status, so this
+		// re-add is not undone) and will announce the change on the next tool
+		// result; the standing block has to be back on the queue for that same
+		// request. The path is announced over PLAN_FILE_CHANNEL inside refresh,
+		// synchronously, so setMode's announcement can name it.
+		if (currentMode === "plan" && previous !== "plan" && lastCtx) refresh(lastCtx);
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		lastCtx = ctx;
 	});
 
 	pi.on("before_agent_start", (_event, ctx) => {
+		lastCtx = ctx;
 		if (currentMode === "plan") refresh(ctx);
 	});
 
@@ -83,16 +129,16 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		label: "Enter plan mode",
 		...ccToolRenderers("Enter plan mode"),
 		description:
-			"Enter plan mode for tasks that need investigation and design before changing anything. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally. Use for non-trivial multi-file work; skip it for simple direct changes.",
-		promptSnippet: "Switch to read-only planning before non-trivial changes",
+			"Enter plan mode: read-only investigation to design an approach before changing anything. Most tasks do not need it.\n" +
+			"For a small or clearly-scoped change, act directly instead. Enter plan mode only for multi-file work whose design is genuinely unclear, or when the user asks for a plan. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally.",
 		parameters: Type.Object({}),
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			pi.events.emit(MODE_CHANNEL, { mode: "plan" });
-			// setMode fires synchronously over the status channel, so currentMode
-			// is already "plan"; announce the file in the tool result too so the
-			// model can start writing this same turn.
+			// setMode broadcasts synchronously over the status channel, so the
+			// listener above has already installed the block and announced the
+			// path (or the mode was plan already and both stand); name the file in
+			// the tool result too so the model can start writing this same turn.
 			const path = ensurePlanFile(ctx);
-			refresh(ctx);
 			return {
 				content: [
 					{
@@ -110,8 +156,8 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		label: "Exit plan mode",
 		...ccToolRenderers("Exit plan mode"),
 		description:
-			"Signal that planning is complete and ask the user to approve the plan. Takes no parameters: the plan is read from the plan file named in the plan-mode reminder, which you must have written before calling this. The user reviews that file's contents.",
-		promptSnippet: "Present your plan file for user approval",
+			"Signal that planning is complete and ask the user to approve the plan.\n" +
+			"Takes no parameters: the plan is read from the plan file named in the plan-mode reminder, which you must have written before calling this. The user reviews that file's contents.",
 		parameters: Type.Object({}),
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			// Guard the out-of-sequence call: without this, a cold exit_plan_mode
@@ -145,45 +191,93 @@ export default function planModeExtension(pi: ExtensionAPI) {
 				};
 			}
 
+			// Plan approval is the user's: with no UI there is no one to approve, and
+			// until 2026-09-05 the model exited plan mode by itself here — a
+			// `-p --permission-mode plan` run was read-only in name only, since the
+			// user's allow rules applied the moment the mode became default
+			// (PERMISSIONS-REVIEW-2026-09-05 M4, measured: `git add -A` ran). The
+			// session stays in plan mode; the plan file is the run's product.
 			if (!ctx.hasUI) {
-				pi.events.emit(MODE_CHANNEL, { mode: "default" });
 				return {
 					content: [
-						{ type: "text", text: "Non-interactive session: plan recorded and plan mode exited. Proceed." },
+						{
+							type: "text",
+							text: `Plan approval needs an interactive session, and this one has no user to approve it. The session stays in plan mode; the plan is recorded at ${path} for the user to review. Do not try to implement it here.`,
+						},
 					],
-					details: { plan, approved: true },
+					details: { planFilePath: path, plan, approved: false },
+					isError: true,
 				};
 			}
 
+			// The mode the session was in before planning leads the list (Claude
+			// Code restores it), then auto mode when a classifier model is reachable —
+			// the same gate the mode cycle uses (permissions/index.ts autoInCycle) —
+			// and the fixed choices. Each approving choice carries the mode it
+			// switches to; the final "Keep planning" choice has none and leaves the
+			// session in plan mode.
+			const autoAvailable = ctx.modelRegistry.getAvailable().length > 0;
+			const restore = modeBeforePlan && (modeBeforePlan !== "auto" || autoAvailable) ? modeBeforePlan : undefined;
+			const fixedModes: PermissionMode[] = [...(autoAvailable ? (["auto"] as const) : []), "acceptEdits", "default"];
+			const options: { label: string; mode?: PermissionMode; restore?: boolean }[] = [
+				...(restore ? [{ label: `Approve — back to ${MODE_NAMES[restore]} (the mode before planning)`, mode: restore, restore: true }] : []),
+				...fixedModes.filter((mode) => mode !== restore).map((mode) => ({ label: `Approve — ${MODE_NAMES[mode]}`, mode })),
+				{ label: "Keep planning" },
+			];
+			const choices = options.map((o) => o.label);
+
 			const choice = await ctx.ui.custom<PlanChoice | null>((tui, theme, _keybindings, done) => {
 				const paint = safeThemePaint(theme);
 				const maxVisible = 12;
 				let offset = 0;
-				let selected: PlanChoice = 0;
+				let selected: PlanChoice = initialPlanChoice(options);
 				let lineCount = 0;
+				// The dialog stays open while exit_plan_mode runs, so pi's working
+				// spinner drives ~8 frames a second — and re-wrapping the whole plan
+				// each frame burned 5–17 ms on a long plan (TUI-REVIEW M1). The plan
+				// is immutable for the dialog's life: wrap once per width, and cache
+				// the rendered frame by (width, offset, selected) so a steady frame
+				// costs nothing. invalidate() (theme swap) drops both.
+				// Only one width is ever live at a time (a resize is the only thing that
+				// changes it), so a single-slot memo is enough — like the model picker's.
+				let wrapped: { width: number; lines: string[] } | undefined;
+				let frame: { key: string; lines: string[] } | undefined;
+				const wrapAt = (wrapWidth: number): string[] => {
+					if (wrapped?.width !== wrapWidth) wrapped = { width: wrapWidth, lines: wrapPlanText(plan, wrapWidth) };
+					return wrapped.lines;
+				};
 				return {
 					render: (width: number) => {
-						const lines = wrapPlanText(plan, Math.max(10, width - 1));
+						const lines = wrapAt(Math.max(10, width - 1));
 						lineCount = lines.length;
 						offset = clampOffset(offset, lineCount, maxVisible);
-						return renderPlanViewer({ lines, offset, choice: selected, maxVisible }, paint, width);
+						const key = `${width}:${offset}:${selected}`;
+						if (frame?.key === key) return frame.lines;
+						const rendered = renderPlanViewer({ lines, offset, choice: selected, choices, maxVisible }, paint, width);
+						frame = { key, lines: rendered };
+						return rendered;
 					},
 					handleInput: (data: string) => {
 						const key = decodeViewerKey(data, maxVisible);
 						if (!key) return;
 						if (key.kind === "cancel") return done(null);
 						if (key.kind === "confirm") return done(selected);
-						if (key.kind === "pick") return done(key.index);
+						if (key.kind === "pick") return key.index < options.length ? done(key.index) : undefined;
 						if (key.kind === "scroll") offset = clampOffset(offset + key.delta, lineCount, maxVisible);
-						else if (key.kind === "choice") selected = (((selected + key.delta) % 3) + 3) % 3 as PlanChoice;
+						else if (key.kind === "choice")
+							selected = (((selected + key.delta) % options.length) + options.length) % options.length;
 						tui.requestRender();
 					},
-					invalidate: () => {},
+					invalidate: () => {
+						wrapped = undefined;
+						frame = undefined;
+					},
 				};
 			});
 
-			if (choice === 0 || choice === 1) {
-				pi.events.emit(MODE_CHANNEL, { mode: choice === 1 ? "acceptEdits" : "default" });
+			const picked = choice != null ? options[choice] : undefined;
+			if (picked?.mode) {
+				pi.events.emit(MODE_CHANNEL, { mode: picked.mode });
 				return {
 					content: [
 						{
@@ -206,4 +300,20 @@ export default function planModeExtension(pi: ExtensionAPI) {
 			};
 		},
 	});
+
+	// Claude Code defers both plan-mode tools behind ToolSearch: they are absent
+	// from the wire tool list and its system prompt never mentions plan mode, so
+	// the model must deliberately load them before planning. Keeping them
+	// always-active (with a prompt snippet) read as standing "plan first" policy
+	// to instruction-eager third-party models, which then entered plan mode for
+	// trivial tasks. User-initiated plan mode (mode cycling, defaultMode) is
+	// unaffected — that flows over MODE_CHANNEL, not through these tools.
+	pi.events.emit(DEFER_CHANNEL, {
+		name: "enter_plan_mode",
+		keywords: ["plan", "planning", "design", "approach", "architecture", "investigate", "read-only"],
+	});
+	pi.events.emit(DEFER_CHANNEL, {
+		name: "exit_plan_mode",
+		keywords: ["plan", "approve", "approval", "present", "finish planning"],
+	});
 }

package/extensions/plan-mode/reminder.ts

@@ -1,32 +1,29 @@
 /**
- * Plan-mode reminder text (pure). Byte-identical for a given state so the
- * every-turn re-emit replaces the queue entry with the same string except when
- * the state genuinely changed (file created, different path).
+ * Plan-mode reminder text (pure). Byte-identical for a given plan-file path,
+ * whether or not the file exists yet: the block is a sticky-append reminder
+ * carried by every user message since plan mode came on, and the queue keeps
+ * that anchor only while the re-emitted text is unchanged. A text that flipped
+ * when the file appeared re-anchored the block and re-cached every message
+ * between entering plan mode and the first write (CACHE-REVIEW-2026-09-04 M2).
  *
- * Mirrors Claude Code's plan-mode system message: the plan lives in a file the
- * model builds incrementally — the one writable path in plan mode — and
- * exit_plan_mode reads that file rather than taking the plan as a parameter.
+ * Adapted from Claude Code's plan-mode system message: the plan lives in a
+ * file the model builds incrementally — the one writable path in plan mode —
+ * and exit_plan_mode reads that file rather than taking the plan as a
+ * parameter. Claude Code's own text does vary with the file's existence; ours
+ * folds both states into one sentence so the cached prefix survives.
  */
 
-export interface PlanReminderState {
-	filePath: string;
-	fileExists: boolean;
-}
-
-export function buildPlanModeReminder({ filePath, fileExists }: PlanReminderState): string {
-	const fileLine = fileExists
-		? `Continue building your plan at ${filePath} with the write/edit tools — edit it incrementally rather than rewriting it from scratch.`
-		: `No plan file exists yet — create it at ${filePath} with the write tool. Build the plan there incrementally as you investigate; do not present the plan as chat text.`;
-
+export function buildPlanModeReminder(filePath: string): string {
+	const fileLine = `Build your plan at ${filePath} with the write/edit tools — create it if it does not exist yet, then edit it incrementally rather than rewriting it from scratch. Do not present the plan as chat text.`;
 	return [
 		`Plan mode is active. You may only use read-only tools; edit and write are blocked everywhere except one file. ${fileLine}`,
 		"",
 		"Workflow:",
-		'1. Explore: delegate broad reconnaissance to `subagent` with `agent: "explore"` (up to 3 in parallel) rather than reading everything yourself.',
-		'2. Design: delegate the implementation strategy to `subagent` with `agent: "plan"` once exploration has mapped the ground.',
+		'1. Explore: delegate broad reconnaissance to the `Agent` tool with `subagent_type: "explore"` (up to 3 in parallel) rather than reading everything yourself.',
+		'2. Design: delegate the implementation strategy to the `Agent` tool with `subagent_type: "plan"` once exploration has mapped the ground.',
 		"3. Review the critical files yourself, and call `ask_user_question` for any decision you cannot make on the user's behalf.",
 		`4. Write the final plan to ${filePath}: a Context section explaining why, your recommended approach (not several options), the critical files named, existing utilities to reuse, and a verification section.`,
-		"5. Call `exit_plan_mode` to ask the user to approve the plan. It reads the plan file directly — you do not pass the plan as a parameter.",
+		"5. Call `exit_plan_mode` to ask the user to approve the plan. It reads the plan file directly — you do not pass the plan as a parameter. If `exit_plan_mode` is not in your active tools, load it first with tool_search (`select:exit_plan_mode`).",
 		"",
 		"End every plan-mode turn with either `ask_user_question` or `exit_plan_mode`. Never ask for plan approval in chat text.",
 	].join("\n");

package/extensions/plan-mode/viewer.ts

@@ -10,10 +10,13 @@
  * painting so ANSI escapes never confuse the width accounting.
  */
 
-export const PLAN_CHOICES = ["Approve — manual approvals", "Approve — auto-accept edits", "Keep planning"] as const;
+import { cutPlainText } from "../lib/tui-render.ts";
 
-/** What the dialog resolves to; index into PLAN_CHOICES, or null for cancel. */
-export type PlanChoice = 0 | 1 | 2;
+/** Hard-wrap plain text to `width` columns, preserving blank lines. */
+export { wrapPlainText as wrapPlanText } from "../lib/tui-render.ts";
+
+/** What the dialog resolves to; index into the choices list, or null for cancel. */
+export type PlanChoice = number;
 
 export type ViewerKey =
 	| { kind: "scroll"; delta: number }
@@ -22,7 +25,12 @@ export type ViewerKey =
 	| { kind: "confirm" }
 	| { kind: "cancel" };
 
-/** Decode a raw terminal chunk; `page` is the scroll step for PgUp/PgDn. */
+/**
+ * Decode a raw terminal chunk; `page` is the scroll step for PgUp/PgDn. Digit
+ * keys resolve to a raw 0-based `pick` index; the caller clamps it to the number
+ * of choices actually shown (the list is dynamic — auto mode joins only when a
+ * classifier model is reachable).
+ */
 export function decodeViewerKey(data: string, page: number): ViewerKey | undefined {
 	switch (data) {
 		case "\x1b[A":
@@ -48,36 +56,37 @@ export function decodeViewerKey(data: string, page: number): ViewerKey | undefin
 		case "\x1b":
 		case "\x03": // ctrl+c — same intent as escape while the dialog is focused
 			return { kind: "cancel" };
-		case "1":
-		case "2":
-		case "3":
-			return { kind: "pick", index: (Number(data) - 1) as PlanChoice };
 		default:
+			if (data.length === 1 && data >= "1" && data <= "9") {
+				return { kind: "pick", index: Number(data) - 1 };
+			}
 			return undefined;
 	}
 }
 
-/** Hard-wrap plain text to `width` columns, preserving blank lines. */
-export function wrapPlanText(text: string, width: number): string[] {
-	const columns = Math.max(1, width);
-	const out: string[] = [];
-	for (const raw of text.replace(/\r\n/g, "\n").split("\n")) {
-		const chars = [...raw];
-		if (chars.length === 0) {
-			out.push("");
-			continue;
-		}
-		for (let i = 0; i < chars.length; i += columns) {
-			out.push(chars.slice(i, i + columns).join(""));
-		}
-	}
-	return out;
-}
-
 export function clampOffset(offset: number, total: number, visible: number): number {
 	return Math.max(0, Math.min(offset, Math.max(0, total - visible)));
 }
 
+/**
+ * The initially highlighted choice: the safest approving option ("manual
+ * approvals", mode "default"). Auto mode may lead the list so it is one
+ * keypress away, but Enter without arrowing must keep approving into manual
+ * mode — the pre-auto-option behavior — never silently switch the session
+ * into a more permissive mode.
+ */
+/**
+ * The pre-selected choice: the option that restores the mode the session was
+ * in before planning when one is offered (Claude Code's ExitPlanMode restores
+ * `prePlanMode`), else "manual approvals", else the first option.
+ */
+export function initialPlanChoice(options: readonly { mode?: string; restore?: boolean }[]): PlanChoice {
+	const restore = options.findIndex((o) => o.restore);
+	if (restore >= 0) return restore;
+	const index = options.findIndex((o) => o.mode === "default");
+	return index >= 0 ? index : 0;
+}
+
 export type Paint = (color: string, text: string) => string;
 
 export interface PlanViewerView {
@@ -85,22 +94,22 @@ export interface PlanViewerView {
 	lines: string[];
 	offset: number;
 	choice: PlanChoice;
+	/** Labels for the numbered choice list; the last is conventionally "Keep planning". */
+	choices: readonly string[];
 	maxVisible?: number;
 }
 
 export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: number): string[] {
 	const maxVisible = view.maxVisible ?? 12;
 	// Cut plain text before painting so escapes never enter the width math.
-	const cut = (line: string) => {
-		const chars = [...line];
-		return chars.length > width ? `${chars.slice(0, Math.max(0, width - 1)).join("")}…` : line;
-	};
+	const cut = (line: string) => cutPlainText(line, width);
 	const rule = paint("dim", "─".repeat(Math.max(0, Math.min(width, 72))));
+	const pickHint = view.choices.length > 1 ? `1-${view.choices.length} pick · ` : "";
 
 	const out: string[] = [];
 	out.push("");
 	out.push(paint("accent", cut("Approve this plan?")));
-	out.push(paint("dim", cut("↑/↓ scroll · ←/→ switch choice · 1-3 pick · enter confirm · esc keep planning")));
+	out.push(paint("dim", cut(`↑/↓ scroll · ←/→ switch choice · ${pickHint}enter confirm · esc keep planning`)));
 	out.push(rule);
 
 	const offset = clampOffset(view.offset, view.lines.length, maxVisible);
@@ -113,7 +122,7 @@ export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: numb
 	}
 	out.push(rule);
 
-	for (const [index, label] of PLAN_CHOICES.entries()) {
+	for (const [index, label] of view.choices.entries()) {
 		const numbered = `${index + 1}. ${label}`;
 		out.push(
 			index === view.choice ? paint("accent", cut(`❯ ${numbered}`)) : cut(`  ${numbered}`),

package/extensions/plugins/counts.ts

@@ -0,0 +1,68 @@
+/**
+ * Install counts for the Discover tab.
+ *
+ * Public stats JSON from the official marketplace repository
+ * (`[{plugin: "name@marketplace", unique_installs}]`), cached under the plugin
+ * root for 24h. A fetch failure hides counts (undefined) — never shows zeros.
+ */
+
+import { join } from "node:path";
+import { readJsonFile, writeJsonAtomic } from "../lib/atomic-write.ts";
+import { fetchWithTimeout } from "../lib/fetch-timeout.ts";
+
+export const INSTALL_COUNTS_URL =
+	"https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json";
+
+const CACHE_FILE = "install-counts-cache.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+
+interface CountsCache {
+	version: 1;
+	fetchedAt: string;
+	counts: Array<{ plugin: string; unique_installs: number }>;
+}
+
+function toMap(counts: CountsCache["counts"]): Map<string, number> {
+	const map = new Map<string, number>();
+	for (const entry of counts) {
+		if (typeof entry?.plugin === "string" && typeof entry?.unique_installs === "number") {
+			map.set(entry.plugin, entry.unique_installs);
+		}
+	}
+	return map;
+}
+
+/** Fresh cached counts, or undefined when absent/expired/malformed. */
+export function readCachedCounts(root: string, now: Date = new Date()): Map<string, number> | undefined {
+	const cache = readJsonFile<CountsCache>(join(root, CACHE_FILE));
+	if (!cache || !Array.isArray(cache.counts) || typeof cache.fetchedAt !== "string") return undefined;
+	const fetchedAt = Date.parse(cache.fetchedAt);
+	if (Number.isNaN(fetchedAt) || now.getTime() - fetchedAt > CACHE_TTL_MS) return undefined;
+	return toMap(cache.counts);
+}
+
+/** Cached counts when fresh, else fetch + cache; undefined on failure. */
+export async function fetchInstallCounts(root: string, now: Date = new Date()): Promise<Map<string, number> | undefined> {
+	const cached = readCachedCounts(root, now);
+	if (cached) return cached;
+
+	try {
+		const response = await fetchWithTimeout(INSTALL_COUNTS_URL, FETCH_TIMEOUT_MS);
+		if (!response.ok) return undefined;
+		const counts = (await response.json()) as CountsCache["counts"];
+		if (!Array.isArray(counts)) return undefined;
+		writeJsonAtomic(join(root, CACHE_FILE), { version: 1, fetchedAt: now.toISOString(), counts } satisfies CountsCache);
+		return toMap(counts);
+	} catch {
+		return undefined;
+	}
+}
+
+/** 999 → "999", 36400 → "36.4K", 1_200_000 → "1.2M" (trailing .0 stripped). */
+export function formatInstallCount(count: number): string {
+	if (count < 1000) return String(count);
+	const scaled = count < 1_000_000 ? count / 1000 : count / 1_000_000;
+	const suffix = count < 1_000_000 ? "K" : "M";
+	return `${scaled.toFixed(1).replace(/\.0$/, "")}${suffix}`;
+}