@f5-sales-demo/xcsh 19.51.2

package/src/modes/components/ttsr-notification.ts

@@ -0,0 +1,80 @@
+import { Box, Container, Spacer, Text } from "@f5xc-salesdemos/pi-tui";
+import type { Rule } from "../../capability/rule";
+import { theme } from "../../modes/theme/theme";
+
+/**
+ * Component that renders a TTSR (Time Traveling Stream Rules) notification.
+ * Shows when a rule violation is detected and the stream is being rewound.
+ */
+export class TtsrNotificationComponent extends Container {
+	#box: Box;
+	#expanded = false;
+
+	constructor(private readonly rules: Rule[]) {
+		super();
+
+		this.addChild(new Spacer(1));
+
+		// Use inverse warning color for yellow background effect
+		this.#box = new Box(1, 0, t => theme.inverse(theme.fg("warning", t)));
+		this.addChild(this.#box);
+
+		this.#rebuild();
+	}
+
+	setExpanded(expanded: boolean): void {
+		if (this.#expanded !== expanded) {
+			this.#expanded = expanded;
+			this.#rebuild();
+		}
+	}
+
+	isExpanded(): boolean {
+		return this.#expanded;
+	}
+
+	#rebuild(): void {
+		this.#box.clear();
+
+		// Build header: warning symbol + rule name + rewind icon
+		const ruleNames = this.rules.map(r => theme.bold(r.name)).join(", ");
+		const label = this.rules.length === 1 ? "rule" : "rules";
+		const header = `${theme.icon.warning} Injecting ${label}: ${ruleNames}`;
+
+		// Create header with rewind icon on the right
+		const rewindIcon = theme.icon.rewind;
+
+		this.#box.addChild(new Text(`${header}  ${rewindIcon}`, 0, 0));
+
+		// Show description(s) - italic and truncated
+		for (const rule of this.rules) {
+			const desc = rule.description || rule.content;
+			if (desc) {
+				this.#box.addChild(new Spacer(1));
+
+				let displayText = desc.trim();
+				if (!this.#expanded) {
+					// Truncate to first 2 lines
+					const lines = displayText.split("\n");
+					if (lines.length > 2) {
+						displayText = `${lines.slice(0, 2).join("\n")}…`;
+					}
+				}
+
+				// Use italic for subtle distinction (fg colors conflict with inverse)
+				this.#box.addChild(new Text(theme.italic(displayText), 0, 0));
+			}
+		}
+
+		// Show expand hint if collapsed and there's more content
+		if (!this.#expanded) {
+			const hasMoreContent = this.rules.some(r => {
+				const desc = r.description || r.content;
+				return desc && desc.split("\n").length > 2;
+			});
+			if (hasMoreContent) {
+				this.#box.addChild(new Text(theme.italic(" (ctrl+o to expand)"), 0, 0));
+			}
+		}
+	}
+}

package/src/modes/components/user-message-selector.ts

@@ -0,0 +1,141 @@
+import { type Component, Container, matchesKey, Spacer, Text, truncateToWidth } from "@f5xc-salesdemos/pi-tui";
+import { theme } from "../../modes/theme/theme";
+import { matchesSelectCancel } from "../../modes/utils/keybinding-matchers";
+import { DynamicBorder } from "./dynamic-border";
+
+interface UserMessageItem {
+	id: string; // Entry ID in the session
+	text: string; // The message text
+	timestamp?: string; // Optional timestamp if available
+}
+
+/**
+ * Custom user message list component with selection
+ */
+class UserMessageList implements Component {
+	#selectedIndex: number = 0;
+	onSelect?: (entryId: string) => void;
+	onCancel?: () => void;
+	#maxVisible: number = 10; // Max messages visible
+
+	constructor(private readonly messages: UserMessageItem[]) {
+		// Store messages in chronological order (oldest to newest)
+		// Start with the last (most recent) message selected
+		this.#selectedIndex = Math.max(0, this.messages.length - 1);
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+
+		if (this.messages.length === 0) {
+			lines.push(theme.fg("muted", "  No user messages found"));
+			return lines;
+		}
+
+		// Calculate visible range with scrolling
+		const startIndex = Math.max(
+			0,
+			Math.min(this.#selectedIndex - Math.floor(this.#maxVisible / 2), this.messages.length - this.#maxVisible),
+		);
+		const endIndex = Math.min(startIndex + this.#maxVisible, this.messages.length);
+
+		// Render visible messages (2 lines per message + blank line)
+		for (let i = startIndex; i < endIndex; i++) {
+			const message = this.messages[i];
+			const isSelected = i === this.#selectedIndex;
+
+			// Normalize message to single line
+			const normalizedMessage = message.text.replace(/\n/g, " ").trim();
+
+			// First line: cursor + message
+			const cursor = isSelected ? theme.fg("chromeAccent", "› ") : "  ";
+			const maxMsgWidth = width - 2; // Account for cursor (2 chars)
+			const truncatedMsg = truncateToWidth(normalizedMessage, maxMsgWidth);
+			const messageLine = cursor + (isSelected ? theme.bold(truncatedMsg) : truncatedMsg);
+
+			lines.push(messageLine);
+
+			// Second line: metadata (position in history)
+			const position = i + 1;
+			const metadata = `  Message ${position} of ${this.messages.length}`;
+			const metadataLine = theme.fg("muted", metadata);
+			lines.push(metadataLine);
+			lines.push(""); // Blank line between messages
+		}
+
+		// Add scroll indicator if needed
+		if (startIndex > 0 || endIndex < this.messages.length) {
+			const scrollInfo = theme.fg("muted", `  (${this.#selectedIndex + 1}/${this.messages.length})`);
+			lines.push(scrollInfo);
+		}
+
+		return lines;
+	}
+
+	handleInput(keyData: string): void {
+		// Up arrow - go to previous (older) message, wrap to bottom when at top
+		if (matchesKey(keyData, "up")) {
+			this.#selectedIndex = this.#selectedIndex === 0 ? this.messages.length - 1 : this.#selectedIndex - 1;
+		}
+		// Down arrow - go to next (newer) message, wrap to top when at bottom
+		else if (matchesKey(keyData, "down")) {
+			this.#selectedIndex = this.#selectedIndex === this.messages.length - 1 ? 0 : this.#selectedIndex + 1;
+		}
+		// Enter - select message and branch
+		else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
+			const selected = this.messages[this.#selectedIndex];
+			if (selected && this.onSelect) {
+				this.onSelect(selected.id);
+			}
+		}
+		// Escape / cancel
+		else if (matchesSelectCancel(keyData)) {
+			if (this.onCancel) {
+				this.onCancel();
+			}
+		}
+	}
+}
+
+/**
+ * Component that renders a user message selector for branching
+ */
+export class UserMessageSelectorComponent extends Container {
+	#messageList: UserMessageList;
+
+	constructor(messages: UserMessageItem[], onSelect: (entryId: string) => void, onCancel: () => void) {
+		super();
+
+		// Add header
+		this.addChild(new Spacer(1));
+		this.addChild(new Text(theme.bold("Branch from Message"), 1, 0));
+		this.addChild(new Text(theme.fg("muted", "Select a message to create a new branch from that point"), 1, 0));
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder());
+		this.addChild(new Spacer(1));
+
+		// Create message list
+		this.#messageList = new UserMessageList(messages);
+		this.#messageList.onSelect = onSelect;
+		this.#messageList.onCancel = onCancel;
+
+		this.addChild(this.#messageList);
+
+		// Add bottom border
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder());
+
+		// Auto-cancel if no messages
+		if (messages.length === 0) {
+			setTimeout(() => onCancel(), 100);
+		}
+	}
+
+	getMessageList(): UserMessageList {
+		return this.#messageList;
+	}
+}

package/src/modes/components/user-message.ts

@@ -0,0 +1,100 @@
+import { Container, Markdown, padding, Spacer, visibleWidth } from "@f5xc-salesdemos/pi-tui";
+import { getMarkdownTheme, theme } from "../../modes/theme/theme";
+
+// U+2503 BOX DRAWINGS HEAVY VERTICAL — continuation bar on wrapped lines.
+const CONTINUATION_BAR = "┃";
+// Markdown child uses paddingX=1 and clamps contentWidth>=1, so its minimum
+// render output is 3 terminal cells. Anything narrower than prefix+3 would
+// overflow the requested width — bail out instead.
+const MIN_MARKDOWN_WIDTH = 3;
+// Two-column layout: the gutter (col 0..GUTTER_WIDTH-1) stays outside the
+// userMessageBg painted region and holds the π icon on the first content
+// line / two spaces on continuations — mirroring how GutterBlock renders
+// its ● indicator at col 0. The painted region starts at col GUTTER_WIDTH
+// and hosts the ┃ accent bar on every content line (including the first).
+const GUTTER_WIDTH = 2;
+const GUTTER_PAD = "  ";
+
+/**
+ * Renders a user message as an F5-branded admonition block with a two-column
+ * layout: the π icon sits in the gutter at col 0 on the first content line
+ * (outside the painted region, matching the `●` indicator pattern used by
+ * `GutterBlock`); the ┃ heavy vertical bar renders at col GUTTER_WIDTH inside
+ * `userMessageBg` on every content line including the first. Both glyphs use
+ * the `border` fg. The bg is painted across the full requested width, and a
+ * leading blank spacer separates the prompt from the preceding block.
+ */
+export class UserMessageComponent extends Container {
+	#text: string;
+	#synthetic: boolean;
+
+	constructor(text: string, synthetic = false) {
+		super();
+		this.#text = text;
+		this.#synthetic = synthetic;
+		this.#rebuild();
+	}
+
+	// Mirror AssistantMessageComponent: on invalidate, drop the Markdown child
+	// and rebuild it so getMarkdownTheme() is re-captured. Without this, a
+	// theme change leaves the Markdown child rendering with the original
+	// construction-time theme.
+	override invalidate(): void {
+		super.invalidate();
+		this.#rebuild();
+	}
+
+	#rebuild(): void {
+		this.children = [];
+		const color = this.#synthetic
+			? (value: string) => theme.fg("dim", value)
+			: (value: string) => `\x1b[3m${theme.fg("userMessageText", value)}\x1b[23m`;
+		this.addChild(new Spacer(1));
+		this.addChild(new Markdown(this.#text, 0, 0, getMarkdownTheme(), { color }));
+	}
+
+	override render(width: number): string[] {
+		const contPrefix = `${CONTINUATION_BAR} `;
+		// π lives in the fixed-width gutter (see the content map below), so it
+		// does not factor into innerWidth. Only contPrefix eats content budget.
+		const innerWidth = width - GUTTER_WIDTH - visibleWidth(contPrefix);
+		if (innerWidth < MIN_MARKDOWN_WIDTH) {
+			return [];
+		}
+		const raw = super.render(innerWidth);
+		if (raw.length === 0) {
+			return raw;
+		}
+
+		let firstContent = 0;
+		while (firstContent < raw.length && raw[firstContent] === "") {
+			firstContent++;
+		}
+		if (firstContent === raw.length) {
+			return raw;
+		}
+
+		// First-line gutter: π icon padded to exactly GUTTER_WIDTH cells. The
+		// glyph width is theme-dependent (Unicode π = 1 col, Nerd Font PUA = 2
+		// cols, ASCII "pi" = 2 cols); right-pad with spaces so the gutter
+		// occupies a fixed slot and the ┃ bar at col GUTTER_WIDTH aligns across
+		// every content line.
+		const piIcon = theme.icon.pi;
+		const piPadSize = Math.max(0, GUTTER_WIDTH - visibleWidth(piIcon));
+		// Pad inside the theme.fg wrap so the border-fg escape, glyph, and
+		// pad space form one contiguous span (no intervening fg reset). This
+		// matches the shape the raw-escape assertion in test 6 looks for.
+		const piGutter = theme.fg("border", piIcon + " ".repeat(piPadSize));
+
+		const leading = raw.slice(0, firstContent);
+		const content = raw.slice(firstContent).map((line, i) => {
+			const prefix = theme.fg("border", contPrefix);
+			const combined = prefix + line;
+			const pad = Math.max(0, width - GUTTER_WIDTH - visibleWidth(combined));
+			const gutter = i === 0 ? piGutter : GUTTER_PAD;
+			return gutter + theme.bg("userMessageBg", combined + padding(pad));
+		});
+
+		return [...leading, ...content];
+	}
+}

package/src/modes/components/visual-truncate.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared utility for truncating text to visual lines (accounting for line wrapping).
+ * Used by both tool-execution.ts and bash-execution.ts for consistent behavior.
+ */
+import { Text } from "@f5xc-salesdemos/pi-tui";
+
+export interface VisualTruncateResult {
+	/** The visual lines to display */
+	visualLines: string[];
+	/** Number of visual lines that were skipped (hidden) */
+	skippedCount: number;
+}
+
+const textCache = new Map<number, Text>();
+
+function getCachedText(paddingX: number): Text {
+	let text = textCache.get(paddingX);
+	if (!text) {
+		text = new Text("", paddingX, 0);
+		textCache.set(paddingX, text);
+	}
+	return text;
+}
+
+/**
+ * Truncate text to a maximum number of visual lines (from the end).
+ * This accounts for line wrapping based on terminal width.
+ *
+ * @param text - The text content (may contain newlines)
+ * @param maxVisualLines - Maximum number of visual lines to show
+ * @param width - Terminal/render width
+ * @param paddingX - Horizontal padding for Text component (default 0).
+ *                   Use 0 when result will be placed in a Box (Box adds its own padding).
+ *                   Use 1 when result will be placed in a plain Container.
+ * @returns The truncated visual lines and count of skipped lines
+ */
+export function truncateToVisualLines(
+	text: string,
+	maxVisualLines: number,
+	width: number,
+	paddingX: number = 0,
+): VisualTruncateResult {
+	if (!text) {
+		return { visualLines: [], skippedCount: 0 };
+	}
+
+	// Create a temporary Text component to render and get visual lines
+	const tempText = getCachedText(paddingX);
+	if (tempText.getText() !== text) {
+		tempText.setText(text);
+	}
+	const allVisualLines = tempText.render(width);
+
+	if (allVisualLines.length <= maxVisualLines) {
+		return { visualLines: allVisualLines, skippedCount: 0 };
+	}
+
+	// Take the last N visual lines
+	const truncatedLines = allVisualLines.slice(-maxVisualLines);
+	const skippedCount = allVisualLines.length - maxVisualLines;
+
+	return { visualLines: truncatedLines, skippedCount };
+}

package/src/modes/components/welcome-checks.ts

@@ -0,0 +1,313 @@
+import type { Model } from "@f5xc-salesdemos/pi-ai";
+import { validateApiKeyAgainstModelsEndpoint } from "@f5xc-salesdemos/pi-ai/utils/oauth/api-key-validation";
+import { logger } from "@f5xc-salesdemos/pi-utils";
+import { MarketplaceManager } from "../../extensibility/plugins/marketplace";
+import {
+	getInstalledPluginsRegistryPath,
+	getMarketplacesCacheDir,
+	getMarketplacesRegistryPath,
+	getPluginsCacheDir,
+} from "../../extensibility/plugins/marketplace/registry";
+import { type AuthStatus, ContextService } from "../../services/xcsh-context";
+import { deriveTenantFromUrl } from "../../services/xcsh-env";
+import type { AuthStorage } from "../../session/auth-storage";
+import { normalizePluginDisplayName } from "./plugins/utils";
+
+// Startup validation budget. These are longer than validateToken's 3000ms default because
+// the welcome path runs during TLS/DNS cold-start — a single 3s shot races against warm-up
+// and falsely reports offline for contexts that reconnect cleanly moments later.
+const STARTUP_FIRST_TIMEOUT_MS = 4000;
+const STARTUP_RETRY_TIMEOUT_MS = 5000;
+const STARTUP_RETRY_DELAY_MS = 500;
+
+type ContextValidator = (opts: {
+	timeoutMs: number;
+}) => Promise<{ status: AuthStatus; latencyMs?: number; errorClass?: "network" | "credential" | "url_not_found" }>;
+
+/**
+ * Runs the context validator once with a startup-sized timeout; if the result is `offline`
+ * (the only transient class — auth_error/connected/unknown are definitive), waits briefly
+ * to let DNS/TLS warm up, then tries once more with a longer timeout.
+ */
+export async function validateContextWithStartupRetry(
+	validate: ContextValidator,
+	options?: {
+		firstTimeoutMs?: number;
+		retryTimeoutMs?: number;
+		retryDelayMs?: number;
+	},
+): Promise<{ status: AuthStatus; latencyMs?: number; errorClass?: "network" | "credential" | "url_not_found" }> {
+	const firstTimeoutMs = options?.firstTimeoutMs ?? STARTUP_FIRST_TIMEOUT_MS;
+	const retryTimeoutMs = options?.retryTimeoutMs ?? STARTUP_RETRY_TIMEOUT_MS;
+	const retryDelayMs = options?.retryDelayMs ?? STARTUP_RETRY_DELAY_MS;
+
+	const first = await validate({ timeoutMs: firstTimeoutMs });
+	if (first.status !== "offline") return first;
+
+	if (retryDelayMs > 0) {
+		await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+	}
+	return await validate({ timeoutMs: retryTimeoutMs });
+}
+
+export type ModelCheckState = "no_provider" | "connected" | "auth_error";
+
+export interface ModelStatus {
+	state: ModelCheckState;
+	provider?: string;
+	latencyMs?: number;
+}
+
+export type ContextCheckState = "no_context" | "connected" | "auth_error" | "offline";
+
+export interface WelcomeContextStatus {
+	state: ContextCheckState;
+	name?: string;
+	latencyMs?: number;
+	errorClass?: "network" | "credential" | "url_not_found";
+}
+
+export interface WelcomeCheckResult {
+	model: ModelStatus;
+	context?: WelcomeContextStatus;
+}
+
+/** Providers that don't store API keys (local inference servers) */
+const KEYLESS_PROVIDERS = new Set(["ollama", "llama.cpp", "lm-studio", "llamafile", "local"]);
+
+/**
+ * Run blocking startup checks for the welcome screen.
+ * Model check always runs. Context check only runs if model is connected.
+ */
+export async function runWelcomeChecks(
+	model: Model | undefined,
+	authStorage: AuthStorage,
+): Promise<WelcomeCheckResult> {
+	const provider = model?.provider ?? "unknown";
+
+	// Step 1: Check model provider credentials exist
+	// Keyless local providers (ollama, llama.cpp, lm-studio, etc.) don't store credentials
+	if (!authStorage.hasAuth(provider) && !KEYLESS_PROVIDERS.has(provider)) {
+		return { model: { state: "no_provider", provider } };
+	}
+
+	// Step 2: Live model validation — try to reach the models endpoint
+	const modelStatus = await validateModelConnection(model, authStorage);
+	if (modelStatus.state !== "connected") {
+		return { model: modelStatus };
+	}
+
+	// Step 3: Context check (only if model is connected)
+	const contextStatus = await checkContextStatus();
+	return { model: modelStatus, context: contextStatus };
+}
+
+async function validateModelConnection(model: Model | undefined, authStorage: AuthStorage): Promise<ModelStatus> {
+	const provider = model?.provider ?? "unknown";
+	try {
+		const rawApiKey = await authStorage.peekApiKey(provider);
+		if (!rawApiKey) {
+			// Keyless providers skip validation
+			if (KEYLESS_PROVIDERS.has(provider)) {
+				return { state: "connected", provider, latencyMs: 0 };
+			}
+			return { state: "auth_error", provider };
+		}
+
+		// Detect unresolved env var names (e.g. "LITELLM_API_KEY" sent as literal)
+		if (/^[A-Z][A-Z0-9]*(?:_[A-Z][A-Z0-9]*)+$/.test(rawApiKey)) {
+			return { state: "auth_error", provider };
+		}
+
+		const baseUrl = model?.baseUrl;
+		if (!baseUrl) {
+			return { state: "auth_error", provider };
+		}
+
+		// GitHub Copilot returns a structured JSON token {token, enterpriseUrl};
+		// extract the actual token for API validation
+		let apiKey = rawApiKey;
+		if (provider === "github-copilot" && rawApiKey.startsWith("{")) {
+			try {
+				const parsed = JSON.parse(rawApiKey);
+				apiKey = parsed.token ?? rawApiKey;
+			} catch {
+				// Not JSON — use as-is
+			}
+		}
+
+		const modelsUrl = `${baseUrl}/models`;
+		const start = performance.now();
+		await validateApiKeyAgainstModelsEndpoint({
+			provider,
+			apiKey,
+			modelsUrl,
+		});
+		const latencyMs = Math.round(performance.now() - start);
+		return { state: "connected", provider, latencyMs };
+	} catch {
+		logger.warn("Welcome model validation failed");
+		return { state: "auth_error", provider };
+	}
+}
+
+async function checkContextStatus(): Promise<WelcomeContextStatus> {
+	try {
+		const contextService = ContextService.instance;
+		if (!contextService) {
+			return { state: "no_context" };
+		}
+
+		const status = contextService.getStatus();
+		if (!status.isConfigured) {
+			return { state: "no_context" };
+		}
+
+		const name =
+			status.activeContextName ??
+			(status.credentialSource === "environment" && status.activeContextUrl
+				? (deriveTenantFromUrl(status.activeContextUrl) ?? "(environment)")
+				: undefined);
+		const result = await validateContextWithStartupRetry(opts => contextService.validateToken(opts));
+
+		switch (result.status) {
+			case "connected":
+				return { state: "connected", name, latencyMs: result.latencyMs };
+			case "auth_error":
+				return { state: "auth_error", name };
+			case "offline":
+				return { state: "offline", name, errorClass: result.errorClass };
+			default:
+				return { state: "no_context" };
+		}
+	} catch {
+		logger.warn("Welcome context validation failed");
+		return { state: "no_context" };
+	}
+}
+
+export type ServiceState = "connected" | "unauthenticated" | "unavailable";
+
+export interface ServiceStatus {
+	name: string;
+	state: ServiceState;
+	hint?: string;
+	_isPlugin?: boolean;
+	_group?: string;
+}
+
+export function mapContextStatus(status: WelcomeContextStatus): ServiceStatus {
+	switch (status.state) {
+		case "connected":
+			return { name: "F5 XC Context", state: "connected" };
+		case "no_context":
+			return { name: "F5 XC Context", state: "unauthenticated", hint: "run: /context create" };
+		case "auth_error":
+			return { name: "F5 XC Context", state: "unauthenticated", hint: "run: /context" };
+		case "offline":
+			switch (status.errorClass) {
+				case "network":
+					return { name: "F5 XC Context", state: "unauthenticated", hint: "network unreachable" };
+				case "url_not_found":
+					return { name: "F5 XC Context", state: "unauthenticated", hint: "tenant URL not found" };
+				default:
+					return { name: "F5 XC Context", state: "unauthenticated", hint: "run: /context" };
+			}
+	}
+}
+
+export interface FixableService {
+	name: string;
+	prompt: string;
+	command: string[];
+	recheck: () => Promise<ServiceStatus>;
+}
+
+export type UnifiedPluginState = "connected" | "unauthenticated" | "unavailable" | "installed" | "not_installed";
+
+export interface UnifiedPluginStatus {
+	name: string;
+	state: UnifiedPluginState;
+	hint?: string;
+	group?: string;
+}
+
+export interface ServiceStatusContributionInput {
+	name: string;
+	group?: string;
+	check: () => Promise<{ state: ServiceState; hint?: string }>;
+}
+
+export async function buildUnifiedPluginList(
+	contributions: ServiceStatusContributionInput[],
+): Promise<UnifiedPluginStatus[]> {
+	const map = new Map<string, UnifiedPluginStatus>();
+
+	for (const contribution of contributions) {
+		try {
+			const status = await contribution.check();
+			map.set(contribution.name.toLowerCase(), {
+				name: contribution.name,
+				state: status.state,
+				hint: status.hint,
+				group: contribution.group,
+			});
+		} catch {
+			map.set(contribution.name.toLowerCase(), {
+				name: contribution.name,
+				state: "unavailable",
+				hint: "check failed",
+				group: contribution.group,
+			});
+		}
+	}
+
+	try {
+		const mgr = new MarketplaceManager({
+			marketplacesRegistryPath: getMarketplacesRegistryPath(),
+			installedRegistryPath: getInstalledPluginsRegistryPath(),
+			marketplacesCacheDir: getMarketplacesCacheDir(),
+			pluginsCacheDir: getPluginsCacheDir(),
+			clearPluginRootsCache: () => {},
+		});
+
+		const [marketplaces, installedSummaries] = await Promise.all([
+			mgr.listMarketplaces(),
+			mgr.listInstalledPlugins(),
+		]);
+
+		const installedIds = new Set(installedSummaries.map(s => s.id));
+
+		for (const mkt of marketplaces) {
+			const available = await mgr.listAvailablePlugins(mkt.name).catch(() => []);
+			for (const entry of available) {
+				if (!entry.recommended) continue;
+				const displayName = normalizePluginDisplayName(entry.name);
+				const key = displayName.toLowerCase();
+				if (map.has(key)) continue;
+				const pluginId = `${entry.name}@${mkt.name}`;
+				map.set(key, {
+					name: displayName,
+					state: installedIds.has(pluginId) ? "installed" : "not_installed",
+					hint: installedIds.has(pluginId) ? undefined : "run: /plugin setup",
+				});
+			}
+		}
+	} catch (err) {
+		logger.debug("buildUnifiedPluginList marketplace check failed", { error: String(err) });
+	}
+
+	const stateOrder: Record<UnifiedPluginState, number> = {
+		connected: 0,
+		unauthenticated: 1,
+		unavailable: 2,
+		installed: 3,
+		not_installed: 4,
+	};
+
+	return [...map.values()].sort((a, b) => {
+		const orderDiff = stateOrder[a.state] - stateOrder[b.state];
+		if (orderDiff !== 0) return orderDiff;
+		return a.name.localeCompare(b.name);
+	});
+}