@f5-sales-demo/xcsh 19.58.3 → 19.61.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.58.3",
+	"version": "19.61.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.58.3",
-		"@f5-sales-demo/pi-agent-core": "19.58.3",
-		"@f5-sales-demo/pi-ai": "19.58.3",
-		"@f5-sales-demo/pi-natives": "19.58.3",
-		"@f5-sales-demo/pi-resource-management": "19.58.3",
-		"@f5-sales-demo/pi-tui": "19.58.3",
-		"@f5-sales-demo/pi-utils": "19.58.3",
+		"@f5-sales-demo/xcsh-stats": "19.61.0",
+		"@f5-sales-demo/pi-agent-core": "19.61.0",
+		"@f5-sales-demo/pi-ai": "19.61.0",
+		"@f5-sales-demo/pi-natives": "19.61.0",
+		"@f5-sales-demo/pi-resource-management": "19.61.0",
+		"@f5-sales-demo/pi-tui": "19.61.0",
+		"@f5-sales-demo/pi-utils": "19.61.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/chat-handler.ts

@@ -156,6 +156,12 @@ export class ChatHandler {
 		this.#server.send(frame);
 	}
 
+	/** True while a chat turn is in flight (streaming or an active request). Used by
+	 * the worker's SIGTERM drain to let a running turn finish before teardown (#1874). */
+	get busy(): boolean {
+		return this.#activeChats.size > 0 || this.#session.isStreaming;
+	}
+
 	dispose(): void {
 		for (const chat of this.#activeChats.values()) {
 			this.#sendTerminal(chat, { type: "chat_error", id: chat.id, error: "session disposed" });

package/src/cli/chrome-cli.ts

@@ -7,14 +7,30 @@
  */
 
 import * as fs from "node:fs";
+import { homedir } from "node:os";
 import * as path from "node:path";
 import { acquirePage, type BrowserProviderStatus, CdpBrowserProvider } from "../browser";
 import { PORT_RANGE_END, PORT_RANGE_START, resolveForcedPort } from "../browser/extension-bridge";
 import { installNativeHost } from "../services/native-host-install";
 
+/** Ask a running manager to step down (control-socket `shutdown` frame). Resolves
+ * true if a manager answered the socket, false if none was running. Best-effort. */
+async function requestManagerShutdown(reason: "updated"): Promise<boolean> {
+	const sock = process.env.XCSH_MANAGER_SOCK ?? path.join(homedir(), ".xcsh", "manager.sock");
+	try {
+		const c = await Bun.connect({ unix: sock, socket: { data() {} } });
+		c.write(`${JSON.stringify({ type: "shutdown", reason })}\n`);
+		await Bun.sleep(50);
+		c.end();
+		return true;
+	} catch {
+		return false; // no manager listening
+	}
+}
+
 type Settings = { get(key: string): unknown };
 
-export type ChromeAction = "status" | "relaunch" | "setup" | "install-host";
+export type ChromeAction = "status" | "relaunch" | "setup" | "install-host" | "recycle";
 
 export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";
 
@@ -56,10 +72,15 @@ export function nativeHostLaunchCommand(
 	execPath: string = process.execPath,
 	resolveXcshBin: () => string | null = defaultResolveXcshBin,
 ): string[] {
+	// Prefer a VERSION-STABLE launcher on PATH (e.g. the Homebrew symlink
+	// /opt/homebrew/bin/xcsh) for BOTH compiled and bun installs. This keeps the
+	// native-messaging wrapper working across `brew upgrade`s instead of pinning
+	// the install-time versioned path (…/Cellar/xcsh/<v>/bin/xcsh), which froze
+	// the extension on an old version until install-host was re-run (#1874).
+	const xcsh = resolveXcshBin();
+	if (xcsh) return [xcsh];
 	const base = path.basename(execPath).toLowerCase();
 	if (base.startsWith("bun")) {
-		const xcsh = resolveXcshBin();
-		if (xcsh) return [xcsh];
 		const script = argv[1];
 		if (script && (script.endsWith(".ts") || script.endsWith(".js") || script.endsWith(".mjs"))) {
 			return [execPath, path.resolve(script)];
@@ -111,6 +132,18 @@ export async function runChromeCommand(action: ChromeAction, settings: Settings)
 		const manifestPath = installNativeHost({ launchCommand, extensionIds: [EXTENSION_ID] });
 		return `Native-messaging host manifest written to:\n  ${manifestPath}`;
 	}
+	if (action === "recycle") {
+		// Proactive post-upgrade recycle (#1874 Task 7): refresh the wrapper to the
+		// version-stable launcher, then ask any running (old) manager to step down so
+		// the new version takes effect NOW instead of on the next Chrome launch. The
+		// successor re-adopts live workers (zero-downtime). Both best-effort.
+		const launchCommand = nativeHostLaunchCommand();
+		installNativeHost({ launchCommand, extensionIds: [EXTENSION_ID] });
+		const stepped = await requestManagerShutdown("updated");
+		return stepped
+			? "Refreshed native-host wrapper; asked the running manager to recycle to this version."
+			: "Refreshed native-host wrapper; no manager was running (it will start fresh on next use).";
+	}
 	// relaunch: self-consented rung 3 — force allowRelaunch regardless of the setting.
 	const { mode } = await acquirePage({ settings, allowRelaunch: true });
 	return `Chrome ready (${mode}). Your real, logged-in session is now debuggable for xcsh.`;

package/src/cli/update-cli.ts

@@ -315,6 +315,10 @@ function updateViaBrew(targetPath: string, expectedVersion: string): void {
 	console.log(chalk.yellow(`To update to ${expectedVersion}, run:`));
 	console.log(chalk.cyan(`  brew upgrade ${APP_NAME}`));
 	console.log(chalk.dim("\nThis ensures the update goes through your organization's Homebrew tap."));
+	// #1874 Task 7: brew upgrade runs out-of-band, so we can't recycle automatically.
+	// Nudge the one command that applies it to the Chrome extension immediately.
+	console.log(chalk.dim(`Then run  ${APP_NAME} chrome recycle  to apply it to the extension now`));
+	console.log(chalk.dim("(otherwise it takes effect the next time you open Chrome)."));
 }
 
 /**
@@ -413,6 +417,18 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 				await updateViaBinaryAt(target.path, release.version);
 				break;
 		}
+
+		// #1874 Task 7: the binary just changed under a possibly-running OLD manager.
+		// Proactively recycle so the new version takes effect now instead of on the
+		// next Chrome launch — refresh the native-host wrapper + step the old manager
+		// down (its successor re-adopts live workers, zero-downtime). The just-updated
+		// `xcsh` on PATH is the new version. Best-effort, non-blocking; passive
+		// supersede covers it if this is skipped.
+		try {
+			Bun.spawn(["xcsh", "chrome", "recycle"], { stdout: "ignore", stderr: "ignore" });
+		} catch {
+			/* recycle is a convenience — never fail an update on it */
+		}
 	} catch (err) {
 		console.error(chalk.red(`Update failed: ${err}`));
 		process.exit(1);

package/src/commands/chrome.ts

@@ -5,7 +5,7 @@ import { Args, Command } from "@f5-sales-demo/pi-utils/cli";
 import { type ChromeAction, runChromeCommand } from "../cli/chrome-cli";
 import { Settings, settings } from "../config/settings";
 
-const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup", "install-host"];
+const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup", "install-host", "recycle"];
 
 export default class Chrome extends Command {
 	static description = "Inspect or arrange the Chrome session xcsh drives for console automation";

package/src/commands/manager-core.ts

@@ -10,10 +10,26 @@ export interface WorkerRec {
 
 export type Registry = Map<string, WorkerRec>;
 
+/** Reasons a manager is asked to step down (#1874). Closed set — fail closed. */
+export type ShutdownReason = "superseded" | "updated" | "manual";
+const SHUTDOWN_REASONS = new Set<string>(["superseded", "updated", "manual"]);
+
 export type ControlMsg =
 	| { type: "provision"; sessionId: string; tenant: string }
 	| { type: "release"; sessionId: string }
-	| { type: "status" };
+	| { type: "status" }
+	| { type: "hello" }
+	| { type: "shutdown"; reason: ShutdownReason };
+
+/** The manager's on-disk liveness record (`~/.xcsh/manager.json`), used for
+ * observability and as the escalation target (pid) when a superseded manager
+ * won't release the socket. The control-socket `hello` answer is authoritative. */
+export interface ManagerState {
+	pid: number;
+	version: string;
+	socket: string;
+	startedAt: number;
+}
 
 function isTenant(v: unknown): v is string {
 	return typeof v === "string" && /^[^|]+\|[^|]+$/.test(v);
@@ -30,9 +46,56 @@ export function parseControlMsg(raw: unknown): ControlMsg | null {
 	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 };
+	if (m.type === "hello") return { type: "hello" };
+	if (m.type === "shutdown" && typeof m.reason === "string" && SHUTDOWN_REASONS.has(m.reason))
+		return { type: "shutdown", reason: m.reason as ShutdownReason };
 	return null;
 }
 
+/** Parse a plain `major.minor.patch` version into a numeric tuple, or null. */
+function parseSemver(v: string | null | undefined): [number, number, number] | null {
+	if (typeof v !== "string") return null;
+	const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+	if (!m) return null;
+	return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** True iff `ourVersion` is a valid version strictly greater than a valid
+ * `runningVersion` — the trigger to replace an older manager. Fails closed
+ * (false) on equal/newer/any-unparseable input, so we never downgrade or flap. */
+export function shouldSupersede(runningVersion: string | null, ourVersion: string): boolean {
+	const a = parseSemver(runningVersion);
+	const b = parseSemver(ourVersion);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i++) {
+		if (b[i] > a[i]) return true;
+		if (b[i] < a[i]) return false;
+	}
+	return false; // equal
+}
+
+/** Serialize the manager liveness record for `~/.xcsh/manager.json`. */
+export function serializeManagerState(s: ManagerState): string {
+	return JSON.stringify({ pid: s.pid, version: s.version, socket: s.socket, startedAt: s.startedAt });
+}
+
+/** Parse `~/.xcsh/manager.json`; null on corrupt/missing/ill-shaped input
+ * (a positive pid, non-empty version + socket, and finite startedAt required). */
+export function parseManagerState(text: string): ManagerState | null {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!raw || typeof raw !== "object") return null;
+	const m = raw as Record<string, unknown>;
+	if (typeof m.pid !== "number" || !Number.isInteger(m.pid) || m.pid <= 0) return null;
+	if (!isNonEmpty(m.version) || !isNonEmpty(m.socket)) return null;
+	if (typeof m.startedAt !== "number" || !Number.isFinite(m.startedAt)) return null;
+	return { pid: m.pid, version: m.version, socket: m.socket, startedAt: m.startedAt };
+}
+
 /** Idempotency: only provision when there is no live worker for the sessionId. */
 export function needsProvision(reg: Registry, sessionId: string): boolean {
 	return !reg.has(sessionId);

package/src/commands/manager.ts

@@ -20,7 +20,11 @@ import * as fs from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
+// Lean subpath (not the package barrel, which pulls the winston logger graph and
+// 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";
+import { removeManagerState, writeManagerState } from "../services/manager-state";
 import { needsProvision, parseControlMsg, pickPort, type Registry, sparesToSpawn, staleKeys } from "./manager-core";
 
 /** Reap a worker idle longer than this (ms). */
@@ -50,6 +54,66 @@ function isPortFree(port: number): boolean {
 	}
 }
 
+/** The PID listening on a loopback bridge port, or 0 if unknown (best-effort via
+ * lsof). Used only to give a re-adopted worker a reapable pid; 0 means "manage by
+ * socket liveness, never signal" (see killPid's pid<=0 guard). */
+function pidListeningOn(port: number): number {
+	try {
+		const out = Bun.spawnSync(["lsof", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+			.stdout.toString()
+			.trim()
+			.split("\n")[0];
+		const pid = Number(out);
+		return Number.isInteger(pid) && pid > 0 ? pid : 0;
+	} catch {
+		return 0; // lsof unavailable — leave unknown
+	}
+}
+
+/** Complete the extension `hello` handshake against a bridge port (with the
+ * origin header the bridge requires), resolving the `hello_ack` frame or null.
+ * EXTENSION_ID is lazy-required so it stays off the manager's cold-start path. */
+function bridgeHello(port: number, timeoutMs = 400): Promise<Record<string, unknown> | null> {
+	return new Promise(resolve => {
+		let done = false;
+		const finish = (v: Record<string, unknown> | null) => {
+			if (done) return;
+			done = true;
+			resolve(v);
+		};
+		let ws: WebSocket;
+		try {
+			const { EXTENSION_ID } = require("../cli/chrome-cli");
+			ws = new WebSocket(`ws://127.0.0.1:${port}`, {
+				headers: { Origin: `chrome-extension://${EXTENSION_ID}` },
+			} as unknown as string[]);
+		} catch {
+			return finish(null);
+		}
+		const close = () => {
+			try {
+				ws.close();
+			} catch {
+				/* already closing */
+			}
+		};
+		ws.onopen = () => ws.send(JSON.stringify({ type: "hello" }));
+		ws.onmessage = e => {
+			try {
+				finish(JSON.parse(String(e.data)) as Record<string, unknown>);
+			} catch {
+				finish(null);
+			}
+			close();
+		};
+		ws.onerror = () => finish(null);
+		setTimeout(() => {
+			close();
+			finish(null);
+		}, timeoutMs);
+	});
+}
+
 /**
  * The argv (AFTER `process.execPath`) to re-run THIS binary in `mode`.
  *
@@ -130,6 +194,17 @@ export default class Manager extends Command {
 		const reg: Registry = new Map();
 		const range = portCandidates();
 
+		// The version this manager advertises (hello ack + manager.json). Overridable
+		// via env ONLY so the supersede integration tests can stand up an "old" manager
+		// (production always reports the real binary VERSION).
+		const selfVersion = process.env.XCSH_MANAGER_VERSION || VERSION;
+
+		// Lifecycle gate (#1874): once we begin graceful shutdown we stop accepting
+		// provisions (the host retries the successor manager) and never double-run
+		// the teardown.
+		let accepting = true;
+		let shuttingDown = false;
+
 		const poolTarget = Math.max(0, Math.trunc(Number(process.env.XCSH_WORKER_POOL_SIZE ?? "2")) || 0);
 		interface SpareRec {
 			proc: Bun.Subprocess;
@@ -180,6 +255,34 @@ export default class Manager extends Command {
 			for (let i = 0; i < n; i++) spawnSpare();
 		};
 
+		/** Zero-downtime handoff (#1874 Task 6): on startup, discover bridge workers a
+		 * PRIOR (superseded) manager left running and re-register them, so a tab's
+		 * session survives the manager swap. Probes the whole range in parallel; a
+		 * bridge answering with a real per-tab sessionId (not the "spare" sentinel) and
+		 * a tenant+env is re-adopted. Spares/unknowns are ignored (the pool refills
+		 * them). Best-effort — never throws. */
+		const readoptWorkers = async (): Promise<void> => {
+			const found = await Promise.all(range.map(async port => ({ port, ack: await bridgeHello(port) })));
+			for (const { port, ack } of found) {
+				if (!ack) continue;
+				const sid = ack.sessionId;
+				const tenant = ack.tenant;
+				const env = ack.env;
+				if (typeof sid !== "string" || sid === "spare" || typeof tenant !== "string" || typeof env !== "string") {
+					continue; // spare sentinel or tenant-less bridge — not a re-adoptable session
+				}
+				if (reg.has(sid)) continue;
+				reg.set(sid, {
+					sessionId: sid,
+					tenant: `${tenant}|${env}`,
+					port,
+					pid: pidListeningOn(port),
+					lastSeen: Date.now(),
+				});
+				console.error(`[xcsh manager] re-adopted worker ${sid} (${tenant}|${env}) on port ${port}`);
+			}
+		};
+
 		/** Adopt a warm spare for a provision (bind over IPC). Returns false if none available. */
 		const adoptSpare = (msg: { sessionId: string; tenant: string }): boolean => {
 			const rec = pool.shift();
@@ -204,15 +307,51 @@ export default class Manager extends Command {
 			return true;
 		};
 
+		const killPid = (pid: number): void => {
+			if (pid <= 0) return; // 0/negative = unknown (re-adopted worker) — NEVER signal (kill(0) hits the group)
+			try {
+				process.kill(pid); // SIGTERM — spares exit at once; bound workers self-drain (worker.ts)
+			} catch {
+				/* already gone */
+			}
+		};
+
 		const reap = (sessionId: string): void => {
 			const w = reg.get(sessionId);
 			if (!w) return;
+			killPid(w.pid);
+			reg.delete(sessionId);
+		};
+
+		/** Graceful teardown (#1874): stop accepting, terminate the (session-less)
+		 * spare pool at once, drop the socket + liveness record, and exit. Idempotent.
+		 *
+		 * Bound workers depend on the reason: on a HANDOFF (superseded/updated — a
+		 * successor manager is about to bind and re-adopt them), we LEAVE them running
+		 * so tab sessions survive the swap (zero-downtime, Task 6). Otherwise (manual
+		 * operator SIGTERM — no successor) we SIGTERM them so they drain + exit rather
+		 * than leak. The manager frees the socket immediately either way. */
+		const gracefulShutdown = (reason: string): void => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			accepting = false;
+			const handoff = reason === "superseded" || reason === "updated";
+			console.error(
+				`[xcsh manager] graceful shutdown (${reason}); reaping ${pool.length} spare(s)` +
+					(handoff ? `, leaving ${reg.size} worker(s) for re-adoption` : ` + ${reg.size} worker(s)`),
+			);
+			for (const s of pool.splice(0)) killPid(s.pid);
+			if (!handoff) {
+				for (const w of reg.values()) killPid(w.pid);
+				reg.clear();
+			}
+			removeManagerState(sockPath);
 			try {
-				process.kill(w.pid);
+				fs.rmSync(sockPath, { force: true });
 			} catch {
-				/* already gone */
+				/* best effort — the OS drops the bound socket on exit anyway */
 			}
-			reg.delete(sessionId);
+			process.exit(0);
 		};
 
 		const spawnWorker = (msg: { sessionId: string; tenant: string }): void => {
@@ -257,7 +396,7 @@ export default class Manager extends Command {
 			console.error(`[xcsh manager] provisioned ${msg.sessionId} (${msg.tenant}) → pid ${proc.pid} on port ${port}`);
 		};
 
-		const handleFrame = (line: string): void => {
+		const handleFrame = (line: string, socket: { write(data: string): void }): void => {
 			const trimmed = line.trim();
 			if (!trimmed) return;
 			let raw: unknown;
@@ -269,6 +408,15 @@ 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) {
+					try {
+						socket.write(`${JSON.stringify({ type: "draining" })}\n`);
+					} catch {
+						/* client hung up */
+					}
+					return;
+				}
 				if (needsProvision(reg, msg.sessionId)) {
 					if (!adoptSpare(msg)) spawnWorker(msg); // adopt a warm spare, else cold-spawn (fallback)
 				}
@@ -276,6 +424,19 @@ export default class Manager extends Command {
 				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)
 			} else if (msg.type === "release") {
 				reap(msg.sessionId);
+			} else if (msg.type === "shutdown") {
+				// A newer native-host (supersede) or the updater asks us to step down.
+				gracefulShutdown(msg.reason);
+			} else if (msg.type === "hello") {
+				// Identity handshake (#1874): a newer native-host reads our version to
+				// decide whether to supersede us. Answer over the same connection.
+				try {
+					socket.write(
+						`${JSON.stringify({ type: "manager_hello_ack", version: selfVersion, pid: process.pid })}\n`,
+					);
+				} catch {
+					/* client hung up mid-handshake — ignore */
+				}
 			}
 			// "status" is validated but currently a no-op sink.
 		};
@@ -292,7 +453,7 @@ export default class Manager extends Command {
 					const combined = (buffers.get(socket) ?? "") + data.toString("utf8");
 					const parts = combined.split("\n");
 					buffers.set(socket, parts.pop() ?? ""); // keep the incomplete trailing fragment
-					for (const line of parts) handleFrame(line);
+					for (const line of parts) handleFrame(line, socket as { write(data: string): void });
 				},
 				close(socket: object): void {
 					buffers.delete(socket);
@@ -331,6 +492,20 @@ export default class Manager extends Command {
 		}
 		console.error(`[xcsh manager] control socket listening at ${sockPath}`);
 
+		// Publish our liveness record (#1874) so a newer native-host can see which
+		// version owns the socket (and, if it must supersede us, find our pid).
+		writeManagerState(sockPath, { pid: process.pid, version: selfVersion, socket: sockPath, startedAt: Date.now() });
+
+		// Clean-signal handling: an operator SIGTERM (or upgrade/recycle) tears us
+		// down gracefully instead of orphaning workers + a stale socket/state file.
+		process.on("SIGTERM", () => gracefulShutdown("manual"));
+		process.on("SIGINT", () => gracefulShutdown("manual"));
+
+		// Zero-downtime handoff: re-adopt any bound workers a superseded manager left
+		// running BEFORE filling the pool (so their ports aren't mistaken for free).
+		// Awaited but bounded (~parallel 400ms); the socket already accepts connections.
+		await readoptWorkers();
+
 		// Pre-warm the spare pool so provisions can adopt instead of cold-spawn.
 		if (poolTarget > 0) maintainPool();
 

package/src/commands/native-host.ts

@@ -16,8 +16,12 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { Command } from "@f5-sales-demo/pi-utils/cli";
+// Lean subpath (not the barrel) to keep the relay's cold start minimal.
+import { VERSION } from "@f5-sales-demo/pi-utils/dirs";
 import { decodeNm, encodeNm } from "../browser/native-messaging";
+import { readManagerState } from "../services/manager-state";
 import { reexecArgv } from "./manager";
+import { shouldSupersede } from "./manager-core";
 
 /** Manager control socket — MUST match `commands/manager.ts` exactly. */
 const SOCKET_PATH = process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
@@ -117,11 +121,24 @@ export default class ChromeHost extends Command {
 	 * Returns the connected socket, or undefined if unreachable after backoff.
 	 */
 	private async ensureManager(socket: Parameters<typeof Bun.connect>[0]["socket"]): Promise<Sock | undefined> {
-		try {
-			dbg("connect: first attempt");
-			return await Bun.connect({ unix: SOCKET_PATH, socket });
-		} catch {
-			dbg("connect: failed → spawn detached manager");
+		// Version-aware supersede (#1874): if a manager already owns the socket, read
+		// its version. If THIS binary is newer (e.g. a `brew upgrade` happened but the
+		// old detached manager is still running), ask it to step down and take over —
+		// otherwise the extension stays pinned to the stale version forever. Same-or-
+		// newer running version → just use it (never downgrade).
+		const runningVersion = await this.#managerVersion();
+		if (runningVersion !== null && !shouldSupersede(runningVersion, VERSION)) {
+			dbg(`manager live @ ${runningVersion} (ours ${VERSION}) — connecting`);
+			try {
+				return await Bun.connect({ unix: SOCKET_PATH, socket });
+			} catch {
+				dbg("live manager raced away before relay connect → spawn");
+			}
+		} else if (runningVersion !== null) {
+			dbg(`supersede: running ${runningVersion} < ours ${VERSION} → step down`);
+			await this.#stepDownRunningManager();
+		} else {
+			dbg("no manager reachable → spawn");
 		}
 
 		// Spawn the manager DETACHED and long-lived. It is NOT awaited/retained so
@@ -145,4 +162,92 @@ export default class ChromeHost extends Command {
 		}
 		return undefined;
 	}
+
+	/** The running manager's advertised version via the `hello` handshake, or null
+	 * if none is reachable. Uses a throwaway connection (separate from the relay). */
+	async #managerVersion(timeoutMs = 1500): Promise<string | null> {
+		const ack = await this.#managerRequest({ type: "hello" }, timeoutMs);
+		return typeof ack?.version === "string" ? ack.version : null;
+	}
+
+	/** Send one control frame and resolve the manager's first reply line (or null). */
+	#managerRequest(frame: unknown, timeoutMs: number): Promise<Record<string, unknown> | null> {
+		return new Promise(resolve => {
+			let buf = "";
+			let done = false;
+			const finish = (v: Record<string, unknown> | null) => {
+				if (done) return;
+				done = true;
+				resolve(v);
+			};
+			Bun.connect({
+				unix: SOCKET_PATH,
+				socket: {
+					open(c) {
+						c.write(`${JSON.stringify(frame)}\n`);
+					},
+					data(c, d) {
+						buf += d.toString("utf8");
+						const nl = buf.indexOf("\n");
+						if (nl < 0) return;
+						try {
+							finish(JSON.parse(buf.slice(0, nl)) as Record<string, unknown>);
+						} catch {
+							finish(null);
+						}
+						try {
+							c.end();
+						} catch {
+							/* already closing */
+						}
+					},
+					error() {
+						finish(null);
+					},
+				},
+			}).catch(() => finish(null));
+			setTimeout(() => finish(null), timeoutMs);
+		});
+	}
+
+	/** True if anything is accepting the control socket right now. */
+	async #managerReachable(): Promise<boolean> {
+		try {
+			const c = await Bun.connect({ unix: SOCKET_PATH, socket: { data() {} } });
+			c.end();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/** Ask the running manager to step down, then wait (bounded) for the socket to
+	 * free — escalating to SIGTERM on the recorded pid if it won't release. */
+	async #stepDownRunningManager(timeoutMs = 5000): Promise<void> {
+		try {
+			const c = await Bun.connect({ unix: SOCKET_PATH, socket: { data() {} } });
+			c.write(`${JSON.stringify({ type: "shutdown", reason: "superseded" })}\n`);
+			await Bun.sleep(50);
+			c.end();
+		} catch {
+			/* already gone */
+		}
+		const deadline = Date.now() + timeoutMs;
+		let escalated = false;
+		while (Date.now() < deadline) {
+			if (!(await this.#managerReachable())) return; // socket freed → success
+			if (!escalated && Date.now() > deadline - timeoutMs / 2) {
+				const st = readManagerState(SOCKET_PATH); // won't drain gracefully → SIGTERM the pid
+				if (st?.pid) {
+					try {
+						process.kill(st.pid);
+					} catch {
+						/* already gone */
+					}
+				}
+				escalated = true;
+			}
+			await Bun.sleep(100);
+		}
+	}
 }

package/src/commands/worker.ts

@@ -73,6 +73,9 @@ export function sessionInfoForWorker(): {
 	return { tenant, env, apiUrl, contextBound, sessionId };
 }
 
+/** Hard ceiling for draining an in-flight chat turn on SIGTERM before teardown (#1874). */
+const WORKER_DRAIN_TIMEOUT_MS = 10_000;
+
 /** 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. */
@@ -197,11 +200,24 @@ export default class Worker extends Command {
 		logger.endTiming();
 
 		let shuttingDown = false;
+		const teardown = () => {
+			chatHandler.dispose();
+			void bridge.close().finally(() => process.exit(0));
+		};
 		const shutdown = () => {
 			if (shuttingDown) return;
 			shuttingDown = true;
-			chatHandler.dispose();
-			void bridge.close().finally(() => process.exit(0));
+			// Bounded drain (#1874): if a chat turn is in flight (e.g. the manager is
+			// recycling for an upgrade), let it finish before teardown instead of
+			// aborting the running agent turn — with a hard ceiling so a hung turn can
+			// never wedge shutdown. An idle worker tears down immediately.
+			if (!chatHandler.busy) return teardown();
+			const deadline = Date.now() + WORKER_DRAIN_TIMEOUT_MS;
+			const tick = () => {
+				if (!chatHandler.busy || Date.now() >= deadline) teardown();
+				else setTimeout(tick, 100);
+			};
+			tick();
 		};
 		process.on("SIGTERM", shutdown);
 		process.on("SIGINT", shutdown);

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.58.3",
-	"commit": "1e0e9e203ce3f95f2e4bb1069f4371d9b7529e91",
-	"shortCommit": "1e0e9e2",
+	"version": "19.61.0",
+	"commit": "54faf1b4029f7a7a4251c5cc6776c789b3e1af5c",
+	"shortCommit": "54faf1b",
 	"branch": "main",
-	"tag": "v19.58.3",
-	"commitDate": "2026-07-05T18:06:30Z",
-	"buildDate": "2026-07-05T18:27:55.948Z",
+	"tag": "v19.61.0",
+	"commitDate": "2026-07-05T20:10:34Z",
+	"buildDate": "2026-07-05T20:32:34.362Z",
 	"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/1e0e9e203ce3f95f2e4bb1069f4371d9b7529e91",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.58.3"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/54faf1b4029f7a7a4251c5cc6776c789b3e1af5c",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.61.0"
 };

package/src/services/manager-state.ts

@@ -0,0 +1,48 @@
+/** Filesystem side of the manager liveness record (`manager.json`), kept next to
+ * the control socket so a test's temp socket dir gets its own state file. The
+ * record is advisory/observability + the escalation target (pid) when a
+ * superseded manager won't release the socket; the control-socket `hello` answer
+ * is authoritative. Pure (de)serialization lives in commands/manager-core. */
+import * as fs from "node:fs";
+import { dirname, join } from "node:path";
+import { type ManagerState, parseManagerState, serializeManagerState } from "../commands/manager-core";
+
+/** `manager.json` alongside the given control socket. */
+export function managerStatePathFor(sockPath: string): string {
+	return join(dirname(sockPath), "manager.json");
+}
+
+/** Atomically write the liveness record (temp + rename so readers never see a
+ * torn file). Best-effort: never throws — a failed write must not crash boot. */
+export function writeManagerState(sockPath: string, state: ManagerState): void {
+	const p = managerStatePathFor(sockPath);
+	try {
+		// Restrictive modes: ~/.xcsh holds credentials (contexts/tokens), so the dir
+		// must be user-only (0700) if we're the one creating it, and the record
+		// user-only (0600) regardless of umask. rename() preserves the tmp's mode.
+		fs.mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+		const tmp = `${p}.${process.pid}.tmp`;
+		fs.writeFileSync(tmp, serializeManagerState(state), { mode: 0o600 });
+		fs.renameSync(tmp, p);
+	} catch {
+		/* advisory only — the socket is the source of truth */
+	}
+}
+
+/** Read + validate the record, or null if absent/corrupt. */
+export function readManagerState(sockPath: string): ManagerState | null {
+	try {
+		return parseManagerState(fs.readFileSync(managerStatePathFor(sockPath), "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+/** Remove the record on graceful shutdown. Best-effort. */
+export function removeManagerState(sockPath: string): void {
+	try {
+		fs.rmSync(managerStatePathFor(sockPath), { force: true });
+	} catch {
+		/* best effort */
+	}
+}