@f5-sales-demo/xcsh 20.2.2 → 20.2.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [20.2.4] - 2026-08-02
+
+### Fixed
+
+- Preserved command exit status while evaluating assignment-only shell commands so canonical captures such as `rc=$?` retain failures ([#2837](https://github.com/f5-sales-demo/xcsh/issues/2837))
+
+## [20.2.3] - 2026-08-02
+
+### Fixed
+
+- Made sandbox launch-flag scope errors consistent in either argument position, report usage exit 2 without parser exceptions, and direct operators to the flag-free conformance check ([#2834](https://github.com/f5-sales-demo/xcsh/issues/2834))
+
 ## [20.2.1] - 2026-08-01
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.2.2",
+	"version": "20.2.4",
 	"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.2.2",
-		"@f5-sales-demo/pi-agent-core": "20.2.2",
-		"@f5-sales-demo/pi-ai": "20.2.2",
-		"@f5-sales-demo/pi-natives": "20.2.2",
-		"@f5-sales-demo/pi-resource-management": "20.2.2",
-		"@f5-sales-demo/pi-tui": "20.2.2",
-		"@f5-sales-demo/pi-utils": "20.2.2",
+		"@f5-sales-demo/xcsh-stats": "20.2.4",
+		"@f5-sales-demo/pi-agent-core": "20.2.4",
+		"@f5-sales-demo/pi-ai": "20.2.4",
+		"@f5-sales-demo/pi-natives": "20.2.4",
+		"@f5-sales-demo/pi-resource-management": "20.2.4",
+		"@f5-sales-demo/pi-tui": "20.2.4",
+		"@f5-sales-demo/pi-utils": "20.2.4",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/cli/flag-spec.ts

@@ -13,7 +13,7 @@
  * `cli/args.ts` can both depend on it without a cycle.
  */
 import { THINKING_EFFORTS } from "@f5-sales-demo/pi-ai";
-import { type FlagDescriptor, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { CliUsageError, type FlagDescriptor, Flags } from "@f5-sales-demo/pi-utils/cli";
 
 export type FlagArity = "boolean" | "value" | "optional-value" | "repeatable-value";
 
@@ -157,8 +157,6 @@ export interface UnrecognizedFlag {
 	name: string;
 }
 
-export class FlagUsageError extends Error {}
-
 /**
  * Rewrite `--name=value` into `["--name", "value"]` for every flag that takes a value.
  *
@@ -197,7 +195,7 @@ export function normalizeFlagTokens(
 		const spec = flagSpec(name);
 		if (spec) {
 			if (!takesValue(spec)) {
-				throw new FlagUsageError(`--${name} is a boolean flag and does not take a value`);
+				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
 			}
 			normalized.push(`--${name}`, value);
 			continue;
@@ -206,7 +204,7 @@ export function normalizeFlagTokens(
 		const extension = extensionFlags?.get(name);
 		if (extension) {
 			if (extension.type === "boolean") {
-				throw new FlagUsageError(`--${name} is a boolean flag and does not take a value`);
+				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
 			}
 			normalized.push(`--${name}`, value);
 			continue;

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

@@ -1,3 +1,4 @@
+import type { FlagDescriptor } from "@f5-sales-demo/pi-utils/cli";
 import { flagNameForChar, flagSpec, type LaunchFlagName } from "./flag-spec";
 
 export interface PrefixedCommandRoute {
@@ -6,6 +7,67 @@ export interface PrefixedCommandRoute {
 	prefixFlags: LaunchFlagName[];
 }
 
+function uniqueFlags(flags: readonly LaunchFlagName[]): LaunchFlagName[] {
+	return [...new Set(flags)];
+}
+
+/**
+ * Find agent-launch flags in a registered command's argv while preserving that command's own flags.
+ *
+ * `--` ends option parsing. Long and short command flags both take precedence over identically named
+ * launch flags, so `sandbox check -v` remains the sandbox check's verbose mode.
+ */
+export function findCommandLaunchFlags(
+	argv: readonly string[],
+	commandFlags: Readonly<Record<string, FlagDescriptor>>,
+): LaunchFlagName[] {
+	const shortCommandFlags = new Set(
+		Object.values(commandFlags)
+			.map(descriptor => descriptor.char)
+			.filter((char): char is string => char !== undefined),
+	);
+	const found: LaunchFlagName[] = [];
+
+	for (const token of argv) {
+		if (token === "--") break;
+		if (token.startsWith("--")) {
+			const name = token.slice(2).split("=", 1)[0];
+			if (commandFlags[name] !== undefined) continue;
+			if (flagSpec(name) !== undefined) found.push(name as LaunchFlagName);
+			continue;
+		}
+		if (!token.startsWith("-") || token === "-") continue;
+		const char = token.slice(1);
+		if (shortCommandFlags.has(char)) continue;
+		const name = flagNameForChar(char);
+		if (name !== undefined) found.push(name);
+	}
+
+	return uniqueFlags(found);
+}
+
+/** Render the single scope diagnostic used for launch flags on either side of a subcommand. */
+export function launchFlagScopeMessage(
+	flags: readonly LaunchFlagName[],
+	command: string,
+	commandArgs: readonly string[],
+	bin: string,
+): string {
+	const unique = uniqueFlags(flags);
+	const names = unique.map(flag => `--${flag}`).join(", ");
+	const singular = unique.length === 1;
+	if (command === "sandbox" && commandArgs[0] === "check") {
+		return (
+			`Launch ${singular ? "flag" : "flags"} ${names} ${singular ? "applies" : "apply"} to an agent session, not to \`sandbox check\`. ` +
+			`Run \`${bin} sandbox check\` without launch flags; its \`explicit grant restores parent enumeration\` probe verifies grant behavior.`
+		);
+	}
+	return (
+		`Launch ${singular ? "flag" : "flags"} ${names} ${singular ? "applies" : "apply"} to an agent session, not to the ` +
+		`\`${command}\` subcommand. Start an agent session with launch flags before its prompt.`
+	);
+}
+
 function optionalValue(token: string | undefined): token is string {
 	return token !== undefined && !token.startsWith("-") && !token.startsWith("@");
 }

package/src/cli.ts

@@ -5,8 +5,7 @@ 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 { findPrefixedCommand, launchFlagScopeMessage } from "./cli/root-command-routing";
 import { locales } from "./locales/index";
 
 registerLocales(locales);
@@ -118,10 +117,13 @@ export function runCli(argv: string[]): Promise<void> {
 				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`,
+			`Error: ${launchFlagScopeMessage(
+				prefixedCommand.prefixFlags,
+				prefixedCommand.command,
+				prefixedCommand.commandArgs,
+				APP_NAME,
+			)}\n`,
 		);
 		process.exitCode = 2;
 		return Promise.resolve();
@@ -152,10 +154,4 @@ if (process.env.XCSH_SMOKE_TEST_SPECS === "1") {
 	process.exit(domainCount > 0 && categoryCount > 0 ? 0 : 1);
 }
 
-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;
-}
+await runCli(process.argv.slice(2));

package/src/commands/sandbox.ts

@@ -1,5 +1,7 @@
 /** Run installed-binary sandbox diagnostics. */
-import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { APP_NAME } from "@f5-sales-demo/pi-utils";
+import { Args, CliUsageError, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { findCommandLaunchFlags, launchFlagScopeMessage } from "../cli/root-command-routing";
 import { runSandboxCheck } from "../cli/sandbox-check";
 
 export default class Sandbox extends Command {
@@ -19,6 +21,10 @@ export default class Sandbox extends Command {
 	};
 
 	async run(): Promise<void> {
+		const launchFlags = findCommandLaunchFlags(this.argv, Sandbox.flags);
+		if (launchFlags.length > 0) {
+			throw new CliUsageError(launchFlagScopeMessage(launchFlags, "sandbox", this.argv, APP_NAME));
+		}
 		const { flags } = await this.parse(Sandbox);
 		const report = await runSandboxCheck({ json: flags.json, verbose: flags.verbose });
 		if (report.summary.failed > 0 || report.summary.errors > 0) process.exitCode = 1;

package/src/exec/bash-executor.ts

@@ -120,11 +120,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	const CWD_SENTINEL_END = ":__XCSH_CWD_END__";
 	// Exit-code capture sentinel — the persistent shell's own exit code reflects
 	// the trailing printf (always 0), so the user command's actual exit status
-	// must be captured in-band. `$?` is referenced directly as a printf argument
-	// (see finalCommand below) because a variable-assignment capture like
-	// `_x=$?` resets `$?` to 0 in brush-core before the RHS is evaluated. Without
-	// this sentinel, subprocess failures like `false`, `ls /nonexistent`, or
-	// `(exit 3)` silently report success.
+	// must be captured in-band before another command replaces it. Without this
+	// sentinel, subprocess failures like `false`, `ls /nonexistent`, or `(exit 3)`
+	// silently report success.
 	const EXIT_SENTINEL_START = "__XCSH_EXIT__:";
 	const EXIT_SENTINEL_END = ":__XCSH_EXIT_END__";
 
@@ -167,12 +165,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	}
 
 	// Append CWD + exit-code sentinels only for persistent shell sessions.
-	// `$?` must be referenced DIRECTLY in the printf arguments — using a
-	// variable assignment like `_x=$?` first resets `$?` to 0 in brush-core
-	// before the RHS is evaluated, defeating the capture. The persistent
-	// shell's winner.exitCode always reflects the printf's return (0), so
-	// the EXIT sentinel is the authoritative source for the user command's
-	// actual exit status.
+	// The persistent shell's winner.exitCode reflects the trailing printf's
+	// return (0), so the EXIT sentinel is the authoritative source for the user
+	// command's actual exit status.
 	const finalCommand = shellSession
 		? `${prefixedCommand}\nprintf '${CWD_SENTINEL_START}%s${CWD_SENTINEL_END}\\n${EXIT_SENTINEL_START}%s${EXIT_SENTINEL_END}\\n' "$PWD" "$?"`
 		: prefixedCommand;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.2.2",
-	"commit": "fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
-	"shortCommit": "fd7d7d7",
+	"version": "20.2.4",
+	"commit": "b47f63ed7ea202dbcc870fbbcc39c20f17814143",
+	"shortCommit": "b47f63e",
 	"branch": "main",
-	"tag": "v20.2.2",
-	"commitDate": "2026-08-02T01:16:07Z",
-	"buildDate": "2026-08-02T01:43:23.755Z",
+	"tag": "v20.2.4",
+	"commitDate": "2026-08-02T04:49:38Z",
+	"buildDate": "2026-08-02T05:15:27.513Z",
 	"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/fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.2.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/b47f63ed7ea202dbcc870fbbcc39c20f17814143",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.2.4"
 };