@f5-sales-demo/xcsh 19.99.0 → 19.100.1

package/package.json

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

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

@@ -168,7 +168,12 @@ function renderActiveModel(model: ActiveModelSnapshot | null): string {
  */
 function renderContainment(containment: ContainmentStatus | null): string {
 	if (!containment) return "";
-	return prompt.render(containmentTemplate, { containment });
+	// `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(
@@ -217,6 +222,16 @@ export function renderAboutDoc(
 		"at /_llms-txt/{topic}.txt, per-page content at /{slug}.md, plus",
 		"llms-small.txt (compact) and llms-full.txt (complete).",
 		"",
+		"Every one of those exists per language as well: {locale}/llms.txt,",
+		"{locale}/llms-small.txt, {locale}/llms-full.txt, the tiered sets at",
+		"/_llms-txt/{locale}/{topic}.txt, and per-page content at /{locale}/{slug}.md.",
+		"The root llms.txt lists the languages under `## Translations`. When the user",
+		"is working in a language, read that language's set rather than translating the",
+		"default locale's — it is already written in their language. Locale segments",
+		"are slugs, not BCP-47 tags (pt-br, zh-cn, zh-tw). The default locale's",
+		"complete and abridged documents stay at the repo root, so its",
+		"{locale}/llms-full.txt is intentionally absent.",
+		"",
 		"## Lineage",
 		"",
 		"xcsh is a fork of [badlogic/pi-mono](https://github.com/badlogic/pi-mono).",

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.99.0",
-	"commit": "8020e6b8aa7ae0c4fd4ac6da9ee9fa81b77182f0",
-	"shortCommit": "8020e6b",
+	"version": "19.100.1",
+	"commit": "ab1af6daf7fdebc0fd0a193bdae578f0e9395eab",
+	"shortCommit": "ab1af6d",
 	"branch": "main",
-	"tag": "v19.99.0",
-	"commitDate": "2026-07-28T17:45:44Z",
-	"buildDate": "2026-07-28T18:11:25.457Z",
+	"tag": "v19.100.1",
+	"commitDate": "2026-07-29T00:48:34Z",
+	"buildDate": "2026-07-29T01:14:16.102Z",
 	"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/8020e6b8aa7ae0c4fd4ac6da9ee9fa81b77182f0",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.99.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/ab1af6daf7fdebc0fd0a193bdae578f0e9395eab",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.100.1"
 };

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

@@ -16,6 +16,21 @@ followed symlinks — so how a path is spelled does not change what is reachable
 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

package/src/sandbox/containment.ts

@@ -19,6 +19,7 @@
 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";
@@ -248,6 +249,17 @@ export interface ContainmentStatus {
 	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;
 }
 
 /**
@@ -260,10 +272,52 @@ export interface ContainmentStatus {
  *
  * 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): ContainmentStatus {
+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 };
-	// Only the macOS seatbelt backend exists today. Linux Landlock is a follow-up; until it lands,
-	// Linux and Windows fall back to the scanner and say so rather than implying enforcement.
+	// 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/tools/bash.ts

@@ -16,7 +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 } from "../sandbox/containment";
+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";
@@ -38,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_]*$/;
@@ -477,25 +485,61 @@ 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).
-	 *
-	 * Uses the session's *live* cwd so an in-tree `cd` keeps working, while the fence's own roots
-	 * decide what is reachable — which is what stops a `cd` out of the tree from taking the boundary
-	 * with it, without the text layer having to recognise every spelling of `cd`.
 	 */
 	#containmentFence() {
-		const policy = resolveSessionPolicy(this.session.cwd, this.session.settings);
+		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: this.session.cwd,
+			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) ?? [],
@@ -660,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,
@@ -671,7 +731,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					maskSecrets,
-					fence: this.#containmentFence(),
+					// 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,
@@ -682,7 +744,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					maskSecrets,
-					fence: this.#containmentFence(),
+					fence,
 					onChunk: chunk => {
 						tailBuffer.append(chunk);
 						if (onUpdate) {

package/src/tools/fetch.ts

@@ -15,6 +15,7 @@ import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { ensureTool } from "../utils/tools-manager";
+import { buildLlmEndpointCandidates } from "../web/llms-endpoints";
 import { extractWithParallel, findParallelApiKey, getParallelExtractContent } from "../web/parallel";
 import { specialHandlers } from "../web/scrapers";
 import type { RenderResult } from "../web/scrapers/types";
@@ -97,32 +98,6 @@ function hasCommand(cmd: string): boolean {
 	return Boolean($which(cmd));
 }
 
-/**
- * Build llms.txt candidates scoped to the requested URL
- */
-function buildLlmEndpointCandidates(url: string): string[] {
-	try {
-		const parsed = new URL(url);
-		if (parsed.pathname === "/") {
-			return [`${parsed.origin}/.well-known/llms.txt`, `${parsed.origin}/llms.txt`, `${parsed.origin}/llms.md`];
-		}
-
-		const trimmedPath = parsed.pathname.replace(/\/+$/, "");
-		const segments = trimmedPath.split("/").filter(Boolean);
-		const scopeDepth = parsed.pathname.endsWith("/") ? segments.length : Math.max(segments.length - 1, 1);
-		const endpoints: string[] = [];
-
-		for (let depth = scopeDepth; depth >= 1; depth--) {
-			const scope = `/${segments.slice(0, depth).join("/")}/`;
-			endpoints.push(`${parsed.origin}${scope}llms.txt`, `${parsed.origin}${scope}llms.md`);
-		}
-
-		return endpoints;
-	} catch {
-		return [];
-	}
-}
-
 /**
  * Normalize URL (add scheme if missing)
  */

package/src/web/llms-endpoints.ts

@@ -0,0 +1,41 @@
+/**
+ * llms.txt endpoint discovery.
+ *
+ * Kept free of native and network imports so the scope walk can be unit tested
+ * on its own: it is the only thing that decides whether a request for a
+ * translated page reaches that language's llms.txt index or silently falls back
+ * to the default locale's.
+ */
+
+/**
+ * Build llms.txt candidates scoped to the requested URL, deepest scope first.
+ *
+ * The federated product docs publish an index per language at
+ * `<locale>/llms.txt` alongside the one at the repo root, so walking outwards
+ * from the deepest path scope is what lets a request for `/mcn/ja/demo/` find
+ * the Japanese index before falling back to `/mcn/llms.txt`. Reversing the walk,
+ * or capping it at the repository segment, would send every non-default-locale
+ * request back to default-locale context.
+ */
+export function buildLlmEndpointCandidates(url: string): string[] {
+	try {
+		const parsed = new URL(url);
+		if (parsed.pathname === "/") {
+			return [`${parsed.origin}/.well-known/llms.txt`, `${parsed.origin}/llms.txt`, `${parsed.origin}/llms.md`];
+		}
+
+		const trimmedPath = parsed.pathname.replace(/\/+$/, "");
+		const segments = trimmedPath.split("/").filter(Boolean);
+		const scopeDepth = parsed.pathname.endsWith("/") ? segments.length : Math.max(segments.length - 1, 1);
+		const endpoints: string[] = [];
+
+		for (let depth = scopeDepth; depth >= 1; depth--) {
+			const scope = `/${segments.slice(0, depth).join("/")}/`;
+			endpoints.push(`${parsed.origin}${scope}llms.txt`, `${parsed.origin}${scope}llms.md`);
+		}
+
+		return endpoints;
+	} catch {
+		return [];
+	}
+}