@f5-sales-demo/xcsh 19.54.0 → 19.55.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.54.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.54.0",
-		"@f5-sales-demo/pi-agent-core": "19.54.0",
-		"@f5-sales-demo/pi-ai": "19.54.0",
-		"@f5-sales-demo/pi-natives": "19.54.0",
-		"@f5-sales-demo/pi-resource-management": "19.54.0",
-		"@f5-sales-demo/pi-tui": "19.54.0",
-		"@f5-sales-demo/pi-utils": "19.54.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/scripts/generate-extension-capabilities.ts

@@ -54,6 +54,7 @@ const output = [
 	"export interface ExtensionCapabilities {",
 	"\treadonly version: string;",
 	"\treadonly contractVersion: string;",
+	"\treadonly multiPortDiscovery?: boolean;",
 	"\treadonly protocol: string;",
 	"\treadonly tools: readonly ExtensionToolDef[];",
 	"\treadonly features: Record<string, unknown>;",

package/src/browser/capabilities.generated.ts

@@ -18,6 +18,7 @@ export interface ExtensionToolDef {
 export interface ExtensionCapabilities {
 	readonly version: string;
 	readonly contractVersion: string;
+	readonly multiPortDiscovery?: boolean;
 	readonly protocol: string;
 	readonly tools: readonly ExtensionToolDef[];
 	readonly features: Record<string, unknown>;
@@ -25,7 +26,8 @@ export interface ExtensionCapabilities {
 
 export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	"version": "0.1.0",
-	"contractVersion": "1.4.0",
+	"contractVersion": "1.5.0",
+	"multiPortDiscovery": true,
 	"protocol": "tool_request/result",
 	"tools": [
 		{
@@ -613,6 +615,16 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 			},
 			"flags": {}
 		},
+		{
+			"name": "diag_bridges",
+			"summary": "List discovered xcsh bridges (port, tenant, env, sessionId, lastSeen) for multi-session diagnostics.",
+			"category": "read",
+			"params": {
+				"type": "object",
+				"properties": {}
+			},
+			"flags": {}
+		},
 		{
 			"name": "capture_login_flow",
 			"summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",
@@ -813,6 +825,6 @@ export const EXTENSION_CAPABILITIES: ExtensionCapabilities = {
 	}
 };
 
-export const EXTENSION_CONTRACT_VERSION = "1.4.0";
+export const EXTENSION_CONTRACT_VERSION = "1.5.0";
 
-export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];
+export const EXTENSION_TOOL_NAMES: readonly string[] = ["ping","capabilities","reload","debug_exec","detach","set_bridge_port","navigate","login","scroll_to","resize_window","tabs_list","tabs_create","tabs_close","click","click_element","click_xy","type_text","form_input","key_press","select_option","label_select","file_upload","read_ax","get_page_text","query_dom","find","wait_for","assert_text","screenshot","read_console","read_network","diag_suspension","diag_bridges","capture_login_flow","wait_for_api_response","get_page_context","javascript_tool","browser_batch","set_explain_mode","annotate"];

package/src/browser/capabilities.json

@@ -1,6 +1,7 @@
 {
   "version": "0.1.0",
-  "contractVersion": "1.4.0",
+  "contractVersion": "1.5.0",
+  "multiPortDiscovery": true,
   "protocol": "tool_request/result",
   "tools": [
     {
@@ -539,6 +540,16 @@
       },
       "flags": {}
     },
+    {
+      "name": "diag_bridges",
+      "summary": "List discovered xcsh bridges (port, tenant, env, sessionId, lastSeen) for multi-session diagnostics.",
+      "category": "read",
+      "params": {
+        "type": "object",
+        "properties": {}
+      },
+      "flags": {}
+    },
     {
       "name": "capture_login_flow",
       "summary": "Diagnostic: captured login redirect chain annotated with tenant/env (Phase 0b).",

package/src/browser/chat-conformance.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.4.0",
+  "contractVersion": "1.5.0",
   "schemas": {
     "chat_request": {
       "type": "object",

package/src/browser/extension-bridge.ts

@@ -67,6 +67,25 @@ export function resolvePort(port?: number): number {
 	return DEFAULT_PORT;
 }
 
+/** Inclusive loopback discovery range for auto-selected bridge ports. */
+export const PORT_RANGE_START = 19222;
+export const PORT_RANGE_END = 19241;
+
+/** Every port in the discovery range, lowest first. */
+export function portCandidates(): number[] {
+	const out: number[] = [];
+	for (let p = PORT_RANGE_START; p <= PORT_RANGE_END; p++) out.push(p);
+	return out;
+}
+
+/** The explicitly forced port (arg → XCSH_BRIDGE_PORT), or null to auto-select. */
+export function resolveForcedPort(port?: number): number | null {
+	if (typeof port === "number" && Number.isFinite(port) && port > 0) return port;
+	const env = Number(process.env.XCSH_BRIDGE_PORT);
+	if (Number.isFinite(env) && env > 0) return env;
+	return null;
+}
+
 /**
  * Loopback WebSocket server bridging xcsh to the Chrome extension. Speaks JSON
  * over WS frames: requests `{type:"tool_request",...}`, replies
@@ -89,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 {
@@ -126,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 }));
@@ -159,56 +182,58 @@ export class BridgeServer {
 		this.#resolveClient(channelId)?.send(JSON.stringify(payload));
 	}
 
-	/** Bind the WebSocket server to a loopback port. Called by {@link startBridgeServer}. */
-	listen(port: number, opts?: { skipOriginCheck?: boolean }): void {
-		this.#server = Bun.serve({
-			port,
-			hostname: "127.0.0.1",
-			fetch: (req, server) => {
-				// Validate the Origin header: only the xcsh Chrome extension may connect.
-				// This restores the access-control guarantee that the Unix socket's 0o600
-				// permissions previously provided.
-				if (!opts?.skipOriginCheck) {
-					const origin = req.headers.get("origin") ?? "";
-					const { EXTENSION_ID } = require("../cli/chrome-cli");
-					if (origin !== `chrome-extension://${EXTENSION_ID}`) {
-						return new Response("Forbidden", { status: 403 });
+	#onOpen(ws: ServerWebSocket<undefined>): void {
+		// Assign a channel ID to each connection. For backwards compat (single
+		// extension), the first connection gets "default". Additional connections
+		// get "ch-1", "ch-2", etc. — supporting multi-tab parallelism.
+		const channelId = this.#clients.size === 0 ? "default" : `ch-${++this.#nextChannelIndex}`;
+		(ws as unknown as { channelId: string }).channelId = channelId;
+		this.#clients.set(channelId, ws);
+		// Start a heartbeat ping to keep the MV3 service worker alive.
+		// Chrome suspends idle SWs after ~30s; a ping every 15s prevents that.
+		if (!this.#heartbeat) {
+			this.#heartbeat = setInterval(() => {
+				for (const c of this.#clients.values()) {
+					try {
+						c.send(JSON.stringify({ type: "ping" }));
+					} catch {
+						/* client may have dropped */
 					}
 				}
-				if (server.upgrade(req)) return undefined;
-				return new Response("xcsh bridge: WebSocket only", { status: 426 });
-			},
-			websocket: {
-				open: ws => {
-					// Assign a channel ID to each connection. For backwards compat (single
-					// extension), the first connection gets "default". Additional connections
-					// get "ch-1", "ch-2", etc. — supporting multi-tab parallelism.
-					const channelId = this.#clients.size === 0 ? "default" : `ch-${++this.#nextChannelIndex}`;
-					(ws as unknown as { channelId: string }).channelId = channelId;
-					this.#clients.set(channelId, ws);
-					// Start a heartbeat ping to keep the MV3 service worker alive.
-					// Chrome suspends idle SWs after ~30s; a ping every 15s prevents that.
-					if (!this.#heartbeat) {
-						this.#heartbeat = setInterval(() => {
-							for (const c of this.#clients.values()) {
-								try {
-									c.send(JSON.stringify({ type: "ping" }));
-								} catch {
-									/* client may have dropped */
-								}
-							}
-						}, 15_000);
+			}, 15_000);
+		}
+		for (const cb of this.#onConnected) cb();
+	}
+
+	/** Try to bind the loopback WS server to `port`. Returns false on EADDRINUSE
+	 * (so the caller can try the next candidate); rethrows any other error. */
+	listen(port: number, opts?: { skipOriginCheck?: boolean }): boolean {
+		try {
+			this.#server = Bun.serve({
+				port,
+				hostname: "127.0.0.1",
+				fetch: (req, server) => {
+					if (!opts?.skipOriginCheck) {
+						const origin = req.headers.get("origin") ?? "";
+						const { EXTENSION_ID } = require("../cli/chrome-cli");
+						if (origin !== `chrome-extension://${EXTENSION_ID}`) {
+							return new Response("Forbidden", { status: 403 });
+						}
 					}
-					for (const cb of this.#onConnected) cb();
-				},
-				message: (ws, message) => {
-					this.#handleMessage(ws, message);
+					if (server.upgrade(req)) return undefined;
+					return new Response("xcsh bridge: WebSocket only", { status: 426 });
 				},
-				close: ws => {
-					this.#onClose(ws);
+				websocket: {
+					open: ws => this.#onOpen(ws),
+					message: (ws, message) => this.#handleMessage(ws, message),
+					close: ws => this.#onClose(ws),
 				},
-			},
-		});
+			});
+			return true;
+		} catch (e) {
+			if (e instanceof Error && /EADDRINUSE|address already in use|in use/i.test(e.message)) return false;
+			throw e;
+		}
 	}
 
 	#handleMessage(ws: ServerWebSocket<undefined>, message: string | Buffer): void {
@@ -228,14 +253,17 @@ 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({
 					type: "hello_ack",
 					sessionId: this.#sessionId,
+					contractVersion: EXTENSION_CONTRACT_VERSION,
 					tenant: info.tenant,
 					env: info.env,
 					apiUrl: info.apiUrl,
+					contextBound: info.contextBound,
 					pid: process.pid,
 				}),
 			);
@@ -293,12 +321,23 @@ export class BridgeServer {
 }
 
 /**
- * Start the {@link BridgeServer} on the resolved loopback port (explicit arg,
- * then `XCSH_BRIDGE_PORT`, then {@link DEFAULT_PORT}). The WebSocket transport
+ * Start the {@link BridgeServer} on the resolved loopback port. If a port is
+ * forced (explicit arg or `XCSH_BRIDGE_PORT`) it must be free — throws loudly
+ * if taken. Otherwise, auto-selects the lowest free port in the discovery range
+ * ({@link PORT_RANGE_START}–{@link PORT_RANGE_END}). The WebSocket transport
  * needs no filesystem setup — Chrome connects directly to `ws://127.0.0.1:<port>`.
  */
 export async function startBridgeServer(port?: number, opts?: { skipOriginCheck?: boolean }): Promise<BridgeServer> {
 	const server = new BridgeServer();
-	server.listen(resolvePort(port), opts);
-	return server;
+	const forced = resolveForcedPort(port);
+	if (forced !== null) {
+		if (!server.listen(forced, opts)) {
+			throw new Error(`XCSH_BRIDGE_PORT ${forced} is already in use — free it or pick another port`);
+		}
+		return server;
+	}
+	for (const candidate of portCandidates()) {
+		if (server.listen(candidate, opts)) return server;
+	}
+	throw new Error(`no free xcsh bridge port in ${PORT_RANGE_START}-${PORT_RANGE_END} — is another app on the range?`);
 }

package/src/browser/extension-page-actions.ts

@@ -501,7 +501,6 @@ export class ExtensionPageActions implements PageActions {
 		throw new Error(`waitFor "${selector}" timed out after ${ms}ms`);
 	}
 
-	// biome-ignore lint/suspicious/useAwait: signature is async (PageActions contract)
 	async screenshot(_file: string): Promise<void> {
 		// Intentionally a no-op for the extension provider. CDP captureScreenshot
 		// transiently FREEZES the MV3 service worker; in observable mode the runner

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 { resolvePort } from "../browser/extension-bridge";
+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 [
@@ -43,14 +89,28 @@ export async function runChromeCommand(action: ChromeAction, settings: Settings)
 	if (action === "status") return renderStatus(await provider.status());
 	if (action === "setup") {
 		// The extension connects directly over a loopback WebSocket — no native-messaging
-		// host manifest to install. Report the port so the user can point the extension at it.
-		const port = resolvePort();
+		// host manifest to install. A forced port is reported exactly; otherwise xcsh
+		// auto-selects the lowest free port in the discovery range at launch.
+		const forced = resolveForcedPort();
+		const where =
+			forced !== null
+				? `ws://127.0.0.1:${forced} (forced via XCSH_BRIDGE_PORT)`
+				: `the lowest free port in ${PORT_RANGE_START}-${PORT_RANGE_END} (printed in the xcsh startup banner)`;
 		return (
-			`The xcsh Chrome extension connects directly to xcsh over a loopback WebSocket on ` +
-			`ws://127.0.0.1:${port} (override with XCSH_BRIDGE_PORT).\n` +
-			`Install/keep the xcsh Chrome extension from the Web Store, then it can drive your real Chrome:\n  ${WEB_STORE_URL}`
+			`The xcsh Chrome extension connects directly to xcsh over a loopback WebSocket on ${where}.\n` +
+			`The extension scans that range and links each tenant's xcsh automatically.\n` +
+			`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;
+}