@f5-sales-demo/xcsh 19.61.5 → 19.62.1

package/package.json

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

package/src/browser/capabilities.generated.ts

@@ -26,7 +26,7 @@ export interface ExtensionCapabilities {
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	"version": "0.1.0",
-	"contractVersion": "1.5.0",
+	"contractVersion": "1.6.0",
 	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
@@ -625,6 +625,26 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 			},
 			"flags": {}
 		},
+		{
+			"name": "diag_activation",
+			"summary": "Diagnostic: per-gate tab-activation readiness timings (bridge/worker/page), cold/warm.",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
+		{
+			"name": "diag_ttft",
+			"summary": "Diagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
 		{
 			"name": "capture_login_flow",
 			"summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",
@@ -825,6 +845,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.5.0";
+export const EXTENSION_CONTRACT_VERSION = "1.6.0";
 
-export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","diag_bridges","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];
+export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","diag_bridges","diag_activation","diag_ttft","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];

package/src/browser/capabilities.json

@@ -1,6 +1,6 @@
 {
   "version": "0.1.0",
-  "contractVersion": "1.5.0",
+  "contractVersion": "1.6.0",
   "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
@@ -550,6 +550,26 @@
       },
       "flags": {}
     },
+    {
+      "name": "diag_activation",
+      "summary": "Diagnostic: per-gate tab-activation readiness timings (bridge/worker/page), cold/warm.",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
+    {
+      "name": "diag_ttft",
+      "summary": "Diagnostic: init→first-token timeline (per-stage ms, total, dominant, cold/warm).",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
     {
       "name": "capture_login_flow",
       "summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",

package/src/browser/chat-conformance.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.5.0",
+  "contractVersion": "1.6.0",
   "schemas": {
     "chat_request": {
       "type": "object",
@@ -210,6 +210,19 @@
         },
         "error": {
           "type": "string"
+        },
+        "reason": {
+          "anyOf": [
+            { "const": "bridge-disconnected", "type": "string" },
+            { "const": "bridge-unresponsive", "type": "string" },
+            { "const": "no-worker", "type": "string" },
+            { "const": "session-busy", "type": "string" },
+            { "const": "session-disposed", "type": "string" },
+            { "const": "token-expired", "type": "string" },
+            { "const": "token-expiring", "type": "string" },
+            { "const": "provider-4xx", "type": "string" },
+            { "const": "provider-5xx", "type": "string" }
+          ]
         }
       }
     },
@@ -433,7 +446,8 @@
       "chat_error": {
         "type": "chat_error",
         "id": "c-1111",
-        "error": "HTTP 403 forbidden"
+        "error": "HTTP 403 forbidden",
+        "reason": "provider-4xx"
       },
       "chat_tool_notice": {
         "type": "chat_tool_notice",

package/src/browser/chat-handler.ts

@@ -4,6 +4,7 @@ import {
 	type ChatDelta,
 	type ChatDone,
 	type ChatError,
+	type ChatErrorReason,
 	type ChatReference,
 	type ChatRequest,
 	type InteractionMode,
@@ -52,7 +53,12 @@ export class ChatHandler {
 
 		this.#server.onDisconnected(() => {
 			for (const chat of this.#activeChats.values()) {
-				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "bridge disconnected" });
+				this.#sendTerminal(chat, {
+					type: "chat_error",
+					id: chat.id,
+					error: "bridge disconnected",
+					reason: "bridge-disconnected",
+				});
 				chat.unsubscribe();
 			}
 			this.#activeChats.clear();
@@ -63,7 +69,12 @@ export class ChatHandler {
 		const { id } = req;
 
 		if (this.#session.isStreaming || this.#activeChats.size > 0) {
-			this.#server.send({ type: "chat_error", id, error: "session busy" } satisfies ChatError);
+			this.#server.send({
+				type: "chat_error",
+				id,
+				error: "session busy",
+				reason: "session-busy",
+			} satisfies ChatError);
 			return;
 		}
 
@@ -96,7 +107,7 @@ export class ChatHandler {
 			await this.#session.prompt(prompt, { expandPromptTemplates: false, synthetic: false });
 		} catch (err: unknown) {
 			const message = err instanceof Error ? err.message : "unknown error";
-			this.#sendTerminal(chat, { type: "chat_error", id, error: message });
+			this.#sendTerminal(chat, { type: "chat_error", id, error: message, reason: classifyChatErrorReason(message) });
 		} finally {
 			if (!chat.terminalSent) {
 				this.#sendTerminal(chat, { type: "chat_done", id });
@@ -153,15 +164,22 @@ export class ChatHandler {
 				}
 			} else if (ame.type === "error") {
 				const errorMsg = ame.error?.errorMessage ?? "LLM error";
-				this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: errorMsg });
+				this.#sendTerminal(chat, {
+					type: "chat_error",
+					id: chat.id,
+					error: errorMsg,
+					reason: classifyChatErrorReason(errorMsg),
+				});
 			}
 		} else if (event.type === "message_end" && event.message.role === "assistant") {
 			const msg = event.message as AssistantMessage;
 			if (msg.stopReason === "error") {
+				const errorMsg = msg.errorMessage ?? "assistant error";
 				this.#sendTerminal(chat, {
 					type: "chat_error",
 					id: chat.id,
-					error: msg.errorMessage ?? "assistant error",
+					error: errorMsg,
+					reason: classifyChatErrorReason(errorMsg),
 				});
 			} else {
 				const references = extractReferences(msg);
@@ -194,13 +212,41 @@ export class ChatHandler {
 
 	dispose(): void {
 		for (const chat of this.#activeChats.values()) {
-			this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "session disposed" });
+			this.#sendTerminal(chat, {
+				type: "chat_error",
+				id: chat.id,
+				error: "session disposed",
+				reason: "session-disposed",
+			});
 			chat.unsubscribe();
 		}
 		this.#activeChats.clear();
 	}
 }
 
+/** Best-effort classification of an upstream/provider error message into a
+ * ChatErrorReason so the panel can pick a distinct, actionable message. Returns
+ * undefined for an unclassified error (the panel then shows the raw error text).
+ * Token checks run before the generic 4xx check (a 401 is more useful as an
+ * expired-token hint than a bare client error). */
+export function classifyChatErrorReason(message: string): ChatErrorReason | undefined {
+	const m = message.toLowerCase();
+	if (/\btoken\b[^.]*\b(expir|invalid)|\b(expir|invalid)[^.]*\btoken\b|aws sso|\/context (create|validate)/.test(m)) {
+		return "token-expired";
+	}
+	if (
+		/\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout|econnreset|etimedout|socket hang up|network error/.test(
+			m,
+		)
+	) {
+		return "provider-5xx";
+	}
+	if (/\b4\d\d\b|forbidden|unauthorized|invalid model|bad request|not found|too many requests|rate limit/.test(m)) {
+		return "provider-4xx";
+	}
+	return undefined;
+}
+
 /**
  * Chrome-extension self-awareness prompt. Injected when xcsh is serving a browser
  * chat (not the CLI TUI). Tells the LLM it's in a Chrome side panel alongside the

package/src/browser/chat-protocol.ts

@@ -80,10 +80,30 @@ export interface ChatDone {
 	references?: ChatReference[];
 }
 
+/** Machine-readable cause of a terminal chat_error, so the panel can render a
+ * distinct, actionable message (and decide whether to auto-recover) instead of a
+ * generic failure. Additive/optional on the wire (contract 1.6.0); an omitted
+ * reason means an unclassified error (legacy behavior — show the error text).
+ * Shared vocabulary with the extension (keep both lists identical). */
+export const CHAT_ERROR_REASONS = [
+	"bridge-disconnected", // the worker's bridge closed mid-turn
+	"bridge-unresponsive", // the socket looked open but the worker never answered
+	"no-worker", // no worker is running for this tab
+	"session-busy", // a turn is already in flight for this session
+	"session-disposed", // the worker session was torn down
+	"token-expired", // F5 XC API token expired
+	"token-expiring", // F5 XC API token is about to expire
+	"provider-4xx", // upstream provider rejected the request (client error)
+	"provider-5xx", // upstream provider failed (server error) — retryable
+] as const;
+
+export type ChatErrorReason = (typeof CHAT_ERROR_REASONS)[number];
+
 export interface ChatError {
 	type: "chat_error";
 	id: string;
 	error: string;
+	reason?: ChatErrorReason;
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/manager-core.ts

@@ -131,6 +131,25 @@ export function touchLastSeen(reg: Registry, sessionId: string | undefined, now:
 	return true;
 }
 
+/** True iff this manager should self-recycle because it is running a STALE on-disk
+ * binary. Only for a COMPILED install: after `brew upgrade` + `brew cleanup`, the old
+ * versioned binary the manager was launched from is DELETED, yet the process lingers
+ * on the freed inode — and can no longer spawn workers/spares (spawn ENOENT), which
+ * surfaces as the extension's "xcsh didn't start". Detecting the deleted binary lets
+ * the manager step down so a fresh one (launched from the version-stable PATH wrapper)
+ * takes over. Dev (`bun src/cli.ts`) has a live interpreter execPath → never stale.
+ * Fail-closed: any error from `exists` → NOT stale, so uncertainty never triggers a
+ * recycle loop. Only the unambiguous deleted-binary signal is used (a version/realpath
+ * drift signal was deliberately NOT added — false positives would flap-recycle). */
+export function binaryIsStale(opts: { compiled: boolean; execPath: string; exists: (p: string) => boolean }): boolean {
+	if (!opts.compiled) return false;
+	try {
+		return !opts.exists(opts.execPath);
+	} catch {
+		return false;
+	}
+}
+
 /** The NDJSON keepalive an actively-chatting worker writes to the manager control
  * socket to refresh its `lastSeen` (consumed by `touchLastSeen`). Null for the
  * unbound `spare` sentinel or an empty id — a spare has no session to keep alive. */

package/src/commands/manager.ts

@@ -26,8 +26,11 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 // slows the manager's cold start — keep the daemon's module graph minimal).
 import { VERSION } from "@f5-sales-demo/pi-utils/dirs";
 import { portCandidates } from "../browser/extension-bridge";
+// Lean standalone fn (compiled-runtime detection) — no heavy graph, safe for the daemon.
+import { detectCompiledRuntime } from "../internal-urls/build-info-runtime";
 import { removeManagerState, writeManagerState } from "../services/manager-state";
 import {
+	binaryIsStale,
 	needsProvision,
 	parseControlMsg,
 	pickPort,
@@ -209,6 +212,17 @@ export default class Manager extends Command {
 		// (production always reports the real binary VERSION).
 		const selfVersion = process.env.XCSH_MANAGER_VERSION || VERSION;
 
+		// Durable-upgrade self-recycle (#upgrade-recycle): a compiled manager whose
+		// on-disk binary was removed by `brew upgrade`+`brew cleanup` lingers on the
+		// freed inode but can no longer spawn workers (ENOENT) → it must step down so a
+		// fresh manager (from the version-stable PATH wrapper) takes over. Dev is never
+		// compiled → never stale. `XCSH_FORCE_STALE=1` lets the dev-mode integration test
+		// exercise the recycle path (same env-override convention as XCSH_MANAGER_VERSION).
+		const compiled = detectCompiledRuntime(import.meta.url, Bun.env);
+		const isSelfStale = (): boolean =>
+			process.env.XCSH_FORCE_STALE === "1" ||
+			binaryIsStale({ compiled, execPath: process.execPath, exists: fs.existsSync });
+
 		// Lifecycle gate (#1874): once we begin graceful shutdown we stop accepting
 		// provisions (the host retries the successor manager) and never double-run
 		// the teardown.
@@ -430,13 +444,22 @@ export default class Manager extends Command {
 			const msg = parseControlMsg(raw);
 			if (!msg) return; // fail closed on unknown/invalid frames
 			if (msg.type === "provision") {
-				// Draining: refuse new work so the host retries the successor manager.
-				if (!accepting) {
+				// Draining, OR self-stale (our binary was removed by an upgrade): refuse
+				// this provision so the host retries the successor manager — spawning now
+				// would ENOENT on the deleted binary. If stale-but-still-accepting, step
+				// down immediately so the fresh manager takes over in seconds (not on the
+				// ≤60s sweep). Reuses the existing draining reply/contract.
+				const stale = accepting && isSelfStale();
+				if (!accepting || stale) {
 					try {
 						socket.write(`${JSON.stringify({ type: "draining" })}\n`);
 					} catch {
 						/* client hung up */
 					}
+					if (stale) {
+						console.error("[xcsh manager] binary is stale (upgraded/removed) — recycling on provision");
+						gracefulShutdown("updated");
+					}
 					return;
 				}
 				const provisionReceivedAt = Date.now(); // TTFT Phase 2: start of manager_provision
@@ -537,8 +560,15 @@ export default class Manager extends Command {
 		// Pre-warm the spare pool so provisions can adopt instead of cold-spawn.
 		if (poolTarget > 0) maintainPool();
 
-		// Idle sweep: reap workers untouched for longer than the TTL.
+		// Idle sweep: reap workers untouched for longer than the TTL. Also self-recycle
+		// if our own binary went stale (upgrade removed it) — a lingering deleted-binary
+		// manager can't spawn workers, so step down for a fresh one (#upgrade-recycle).
 		setInterval(() => {
+			if (isSelfStale()) {
+				console.error("[xcsh manager] binary is stale (upgraded/removed) — recycling on sweep");
+				gracefulShutdown("updated");
+				return;
+			}
 			for (const key of staleKeys(reg, Date.now(), IDLE_MS)) reap(key);
 		}, SWEEP_MS);
 

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.5",
-	"commit": "e9f45bc1c87e84c1d99060a016ae1e20907e2210",
-	"shortCommit": "e9f45bc",
+	"version": "19.62.1",
+	"commit": "914880a26dc07e8cbfe5f79dcaef4012e559779d",
+	"shortCommit": "914880a",
 	"branch": "main",
-	"tag": "v19.61.5",
-	"commitDate": "2026-07-08T01:47:55Z",
-	"buildDate": "2026-07-08T02:09:52.692Z",
+	"tag": "v19.62.1",
+	"commitDate": "2026-07-08T16:48:22Z",
+	"buildDate": "2026-07-08T17:15:30.572Z",
 	"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/e9f45bc1c87e84c1d99060a016ae1e20907e2210",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.5"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/914880a26dc07e8cbfe5f79dcaef4012e559779d",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.62.1"
 };