@f5-sales-demo/xcsh 19.56.1 → 19.57.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.56.1",
+	"version": "19.57.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.56.1",
-		"@f5-sales-demo/pi-agent-core": "19.56.1",
-		"@f5-sales-demo/pi-ai": "19.56.1",
-		"@f5-sales-demo/pi-natives": "19.56.1",
-		"@f5-sales-demo/pi-resource-management": "19.56.1",
-		"@f5-sales-demo/pi-tui": "19.56.1",
-		"@f5-sales-demo/pi-utils": "19.56.1",
+		"@f5-sales-demo/xcsh-stats": "19.57.0",
+		"@f5-sales-demo/pi-agent-core": "19.57.0",
+		"@f5-sales-demo/pi-ai": "19.57.0",
+		"@f5-sales-demo/pi-natives": "19.57.0",
+		"@f5-sales-demo/pi-resource-management": "19.57.0",
+		"@f5-sales-demo/pi-tui": "19.57.0",
+		"@f5-sales-demo/pi-utils": "19.57.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/worker-tools-harness.ts

@@ -0,0 +1,151 @@
+// Headless worker-tool harness — no Chrome, no F5 login.
+//
+// Spawns a real `xcsh worker`, connects a MOCK extension bridge client (exactly
+// the hello handshake + origin the real service worker uses), sends a chat_request
+// asking it to navigate, and observes:
+//   (a) which tools the worker's agent actually has (from the daily log), and
+//   (b) whether the agent emits a `navigate` tool_request over the bridge.
+//
+// This isolates the "agent responds but never drives" bug to the WORKER's tool
+// registration, deterministically and repeatably.
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// XCSH_DEV=1 → run the local source build (`bun src/cli.ts worker`) so source
+// edits are testable; otherwise the installed Homebrew binary.
+const XCSH_REPO = new URL("..", import.meta.url).pathname; // packages/coding-agent
+const DEV = process.env.XCSH_DEV === "1";
+const SPAWN_CMD = DEV ? ["bun", "src/cli.ts", "worker"] : ["/opt/homebrew/bin/xcsh", "worker"];
+const SPAWN_CWD = DEV ? XCSH_REPO : process.cwd();
+const EXT_ID = "klajkjdoehjidngligegnpknogmjjhkc";
+const ORIGIN = `chrome-extension://${EXT_ID}`; // bridge origin check: exact, no trailing slash
+const PORT = 19260; // away from the real backend range (19222-19241)
+const TENANT = process.env.HARNESS_TENANT ?? "f5-sales-demo|production";
+const PROMPT = process.env.HARNESS_PROMPT ?? "Navigate the browser to the origin pools list.";
+
+function log(...a: unknown[]) {
+	console.log("[harness]", ...a);
+}
+
+// 1) Spawn the worker with a forced bridge port + tenant identity.
+const worker = Bun.spawn(SPAWN_CMD, {
+	cwd: SPAWN_CWD,
+	env: {
+		...process.env,
+		XCSH_BRIDGE_PORT: String(PORT),
+		XCSH_SESSION_ID: "tab-9999",
+		XCSH_SESSION_TENANT: TENANT,
+	},
+	stdout: "pipe",
+	stderr: "pipe",
+});
+log(`spawned worker pid=${worker.pid} (${DEV ? "DEV build" : "homebrew"}), port=${PORT}, tenant=${TENANT}`);
+
+// Stream worker stderr; resolve when the bridge is listening.
+let bridgeUp = false;
+const decoder = new TextDecoder();
+(async () => {
+	for await (const chunk of worker.stderr) {
+		const s = decoder.decode(chunk);
+		for (const line of s.split("\n")) {
+			if (line.trim()) log("worker⟩", line.trim());
+			if (line.includes("extension bridge listening")) bridgeUp = true;
+		}
+	}
+})();
+
+// Wait for the bridge, then give the (heavier) agent session time to init + attach
+// the chat handler (chatHandler.attach() runs AFTER createAgentSession).
+for (let i = 0; i < 120 && !bridgeUp; i++) await Bun.sleep(250);
+if (!bridgeUp) {
+	log("FAIL: bridge never came up");
+	worker.kill();
+	process.exit(1);
+}
+log("bridge up; waiting 12s for agent session init…");
+await Bun.sleep(12_000);
+
+// 2) Connect the mock extension client with the correct Origin.
+const toolRequests: string[] = [];
+let chatText = "";
+let chatErr: string | null = null;
+let done = false;
+
+const ws = new WebSocket(`ws://127.0.0.1:${PORT}`, { headers: { Origin: ORIGIN } } as unknown as string[]);
+ws.onopen = () => {
+	log("client connected; sending hello");
+	ws.send(JSON.stringify({ type: "hello", contractVersion: "1.5.0", extensionId: "harness" }));
+};
+ws.onerror = () => log("client ws error (origin rejected?)");
+ws.onmessage = e => {
+	let m: Record<string, unknown>;
+	try {
+		m = JSON.parse(e.data as string);
+	} catch {
+		return;
+	}
+	switch (m.type) {
+		case "hello_ack":
+			log(`hello_ack: tenant=${m.tenant} sessionId=${m.sessionId} contractVersion=${m.contractVersion}`);
+			log(`sending chat_request: "${PROMPT}"`);
+			ws.send(
+				JSON.stringify({
+					type: "chat_request",
+					id: "c-harness-1",
+					text: PROMPT,
+					context: null,
+					mode: "configuration",
+				}),
+			);
+			break;
+		case "tool_request":
+			log(`◆ TOOL_REQUEST from agent: tool="${m.tool}" id=${m.id}`);
+			toolRequests.push(m.tool as string);
+			// Reply so the agent's turn can proceed.
+			ws.send(JSON.stringify({ type: "tool_result", id: m.id, content: "ok (harness stub)", is_error: false }));
+			break;
+		case "chat_delta":
+			chatText += (m.delta as string) ?? "";
+			break;
+		case "chat_done":
+			done = true;
+			break;
+		case "chat_error":
+			chatErr = (m.error as string) ?? "unknown";
+			done = true;
+			break;
+	}
+};
+
+// 3) Wait for the turn to finish (or time out).
+for (let i = 0; i < 240 && !done; i++) await Bun.sleep(250);
+
+// 4) Read the worker's actual tool set from the daily log.
+let activeTools = "(not found in daily log)";
+try {
+	const logPath = join(homedir(), ".xcsh", "logs", `xcsh.${new Date().toISOString().slice(0, 10)}.log`);
+	const text = await Bun.file(logPath).text();
+	const lines = text.split("\n").filter(l => l.includes(`"pid":${worker.pid}`) && l.includes("activeToolNames"));
+	if (lines.length) {
+		const parsed = JSON.parse(lines[lines.length - 1]);
+		activeTools = JSON.stringify(parsed.activeToolNames);
+	}
+} catch {}
+
+console.log("\n==================== RESULT ====================");
+console.log("agent tool_requests emitted :", toolRequests.length ? toolRequests.join(", ") : "(none)");
+console.log("worker activeToolNames       :", activeTools);
+console.log("has navigate tool?           :", activeTools.includes('"navigate"') ? "YES" : "NO");
+console.log("emitted a navigate?          :", toolRequests.includes("navigate") ? "YES" : "NO");
+console.log("chat error                   :", chatErr ?? "(none)");
+console.log("agent said (first 240 chars) :", chatText.slice(0, 240).replace(/\n/g, " "));
+if (toolRequests.includes("navigate")) console.log("\n[PASS] worker agent HAS + CALLS navigate — tool registration OK");
+else console.log("\n[FAIL] worker never called navigate — browser tools missing from the agent");
+console.log("===============================================");
+
+try {
+	ws.close();
+} catch {}
+worker.kill();
+await Bun.sleep(300);
+process.exit(0);

package/src/browser/extension-bridge-tools.ts

@@ -0,0 +1,71 @@
+/**
+ * Agent tools for the Chrome extension's browser actions.
+ *
+ * The extension advertises a fixed set of tools (EXTENSION_CAPABILITIES.tools:
+ * navigate, click, read_ax, type_text, …). Before this factory, those names were
+ * requested by the worker (BROWSER_TOOL_NAMES) but never registered as agent
+ * tools — so the agent could only run the form-driven `catalog_workflow_runner`
+ * and had no way to `navigate`/`click`, i.e. it replied "Navigating…" and never
+ * drove the browser. This turns each advertised tool into a `CustomTool` whose
+ * `execute` proxies the call to the connected extension over the bridge.
+ */
+import type { AgentToolResult, AgentToolUpdateCallback } from "@f5-sales-demo/pi-agent-core";
+import type { TSchema } from "@sinclair/typebox";
+import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
+import { EXTENSION_CAPABILITIES, type ExtensionToolDef } from "./capabilities.generated";
+import type { BridgeServer } from "./extension-bridge";
+
+/**
+ * Extension tools that are transport/diagnostic plumbing, not agent actions —
+ * never exposed to the LLM. Everything else in EXTENSION_CAPABILITIES becomes a
+ * callable agent tool.
+ */
+const INTERNAL_TOOLS = new Set<string>([
+	"ping",
+	"capabilities",
+	"reload",
+	"debug_exec",
+	"detach",
+	"set_bridge_port",
+	"diag_suspension",
+	"diag_bridges",
+]);
+
+/** Build a CustomTool that proxies one extension tool to `bridge.request`. */
+function bridgeTool(bridge: BridgeServer, def: ExtensionToolDef): CustomTool<TSchema, unknown> {
+	return {
+		name: def.name,
+		label: def.name,
+		description: def.summary,
+		// The extension's JSON-Schema `params` is a TypeBox-compatible schema object.
+		parameters: (def.params ?? { type: "object", properties: {} }) as unknown as TSchema,
+		async execute(
+			_toolCallId: string,
+			params: unknown,
+			_onUpdate: AgentToolUpdateCallback<unknown, TSchema> | undefined,
+			_ctx: CustomToolContext,
+			_signal?: AbortSignal,
+		): Promise<AgentToolResult<unknown, TSchema>> {
+			const res = await bridge.request(def.name, (params ?? {}) as Record<string, unknown>);
+			const raw = typeof res.content === "string" ? res.content : JSON.stringify(res.content);
+			// AgentToolResult has no isError flag — surface the extension's error in the
+			// text so the model sees the failure and can react.
+			const text = res.is_error ? `Error: ${raw}` : raw;
+			return { content: [{ type: "text" as const, text }] };
+		},
+	};
+}
+
+/**
+ * Every agent-facing extension tool as a bridge-proxying CustomTool. Pass the
+ * result to `createAgentSession({ customTools })` so the worker's agent can drive
+ * the browser. Requires `bridge` (the worker's live extension-bridge server).
+ */
+export function createExtensionBridgeTools(bridge: BridgeServer): CustomTool<TSchema, unknown>[] {
+	return EXTENSION_CAPABILITIES.tools.filter(def => !INTERNAL_TOOLS.has(def.name)).map(def => bridgeTool(bridge, def));
+}
+
+/** Names of the agent-facing extension tools (for tool-scoping / tests). */
+export const EXTENSION_AGENT_TOOL_NAMES: readonly string[] = EXTENSION_CAPABILITIES.tools
+	.filter(def => !INTERNAL_TOOLS.has(def.name))
+	.map(def => def.name);

package/src/commands/worker.ts

@@ -17,6 +17,7 @@ import { getProjectDir, getXCSHConfigDir } from "@f5-sales-demo/pi-utils";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { ChatHandler } from "../browser/chat-handler";
 import { startBridgeServer } from "../browser/extension-bridge";
+import { createExtensionBridgeTools, EXTENSION_AGENT_TOOL_NAMES } from "../browser/extension-bridge-tools";
 import { setSharedBridgeServer } from "../browser/provider";
 import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
@@ -118,10 +119,16 @@ export default class Worker extends Command {
 		bridge.setSessionInfo(sessionInfoForWorker);
 		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
 
+		// The extension's browser actions (navigate/click/read_ax/…) are not builtin
+		// tools — turn each into a bridge-proxying CustomTool so the agent can drive
+		// the browser (without this the agent only has catalog_workflow_runner and
+		// merely narrates "Navigating…"). Include their names in the tool scope.
+		const extensionTools = createExtensionBridgeTools(bridge);
 		const { session } = await createAgentSession({
 			cwd,
 			hasUI: false,
-			toolNames: BROWSER_TOOL_NAMES,
+			toolNames: [...new Set([...BROWSER_TOOL_NAMES, ...EXTENSION_AGENT_TOOL_NAMES])],
+			customTools: extensionTools,
 			// Headless worker: no MCP discovery, no LSP warmup, no extension discovery —
 			// keep startup lean and free of network calls / blocking prompts.
 			enableMCP: false,

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.56.1",
-	"commit": "5630d1694415b3da8edb73803fdf7ad37467d77d",
-	"shortCommit": "5630d16",
+	"version": "19.57.0",
+	"commit": "9b508d8af3633290ce801f2ca9956dd22df78e30",
+	"shortCommit": "9b508d8",
 	"branch": "main",
-	"tag": "v19.56.1",
-	"commitDate": "2026-07-03T17:49:52Z",
-	"buildDate": "2026-07-03T18:14:31.834Z",
+	"tag": "v19.57.0",
+	"commitDate": "2026-07-04T20:19:08Z",
+	"buildDate": "2026-07-04T20:54:40.287Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/5630d1694415b3da8edb73803fdf7ad37467d77d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.56.1"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/9b508d8af3633290ce801f2ca9956dd22df78e30",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.57.0"
 };

package/src/locales/ar.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "مثبتة",
 	"plugins.tabs.recommended": "موصى بها",
 	"plugins.tabs.discover": "استكشاف",

package/src/locales/de.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "Installiert",
 	"plugins.tabs.recommended": "Empfohlen",
 	"plugins.tabs.discover": "Entdecken",

package/src/locales/en.json

@@ -303,6 +303,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 
 	"plugins.tabs.installed": "Installed",
 	"plugins.tabs.recommended": "Recommended",

package/src/locales/es.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "Instalados",
 	"plugins.tabs.recommended": "Recomendados",
 	"plugins.tabs.discover": "Descubrir",

package/src/locales/fr.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "Installés",
 	"plugins.tabs.recommended": "Recommandés",
 	"plugins.tabs.discover": "Découvrir",

package/src/locales/hi.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "इंस्टॉल किए गए",
 	"plugins.tabs.recommended": "अनुशंसित",
 	"plugins.tabs.discover": "खोजें",

package/src/locales/it.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "Installati",
 	"plugins.tabs.recommended": "Consigliati",
 	"plugins.tabs.discover": "Scopri",

package/src/locales/ja.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "インストール済み",
 	"plugins.tabs.recommended": "推奨",
 	"plugins.tabs.discover": "検索",

package/src/locales/ko.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "설치됨",
 	"plugins.tabs.recommended": "권장",
 	"plugins.tabs.discover": "검색",

package/src/locales/pt-br.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "Instalados",
 	"plugins.tabs.recommended": "Recomendados",
 	"plugins.tabs.discover": "Descobrir",

package/src/locales/th.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "ติดตั้งแล้ว",
 	"plugins.tabs.recommended": "แนะนำ",
 	"plugins.tabs.discover": "ค้นหา",

package/src/locales/zh-cn.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "已安装",
 	"plugins.tabs.recommended": "推荐",
 	"plugins.tabs.discover": "发现",

package/src/locales/zh-tw.json

@@ -282,6 +282,8 @@
 	"login.wizard.configSaved": "Configuration saved. You're ready to go!",
 	"login.wizard.failed": "Connection failed — {error}",
 	"login.wizard.retryHint": "Press Escape to skip, or enter a new value:",
+	"gate.noProvider": "No LLM provider configured — run /login to connect one before sending a message.",
+	"gate.noProviderBlock": "No LLM provider configured. Run /login to connect one, then retry. (/help and /model still work.)",
 	"plugins.tabs.installed": "已安裝",
 	"plugins.tabs.recommended": "推薦",
 	"plugins.tabs.discover": "探索",

package/src/main.ts

@@ -165,33 +165,16 @@ async function runInteractiveMode(
 		versionCheckPromise.catch(() => undefined),
 		new Promise<string | undefined>(resolve => setTimeout(() => resolve(undefined), INITIAL_UPDATE_CHECK_TIMEOUT_MS)),
 	]);
-	const initialUpdateStatus = initialUpdateVersion
-		? { available: true, latestVersion: initialUpdateVersion }
-		: undefined;
-
-	const mode = new InteractiveMode(
-		session,
-		version,
-		initialUpdateStatus,
-		setExtensionUIContext,
-		lspServers,
-		mcpManager,
-		eventBus,
-	);
+
+	const mode = new InteractiveMode(session, version, setExtensionUIContext, lspServers, mcpManager, eventBus);
 
 	await mode.init();
 
-	if (!initialUpdateVersion) {
-		versionCheckPromise
-			.then(newVersion => {
-				if (!settings.get("startup.checkUpdate")) {
-					return;
-				}
-				if (newVersion) {
-					mode.setUpdateStatus({ available: true, latestVersion: newVersion });
-				}
-			})
-			.catch(() => {});
+	// Non-blocking, one-shot update notice: only surface it if the background check
+	// already resolved within the startup race (no waiting, no live re-render). If it
+	// resolves later, the update is available on demand via /plugins.
+	if (initialUpdateVersion && settings.get("startup.checkUpdate")) {
+		mode.showStatus(`Update available: v${initialUpdateVersion} — run: xcsh update`, { dim: true });
 	}
 
 	mode.renderInitialMessages();
@@ -717,34 +700,38 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 		sessionManager = await SessionManager.open(selectedPath);
 	}
 
-	// Refresh stale marketplace clones before loading plugins so extensions run latest code.
+	// Refresh stale marketplace clones in the background so startup never blocks on
+	// git/network. Upgraded plugin code applies on the next launch (same trade-off as
+	// the "notify" branch below). Offline/corrupt data is tolerated by the try/catch.
 	const autoUpdate = settings.get("marketplace.autoUpdate");
 	if (autoUpdate !== "off") {
-		try {
-			const startupMgr = new MarketplaceManager({
-				marketplacesRegistryPath: getMarketplacesRegistryPath(),
-				installedRegistryPath: getInstalledPluginsRegistryPath(),
-				projectInstalledRegistryPath: (await resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
-				marketplacesCacheDir: getMarketplacesCacheDir(),
-				pluginsCacheDir: getPluginsCacheDir(),
-				clearPluginRootsCache: (extraPaths?: readonly string[]) => {
-					const h = os.homedir();
-					invalidateFsCache(path.join(h, getConfigDirName(), "plugins", "installed_plugins.json"));
-					for (const p of extraPaths ?? []) invalidateFsCache(p);
-					clearXcshPluginRootsCache();
-				},
-			});
-			await startupMgr.refreshStaleMarketplaces();
-			if (autoUpdate === "auto") {
-				const updates = await startupMgr.checkForUpdates();
-				if (updates.length > 0) {
-					await startupMgr.upgradeAllPlugins();
-					logger.debug(`Auto-upgraded ${updates.length} marketplace plugin(s) at startup`);
+		void (async () => {
+			try {
+				const startupMgr = new MarketplaceManager({
+					marketplacesRegistryPath: getMarketplacesRegistryPath(),
+					installedRegistryPath: getInstalledPluginsRegistryPath(),
+					projectInstalledRegistryPath: (await resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
+					marketplacesCacheDir: getMarketplacesCacheDir(),
+					pluginsCacheDir: getPluginsCacheDir(),
+					clearPluginRootsCache: (extraPaths?: readonly string[]) => {
+						const h = os.homedir();
+						invalidateFsCache(path.join(h, getConfigDirName(), "plugins", "installed_plugins.json"));
+						for (const p of extraPaths ?? []) invalidateFsCache(p);
+						clearXcshPluginRootsCache();
+					},
+				});
+				await startupMgr.refreshStaleMarketplaces();
+				if (autoUpdate === "auto") {
+					const updates = await startupMgr.checkForUpdates();
+					if (updates.length > 0) {
+						await startupMgr.upgradeAllPlugins();
+						logger.debug(`Auto-upgraded ${updates.length} marketplace plugin(s) at startup`);
+					}
 				}
+			} catch {
+				// Network failure, corrupt data, offline — proceed with cached plugins.
 			}
-		} catch {
-			// Network failure, corrupt data, offline — proceed with cached plugins.
-		}
+		})();
 	}
 
 	// Wire --plugin-dir and preload plugin roots for sync consumers (LSP config)