@f5-sales-demo/xcsh 20.3.2 → 20.4.0

package/src/sandbox/command-operands.ts

@@ -1,216 +1,5 @@
-/**
- * Which words of a command are provably *not* filesystem references.
- *
- * The read-boundary scan in `enforce.ts` finds path-like tokens by scanning raw command text. That
- * is indiscriminate on purpose, and it is what makes the scan hard to fool — it sees inside quoted
- * scripts, heredoc bodies and nested commands by accident. It also produces the false positives in
- * issue #2470: `sed -n '/a/p'` is refused because `/a/p` is absolute-looking, even though sed never
- * opens it.
- *
- * So this module does not replace that scan. It identifies the narrow set of words a command
- * demonstrably treats as a script or a pattern rather than a filename; `enforce.ts` blanks those
- * spans and re-runs the scan over what is left. The scan remains the floor.
- *
- * Note the exemption is *positional*. An earlier version subtracted token strings, which lost track
- * of which occurrence a token came from: exempting the quoted operand of
- * `echo '/elsewhere/x' && cat /elsewhere/x` also cleared the identical token belonging to `cat`.
- *
- * The invariant to preserve: an exemption must never let a command read a file it would not
- * otherwise open. Concretely, that means every one of these must stay unexempted, because each one
- * really does open the path inside it — `test/sandbox-enforce.test.ts` pins all of them:
- *
- *     sh -c 'cat /work/custB/x'          the shell runs the string
- *     bash <<'EOF' … EOF                 the heredoc body is a script
- *     find . -exec sh -c '…' \;          -exec consumes a whole command run
- *     sed -n 'r /work/custB/x'           sed's `r` reads a file
- *     sed 's|x|cat /work/custB/x|e'      sed's `e` flag executes the replacement
- *     awk 'BEGIN { getline x < "…" }'    awk's getline reads a file
- *
- * When a dialect construct cannot be ruled out, do not exempt. A missed construct is a sandbox
- * escape; a falsely-detected one is only a false positive the current code already produces.
- */
 import type { ShellSimpleCommand, ShellWord } from "../tools/shell-lex";
 
-interface OperandSpec {
-	/** Count of leading non-option operands that are scripts or patterns rather than files. */
-	readonly exemptLeading: number;
-	/** Options that relocate the script, so no leading operand is exemptible. */
-	readonly suppressedBy: readonly string[];
-	/** Options taking no argument. Anything not listed here or in `valueOptions` disables exemption. */
-	readonly booleanOptions: readonly string[];
-	/** Options whose following word is a value, not an operand. */
-	readonly valueOptions: readonly string[];
-	/** Set when every operand is text the command never interprets as a path. */
-	readonly exemptAll?: true;
-	/** Dialect whose file-access constructs must be absent for the exemption to hold. */
-	readonly dialect?: "sed" | "awk";
-}
-
-const SED: OperandSpec = {
-	exemptLeading: 1,
-	suppressedBy: ["-e", "--expression", "-f", "--file"],
-	booleanOptions: [
-		"-n",
-		"--quiet",
-		"--silent",
-		"-s",
-		"--separate",
-		"-u",
-		"--unbuffered",
-		"-z",
-		"--null-data",
-		"-E",
-		"-r",
-		"--regexp-extended",
-		"--posix",
-		"--debug",
-		"--sandbox",
-	],
-	// -i and -l are deliberately absent: GNU sed attaches -i's suffix and gives -l an argument,
-	// while BSD sed gives -i an argument and treats -l as a flag. Their arity is unknowable here,
-	// so they land in the unrecognized bucket and disable exemption.
-	valueOptions: [],
-	dialect: "sed",
-};
-
-const AWK: OperandSpec = {
-	exemptLeading: 1,
-	suppressedBy: ["-f", "--file", "--source"],
-	booleanOptions: ["--posix", "--traditional", "--re-interval", "-c"],
-	valueOptions: ["-v", "--assign", "-F", "--field-separator"],
-	dialect: "awk",
-};
-
-const GREP: OperandSpec = {
-	exemptLeading: 1,
-	suppressedBy: ["-e", "--regexp", "-f", "--file"],
-	booleanOptions: [
-		"-r",
-		"-R",
-		"--recursive",
-		"-i",
-		"--ignore-case",
-		"-v",
-		"--invert-match",
-		"-n",
-		"--line-number",
-		"-H",
-		"--with-filename",
-		"-h",
-		"--no-filename",
-		"-c",
-		"--count",
-		"-l",
-		"--files-with-matches",
-		"-L",
-		"--files-without-match",
-		"-w",
-		"--word-regexp",
-		"-x",
-		"--line-regexp",
-		"-F",
-		"--fixed-strings",
-		"-E",
-		"--extended-regexp",
-		"-P",
-		"--perl-regexp",
-		"-o",
-		"--only-matching",
-		"-q",
-		"--quiet",
-		"-a",
-		"--text",
-		"-s",
-		"--no-messages",
-		"-z",
-		"--null-data",
-		"-b",
-		"--byte-offset",
-		"--color",
-		"--colour",
-	],
-	valueOptions: [
-		"-m",
-		"--max-count",
-		"-A",
-		"--after-context",
-		"-B",
-		"--before-context",
-		"-C",
-		"--context",
-		"--include",
-		"--exclude",
-		"--exclude-dir",
-	],
-};
-
-const EMITTER: OperandSpec = {
-	exemptLeading: 0,
-	suppressedBy: [],
-	booleanOptions: ["-n", "-e", "-E"],
-	valueOptions: [],
-	exemptAll: true,
-};
-
-/**
- * Per-command operand models.
- *
- * `find` and `rg` are deliberately absent. `find -exec` consumes an entire command run, and `rg` has
- * options that execute a program per input (`--pre`, `--hostname-bin`) — in both cases an operand
- * that looks like a pattern can be a path the command runs, so the cost of drawing the boundary
- * wrong is a bypass rather than a false positive. #2470 reports false positives for neither, so
- * there is nothing to buy. `grep`/`egrep`/`fgrep` stay: their option surface is POSIX-stable and
- * contains nothing that executes.
- */
-const SPECS: Record<string, OperandSpec> = {
-	sed: SED,
-	gsed: SED,
-	awk: AWK,
-	gawk: AWK,
-	mawk: AWK,
-	nawk: AWK,
-	grep: GREP,
-	egrep: GREP,
-	fgrep: GREP,
-	echo: EMITTER,
-	printf: EMITTER,
-};
-
-/** A sed address: a line number, `$`, a `/regex/`, or nothing at all. */
-const SED_ADDRESS = String.raw`(?:\/(?:\\.|[^\/\\])*\/|[0-9]+|\$)?`;
-
-/**
- * sed commands that read a file (`r`, `R`), write one (`w`, `W`), or execute a shell command (`e`),
- * in command position after an optional address range. Anchoring on the address is what keeps
- * `s/red/blue/` exempt while catching `/foo/r file`.
- */
-const SED_FILE_ACCESS = new RegExp(
-	String.raw`(?:^|[;{}\n])\s*${SED_ADDRESS}(?:,${SED_ADDRESS})?\s*!?\s*[rRwWe](?:\s|$)`,
-);
-
-/**
- * A substitution flag that writes a file (`w`) or executes the replacement as a shell command (`e`),
- * as in `s/a/b/w file` or `s|x|cat /elsewhere/secret|e`. The `e` flag makes the script arbitrary
- * code, so a script carrying it is never inert text.
- */
-const SED_SUBSTITUTE_EXECUTES = /s(.)(?:\\.|(?!\1)[^\\])*\1(?:\\.|(?!\1)[^\\])*\1[a-zA-Z0-9]*[we]/;
-
-/** awk constructs that read, write, or execute rather than just matching and printing. */
-const AWK_FILE_ACCESS = [
-	/\bgetline\b/,
-	/\bsystem\s*\(/,
-	/\bclose\s*\(/,
-	/\bfflush\s*\(/,
-	/\|/, // a pipe to or from a command
-	/\b(?:print|printf)\b[^;}\n]*>/,
-];
-
-function hasFileAccessConstruct(dialect: "sed" | "awk" | undefined, script: string): boolean {
-	if (dialect === "sed") return SED_FILE_ACCESS.test(script) || SED_SUBSTITUTE_EXECUTES.test(script);
-	if (dialect === "awk") return AWK_FILE_ACCESS.some(pattern => pattern.test(script));
-	return false;
-}
-
 /** The option name of a word, ignoring any `=value` suffix; undefined when it is not an option. */
 function optionName(text: string): string | undefined {
 	if (!text.startsWith("-") || text === "-" || text === "--") return undefined;
@@ -218,67 +7,6 @@ function optionName(text: string): string | undefined {
 	return equals === -1 ? text : text.slice(0, equals);
 }
 
-/**
- * Words of `cmd` whose contents the invoked command provably never opens as a path.
- *
- * Returns an empty array whenever anything is uncertain: an unknown command, a suppressing option, a
- * word that is unquoted or carries an expansion, a redirect target, or a script containing a
- * file-access construct.
- */
-export function provenExemptWords(cmd: ShellSimpleCommand): ShellWord[] {
-	if (cmd.name === undefined) return [];
-	const spec = SPECS[cmd.name];
-	if (spec === undefined) return [];
-
-	const operandWords = cmd.words.slice(cmd.operandStart);
-
-	// Which operand holds the script depends entirely on how the options parsed, so an option the
-	// model cannot parse exactly makes the whole command unmodellable. Two ways that bites:
-	// a suppressing option carrying an attached argument (`-e's/a/b/'`) would go unrecognized and
-	// let a real file operand slide into the script slot, and an option of unknown arity (`sed -i`)
-	// would shift every operand by one. Both end in exempting a path the command really opens, so
-	// anything unrecognized disables exemption for this command.
-	for (const word of operandWords) {
-		if (word.redirect !== undefined) continue;
-		const option = optionName(word.text);
-		if (option === undefined) continue;
-		if (spec.suppressedBy.includes(option)) return [];
-		if (!spec.booleanOptions.includes(option) && !spec.valueOptions.includes(option)) return [];
-	}
-
-	const exempt: ShellWord[] = [];
-	let leadingSeen = 0;
-
-	for (let i = 0; i < operandWords.length; i++) {
-		const word = operandWords[i];
-
-		// A redirect target is a real file the shell opens, whatever the command does with its args.
-		if (word.redirect !== undefined) continue;
-
-		const option = optionName(word.text);
-		if (option !== undefined) {
-			// An option's value is consumed here so it is never mistaken for the first operand.
-			if (!word.text.includes("=") && spec.valueOptions.includes(option)) i++;
-			continue;
-		}
-
-		if (!spec.exemptAll) {
-			if (leadingSeen >= spec.exemptLeading) continue;
-			leadingSeen++;
-		}
-
-		// Quoting is the author's own signal that the word is data. An unquoted or expansion-bearing
-		// word is not provably anything, so it stays on the floor.
-		if (word.quote !== "single" && word.quote !== "double") continue;
-		if (!word.literal) continue;
-		if (hasFileAccessConstruct(spec.dialect, word.text)) continue;
-
-		exempt.push(word);
-	}
-
-	return exempt;
-}
-
 /** Flag-only options shared by the compressors. */
 const GZIP_BOOLEAN_OPTIONS = [
 	"-1",
@@ -380,8 +108,8 @@ const COPY_BOOLEAN_OPTIONS = [
  * `tar -f` is absent because whether it reads or writes depends on the mode letters, and getting that
  * wrong in the permissive direction is the bug being fixed.
  *
- * Same suppression rule as `provenExemptWords`: an option this model cannot parse exactly shifts operand
- * positions, so anything unrecognized abandons the command rather than guessing at a slot.
+ * An option this model cannot parse exactly shifts operand positions, so anything unrecognized
+ * abandons the command rather than guessing at a slot.
  */
 interface WriteOperandSpec {
 	/** Options taking a separate value, so it is not mistaken for a positional operand. */
@@ -396,8 +124,8 @@ interface WriteOperandSpec {
 	writesAllPositional?: boolean;
 	/** The final positional operand is written (`cp src dst`). */
 	writesLastPositional?: boolean;
-	/** With this option present the destination moves into it, so positional slots stop being writes. */
-	destinationOption?: string;
+	/** Options that move the destination into their value, so positional slots stop being writes. */
+	destinationOptions?: readonly string[];
 	/** Positional operands that are not paths at all — `chmod 644 f`, `chown me f`. */
 	skipLeadingPositional?: number;
 	/** Every positional is written once this option appears (`install -d a b c`). */
@@ -413,7 +141,7 @@ const WRITE_OPERAND_SPECS: Record<string, WriteOperandSpec> = {
 		booleanOptions: ["-a", "--append", "-i", "--ignore-interrupts", "-p"],
 		writesAllPositional: true,
 	},
-	// `of=` is the output file. `if=` stays a read, which is what the floor already gives it.
+	// `of=` is the output file. `if=` is deliberately not interpreted by the pre-check.
 	dd: { valueOptions: [], booleanOptions: [], outputPrefixes: ["of="] },
 	sort: {
 		valueOptions: ["-k", "-t", "-S", "-T", "--key", "--field-separator", "--buffer-size"],
@@ -424,7 +152,7 @@ const WRITE_OPERAND_SPECS: Record<string, WriteOperandSpec> = {
 		valueOptions: ["-S", "--suffix", "-t", "--target-directory"],
 		booleanOptions: COPY_BOOLEAN_OPTIONS,
 		writesLastPositional: true,
-		destinationOption: "-t",
+		destinationOptions: ["-t", "--target-directory"],
 	},
 	// `mv` also REMOVES its sources, so a source in a read-only root is a mutation of that root.
 	// Marking only the destination let `mv /shared/ctx/file .` delete from a read-allowed grant.
@@ -433,13 +161,13 @@ const WRITE_OPERAND_SPECS: Record<string, WriteOperandSpec> = {
 		booleanOptions: ["-f", "--force", "-i", "--interactive", "-n", "--no-clobber", "-v", "--verbose", "-u"],
 		writesLastPositional: true,
 		writesSourcesToo: true,
-		destinationOption: "-t",
+		destinationOptions: ["-t", "--target-directory"],
 	},
 	install: {
 		valueOptions: ["-m", "--mode", "-o", "--owner", "-g", "--group", "-t", "--target-directory", "-S", "--suffix"],
 		booleanOptions: ["-b", "-c", "-C", "-d", "-D", "-p", "-s", "-v", "--verbose", "--backup"],
 		writesLastPositional: true,
-		destinationOption: "-t",
+		destinationOptions: ["-t", "--target-directory"],
 		// `install -d a b c` creates every operand as a directory rather than copying into the last.
 		allPositionalOption: "-d",
 	},
@@ -465,7 +193,7 @@ const WRITE_OPERAND_SPECS: Record<string, WriteOperandSpec> = {
 		valueOptions: ["-S", "--suffix", "-t", "--target-directory"],
 		booleanOptions: ["-b", "-f", "--force", "-i", "-L", "-n", "-P", "-r", "-s", "--symbolic", "-v"],
 		writesLastPositional: true,
-		destinationOption: "-t",
+		destinationOptions: ["-t", "--target-directory"],
 	},
 	shred: {
 		valueOptions: ["-n", "--iterations", "-s", "--size"],
@@ -538,7 +266,8 @@ export function writtenOperandWords(cmd: ShellSimpleCommand): ShellWord[] {
 	// literally named `-t` makes `cp -- -t /drop/secret out/` read as a target-directory option and
 	// relabels a source as a write target.
 	let sawEndOfOptions = false;
-	for (const word of operandWords) {
+	for (let index = 0; index < operandWords.length; index += 1) {
+		const word = operandWords[index];
 		if (word.text === "--") {
 			sawEndOfOptions = true;
 			continue;
@@ -546,7 +275,10 @@ export function writtenOperandWords(cmd: ShellSimpleCommand): ShellWord[] {
 		if (sawEndOfOptions) continue;
 		const option = optionName(word.text);
 		if (option === undefined) continue;
-		if (isOutputOption(spec, option) || spec.valueOptions.includes(option)) continue;
+		if (isOutputOption(spec, option) || spec.valueOptions.includes(option)) {
+			if (!word.text.includes("=")) index += 1;
+			continue;
+		}
 		if (spec.booleanOptions.includes(option)) continue;
 		if (matchesAllPositionalOption(spec, option)) continue;
 		if (bundledBooleans(option, spec) !== undefined) continue;
@@ -583,13 +315,11 @@ export function writtenOperandWords(cmd: ShellSimpleCommand): ShellWord[] {
 				continue;
 			}
 			if (spec.valueOptions.includes(option)) {
-				if (option === spec.destinationOption) destinationMoved = true;
-				if (!attached) {
-					const target = operandWords[index + 1];
-					index += 1;
+				const target = attached ? valueAfterEquals(word) : operandWords[index + 1];
+				if (!attached) index += 1;
+				if (spec.destinationOptions?.includes(option)) {
+					destinationMoved = true;
 					if (target?.literal) written.push(target);
-				} else if (word.literal) {
-					written.push(word);
 				}
 			}
 			continue;
@@ -598,7 +328,7 @@ export function writtenOperandWords(cmd: ShellSimpleCommand): ShellWord[] {
 		// `of=PATH` and friends are positional in shape but name their own direction.
 		const prefix = spec.outputPrefixes?.find(candidate => word.text.startsWith(candidate));
 		if (prefix !== undefined) {
-			if (word.literal) written.push(word);
+			if (word.literal) written.push({ ...word, text: word.text.slice(prefix.length) });
 			continue;
 		}
 

package/src/sandbox/containment.ts

@@ -7,9 +7,9 @@
  * profile could not even `execvp /bin/cat`.
  *
  * So the fence is gentle. It leaves `/usr`, `/tmp`, package caches, the network and process execution
- * alone. Its cross-tenant courtesy removes the discovery step — enumerating the session root's parent —
- * while keeping named operator access. Other operators' accounts, explicit data roots and cross-session
- * state remain denied where the model has no legitimate reason to wander (#2554).
+ * alone. Its cross-tenant courtesy removes discovery by enumerating session, account, and data
+ * containers while keeping named operator access. Xcsh-private cross-session state remains denied
+ * recursively unless the operator grants it explicitly (#2931).
  *
  * Produced declaratively rather than as an ordered rule list, because the two backends disagree about
  * order: seatbelt evaluates rules in sequence with the last match winning, while Landlock only grants
@@ -257,10 +257,8 @@ function canonicalThroughExisting(target: string): string {
  * otherwise deny `/`, `/usr` or `/tmp` — refusing exactly the work this fence is supposed to leave
  * alone.
  *
- * `/Users` and `/home` were here too, and deliberately are no longer: those hold other operators'
- * accounts, so denying them is the point rather than the accident (#2624). The workspace, the caches
- * and the tool config dirs all match at greater depth, and home is denied anyway, so nothing inside
- * the current account changes.
+ * `/Users` and `/home` are deliberately absent: their exact listings are protected separately while
+ * named account paths remain available (#2931).
  */
 function tooBroadToDeny(candidate: string, fsRoot: string): boolean {
 	if (candidate === path.parse(candidate).root) return true;
@@ -348,14 +346,12 @@ function resolveGrants(roots: readonly string[] | undefined, home: string): Set<
  * Filesystem roots other than the one the workspace is on.
  *
  * On POSIX there is one root and this is empty. On Windows every drive letter is its own root, so a
- * workspace on `C:` left `D:\customerB` and any mapped share matching no rule at all — and Windows has
- * no kernel backend, so the command-text scan is the entire boundary there. While that scan was
- * deny-by-default it refused those paths incidentally; making it agree with the fence (#2624) removed
- * the cover and exposed the gap. Found by adversarial review.
+ * workspace on `C:` otherwise leaves the `D:\` account/data container discoverable. Windows has no
+ * kernel backend, so this exact-enumeration rule is enforced for structured tools but cannot confine a
+ * Bash child process.
  *
  * **Unverified on Windows.** The probe below cannot run on the platforms this fleet uses, so what is
- * tested is the denying, not the discovery — see the test, which injects the list. A drive holding a
- * toolchain is opened again with `--allow-path`, which grants at greater depth.
+ * tested is the exact-enumeration protection, not discovery — see the test, which injects the list.
  *
  * UNC paths (`\\server\share`) have no enumerable root and are not covered.
  */
@@ -446,10 +442,12 @@ export function buildContainmentFence(options: ContainmentOptions): ContainmentF
 	// Through `resolveGrants` like the allow-lists, so a session temp dir or artifacts dir that does not
 	// exist yet is still granted rather than silently dropped.
 	const tildeHome = canonical(options.homeForTilde ?? options.home ?? os.homedir()) ?? os.homedir();
-	for (const root of resolveGrants(
-		[options.sessionTmp, ...(options.extraRoots ?? [])].filter((r): r is string => r !== undefined),
+	const sessionTmpResolved = resolveGrants(
+		options.sessionTmp === undefined ? undefined : [options.sessionTmp],
 		tildeHome,
-	)) {
+	);
+	const extraResolved = resolveGrants(options.extraRoots, tildeHome);
+	for (const root of [...sessionTmpResolved, ...extraResolved]) {
 		allow.add(root);
 	}
 	// Kept distinct. Merging them into one read+write list made a folder shared for reading writable,
@@ -474,15 +472,17 @@ export function buildContainmentFence(options: ContainmentOptions): ContainmentF
 	// posture is intentionally not enough: it keeps named access working, while this one exact directory
 	// still cannot be scanned. `--allow-path` appears in both settings lists, so it reaches this branch via
 	// `readOnlyResolved`; a write-only grant does not imply permission to learn directory entries.
-	const parentExplicitlyReadable = [...readOnlyResolved].some(root => pathIsWithin(root, parentToProtect));
+	const parentExplicitlyReadable = [...extraResolved, ...readOnlyResolved].some(root =>
+		pathIsWithin(root, parentToProtect),
+	);
 	if (!tooBroadToDeny(parentToProtect, fsRoot) && !parentExplicitlyReadable) {
 		denyEnumerate.add(parentToProtect);
 	}
 
 	if (home !== undefined) {
 		// The account container is a data root, but this operator's whole home belongs to them (#2637).
-		// A deeper full allow preserves their normal filesystem rights while leaving sibling accounts under
-		// the broader deny. Cross-session stores are denied again at still greater depth below.
+		// A deeper full allow preserves their normal filesystem rights. The account container loses only
+		// enumeration, and cross-session stores are denied again at still greater depth below.
 		allow.add(home);
 
 		// Granted whether or not they exist yet. `~/.bun` has to be writable *before* the first
@@ -493,21 +493,17 @@ export function buildContainmentFence(options: ContainmentOptions): ContainmentF
 		}
 	}
 
-	// Top-level directories that hold somebody's files. Without these the fence covered only home and
-	// the workspace's ancestors, so with the workspace at `~/MEDDPICC/CUSTOMER-A` another operator's
-	// account, an external volume and `/data/globex` were all readable AND writable — measured. The
-	// command-text scan was refusing them on the way in, which is exactly why that scan could not
-	// simply be stood down (#2624).
+	// Top-level directories that hold somebody's files lose only their own directory listing. Named
+	// descendants remain available with the operator's normal filesystem rights: this fence removes
+	// casual discovery, not professional access to a path the operator already knows (#2931).
 	//
 	// Two sources, and the static one is not redundant: enumeration is a single `readdir` that can
 	// fail, and coverage that evaporates with it would be worse than no claim at all. So the known data
-	// roots are denied by name, and enumeration adds whatever this machine has that the list does not
-	// foresee.
+	// roots are protected by name, and enumeration adds whatever this machine has that the list does
+	// not foresee.
 	//
 	// The known roots are resolved through their existing ancestors rather than dropped when absent, so
-	// a `/data` created *after* the session starts is already denied. Seatbelt matches a `(subpath …)`
-	// prefix whether or not the path exists; Landlock cannot attach a rule to an absent inode, but its
-	// plan never grants a path `readdir` did not see either, so nothing is lost there.
+	// a `/data` created *after* the session starts already has its exact listing protected.
 	const known = DATA_ROOTS.map(name => canonicalThroughExisting(path.join(fsRoot, path.basename(name))));
 	const accountRoots = new Set(["Users", "home"].map(name => canonicalThroughExisting(path.join(fsRoot, name))));
 	const found = dataRootEntries(fsRoot).map(entry => canonical(entry) ?? entry);
@@ -525,17 +521,15 @@ export function buildContainmentFence(options: ContainmentOptions): ContainmentF
 		// e.g. /Volumes/Macintosh HD -> /. Skipped for the whole-root list, per the note above.
 		if (!rootScoped.has(resolved) && tooBroadToDeny(resolved, fsRoot)) continue;
 		if (resolved === fsRoot) continue; // never the root the workspace lives on
-		// A directory containing home is normally too broad to deny because it would revoke the operator's
-		// own files (#2637). Account containers are the deliberate exception: they are denied here and the
-		// canonical home allow above wins at greater depth, isolating sibling accounts without hobbling the
-		// operator (#2788).
+		// A directory containing home is normally too broad to protect because it would hide unrelated
+		// operational entries. Account containers are the deliberate exception: their listing is the
+		// discovery surface, while every named account remains reachable (#2788, #2931).
 		if (home !== undefined && pathIsWithin(resolved, home) && !accountRoots.has(resolved)) continue;
-		// A deny beats an allow at EQUAL depth, so denying a root that IS the workspace or IS something
-		// the operator granted would not be redundant — it would silently revoke the grant. Deeper is
-		// fine and intended: an ancestor deny with the workspace allowed inside it is the normal shape.
+		// The session workspace and explicit read/full grants retain enumeration. A write-only grant does
+		// not imply permission to learn directory entries.
 		if (resolved === workspace) continue;
-		if (allow.has(resolved) || allowReadOnly.has(resolved) || allowWriteOnly.has(resolved)) continue;
-		deny.add(resolved);
+		if ([...extraResolved, ...readOnlyResolved].some(root => pathIsWithin(root, resolved))) continue;
+		denyEnumerate.add(resolved);
 	}
 
 	// Cross-session leak roots. These may sit *under* an allowed root — the agent dir is inside home,
@@ -550,8 +544,13 @@ export function buildContainmentFence(options: ContainmentOptions): ContainmentF
 		getXCSHContextsDir(),
 		...sharedTempLeakRoots(),
 	];
+	const explicitGrants = [...extraResolved, ...readOnlyResolved, ...writeOnlyResolved];
 	for (const leak of leaks) {
-		deny.add(canonicalThroughExisting(leak));
+		const resolved = canonicalThroughExisting(leak);
+		// A grant at or above a private root is an explicit operator override. Directional grants stay
+		// directional because their allowReadOnly/allowWriteOnly rule remains the deepest matching rule.
+		if (explicitGrants.some(root => pathIsWithin(root, resolved))) continue;
+		deny.add(resolved);
 	}
 
 	return {
@@ -601,7 +600,7 @@ export type ContainmentBackend = "seatbelt" | "landlock" | "scanner-only" | "dis
 export interface ContainmentStatus {
 	readonly enabled: boolean;
 	readonly backend: ContainmentBackend;
-	/** True when the kernel enforces it, false when only the command-text scan does. */
+	/** True when the kernel enforces it, false when only precise tool-call pre-checks run. */
 	readonly osEnforced: boolean;
 	/**
 	 * Set when the backend enforces reads and writes but cannot govern truncation.
@@ -621,8 +620,8 @@ export interface ContainmentStatus {
  *
  * Reported so an operator can tell a confined session from an unconfined one. The distinction is not
  * cosmetic: with a backend, a path is checked where it is opened and the spelling cannot matter;
- * without one, the only check reads the command text and is best-effort by construction. Two sessions
- * that look identical can offer very different guarantees, and `xcsh://about` is where that is stated.
+ * without one, only explicit tool-call effects can be checked before execution. Two sessions that look
+ * identical can offer very different guarantees, and `xcsh://about` is where that is stated.
  *
  * Deliberately not surfaced at startup or anywhere in the TUI — the operator asked for no UI change.
  */