@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/domains/safety/protected-artifacts.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { artifactDefaultPath } from "../../core/artifact-paths.js";
-import { canonicalizeExistingPath } from "../../core/path-canonical.js";
+import { canonicalizeExistingPath, canonicalizeRawPath } from "../../core/path-canonical.js";
 import { ToolNames } from "../../core/tool-names.js";
 import { isVerificationScriptName } from "../../core/verification-scripts.js";
 
@@ -73,7 +73,8 @@ interface NormalizedArtifact {
 	artifact: ProtectedArtifact;
 }
 
-const COMMAND_SEPARATORS = new Set([";", "&", "&&", "||", "|"]);
+// `(` and `)` open and close a subshell or group; each side starts a new command.
+const COMMAND_SEPARATORS = new Set([";", "&", "&&", "||", "|", "(", ")"]);
 const SHELL_WRAPPERS = new Set(["command", "builtin", "sudo", "doas"]);
 const SHELL_REDIRECTIONS = new Set([">", ">>", "<", "<<", "<<<", "<&", ">&", "<>", ">|", "&>", "&>>"]);
 const SHELL_WRITE_REDIRECTIONS = new Set([">", ">>", ">&", "<>", ">|", "&>", "&>>"]);
@@ -84,6 +85,8 @@ export interface ShellToken {
 	quoted: boolean;
 	start: number;
 	end: number;
+	/** Scripts of the `$(...)`, `<(...)`, and `>(...)` substitutions this word carries. */
+	substitutions?: string[];
 }
 
 /**
@@ -158,7 +161,11 @@ function classifyDestructiveCommand(
 	const artifacts = normalizedArtifacts(protectedArtifacts);
 	if (artifacts.length === 0) return { kind: "benign", matches: [] };
 
-	for (const tokens of splitSegments(scanShellLike(command))) {
+	const segments = splitSegments(scanShellLike(command)).flatMap((tokens) => [
+		tokens,
+		...substitutionSegments(tokens, 0),
+	]);
+	for (const tokens of segments) {
 		const segment = shellCommandArguments(tokens);
 		const redirect = classifyRedirect(tokens, artifacts);
 		if (redirect.kind === "destructive") return redirect;
@@ -310,7 +317,7 @@ function expandedShellSegments(command: string, depth = 0): ShellToken[][] {
 	if (depth >= INNER_SHELL_MAX_DEPTH) return segments;
 	const out: ShellToken[][] = [];
 	for (const segment of segments) {
-		out.push(segment);
+		out.push(segment, ...substitutionSegments(segment, depth));
 		const script = segmentShellScript(shellCommandArguments(segment));
 		if (script !== null) out.push(...expandedShellSegments(script, depth + 1));
 	}
@@ -342,17 +349,388 @@ export function inlineShellScript(command: string): string | null {
 export function extractCommandCdTargets(command: string): string[] {
 	const targets: string[] = [];
 	for (const tokens of expandedShellSegments(command)) {
-		const segment = shellCommandArguments(tokens);
-		const commandIndex = commandTokenIndex(segment);
-		if (commandIndex === null) continue;
-		const executable = basenameToken(segment[commandIndex]);
-		if (executable !== "cd" && executable !== "pushd") continue;
-		const target = pathArgs(segment, commandIndex).at(0);
-		targets.push(target ?? "~");
+		const target = cdTarget(shellCommandArguments(tokens));
+		if (target !== null) targets.push(target);
 	}
 	return targets;
 }
 
+function cdTarget(segment: ReadonlyArray<string>): string | null {
+	const commandIndex = commandTokenIndex(segment);
+	if (commandIndex === null) return null;
+	const executable = basenameToken(segment[commandIndex]);
+	if (executable !== "cd" && executable !== "pushd") return null;
+	return pathArgs(segment, commandIndex).at(0) ?? "~";
+}
+
+/**
+ * A path-bearing step of a shell command, in the order the shell takes them.
+ * `link` is a link the command creates: `sources` are what it points at (a
+ * symbolic link's text, or the file a hard link shares), and `linkDirs` are the
+ * directories it may be created in, relative to where the shell is. A
+ * `subshell` opens or closes a child shell: `( ... )`, a substitution, or the
+ * script of an `sh -c`. A cd is `unmodeled` when it can run more times than it
+ * is written, or resolve somewhere its text does not say: inside a loop, after
+ * a function definition, or with CDPATH named.
+ */
+export type CommandPathEvent =
+	| { kind: "cd"; target: string; unmodeled: boolean }
+	| { kind: "write"; target: string }
+	| { kind: "link"; symbolic: boolean; sources: string[]; linkDirs: string[]; origin: LinkOrigin }
+	| { kind: "subshell"; open: boolean };
+
+/**
+ * How a link event knows its sources. `text` is a link made from the words
+ * the command names. `copied` is `mv`, or a `cp` that keeps links, whose
+ * sources are existing paths: a source that is itself a link is recreated with
+ * the same text. `input` is `xargs` or `find -exec`, whose real operands come
+ * from input the scanner never sees.
+ */
+export type LinkOrigin = "text" | "copied" | "input";
+
+interface CommandPathWalkState {
+	events: CommandPathEvent[];
+	/** Loops open around the current segment; their cds may run any number of times. */
+	loopDepth: number;
+	/** A function is defined before this point, so a later call can rerun any cd. */
+	functionSeen: boolean;
+	/** CDPATH is named, so a relative cd may resolve against it instead. */
+	cdpath: boolean;
+	/** A `case` pattern ends in a bare `)`, so no parenthesis can be trusted as a subshell. */
+	caseSeen: boolean;
+	/**
+	 * A here-document opened before this point that the walk reads with its
+	 * body. The scanner reads body lines as commands, so a later cd or
+	 * parenthesis may be body text.
+	 */
+	heredocSeen: boolean;
+	/** Whether a top-level here-document counts, or only one inside a substitution or `sh -c`. */
+	topLevelHeredocs: boolean;
+}
+
+/** Words that open a loop whose condition and body may run more than once; `done` closes it. */
+const LOOP_WORDS: ReadonlySet<string> = new Set(["for", "while", "until", "select"]);
+
+/** The reserved words a segment starts with, and a leading for, case, or select. */
+function leadingShellWords(argv: ReadonlyArray<string>): string[] {
+	const words: string[] = [];
+	for (const word of argv) {
+		if (SHELL_RESERVED_PREFIXES.has(word)) {
+			words.push(word);
+			continue;
+		}
+		if (word === "for" || word === "case" || word === "select") words.push(word);
+		break;
+	}
+	return words;
+}
+
+/**
+ * The cd, write, and link steps of a command in order, with the child shells
+ * around them, so a caller can resolve each write against every directory an
+ * earlier cd can leave the shell in. A segment's substitutions and redirects
+ * are opened before its command runs, so they come before its cd.
+ */
+function extractCommandPathWalk(command: string, topLevelHeredocs = true): CommandPathEvent[] {
+	const walk: CommandPathWalkState = {
+		events: [],
+		loopDepth: 0,
+		functionSeen: false,
+		cdpath: /\bCDPATH\b/u.test(command),
+		caseSeen: false,
+		heredocSeen: false,
+		topLevelHeredocs,
+	};
+	collectPathWalk(command, 0, walk);
+	return walk.caseSeen ? walk.events.filter((event) => event.kind !== "subshell") : walk.events;
+}
+
+/**
+ * The path walks a caller has to judge a command by. The scanner cannot tell a
+ * here-document body line from a command: a body `(` and `)` around a real cd
+ * made the walk forget it, and a lone quote in a body swallowed every later
+ * command. So a command with a here-document is also read with its bodies
+ * removed, and a write escalates when either walk escalates it. A
+ * here-document that cannot be removed, because it sits inside a substitution
+ * or an `sh -c` script or has no word, leaves every later cd unmodeled.
+ */
+export function extractCommandPathWalks(command: string): CommandPathEvent[][] {
+	const withoutBodies = withoutHeredocBodies(command);
+	if (withoutBodies === command) return [extractCommandPathWalk(command)];
+	const removedAll = !scanShellLike(withoutBodies).some((token) => token.operator && token.value === "<<");
+	return [extractCommandPathWalk(command, !removedAll), extractCommandPathWalk(withoutBodies)];
+}
+
+/** More here-documents than this in one command are left in place. */
+const MAX_HEREDOCS = 64;
+
+/**
+ * The command with each top-level here-document body removed and its `<<WORD`
+ * blanked, so what is left reads as the commands bash runs. A body starts on
+ * the line after its operator and ends at the line that is exactly its word
+ * (tabs stripped first for `<<-`), or at the end of the command, as in bash.
+ * Several here-documents on one line take their bodies in order.
+ */
+function withoutHeredocBodies(command: string): string {
+	let text = command;
+	for (let pass = 0; pass < MAX_HEREDOCS; pass += 1) {
+		const tokens = scanShellLike(text);
+		const first = tokens.findIndex((token) => token.operator && token.value === "<<");
+		if (first === -1) return text;
+		const lineEnd = tokens.findIndex(
+			(token, index) => index > first && token.operator && token.value === ";" && text[token.start] === "\n",
+		);
+		const docs: Array<{ start: number; end: number; word: string; stripTabs: boolean }> = [];
+		for (let index = first; index < (lineEnd === -1 ? tokens.length : lineEnd); index += 1) {
+			const operator = tokens[index];
+			if (operator === undefined || !operator.operator || operator.value !== "<<") continue;
+			let word = tokens[index + 1];
+			let stripTabs = false;
+			if (word !== undefined && !word.operator && word.start === operator.end && text[word.start] === "-") {
+				stripTabs = true;
+				if (word.value === "-") word = tokens[index + 2];
+			}
+			// `<<` with no word is a syntax error: bash runs nothing, so leave it as written.
+			if (word === undefined || word.operator) return text;
+			const delimiter = stripTabs && text[word.start] === "-" ? word.value.slice(1) : word.value;
+			docs.push({ start: operator.start, end: word.end, word: delimiter, stripTabs });
+		}
+		let head = text;
+		for (const doc of [...docs].reverse()) {
+			head = `${head.slice(0, doc.start)}${" ".repeat(doc.end - doc.start)}${head.slice(doc.end)}`;
+		}
+		if (lineEnd === -1) {
+			text = head;
+			continue;
+		}
+		const bodyStart = (tokens[lineEnd]?.start ?? text.length) + 1;
+		let cursor = bodyStart;
+		for (const doc of docs) {
+			while (cursor < text.length) {
+				const newline = text.indexOf("\n", cursor);
+				const line = text.slice(cursor, newline === -1 ? text.length : newline);
+				cursor = newline === -1 ? text.length : newline + 1;
+				if ((doc.stripTabs ? line.replace(/^\t+/u, "") : line) === doc.word) break;
+			}
+		}
+		text = `${head.slice(0, bodyStart)}${text.slice(cursor)}`;
+	}
+	return text;
+}
+
+function collectPathWalk(command: string, depth: number, walk: CommandPathWalkState): void {
+	const tokens = scanShellLike(command);
+	let segment: ShellToken[] = [];
+	for (const [index, token] of tokens.entries()) {
+		if (token.operator && COMMAND_SEPARATORS.has(token.value)) {
+			collectSegmentPathEvents(segment, depth, walk);
+			segment = [];
+			// `name()` defines a function whose body may run any number of times.
+			const next = tokens[index + 1];
+			if (token.value === "(" && next?.operator === true && next.value === ")") walk.functionSeen = true;
+			// After a here-document a parenthesis may be body text, and a false `)`
+			// would restore bases from before a real cd, so none are trusted.
+			if ((token.value === "(" || token.value === ")") && !walk.heredocSeen)
+				walk.events.push({ kind: "subshell", open: token.value === "(" });
+			continue;
+		}
+		segment.push(token);
+	}
+	collectSegmentPathEvents(segment, depth, walk);
+}
+
+function collectChildScript(script: string, depth: number, walk: CommandPathWalkState): void {
+	if (depth >= INNER_SHELL_MAX_DEPTH) return;
+	walk.events.push({ kind: "subshell", open: true });
+	collectPathWalk(script, depth + 1, walk);
+	// A body line can hide a later command from the walk above, as a lone quote does.
+	const withoutBodies = withoutHeredocBodies(script);
+	if (withoutBodies !== script) collectPathWalk(withoutBodies, depth + 1, walk);
+	// A here-document body can move where the scanner thinks a substitution
+	// ends, so the script may hold commands of the parent: keep its cds.
+	if (!walk.heredocSeen) walk.events.push({ kind: "subshell", open: false });
+}
+
+function collectSegmentPathEvents(segment: ReadonlyArray<ShellToken>, depth: number, walk: CommandPathWalkState): void {
+	if (segment.length === 0) return;
+	for (const token of segment) {
+		for (const script of token.substitutions ?? []) collectChildScript(script, depth, walk);
+	}
+	const argv = shellCommandArguments(segment);
+	if (argv[0] === "done" && walk.loopDepth > 0) walk.loopDepth -= 1;
+	if (argv[0] === "function") walk.functionSeen = true;
+	for (const word of leadingShellWords(argv)) {
+		if (LOOP_WORDS.has(word)) walk.loopDepth += 1;
+		if (word === "case") walk.caseSeen = true;
+	}
+	const writes: string[] = [];
+	collectRedirectTargets(segment, writes);
+	collectInvokedWriteTargets(argv, writes);
+	collectInPlaceEditTargets(argv, writes);
+	for (const target of writes.filter(isInterestingWriteTarget)) walk.events.push({ kind: "write", target });
+	collectLinkEvents(argv, walk.events);
+	const cd = cdTarget(argv);
+	if (cd !== null) {
+		walk.events.push({
+			kind: "cd",
+			target: cd,
+			unmodeled: walk.loopDepth > 0 || walk.functionSeen || walk.cdpath || walk.heredocSeen,
+		});
+	}
+	const script = segmentShellScript(argv);
+	if (script !== null) collectChildScript(script, depth, walk);
+	// The body starts on the next line, so this segment's own cd is real.
+	if ((depth > 0 || walk.topLevelHeredocs) && segment.some((token) => token.operator && token.value === "<<"))
+		walk.heredocSeen = true;
+}
+
+/** Commands that run the command after them, possibly with options and arguments of their own. */
+const LINK_WRAPPERS: ReadonlySet<string> = new Set([
+	"nice",
+	"nohup",
+	"timeout",
+	"stdbuf",
+	"ionice",
+	"chrt",
+	"xargs",
+	"busybox",
+	"setsid",
+	"taskset",
+	"flock",
+	"exec",
+	"find",
+]);
+
+/** Commands that can make a link, or recreate one they move or copy. */
+const LINK_COMMANDS: ReadonlySet<string> = new Set(["ln", "link", "cp", "mv"]);
+
+/**
+ * The index of the link command a wrapper runs, and whether its operands come
+ * from input. A wrapper's own options and arguments are skipped by looking for
+ * the next word that names a link command or another wrapper; `find` runs
+ * what follows `-exec`, `-execdir`, `-ok`, or `-okdir`.
+ */
+function linkCommandIndex(argv: ReadonlyArray<string>): { index: number; fromInput: boolean } | null {
+	let index = commandTokenIndex(argv);
+	let fromInput = false;
+	while (index !== null && LINK_WRAPPERS.has(basenameToken(argv[index]))) {
+		const wrapper = basenameToken(argv[index]);
+		if (wrapper === "xargs" || wrapper === "find") fromInput = true;
+		const from = index;
+		const next =
+			wrapper === "find"
+				? argv.findIndex((word, at) => at > from && /^-(?:exec|execdir|ok|okdir)$/u.test(word)) + 1
+				: argv.findIndex(
+						(word, at) => at > from && (LINK_COMMANDS.has(basenameToken(word)) || LINK_WRAPPERS.has(basenameToken(word))),
+					);
+		index = next > from ? next : null;
+	}
+	return index === null ? null : { index, fromInput };
+}
+
+/**
+ * Links a command makes. `ln` (hard unless `-s`), `link` (always hard), `cp -s`,
+ * and `cp -l` make one from the words they name. `mv` and a `cp` that keeps
+ * links (`-a`, `-P`, `-d`, `--no-dereference`, or a recursive copy without
+ * `-L` or `-H`) recreate any source that is itself a link. Behind `xargs` or
+ * `find -exec` the operands are unknown. With `-t DIR` every link goes in DIR;
+ * with one operand it goes in the current directory; otherwise the last operand
+ * is either the link or, when it is a directory, where the links go, unless
+ * `-T` says it is never a directory.
+ */
+function collectLinkEvents(argv: ReadonlyArray<string>, out: CommandPathEvent[]): void {
+	const found = linkCommandIndex(argv);
+	if (found === null) return;
+	const cmdIndex = found.index;
+	const executable = basenameToken(argv[cmdIndex]);
+	if (!LINK_COMMANDS.has(executable)) return;
+	let symbolic = false;
+	let hard = executable === "ln" || executable === "link";
+	let keepsLinks = executable === "mv";
+	let dereferences = false;
+	let targetDirectory: string | null = null;
+	let noTargetDirectory = false;
+	let endOfOptions = false;
+	const operands: string[] = [];
+	for (let index = cmdIndex + 1; index < argv.length; index += 1) {
+		const token = argv[index] ?? "";
+		// `find -exec` ends its command at a lone `;` or `+`.
+		if (found.fromInput && (token === ";" || token === "+")) break;
+		if (endOfOptions || !token.startsWith("-") || token === "-") {
+			operands.push(token);
+			continue;
+		}
+		if (token === "--") {
+			endOfOptions = true;
+			continue;
+		}
+		if (token.startsWith("--")) {
+			const eq = token.indexOf("=");
+			const name = eq === -1 ? token : token.slice(0, eq);
+			const value = eq === -1 ? undefined : token.slice(eq + 1);
+			if (executable === "mv") {
+				if (name === "--target-directory") {
+					targetDirectory = value ?? argv[index + 1] ?? null;
+					if (value === undefined) index += 1;
+				} else if (name === "--no-target-directory") noTargetDirectory = true;
+				else if (name === "--suffix" && value === undefined) index += 1;
+				continue;
+			}
+			if (name === "--symbolic" || name === "--symbolic-link") symbolic = true;
+			else if (name === "--link") hard = true;
+			else if (name === "--archive" || name === "--no-dereference" || name === "--recursive") keepsLinks = true;
+			else if (name === "--dereference") dereferences = true;
+			else if (name === "--no-target-directory") noTargetDirectory = true;
+			else if (name === "--target-directory") {
+				targetDirectory = value ?? argv[index + 1] ?? null;
+				if (value === undefined) index += 1;
+			} else if (name === "--suffix" && value === undefined) index += 1;
+			continue;
+		}
+		for (let at = 1; at < token.length; at += 1) {
+			const flag = token[at];
+			if (flag === "s" && executable !== "mv") symbolic = true;
+			else if (flag === "l" && executable === "cp") hard = true;
+			else if (executable === "cp" && flag !== undefined && "aPdrR".includes(flag)) keepsLinks = true;
+			else if (executable === "cp" && (flag === "L" || flag === "H")) dereferences = true;
+			else if (flag === "T") noTargetDirectory = true;
+			else if (flag === "t" || flag === "S") {
+				// The rest of the cluster, or the next word, is the option's argument.
+				const rest = token.slice(at + 1);
+				const value = rest.length > 0 ? rest : argv[index + 1];
+				if (rest.length === 0) index += 1;
+				if (flag === "t") targetDirectory = value ?? null;
+				break;
+			}
+		}
+	}
+	const copied = !symbolic && !hard && keepsLinks && !dereferences;
+	if (!symbolic && !hard && !copied) return;
+	let sources = operands;
+	let linkDirs = ["."];
+	if (targetDirectory !== null) {
+		linkDirs = [targetDirectory];
+		out.push({ kind: "write", target: targetDirectory });
+	} else if (operands.length > 1) {
+		const destination = operands.at(-1) as string;
+		sources = operands.slice(0, -1);
+		const parent = path.posix.dirname(destination);
+		linkDirs = noTargetDirectory ? [parent] : [parent, destination];
+	}
+	const origin: LinkOrigin = found.fromInput ? "input" : copied ? "copied" : "text";
+	if (origin === "input") {
+		out.push({
+			kind: "link",
+			symbolic: symbolic || copied,
+			sources: operands.length > 0 ? operands : ["<input>"],
+			linkDirs,
+			origin,
+		});
+		return;
+	}
+	if (sources.length > 0) out.push({ kind: "link", symbolic: symbolic || copied, sources, linkDirs, origin });
+}
+
 /**
  * Returns paths that common shell commands would remove from their current
  * location. This intentionally covers only deterministic, path-bearing
@@ -384,7 +762,7 @@ export function extractCommandDeleteTargets(command: string): string[] {
 /** Recognizable operator CLI installation paths invoked through a model shell.
  * This is command inspection, not confinement of arbitrary scripts or aliases.
  */
-export function invokesClioSkillMutation(command: string): boolean {
+export function invokesClioSkillMutation(command: string, excludeLibrary = false): boolean {
 	for (const segment of expandedShellSegments(command)) {
 		const argv = shellCommandArguments(segment);
 		const index = commandTokenIndex(argv);
@@ -423,6 +801,7 @@ export function invokesClioSkillMutation(command: string): boolean {
 			args[0] !== "interop"
 		)
 			continue;
+		if (excludeLibrary && args[0] === "library") continue;
 		if (resourceCliMutatesSkills(args[0], args.slice(1))) return true;
 	}
 	return false;
@@ -762,7 +1141,36 @@ function pathMatchesArtifact(commandPath: string, artifactKey: string, mode: "ta
 	return isSameOrDescendant(commandKey, artifactKey) || isSameOrDescendant(artifactKey, commandKey);
 }
 
-function validationMatch(executable: string, args: ReadonlyArray<string>): string | null {
+/**
+ * Every fixed label `validationMatch` returns. The only other label is the
+ * `npm run <verification script>` family. The policy engine's
+ * `TEST_RUNNER_COMMANDS` must run each of these without an ask at auto-edit;
+ * `tests/contracts/test-runner-vocabulary.test.ts` fails when the two drift.
+ */
+export const VALIDATION_COMMAND_LABELS = [
+	"npm test",
+	"node --test",
+	"pytest",
+	"python -m pytest",
+	"python -m unittest",
+	"cargo test",
+	"go test",
+	"ctest",
+	"make test",
+	"make check",
+	"ninja test",
+	"meson test",
+	"mvn test",
+	"gradle test",
+] as const;
+
+export type ValidationCommandLabel = (typeof VALIDATION_COMMAND_LABELS)[number];
+
+function validationMatch(
+	executable: string,
+	args: ReadonlyArray<string>,
+): ValidationCommandLabel | `npm run ${string}` | null {
+	if (executable === "node" && args[0] === "--test") return "node --test";
 	if (executable === "npm") {
 		if (args[0] === "test") return "npm test";
 		const script = args[0] === "run" && typeof args[1] === "string" ? args[1] : null;
@@ -770,11 +1178,14 @@ function validationMatch(executable: string, args: ReadonlyArray<string>): strin
 	}
 	if (executable === "pytest") return "pytest";
 	if (isPythonExecutable(executable) && moduleArg(args) === "pytest") return "python -m pytest";
+	if (isPythonExecutable(executable) && moduleArg(args) === "unittest") return "python -m unittest";
 	if (executable === "cargo" && args[0] === "test") return "cargo test";
 	if (executable === "go" && args[0] === "test") return "go test";
 	if (executable === "ctest") return "ctest";
 	if (executable === "make" && args[0] === "test") return "make test";
+	if (executable === "make" && args[0] === "check") return "make check";
 	if (executable === "ninja" && args[0] === "test") return "ninja test";
+	if (executable === "meson" && args[0] === "test") return "meson test";
 	if (executable === "mvn" && args[0] === "test") return "mvn test";
 	if ((executable === "gradle" || executable === "gradlew") && args[0] === "test") return "gradle test";
 	return null;
@@ -890,12 +1301,16 @@ export function scanShellLike(command: string): ShellToken[] {
 	let quoted = false;
 	let quote: "'" | '"' | null = null;
 
+	let substitutions: string[] = [];
 	const pushCurrent = (end: number): void => {
 		if (wordStart === null) return;
-		tokens.push({ value: current, operator: false, quoted, start: wordStart, end });
+		const token: ShellToken = { value: current, operator: false, quoted, start: wordStart, end };
+		if (substitutions.length > 0) token.substitutions = substitutions;
+		tokens.push(token);
 		current = "";
 		wordStart = null;
 		quoted = false;
+		substitutions = [];
 	};
 
 	for (let index = 0; index < command.length; index += 1) {
@@ -945,7 +1360,31 @@ export function scanShellLike(command: string): ShellToken[] {
 			if (char === "\n") tokens.push({ value: ";", operator: true, quoted: false, start: index, end: index + 1 });
 			continue;
 		}
-		if (";&|><".includes(char)) {
+		if (char === "(") {
+			// `$(`, `<(`, and `>(` open a substitution that belongs to the word it
+			// sits in, so `$(echo)/../x` stays one path; its script is kept for
+			// the scanners that read it as a child command.
+			const previous = tokens.at(-1);
+			const dollar = wordStart !== null && command[index - 1] === "$" && current.endsWith("$");
+			const processSubstitution =
+				wordStart === null &&
+				previous?.operator === true &&
+				previous.end === index &&
+				(previous.value === "<" || previous.value === ">");
+			if (dollar || processSubstitution) {
+				const close = matchingParen(command, index);
+				if (processSubstitution) {
+					tokens.pop();
+					wordStart = index - 1;
+					current = previous.value;
+				}
+				current += command.slice(index, close + 1);
+				substitutions.push(command.slice(index + 1, close));
+				index = close;
+				continue;
+			}
+		}
+		if (";&|><()".includes(char)) {
 			pushCurrent(index);
 			const three = command.slice(index, index + 3);
 			const two = command.slice(index, index + 2);
@@ -966,6 +1405,55 @@ export function scanShellLike(command: string): ShellToken[] {
 	return tokens;
 }
 
+/**
+ * The index of the `)` that closes the `(` at `open`, skipping quoted text and
+ * escapes, or the last index when the substitution is never closed.
+ */
+function matchingParen(command: string, open: number): number {
+	let depth = 0;
+	let quote: "'" | '"' | null = null;
+	for (let index = open; index < command.length; index += 1) {
+		const char = command[index];
+		if (quote !== null) {
+			if (char === "\\" && quote === '"') index += 1;
+			else if (char === quote) quote = null;
+			continue;
+		}
+		if (char === "\\") index += 1;
+		else if (char === "'" || char === '"') quote = char;
+		else if (char === "(") depth += 1;
+		else if (char === ")") {
+			depth -= 1;
+			if (depth === 0) return index;
+		}
+	}
+	return command.length - 1;
+}
+
+/**
+ * The segments of the substitutions a segment's words carry, read as child
+ * commands; they run before the segment's own command does.
+ */
+function substitutionSegments(tokens: ReadonlyArray<ShellToken>, depth: number): ShellToken[][] {
+	if (depth >= INNER_SHELL_MAX_DEPTH) return [];
+	return tokens.flatMap((token) =>
+		(token.substitutions ?? []).flatMap((script) => expandedShellSegments(script, depth + 1)),
+	);
+}
+
+/** scanShellLike with each substitution's tokens appended after a `;`, for scans that read every word. */
+export function scanShellLikeDeep(command: string, depth = 0): ShellToken[] {
+	const tokens = scanShellLike(command);
+	if (depth >= INNER_SHELL_MAX_DEPTH) return tokens;
+	const inner = tokens.flatMap((token) =>
+		(token.substitutions ?? []).flatMap((script) => [
+			{ value: ";", operator: true, quoted: false, start: token.start, end: token.start },
+			...scanShellLikeDeep(script, depth + 1),
+		]),
+	);
+	return [...tokens, ...inner];
+}
+
 function splitSegments(tokens: ReadonlyArray<ShellToken>): ShellToken[][] {
 	const segments: ShellToken[][] = [];
 	let current: ShellToken[] = [];
@@ -981,11 +1469,33 @@ function splitSegments(tokens: ReadonlyArray<ShellToken>): ShellToken[][] {
 	return segments;
 }
 
+/**
+ * Reserved words that can stand before a command in the same segment: a brace
+ * group, a negation, and the heads of if, loop, and else bodies. Without them
+ * `if true; then cd /x; fi` read `then` as the command and hid the cd.
+ */
+const SHELL_RESERVED_PREFIXES: ReadonlySet<string> = new Set([
+	"{",
+	"!",
+	"if",
+	"then",
+	"elif",
+	"else",
+	"while",
+	"until",
+	"do",
+	"time",
+]);
+
 function commandTokenIndex(segment: ReadonlyArray<string>): number | null {
 	let index = 0;
 	while (index < segment.length) {
 		const token = segment[index];
 		if (token === undefined) return null;
+		if (SHELL_RESERVED_PREFIXES.has(token)) {
+			index += 1;
+			continue;
+		}
 		if (isEnvAssignment(token)) {
 			index += 1;
 			continue;
@@ -1062,8 +1572,9 @@ function normalizePathKey(input: string): string | null {
 	if (isWindowsAbsolutePath(trimmed) && path.sep !== "\\") {
 		return toSlashKey(path.win32.normalize(trimmed));
 	}
+	// Physical, as the kernel resolves `link/..` in a command's path argument.
 	const resolved = path.isAbsolute(trimmed) ? trimmed : path.resolve(trimmed);
-	return toSlashKey(canonicalizeExistingPath(resolved));
+	return toSlashKey(canonicalizeRawPath(trimmed, process.cwd()) ?? canonicalizeExistingPath(resolved));
 }
 
 function wildcardRootKey(input: string): string | null {