@f5-sales-demo/xcsh 19.61.4 → 19.62.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.61.4",
+	"version": "19.62.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",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.61.4",
-		"@f5-sales-demo/pi-agent-core": "19.61.4",
-		"@f5-sales-demo/pi-ai": "19.61.4",
-		"@f5-sales-demo/pi-natives": "19.61.4",
-		"@f5-sales-demo/pi-resource-management": "19.61.4",
-		"@f5-sales-demo/pi-tui": "19.61.4",
-		"@f5-sales-demo/pi-utils": "19.61.4",
+		"@f5-sales-demo/xcsh-stats": "19.62.0",
+		"@f5-sales-demo/pi-agent-core": "19.62.0",
+		"@f5-sales-demo/pi-ai": "19.62.0",
+		"@f5-sales-demo/pi-natives": "19.62.0",
+		"@f5-sales-demo/pi-resource-management": "19.62.0",
+		"@f5-sales-demo/pi-tui": "19.62.0",
+		"@f5-sales-demo/pi-utils": "19.62.0",
 		"@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,
@@ -31,12 +32,19 @@ export class ChatHandler {
 	#session: AgentSession;
 	#activeChats = new Map<string, ActiveChat>();
 	#activeHistoryHint: string | undefined;
+	#onTurnStart: (() => void) | undefined;
 
 	constructor(server: BridgeServer, session: AgentSession) {
 		this.#server = server;
 		this.#session = session;
 	}
 
+	/** Register a callback fired when a chat turn is accepted (used by the worker's
+	 * manager keepalive to refresh lastSeen at turn start). */
+	onTurnStart(cb: () => void): void {
+		this.#onTurnStart = cb;
+	}
+
 	attach(): void {
 		this.#server.onMessage(msg => {
 			if (isChatRequest(msg)) this.#handleChatRequest(msg as unknown as ChatRequest);
@@ -45,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();
@@ -56,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;
 		}
 
@@ -75,6 +93,7 @@ export class ChatHandler {
 			spanEmitted: false,
 		};
 		this.#activeChats.set(id, chat);
+		this.#onTurnStart?.();
 
 		const unsubscribe = this.#session.subscribe((event: AgentSessionEvent) => {
 			this.#handleSessionEvent(chat, event);
@@ -88,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 });
@@ -145,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);
@@ -186,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

@@ -17,7 +17,9 @@ const SHUTDOWN_REASONS = new Set<string>(["superseded", "updated", "manual"]);
 export type ControlMsg =
 	| { type: "provision"; sessionId: string; tenant: string }
 	| { type: "release"; sessionId: string }
-	| { type: "status" }
+	// An sid-less status is the legacy no-op sink; an sid-carrying status is a
+	// keepalive from an actively-chatting worker (see keepaliveFrame/touchLastSeen).
+	| { type: "status"; sessionId?: string }
 	| { type: "hello" }
 	| { type: "shutdown"; reason: ShutdownReason };
 
@@ -42,7 +44,8 @@ function isNonEmpty(v: unknown): v is string {
 export function parseControlMsg(raw: unknown): ControlMsg | null {
 	if (!raw || typeof raw !== "object") return null;
 	const m = raw as Record<string, unknown>;
-	if (m.type === "status") return { type: "status" };
+	if (m.type === "status")
+		return isNonEmpty(m.sessionId) ? { type: "status", sessionId: m.sessionId } : { type: "status" };
 	if (m.type === "provision" && isNonEmpty(m.sessionId) && isTenant(m.tenant))
 		return { type: "provision", sessionId: m.sessionId, tenant: m.tenant };
 	if (m.type === "release" && isNonEmpty(m.sessionId)) return { type: "release", sessionId: m.sessionId };
@@ -115,6 +118,27 @@ export function staleKeys(reg: Registry, now: number, idleMs: number): string[]
 	return out;
 }
 
+/** Refresh a worker's `lastSeen` from a keepalive/status frame; true iff a known
+ * session was touched. The manager never sees chat traffic (it flows worker↔
+ * bridge↔extension), so an actively-used session would otherwise be idle-reaped
+ * mid-conversation. An actively-chatting worker emits `keepaliveFrame` to drive
+ * this, keeping its session out of `staleKeys`. */
+export function touchLastSeen(reg: Registry, sessionId: string | undefined, now: number): boolean {
+	if (!sessionId) return false;
+	const w = reg.get(sessionId);
+	if (!w) return false;
+	w.lastSeen = now;
+	return true;
+}
+
+/** 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. */
+export function keepaliveFrame(sessionId: string): string | null {
+	if (!sessionId || sessionId === "spare") return null;
+	return `${JSON.stringify({ type: "status", sessionId })}\n`;
+}
+
 /** How many new spares to spawn now to reach `target`, without exceeding the port
  * budget: spares + active workers must fit the discovery range. Never negative. */
 export function sparesToSpawn(

package/src/commands/manager-keepalive.ts

@@ -0,0 +1,117 @@
+/**
+ * Worker→manager keepalive client.
+ *
+ * The manager idle-reaps a worker whose `lastSeen` is older than `IDLE_MS`, and
+ * `lastSeen` is refreshed ONLY when the manager receives a control frame. Chat
+ * traffic flows worker↔bridge↔extension and never reaches the manager, so an
+ * actively-used-then-briefly-idle session used to be reaped mid-conversation
+ * (the "Turn aborted." after a break). This client emits a `status{sessionId}`
+ * keepalive over the manager's UNIX control socket while a turn is in flight and
+ * at each turn start, so the manager's sweep leaves an in-use session alive.
+ *
+ * The socket lifecycle (connect/reconnect) is injected as a `Connector` so the
+ * scheduling/emit logic is unit-testable without a real socket; the worker wires
+ * a `Bun.connect` transport. Best-effort throughout: if the manager socket is
+ * down (e.g. mid-supersede) emits are dropped and the next emit reconnects — so
+ * after a manager handoff the keepalive re-targets the successor manager, which
+ * has already re-adopted this worker.
+ */
+import { keepaliveFrame } from "./manager-core";
+
+/** A live connection to the manager control socket. */
+export interface KeepaliveTransport {
+	write(data: string): void;
+	close(): void;
+}
+
+/** Opens a transport; `onClose` MUST be invoked when the connection drops so the
+ * keepalive knows to reconnect on its next emit. Returns null if it cannot open. */
+export type Connector = (onClose: () => void) => Promise<KeepaliveTransport | null>;
+
+export interface ManagerKeepaliveDeps {
+	connect: Connector;
+	/** Current worker session id (may transition from "spare" to a real id). */
+	sessionId: () => string;
+	/** True while a chat turn is in flight. */
+	busy: () => boolean;
+}
+
+export class ManagerKeepalive {
+	#deps: ManagerKeepaliveDeps;
+	#transport: KeepaliveTransport | null = null;
+	#connecting = false;
+	#pending = false; // a keepalive is due once a connection is (re)established
+	#stopped = false;
+
+	constructor(deps: ManagerKeepaliveDeps) {
+		this.#deps = deps;
+	}
+
+	/** Periodic tick (driven by the worker's interval): emit iff a turn is busy. */
+	tick(): void {
+		if (this.#deps.busy()) this.#emit();
+	}
+
+	/** One-shot emit at the start of each turn — refreshes lastSeen immediately so
+	 * a session with long think-time between turns is never reaped between them. */
+	turnStart(): void {
+		this.#emit();
+	}
+
+	/** Stop emitting and close any open transport. */
+	stop(): void {
+		this.#stopped = true;
+		this.#pending = false;
+		this.#transport?.close();
+		this.#transport = null;
+	}
+
+	#emit(): void {
+		if (this.#stopped) return;
+		const frame = keepaliveFrame(this.#deps.sessionId());
+		if (!frame) return; // spare / unbound → nothing to keep alive (also skips connecting)
+		if (this.#transport) {
+			try {
+				this.#transport.write(frame);
+			} catch {
+				this.#transport = null; // dead socket → drop and reconnect on next emit
+				this.#pending = true;
+				void this.#ensureConnected();
+			}
+			return;
+		}
+		this.#pending = true;
+		void this.#ensureConnected();
+	}
+
+	async #ensureConnected(): Promise<void> {
+		if (this.#stopped || this.#transport || this.#connecting) return;
+		this.#connecting = true;
+		let t: KeepaliveTransport | null = null;
+		try {
+			t = await this.#deps.connect(() => {
+				this.#transport = null; // socket dropped → next emit reconnects
+			});
+		} catch {
+			t = null;
+		}
+		this.#connecting = false;
+		if (!t) return; // manager unreachable — best-effort, a later emit retries
+		if (this.#stopped) {
+			t.close();
+			return;
+		}
+		this.#transport = t;
+		if (this.#pending) {
+			this.#pending = false;
+			const frame = keepaliveFrame(this.#deps.sessionId());
+			if (frame) {
+				try {
+					this.#transport.write(frame);
+				} catch {
+					this.#transport = null;
+				}
+			}
+		}
+	}
+}

package/src/commands/manager.ts

@@ -11,6 +11,8 @@
  *          on sessionId, so two tabs of the SAME tenant get two workers.
  *   {"type":"release","sessionId":"tab-7"}  → kill + forget that session's worker
  *   {"type":"status"}                        → accepted; no-op sink
+ *   {"type":"status","sessionId":"tab-7"}    → keepalive: refresh that worker's
+ *          lastSeen so an actively-chatting session is not idle-reaped
  *
  * All registry/port/idempotency/idle policy is the pure `manager-core`; this file
  * is the thin I/O shell (socket, spawn, kill, timer) around it. A background sweep
@@ -25,7 +27,15 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { VERSION } from "@f5-sales-demo/pi-utils/dirs";
 import { portCandidates } from "../browser/extension-bridge";
 import { removeManagerState, writeManagerState } from "../services/manager-state";
-import { needsProvision, parseControlMsg, pickPort, type Registry, sparesToSpawn, staleKeys } from "./manager-core";
+import {
+	needsProvision,
+	parseControlMsg,
+	pickPort,
+	type Registry,
+	sparesToSpawn,
+	staleKeys,
+	touchLastSeen,
+} from "./manager-core";
 
 /** Reap a worker idle longer than this (ms). */
 const IDLE_MS = 20 * 60_000;
@@ -434,8 +444,13 @@ export default class Manager extends Command {
 					const managerProvisionMs = Date.now() - provisionReceivedAt;
 					if (!adoptSpare(msg, managerProvisionMs)) spawnWorker(msg, managerProvisionMs); // adopt a warm spare, else cold-spawn (fallback)
 				}
-				const w = reg.get(msg.sessionId);
-				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)
+				touchLastSeen(reg, msg.sessionId, Date.now()); // touch on every provision (keep-alive)
+			} else if (msg.type === "status") {
+				// Keepalive from an actively-chatting worker (#idle-reap): refresh
+				// lastSeen so the idle sweep never reaps a session that is in use.
+				// Chat traffic never reaches the manager, so this is the only signal
+				// that an otherwise-quiet-to-the-manager worker is still working.
+				touchLastSeen(reg, msg.sessionId, Date.now());
 			} else if (msg.type === "release") {
 				reap(msg.sessionId);
 			} else if (msg.type === "shutdown") {
@@ -452,7 +467,6 @@ export default class Manager extends Command {
 					/* client hung up mid-handshake — ignore */
 				}
 			}
-			// "status" is validated but currently a no-op sink.
 		};
 
 		// Per-connection NDJSON buffer: a control frame can be split across two TCP

package/src/commands/worker.ts

@@ -13,6 +13,8 @@
  * `XCSH_SESSION_TENANT` so it advertises its assigned tenant even before a context
  * is bound. This lets the extension panel lock onto the right tenant immediately.
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { getProjectDir, getXCSHConfigDir, logger } from "@f5-sales-demo/pi-utils";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
 import { ChatHandler } from "../browser/chat-handler";
@@ -25,6 +27,7 @@ import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
 import { deriveTenantEnv } from "../services/xcsh-env";
+import { type KeepaliveTransport, ManagerKeepalive } from "./manager-keepalive";
 
 /** Mutable worker identity. Seeded from env at spawn (backward compat); replaced by a
  * late IPC bind on a pre-warmed spare. `null` fields fall back to env, then the "spare"
@@ -77,6 +80,16 @@ export function sessionInfoForWorker(): {
 /** Hard ceiling for draining an in-flight chat turn on SIGTERM before teardown (#1874). */
 const WORKER_DRAIN_TIMEOUT_MS = 10_000;
 
+/** How often the worker pings the manager while a turn is in flight, refreshing its
+ * lastSeen so an actively-chatting session is never idle-reaped. Comfortably under
+ * the manager's IDLE_MS (20 min); a turn also pings once at its start. */
+const KEEPALIVE_MS = 60_000;
+
+/** The manager control socket (same derivation as native-host / chrome-cli). */
+function managerSockPath(): string {
+	return process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
+}
+
 /** Browser-automation tool set — identical scoping to `main.ts`'s extension path.
  * With scoped tools the ONLY way to create a resource is the form-driven workflow
  * runner, which is exactly what the human watching the browser wants. */
@@ -274,6 +287,38 @@ export default class Worker extends Command {
 		const chatHandler = new ChatHandler(bridge, session);
 		chatHandler.attach();
 
+		// Manager keepalive: while a turn is in flight (and at each turn start), ping
+		// the manager control socket so it refreshes this worker's lastSeen and its
+		// idle sweep does not reap an actively-used session mid-conversation. Chat
+		// traffic never reaches the manager, so this is the only liveness signal.
+		// Best-effort + self-reconnecting: a dropped socket (e.g. manager supersede)
+		// is re-opened on the next emit, re-targeting the successor manager.
+		const keepalive = new ManagerKeepalive({
+			sessionId: () => sessionInfoForWorker().sessionId ?? "spare",
+			busy: () => chatHandler.busy,
+			connect: async onClose => {
+				try {
+					const sock = await Bun.connect({
+						unix: managerSockPath(),
+						socket: { data() {}, close: () => onClose(), error: () => onClose() },
+					});
+					const transport: KeepaliveTransport = {
+						write: data => {
+							sock.write(data);
+						},
+						close: () => {
+							sock.end();
+						},
+					};
+					return transport;
+				} catch {
+					return null; // manager not reachable — a later emit retries
+				}
+			},
+		});
+		chatHandler.onTurnStart(() => keepalive.turnStart());
+		const keepaliveTimer = setInterval(() => keepalive.tick(), KEEPALIVE_MS);
+
 		// session-ready. Emit the per-tab boot breakdown when requested (parity with
 		// main.ts:1002-1009). PI_TIMING=x prints then exits — used by bench/extension-session.ts
 		// to measure total worker cold-start; otherwise this is a no-op.
@@ -287,6 +332,8 @@ export default class Worker extends Command {
 
 		let shuttingDown = false;
 		const teardown = () => {
+			clearInterval(keepaliveTimer);
+			keepalive.stop();
 			chatHandler.dispose();
 			void bridge.close().finally(() => process.exit(0));
 		};

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.61.4",
-	"commit": "8697bc5fee06350b861c8c8bf7bbac1f00f85408",
-	"shortCommit": "8697bc5",
+	"version": "19.62.0",
+	"commit": "002bc2b7d7e14a95e282f940730cbdc347197635",
+	"shortCommit": "002bc2b",
 	"branch": "main",
-	"tag": "v19.61.4",
-	"commitDate": "2026-07-07T16:14:37Z",
-	"buildDate": "2026-07-07T16:40:48.327Z",
+	"tag": "v19.62.0",
+	"commitDate": "2026-07-08T02:22:10Z",
+	"buildDate": "2026-07-08T02:45:44.169Z",
 	"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/8697bc5fee06350b861c8c8bf7bbac1f00f85408",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.4"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/002bc2b7d7e14a95e282f940730cbdc347197635",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.62.0"
 };