@f5-sales-demo/xcsh 20.1.0 → 20.1.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [20.1.2] - 2026-08-01
+
+### Fixed
+
+- Made `xcsh sandbox check` work for sessions rooted directly under the operator home, distinguish harness errors from sandbox failures, and verify this topology against installed release artifacts ([#2807](https://github.com/f5-sales-demo/xcsh/issues/2807))
+
+## [20.1.1] - 2026-08-01
+
+### Fixed
+
+- Made `xcsh sandbox check` exercise the live bash profile, report actionable failure details, and run under macOS and Linux confinement in CI ([#2800](https://github.com/f5-sales-demo/xcsh/issues/2800))
+
 ## [20.1.0] - 2026-08-01
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.1.0",
+	"version": "20.1.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "20.1.0",
-		"@f5-sales-demo/pi-agent-core": "20.1.0",
-		"@f5-sales-demo/pi-ai": "20.1.0",
-		"@f5-sales-demo/pi-natives": "20.1.0",
-		"@f5-sales-demo/pi-resource-management": "20.1.0",
-		"@f5-sales-demo/pi-tui": "20.1.0",
-		"@f5-sales-demo/pi-utils": "20.1.0",
+		"@f5-sales-demo/xcsh-stats": "20.1.2",
+		"@f5-sales-demo/pi-agent-core": "20.1.2",
+		"@f5-sales-demo/pi-ai": "20.1.2",
+		"@f5-sales-demo/pi-natives": "20.1.2",
+		"@f5-sales-demo/pi-resource-management": "20.1.2",
+		"@f5-sales-demo/pi-tui": "20.1.2",
+		"@f5-sales-demo/pi-utils": "20.1.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/cli/sandbox-check.ts

@@ -8,13 +8,20 @@ import { Settings } from "../config/settings";
 import { fenceForNative } from "../exec/bash-executor";
 import { buildContainmentFence, type ContainmentFence, containmentStatus } from "../sandbox/containment";
 import { evaluateToolCall } from "../sandbox/enforce";
+import {
+	SANDBOX_CHECK_NAMED_SIBLING_ENV,
+	SANDBOX_OPERATOR_HOME_ENV,
+	SANDBOX_SESSION_ROOT_ENV,
+} from "../sandbox/session-fence";
 import { BashTool, type ToolSession } from "../tools";
 
-export type SandboxCheckResultStatus = "PASS" | "FAIL" | "SKIP";
+export type SandboxCheckResultStatus = "PASS" | "FAIL" | "SKIP" | "ERROR";
 
 export interface SandboxCheckResult {
 	name: string;
 	status: SandboxCheckResultStatus;
+	/** Present on failures, errors, and skips; paths are generalized before they leave the process. */
+	detail?: string;
 }
 
 export interface SandboxCheckReport {
@@ -24,38 +31,115 @@ export interface SandboxCheckReport {
 	summary: {
 		passed: number;
 		failed: number;
+		errors: number;
 		skipped: number;
 	};
 }
 
 export interface SandboxCheckOptions {
 	json?: boolean;
+	verbose?: boolean;
 }
 
+interface ProbeOutcome {
+	passed: boolean;
+	detail?: string;
+}
+
+interface ShellProbeResult {
+	exitCode: number;
+	output: string;
+}
+
+type Redaction = readonly [path: string, label: string];
+
 function quote(value: string): string {
 	return JSON.stringify(value);
 }
 
-async function shellExitCode(
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+	const code = (error as { code?: unknown }).code;
+	return typeof code === "string" ? code : undefined;
+}
+
+function sanitizeDetail(value: string, redactions: readonly Redaction[]): string {
+	let sanitized = value;
+	for (const [actual, label] of [...redactions].sort(([a], [b]) => b.length - a.length)) {
+		if (actual.length > 0) sanitized = sanitized.replaceAll(actual, label);
+	}
+	sanitized = sanitized.replace(/\s+/gu, " ").trim();
+	return sanitized.length > 500 ? `${sanitized.slice(0, 497)}...` : sanitized;
+}
+
+function errnoFromOutput(output: string): string {
+	if (/operation not permitted/iu.test(output)) return "EPERM";
+	if (/permission denied/iu.test(output)) return "EACCES";
+	if (/no such file or directory/iu.test(output)) return "ENOENT";
+	if (/not a directory/iu.test(output)) return "ENOTDIR";
+	return "unknown";
+}
+
+function exceptionOutcome(
+	assertion: string,
+	displayPath: string,
+	error: unknown,
+	redactions: readonly Redaction[],
+): ProbeOutcome {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		passed: false,
+		detail: sanitizeDetail(
+			`${assertion}; path=${displayPath}; errno=${errorCode(error) ?? "unknown"}; error=${message}`,
+			redactions,
+		),
+	};
+}
+
+function shellOutcome(
+	result: ShellProbeResult,
+	expectSuccess: boolean,
+	assertion: string,
+	displayPath: string,
+	redactions: readonly Redaction[],
+): ProbeOutcome {
+	const passed = expectSuccess ? result.exitCode === 0 : result.exitCode !== 0;
+	if (passed) return { passed: true };
+	const output = sanitizeDetail(result.output, redactions);
+	const errno = result.exitCode === 0 ? "none" : errnoFromOutput(output);
+	return {
+		passed: false,
+		detail: sanitizeDetail(
+			`${assertion}; path=${displayPath}; exit=${result.exitCode}; errno=${errno}${output ? `; output=${output}` : ""}`,
+			redactions,
+		),
+	};
+}
+
+async function shellProbe(
 	command: string,
 	cwd: string,
-	fence: ContainmentFence,
+	fence: ContainmentFence | undefined,
 	signal: AbortSignal,
-): Promise<number> {
+): Promise<ShellProbeResult> {
+	let output = "";
 	const result = await executeShell(
 		{
 			command,
 			cwd,
-			fence: fenceForNative(fence),
+			fence: fence === undefined ? undefined : fenceForNative(fence),
 			signal,
 			timeoutMs: 15_000,
 		},
-		() => {},
+		(error, chunk) => {
+			if (error) output += `${error.message}\n`;
+			else output += chunk;
+		},
 	);
-	return result.exitCode ?? -1;
+	return { exitCode: result.exitCode ?? -1, output };
 }
 
-function renderReport(report: SandboxCheckReport, json: boolean): void {
+function renderReport(report: SandboxCheckReport, json: boolean, verbose: boolean): void {
 	if (json) {
 		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 		return;
@@ -63,43 +147,83 @@ function renderReport(report: SandboxCheckReport, json: boolean): void {
 
 	const enforcement = report.osEnforced ? "OS enforced" : "scanner only";
 	process.stdout.write(`Sandbox backend: ${report.backend} (${enforcement})\n\n`);
-	const width = Math.max(...report.checks.map(check => check.name.length));
+	const nameWidth = Math.max(0, ...report.checks.map(check => check.name.length));
+	const statusWidth = Math.max(0, ...report.checks.map(check => check.status.length));
 	for (const check of report.checks) {
-		process.stdout.write(`${check.status.padEnd(4)}  ${check.name.padEnd(width)}\n`);
+		process.stdout.write(`${check.status.padEnd(statusWidth)}  ${check.name.padEnd(nameWidth)}\n`);
+		if (verbose && check.detail) process.stdout.write(`      ${check.detail}\n`);
 	}
 	process.stdout.write(
-		`\n${report.summary.passed} passed, ${report.summary.failed} failed, ${report.summary.skipped} skipped\n`,
+		`\n${report.summary.passed} passed, ${report.summary.failed} failed, ${report.summary.errors} errors, ${report.summary.skipped} skipped\n`,
 	);
+	if (report.checks.some(check => check.name === "conformance matrix setup" && check.status === "ERROR")) {
+		process.stdout.write("Conformance matrix did not run.\n");
+	}
+	if (!verbose && (report.summary.failed > 0 || report.summary.errors > 0)) {
+		process.stdout.write("Run `xcsh sandbox check --verbose` for failure details.\n");
+	}
 }
 
 /** Run the conformance matrix and report only after every synthetic fixture has been removed. */
 export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promise<SandboxCheckReport> {
 	const backend = containmentStatus(true);
 	const checks: SandboxCheckResult[] = [];
+	const fixturePaths: string[] = [];
+	const knownCleanupLeaves: string[] = [];
+	const nonEnumerableCleanupDirs = new Set<string>();
+	const redactions: Redaction[] = [];
 	const abortController = new AbortController();
 	const interrupt = () => abortController.abort();
 	process.once("SIGINT", interrupt);
 	process.once("SIGTERM", interrupt);
 
 	let fixtureRoot: string | undefined;
-	const add = (name: string, status: SandboxCheckResultStatus): void => {
-		checks.push({ name, status });
+	const add = (name: string, status: SandboxCheckResultStatus, detail?: string): void => {
+		checks.push({ name, status, ...(detail ? { detail } : {}) });
 	};
-	const check = async (name: string, probe: () => boolean | Promise<boolean>): Promise<void> => {
+	const check = async (
+		name: string,
+		probe: () => boolean | ProbeOutcome | Promise<boolean | ProbeOutcome>,
+	): Promise<void> => {
 		if (abortController.signal.aborted) {
-			add(name, "FAIL");
+			add(name, "ERROR", "probe aborted before execution; path=<probe>; errno=ABORTED");
 			return;
 		}
 		try {
-			add(name, (await probe()) ? "PASS" : "FAIL");
-		} catch {
-			add(name, "FAIL");
+			const result = await probe();
+			const outcome = typeof result === "boolean" ? { passed: result } : result;
+			add(
+				name,
+				outcome.passed ? "PASS" : "FAIL",
+				outcome.passed ? undefined : (outcome.detail ?? "assertion failed; path=<probe>; errno=unknown"),
+			);
+		} catch (error) {
+			const outcome = exceptionOutcome("probe threw", "<probe>", error, redactions);
+			add(name, "ERROR", outcome.detail);
 		}
 	};
 
 	try {
-		const tmpRoot = await fs.realpath(os.tmpdir());
-		fixtureRoot = await fs.mkdtemp(path.join(tmpRoot, "xcsh-sandbox-check-"));
+		const inheritedWorkspace = process.env[SANDBOX_SESSION_ROOT_ENV];
+		const inheritedHome = process.env[SANDBOX_OPERATOR_HOME_ENV];
+		const inheritedSibling = process.env[SANDBOX_CHECK_NAMED_SIBLING_ENV];
+		const inheritedProfile = inheritedWorkspace !== undefined;
+		const workspaceInput = inheritedWorkspace ?? process.cwd();
+		const homeInput = inheritedHome ?? os.homedir();
+		redactions.push([workspaceInput, "<workspace>"], [homeInput, "<operator-home>"]);
+		// BashTool owns and canonicalises inherited values before applying Seatbelt/Landlock. Re-running
+		// realpath here can require metadata access that the live profile deliberately withholds from the
+		// session parent — which is the operator home for a `~/<workspace>` layout (#2807).
+		const liveWorkspace = inheritedWorkspace ?? (await fs.realpath(workspaceInput));
+		const liveHome = inheritedHome ?? (await fs.realpath(homeInput));
+		redactions.push([liveWorkspace, "<workspace>"], [liveHome, "<operator-home>"]);
+		if (inheritedSibling !== undefined) redactions.push([inheritedSibling, "<session-parent>/<synthetic-sibling>"]);
+
+		const fixtureBase = inheritedProfile ? liveWorkspace : await fs.realpath(os.tmpdir());
+		fixtureRoot = await fs.mkdtemp(path.join(fixtureBase, ".xcsh-sandbox-check-policy-"));
+		fixturePaths.push(fixtureRoot);
+		redactions.push([fixtureRoot, "<synthetic-root>"]);
+
 		const accountRoot = path.join(fixtureRoot, "Users");
 		const operatorHome = path.join(accountRoot, "operator");
 		const otherHome = path.join(accountRoot, "other-account");
@@ -165,39 +289,134 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 				cwd: workspace,
 				fence,
 			});
-			return blocked.every(result => result.block) && !ownConfig.block;
+			const passed = blocked.every(result => result.block) && !ownConfig.block;
+			return passed
+				? { passed: true }
+				: {
+						passed: false,
+						detail: "structured-tool policy disagreed with the shell boundary; path=<synthetic-root>; errno=none",
+					};
 		});
 
 		await check("workspace read, write, glob, and recursion", async () => {
+			const displayPath = "<workspace>/<synthetic-fixture>";
+			let liveFixture: string;
+			try {
+				liveFixture = await fs.mkdtemp(path.join(liveWorkspace, ".xcsh-sandbox-check-workspace-"));
+				fixturePaths.push(liveFixture);
+				redactions.push([liveFixture, displayPath]);
+				await fs.mkdir(path.join(liveFixture, "nested"));
+				await Bun.write(path.join(liveFixture, "own.txt"), "own\n");
+			} catch (error) {
+				return exceptionOutcome("create live workspace fixture", displayPath, error, redactions);
+			}
 			const command =
 				"cat own.txt > /dev/null && printf created > created.txt && " +
 				"printf '%s\\n' ./* > /dev/null && find . -type f > /dev/null";
-			return (await shellExitCode(command, workspace, fence, abortController.signal)) === 0;
+			const result = await shellProbe(command, liveFixture, undefined, abortController.signal);
+			return shellOutcome(
+				result,
+				true,
+				"live profile must allow workspace read, write, glob, and recursion",
+				displayPath,
+				redactions,
+			);
 		});
+
 		await check("named sibling remains reachable", async () => {
-			const command = `cd ${quote(sibling)} && test "$(cat named.txt)" = sibling`;
-			return (await shellExitCode(command, workspace, fence, abortController.signal)) === 0;
+			const displayPath = "<session-parent>/<synthetic-sibling>";
+			let liveSibling = inheritedSibling;
+			if (liveSibling === undefined) {
+				try {
+					liveSibling = await fs.mkdtemp(path.join(path.dirname(liveWorkspace), ".xcsh-sandbox-check-sibling-"));
+					fixturePaths.push(liveSibling);
+					nonEnumerableCleanupDirs.add(liveSibling);
+					redactions.push([liveSibling, displayPath]);
+					const namedFile = path.join(liveSibling, "named.txt");
+					await Bun.write(namedFile, "sibling\n");
+					knownCleanupLeaves.push(namedFile);
+				} catch (error) {
+					return exceptionOutcome("create named sibling fixture", displayPath, error, redactions);
+				}
+			}
+			const result = await shellProbe(
+				'test "$(cat named.txt)" = sibling',
+				liveSibling,
+				undefined,
+				abortController.signal,
+			);
+			return shellOutcome(result, true, "live profile must allow a named sibling read", displayPath, redactions);
 		});
 
 		if (backend.osEnforced) {
 			await check("session parent cannot be enumerated", async () => {
-				const command = `ls ${quote(workspaces)} > /dev/null`;
-				return (await shellExitCode(command, workspace, fence, abortController.signal)) !== 0;
+				const result = await shellProbe(
+					`ls ${quote(workspaces)} > /dev/null`,
+					workspace,
+					fence,
+					abortController.signal,
+				);
+				return shellOutcome(
+					result,
+					false,
+					"synthetic session parent enumeration must be refused",
+					"<synthetic-session-parent>",
+					redactions,
+				);
 			});
 			await check("account container cannot be enumerated", async () => {
-				const command = `ls ${quote(accountRoot)} > /dev/null`;
-				return (await shellExitCode(command, workspace, fence, abortController.signal)) !== 0;
+				const result = await shellProbe(
+					`ls ${quote(accountRoot)} > /dev/null`,
+					workspace,
+					fence,
+					abortController.signal,
+				);
+				return shellOutcome(
+					result,
+					false,
+					"synthetic account container enumeration must be refused",
+					"<synthetic-account-container>",
+					redactions,
+				);
 			});
 			await check("synthetic other account cannot be entered", async () => {
-				const command = `cd ${quote(otherHome)}`;
-				return (await shellExitCode(command, workspace, fence, abortController.signal)) !== 0;
+				const result = await shellProbe(`cd ${quote(otherHome)}`, workspace, fence, abortController.signal);
+				return shellOutcome(
+					result,
+					false,
+					"synthetic other account traversal must be refused",
+					"<synthetic-other-account>",
+					redactions,
+				);
 			});
 			await check("cross-session stores cannot be read", async () => {
-				const sessionRead = `cat ${quote(path.join(otherSession, "state.jsonl"))} > /dev/null`;
-				const memoryRead = `cat ${quote(path.join(otherMemory, "MEMORY.md"))} > /dev/null`;
-				return (
-					(await shellExitCode(sessionRead, workspace, fence, abortController.signal)) !== 0 &&
-					(await shellExitCode(memoryRead, workspace, fence, abortController.signal)) !== 0
+				const sessionRead = await shellProbe(
+					`cat ${quote(path.join(otherSession, "state.jsonl"))} > /dev/null`,
+					workspace,
+					fence,
+					abortController.signal,
+				);
+				const sessionOutcome = shellOutcome(
+					sessionRead,
+					false,
+					"synthetic other session read must be refused",
+					"<synthetic-session-store>/<synthetic-session>",
+					redactions,
+				);
+				if (!sessionOutcome.passed) return sessionOutcome;
+
+				const memoryRead = await shellProbe(
+					`cat ${quote(path.join(otherMemory, "MEMORY.md"))} > /dev/null`,
+					workspace,
+					fence,
+					abortController.signal,
+				);
+				return shellOutcome(
+					memoryRead,
+					false,
+					"synthetic other memory read must be refused",
+					"<synthetic-memory-store>/<synthetic-memory>",
+					redactions,
 				);
 			});
 		} else {
@@ -207,14 +426,39 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 				"synthetic other account cannot be entered",
 				"cross-session stores cannot be read",
 			]) {
-				add(name, "SKIP");
+				add(name, "SKIP", "OS enforcement backend unavailable; path=<probe>; errno=unsupported");
 			}
 		}
 
 		await check("operator home configuration is writable", async () => {
-			const target = path.join(configDir, "config");
-			const command = `printf operator > ${quote(target)} && test "$(cat ${quote(target)})" = operator`;
-			return (await shellExitCode(command, workspace, fence, abortController.signal)) === 0;
+			const displayPath = "<operator-home>/<synthetic-fixture>";
+			let liveConfig: string;
+			try {
+				// Landlock cannot grant creation on a split directory without also granting every
+				// denied descendant. The live fence therefore grants operator-owned CLI config roots
+				// explicitly; use one of those when another Landlock profile is already inherited.
+				// Standalone and Seatbelt checks retain the direct-home probe.
+				const configBase =
+					inheritedProfile && backend.backend === "landlock" ? path.join(liveHome, ".config", "gh") : liveHome;
+				liveConfig = await fs.mkdtemp(path.join(configBase, ".xcsh-sandbox-check-home-"));
+				fixturePaths.push(liveConfig);
+				redactions.push([liveConfig, displayPath]);
+			} catch (error) {
+				return exceptionOutcome("create operator-home fixture", displayPath, error, redactions);
+			}
+			const result = await shellProbe(
+				'printf operator > config && test "$(cat config)" = operator',
+				liveConfig,
+				undefined,
+				abortController.signal,
+			);
+			return shellOutcome(
+				result,
+				true,
+				"live profile must allow operator-home configuration writes",
+				displayPath,
+				redactions,
+			);
 		});
 
 		await check("cwd resets across tool calls", async () => {
@@ -248,24 +492,57 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 					.map(part => part.text)
 					.join("")
 					.trim();
-			return text(moved) === nested && text(reset) === workspace && text(explicit) === nested;
+			const passed = text(moved) === nested && text(reset) === workspace && text(explicit) === nested;
+			return passed
+				? { passed: true }
+				: {
+						passed: false,
+						detail:
+							"tool-call cwd did not reset to <synthetic-workspace> or honor explicit cwd; path=<synthetic-root>; errno=none",
+					};
 		});
-	} catch {
-		add("conformance matrix completed", "FAIL");
+	} catch (error) {
+		const outcome = exceptionOutcome("conformance matrix setup failed", "<probe>", error, redactions);
+		add("conformance matrix setup", "ERROR", outcome.detail);
 	} finally {
 		process.off("SIGINT", interrupt);
 		process.off("SIGTERM", interrupt);
-		if (fixtureRoot === undefined) {
-			add("synthetic fixtures removed", "FAIL");
-		} else {
+		const cleanupFailures: string[] = [];
+		for (const leafPath of [...knownCleanupLeaves].reverse()) {
 			try {
-				await fs.rm(fixtureRoot, { recursive: true, force: true });
-				await fs.stat(fixtureRoot);
-				add("synthetic fixtures removed", "FAIL");
+				await fs.rm(leafPath, { force: true });
 			} catch (error) {
-				add("synthetic fixtures removed", isEnoent(error) ? "PASS" : "FAIL");
+				if (!isEnoent(error)) cleanupFailures.push(error instanceof Error ? error.message : String(error));
 			}
 		}
+		for (const fixturePath of [...fixturePaths].reverse()) {
+			try {
+				// Landlock denies enumeration of the session parent. A sibling created after the
+				// profile snapshot consequently cannot be walked during recursive cleanup, even
+				// though its known leaf and the directory itself can be removed by name.
+				if (nonEnumerableCleanupDirs.has(fixturePath)) await fs.rmdir(fixturePath);
+				else await fs.rm(fixturePath, { recursive: true, force: true });
+				await fs.stat(fixturePath);
+				cleanupFailures.push(`fixture remains at ${fixturePath}`);
+			} catch (error) {
+				if (!isEnoent(error)) cleanupFailures.push(error instanceof Error ? error.message : String(error));
+			}
+		}
+
+		if (cleanupFailures.length > 0) {
+			add(
+				"synthetic fixtures removed",
+				"ERROR",
+				sanitizeDetail(
+					`fixture cleanup incomplete; path=<synthetic-fixtures>; errno=unknown; error=${cleanupFailures.join("; ")}`,
+					redactions,
+				),
+			);
+		} else if (fixturePaths.length === 0) {
+			add("synthetic fixtures removed", "SKIP", "setup created no fixtures; path=<synthetic-fixtures>; errno=none");
+		} else {
+			add("synthetic fixtures removed", "PASS");
+		}
 	}
 
 	const report: SandboxCheckReport = {
@@ -275,9 +552,10 @@ export async function runSandboxCheck(options: SandboxCheckOptions = {}): Promis
 		summary: {
 			passed: checks.filter(result => result.status === "PASS").length,
 			failed: checks.filter(result => result.status === "FAIL").length,
+			errors: checks.filter(result => result.status === "ERROR").length,
 			skipped: checks.filter(result => result.status === "SKIP").length,
 		},
 	};
-	renderReport(report, options.json ?? false);
+	renderReport(report, options.json ?? false, options.verbose ?? false);
 	return report;
 }

package/src/commands/sandbox.ts

@@ -15,11 +15,12 @@ export default class Sandbox extends Command {
 
 	static flags = {
 		json: Flags.boolean({ description: "Output JSON" }),
+		verbose: Flags.boolean({ char: "v", description: "Show failure details" }),
 	};
 
 	async run(): Promise<void> {
 		const { flags } = await this.parse(Sandbox);
-		const report = await runSandboxCheck({ json: flags.json });
-		if (report.summary.failed > 0) process.exitCode = 1;
+		const report = await runSandboxCheck({ json: flags.json, verbose: flags.verbose });
+		if (report.summary.failed > 0 || report.summary.errors > 0) process.exitCode = 1;
 	}
 }

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.1.0",
-	"commit": "a4002d84fa2f409413a313cb8a04670a1b107084",
-	"shortCommit": "a4002d8",
+	"version": "20.1.2",
+	"commit": "b5534d98c8ad483cc6e8709b44242cf3ea98041d",
+	"shortCommit": "b5534d9",
 	"branch": "main",
-	"tag": "v20.1.0",
-	"commitDate": "2026-08-01T13:46:31Z",
-	"buildDate": "2026-08-01T14:24:45.281Z",
+	"tag": "v20.1.2",
+	"commitDate": "2026-08-01T21:09:01Z",
+	"buildDate": "2026-08-01T21:30:18.970Z",
 	"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/a4002d84fa2f409413a313cb8a04670a1b107084",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.1.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/b5534d98c8ad483cc6e8709b44242cf3ea98041d",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.1.2"
 };

package/src/internal-urls/console-catalog.generated.ts

@@ -2,10 +2,10 @@
 
 import type { ConsoleCatalogData } from "./console-catalog-types";
 
-export const CONSOLE_CATALOG_VERSION = "8e7e1863840cc8ed4db0a9781c695f251aafb214";
+export const CONSOLE_CATALOG_VERSION = "ea6ed666f67f016f68f4e538d1f22e44e18d11a2";
 
 export const CONSOLE_CATALOG_DATA: ConsoleCatalogData = {
-	version: "8e7e1863840cc8ed4db0a9781c695f251aafb214",
+	version: "ea6ed666f67f016f68f4e538d1f22e44e18d11a2",
 	workflows: {
 		"address-allocator/create":
 			'---\nschema: urn:xcsh:console:workflow:v1\nid: address-allocator-create\nlabel: Create IP Address Allocators\nresource: address-allocator\noperation: create\npreconditions:\n  - user_logged_in\n  - "role_minimum: admin"\nparams:\n  name:\n    required: true\n    description: IP Address Allocators name (lowercase alphanumeric and hyphens)\n    example: example-address-allocator\n  address_allocator_mode:\n    required: true\n    description: Address Allocator Mode\n  allocation_unit:\n    required: false\n    description: Allocation Unit\n    default: 0\n  address_pool:\n    required: false\n    description: Address Pool\n    default: value\n  address_allocation_scheme:\n    required: false\n    description: "Server-required: Field should be not nil"\n    default: value\nsteps:\n  - id: navigate-to-list\n    action: navigate\n    url: /web/workspaces/multi-cloud-network-connect/manage/networking/legacy_network_configuration/address_allocators\n    wait_for: text(\'IP Address Allocators\')\n    description: Navigate to IP Address Allocators list page\n  - id: click-add-tab\n    action: click\n    selector: text(\'Add IP Address Allocator\')\n    wait_for: textbox[name=\'Name\']\n    description: Click Add IP Address Allocator to open the create form\n  - id: fill-name\n    action: fill\n    selector: textbox[name=\'Name\']\n    value: "{name}"\n    description: Enter Name\n  - id: select-address_allocator_mode\n    action: select\n    selector: listbox\n    context: Address Allocator Mode section\n    value: "{address_allocator_mode}"\n    description: Select Address Allocator Mode\n  - id: fill-allocation_unit\n    action: fill\n    selector: spinbutton[name=\'Allocation Unit\']\n    value: "{allocation_unit}"\n    description: Set Allocation Unit\n  - id: fill-address_pool\n    action: fill\n    selector: ngx-datatable input.form-control\n    context: Address Pool table\n    value: "{address_pool}"\n    description: Enter Address Pool in the existing table row (no Add Item needed — the table ships one empty row)\n  - id: select-address_allocation_scheme\n    action: select\n    selector: listbox\n    context: Address Allocation Scheme section\n    value: "{address_allocation_scheme}"\n    description: Select Address Allocation Scheme\n  - id: save\n    action: click\n    selector: "[class*=\'save-bt\'],[class*=\'submit-button\']"\n    context: footer\n    wait_for: text(\'{name}\')\n    wait_timeout_ms: 30000\n    description: Save/submit the form (union selector matches save-bt OR submit-button)\npostconditions:\n  - resource_list_page_visible\n  - "resource_name_in_list: {name}"\nmetadata:\n  confidence: inferred\n  discovered_at: 2026-06-24\n  console_version: "2025.06"\n  notes: Auto-generated by scripts/generate-workflows.ts from api-specs-enriched field metadata.\n',
@@ -978,8 +978,6 @@ export const CONSOLE_CATALOG_DATA: ConsoleCatalogData = {
 			"---\nschema: urn:xcsh:console:resource:v1\nid: securemesh-site\nlabel: Secure Mesh Sites\n_source: Generated from api-specs-enriched/config/console_ui.yaml\napi:\n  kind: securemesh_site\nconsole:\n  workspace: multi-cloud-network-connect\n  workspace_label: Multi-Cloud Network Connect\n  route_prefix: /web/workspaces/multi-cloud-network-connect\n  route_pattern: /manage/site_management/legacy_configs/securemesh_site\n  menu_path:\n    - Manage\n    - Site Management\n    - Legacy Configurations\n    - Secure Mesh Sites\n  breadcrumbs:\n    - Home\n    - Multi-Cloud Network Connect\n    - Manage\n    - Site Management\n    - Legacy Configurations\n    - Secure Mesh Sites\n  namespace_scoped: false\nadd_action:\n  type: tab\n  label: Add Secure Mesh Site\nsave_action:\n  label: Add Secure Mesh Site\ncancel_action:\n  label: Cancel All\nform_tabs:\n  - Form\n  - Documentation\n  - JSON\nform:\n  sections:\n    - id: metadata\n      label: Metadata\n      api_fields:\n        - metadata.name\n        - metadata.labels\n        - metadata.description\nenriched_fields:\n  count: 25\n  source: api-specs-enriched/config/console_field_metadata.yaml\nmetadata:\n  confidence: validated\n  discovered_at: '2026-06-16'\n  console_version: '2025.06'\n",
 		"securemesh-site-v2":
 			"---\nschema: urn:xcsh:console:resource:v1\nid: securemesh-site-v2\nlabel: Secure Mesh Sites v2\n_source: Generated from api-specs-enriched/config/console_ui.yaml\napi:\n  kind: securemesh_site_v2\nconsole:\n  workspace: multi-cloud-network-connect\n  workspace_label: Multi-Cloud Network Connect\n  route_prefix: /web/workspaces/multi-cloud-network-connect\n  route_pattern: /manage/site_management/cloud_sites/securemesh_site_v2\n  menu_path:\n    - Manage\n    - Site Management\n    - Customer Edges\n    - Secure Mesh Sites v2\n  breadcrumbs:\n    - Home\n    - Multi-Cloud Network Connect\n    - Manage\n    - Site Management\n    - Customer Edges\n    - Secure Mesh Sites v2\n  namespace_scoped: false\nadd_action:\n  type: tab\n  label: Add Secure Mesh Site v2\nsave_action:\n  label: Add Secure Mesh Site v2\ncancel_action:\n  label: Cancel All\nform_tabs:\n  - Form\n  - Documentation\n  - JSON\nform:\n  sections:\n    - id: metadata\n      label: Metadata\n      api_fields:\n        - metadata.name\n        - metadata.labels\n        - metadata.description\nenriched_fields:\n  count: 8\n  source: api-specs-enriched/config/console_field_metadata.yaml\nmetadata:\n  confidence: validated\n  discovered_at: '2026-06-16'\n  console_version: '2025.06'\n",
-		"securemesh-site-v2-cloud":
-			"---\nschema: urn:xcsh:console:resource:v1\nid: securemesh-site-v2-cloud\nlabel: Secure Mesh Sites v2\n_source: Generated from api-specs-enriched/config/console_ui.yaml\napi:\n  kind: securemesh_site_v2_cloud\nconsole:\n  workspace: multi-cloud-network-connect\n  workspace_label: Multi-Cloud Network Connect\n  route_prefix: /web/workspaces/multi-cloud-network-connect\n  route_pattern: /manage/site_management/cloud_sites/securemesh_site_v2\n  menu_path:\n    - Manage\n    - Site Management\n    - Customer Edges\n    - Secure Mesh Sites v2\n  breadcrumbs:\n    - Home\n    - Multi-Cloud Network Connect\n    - Manage\n    - Site Management\n    - Customer Edges\n    - Secure Mesh Sites v2\n  namespace_scoped: false\nadd_action:\n  type: tab\n  label: Add Secure Mesh Site\nsave_action:\n  label: Add Secure Mesh Site\ncancel_action:\n  label: Cancel All\nform_tabs:\n  - Form\n  - Documentation\n  - JSON\nform:\n  sections:\n    - id: metadata\n      label: Metadata\n      api_fields:\n        - metadata.name\n        - metadata.labels\n        - metadata.description\nmetadata:\n  confidence: validated\n  discovered_at: '2026-06-17'\n  console_version: '2025.06'\n  notes: This is the v2 cloud sites path — differs from securemesh_site_v2 which may have a different route\n",
 		segment:
 			"---\nschema: urn:xcsh:console:resource:v1\nid: segment\nlabel: Segments\n_source: Generated from api-specs-enriched/config/console_ui.yaml\napi:\n  kind: segment\nconsole:\n  workspace: multi-cloud-network-connect\n  workspace_label: Multi-Cloud Network Connect\n  route_prefix: /web/workspaces/multi-cloud-network-connect\n  route_pattern: /manage/networking/network_configuration/segment\n  menu_path:\n    - Manage\n    - Networking\n    - Network Configuration\n    - Segments\n  breadcrumbs:\n    - Home\n    - Multi-Cloud Network Connect\n    - Manage\n    - Networking\n    - Network Configuration\n    - Segments\n  namespace_scoped: false\nadd_action:\n  type: tab\n  label: Add Segment\nsave_action:\n  label: Add Segment\ncancel_action:\n  label: Cancel All\nform_tabs:\n  - Form\n  - Documentation\n  - JSON\nform:\n  sections:\n    - id: metadata\n      label: Metadata\n      api_fields:\n        - metadata.name\n        - metadata.labels\n        - metadata.description\nenriched_fields:\n  count: 4\n  source: api-specs-enriched/config/console_field_metadata.yaml\nmetadata:\n  confidence: validated\n  discovered_at: '2026-06-16'\n  console_version: '2025.06'\n",
 		"segment-connection":

package/src/sandbox/session-fence.ts

@@ -16,6 +16,18 @@
  */
 import { buildContainmentFence, type ContainmentFence } from "./containment";
 
+/**
+ * Trusted context added to commands launched by the fenced model bash tool.
+ *
+ * A subprocess cannot infer the session anchor after a command-local `cd`, and an inherited OS
+ * sandbox cannot be loosened. The installed sandbox diagnostic uses these values to place its
+ * allow-side fixtures inside paths the live bash profile already grants instead of inventing a
+ * second workspace under the system temp directory (#2800).
+ */
+export const SANDBOX_SESSION_ROOT_ENV = "XCSH_SANDBOX_SESSION_ROOT";
+export const SANDBOX_OPERATOR_HOME_ENV = "XCSH_SANDBOX_OPERATOR_HOME";
+export const SANDBOX_CHECK_NAMED_SIBLING_ENV = "XCSH_SANDBOX_CHECK_NAMED_SIBLING";
+
 /** The slice of `Settings` this needs — supplied explicitly so the caller names its own source. */
 export interface SettingsReader {
 	get(key: string): unknown;

package/src/tools/bash.ts

@@ -1,4 +1,6 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type {
 	AgentTool,
 	AgentToolContext,
@@ -17,7 +19,12 @@ import { truncateToVisualLines } from "../modes/components/visual-truncate";
 import type { Theme } from "../modes/theme/theme";
 import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
 import { type ContainmentFence, containmentStatus, fenceVerdict } from "../sandbox/containment";
-import { resolveSessionFence } from "../sandbox/session-fence";
+import {
+	resolveSessionFence,
+	SANDBOX_CHECK_NAMED_SIBLING_ENV,
+	SANDBOX_OPERATOR_HOME_ENV,
+	SANDBOX_SESSION_ROOT_ENV,
+} from "../sandbox/session-fence";
 import { SECRET_ENV_PATTERNS, type SecretObfuscator } from "../secrets";
 import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
@@ -177,6 +184,21 @@ function normalizeBashEnv(env: Record<string, string> | undefined): Record<strin
 	return normalized;
 }
 
+/** Canonical context resolved by the unfenced host before a child inherits the live profile. */
+async function canonicalizeSandboxContextPath(input: string): Promise<string> {
+	try {
+		return await fs.promises.realpath(input);
+	} catch {
+		// The fence builder already handles an unavailable home conservatively. Keep ordinary bash calls
+		// working in that case; the diagnostic will report the path-specific failure if it is invoked.
+		return input;
+	}
+}
+
+function invokesSandboxCheck(command: string): boolean {
+	return /(?:xcsh(?:-[a-z0-9-]+)?|cli\.ts)["']?\s+["']?sandbox["']?\s+["']?check["']?(?:\s|$)/iu.test(command);
+}
+
 function escapeBashEnvValueForDisplay(value: string): string {
 	return value
 		.replaceAll("\\", "\\\\")
@@ -557,11 +579,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	 * RPC `bash` reach it too, and the same brush-core runs credential helpers and the interactive
 	 * `xcsh shell`. Only the model's tool call is fenced (#2554).
 	 */
-	#containmentFence() {
+	#containmentFence(root = this.#containmentRoot()) {
 		const artifactsDir = this.session.getArtifactsDir?.();
 		// One resolver, shared with `sandbox-guard` and the internal-URL check, so the pre-check and the
 		// kernel cannot be looking at different boundaries (#2624).
-		return resolveSessionFence(this.#containmentRoot(), this.session.settings, {
+		return resolveSessionFence(root, this.session.settings, {
 			extraRoots: artifactsDir ? [artifactsDir] : [],
 		});
 	}
@@ -583,7 +605,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		ctx?: AgentToolContext,
 	): Promise<AgentToolResult<BashToolDetails>> {
 		let command = rawCommand;
-		const env = normalizeBashEnv(rawEnv);
+		const requestedEnv = normalizeBashEnv(rawEnv);
 
 		// Extract leading `cd <path> && ...` into cwd when the model ignores the cwd parameter.
 		if (!cwd) {
@@ -627,7 +649,27 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// different configurations — which doubled a cost that lands as user-visible latency. Sharing is
 		// also the more correct answer: the internal-URL check and the shell are then reasoning about the
 		// same boundary rather than two that merely agree today.
-		const fence = this.#containmentFence();
+		const containmentRoot = this.#containmentRoot();
+		const fence = this.#containmentFence(containmentRoot);
+		const sandboxCheckInvocation = fence !== undefined && invokesSandboxCheck(command);
+		// A nested `xcsh sandbox check` must exercise the grants of this exact live profile. Seatbelt and
+		// Landlock restrictions compose and cannot be relaxed by its subprocess, so the diagnostic needs
+		// the immutable session anchor even when this individual call uses `cwd` or starts with `cd`.
+		// Keep these values host-owned: tool-supplied env cannot replace them.
+		let env = requestedEnv;
+		let trustedSessionRoot = containmentRoot;
+		if (fence !== undefined) {
+			const [canonicalSessionRoot, trustedOperatorHome] = await Promise.all([
+				canonicalizeSandboxContextPath(containmentRoot),
+				canonicalizeSandboxContextPath(os.homedir()),
+			]);
+			trustedSessionRoot = canonicalSessionRoot;
+			env = {
+				...requestedEnv,
+				[SANDBOX_SESSION_ROOT_ENV]: trustedSessionRoot,
+				[SANDBOX_OPERATOR_HOME_ENV]: trustedOperatorHome,
+			};
+		}
 
 		const localOptions = {
 			getArtifactsDir: this.session.getArtifactsDir,
@@ -670,6 +712,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const obfuscator = this.session.obfuscator;
 		_sessionObfuscator = obfuscator; // Keep module-level ref fresh for renderer
 		const maskSecrets = obfuscator?.hasSecrets() ? (t: string) => obfuscator.obfuscate(t) : undefined;
+		if (asyncRequested && sandboxCheckInvocation) {
+			throw new ToolError("Sandbox check must run synchronously so its synthetic fixtures can be removed.");
+		}
 
 		if (asyncRequested) {
 			if (!this.session.asyncJobManager) {
@@ -690,7 +735,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec);
 		}
 
-		if (this.#autoBackgroundEnabled && !pty && this.session.asyncJobManager) {
+		if (this.#autoBackgroundEnabled && !pty && this.session.asyncJobManager && !sandboxCheckInvocation) {
 			const autoBackgroundWaitMs = this.#resolveAutoBackgroundWaitMs(timeoutMs);
 			const startBackgrounded = autoBackgroundWaitMs === 0;
 			const job = this.#startManagedBashJob({
@@ -748,41 +793,60 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		const osBackend = containmentStatus(fence !== undefined);
 		const ptyConfinable = !osBackend.osEnforced || osBackend.backend === "seatbelt";
 		const usePty = pty && ptyConfinable && $env.PI_NO_PTY !== "1" && ctx?.hasUI === true && ctx.ui !== undefined;
-		const result: BashResult | BashInteractiveResult = usePty
-			? await runInteractiveBashPty(ctx.ui!, {
-					command,
-					cwd: commandCwd,
-					timeoutMs,
-					signal,
-					env,
-					artifactPath,
-					artifactId,
-					maskSecrets,
-					// The same fence that decided `ptyConfinable`, so the gate and the enforcement can
-					// never be looking at different answers.
-					fence,
-				})
-			: await executeBash(command, {
-					cwd: commandCwd,
-					sessionKey: this.session.getSessionId?.() ?? undefined,
-					timeout: timeoutMs,
-					signal,
-					env,
-					artifactPath,
-					artifactId,
-					maskSecrets,
-					fence,
-					onChunk: chunk => {
-						tailBuffer.append(chunk);
-						if (onUpdate) {
-							const preview = maskSecrets ? maskSecrets(tailBuffer.text()) : tailBuffer.text();
-							onUpdate({
-								content: [{ type: "text", text: preview }],
-								details: {},
-							});
-						}
-					},
-				});
+		let sandboxCheckSibling: string | undefined;
+		if (sandboxCheckInvocation) {
+			// Landlock cannot add a newly-created child to an already-applied profile. Prepare the named
+			// sibling before the child is confined so the diagnostic measures reachability, not whether a
+			// nested sandbox can widen itself. The host owns both this path and its cleanup.
+			sandboxCheckSibling = await fs.promises.mkdtemp(
+				path.join(path.dirname(trustedSessionRoot), ".xcsh-sandbox-check-live-sibling-"),
+			);
+			await Bun.write(path.join(sandboxCheckSibling, "named.txt"), "sibling\n");
+			env = { ...env, [SANDBOX_CHECK_NAMED_SIBLING_ENV]: sandboxCheckSibling };
+		}
+
+		let result: BashResult | BashInteractiveResult;
+		try {
+			result = usePty
+				? await runInteractiveBashPty(ctx.ui!, {
+						command,
+						cwd: commandCwd,
+						timeoutMs,
+						signal,
+						env,
+						artifactPath,
+						artifactId,
+						maskSecrets,
+						// The same fence that decided `ptyConfinable`, so the gate and the enforcement can
+						// never be looking at different answers.
+						fence,
+					})
+				: await executeBash(command, {
+						cwd: commandCwd,
+						sessionKey: this.session.getSessionId?.() ?? undefined,
+						timeout: timeoutMs,
+						signal,
+						env,
+						artifactPath,
+						artifactId,
+						maskSecrets,
+						fence,
+						onChunk: chunk => {
+							tailBuffer.append(chunk);
+							if (onUpdate) {
+								const preview = maskSecrets ? maskSecrets(tailBuffer.text()) : tailBuffer.text();
+								onUpdate({
+									content: [{ type: "text", text: preview }],
+									details: {},
+								});
+							}
+						},
+					});
+		} finally {
+			if (sandboxCheckSibling !== undefined) {
+				await fs.promises.rm(sandboxCheckSibling, { recursive: true, force: true });
+			}
+		}
 		if (result.cancelled) {
 			if (signal?.aborted) {
 				throw new ToolAbortError(normalizeResultOutput(result) || "Command aborted");