@f5-sales-demo/xcsh 19.55.0 → 19.55.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.55.0",
+	"version": "19.55.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",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.55.0",
-		"@f5-sales-demo/pi-agent-core": "19.55.0",
-		"@f5-sales-demo/pi-ai": "19.55.0",
-		"@f5-sales-demo/pi-natives": "19.55.0",
-		"@f5-sales-demo/pi-resource-management": "19.55.0",
-		"@f5-sales-demo/pi-tui": "19.55.0",
-		"@f5-sales-demo/pi-utils": "19.55.0",
+		"@f5-sales-demo/xcsh-stats": "19.55.1",
+		"@f5-sales-demo/pi-agent-core": "19.55.1",
+		"@f5-sales-demo/pi-ai": "19.55.1",
+		"@f5-sales-demo/pi-natives": "19.55.1",
+		"@f5-sales-demo/pi-resource-management": "19.55.1",
+		"@f5-sales-demo/pi-tui": "19.55.1",
+		"@f5-sales-demo/pi-utils": "19.55.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/extension-bridge.ts

@@ -108,7 +108,9 @@ export class BridgeServer {
 	/** Stable per-process session id, advertised to the extension on `hello`. */
 	#sessionId = `sess-${crypto.randomUUID()}`;
 	/** Provider of this process's tenant identity, answering the `hello` handshake. */
-	#sessionInfo: (() => { tenant: string | null; env: string | null; apiUrl: string | null }) | null = null;
+	#sessionInfo:
+		| (() => { tenant: string | null; env: string | null; apiUrl: string | null; contextBound: boolean })
+		| null = null;
 
 	/** The port the WebSocket server is listening on (0 = not bound). */
 	get port(): number {
@@ -145,13 +147,15 @@ export class BridgeServer {
 
 	/** Set the tenant-identity provider that answers the extension's `hello`
 	 * handshake with `{ tenant, env, apiUrl }` for THIS xcsh process/context. */
-	setSessionInfo(cb: () => { tenant: string | null; env: string | null; apiUrl: string | null }): void {
+	setSessionInfo(
+		cb: () => { tenant: string | null; env: string | null; apiUrl: string | null; contextBound: boolean },
+	): void {
 		this.#sessionInfo = cb;
 	}
 
 	/** Push a tenant change to all connected panels (e.g. after `/context activate`). */
 	broadcastTenantChanged(): void {
-		const info = this.#sessionInfo?.() ?? { tenant: null, env: null, apiUrl: null };
+		const info = this.#sessionInfo?.() ?? { tenant: null, env: null, apiUrl: null, contextBound: false };
 		for (const c of this.#clients.values()) {
 			try {
 				c.send(JSON.stringify({ type: "tenant_changed", sessionId: this.#sessionId, ...info }));
@@ -249,7 +253,7 @@ export class BridgeServer {
 			ws.send(JSON.stringify({ type: "pong" }));
 		} else if (msg.type === "hello") {
 			// Identity handshake: tell the extension which tenant this process serves.
-			const info = this.#sessionInfo?.() ?? { tenant: null, env: null, apiUrl: null };
+			const info = this.#sessionInfo?.() ?? { tenant: null, env: null, apiUrl: null, contextBound: false };
 			const { EXTENSION_CONTRACT_VERSION } = require("./capabilities.generated");
 			ws.send(
 				JSON.stringify({
@@ -259,6 +263,7 @@ export class BridgeServer {
 					tenant: info.tenant,
 					env: info.env,
 					apiUrl: info.apiUrl,
+					contextBound: info.contextBound,
 					pid: process.pid,
 				}),
 			);

package/src/cli/chrome-cli.ts

@@ -6,12 +6,15 @@
  * touching Chrome, settings, or the network.
  */
 
+import * as fs from "node:fs";
+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";
 
 type Settings = { get(key: string): unknown };
 
-export type ChromeAction = "status" | "relaunch" | "setup";
+export type ChromeAction = "status" | "relaunch" | "setup" | "install-host";
 
 export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";
 
@@ -22,6 +25,49 @@ export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";
  */
 export const WEB_STORE_URL = `https://chromewebstore.google.com/detail/${EXTENSION_ID}`;
 
+/** Find a compiled `xcsh` binary on PATH (self-contained; survives Chrome's stripped env). */
+function defaultResolveXcshBin(): string | null {
+	const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+	for (const dir of dirs) {
+		const candidate = path.join(dir, "xcsh");
+		try {
+			fs.accessSync(candidate, fs.constants.X_OK);
+			return candidate;
+		} catch {
+			/* not on this PATH entry */
+		}
+	}
+	return null;
+}
+
+/**
+ * Resolve the exec prefix Chrome's launcher wrapper should invoke to reach the
+ * `chrome-host` relay (the wrapper appends `chrome-host "$@"`).
+ *
+ * Compiled: `process.execPath` IS the xcsh binary → ["<xcsh>"].
+ * Dev (`bun /abs/src/cli.ts …`): `process.execPath` is bun, which fails under
+ * Chrome's stripped env for a `.ts` entry — so prefer a compiled `xcsh` on PATH
+ * when resolvable; otherwise fall back to ["<bun>", "<abs entry script>"]. The
+ * script is resolved to an ABSOLUTE path because Chrome launches the host from an
+ * arbitrary working directory.
+ */
+export function nativeHostLaunchCommand(
+	argv: string[] = process.argv,
+	execPath: string = process.execPath,
+	resolveXcshBin: () => string | null = defaultResolveXcshBin,
+): string[] {
+	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)];
+		}
+	}
+	return [execPath];
+}
+
 export function renderStatus(s: BrowserProviderStatus): string {
 	const yn = (b: boolean) => (b ? "yes" : "no");
 	return [
@@ -56,6 +102,15 @@ export async function runChromeCommand(action: ChromeAction, settings: Settings)
 			`Install/keep the xcsh Chrome extension from the Web Store:\n  ${WEB_STORE_URL}`
 		);
 	}
+	if (action === "install-host") {
+		// Chrome ignores a manifest `args` field and can't select the `chrome-host`
+		// subcommand, so the manifest `path` points at a generated wrapper that execs
+		// the resolved xcsh with `chrome-host`. Resolve the launch prefix here (reads
+		// process.execPath/argv/PATH); installNativeHost stays a pure writer.
+		const launchCommand = nativeHostLaunchCommand();
+		const manifestPath = installNativeHost({ launchCommand, extensionIds: [EXTENSION_ID] });
+		return `Native-messaging host manifest written to:\n  ${manifestPath}`;
+	}
 	// 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.ts

@@ -52,16 +52,19 @@ const commands: CommandEntry[] = [
 	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{ name: "chrome", load: () => import("./commands/chrome").then(m => m.default) },
+	{ name: "chrome-host", load: () => import("./commands/native-host").then(m => m.default) },
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
+	{ name: "manager", load: () => import("./commands/manager").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
 	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
 	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "worker", load: () => import("./commands/worker").then(m => m.default) },
 	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
 ];
 
@@ -90,11 +93,17 @@ export function runCli(argv: string[]): Promise<void> {
 	// Everything else that isn't a known subcommand routes to "launch".
 	const first = argv[0];
 	const runArgv =
-		first === "--help" || first === "-h" || first === "--version" || first === "-v" || first === "help"
-			? argv
-			: isSubcommand(first)
+		// Chrome launches the native-messaging host with the calling extension's
+		// origin (chrome-extension://…/) as the first arg. Route that to the
+		// `chrome-host` relay — a safety net if a manifest `path` points straight at
+		// the binary instead of the launcher wrapper.
+		first?.startsWith("chrome-extension://")
+			? ["chrome-host", ...argv]
+			: first === "--help" || first === "-h" || first === "--version" || first === "-v" || first === "help"
 				? argv
-				: ["launch", ...argv];
+				: isSubcommand(first)
+					? argv
+					: ["launch", ...argv];
 	return run({ bin: APP_NAME, version: VERSION, argv: runArgv, commands, help: showHelp });
 }
 

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"];
+const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup", "install-host"];
 
 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

@@ -0,0 +1,49 @@
+/** Pure worker-registry + control-protocol logic for the manager. No I/O. */
+
+export interface WorkerRec {
+	tenantKey: string; // "tenant|env"
+	port: number;
+	pid: number;
+	lastSeen: number; // epoch ms
+}
+
+export type Registry = Map<string, WorkerRec>;
+
+export type ControlMsg =
+	| { type: "provision"; tenantKey: string }
+	| { type: "release"; tenantKey: string }
+	| { type: "status" };
+
+function isTenantKey(v: unknown): v is string {
+	return typeof v === "string" && /^[^|]+\|[^|]+$/.test(v);
+}
+
+/** Validate an inbound control frame; null if malformed (fail closed). */
+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 === "provision" || m.type === "release") && isTenantKey(m.tenantKey)) {
+		return { type: m.type, tenantKey: m.tenantKey };
+	}
+	return null;
+}
+
+/** Idempotency: only provision when there is no live worker for the key. */
+export function needsProvision(reg: Registry, tenantKey: string): boolean {
+	return !reg.has(tenantKey);
+}
+
+/** Lowest free port in the range not already held by a worker. */
+export function pickPort(reg: Registry, range: number[]): number | null {
+	const used = new Set([...reg.values()].map(w => w.port));
+	for (const p of range) if (!used.has(p)) return p;
+	return null;
+}
+
+/** Keys whose worker has been idle longer than idleMs. */
+export function staleKeys(reg: Registry, now: number, idleMs: number): string[] {
+	const out: string[] = [];
+	for (const w of reg.values()) if (now - w.lastSeen > idleMs) out.push(w.tenantKey);
+	return out;
+}

package/src/commands/manager.ts

@@ -0,0 +1,217 @@
+/**
+ * Manager mode — `xcsh manager`.
+ *
+ * A detached, long-lived control server that owns the fleet of per-tenant
+ * `xcsh worker` processes. It listens on a UNIX SOCKET (`~/.xcsh/manager.sock`,
+ * override `XCSH_MANAGER_SOCK`) for NDJSON control frames — one JSON object per
+ * line — validated by the pure `manager-core` protocol:
+ *
+ *   {"type":"provision","tenantKey":"acme|staging"}  → spawn a worker (idempotent)
+ *   {"type":"release","tenantKey":"acme|staging"}     → kill + forget the worker
+ *   {"type":"status"}                                 → accepted; no-op sink
+ *
+ * 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
+ * reaps workers idle longer than the TTL. The process blocks forever.
+ */
+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";
+import { portCandidates } from "../browser/extension-bridge";
+import { needsProvision, parseControlMsg, pickPort, type Registry, staleKeys } from "./manager-core";
+
+/** Reap a worker idle longer than this (ms). */
+const IDLE_MS = 20 * 60_000;
+/** How often the idle sweep runs (ms). */
+const SWEEP_MS = 60_000;
+
+/**
+ * Whether a loopback TCP port is bindable RIGHT NOW. `pickPort` only dedupes
+ * against the manager's own registry; a range port can still be held by another
+ * app, a stale worker, or a second manager. We pre-filter the range with this so
+ * a spawned worker (which binds its forced `XCSH_BRIDGE_PORT` strictly) never
+ * lands on an occupied port and dies. Bun.listen binds and throws synchronously,
+ * so this stays sync — keeping provision idempotency race-free.
+ */
+function isPortFree(port: number): boolean {
+	try {
+		const listener = Bun.listen({
+			hostname: "127.0.0.1",
+			port,
+			socket: { data() {}, open() {}, close() {}, error() {} },
+		});
+		listener.stop(true);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The argv (AFTER `process.execPath`) to re-run THIS binary in `mode`.
+ *
+ * Dev: launched as `bun /abs/src/cli.ts manager`, so `process.argv[1]` is the
+ * script path → `["/abs/src/cli.ts", <mode>]`, and `process.execPath` is bun.
+ *
+ * Compiled: `process.execPath` IS the xcsh binary and `process.argv[1]` is the
+ * subcommand (e.g. "manager"), not a script file → `[<mode>]`.
+ *
+ * We detect dev by the script extension so the integration tests — which run
+ * `bun src/cli.ts <mode>` — re-exec a genuinely working subcommand. Shared by
+ * the manager (worker re-exec) and the chrome-host (manager re-exec).
+ */
+export function reexecArgv(mode: "worker" | "manager"): string[] {
+	const script = process.argv[1];
+	if (script && (script.endsWith(".ts") || script.endsWith(".js") || script.endsWith(".mjs"))) {
+		return [script, mode];
+	}
+	return [mode];
+}
+
+/** The argv (AFTER `process.execPath`) to re-run THIS binary in `worker` mode. */
+export function workerArgv(): string[] {
+	return reexecArgv("worker");
+}
+
+export default class Manager extends Command {
+	static description = "Run the detached control server that spawns/reaps per-tenant workers; blocks forever";
+
+	async run(): Promise<void> {
+		const sockPath = process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
+		fs.mkdirSync(dirname(sockPath), { recursive: true });
+
+		const reg: Registry = new Map();
+		const range = portCandidates();
+
+		const reap = (tenantKey: string): void => {
+			const w = reg.get(tenantKey);
+			if (!w) return;
+			try {
+				process.kill(w.pid);
+			} catch {
+				/* already gone */
+			}
+			reg.delete(tenantKey);
+		};
+
+		const spawnWorker = (tenantKey: string): void => {
+			// Registry-dedupe (pickPort) over only the ports free at the OS level.
+			const port = pickPort(reg, range.filter(isPortFree));
+			if (port === null) {
+				console.error(`[xcsh manager] port range exhausted; cannot provision ${tenantKey}`);
+				return;
+			}
+			const proc = Bun.spawn([process.execPath, ...workerArgv()], {
+				env: {
+					...process.env,
+					XCSH_BROWSER_PROVIDER: "extension",
+					XCSH_SESSION_TENANT: tenantKey,
+					XCSH_BRIDGE_PORT: String(port),
+					// Isolate the worker's tenant binding: an ambient XCSH_API_URL in the
+					// manager's env would make sdk.ts skip the XCSH_SESSION_TENANT branch and
+					// bind hello_ack.tenant from the env apiUrl instead. Clear both so the
+					// spawned tenant key is authoritative (undefined removes the var in Bun).
+					XCSH_API_URL: undefined,
+					XCSH_API_TOKEN: undefined,
+				},
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			reg.set(tenantKey, { tenantKey, port, pid: proc.pid, lastSeen: Date.now() });
+			// Reconcile a dead worker: when THIS process exits (crash, forced-port
+			// EADDRINUSE with no retry, etc.), drop its registry entry so the next
+			// provision respawns instead of finding a zombie. Guard on pid so an
+			// already-respawned entry for the same tenant is never clobbered.
+			proc.exited.then(() => {
+				const cur = reg.get(tenantKey);
+				if (cur && cur.pid === proc.pid) reg.delete(tenantKey);
+			});
+			console.error(`[xcsh manager] provisioned ${tenantKey} → pid ${proc.pid} on port ${port}`);
+		};
+
+		const handleFrame = (line: string): void => {
+			const trimmed = line.trim();
+			if (!trimmed) return;
+			let raw: unknown;
+			try {
+				raw = JSON.parse(trimmed);
+			} catch {
+				return; // malformed line — ignore, keep serving
+			}
+			const msg = parseControlMsg(raw);
+			if (!msg) return; // fail closed on unknown/invalid frames
+			if (msg.type === "provision") {
+				if (needsProvision(reg, msg.tenantKey)) spawnWorker(msg.tenantKey);
+				const w = reg.get(msg.tenantKey);
+				if (w) w.lastSeen = Date.now(); // touch on every provision (keep-alive)
+			} else if (msg.type === "release") {
+				reap(msg.tenantKey);
+			}
+			// "status" is validated but currently a no-op sink.
+		};
+
+		// Per-connection NDJSON buffer: a control frame can be split across two TCP
+		// reads, so we only parse complete newline-terminated lines and retain any
+		// trailing fragment until the rest of it arrives. Keyed by socket (WeakMap
+		// so a closed connection's buffer is collected without manual bookkeeping).
+		const buffers = new WeakMap<object, string>();
+		const socketConfig = {
+			unix: sockPath,
+			socket: {
+				data(socket: object, data: Buffer): void {
+					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);
+				},
+				close(socket: object): void {
+					buffers.delete(socket);
+				},
+			},
+		};
+
+		// Single-manager invariant — probe liveness BEFORE binding.
+		//
+		// Two chrome-hosts can cold-start concurrently, both find no socket, and
+		// both spawn a manager. `Bun.listen({unix})` SILENTLY unlinks and rebinds
+		// any existing socket path — it does NOT throw EADDRINUSE even when a live
+		// manager is accepting on it (verified on Bun 1.3.x, in- and cross-process).
+		// So a naive `listen` would clobber the first manager's socket, leaving it
+		// orphaned on an unlinked path (blocking forever, leaking its worker ports)
+		// while a second live manager takes over — breaking "at most one manager".
+		//
+		// Guard by CONNECTING first: if a live manager answers, this process lost
+		// the race and exits WITHOUT touching the socket file (it belongs to the
+		// live manager). If nothing answers, the path is free or a STALE file from
+		// a crashed manager — either way `Bun.listen` safely (re)binds it (its own
+		// unlink-and-rebind reclaims the stale file; no explicit rm needed).
+		let liveOwner = false;
+		try {
+			const probe = await Promise.race([
+				Bun.connect({ unix: sockPath, socket: { data() {} } }),
+				new Promise<never>((_, reject) =>
+					setTimeout(() => reject(new Error("manager liveness probe timeout")), 500),
+				),
+			]);
+			liveOwner = true;
+			probe.end();
+		} catch {
+			/* nothing accepting → free path, or a stale socket file from a crashed manager */
+		}
+		if (liveOwner) {
+			console.error(`[xcsh manager] another manager already live at ${sockPath}; exiting`);
+			process.exit(0);
+		}
+		Bun.listen(socketConfig);
+		console.error(`[xcsh manager] control socket listening at ${sockPath}`);
+
+		// Idle sweep: reap workers untouched for longer than the TTL.
+		setInterval(() => {
+			for (const key of staleKeys(reg, Date.now(), IDLE_MS)) reap(key);
+		}, SWEEP_MS);
+
+		// Detached, long-lived: block until the process is torn down.
+		await new Promise<never>(() => {});
+	}
+}

package/src/commands/native-host.ts

@@ -0,0 +1,148 @@
+/**
+ * `chrome-host` — native-messaging relay subcommand.
+ *
+ * Launched by Chrome as the native-messaging host. It is a thin relay between
+ * Chrome's stdio (native-messaging framing: 4-byte LE length + JSON) and the
+ * long-lived `xcsh manager` control server's UNIX socket (newline-delimited
+ * JSON). No business logic lives here.
+ *
+ * Unlike a plain relay, the host ENSURES the manager before relaying: if the
+ * control socket can't be connected (manager not yet running), it spawns a
+ * DETACHED, long-lived `xcsh manager` and retries with a short backoff. The
+ * ensure is idempotent — if the first connect succeeds no manager is spawned,
+ * so we never launch two. If the manager still can't be reached after the
+ * backoff we exit cleanly (0); the extension retries the whole bootstrap.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Command } from "@f5-sales-demo/pi-utils/cli";
+import { decodeNm, encodeNm } from "../browser/native-messaging";
+import { reexecArgv } from "./manager";
+
+/** Manager control socket — MUST match `commands/manager.ts` exactly. */
+const SOCKET_PATH = process.env.XCSH_MANAGER_SOCK ?? join(homedir(), ".xcsh", "manager.sock");
+
+/** Connect-retry budget after (re)spawning the manager: ~2s total. */
+const CONNECT_RETRIES = 20;
+const CONNECT_BACKOFF_MS = 100;
+
+// Diagnostic relay tracing, OFF unless ~/.xcsh/chrome-host-debug exists. Security:
+// writes to a 0600 file in the user's home, lifecycle + byte-counts ONLY — never
+// message content — and never to stdout (that would corrupt the NM stream).
+function dbg(msg: string): void {
+	try {
+		const fs = require("node:fs");
+		const home = process.env.HOME || homedir();
+		if (!fs.existsSync(join(home, ".xcsh", "chrome-host-debug"))) return;
+		const fd = fs.openSync(join(home, ".xcsh", "chrome-host.log"), "a", 0o600);
+		fs.appendFileSync(fd, `${new Date().toISOString()} pid=${process.pid} ${msg}\n`);
+		fs.closeSync(fd);
+	} catch {
+		/* logging must never break the relay */
+	}
+}
+
+type Sock = Awaited<ReturnType<typeof Bun.connect>>;
+
+export default class ChromeHost extends Command {
+	static description = "Native-messaging relay between Chrome and the xcsh manager socket (internal)";
+
+	async run(): Promise<void> {
+		let socketBuffer = "";
+		const socketHandlers = {
+			data(_sock: Sock, chunk: Uint8Array): void {
+				// Manager → Chrome: NDJSON lines → native-messaging frames.
+				socketBuffer += new TextDecoder().decode(chunk);
+				let newlineIndex = socketBuffer.indexOf("\n");
+				while (newlineIndex !== -1) {
+					const line = socketBuffer.slice(0, newlineIndex);
+					socketBuffer = socketBuffer.slice(newlineIndex + 1);
+					if (line.length > 0) {
+						dbg(`socket→chrome ${line.length}B`);
+						// Guard the parse/encode: a malformed manager line would otherwise
+						// throw INSIDE this Bun socket callback. Drop it (trace only) — never
+						// surface the error on stdout, which is the native-messaging stream.
+						try {
+							process.stdout.write(encodeNm(JSON.parse(line)));
+						} catch {
+							dbg("socket→chrome drop: malformed line");
+						}
+					}
+					newlineIndex = socketBuffer.indexOf("\n");
+				}
+			},
+			close(): void {
+				dbg("manager socket closed → exit");
+				process.exit(0);
+			},
+			error(): void {
+				dbg("manager socket error → exit");
+				process.exit(0);
+			},
+		};
+
+		dbg(`start sock=${SOCKET_PATH} argc=${process.argv.length}`);
+		const socket = await this.ensureManager(socketHandlers);
+		if (!socket) {
+			// Manager unreachable after ensure — exit cleanly; the extension retries.
+			dbg("ensureManager: unreachable → exit");
+			process.exit(0);
+		}
+
+		// Chrome stdin → manager: native-messaging frames → NDJSON lines.
+		dbg("reading chrome stdin");
+		let stdinBuffer: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+		for await (const chunk of process.stdin) {
+			const bytes = new Uint8Array(chunk);
+			const next = new Uint8Array(stdinBuffer.length + bytes.length);
+			next.set(stdinBuffer, 0);
+			next.set(bytes, stdinBuffer.length);
+			const { messages, rest } = decodeNm(next);
+			stdinBuffer = rest;
+			for (const msg of messages) {
+				dbg(`chrome→socket ${JSON.stringify(msg).length}B`);
+				socket.write(`${JSON.stringify(msg)}\n`);
+			}
+		}
+
+		// Chrome closed stdin — tear down and exit.
+		dbg("chrome stdin EOF → exit");
+		socket.end();
+		process.exit(0);
+	}
+
+	/**
+	 * Connect to the manager, spawning a detached one if the first connect fails.
+	 * Idempotent: a successful first connect spawns nothing (never two managers).
+	 * 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");
+		}
+
+		// Spawn the manager DETACHED and long-lived. It is NOT awaited/retained so
+		// it outlives this host process; on macOS killing the host does not kill it.
+		Bun.spawn([process.execPath, ...reexecArgv("manager")], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+
+		// Retry-connect with a short backoff while the manager binds its socket.
+		for (let i = 0; i < CONNECT_RETRIES; i++) {
+			await Bun.sleep(CONNECT_BACKOFF_MS);
+			try {
+				const s = await Bun.connect({ unix: SOCKET_PATH, socket });
+				dbg(`connect: succeeded after ${i + 1} retries`);
+				return s;
+			} catch {
+				/* manager not bound yet — keep retrying */
+			}
+		}
+		return undefined;
+	}
+}

package/src/commands/worker.ts

@@ -0,0 +1,144 @@
+/**
+ * Headless worker mode — `xcsh worker`.
+ *
+ * A non-interactive process that starts the Chrome-extension bridge, creates ONE
+ * agent session bound to this worker's tenant (`XCSH_SESSION_TENANT`, matched to a
+ * context by the session-context bootstrap in `createAgentSession`), attaches the
+ * chat handler, and blocks until SIGTERM/SIGINT. It mirrors the extension-bridge
+ * startup path in `main.ts` (bridge → setSessionInfo → browser-only tool scoping →
+ * createAgentSession → ChatHandler.attach) MINUS the TUI.
+ *
+ * Unlike the interactive path — whose `hello_ack` tenant is derived purely from the
+ * active context's apiUrl (null when contextless) — the worker also falls back to
+ * `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 { getProjectDir, getXCSHConfigDir } from "@f5-sales-demo/pi-utils";
+import { Command } from "@f5-sales-demo/pi-utils/cli";
+import { ChatHandler } from "../browser/chat-handler";
+import { startBridgeServer } from "../browser/extension-bridge";
+import { setSharedBridgeServer } from "../browser/provider";
+import { initializeWithSettings } from "../discovery";
+import { createAgentSession } from "../sdk";
+import { ContextService } from "../services/xcsh-context";
+import { sessionKeyFromUrl } from "../services/xcsh-env";
+
+/** Tenant identity for the `hello` handshake. The active context wins; when the
+ * worker is contextless we parse `XCSH_SESSION_TENANT` (`tenant|env`) so the panel
+ * still learns which tenant this process serves (apiUrl stays null). Must be sync —
+ * the bridge invokes it synchronously while answering `hello`. */
+export function sessionInfoForWorker(): {
+	tenant: string | null;
+	env: string | null;
+	apiUrl: string | null;
+	contextBound: boolean;
+} {
+	let apiUrl: string | null = null;
+	let contextBound = false;
+	try {
+		apiUrl = ContextService.instance.activeApiUrl;
+		// A worker is "context-bound" when it has an active stored context (not just an env-derived apiUrl).
+		contextBound = ContextService.instance.getStatus().activeContextName != null;
+	} catch {
+		/* ContextService not initialized — fall through to env; 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 };
+	}
+	// Contextless: the worker's assigned tenant is carried in XCSH_SESSION_TENANT.
+	const raw = process.env.XCSH_SESSION_TENANT;
+	if (raw) {
+		const [tenant, env] = raw.split("|");
+		return { tenant: tenant || null, env: env || null, apiUrl: null, contextBound };
+	}
+	return { tenant: null, env: null, apiUrl: null, contextBound };
+}
+
+/** 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. */
+const BROWSER_TOOL_NAMES = [
+	"catalog_workflow_runner",
+	"navigate",
+	"click",
+	"click_element",
+	"fill",
+	"type_text",
+	"screenshot",
+	"login",
+	"read_ax",
+	"get_page_context",
+	"query_dom",
+	"find",
+	"wait_for",
+	"key_press",
+	"select_option",
+	"label_select",
+	"scroll_to",
+	"annotate",
+	"set_explain_mode",
+];
+
+export default class Worker extends Command {
+	static description = "Run a headless extension-bridge worker (no TUI); blocks until SIGTERM";
+
+	async run(): Promise<void> {
+		process.env.XCSH_BROWSER_PROVIDER = "extension";
+
+		const cwd = getProjectDir();
+		const { Settings, settings } = await import("../config/settings");
+		await Settings.init({ cwd });
+
+		// Init the ContextService singleton so the session-context bootstrap (Task 3)
+		// can match XCSH_SESSION_TENANT to a stored context, and so sessionInfoForWorker
+		// can read the active apiUrl once bound.
+		try {
+			ContextService.init(getXCSHConfigDir());
+		} catch {
+			/* already initialized / unavailable — continue. */
+		}
+
+		// Provider persistence for model discovery (parity with main.ts).
+		initializeWithSettings(settings);
+
+		// Quiet startup: skip the welcome screen + blocking plugin "Fix now?" prompts.
+		settings.override("startup.quiet", true);
+
+		// INSTANT-ON: start the bridge before the heavy session init so the extension
+		// can connect immediately. Honors XCSH_BRIDGE_PORT (forced) or auto-selects.
+		const bridge = await startBridgeServer();
+		console.error(`[xcsh worker] extension bridge listening on ws://127.0.0.1:${bridge.port}`);
+		setSharedBridgeServer(bridge);
+		bridge.setSessionInfo(sessionInfoForWorker);
+		ContextService.onContextChange(() => bridge.broadcastTenantChanged());
+
+		const { session } = await createAgentSession({
+			cwd,
+			hasUI: false,
+			toolNames: BROWSER_TOOL_NAMES,
+			// Headless worker: no MCP discovery, no LSP warmup, no extension discovery —
+			// keep startup lean and free of network calls / blocking prompts.
+			enableMCP: false,
+			enableLsp: false,
+			disableExtensionDiscovery: true,
+		});
+
+		const chatHandler = new ChatHandler(bridge, session);
+		chatHandler.attach();
+
+		let shuttingDown = false;
+		const shutdown = () => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			chatHandler.dispose();
+			void bridge.close().finally(() => process.exit(0));
+		};
+		process.on("SIGTERM", shutdown);
+		process.on("SIGINT", shutdown);
+
+		// Block until a signal tears us down.
+		await new Promise<never>(() => {});
+	}
+}

package/src/extensibility/extensions/bundled/herdr-reporter.ts

@@ -1,23 +1,77 @@
+import { connect } from "node:net";
 import type { ExtensionAPI } from "@f5-sales-demo/xcsh";
 
 /**
  * herdr integration (bundled, default-on).
  *
- * Reports xcsh's live agent state to the herdr terminal multiplexer over its
- * socket API so an xcsh pane shows up as a first-class "xcsh" assistant with an
- * idle / working / blocked indicator.
+ * Reports xcsh's live agent state to the herdr terminal multiplexer so an xcsh
+ * pane shows up as a first-class "xcsh" assistant with an idle / working /
+ * blocked indicator.
+ *
+ * Transport: herdr injects `HERDR_SOCKET_PATH` into every pane, so state is
+ * reported by writing a newline-delimited JSON-RPC request straight to that unix
+ * socket. This is PATH-independent — unlike shelling out to the `herdr` CLI,
+ * which silently no-ops when herdr runs as a launchd/`brew services` server and
+ * spawns panes without `/opt/homebrew/bin` on PATH. If `HERDR_SOCKET_PATH` is
+ * somehow unset, we fall back to the `herdr` CLI.
  *
  * xcsh is a fork of pi; a user may have both installed, so this reporter always
  * identifies itself as "xcsh" (never "pi") and claims pane authority via
- * `--source xcsh` so herdr's passive pi-detection heuristics cannot mislabel the
- * pane.
+ * `source: "xcsh"` so herdr's passive pi-detection heuristics cannot mislabel
+ * the pane.
  *
  * The extension is completely inert unless it is running inside a herdr pane
- * (detected via the `HERDR_PANE_ID` environment variable herdr injects), so it
- * has zero effect for users who do not run xcsh under herdr.
+ * (detected via `HERDR_PANE_ID`), so it has zero effect for users who do not run
+ * xcsh under herdr.
  */
 
 const HERDR_AGENT_LABEL = "xcsh";
+const REPORT_METHOD = "pane.report_agent";
+const RELEASE_METHOD = "pane.release_agent";
+const SOCKET_TIMEOUT_MS = 2000;
+
+/**
+ * Write one newline-delimited JSON-RPC request to herdr's unix socket and close.
+ * Fire-and-forget: the response is ignored and every failure path is reported
+ * via `onError` without throwing, so a dead socket never disturbs the agent.
+ */
+function sendToHerdrSocket(
+	socketPath: string,
+	method: string,
+	params: Record<string, unknown>,
+	onError: (err: unknown) => void,
+): void {
+	const conn = connect({ path: socketPath });
+	// Never let a report keep xcsh's event loop alive.
+	conn.unref();
+	conn.once("error", err => {
+		onError(err);
+		conn.destroy();
+	});
+	conn.once("connect", () => {
+		conn.end(`${JSON.stringify({ id: "xcsh:herdr-reporter", method, params })}\n`);
+	});
+	conn.setTimeout(SOCKET_TIMEOUT_MS, () => conn.destroy());
+}
+
+/** Translate a JSON-RPC report/release into `herdr` CLI arguments (fallback). */
+function toCliArgs(method: string, params: Record<string, unknown>): string[] {
+	const subcommand = method === REPORT_METHOD ? "report-agent" : "release-agent";
+	const args = [
+		"pane",
+		subcommand,
+		String(params.pane_id),
+		"--source",
+		String(params.source),
+		"--agent",
+		String(params.agent),
+	];
+	if (params.state !== undefined) {
+		args.push("--state", String(params.state));
+	}
+	args.push("--seq", String(params.seq));
+	return args;
+}
 
 export default function herdrReporter(pi: ExtensionAPI): void {
 	const paneId = process.env.HERDR_PANE_ID;
@@ -33,29 +87,30 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 
 	pi.setLabel(HERDR_AGENT_LABEL);
 
-	// Fire-and-forget: a missing or failing herdr CLI must never disturb the agent.
-	const runHerdr = (args: string[]): void => {
-		pi.exec("herdr", args).catch((err: unknown) => {
-			pi.logger.debug("herdr report failed", {
-				error: err instanceof Error ? err.message : String(err),
-			});
+	const onError = (err: unknown): void => {
+		pi.logger.debug("herdr report failed", {
+			error: err instanceof Error ? err.message : String(err),
 		});
 	};
 
+	const send = (method: string, params: Record<string, unknown>): void => {
+		const socketPath = process.env.HERDR_SOCKET_PATH;
+		if (socketPath) {
+			sendToHerdrSocket(socketPath, method, params, onError);
+			return;
+		}
+		// Fallback for the rare case herdr did not inject a socket path.
+		pi.exec("herdr", toCliArgs(method, params)).catch(onError);
+	};
+
 	const report = (state: "idle" | "working" | "blocked"): void => {
-		runHerdr([
-			"pane",
-			"report-agent",
-			paneId,
-			"--source",
-			HERDR_AGENT_LABEL,
-			"--agent",
-			HERDR_AGENT_LABEL,
-			"--state",
+		send(REPORT_METHOD, {
+			pane_id: paneId,
+			source: HERDR_AGENT_LABEL,
+			agent: HERDR_AGENT_LABEL,
 			state,
-			"--seq",
-			String(seq++),
-		]);
+			seq: seq++,
+		});
 	};
 
 	// Announce presence as soon as the session is initialized.
@@ -87,16 +142,11 @@ export default function herdrReporter(pi: ExtensionAPI): void {
 
 	// Relinquish pane authority so herdr stops showing xcsh once we exit.
 	pi.on("session_shutdown", () => {
-		runHerdr([
-			"pane",
-			"release-agent",
-			paneId,
-			"--source",
-			HERDR_AGENT_LABEL,
-			"--agent",
-			HERDR_AGENT_LABEL,
-			"--seq",
-			String(seq++),
-		]);
+		send(RELEASE_METHOD, {
+			pane_id: paneId,
+			source: HERDR_AGENT_LABEL,
+			agent: HERDR_AGENT_LABEL,
+			seq: seq++,
+		});
 	});
 }

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.55.0",
-	"commit": "d4705fb3ced007a59e110d11971eb25c3dc9e83f",
-	"shortCommit": "d4705fb",
+	"version": "19.55.1",
+	"commit": "48c9f78cdcabe71d95cc97b067c64119f03fb22d",
+	"shortCommit": "48c9f78",
 	"branch": "main",
-	"tag": "v19.55.0",
-	"commitDate": "2026-07-02T22:38:12Z",
-	"buildDate": "2026-07-02T23:02:06.036Z",
+	"tag": "v19.55.1",
+	"commitDate": "2026-07-03T01:03:31Z",
+	"buildDate": "2026-07-03T01:25:43.578Z",
 	"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/d4705fb3ced007a59e110d11971eb25c3dc9e83f",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.55.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/48c9f78cdcabe71d95cc97b067c64119f03fb22d",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.55.1"
 };

package/src/main.ts

@@ -826,15 +826,18 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 			const { sessionKeyFromUrl } = await import("./services/xcsh-env");
 			const readInfo = () => {
 				let apiUrl: string | null = null;
+				let contextBound = false;
 				try {
 					apiUrl = ContextService.instance.activeApiUrl;
+					// Context-bound when a stored context is active (not just an env-derived apiUrl).
+					contextBound = ContextService.instance.getStatus().activeContextName != null;
 				} catch {
 					/* ContextService not initialized */
 				}
 				// 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;
-				return { tenant: key?.tenant ?? null, env: key?.env ?? null, apiUrl };
+				return { tenant: key?.tenant ?? null, env: key?.env ?? null, apiUrl, contextBound };
 			};
 			bridgeServer.setSessionInfo(readInfo);
 			ContextService.onContextChange(() => bridgeServer?.broadcastTenantChanged());

package/src/sdk.ts

@@ -783,9 +783,28 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const svc = ContextService.instance; // inited in main.ts (throws for SDK/tests → caught)
 		if (!process.env.XCSH_API_URL) {
 			const bound = existingSession.activeContextName; // resumed binding, if any
-			const available = (await svc.listContexts()).map(c => c.name);
-			const folderContext = await svc.resolveFolderContextName(cwd);
-			const autoBind = resolveAutoBind({ kind: "cli", availableContexts: available, folderContext });
+			const contexts = await svc.listContexts();
+			const available = contexts.map(c => c.name);
+			const tenantKey = process.env.XCSH_SESSION_TENANT;
+			let autoBind: ReturnType<typeof resolveAutoBind>;
+			if (tenantKey) {
+				// Extension worker: match a context to this worker's tenant.
+				const { sessionKeyFromUrl } = await import("./services/xcsh-env");
+				const contextTenantKeys: Record<string, string> = {};
+				for (const c of contexts) {
+					const key = c.apiUrl ? sessionKeyFromUrl(c.apiUrl) : null;
+					if (key) contextTenantKeys[c.name] = `${key.tenant}|${key.env}`;
+				}
+				autoBind = resolveAutoBind({
+					kind: "extension",
+					availableContexts: available,
+					tenantKey,
+					contextTenantKeys,
+				});
+			} else {
+				const folderContext = await svc.resolveFolderContextName(cwd);
+				autoBind = resolveAutoBind({ kind: "cli", availableContexts: available, folderContext });
+			}
 			const choice = chooseSessionContext(bound, autoBind);
 			if ("activate" in choice) {
 				try {

package/src/services/native-host-install.ts

@@ -0,0 +1,63 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Chrome native-messaging host name (matches the pre-WS-transition host). */
+export const NATIVE_HOST_NAME = "com.xcsh.xcsh.chrome_host";
+
+function nativeHostDir(home: string, platform: NodeJS.Platform): string {
+	if (platform === "darwin")
+		return path.join(home, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+	if (platform === "linux") return path.join(home, ".config", "google-chrome", "NativeMessagingHosts");
+	throw new Error(`native-host install unsupported on platform '${platform}' (macOS/Linux only)`);
+}
+
+/** Single-quote a token for a POSIX `sh` command line (safe for spaces/specials). */
+function shQuote(token: string): string {
+	return `'${token.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Idempotently write the user-level NM host manifest AND its launcher wrapper.
+ * Returns the manifest path.
+ *
+ * Chrome native-messaging manifests support ONLY {name, description, path, type,
+ * allowed_origins} — Chrome does NOT honor an `args` field, and when it launches
+ * the host it passes the calling extension's origin as argv[1] to `path`. So the
+ * manifest CANNOT point straight at the xcsh binary (that would run the default
+ * `launch`/TUI, never `chrome-host`). Instead `path` points at a generated
+ * executable wrapper that execs the real xcsh with the `chrome-host` subcommand
+ * and forwards Chrome's args ("$@"). `launchCommand` is the resolved exec prefix
+ * (e.g. ["/usr/local/bin/xcsh"] compiled, or ["/path/bun", "/abs/src/cli.ts"] in
+ * dev) — resolved by the CLI layer so this stays a pure writer.
+ */
+export function installNativeHost(opts: {
+	launchCommand: string[];
+	extensionIds: string[];
+	home?: string;
+	platform?: NodeJS.Platform;
+}): string {
+	if (opts.launchCommand.length === 0) throw new Error("installNativeHost: launchCommand must not be empty");
+	const home = opts.home ?? os.homedir();
+	const platform = opts.platform ?? process.platform;
+	const dir = nativeHostDir(home, platform);
+	const manifestPath = path.join(dir, `${NATIVE_HOST_NAME}.json`);
+	const wrapperPath = path.join(dir, `${NATIVE_HOST_NAME}.sh`);
+	fs.mkdirSync(dir, { recursive: true });
+
+	// Executable launcher: exec the real xcsh with `chrome-host`, forwarding
+	// Chrome's origin arg via "$@". 0o755 so Chrome can execute it directly.
+	const wrapper = `#!/bin/sh\nexec ${opts.launchCommand.map(shQuote).join(" ")} chrome-host "$@"\n`;
+	fs.writeFileSync(wrapperPath, wrapper, { mode: 0o755 });
+	fs.chmodSync(wrapperPath, 0o755); // writeFileSync mode is subject to umask; force it.
+
+	const manifest = {
+		name: NATIVE_HOST_NAME,
+		description: "xcsh Chrome native-messaging host (auto-provisioning bootstrap)",
+		path: wrapperPath,
+		type: "stdio",
+		allowed_origins: opts.extensionIds.map(id => `chrome-extension://${id}/`),
+	};
+	fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	return manifestPath;
+}