@f5-sales-demo/xcsh 20.1.2 → 20.2.2

package/src/browser/extension-bridge.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { Server, ServerWebSocket } from "bun";
 import { LOCALIP_HOST } from "./bridge-cert";
+import { EXTENSION_ID } from "./extension-identity";
 import { type ClientHost, isClientHost } from "./host-profiles";
 
 export interface ToolResult {
@@ -189,8 +190,6 @@ export const ADDIN_ALLOWED_ORIGIN_SUFFIXES = ["local-ip.sh"] as const;
  */
 export function isAllowedBridgeOrigin(origin: string | null | undefined): boolean {
 	if (!origin) return false;
-	// Lazy require avoids a top-level import cycle (chrome-cli imports this module).
-	const { EXTENSION_ID } = require("../cli/chrome-cli") as { EXTENSION_ID: string };
 	if (origin === `chrome-extension://${EXTENSION_ID}`) return true;
 	let url: URL;
 	try {
@@ -403,7 +402,6 @@ export class BridgeServer {
 	listen(port: number, opts?: BridgeListenOpts): boolean {
 		// Extract the fetch + websocket handlers to locals so BOTH the ws and the wss
 		// listeners share ONE implementation (DRY). Behavior is unchanged from before.
-		const { EXTENSION_ID } = require("../cli/chrome-cli") as { EXTENSION_ID: string };
 		const fetch = (req: Request, server: Server<undefined>): Response | undefined => {
 			const origin = req.headers.get("origin");
 			// SUPERSET gate: the Chrome ext origin stays allowed (Chrome path preserved);
@@ -480,11 +478,10 @@ export class BridgeServer {
 			ws.send(JSON.stringify({ type: "pong" }));
 		} else if (msg.type === "hello") {
 			// Identity handshake: tell the extension which tenant this process serves.
-			// Record the announced client host (contract 1.10.0): Office sends its
-			// lowercased Office.context.host ("excel"|"powerpoint"|"word"); the Chrome
-			// extension omits it → clientHost stays null → the browser profile. Invalid
-			// values are ignored (null retained). Echoed back so the client can confirm.
-			if (isClientHost(msg.host)) this.#clientHost = msg.host;
+			// Record the announced client host only on the server-owned Office bridge.
+			// A browser client cannot gain Office routing or provider configuration by
+			// claiming an Office host in an untrusted hello frame.
+			this.#clientHost = this.#serveKind === "office" && isClientHost(msg.host) ? msg.host : null;
 			const info = this.#sessionInfo?.() ?? {
 				tenant: null,
 				env: null,
@@ -506,7 +503,7 @@ export class BridgeServer {
 					serveKind: this.#serveKind,
 					pid: process.pid,
 					wssPort: this.wssPort,
-					canConfigureProvider: true,
+					...(this.#serveKind === "office" ? { canConfigureProvider: true } : {}),
 				}),
 			);
 		} else {

package/src/browser/extension-identity.ts

@@ -0,0 +1,2 @@
+/** Public Chrome Web Store identity used by the bridge origin allowlist. */
+export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";

package/src/browser/extension-provider.ts

@@ -24,11 +24,6 @@ export function resolveRef(tree: AxRefNode, selector: string): string {
 /** Thin wrapper over the bridge for the page-level operations the agent needs. */
 export interface ExtensionPage {
 	navigate(url: string): Promise<void>;
-	login(
-		email: string,
-		password: string,
-		consoleUrl: string,
-	): Promise<{ loggedIn: boolean; finalUrl: string; steps: string[] }>;
 	readAx(): Promise<AxRefNode>;
 	click(ref: string): Promise<void>;
 	screenshot(): Promise<string>;
@@ -102,25 +97,17 @@ function unwrap(result: ToolResult, tool: string): unknown {
 
 /**
  * Connect-time discovery handshake: confirm the extension is live and that its
- * published capability contract matches what xcsh was built against. Warns (does
- * not fail) on mismatch — a co-built pair stays in lockstep, while a hand-run
- * mismatch degrades gracefully. Falls back to `ping` for an extension that
- * predates the `capabilities` tool.
+ * published capability contract exactly matches what xcsh was built against.
+ * Contract 2 is a prerelease clean break: an absent or mismatched manifest fails
+ * closed instead of falling back to a legacy liveness-only handshake.
  */
 async function handshakeCapabilities(server: BridgeServer): Promise<void> {
-	let liveContractVersion: string | undefined;
-	try {
-		const caps = unwrap(await server.request("capabilities", {}), "capabilities") as {
-			contractVersion?: string;
-		};
-		liveContractVersion = caps?.contractVersion;
-	} catch {
-		// Older extension without the `capabilities` tool — at least confirm liveness.
-		unwrap(await server.request("ping", {}), "ping");
-	}
-	const check = checkContractVersion(liveContractVersion, EXTENSION_CONTRACT_VERSION);
+	const caps = unwrap(await server.request("capabilities", {}), "capabilities") as {
+		contractVersion?: string;
+	};
+	const check = checkContractVersion(caps?.contractVersion, EXTENSION_CONTRACT_VERSION);
 	if (!check.ok) {
-		console.warn(`[xcsh] Chrome extension capability mismatch (${check.severity}): ${check.message}`);
+		throw new Error(`Chrome extension capability mismatch (${check.severity}): ${check.message}`);
 	}
 }
 
@@ -135,27 +122,6 @@ class BridgeExtensionPage implements ExtensionPage {
 		unwrap(await this.#server.request("navigate", { url }), "navigate");
 	}
 
-	async login(
-		email: string,
-		password: string,
-		consoleUrl: string,
-	): Promise<{ loggedIn: boolean; finalUrl: string; steps: string[] }> {
-		// Defense-in-depth: validate the console URL before sending credentials
-		// over the bridge — only https F5 XC console domains are allowed, so a
-		// bad consoleUrl can never carry credentials to a foreign host.
-		const parsed = new URL(consoleUrl); // throws on malformed
-		if (parsed.protocol !== "https:") {
-			throw new Error(`login: consoleUrl must use https, got ${parsed.protocol}`);
-		}
-		if (!/\.volterra\.us$|\.console\.ves\.volterra\.io$/.test(parsed.hostname)) {
-			throw new Error(`login: consoleUrl host "${parsed.hostname}" is not an allowed F5 XC console domain`);
-		}
-		return unwrap(
-			await this.#server.request("login", { email, password, consoleUrl: parsed.toString() }, 90_000),
-			"login",
-		) as { loggedIn: boolean; finalUrl: string; steps: string[] };
-	}
-
 	async readAx(): Promise<AxRefNode> {
 		return unwrap(await this.#server.request("read_ax", {}), "read_ax") as AxRefNode;
 	}
@@ -355,18 +321,9 @@ export class ExtensionBrowserProvider implements BrowserProvider {
 
 		const page: ExtensionPage = new BridgeExtensionPage(server);
 
-		// Auto-login: if XCSH_USERNAME + XCSH_CONSOLE_PASSWORD are available (set by
-		// ContextService from the context's env map), login automatically — the login
-		// tool handles "already authenticated" (instant return) so calling it every
-		// time is cheap and guarantees a valid session. Falls back to navigate-only
-		// (co-drive) if credentials aren't available.
-		const email = process.env.XCSH_USERNAME;
-		const password = process.env.XCSH_CONSOLE_PASSWORD;
-		if (email && password) {
-			await page.login(email, password, consoleUrl);
-		} else {
-			unwrap(await server.request("navigate", { url: consoleUrl }), "navigate");
-		}
+		// Authentication remains an operator-owned browser action. The worker never
+		// reads or forwards usernames/passwords across the extension bridge.
+		unwrap(await server.request("navigate", { url: consoleUrl }), "navigate");
 
 		return {
 			page: new ExtensionPageActions(page),

package/src/browser/host-profiles.ts

@@ -57,7 +57,7 @@ BEHAVIOR:
 - You KNOW which page the user is on (injected below). Don't ask "what page are you on?" — tell them.
 - For questions about the page/resource: answer from the injected context. No tools.
 - If a blocking popup/survey appears, dismiss it by clicking the close button.
-- If on the LOGIN page: use the login tool to log in. The login tool handles ALL environments — production (*.console.ves.volterra.io) AND staging (*.staging.volterra.us, login-staging.volterra.us). Do NOT claim the login tool is broken, unsupported, or doesn't work for staging — it does.
+- If on the LOGIN page: ask the user to authenticate directly in the browser. Never request, accept, or enter a username, password, token, or other authentication secret.
 
 BROWSER AUTOMATION (when the user asks to create/modify/navigate resources):
 - You are IN a Chrome browser. The active console tab is your workspace — use IT.

package/src/cli/chrome-cli.ts

@@ -11,8 +11,11 @@ import { homedir } from "node:os";
 import * as path from "node:path";
 import { acquirePage, type BrowserProviderStatus, CdpBrowserProvider } from "../browser";
 import { PORT_RANGE_END, PORT_RANGE_START, resolveForcedPort } from "../browser/extension-bridge";
+import { EXTENSION_ID } from "../browser/extension-identity";
 import { installNativeHost } from "../services/native-host-install";
 
+export * from "../browser/extension-identity";
+
 /** Ask a running manager to step down (control-socket `shutdown` frame). Resolves
  * true if a manager answered the socket, false if none was running. Best-effort. */
 async function requestManagerShutdown(reason: "updated"): Promise<boolean> {
@@ -32,8 +35,6 @@ type Settings = { get(key: string): unknown };
 
 export type ChromeAction = "status" | "relaunch" | "setup" | "install-host" | "recycle";
 
-export const EXTENSION_ID = "klajkjdoehjidngligegnpknogmjjhkc";
-
 /**
  * Baked-in Chrome Web Store URL for the xcsh console-automation extension.
  * Surfaced to the user when the extension is not installed/connected so they

package/src/cli/root-command-routing.ts

@@ -0,0 +1,72 @@
+import { flagNameForChar, flagSpec, type LaunchFlagName } from "./flag-spec";
+
+export interface PrefixedCommandRoute {
+	command: string;
+	commandArgs: string[];
+	prefixFlags: LaunchFlagName[];
+}
+
+function optionalValue(token: string | undefined): token is string {
+	return token !== undefined && !token.startsWith("-") && !token.startsWith("@");
+}
+
+/**
+ * Find a registered command after root launch flags without changing their scope.
+ *
+ * Root flags configure an agent launch. They are not global options for every command, so callers use
+ * this result to report the scope error instead of treating the command and its arguments as prompt
+ * text. `--` deliberately stops command discovery and keeps everything after it as launch content.
+ */
+export function findPrefixedCommand(
+	argv: readonly string[],
+	isCommand: (token: string) => boolean,
+): PrefixedCommandRoute | undefined {
+	const prefixFlags: LaunchFlagName[] = [];
+	let index = 0;
+	while (index < argv.length) {
+		const token = argv[index];
+		if (token === "--") return undefined;
+		if (!token.startsWith("-") || token === "-") {
+			if (prefixFlags.length === 0 || !isCommand(token)) return undefined;
+			return {
+				command: token,
+				commandArgs: argv.slice(index + 1),
+				prefixFlags,
+			};
+		}
+
+		const [longName, inlineValue] = token.startsWith("--") ? token.slice(2).split("=", 2) : [undefined, undefined];
+		const name = longName ?? flagNameForChar(token.slice(1));
+		const spec = name === undefined ? undefined : flagSpec(name);
+		if (name === undefined || spec === undefined) return undefined;
+		prefixFlags.push(name as LaunchFlagName);
+
+		// Keep invalid boolean `=value` forms on the launch parser's diagnostic path instead of
+		// replacing that syntax error with a subcommand-scope error.
+		if (spec.arity === "boolean") {
+			if (inlineValue !== undefined) return undefined;
+			index++;
+			continue;
+		}
+		if (inlineValue !== undefined) {
+			index++;
+			continue;
+		}
+		// Optional values and subcommands are otherwise ambiguous. A registered command wins; an
+		// operator who means the same token as a value can state that unambiguously with `=`.
+		if (spec.arity === "optional-value" && isCommand(argv[index + 1] ?? "")) {
+			return {
+				command: argv[index + 1],
+				commandArgs: argv.slice(index + 2),
+				prefixFlags,
+			};
+		}
+		if (spec.arity === "optional-value") {
+			index += optionalValue(argv[index + 1]) ? 2 : 1;
+			continue;
+		}
+		if (argv[index + 1] === undefined) return undefined;
+		index += 2;
+	}
+	return undefined;
+}

package/src/cli/sandbox-check.ts

@@ -2,11 +2,11 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import { executeShell } from "@f5-sales-demo/pi-natives";
+import { executeShell, fencePermits } from "@f5-sales-demo/pi-natives";
 import { isEnoent } from "@f5-sales-demo/pi-utils";
 import { Settings } from "../config/settings";
 import { fenceForNative } from "../exec/bash-executor";
-import { buildContainmentFence, type ContainmentFence, containmentStatus } from "../sandbox/containment";
+import { buildContainmentFence, type ContainmentFence, containmentStatus, fenceVerdict } from "../sandbox/containment";
 import { evaluateToolCall } from "../sandbox/enforce";
 import {
 	SANDBOX_CHECK_NAMED_SIBLING_ENV,
@@ -364,6 +364,46 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 					redactions,
 				);
 			});
+			await check("explicit grant restores parent enumeration", async () => {
+				const grantedFence = buildContainmentFence({
+					workspace,
+					home: operatorHome,
+					fsRoot: fixtureRoot,
+					leakRoots: [sessionStore, memoryStore],
+					readOnlyRoots: [workspaces],
+					writeOnlyRoots: [workspaces],
+				});
+				const grantedNativeFence = fenceForNative(grantedFence);
+				if (
+					fenceVerdict(grantedFence, workspaces, "enumerate") !== "allow" ||
+					grantedNativeFence === undefined ||
+					!fencePermits(grantedNativeFence, workspaces, false, true)
+				) {
+					return {
+						passed: false,
+						detail:
+							"explicit grant was not accepted by both policy engines; path=<synthetic-session-parent>; errno=none",
+					};
+				}
+
+				// An inherited OS profile cannot be widened by a child. In that topology the live
+				// profile already grants this synthetic path through the workspace, so exercise the
+				// real operation there after both policy engines accepted the explicit grant. A
+				// standalone check applies the granted fence itself and covers the OS compiler too.
+				const result = await shellProbe(
+					`ls ${quote(workspaces)} > /dev/null`,
+					workspace,
+					inheritedProfile ? undefined : grantedFence,
+					abortController.signal,
+				);
+				return shellOutcome(
+					result,
+					true,
+					"explicit grant must restore synthetic session parent enumeration",
+					"<synthetic-session-parent>",
+					redactions,
+				);
+			});
 			await check("account container cannot be enumerated", async () => {
 				const result = await shellProbe(
 					`ls ${quote(accountRoot)} > /dev/null`,
@@ -422,6 +462,7 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 		} else {
 			for (const name of [
 				"session parent cannot be enumerated",
+				"explicit grant restores parent enumeration",
 				"account container cannot be enumerated",
 				"synthetic other account cannot be entered",
 				"cross-session stores cannot be read",

package/src/cli.ts

@@ -5,6 +5,8 @@ import { APP_NAME, initI18n, MIN_BUN_VERSION, registerLocales, t, VERSION } from
  * lightweight CLI runner from pi-utils.
  */
 import { type CommandEntry, run } from "@f5-sales-demo/pi-utils/cli";
+import { FlagUsageError } from "./cli/flag-spec";
+import { findPrefixedCommand } from "./cli/root-command-routing";
 import { locales } from "./locales/index";
 
 registerLocales(locales);
@@ -89,11 +91,41 @@ function isSubcommand(first: string | undefined): boolean {
 	return commands.some(e => e.name === first || e.aliases?.includes(first));
 }
 
+function requestsHelp(args: readonly string[]): boolean {
+	for (const arg of args) {
+		if (arg === "--") return false;
+		if (arg === "--help" || arg === "-h") return true;
+	}
+	return false;
+}
+
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export function runCli(argv: string[]): Promise<void> {
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
 	const first = argv[0];
+	const prefixedCommand = findPrefixedCommand(argv, token => isSubcommand(token));
+	if (
+		prefixedCommand !== undefined &&
+		!prefixedCommand.prefixFlags.some(flag => flag === "help" || flag === "version")
+	) {
+		if (requestsHelp(prefixedCommand.commandArgs)) {
+			return run({
+				bin: APP_NAME,
+				version: VERSION,
+				argv: [prefixedCommand.command, ...prefixedCommand.commandArgs],
+				commands,
+				help: showHelp,
+			});
+		}
+		const flags = [...new Set(prefixedCommand.prefixFlags)].map(flag => `--${flag}`).join(", ");
+		process.stderr.write(
+			`Error: launch ${prefixedCommand.prefixFlags.length === 1 ? "flag" : "flags"} ${flags} cannot precede the ` +
+				`\`${prefixedCommand.command}\` subcommand. Launch flags configure an agent session; subcommands must come first.\n`,
+		);
+		process.exitCode = 2;
+		return Promise.resolve();
+	}
 	const runArgv =
 		// Chrome launches the native-messaging host with the calling extension's
 		// origin (chrome-extension://…/) as the first arg. Route that to the
@@ -120,4 +152,10 @@ if (process.env.XCSH_SMOKE_TEST_SPECS === "1") {
 	process.exit(domainCount > 0 && categoryCount > 0 ? 0 : 1);
 }
 
-await runCli(process.argv.slice(2));
+try {
+	await runCli(process.argv.slice(2));
+} catch (error) {
+	if (!(error instanceof FlagUsageError)) throw error;
+	process.stderr.write(`Error: ${error.message}\n`);
+	process.exitCode = 2;
+}

package/src/commands/manager.ts

@@ -26,6 +26,7 @@ import { Command } from "@f5-sales-demo/pi-utils/cli";
 // 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 { EXTENSION_ID } from "../browser/extension-identity";
 // Lean standalone fn (compiled-runtime detection) — no heavy graph, safe for the daemon.
 import { detectCompiledRuntime } from "../internal-urls/build-info-runtime";
 import { removeManagerState, writeManagerState } from "../services/manager-state";
@@ -88,8 +89,7 @@ function pidListeningOn(port: number): number {
 }
 
 /** Complete the extension `hello` handshake against a bridge port (with the
- * origin header the bridge requires), resolving the `hello_ack` frame or null.
- * EXTENSION_ID is lazy-required so it stays off the manager's cold-start path. */
+ * origin header the bridge requires), resolving the `hello_ack` frame or null. */
 function bridgeHello(port: number, timeoutMs = 400): Promise<Record<string, unknown> | null> {
 	const { promise, resolve } = Promise.withResolvers<Record<string, unknown> | null>();
 	let done = false;
@@ -100,7 +100,6 @@ function bridgeHello(port: number, timeoutMs = 400): Promise<Record<string, unkn
 	};
 	let ws: WebSocket;
 	try {
-		const { EXTENSION_ID } = require("../cli/chrome-cli");
 		// Intentionally ws://: the internal Chrome re-adoption client targets the
 		// bridge's local ws listener and does not cross the Office TLS boundary.
 		ws = new WebSocket(`ws://127.0.0.1:${port}`, {
@@ -528,6 +527,12 @@ export default class Manager extends Command {
 			},
 		};
 
+		// Finish startup reconciliation before publishing the control socket. A socket
+		// that accepts connections is the manager's readiness contract: clients send
+		// their first frame immediately, and a request/reply client can otherwise time
+		// out while the initial bridge scan is still loading and probing dependencies.
+		await readoptWorkers();
+
 		// Single-manager invariant + stale-socket reclamation. A live manager is
 		// never clobbered (we probe first and again on collision); a stale socket
 		// from a crashed/killed manager is reclaimed rather than crashing on
@@ -568,11 +573,6 @@ export default class Manager extends Command {
 		process.on("SIGTERM", () => gracefulShutdown("manual"));
 		process.on("SIGINT", () => gracefulShutdown("manual"));
 
-		// Zero-downtime handoff: re-adopt any bound workers a superseded manager left
-		// running BEFORE filling the pool (so their ports aren't mistaken for free).
-		// Awaited but bounded (~parallel 400ms); the socket already accepts connections.
-		await readoptWorkers();
-
 		// Pre-warm the spare pool so provisions can adopt instead of cold-spawn.
 		if (poolTarget > 0) maintainPool();
 

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.1.2",
-	"commit": "b5534d98c8ad483cc6e8709b44242cf3ea98041d",
-	"shortCommit": "b5534d9",
+	"version": "20.2.2",
+	"commit": "fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
+	"shortCommit": "fd7d7d7",
 	"branch": "main",
-	"tag": "v20.1.2",
-	"commitDate": "2026-08-01T21:09:01Z",
-	"buildDate": "2026-08-01T21:30:18.970Z",
+	"tag": "v20.2.2",
+	"commitDate": "2026-08-02T01:16:07Z",
+	"buildDate": "2026-08-02T01:43:23.755Z",
 	"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/b5534d98c8ad483cc6e8709b44242cf3ea98041d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.1.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.2.2"
 };

package/src/main.ts

@@ -321,13 +321,11 @@ async function maybeAutoChdir(parsed: Args): Promise<void> {
 		return;
 	}
 
-	const normalizePath = (value: string) => {
-		const resolved = realpathSync(path.resolve(value));
-		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
-	};
-
-	const cwd = normalizePath(getProjectDir());
-	const normalizedHome = normalizePath(home);
+	// A nested xcsh process may inherit a profile that permits named home access but withholds parent
+	// metadata. Comparison is advisory auto-chdir logic, so an unavailable realpath must fall back to
+	// the resolved spelling instead of crashing before command dispatch (#2817).
+	const cwd = normalizePathForComparison(getProjectDir());
+	const normalizedHome = normalizePathForComparison(home);
 	if (cwd !== normalizedHome) {
 		return;
 	}
@@ -356,7 +354,7 @@ async function maybeAutoChdir(parsed: Args): Promise<void> {
 
 	try {
 		const fallback = os.tmpdir();
-		if (fallback && normalizePath(fallback) !== cwd && (await isDirectory(fallback))) {
+		if (fallback && normalizePathForComparison(fallback) !== cwd && (await isDirectory(fallback))) {
 			setProjectDir(fallback);
 		}
 	} catch {