@f5-sales-demo/xcsh 19.58.2 → 19.60.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.58.2",
+	"version": "19.60.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.2",
-		"@f5-sales-demo/pi-agent-core": "19.58.2",
-		"@f5-sales-demo/pi-ai": "19.58.2",
-		"@f5-sales-demo/pi-natives": "19.58.2",
-		"@f5-sales-demo/pi-resource-management": "19.58.2",
-		"@f5-sales-demo/pi-tui": "19.58.2",
-		"@f5-sales-demo/pi-utils": "19.58.2",
+		"@f5-sales-demo/xcsh-stats": "19.60.0",
+		"@f5-sales-demo/pi-agent-core": "19.60.0",
+		"@f5-sales-demo/pi-ai": "19.60.0",
+		"@f5-sales-demo/pi-natives": "19.60.0",
+		"@f5-sales-demo/pi-resource-management": "19.60.0",
+		"@f5-sales-demo/pi-tui": "19.60.0",
+		"@f5-sales-demo/pi-utils": "19.60.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

@@ -56,10 +56,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)];

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). */
@@ -130,6 +134,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;
@@ -215,6 +230,38 @@ export default class Manager extends Command {
 			reg.delete(sessionId);
 		};
 
+		const killPid = (pid: number): void => {
+			try {
+				process.kill(pid); // SIGTERM — spares exit at once; bound workers self-drain (worker.ts)
+			} catch {
+				/* already gone */
+			}
+		};
+
+		/** Graceful teardown (#1874): stop accepting, terminate the (session-less)
+		 * spare pool at once, SIGTERM bound workers so they drain their in-flight turn,
+		 * drop the socket + liveness record, and exit. Idempotent. Bounded by each
+		 * worker's own drain ceiling — the manager frees the socket immediately so a
+		 * successor can bind without waiting on drains. */
+		const gracefulShutdown = (reason: string): void => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			accepting = false;
+			console.error(
+				`[xcsh manager] graceful shutdown (${reason}); reaping ${pool.length} spare(s) + ${reg.size} worker(s)`,
+			);
+			for (const s of pool.splice(0)) killPid(s.pid);
+			for (const w of reg.values()) killPid(w.pid);
+			reg.clear();
+			removeManagerState(sockPath);
+			try {
+				fs.rmSync(sockPath, { force: true });
+			} catch {
+				/* best effort — the OS drops the bound socket on exit anyway */
+			}
+			process.exit(0);
+		};
+
 		const spawnWorker = (msg: { sessionId: string; tenant: string }): void => {
 			// Registry-dedupe (pickPort) over only the ports free at the OS level.
 			const port = pickPort(reg, range.filter(isPortFree));
@@ -257,7 +304,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 +316,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 +332,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 +361,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 +400,15 @@ 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"));
+
 		// 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

@@ -23,7 +23,7 @@ import { initializeWithSettings } from "../discovery";
 import { createAgentSession } from "../sdk";
 import { activateTenantContext } from "../services/session-context-binding";
 import { ContextService } from "../services/xcsh-context";
-import { sessionKeyFromUrl } from "../services/xcsh-env";
+import { deriveTenantEnv } from "../services/xcsh-env";
 
 /** 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"
@@ -64,19 +64,18 @@ export function sessionInfoForWorker(): {
 		/* ContextService not initialized — fall through to the tenant key; contextBound stays false. */
 	}
 	apiUrl = apiUrl ?? process.env.XCSH_API_URL ?? null;
-	if (apiUrl) {
-		const key = sessionKeyFromUrl(apiUrl);
-		return { tenant: key?.tenant ?? null, env: key?.env ?? null, apiUrl, contextBound, sessionId };
-	}
-	// Contextless: advertise the tenant carried by the bind (or spawn env).
-	const raw = boundIdentity?.tenantKey ?? process.env.XCSH_SESSION_TENANT;
-	if (raw) {
-		const [tenant, env] = raw.split("|");
-		return { tenant: tenant || null, env: env || null, apiUrl: null, contextBound, sessionId };
-	}
-	return { tenant: null, env: null, apiUrl: null, contextBound, sessionId };
+	// Prefer the apiUrl-derived key (active context wins), but fall back to the
+	// tenant this worker was assigned (IPC bind or spawn env) so an apiUrl whose
+	// host we can't parse never blanks a KNOWN tenant — which would make the
+	// extension drop the bridge and show "No xcsh running for this tenant" (#1872).
+	const tenantKey = boundIdentity?.tenantKey ?? process.env.XCSH_SESSION_TENANT ?? null;
+	const { tenant, env } = deriveTenantEnv(apiUrl, tenantKey);
+	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. */
@@ -201,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.2",
-	"commit": "c666636feed4f03e00897187bb494b2bed0f27e9",
-	"shortCommit": "c666636",
+	"version": "19.60.0",
+	"commit": "37266bce39f1c2714a947ebfcbd9dbae46b312a0",
+	"shortCommit": "37266bc",
 	"branch": "main",
-	"tag": "v19.58.2",
-	"commitDate": "2026-07-05T17:19:13Z",
-	"buildDate": "2026-07-05T17:40:57.828Z",
+	"tag": "v19.60.0",
+	"commitDate": "2026-07-05T19:32:50Z",
+	"buildDate": "2026-07-05T20:00:48.862Z",
 	"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/c666636feed4f03e00897187bb494b2bed0f27e9",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.58.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/37266bce39f1c2714a947ebfcbd9dbae46b312a0",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.60.0"
 };

package/src/main.ts

@@ -815,7 +815,7 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 		// tenant), so the panel can lock its session and route per tenant.
 		{
 			const { ContextService } = await import("./services/xcsh-context");
-			const { sessionKeyFromUrl } = await import("./services/xcsh-env");
+			const { deriveTenantEnv } = await import("./services/xcsh-env");
 			const readInfo = () => {
 				let apiUrl: string | null = null;
 				let contextBound = false;
@@ -828,15 +828,13 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 				}
 				// Fall back to the env override when no context is active (env-only mode).
 				apiUrl = apiUrl ?? process.env.XCSH_API_URL ?? null;
-				const key = apiUrl ? sessionKeyFromUrl(apiUrl) : null;
+				// Prefer the apiUrl-derived key; fall back to the assigned tenant key so an
+				// unparseable apiUrl never blanks a known tenant (#1872). Same contract as
+				// the worker path (sessionInfoForWorker).
+				const tenantKey = process.env.XCSH_SESSION_TENANT ?? null;
+				const { tenant, env } = deriveTenantEnv(apiUrl, tenantKey);
 				// Interactive path has no per-tab XCSH_SESSION_ID; workers echo one, this doesn't.
-				return {
-					tenant: key?.tenant ?? null,
-					env: key?.env ?? null,
-					apiUrl,
-					contextBound,
-					sessionId: null,
-				};
+				return { tenant, env, apiUrl, contextBound, sessionId: null };
 			};
 			bridgeServer.setSessionInfo(readInfo);
 			ContextService.onContextChange(() => bridgeServer?.broadcastTenantChanged());

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 */
+	}
+}

package/src/services/xcsh-env.ts

@@ -128,6 +128,31 @@ export function sessionKeyFromUrl(url: string | undefined): SessionKey | null {
 	return null;
 }
 
+/**
+ * Resolve the `{tenant, env}` a worker advertises to the extension's `hello`
+ * handshake. Prefers the session key parsed from `apiUrl` (the live/active
+ * context is authoritative) but falls back to the worker's assigned tenant key
+ * (`"tenant|env"`, from `boundIdentity.tenantKey` / `XCSH_SESSION_TENANT`) when
+ * `apiUrl` is absent OR its host doesn't parse to a key.
+ *
+ * The fallback is load-bearing (#1872): the extension's `liveTenants` filter
+ * keeps a bridge only when BOTH `tenant` and `env` are set, so returning
+ * `{tenant:null, env:null}` for a worker that KNOWS its tenant (e.g. an
+ * activated context whose stored `apiUrl` isn't `<tenant>.console.ves.volterra.io`)
+ * silently drops the bridge and the panel shows "No xcsh running for this tenant".
+ */
+export function deriveTenantEnv(
+	apiUrl: string | null,
+	tenantKey: string | null | undefined,
+): { tenant: string | null; env: string | null } {
+	const key = apiUrl ? sessionKeyFromUrl(apiUrl) : null;
+	const [assignedTenant, assignedEnv] = (tenantKey ?? "").split("|");
+	return {
+		tenant: key?.tenant ?? (assignedTenant || null),
+		env: key?.env ?? (assignedEnv || null),
+	};
+}
+
 /**
  * Reduce an API URL to its origin (`https://host[:port]`) — the canonical stored
  * form for a context endpoint.