@f5-sales-demo/xcsh 19.98.1 → 19.98.3

package/package.json

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

package/src/commands/manager-core.ts

@@ -104,13 +104,6 @@ export function needsProvision(reg: Registry, sessionId: string): boolean {
 	return !reg.has(sessionId);
 }
 
-/** Lowest free port in the range not already held by a worker. */
-export function pickPort(reg: Registry, range: number[]): number | null {
-	const used = new Set([...reg.values()].map(w => w.port));
-	for (const p of range) if (!used.has(p)) return p;
-	return null;
-}
-
 /** sessionIds whose worker has been idle longer than idleMs. */
 export function staleKeys(reg: Registry, now: number, idleMs: number): string[] {
 	const out: string[] = [];
@@ -170,3 +163,35 @@ export function sparesToSpawn(
 	const freeSlots = Math.max(0, totalPorts - activeWorkers - currentSpares);
 	return Math.min(want, freeSlots);
 }
+
+/**
+ * Choose a port to spawn on, probing ONLY ports that are not already spoken for.
+ *
+ * `isFree` is not a read — every implementation of it binds the port to find out,
+ * then releases it. Probing a port that has already been handed to a worker which
+ * is still starting up can therefore win that bind, and a worker whose forced
+ * `XCSH_BRIDGE_PORT` is occupied throws and exits rather than retrying
+ * ("XCSH_BRIDGE_PORT N is already in use", extension-bridge.ts). `proc.exited`
+ * then drops its registry entry, so the session ends up with no worker at all.
+ *
+ * That is the two-tab flake (#2463): provisioning a second tab swept the whole
+ * range, including the first tab's port, and could kill the first tab's worker
+ * mid-bind — leaving exactly one port advertising the tenant.
+ *
+ * `reserved` covers ports promised but not yet in the registry (pre-warmed spares
+ * live there until adopted). Probing is lazy: it stops at the first free port, so
+ * this binds no more ports than it has to.
+ */
+export function selectSpawnPort(
+	reg: Registry,
+	range: readonly number[],
+	reserved: readonly number[],
+	isFree: (port: number) => boolean,
+): number | null {
+	const taken = new Set<number>([...reg.values()].map(w => w.port).concat(reserved));
+	for (const port of range) {
+		if (taken.has(port)) continue; // ours already — never probe it
+		if (isFree(port)) return port;
+	}
+	return null;
+}

package/src/commands/manager.ts

@@ -33,8 +33,8 @@ import {
 	binaryIsStale,
 	needsProvision,
 	parseControlMsg,
-	pickPort,
 	type Registry,
+	selectSpawnPort,
 	sparesToSpawn,
 	staleKeys,
 	touchLastSeen,
@@ -46,12 +46,16 @@ const IDLE_MS = 20 * 60_000;
 const SWEEP_MS = 60_000;
 
 /**
- * Whether a loopback TCP port is bindable RIGHT NOW. `pickPort` only dedupes
- * against the manager's own registry; a range port can still be held by another
- * app, a stale worker, or a second manager. We pre-filter the range with this so
- * a spawned worker (which binds its forced `XCSH_BRIDGE_PORT` strictly) never
- * lands on an occupied port and dies. Bun.listen binds and throws synchronously,
- * so this stays sync — keeping provision idempotency race-free.
+ * Whether a loopback TCP port is bindable RIGHT NOW. A range port can be held by
+ * another app, a stale worker, or a second manager, and a spawned worker binds its
+ * forced `XCSH_BRIDGE_PORT` strictly — it throws and exits rather than falling back
+ * — so an occupied port must be ruled out before we hand it over.
+ *
+ * NOTE this is a BINDING probe, not a read: it takes the port and releases it. Only
+ * `selectSpawnPort` may call it, and only for ports we have not already handed out;
+ * probing one of our own in-flight workers can win the bind and kill it (#2463).
+ * Bun.listen binds and throws synchronously, so this stays sync — keeping provision
+ * idempotency race-free.
  */
 function isPortFree(port: number): boolean {
 	try {
@@ -241,10 +245,12 @@ export default class Manager extends Command {
 		const pool: SpareRec[] = [];
 
 		const spawnSpare = (): void => {
-			const usedPorts = new Set<number>([...reg.values()].map(w => w.port).concat(pool.map(s => s.port)));
-			const port = pickPort(
+			// Same rule as spawnWorker: assigned and reserved ports are never probed.
+			const port = selectSpawnPort(
 				reg,
-				range.filter(p => !usedPorts.has(p) && isPortFree(p)),
+				range,
+				pool.map(s => s.port),
+				isPortFree,
 			);
 			if (port === null) return; // range full — do not pre-warm
 			const proc = Bun.spawn([process.execPath, ...workerArgv()], {
@@ -388,8 +394,15 @@ export default class Manager extends Command {
 		};
 
 		const spawnWorker = (msg: { sessionId: string; tenant: string }, managerProvisionMs: number): void => {
-			// Registry-dedupe (pickPort) over only the ports free at the OS level.
-			const port = pickPort(reg, range.filter(isPortFree));
+			// Never probe a port we have already handed out: isPortFree BINDS to find
+			// out, so sweeping the whole range could win the bind from a worker that is
+			// still starting up and kill it (#2463). Spares are reserved the same way.
+			const port = selectSpawnPort(
+				reg,
+				range,
+				pool.map(s => s.port),
+				isPortFree,
+			);
 			if (port === null) {
 				console.error(`[xcsh manager] port range exhausted; cannot provision ${msg.sessionId}`);
 				return;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.98.1",
-	"commit": "2cf64a9979fc34447e7e1f35b466fbcc789b2289",
-	"shortCommit": "2cf64a9",
+	"version": "19.98.3",
+	"commit": "4d3b95e9c675ae810cc60b6829fa3541a042d1ac",
+	"shortCommit": "4d3b95e",
 	"branch": "main",
-	"tag": "v19.98.1",
-	"commitDate": "2026-07-28T02:41:40Z",
-	"buildDate": "2026-07-28T03:07:44.141Z",
+	"tag": "v19.98.3",
+	"commitDate": "2026-07-28T05:29:35Z",
+	"buildDate": "2026-07-28T05:56:14.196Z",
 	"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/2cf64a9979fc34447e7e1f35b466fbcc789b2289",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.1"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/4d3b95e9c675ae810cc60b6829fa3541a042d1ac",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.3"
 };

package/src/sandbox/enforce.ts

@@ -116,6 +116,29 @@ function isSystemPath(resolved: string): boolean {
 	return SYSTEM_READ_ROOTS.some(root => resolved === root || resolved.startsWith(`${root}${path.sep}`));
 }
 
+/**
+ * Character devices that discard output or route it back to the caller's own descriptors. Writing
+ * to one stores nothing and reaches no file, so it cannot carry data across the boundary — and
+ * `> /dev/null` is too common to refuse.
+ *
+ * An exact list, not a `/dev` prefix: `/dev` also holds raw block devices like `/dev/disk0`, where
+ * a write is both an escape and a catastrophe.
+ */
+const SYSTEM_WRITE_SINKS = new Set([
+	"/dev/null",
+	"/dev/zero",
+	"/dev/full",
+	"/dev/tty",
+	"/dev/stdin",
+	"/dev/stdout",
+	"/dev/stderr",
+]);
+
+function isSystemWriteSink(resolved: string): boolean {
+	// /dev/fd/N is an already-open descriptor of this process, not a path it can newly reach.
+	return SYSTEM_WRITE_SINKS.has(resolved) || resolved.startsWith("/dev/fd/");
+}
+
 function firstString(input: Record<string, unknown>, keys: string[]): string | undefined {
 	for (const key of keys) {
 		const value = input[key];
@@ -132,52 +155,193 @@ function looksLikePath(token: string): boolean {
 	return path.isAbsolute(token) || token.startsWith("~") || /(^|[/\\])\.\.([/\\]|$)/.test(token);
 }
 
+/** A path-like token found by the floor, with where it was found. */
+interface PathOccurrence {
+	token: string;
+	/** Offset of the token's first character — past any opening quote — in the scanned string. */
+	at: number;
+	/** Set when a redirection operator in the raw text says what the shell will do with it. */
+	access?: SandboxAccess;
+}
+
+/**
+ * What a redirection operator does to the operand that follows it. `skip` is a here-string or a
+ * heredoc delimiter: that operand is literal data the shell never opens — verified against bash,
+ * where `cat <<</tmp/f` prints the string `/tmp/f` rather than the contents of that file.
+ */
+function operandAccess(operator: string): SandboxAccess | "skip" {
+	if (operator.includes("<<")) return "skip";
+	// `<>` opens for both; the write side is the one a read-only grant must not license.
+	return operator.includes(">") ? "write" : "read";
+}
+
+/** A path to check, and the boundary to check it against. */
+interface PathCandidate {
+	token: string;
+	access: SandboxAccess;
+}
+
+/** Write first, so a `<>` denial names the stricter boundary the caller is most likely missing. */
+const WRITE_AND_READ = ["write", "read"] as const satisfies readonly SandboxAccess[];
+
+/** A redirection operator, with its optional file-descriptor prefix. Longest forms first. */
+const REDIRECT_OPERATOR = /[0-9]*(?:&>>|&>|<<<|<<-|<<|>>|>\||<>|>&|<&|>|<)/g;
+
+/** A whitespace token that is only a redirection operator, so the next token is its operand. */
+const BARE_REDIRECT = /^[0-9]*(?:&>>|&>|<<<|<<-|<<|>>|>\||<>|>&|<&|>|<)$/;
+
+/**
+ * A path glued to its option, as one shell word (#2524).
+ *
+ * `path.isAbsolute("if=/work/custB/secret")` is false, so the floor's whole-token test
+ * never saw these — a single space was the difference between the blocked form and the
+ * allowed one.
+ *
+ * Only the option's VALUE is captured, never an arbitrary `/`-containing substring. That
+ * distinction is what keeps #2470 shut: scanning any slash-bearing fragment would read
+ * `sed -n '/a/p'` as a path again, which is the false positive #2479 exists to remove.
+ * The captured value still has to satisfy `looksLikePath`, so `--output=./out` stays
+ * allowed while `--output=/work/custB/x` does not.
+ *
+ * The short-option form additionally requires its value to begin with `/` or `~`. Without
+ * that, `-la` and friends would be read as an option carrying a relative path.
+ */
+const OPTION_VALUE_FORMS: readonly RegExp[] = [
+	/^-{1,2}[A-Za-z0-9][^=]*=(.+)$/, // --output=/p, -o=/p
+	/^[A-Za-z_][A-Za-z0-9_]*=(.+)$/, // if=/p, of=/p (operand style)
+	/^-[A-Za-z0-9]+([/~].*)$/, // -o/p, -C/p (no separator)
+];
+
 /**
  * Path-like tokens in a command/code string: bare (whitespace-split) and quoted.
  *
  * Indiscriminate by design, and that is the point: because it never asks what a command *means*, it
  * also catches paths hidden inside quoted scripts, heredoc bodies, `-exec` runs and substitutions.
  * This is the coverage floor for both bash and python. Do not narrow it.
+ *
+ * Offsets come along so a caller can tell one occurrence of a token from another. Nothing else about
+ * what this finds has changed: the two passes and `looksLikePath` are the floor.
  */
-function codePathTokens(command: string): string[] {
-	const tokens = new Set<string>();
-	for (const raw of command.split(/\s+/)) tokens.add(raw.replace(/^["']|["']$/g, ""));
-	for (const match of command.matchAll(/["']([^"']+)["']/g)) tokens.add(match[1]);
-	return [...tokens].filter(token => token.length > 0 && looksLikePath(token));
+function codePathOccurrences(command: string): PathOccurrence[] {
+	const found: PathOccurrence[] = [];
+	const add = (token: string, at: number, access?: SandboxAccess): void => {
+		if (token.length > 0 && looksLikePath(token)) found.push({ token, at, access });
+	};
+	// Set when the previous token was nothing but a redirection operator, so this one is its operand.
+	let carried: SandboxAccess | "skip" | undefined;
+	for (const match of command.matchAll(/\S+/g)) {
+		const raw = match[0];
+		const operand = carried;
+		carried = undefined;
+
+		if (BARE_REDIRECT.test(raw)) {
+			carried = operandAccess(raw);
+			continue;
+		}
+
+		const stripped = raw.replace(/^["']|["']$/g, "");
+		const openingQuote = raw.length !== stripped.length && (raw[0] === '"' || raw[0] === "'") ? 1 : 0;
+		if (operand !== "skip") add(stripped, match.index + openingQuote, operand);
+		// An operator glued to its operand is one whitespace token, and `>/work/x` is not absolute.
+		// The lexer resolves this for words it can see, but not for text inside a quoted script or a
+		// heredoc body — where the floor is the only thing looking — so scan past the operator here
+		// too, anywhere it appears in the token: `echo a>/work/x` is one token as well. The operator
+		// is also the only thing that says which boundary a nested redirect crosses.
+		for (const operator of stripped.matchAll(REDIRECT_OPERATOR)) {
+			const access = operandAccess(operator[0]);
+			if (access === "skip") continue;
+			const from = operator.index + operator[0].length;
+			add(stripped.slice(from).replace(/^["']|["']$/g, ""), match.index + openingQuote + from, access);
+		}
+
+		// An option glued to its value is one word too, and the lexer cannot help: it
+		// correctly reports `if=/work/custB/secret` as a single word, because that is what
+		// it is. Which options introduce a filename is command-specific knowledge the floor
+		// deliberately does not have, so scan the value and let `looksLikePath` decide.
+		//
+		// Skipped after a here-string or heredoc delimiter for the same reason the whole
+		// token is: that operand is literal data the shell never opens, so `cat <<<if=/tmp/f`
+		// prints the text rather than reading the file.
+		if (operand !== "skip") {
+			for (const form of OPTION_VALUE_FORMS) {
+				const optionValue = stripped.match(form);
+				if (!optionValue?.[1]) continue;
+				const from = stripped.length - optionValue[1].length;
+				add(optionValue[1].replace(/^["']|["']$/g, ""), match.index + openingQuote + from, operand);
+				break; // the forms overlap; the first that matches has already captured the value
+			}
+		}
+	}
+	for (const match of command.matchAll(/["']([^"']+)["']/g)) add(match[1], match.index + 1);
+	return found;
+}
+
+/** The floor as plain read candidates — what a non-shell language gets. */
+function codePathCandidates(command: string): PathCandidate[] {
+	return codePathOccurrences(command).map(({ token }) => ({ token, access: "read" as const }));
 }
 
 /**
- * Path-like tokens of a *bash* command, ignoring words the invoked command provably treats as a
- * script or pattern rather than a filename (issue #2470: `sed -n '/a/p'` was refused because `/a/p`
- * looks absolute, though sed never opens it).
+ * Path candidates of a *bash* command. Three things happen here, and only the first narrows:
  *
- * Implemented by blanking the exempt spans and re-running the floor over what remains, rather than
- * by subtracting a set of token strings. Set subtraction loses which *occurrence* a token came from,
- * so `echo '/elsewhere/x' && cat /elsewhere/x` would exempt the echo operand and thereby clear the
- * identical token belonging to `cat`. Blanking is positional and cannot leak that way.
+ * 1. **Exempt words are blanked.** Words the invoked command provably treats as a script or pattern
+ *    rather than a filename stop being scanned (issue #2470: `sed -n '/a/p'` was refused because
+ *    `/a/p` looks absolute, though sed never opens it). Implemented by blanking the exempt spans and
+ *    re-running the floor over what remains, rather than by subtracting a set of token strings. Set
+ *    subtraction loses which *occurrence* a token came from, so `echo '/elsewhere/x' && cat
+ *    /elsewhere/x` would exempt the echo operand and thereby clear the identical token belonging to
+ *    `cat`. Blanking is positional and cannot leak that way.
  *
- * It also keeps the floor's reach: text the lexer never turns into a word — a heredoc body, an
+ * 2. **A word the shell opens for writing is checked against the write boundary** (issue #2516).
+ *    Every candidate used to be checked as a read, so a path granted read access but not write was
+ *    writable through `>`. Marking is by span, for the same occurrence-identity reason as blanking:
+ *    in `cat /shared/x && printf y > /shared/x` only the second occurrence is the write.
+ *
+ * 3. **Redirect targets are added as candidates** (issue #2520). The floor splits on whitespace, so
+ *    an operator glued to its path — `cat </work/custB/secret` — was one token that did not look
+ *    like a path and was never checked at all. The lexer parses those correctly, so its redirect
+ *    targets go in on top of the floor. This only ever adds candidates.
+ *
+ * The floor's reach is unchanged: text the lexer never turns into a word — a heredoc body, an
  * `-exec` run — is not blanked, so it is still scanned. When the command cannot be lexed
- * confidently, nothing is blanked at all.
+ * confidently, the floor stands alone.
  */
-function shellPathTokens(command: string): string[] {
-	const floor = codePathTokens(command);
-	if (floor.length === 0) return floor;
-
+function shellPathCandidates(command: string): PathCandidate[] {
 	const lexed = lexShellCommand(command);
-	// Unbalanced quotes mean the word boundaries are guesses; keep the whole floor.
-	if (lexed.unterminated) return floor;
+	// Unbalanced quotes mean every word boundary is a guess: neither the blanking nor the write
+	// marking below can be trusted, so fall back to the floor, checked as reads.
+	if (lexed.unterminated) return codePathCandidates(command);
 
 	const exemptSpans = lexed.commands.flatMap(simpleCommand => provenExemptWords(simpleCommand));
-	if (exemptSpans.length === 0) return floor;
-
+	let scanned = command;
 	// Replace each exempt word with equivalent-length whitespace, so surrounding offsets and word
 	// boundaries are preserved and only that word's own text stops being scanned.
-	let masked = command;
 	for (const word of exemptSpans) {
-		masked = masked.slice(0, word.start) + " ".repeat(word.end - word.start) + masked.slice(word.end);
+		scanned = scanned.slice(0, word.start) + " ".repeat(word.end - word.start) + scanned.slice(word.end);
 	}
-	return codePathTokens(masked);
+
+	// `<>` opens for both, so it stays a read here and picks up its write below: a floor occurrence
+	// may carry only one access, and read is the one the floor would have used anyway.
+	const writeTargets = lexed.words.filter(word => word.redirect === "write");
+	const inWriteTarget = (at: number): boolean => writeTargets.some(word => at >= word.start && at < word.end);
+
+	// A floor occurrence takes the access its own operator gave it; failing that, the span of a
+	// lexed write target it sits inside; failing that, read.
+	const candidates: PathCandidate[] = codePathOccurrences(scanned).map(({ token, at, access }) => ({
+		token,
+		access: access ?? (inWriteTarget(at) ? "write" : "read"),
+	}));
+
+	// Not gated on `looksLikePath`: that test is for the floor's *guesses* about which fragments of a
+	// command might be filenames. A redirect target is one the shell will certainly open, so a bare
+	// `out.txt` is checked too — it resolves under the cwd, which a read-only cwd does not license.
+	for (const word of lexed.words) {
+		if (word.redirect === undefined || word.redirect === "here-string") continue;
+		for (const access of word.redirect === "read-write" ? WRITE_AND_READ : [word.redirect]) {
+			candidates.push({ token: word.text, access });
+		}
+	}
+	return candidates;
 }
 
 /** Base directories a search input would actually search, split like the tools do. */
@@ -216,13 +380,19 @@ function evaluateCodeTool(check: ToolCallCheck, fields: string[], shell: boolean
 	}
 
 	for (const command of commands) {
-		// Only bash gets the shell-aware subtraction. Python is not shell: lexing `open('/x')` as
-		// shell yields one non-absolute word and would lose the check entirely.
-		for (const token of shell ? shellPathTokens(command) : codePathTokens(command)) {
+		// Only bash gets the shell-aware treatment. Python is not shell: lexing `open('/x')` as
+		// shell yields one non-absolute word and would lose the check entirely, and it has no
+		// redirects, so every candidate it produces is a read.
+		const seen = new Set<string>();
+		for (const { token, access } of shell ? shellPathCandidates(command) : codePathCandidates(command)) {
+			if (!seen.add(`${access}\0${token}`)) continue;
 			const resolved = resolveToCwd(token, base);
-			if (!policy.isAllowed(resolved, "read") && !isSystemPath(resolved)) {
-				return deny(policy, resolved, "read");
-			}
+			if (policy.isAllowed(resolved, access)) continue;
+			// SYSTEM_READ_ROOTS is a read allowance — "directories a subprocess may legitimately
+			// read or traverse". It never licenses writing into /etc, /usr or /opt; only the
+			// discard-and-echo devices are writable.
+			if (access === "read" ? isSystemPath(resolved) : isSystemWriteSink(resolved)) continue;
+			return deny(policy, resolved, access);
 		}
 	}
 

package/src/tools/shell-lex.ts

@@ -23,6 +23,12 @@
 /** How a word was quoted. `mixed` when built from differently-quoted segments, as in `a"b"'c'`. */
 export type QuoteKind = "none" | "single" | "double" | "ansi-c" | "mixed";
 
+/**
+ * What the shell will do with a redirect operand. `<>` opens the file for both. `here-string` is
+ * `<<<`, whose operand is literal text supplied on stdin — the shell never opens it as a path.
+ */
+export type RedirectDirection = "read" | "write" | "read-write" | "here-string";
+
 export interface ShellWord {
 	/** Literal text after quote removal and backslash processing. */
 	text: string;
@@ -37,8 +43,11 @@ export interface ShellWord {
 	 * must not treat a non-literal word as a resolvable path or a whole-word URL.
 	 */
 	literal: boolean;
-	/** Set when this word is the target of a redirection, with the direction of that redirect. */
-	redirect: "read" | "write" | undefined;
+	/**
+	 * Set when this word is the target of a redirection, with the direction of that redirect.
+	 * `read-write` is `<>`, which opens the one file for both.
+	 */
+	redirect: RedirectDirection | undefined;
 }
 
 export type ShellOperator = "|" | "||" | "&&" | ";" | "&" | "\n";
@@ -245,7 +254,7 @@ function readOperator(lexer: Lexer): ShellOperator | undefined {
 }
 
 type RedirectToken =
-	| { kind: "file"; direction: "read" | "write" }
+	| { kind: "file"; direction: RedirectDirection }
 	| { kind: "fd-dup" }
 	| { kind: "heredoc"; stripTabs: boolean };
 
@@ -274,10 +283,10 @@ function readRedirect(lexer: Lexer, end: number): RedirectToken | undefined {
 		return { kind: "file", direction: "write" };
 	}
 	if (src.startsWith("<<<", cursor)) {
-		// A here-string supplies literal text, not a filename, but treating it as a redirect target
-		// keeps it out of the exemptible-operand set.
+		// A here-string supplies literal text, not a filename. It stays a redirect target so it is
+		// still kept out of the exemptible-operand set, but its direction says it is never opened.
 		lexer.pos = cursor + 3;
-		return { kind: "file", direction: "read" };
+		return { kind: "file", direction: "here-string" };
 	}
 	if (src.startsWith("<<-", cursor)) {
 		lexer.pos = cursor + 3;
@@ -287,15 +296,33 @@ function readRedirect(lexer: Lexer, end: number): RedirectToken | undefined {
 		lexer.pos = cursor + 2;
 		return { kind: "heredoc", stripTabs: false };
 	}
-	if (src.startsWith(">&", cursor) || src.startsWith("<&", cursor)) {
+	// `<>` opens one file for reading and writing; reported as `<` alone the write would be invisible.
+	if (src.startsWith("<>", cursor)) {
 		lexer.pos = cursor + 2;
-		while (lexer.pos < end && (isDigit(src[lexer.pos]) || src[lexer.pos] === "-")) lexer.pos++;
-		return { kind: "fd-dup" };
+		return { kind: "file", direction: "read-write" };
+	}
+	// `>&` and `<&` duplicate a descriptor only when a descriptor follows: `2>&1`, `3>&-`. With a
+	// filename after it — `printf x >&out.txt` — bash opens the file instead, sending both stdout
+	// and stderr to it, so the target has to be checked like any other write.
+	if (src.startsWith(">&", cursor) || src.startsWith("<&", cursor)) {
+		const write = src[cursor] === ">";
+		let scan = cursor + 2;
+		while (scan < end && isDigit(src[scan])) scan++;
+		if (src[scan] === "-") scan++;
+		const duplicated = scan > cursor + 2 && (scan >= end || isWordBreak(src[scan]));
+		lexer.pos = duplicated ? scan : cursor + 2;
+		return duplicated ? { kind: "fd-dup" } : { kind: "file", direction: write ? "write" : "read" };
 	}
 	if (src.startsWith(">>", cursor)) {
 		lexer.pos = cursor + 2;
 		return { kind: "file", direction: "write" };
 	}
+	// `>|` overrides noclobber. Without this the `|` reads as a pipe and the filename after it
+	// becomes the next command's name, so the write target is lost.
+	if (src.startsWith(">|", cursor)) {
+		lexer.pos = cursor + 2;
+		return { kind: "file", direction: "write" };
+	}
 	if (ch === ">") {
 		lexer.pos = cursor + 1;
 		return { kind: "file", direction: "write" };
@@ -304,6 +331,11 @@ function readRedirect(lexer: Lexer, end: number): RedirectToken | undefined {
 	return { kind: "file", direction: "read" };
 }
 
+/** True where a word ends: whitespace, or the start of an operator or grouping. */
+function isWordBreak(ch: string | undefined): boolean {
+	return ch === undefined || /[\s;&|<>()]/.test(ch);
+}
+
 function isDigit(ch: string | undefined): boolean {
 	return ch !== undefined && ch >= "0" && ch <= "9";
 }