@f5-sales-demo/xcsh 19.98.10 → 19.100.0

package/package.json

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

package/src/exec/bash-executor.ts

@@ -6,10 +6,27 @@
 import * as fs from "node:fs/promises";
 import { executeShell, Shell } from "@f5-sales-demo/pi-natives";
 import { Settings } from "../config/settings";
+import type { ContainmentFence } from "../sandbox/containment";
 import { OutputSink } from "../session/streaming-output";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
 import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
+/**
+ * The fence as the napi boundary wants it: plain mutable arrays, or absent for unrestricted.
+ *
+ * Shared with the PTY path, which needs the identical conversion. One converter, so the two
+ * execution paths cannot end up disagreeing about what they hand the native layer.
+ */
+export function fenceForNative(fence: ContainmentFence | undefined) {
+	if (!fence) return undefined;
+	return {
+		allow: [...fence.allow],
+		allowReadOnly: [...fence.allowReadOnly],
+		allowWriteOnly: [...fence.allowWriteOnly],
+		deny: [...fence.deny],
+	};
+}
+
 export interface BashExecutorOptions {
 	cwd?: string;
 	timeout?: number;
@@ -24,6 +41,16 @@ export interface BashExecutorOptions {
 	artifactId?: string;
 	/** Mask sensitive values (e.g. env var secrets) in output. */
 	maskSecrets?: (text: string) => string;
+	/**
+	 * Which paths this command may reach, enforced inside the shell rather than guessed from the
+	 * command text (#2554).
+	 *
+	 * Absent means unrestricted, and absent is the default on purpose. Only the model's `bash` tool
+	 * supplies one — `executeBash` is also reached by user-typed `!cmd`, by RPC `bash`, and the same
+	 * brush-core runs credential helpers and the interactive `xcsh shell`. Fencing those would break
+	 * API-key resolution and confine the operator at their own prompt.
+	 */
+	fence?: ContainmentFence;
 }
 
 export interface BashResult {
@@ -186,6 +213,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 						env: commandEnv,
 						timeoutMs: options?.timeout,
 						signal: runAbortController.signal,
+						fence: fenceForNative(options?.fence),
 					},
 					(err, chunk) => {
 						if (!err) {
@@ -202,6 +230,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 						snapshotPath: snapshotPath ?? undefined,
 						timeoutMs: options?.timeout,
 						signal: runAbortController.signal,
+						fence: fenceForNative(options?.fence),
 					},
 					(err, chunk) => {
 						if (!err) {

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

@@ -3,6 +3,8 @@ import * as path from "node:path";
 import { prompt } from "@f5-sales-demo/pi-utils";
 import { $ } from "bun";
 import activeModelTemplate from "../prompts/internal-urls/active-model.md" with { type: "text" };
+import containmentTemplate from "../prompts/internal-urls/containment.md" with { type: "text" };
+import type { ContainmentStatus } from "../sandbox/containment";
 import type { ContextStatus } from "../services/xcsh-context";
 import type { ActiveModelSnapshot } from "../session/active-model";
 import { BUILD_INFO, type BuildInfo } from "./build-info.generated";
@@ -157,10 +159,28 @@ function renderActiveModel(model: ActiveModelSnapshot | null): string {
 	return prompt.render(activeModelTemplate, { model });
 }
 
+/**
+ * What is enforcing the filesystem boundary, and what that does and does not guarantee.
+ *
+ * Stated here because two sessions can look identical and offer very different guarantees: with an OS
+ * backend a path is checked where it is opened and the spelling cannot matter, while without one the
+ * only check reads the command text. An operator has no other way to tell which they have.
+ */
+function renderContainment(containment: ContainmentStatus | null): string {
+	if (!containment) return "";
+	// `landlock` is derived rather than another field on the status, because the template needs a
+	// boolean and Handlebars cannot compare strings. It gates the Linux-only costs — unlistable split
+	// directories, no setuid, no interactive terminal — which are true of that backend and no other.
+	return prompt.render(containmentTemplate, {
+		containment: { ...containment, landlock: containment.backend === "landlock" },
+	});
+}
+
 export function renderAboutDoc(
 	info: RuntimeBuildInfo,
 	context: ContextStatus | null,
 	model: ActiveModelSnapshot | null,
+	containment: ContainmentStatus | null,
 ): string {
 	return [
 		"# xcsh — identity and build fingerprint",
@@ -183,6 +203,7 @@ export function renderAboutDoc(
 		"",
 		renderPlatformContext(context, Date.now()),
 		renderActiveModel(model),
+		renderContainment(containment),
 		"## Source of truth",
 		"",
 		`- Repository: ${info.repoUrl}`,

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.98.10",
-	"commit": "8523f605f109087c188c50d82aa0d20add2e7544",
-	"shortCommit": "8523f60",
+	"version": "19.100.0",
+	"commit": "77f25e303dc3b1fa200117333808b1ed95a6927d",
+	"shortCommit": "77f25e3",
 	"branch": "main",
-	"tag": "v19.98.10",
-	"commitDate": "2026-07-28T14:58:14Z",
-	"buildDate": "2026-07-28T15:23:24.282Z",
+	"tag": "v19.100.0",
+	"commitDate": "2026-07-28T22:16:47Z",
+	"buildDate": "2026-07-28T22:49:07.531Z",
 	"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/8523f605f109087c188c50d82aa0d20add2e7544",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.10"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/77f25e303dc3b1fa200117333808b1ed95a6927d",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.100.0"
 };

package/src/internal-urls/plugin-resolve.ts

@@ -55,12 +55,12 @@ function contentTypeFor(filePath: string): InternalResource["contentType"] {
 /**
  * Extensions a plugin may legitimately declare that are NOT text.
  *
- * Reading one as UTF-8 corrupts it, and nobody wants 91 KB of mangled bytes in a prompt
- * either — the MEDDPICC plugin's `meddpicc-template.xlsx` is exactly that size. What a
- * caller needs is where the file is, so it can be copied, opened, or handed to a tool
- * that understands the format; so a binary resource resolves to its location, not its
- * contents. Deliberately a small allow-list of formats plugins actually ship rather than
- * content sniffing, so the decision is inspectable.
+ * Reading one as UTF-8 corrupts it, and nobody wants tens of kilobytes of mangled bytes in a
+ * prompt either — a spreadsheet or a slide deck runs to that easily. What a caller needs is
+ * where the file is, so it can be copied, opened, or handed to a tool that understands the
+ * format; so a binary resource resolves to its location, not its contents. Deliberately a
+ * small allow-list of formats plugins actually ship rather than content sniffing, so the
+ * decision is inspectable.
  */
 const BINARY_EXTENSIONS = new Set([
 	".xlsx",

package/src/internal-urls/xcsh-protocol.ts

@@ -27,6 +27,7 @@
  */
 import * as path from "node:path";
 import { logger } from "@f5-sales-demo/pi-utils";
+import type { ContainmentStatus } from "../sandbox/containment";
 import type { ContextStatus } from "../services/xcsh-context";
 import type { ActiveModelSnapshot } from "../session/active-model";
 import { type ApiCatalogResolver, createApiCatalogResolver } from "./api-catalog-resolve";
@@ -311,6 +312,12 @@ export interface InternalDocsProtocolOptions {
 	 * reflects a mid-session switch instead of the model the session launched with (#2459).
 	 */
 	readonly getActiveModel?: () => ActiveModelSnapshot | null;
+	/**
+	 * What is enforcing the filesystem boundary. A live getter, like `getActiveModel`, because
+	 * `--no-sandbox` and `sandbox.enabled` can differ per session and the answer must not be captured
+	 * at construction.
+	 */
+	readonly getContainment?: () => ContainmentStatus | null;
 	readonly apiSpecResolver?: ApiSpecResolver;
 	readonly apiCatalogResolver?: ApiCatalogResolver;
 	readonly getPluginRoots?: GetPluginRoots;
@@ -323,6 +330,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	readonly #resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
 	readonly #getContextStatus: (() => ContextStatus | null) | undefined;
 	readonly #getActiveModel: (() => ActiveModelSnapshot | null) | undefined;
+	readonly #getContainment: (() => ContainmentStatus | null) | undefined;
 	#apiSpecResolver: ApiSpecResolver | null;
 	#apiCatalogResolver: ApiCatalogResolver | null;
 	#terraformResolver: TerraformResolver | null;
@@ -338,6 +346,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
 		this.#getContextStatus = options.getContextStatus;
 		this.#getActiveModel = options.getActiveModel;
+		this.#getContainment = options.getContainment;
 		this.#apiSpecResolver = options.apiSpecResolver ?? null;
 		this.#apiCatalogResolver = options.apiCatalogResolver ?? null;
 		this.#terraformResolver = null;
@@ -814,7 +823,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			const info = await this.#resolveBuildInfo();
 			const context = this.#getContextStatus?.() ?? null;
 			const activeModel = this.#getActiveModel?.() ?? null;
-			const content = renderAboutDoc(info, context, activeModel);
+			const containment = this.#getContainment?.() ?? null;
+			const content = renderAboutDoc(info, context, activeModel, containment);
 			return {
 				url: url.href,
 				content,

package/src/prompts/internal-urls/containment.md

@@ -0,0 +1,50 @@
+## Sandbox containment
+
+{{#if containment.enabled}}
+Filesystem isolation is **on**. Enforcement for the `bash` tool: **{{containment.backend}}**.
+
+{{#if containment.osEnforced}}
+Your shell is confined by the operating system, not by inspecting the command you wrote. A path is
+checked where it is actually opened, after the shell has expanded variables, resolved aliases and
+followed symlinks — so how a path is spelled does not change what is reachable.
+- Ordinary work is unrestricted: system paths, `/tmp`, package caches (`~/.bun`, `~/.cargo`, …), the
+  network, and running programs are all untouched.
+- What is refused: reading or writing outside the session directory — another checkout, `~/.ssh`,
+  `~/.aws`, `~/Documents`, and other sessions' transcripts. `~/.gitconfig` is readable, not writable.
+- `cd` out of the session tree is refused, because every later relative path would resolve there.
+
+If a command is refused, do not try to reach the same path a different way: the boundary is enforced
+below the command text, so no rewriting will succeed. Say what you needed and why. The operator can
+widen it with `--allow-path <dir>`, which grants read and write.
+
+{{#if containment.landlock}}
+Three things behave differently under this backend, and none of them is a bug to work around:
+- `ls /` and `ls` of the directory holding the session tree fail. A kernel rule covers a whole subtree,
+  so a directory with both reachable and unreachable children cannot be listed at all. Listing a
+  specific directory you can reach works normally.
+- `sudo` and other setuid programs do not work, because confining a process requires giving up the
+  ability to gain privileges.
+- Interactive terminal programs (`top`, `less`, an interactive `ssh`) run without a real terminal here,
+  so prefer their non-interactive forms — `ps`, `cat`, `ssh -T`, or a piped command.
+{{#if containment.truncationUngoverned}}
+- This kernel is too old to govern truncation, so a file outside the boundary can still be emptied even
+  though it cannot be read or written. Never truncate a path outside the session directory.
+{{/if}}
+{{/if}}
+{{else}}
+On this platform there is **no OS-level backend**, so the boundary is enforced only by scanning the
+command text before it runs. That check is best-effort by construction: it reads what you wrote
+rather than what the shell will do, so a path assembled at runtime or reached through an unusual
+spelling may not be caught.
+
+Treat the boundary as a statement of intent rather than a guarantee here, and do not go looking for
+paths outside the session directory on the assumption that something would stop you.
+{{/if}}
+{{else}}
+Filesystem isolation is **off** for this session — started with `--no-sandbox`, or
+`sandbox.enabled` is false. Every path on this machine is reachable.
+
+Nothing is confining you, so the judgement is yours: stay within the directory the operator is
+working in unless they asked for something else, and do not read private files elsewhere on the
+machine because you happen to be able to.
+{{/if}}

package/src/sandbox/containment.ts

@@ -0,0 +1,323 @@
+/**
+ * The containment fence: what the shell may reach, enforced below the command text.
+ *
+ * This is deliberately NOT `SandboxPolicy`. That object is deny-by-default — "a path matched by no
+ * rule is denied" — which is the right posture for the structured file tools and the wrong one here.
+ * Confining a shell that way refuses ordinary work: measured on macOS 26.3, a deny-default seatbelt
+ * profile could not even `execvp /bin/cat`.
+ *
+ * So the fence is gentle. It restricts no operation — `/usr`, `/tmp`, package caches, the network and
+ * process execution are never mentioned, and nothing that works today stops working. The single thing
+ * it prevents is the assistant wandering the filesystem: reading or writing another customer's
+ * checkout, `~/.ssh`, `~/Documents`. That is where the cross-customer risk actually lives (#2554).
+ *
+ * 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
+ * and cannot deny a subpath of something granted. Both can compile `{allow, allowReadOnly, deny}` with
+ * deny-wins, so neither has to reason about ordering.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as natives from "@f5-sales-demo/pi-natives";
+import { getMemoriesDir, getSessionsDir, getXCSHContextsDir, pathIsWithin } from "@f5-sales-demo/pi-utils";
+
+export type FenceAccess = "read" | "write";
+export type FenceVerdict = "allow" | "deny";
+
+export interface ContainmentFence {
+	/** Canonical roots the shell may read and write. */
+	readonly allow: readonly string[];
+	/** Canonical roots the shell may read but not write. */
+	readonly allowReadOnly: readonly string[];
+	/** Canonical roots the shell may write but not read. */
+	readonly allowWriteOnly: readonly string[];
+	/** Canonical roots denied in both directions, winning over any allow they sit inside. */
+	readonly deny: readonly string[];
+}
+
+export interface ContainmentOptions {
+	/** The session's working directory. Must exist — it is the one root that cannot be dropped. */
+	workspace: string;
+	/** Overridable for tests; defaults to the real home directory. */
+	home?: string;
+	/** A session-specific temp dir, if the session has one. */
+	sessionTmp?: string;
+	/** Roots granted read+write, as `--allow-path` does. */
+	extraRoots?: readonly string[];
+	/** Roots granted read only — `sandbox.allowRead`. Must NOT become writable. */
+	readOnlyRoots?: readonly string[];
+	/** Roots granted write only — `sandbox.allowWrite`. */
+	writeOnlyRoots?: readonly string[];
+	/** Cross-session leak roots to deny. Defaults to the real memories/sessions/contexts dirs. */
+	leakRoots?: readonly string[];
+}
+
+/**
+ * Directories inside home that hold tool state rather than the operator's data. Denying home without
+ * carving these back out is what would break `bun install`, `cargo build` and `npm ci` — the exact
+ * class of breakage this fence must not cause.
+ *
+ * `~/Library/Caches` is macOS-wide tool cache; it is not customer data and several toolchains use it.
+ */
+const CACHE_DIRS = [
+	// Artifact subdirectories only. Granting the parents put credentials inside the fence —
+	// `.cargo/credentials.toml`, `.m2/settings.xml`, `.npm/_authToken` — and `.cargo/config.toml`
+	// and `.gradle/init.gradle` are worse than credentials: both can redirect a later build, so a
+	// write there is persistence rather than theft. Found by adversarial review, verified writable.
+	path.join(".bun", "install", "cache"),
+	path.join(".cargo", "registry"),
+	path.join(".cargo", "git"),
+	path.join(".npm", "_cacache"),
+	path.join(".m2", "repository"),
+	path.join(".gradle", "caches"),
+	path.join(".gradle", "wrapper"),
+	path.join(".yarn", "berry", "cache"),
+	path.join(".rustup", "toolchains"),
+	path.join(".rustup", "downloads"),
+	// No credential convention of their own, so granted whole.
+	".pnpm-store",
+	".deno",
+	path.join("Library", "Caches"),
+	path.join("Library", "pnpm"),
+];
+
+/** Read-only inside home: configuration a tool needs to behave correctly, but must not rewrite. */
+const READ_ONLY_HOME = [".gitconfig", path.join(".config", "git")];
+
+/**
+ * Canonicalise a root, or return undefined when it is absent.
+ *
+ * Canonicalisation is load-bearing rather than tidiness: a seatbelt `(subpath "/tmp/x")` rule grants
+ * nothing, because the real path is `/private/tmp/x`. A rule that appears to enforce and does not is
+ * the worst outcome available, so a root that cannot be resolved is dropped rather than emitted.
+ */
+function canonical(root: string): string | undefined {
+	try {
+		return fs.realpathSync(root);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Parents that must never be denied, however the workspace is placed.
+ *
+ * Denying the workspace's parent closes sibling access, but the parent is not always a sibling
+ * container. A workspace directly under `/`, under a system directory, or under the OS temp dir would
+ * otherwise deny `/`, `/usr` or `/tmp` — refusing exactly the work this fence is supposed to leave
+ * alone. The home tree is excluded too because the home deny already covers it, at the right depth.
+ */
+function tooBroadToDeny(candidate: string): boolean {
+	if (candidate === path.parse(candidate).root) return true;
+	const never = [
+		safeReal(os.tmpdir()),
+		"/usr",
+		"/bin",
+		"/sbin",
+		"/lib",
+		"/opt",
+		"/etc",
+		"/dev",
+		"/proc",
+		"/sys",
+		"/var",
+		"/private",
+		"/System",
+		"/Library",
+		"/Users",
+		"/home",
+	];
+	return never.includes(candidate);
+}
+
+/** realpath without throwing, for building the never-deny list. */
+function safeReal(input: string): string {
+	try {
+		return fs.realpathSync(input);
+	} catch {
+		return input;
+	}
+}
+
+/** The deepest root containing `candidate`, so a nested rule beats the broader one it sits inside. */
+function deepestMatch(roots: readonly string[], candidate: string): string | undefined {
+	let best: string | undefined;
+	for (const root of roots) {
+		if (!pathIsWithin(root, candidate)) continue;
+		if (best === undefined || root.length > best.length) best = root;
+	}
+	return best;
+}
+
+/** Build the fence for a session. Throws only when the workspace itself cannot be resolved. */
+export function buildContainmentFence(options: ContainmentOptions): ContainmentFence {
+	const workspace = canonical(options.workspace);
+	if (workspace === undefined) {
+		throw new Error(
+			`sandbox containment: cannot canonicalise the session workspace ${options.workspace}. ` +
+				"A fence built on an unresolved path would silently grant nothing, so refusing to build one.",
+		);
+	}
+
+	const home = canonical(options.home ?? os.homedir());
+	const allow = new Set<string>([workspace]);
+	const allowReadOnly = new Set<string>();
+	const allowWriteOnly = new Set<string>();
+	const deny = new Set<string>();
+
+	// Home is one fence. The workspace's own parent is the other, and it is the one that matters when
+	// checkouts live outside home: with /work/customer-a as the workspace, /work/customer-b matched no
+	// rule at all and was readable and writable. Denying the parent closes sibling access wherever the
+	// checkouts sit, which is the threat this exists for.
+	if (home !== undefined && home !== workspace) deny.add(home);
+	const parent = path.dirname(workspace);
+	if (parent !== workspace && !tooBroadToDeny(parent)) deny.add(parent);
+
+	for (const root of [options.sessionTmp, ...(options.extraRoots ?? [])]) {
+		if (root === undefined) continue;
+		const resolved = canonical(root);
+		if (resolved !== undefined) allow.add(resolved);
+	}
+	// Kept distinct. Merging them into one read+write list made a folder shared for reading writable,
+	// undoing the read/write split built for #2516 — found by adversarial review.
+	for (const root of options.readOnlyRoots ?? []) {
+		const resolved = canonical(root);
+		if (resolved !== undefined) allowReadOnly.add(resolved);
+	}
+	for (const root of options.writeOnlyRoots ?? []) {
+		const resolved = canonical(root);
+		if (resolved !== undefined) allowWriteOnly.add(resolved);
+	}
+
+	if (home !== undefined) {
+		// Granted whether or not they exist yet. `~/.bun` has to be writable *before* the first
+		// `bun install` creates it, so dropping absent caches would break exactly the first run.
+		// Canonicalised when present, so a symlinked cache resolves to its real location.
+		for (const cache of CACHE_DIRS) allow.add(canonical(path.join(home, cache)) ?? path.join(home, cache));
+		for (const config of READ_ONLY_HOME) {
+			allowReadOnly.add(canonical(path.join(home, config)) ?? path.join(home, config));
+		}
+	}
+
+	// Cross-session leak roots. These may sit *under* an allowed root — the agent dir is inside home,
+	// and a session whose workspace is the agent dir would otherwise re-expose every other session's
+	// transcript. `fenceVerdict` resolves that by depth, so nesting is safe rather than accidental.
+	const leaks = options.leakRoots ?? [getMemoriesDir(), getSessionsDir(), getXCSHContextsDir()];
+	for (const leak of leaks) {
+		const resolved = canonical(leak);
+		if (resolved !== undefined) deny.add(resolved);
+	}
+
+	return {
+		allow: [...allow],
+		allowReadOnly: [...allowReadOnly],
+		allowWriteOnly: [...allowWriteOnly],
+		deny: [...deny],
+	};
+}
+
+/**
+ * Whether the fence permits `access` on `candidate`.
+ *
+ * Deepest match wins, and a deny beats an allow at equal depth — the same precedence `SandboxPolicy`
+ * uses, so the two layers cannot disagree about a path they both see. Unlike that policy, the default
+ * here is **allow**: a path matched by no rule is outside the fence and none of its business.
+ */
+export function fenceVerdict(fence: ContainmentFence, candidate: string, access: FenceAccess): FenceVerdict {
+	const denied = deepestMatch(fence.deny, candidate);
+	const readOnly = deepestMatch(fence.allowReadOnly, candidate);
+	const writeOnly = deepestMatch(fence.allowWriteOnly, candidate);
+	const allowed = deepestMatch(fence.allow, candidate);
+
+	const depth = (root: string | undefined): number => (root === undefined ? -1 : root.length);
+	const deepest = Math.max(depth(denied), depth(readOnly), depth(writeOnly), depth(allowed));
+
+	// Deny first at equal depth: the leak roots depend on it.
+	if (denied !== undefined && depth(denied) === deepest) return "deny";
+	if (readOnly !== undefined && depth(readOnly) === deepest) return access === "read" ? "allow" : "deny";
+	if (writeOnly !== undefined && depth(writeOnly) === deepest) return access === "write" ? "allow" : "deny";
+	if (allowed !== undefined && depth(allowed) === deepest) return "allow";
+	return "allow";
+}
+
+/** Which mechanism is actually enforcing the boundary for the `bash` tool. */
+export type ContainmentBackend = "seatbelt" | "landlock" | "scanner-only" | "disabled";
+
+export interface ContainmentStatus {
+	readonly enabled: boolean;
+	readonly backend: ContainmentBackend;
+	/** True when the kernel enforces it, false when only the command-text scan does. */
+	readonly osEnforced: boolean;
+	/**
+	 * Set when the backend enforces reads and writes but cannot govern truncation.
+	 *
+	 * True only on Landlock ABI 2 — kernels 5.19 to 6.1, which includes Debian 12 — where
+	 * `LANDLOCK_ACCESS_FS_TRUNCATE` does not exist. A denied file cannot be read or written there, but
+	 * `truncate(2)` can still zero it. That is destruction rather than disclosure, and it is not
+	 * reachable through `>` (which needs write access at open), so the backend is still worth having.
+	 * Reported rather than folded into `osEnforced`, because "enforced" and "enforced except this" are
+	 * different claims and an operator is entitled to know which one they have.
+	 */
+	readonly truncationUngoverned?: boolean;
+}
+
+/**
+ * What is actually enforcing the boundary right now.
+ *
+ * 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.
+ *
+ * Deliberately not surfaced at startup or anywhere in the TUI — the operator asked for no UI change.
+ */
+export function containmentStatus(
+	enabled: boolean,
+	platform: string = process.platform,
+	probe: () => { backend: string; truncateHandled?: boolean } | undefined = probeNativeBackend,
+): ContainmentStatus {
+	if (!enabled) return { enabled: false, backend: "disabled", osEnforced: false };
+	// macOS always has seatbelt, so there is nothing to ask.
+	if (platform === "darwin") return { enabled: true, backend: "seatbelt", osEnforced: true };
+	// Everywhere else the answer cannot be inferred from the platform name. Landlock can be compiled
+	// out of the kernel, left out of its boot-time LSM list, or too old to allow cross-directory
+	// rename — and none of that is visible from `process.platform`. Asking the native layer is the
+	// difference between reporting what is enforcing and reporting what we hope is enforcing.
+	// Guarded here rather than inside the probe, so *any* probe is safe to pass — including an injected
+	// one. A native module from an older release has no such export, and letting a `TypeError` escape
+	// would turn a missing status line into a broken `xcsh://about`. Falling back to `scanner-only`
+	// understates the boundary, which is the safe direction to be wrong in.
+	let probed: { backend: string; truncateHandled?: boolean } | undefined;
+	try {
+		probed = probe();
+	} catch {
+		probed = undefined;
+	}
+	if (probed?.backend === "landlock") {
+		return {
+			enabled: true,
+			backend: "landlock",
+			osEnforced: true,
+			// Absent on the ABI that governs truncation; present, and stated, on the one that does not.
+			...(probed.truncateHandled === false ? { truncationUngoverned: true } : {}),
+		};
+	}
+	return { enabled: true, backend: "scanner-only", osEnforced: false };
+}
+
+/**
+ * Ask the native layer which backend is active, if it can answer.
+ *
+ * **Reached through a namespace import on purpose.** A native module built before this export existed
+ * does not have the symbol, and a static `import { containmentBackend }` against it fails at *link*
+ * time with `SyntaxError: Export named 'containmentBackend' not found` — taking the whole module graph
+ * down before any `try`/`catch` can run. Found exactly that way: the tarball install smoke test died on
+ * it while the runtime guard sat there looking sufficient. A namespace member that is absent is merely
+ * `undefined`, which is a case code can actually handle.
+ */
+function probeNativeBackend(): { backend: string; truncateHandled?: boolean } | undefined {
+	const probe = (natives as { containmentBackend?: () => { backend: string; truncateHandled?: boolean } })
+		.containmentBackend;
+	return typeof probe === "function" ? probe() : undefined;
+}

package/src/sandbox/enforce.ts

@@ -14,8 +14,22 @@
  * Arbitrary-code tools (`bash`, `python`) cannot be fully contained in-process: this
  * checks the `cwd` argument precisely and scans the command/code for path tokens
  * (bare, quoted, `~`, `..`, absolute) that escape the tree. OS system paths are exempt.
- * This is best-effort; the opt-in OS-level sandbox (Phase 2) is the airtight enforcement
- * for both bash and python.
+ *
+ * **This scan is no longer the boundary for `bash` on macOS.** Containment now runs below the command
+ * text (`sandbox/containment.ts`, #2554): the shell's own `cd` and redirections are checked where they
+ * act, and spawned children are confined by a seatbelt profile. A path is therefore decided after
+ * expansion, alias resolution and symlink following, which is what closed the escapes this scan kept
+ * leaking — #2470, #2516, #2520, #2524, #2540, #2542, #2553, and GHSA-q4hg.
+ *
+ * What remains this file's job:
+ *  - every structured file tool (`read`/`write`/`edit`/`grep`/…), which has no subprocess to confine
+ *  - `python`, which is not covered by the shell fence at all
+ *  - `bash` on platforms with no backend — Linux Landlock is a follow-up, Windows has no equivalent —
+ *    where this is again the only layer, and `xcsh://about` says so
+ *  - a fast pre-check that produces a readable refusal before a command runs
+ *
+ * So: keep it, and do not extend it. Another spelling caught here buys little now, and the pattern of
+ * adding one has a poor record — two adversarial rounds on the #2542 fix alone produced six bypasses.
  */
 import * as path from "node:path";
 import { expandPath, parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";

package/src/sdk.ts

@@ -96,6 +96,8 @@ import {
 } from "./mcp/discoverable-tool-metadata";
 import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
+import { containmentStatus } from "./sandbox/containment";
+import { resolveSessionPolicy } from "./sandbox/session-policy";
 import {
 	collectEnvSecrets,
 	deobfuscateSessionContext,
@@ -1154,6 +1156,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						return null;
 					}
 				},
+				// Read live rather than captured, for the same reason as the model: `--no-sandbox` and
+				// `sandbox.enabled` are per-session, so the answer must reflect this session (#2554).
+				getContainment: () => containmentStatus(resolveSessionPolicy(process.cwd(), settings) !== undefined),
 				// Read live rather than captured: `session.model` is a read-through to agent state, so a
 				// mid-session Ctrl+P switch shows up on the next xcsh://about read (#2459).
 				getActiveModel: () =>

package/src/tools/bash-interactive.ts

@@ -12,8 +12,10 @@ import {
 } from "@f5-sales-demo/pi-tui";
 import type { Terminal as XtermTerminalType } from "@xterm/headless";
 import xterm from "@xterm/headless";
+import { fenceForNative } from "../exec/bash-executor";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import type { Theme } from "../modes/theme/theme";
+import type { ContainmentFence } from "../sandbox/containment";
 import { OutputSink, type OutputSummary } from "../session/streaming-output";
 import { sanitizeWithImagePassthrough } from "../utils/image-passthrough";
 import { formatStatusIcon, replaceTabs } from "./render-utils";
@@ -293,6 +295,17 @@ export async function runInteractiveBashPty(
 		artifactPath?: string;
 		artifactId?: string;
 		maskSecrets?: (text: string) => string;
+		/**
+		 * Filesystem boundary for this command. `undefined` means unrestricted, and must be said
+		 * rather than omitted.
+		 *
+		 * Deliberately a required key with an optional value. This path is reached only from the
+		 * model's `bash` tool, and it was unfenced precisely because the field was easy to leave out
+		 * of one of two call sites — the boundary ended up opt-out via a parameter the model itself
+		 * supplies. Requiring the key makes that omission a type error instead of a silent hole; a
+		 * future caller that genuinely wants no fence has to write `fence: undefined` and mean it.
+		 */
+		fence: ContainmentFence | undefined;
 	},
 ): Promise<BashInteractiveResult> {
 	const sink = new OutputSink({
@@ -360,6 +373,7 @@ export async function runInteractiveBashPty(
 						signal: options.signal,
 						cols,
 						rows,
+						fence: fenceForNative(options.fence),
 					},
 					(err, chunk) => {
 						if (finished || err || !chunk) return;

package/src/tools/bash.ts

@@ -16,6 +16,7 @@ import { resolveLocalRoot } from "../internal-urls/local-protocol";
 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 { buildContainmentFence, containmentStatus } from "../sandbox/containment";
 import { resolveSessionPolicy } from "../sandbox/session-policy";
 import { SECRET_ENV_PATTERNS, type SecretObfuscator } from "../secrets";
 import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
@@ -37,6 +38,14 @@ import { clampTimeout } from "./tool-timeouts";
 // Module-level obfuscator reference for the renderer (set by BashTool constructor).
 let _sessionObfuscator: SecretObfuscator | undefined;
 
+/**
+ * Where each session's containment boundary is anchored, captured once and never moved by the model.
+ *
+ * Keyed on the session object because the tool is built by a factory, so an instance field would reset
+ * whenever a new `BashTool` is made. Weak so a finished session is collectable.
+ */
+const FENCE_ANCHORS = new WeakMap<object, { root: string; project: string }>();
+
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
 
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -392,6 +401,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 						artifactPath,
 						artifactId,
 						maskSecrets: options.maskSecrets,
+						fence: this.#containmentFence(),
 						onChunk: chunk => {
 							tailBuffer.append(chunk);
 							const preview = options.maskSecrets ? options.maskSecrets(tailBuffer.text()) : tailBuffer.text();
@@ -475,6 +485,67 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return Math.max(0, Math.min(this.#autoBackgroundThresholdMs, timeoutMs - timeoutBufferMs));
 	}
 
+	/**
+	 * Where this session's boundary is anchored.
+	 *
+	 * **Not the live cwd.** The fence used to be rebuilt from `session.cwd`, which line ~717 replaces
+	 * with whatever PWD the command ended in — so the model could move the boundary with a `cd`. Measured
+	 * on a workspace outside the home tree, which is the layout the sibling-checkout deny exists for:
+	 * with `/work/custA` as the workspace, `/work/custB/secret.env` was denied; `cd /usr` is permitted
+	 * (correctly — `/usr` is not sensitive), and the *next* fence was rooted at `/usr`, where the parent
+	 * deny of `/work` cannot be expressed because `dirname("/usr")` is `/` and denying the root is refused
+	 * as too broad. `/work/custB` then became readable **and** writable. Two tool calls, no exotic
+	 * spelling, and the tenant boundary was gone.
+	 *
+	 * So the anchor is captured once per session and never follows the shell. It is keyed on the session
+	 * object rather than held on this instance because the tool is built by a factory
+	 * (`bash: s => new BashTool(s)`) and must not depend on how long an instance happens to live.
+	 *
+	 * An *operator* moving the project — startup, or the slash command that calls `setProjectDir` — does
+	 * re-anchor it. That asymmetry is the point: the operator may move the boundary, the model may not.
+	 *
+	 * Note the read/write tools are unaffected by this class of bug: `SandboxPolicy` is deny-by-default,
+	 * so relocating its root grants nothing new. Only an allow-by-default fence loses a deny when it
+	 * moves, which is why this needed fixing here and not there.
+	 */
+	#containmentRoot(): string {
+		const project = getProjectDir();
+		const anchor = FENCE_ANCHORS.get(this.session);
+		if (anchor === undefined) {
+			FENCE_ANCHORS.set(this.session, { root: this.session.cwd, project });
+			return this.session.cwd;
+		}
+		if (anchor.project !== project) {
+			// The operator moved the project. Re-anchor there rather than at `session.cwd`, which a
+			// model `cd` may have moved in the meantime.
+			FENCE_ANCHORS.set(this.session, { root: project, project });
+			return project;
+		}
+		return anchor.root;
+	}
+
+	/**
+	 * The fence for this invocation, or undefined when isolation is off.
+	 *
+	 * Built here rather than in the executor because `executeBash` is shared: user-typed `!cmd` and
+	 * 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() {
+		const root = this.#containmentRoot();
+		const policy = resolveSessionPolicy(root, this.session.settings);
+		if (!policy) return undefined; // --no-sandbox / sandbox.enabled = false
+		const artifactsDir = this.session.getArtifactsDir?.();
+		// The three grants stay distinct. Merging allowRead and allowWrite into one read+write list
+		// made a folder shared for reading writable, undoing the split built for #2516.
+		return buildContainmentFence({
+			workspace: root,
+			extraRoots: artifactsDir ? [artifactsDir] : [],
+			readOnlyRoots: (this.session.settings.get("sandbox.allowRead") as string[] | undefined) ?? [],
+			writeOnlyRoots: (this.session.settings.get("sandbox.allowWrite") as string[] | undefined) ?? [],
+		});
+	}
+
 	async execute(
 		_toolCallId: string,
 		{
@@ -633,7 +704,23 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		// Allocate artifact for truncated output storage
 		const { path: artifactPath, id: artifactId } = (await this.session.allocateOutputArtifact?.("bash")) ?? {};
 
-		const usePty = pty && $env.PI_NO_PTY !== "1" && ctx?.hasUI === true && ctx.ui !== undefined;
+		// The PTY path can only be confined where the OS backend reaches it, and on Linux it does not:
+		// Landlock is applied in a `pre_exec` hook, and `portable-pty`'s `CommandBuilder` exposes none
+		// (its `as_command` is private, and its `Clone + Debug + PartialEq` derives preclude a closure
+		// field ever being added). Since `pty` is a parameter the *model* supplies, leaving it reachable
+		// would make containment opt-out by the very caller it constrains — the hole that was just closed
+		// on macOS. So a fenced session falls back to the non-PTY path, which is confined.
+		//
+		// The cost is real and Linux-only: `top`, `less` and `ssh` run without a terminal in a fenced
+		// session. Confining the PTY child properly is the follow-up; reporting a boundary that a flag
+		// steps around would be worse than losing interactivity.
+		// Only worth giving up when there is an OS backend for the non-PTY path to use and none for this
+		// one. Where no backend exists — Linux without Landlock, Windows — both paths are scanner-only,
+		// so disabling PTY would remove interactive terminals and improve containment by nothing.
+		const fence = this.#containmentFence();
+		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,
@@ -644,6 +731,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					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,
@@ -654,6 +744,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					maskSecrets,
+					fence,
 					onChunk: chunk => {
 						tailBuffer.append(chunk);
 						if (onUpdate) {