@iowarp/clio-coder 0.3.0 → 0.3.2

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

@@ -0,0 +1,993 @@
+import path from "node:path";
+import { artifactDefaultPath } from "../../core/artifact-paths.js";
+import { canonicalizeExistingPath } from "../../core/path-canonical.js";
+import { ToolNames } from "../../core/tool-names.js";
+import { isVerificationScriptName } from "../../core/verification-scripts.js";
+
+export type ProtectedArtifactSource = "validation" | "middleware" | "user" | "session";
+
+export interface ProtectedArtifact {
+	path: string;
+	protectedAt: string;
+	reason: string;
+	validationCommand?: string;
+	validationExitCode?: number;
+	source: ProtectedArtifactSource;
+}
+
+export interface ProtectedArtifactState {
+	artifacts: ProtectedArtifact[];
+}
+
+export type DestructiveCommandOperation =
+	| "rm"
+	| "mv"
+	| "truncate"
+	| "redirect"
+	| "cp"
+	| "git_checkout"
+	| "git_restore"
+	| "git_reset_hard"
+	| "find_delete";
+
+export interface ProtectedArtifactCommandMatch {
+	artifactPath: string;
+	commandPath: string;
+	reason: string;
+}
+
+export type DestructiveCommandClassification =
+	| { kind: "benign"; matches: [] }
+	| {
+			kind: "destructive";
+			operation: DestructiveCommandOperation;
+			matches: ProtectedArtifactCommandMatch[];
+	  };
+
+export type ValidationCommandDetection = { kind: "validation"; matched: string } | { kind: "none" };
+
+/**
+ * Which vocabulary of checking commands a caller wants recognized.
+ *
+ * `finish-contract` is the strict set: commands that assert something about
+ * correctness and fail loudly when it does not hold. It is the default because
+ * the consumers that spend it are gates. The finish contract counts a match as
+ * a validating turn, and the mutation-report validator counts one as the
+ * difference between `pass` and `unmeasured`. A turn whose only command was
+ * `git diff` has validated nothing, so admitting read-verification here would
+ * hand both gates a way to be satisfied by inspection alone.
+ *
+ * `grounding` is the wider set: everything strict plus the read-verification
+ * and ad-hoc shapes agents actually reach for (`git diff`, `node -e`,
+ * `npx vitest`, `tsc --noEmit`). Its consumer, dispatch validation grounding,
+ * spends a match on nothing. An unmatched claim there is reported and never
+ * downgrades a quality label, so the cost of a miss is noise in the receipt
+ * rather than a gate opening. Observed live this session: S3 workers claimed
+ * "git diff verification" and grounded 0/1, and a slice-2 coder verified its
+ * own fix with `node -e "import(...)"`. Both are real work the strict set
+ * cannot name.
+ */
+export type ValidationCommandScope = "finish-contract" | "grounding";
+
+interface NormalizedArtifact {
+	key: string;
+	artifact: ProtectedArtifact;
+}
+
+const COMMAND_SEPARATORS = new Set([";", "&&", "||", "|"]);
+const SHELL_WRAPPERS = new Set(["command", "builtin", "sudo", "doas"]);
+
+/**
+ * Paths a tool call would mutate, derived from the tool's path argument.
+ * Returns at most one path today: write/edit when a path arg is present, and
+ * the artifact writers' defaults. Bash mutation targets are handled
+ * separately through command classification.
+ */
+export function toolMutationPaths(toolName: string, args: Record<string, unknown> | undefined): string[] {
+	if (toolName === ToolNames.Artifact) {
+		return [mutationPathArg(args) ?? artifactDefaultPath(args?.kind)];
+	}
+	if (toolName === ToolNames.Write || toolName === ToolNames.Edit) {
+		const candidate = mutationPathArg(args);
+		return candidate === null ? [] : [candidate];
+	}
+	return [];
+}
+
+/**
+ * Shared protected-artifact decision used by both the orchestrator middleware
+ * guard and mediated worker runtimes. Keeping target extraction and bash
+ * classification in one function prevents a dispatched worker from applying
+ * a weaker interpretation of the same frozen protection state.
+ */
+export function protectedArtifactMutationBlockReason(
+	state: ProtectedArtifactState,
+	toolName: string,
+	args: Record<string, unknown> | undefined,
+): string | null {
+	if (state.artifacts.length === 0) return null;
+	for (const candidate of toolMutationPaths(toolName, args)) {
+		if (isProtectedPath(state, candidate)) {
+			return `protected artifact blocked: ${toolName} would modify protected path ${candidate}`;
+		}
+	}
+	if (toolName !== ToolNames.Bash) return null;
+	const command = typeof args?.command === "string" && args.command.length > 0 ? args.command : null;
+	if (command === null) return null;
+	const classification = classifyDestructiveCommand(command, state.artifacts);
+	if (classification.kind === "benign") return null;
+	const affected = classification.matches.map((match) => match.artifactPath).join(", ");
+	return `protected artifact blocked: ${classification.operation} would affect ${affected}`;
+}
+
+function mutationPathArg(args: Record<string, unknown> | undefined): string | null {
+	if (!args) return null;
+	const candidate = args.path ?? args.file_path ?? args.filePath;
+	return typeof candidate === "string" && candidate.length > 0 ? candidate : null;
+}
+
+export function protectArtifact(state: ProtectedArtifactState, artifact: ProtectedArtifact): ProtectedArtifactState {
+	const artifacts = artifactMap(state.artifacts);
+	const key = normalizePathKey(artifact.path);
+	if (key !== null) artifacts.set(key, cloneArtifact(artifact));
+	return stateFromMap(artifacts);
+}
+
+function isProtectedPath(state: ProtectedArtifactState, artifactPath: string): boolean {
+	const candidate = normalizePathKey(artifactPath);
+	if (candidate === null) return false;
+	for (const artifact of normalizedArtifacts(state.artifacts)) {
+		if (isSameOrDescendant(candidate, artifact.key)) return true;
+	}
+	return false;
+}
+
+function classifyDestructiveCommand(
+	command: string,
+	protectedArtifacts: ReadonlyArray<ProtectedArtifact>,
+): DestructiveCommandClassification {
+	const artifacts = normalizedArtifacts(protectedArtifacts);
+	if (artifacts.length === 0) return { kind: "benign", matches: [] };
+
+	const tokens = tokenizeShellLike(command);
+	for (const segment of splitSegments(tokens)) {
+		const redirect = classifyRedirect(segment, artifacts);
+		if (redirect.kind === "destructive") return redirect;
+
+		const commandIndex = commandTokenIndex(segment);
+		if (commandIndex === null) continue;
+		const executable = basenameToken(segment[commandIndex]);
+		if (executable === "rm") {
+			const result = classifyPathOperation(
+				"rm",
+				"rm can remove protected artifacts",
+				pathArgs(segment, commandIndex),
+				artifacts,
+			);
+			if (result.kind === "destructive") return result;
+			continue;
+		}
+		if (executable === "mv") {
+			const result = classifyPathOperation(
+				"mv",
+				"mv can move or overwrite protected artifacts",
+				pathArgs(segment, commandIndex),
+				artifacts,
+			);
+			if (result.kind === "destructive") return result;
+			continue;
+		}
+		if (executable === "truncate") {
+			const result = classifyPathOperation(
+				"truncate",
+				"truncate can overwrite protected artifacts",
+				pathArgs(segment, commandIndex),
+				artifacts,
+			);
+			if (result.kind === "destructive") return result;
+			continue;
+		}
+		if (executable === "cp") {
+			const args = pathArgs(segment, commandIndex);
+			const destination = args.at(-1);
+			const result = classifyPathOperation(
+				"cp",
+				"cp can overwrite protected artifacts",
+				destination === undefined ? [] : [destination],
+				artifacts,
+			);
+			if (result.kind === "destructive") return result;
+			continue;
+		}
+		if (executable === "git") {
+			const result = classifyGitOperation(segment.slice(commandIndex + 1), artifacts);
+			if (result.kind === "destructive") return result;
+			continue;
+		}
+		if (executable === "find") {
+			const result = classifyFindDelete(segment.slice(commandIndex + 1), artifacts);
+			if (result.kind === "destructive") return result;
+		}
+	}
+
+	return { kind: "benign", matches: [] };
+}
+
+export function detectValidationCommand(
+	command: string,
+	scope: ValidationCommandScope = "finish-contract",
+): ValidationCommandDetection {
+	const tokens = tokenizeShellLike(command);
+	for (const segment of splitSegments(tokens)) {
+		const commandIndex = commandTokenIndex(segment);
+		if (commandIndex === null) continue;
+		const executable = basenameToken(segment[commandIndex]);
+		const args = segment.slice(commandIndex + 1);
+		const matched =
+			validationMatch(executable, args) ?? (scope === "grounding" ? groundingMatch(executable, args) : null);
+		if (matched !== null) return { kind: "validation", matched };
+	}
+	return { kind: "none" };
+}
+
+/**
+ * Returns every path the command would write to: shell redirect targets
+ * (`>`, `>>`), all path arguments to `tee`, `mkdir`, and `touch`, the
+ * destination argument of `cp`, `mv`, and `ln`, and the file operands of an
+ * in-place `sed -i` edit. Standard descriptors like `/dev/null` and fd
+ * references like `&1` are filtered out so callers only see real filesystem
+ * targets.
+ *
+ * Used by the action classifier to escalate bash calls that write to a
+ * system root or out-of-cwd path through the same confirmation gate as the
+ * write tool, and by the finish-contract to decide whether a turn mutated
+ * workspace state. Both consumers read the same primitive, so a write pattern
+ * this recognizes gates and gate-completes consistently. pi-mono executes the
+ * bash command verbatim, so the registry-side check has to happen before the
+ * shell runs.
+ */
+export function extractCommandWriteTargets(command: string): string[] {
+	const targets: string[] = [];
+	for (const segment of expandedSegments(command)) {
+		collectRedirectTargets(segment, targets);
+		collectInvokedWriteTargets(segment, targets);
+		collectInPlaceEditTargets(segment, targets);
+	}
+	return targets.filter(isInterestingWriteTarget);
+}
+
+/** Shells whose `-c` argument is a script this scanner has to read as a command line. */
+const INNER_SHELLS: ReadonlySet<string> = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+
+/** Depth cap for `sh -c 'sh -c "..."'`; three levels is far past anything real. */
+const INNER_SHELL_MAX_DEPTH = 3;
+
+/**
+ * The script a segment hands a shell through `-c`, or null when the segment is
+ * not that shape. The tokenizer keeps a quoted script as one token, so without
+ * this every scanner here is blind one `sh -c` deep: `sh -c 'echo x >
+ * /etc/foo'` exposed no redirect target at all, which is how a recorded drive
+ * got a write past the gate that refused the same redirect written plainly
+ * (REPORT-dispatch-drive-1.md S1). Flag clusters (`-lc`, `-ec`) count, since
+ * the shell reads them the same way.
+ */
+function segmentShellScript(segment: ReadonlyArray<string>): string | null {
+	const commandIndex = commandTokenIndex(segment);
+	if (commandIndex === null) return null;
+	if (!INNER_SHELLS.has(basenameToken(segment[commandIndex]))) return null;
+	for (let index = commandIndex + 1; index < segment.length; index += 1) {
+		const token = segment[index];
+		if (token === undefined) continue;
+		if (token.startsWith("-") && token.length > 1) {
+			if (!token.slice(1).includes("c")) continue;
+			const script = segment[index + 1];
+			return script !== undefined && script.length > 0 ? script : null;
+		}
+		// The first operand of a shell invocation without -c is a script file,
+		// whose contents this scanner cannot see anyway.
+		return null;
+	}
+	return null;
+}
+
+/**
+ * A command's segments, with every `sh -c '<script>'` wrapper followed by the
+ * segments of the script it runs. The wrapper segment itself is kept: a
+ * scanner that reads its operands (`cp`, `tee`) must still see them.
+ */
+function expandedSegments(command: string, depth = 0): string[][] {
+	const segments = splitSegments(tokenizeShellLike(command));
+	if (depth >= INNER_SHELL_MAX_DEPTH) return segments;
+	const out: string[][] = [];
+	for (const segment of segments) {
+		out.push(segment);
+		const script = segmentShellScript(segment);
+		if (script !== null) out.push(...expandedSegments(script, depth + 1));
+	}
+	return out;
+}
+
+/**
+ * The script when the whole command is one `sh -c '<script>'` invocation and
+ * nothing else. The policy engine recognizes such a command by its inner
+ * script rather than treating `sh` as an unrecognized executable.
+ */
+export function inlineShellScript(command: string): string | null {
+	const segments = splitSegments(tokenizeShellLike(command));
+	if (segments.length !== 1) return null;
+	const segment = segments[0];
+	if (segment === undefined) return null;
+	return segmentShellScript(segment);
+}
+
+/**
+ * Returns the directory each `cd`/`pushd` in the command targets. A bare
+ * `cd` (and `cd -`, whose OLDPWD is unset in a fresh shell) is reported as
+ * `~`: it goes to the user's home directory. The action classifier resolves
+ * these against the workspace root, because a `cd` outside the workspace
+ * re-bases every relative path that follows it — the laundering pattern the
+ * recorded escape used (`cd /abs/outside && python3 <<EOF ...` writing
+ * relative files outside the session workspace).
+ */
+export function extractCommandCdTargets(command: string): string[] {
+	const targets: string[] = [];
+	for (const segment of expandedSegments(command)) {
+		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 ?? "~");
+	}
+	return targets;
+}
+
+/**
+ * Returns paths that common shell commands would remove from their current
+ * location. This intentionally covers only deterministic, path-bearing
+ * patterns; broader command admission remains owned by the policy engine.
+ */
+export function extractCommandDeleteTargets(command: string): string[] {
+	const targets: string[] = [];
+	for (const segment of expandedSegments(command)) {
+		const commandIndex = commandTokenIndex(segment);
+		if (commandIndex === null) continue;
+		const executable = basenameToken(segment[commandIndex]);
+		if (executable === "rm") {
+			targets.push(...pathArgs(segment, commandIndex));
+			continue;
+		}
+		if (executable === "mv") {
+			const args = pathArgs(segment, commandIndex);
+			if (args.length >= 2) targets.push(...args.slice(0, -1));
+			continue;
+		}
+		if (executable === "find" && segment.includes("-delete")) {
+			targets.push(...findRoots(segment.slice(commandIndex + 1)));
+		}
+	}
+	return targets.filter(isInterestingWriteTarget);
+}
+
+const STANDARD_DEV_TARGETS = new Set(["/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/zero"]);
+
+function collectRedirectTargets(segment: ReadonlyArray<string>, out: string[]): void {
+	for (let index = 0; index < segment.length - 1; index += 1) {
+		const token = segment[index];
+		if (token !== ">" && token !== ">>") continue;
+		const target = segment[index + 1];
+		if (target !== undefined) out.push(target);
+	}
+}
+
+function collectInvokedWriteTargets(segment: ReadonlyArray<string>, out: string[]): void {
+	const cmdIndex = commandTokenIndex(segment);
+	if (cmdIndex === null) return;
+	const executable = basenameToken(segment[cmdIndex]);
+	if (executable === "tee") {
+		for (const arg of pathArgs(segment, cmdIndex)) out.push(arg);
+		return;
+	}
+	// mkdir and touch create filesystem entries at every path operand. The
+	// recorded workspace escape (`mkdir -p /abs/outside && cd ...` in the
+	// skill-mastery app-idea battery) rode exactly this blind spot: redirects
+	// and tee were classified, directory creation was not.
+	if (executable === "mkdir" || executable === "touch") {
+		for (const arg of pathArgs(segment, cmdIndex)) out.push(arg);
+		return;
+	}
+	if (executable === "ln") {
+		const args = pathArgs(segment, cmdIndex);
+		const destination = args.at(-1);
+		if (args.length >= 2 && destination !== undefined) out.push(destination);
+		return;
+	}
+	if (executable === "cp" || executable === "mv") {
+		const args = pathArgs(segment, cmdIndex);
+		const destination = args.at(-1);
+		if (args.length >= 2 && destination !== undefined) out.push(destination);
+	}
+}
+
+/**
+ * In-place stream-editor writes: `sed -i` (GNU `-iSUFFIX` / `--in-place` and
+ * BSD `-i ''` forms) rewrites its file operands in place, which the redirect and
+ * tee/cp/mv detectors miss. Weak models reach for `sed -i` constantly, so
+ * recognizing it here lets both the classifier and the finish-contract treat it
+ * as the write it is. The sed script operand is dropped (it is not a file), so
+ * an address-form script such as `/pat/d` cannot be mistaken for an out-of-cwd
+ * write target.
+ */
+function collectInPlaceEditTargets(segment: ReadonlyArray<string>, out: string[]): void {
+	const cmdIndex = commandTokenIndex(segment);
+	if (cmdIndex === null) return;
+	if (basenameToken(segment[cmdIndex]) !== "sed") return;
+	if (!hasSedInPlaceFlag(segment, cmdIndex)) return;
+	for (const operand of sedFileOperands(segment, cmdIndex)) out.push(operand);
+}
+
+function hasSedInPlaceFlag(segment: ReadonlyArray<string>, cmdIndex: number): boolean {
+	for (let index = cmdIndex + 1; index < segment.length; index += 1) {
+		const token = segment[index];
+		if (token === undefined) continue;
+		if (COMMAND_SEPARATORS.has(token)) break;
+		if (token === "--") break;
+		if (token === "--in-place" || token.startsWith("--in-place=")) return true;
+		if (token.startsWith("--")) continue;
+		// A short-option cluster carrying `i` (`-i`, `-i.bak`, `-ni`) requests
+		// in-place editing; sed's other short flags (`-n`, `-e`, `-r`, ...) do not.
+		if (token.startsWith("-") && token.length > 1 && token.slice(1).includes("i")) return true;
+	}
+	return false;
+}
+
+/**
+ * File operands of a sed invocation, with the inline script dropped. `-e`/`-f`/
+ * `--expression`/`--file` supply the script explicitly, so when one is present
+ * every bare operand is a file; otherwise the first bare operand is the script.
+ */
+function sedFileOperands(segment: ReadonlyArray<string>, cmdIndex: number): string[] {
+	const operands: string[] = [];
+	let sawScriptFlag = false;
+	let endOfOptions = false;
+	for (let index = cmdIndex + 1; index < segment.length; index += 1) {
+		const token = segment[index];
+		if (token === undefined) continue;
+		if (COMMAND_SEPARATORS.has(token)) break;
+		if (!endOfOptions && token === "--") {
+			endOfOptions = true;
+			continue;
+		}
+		if (!endOfOptions && token.startsWith("-") && token.length > 1) {
+			if (token === "-e" || token === "-f") {
+				sawScriptFlag = true;
+				index += 1;
+				continue;
+			}
+			if (token === "-l") {
+				index += 1;
+				continue;
+			}
+			if (token === "--expression" || token === "--file") {
+				sawScriptFlag = true;
+				index += 1;
+				continue;
+			}
+			if (token.startsWith("--expression=") || token.startsWith("--file=")) {
+				sawScriptFlag = true;
+				continue;
+			}
+			continue;
+		}
+		operands.push(token);
+	}
+	if (!sawScriptFlag && operands.length > 0) operands.shift();
+	return operands;
+}
+
+function isInterestingWriteTarget(target: string): boolean {
+	if (target.length === 0) return false;
+	if (target.startsWith("&")) return false;
+	if (STANDARD_DEV_TARGETS.has(target)) return false;
+	if (target.startsWith("/dev/fd/")) return false;
+	return true;
+}
+
+function classifyRedirect(
+	segment: ReadonlyArray<string>,
+	artifacts: ReadonlyArray<NormalizedArtifact>,
+): DestructiveCommandClassification {
+	for (let index = 0; index < segment.length; index += 1) {
+		if (segment[index] !== ">") continue;
+		const target = segment[index + 1];
+		if (target === undefined) continue;
+		const matches = matchesForPaths([target], artifacts, "target", "redirect can overwrite protected artifacts");
+		if (matches.length > 0) {
+			return {
+				kind: "destructive",
+				operation: "redirect",
+				matches,
+			};
+		}
+	}
+	return { kind: "benign", matches: [] };
+}
+
+function classifyGitOperation(
+	args: ReadonlyArray<string>,
+	artifacts: ReadonlyArray<NormalizedArtifact>,
+): DestructiveCommandClassification {
+	const subcommand = args[0];
+	if (subcommand === "reset" && args.includes("--hard")) {
+		return {
+			kind: "destructive",
+			operation: "git_reset_hard",
+			matches: artifacts.map(({ artifact }) => ({
+				artifactPath: artifact.path,
+				commandPath: ".",
+				reason: "git reset --hard can overwrite protected artifacts",
+			})),
+		};
+	}
+
+	if (subcommand === "checkout" && args.includes("--")) {
+		const paths = args.slice(args.indexOf("--") + 1);
+		const matches = matchesForPaths(paths, artifacts, "intersects", "git checkout -- can overwrite protected artifacts");
+		if (matches.length > 0) {
+			return {
+				kind: "destructive",
+				operation: "git_checkout",
+				matches,
+			};
+		}
+		return { kind: "benign", matches: [] };
+	}
+
+	if (subcommand === "restore") {
+		const matches = matchesForPaths(
+			pathArgs(args.slice(1), -1),
+			artifacts,
+			"intersects",
+			"git restore can overwrite protected artifacts",
+		);
+		if (matches.length > 0) {
+			return {
+				kind: "destructive",
+				operation: "git_restore",
+				matches,
+			};
+		}
+	}
+
+	return { kind: "benign", matches: [] };
+}
+
+function classifyFindDelete(
+	args: ReadonlyArray<string>,
+	artifacts: ReadonlyArray<NormalizedArtifact>,
+): DestructiveCommandClassification {
+	if (!args.includes("-delete")) return { kind: "benign", matches: [] };
+	const roots = findRoots(args);
+	const matches = matchesForPaths(
+		roots.length === 0 ? ["."] : roots,
+		artifacts,
+		"intersects",
+		"find -delete can remove protected artifacts",
+	);
+	if (matches.length > 0) {
+		return {
+			kind: "destructive",
+			operation: "find_delete",
+			matches,
+		};
+	}
+	return { kind: "benign", matches: [] };
+}
+
+function findRoots(args: ReadonlyArray<string>): string[] {
+	const roots: string[] = [];
+	for (const token of args) {
+		if (token === "-delete" || token.startsWith("-") || token === "(" || token === "!" || token === "not") break;
+		if (token === "--") continue;
+		roots.push(token);
+	}
+	return roots.length === 0 ? ["."] : roots;
+}
+
+function classifyPathOperation(
+	operation: DestructiveCommandOperation,
+	reason: string,
+	paths: ReadonlyArray<string>,
+	artifacts: ReadonlyArray<NormalizedArtifact>,
+): DestructiveCommandClassification {
+	const matches = matchesForPaths(paths, artifacts, "intersects", reason);
+	if (matches.length === 0) return { kind: "benign", matches: [] };
+	return {
+		kind: "destructive",
+		operation,
+		matches,
+	};
+}
+
+function matchesForPaths(
+	commandPaths: ReadonlyArray<string>,
+	artifacts: ReadonlyArray<NormalizedArtifact>,
+	mode: "target" | "intersects",
+	reason: string,
+): ProtectedArtifactCommandMatch[] {
+	const matches: ProtectedArtifactCommandMatch[] = [];
+	const seen = new Set<string>();
+	for (const commandPath of commandPaths) {
+		for (const artifact of artifacts) {
+			if (!pathMatchesArtifact(commandPath, artifact.key, mode)) continue;
+			const key = `${artifact.key}\0${commandPath}\0${reason}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			matches.push({
+				artifactPath: artifact.artifact.path,
+				commandPath,
+				reason,
+			});
+		}
+	}
+	matches.sort(compareMatches);
+	return matches;
+}
+
+function pathMatchesArtifact(commandPath: string, artifactKey: string, mode: "target" | "intersects"): boolean {
+	const wildcardRoot = wildcardRootKey(commandPath);
+	if (wildcardRoot !== null) {
+		return isSameOrDescendant(artifactKey, wildcardRoot);
+	}
+	const commandKey = normalizePathKey(commandPath);
+	if (commandKey === null) return false;
+	if (mode === "target") return isSameOrDescendant(commandKey, artifactKey);
+	return isSameOrDescendant(commandKey, artifactKey) || isSameOrDescendant(artifactKey, commandKey);
+}
+
+function validationMatch(executable: string, args: ReadonlyArray<string>): string | null {
+	if (executable === "npm") {
+		if (args[0] === "test") return "npm test";
+		const script = args[0] === "run" && typeof args[1] === "string" ? args[1] : null;
+		if (script !== null && isVerificationScriptName(script)) return `npm run ${script}`;
+	}
+	if (executable === "pytest") return "pytest";
+	if (isPythonExecutable(executable) && moduleArg(args) === "pytest") return "python -m pytest";
+	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 === "ninja" && args[0] === "test") return "ninja test";
+	if (executable === "mvn" && args[0] === "test") return "mvn test";
+	if ((executable === "gradle" || executable === "gradlew") && args[0] === "test") return "gradle test";
+	return null;
+}
+
+/**
+ * The `grounding`-only half of the vocabulary. Every rule here is an exact
+ * leading-command match on a canonicalized executable, never a substring guess,
+ * so a command that merely mentions `tsc` or `diff` in an argument stays
+ * unrecognized. Failing to match is the safe direction for this scope.
+ */
+function groundingMatch(executable: string, args: ReadonlyArray<string>): string | null {
+	if (executable === "git") {
+		if (args[0] === "diff") return "git diff";
+		if (args[0] === "status") return "git status";
+		return null;
+	}
+	if (executable === "node") {
+		if (args.includes("--test")) return "node --test";
+		if (args.includes("-e") || args.includes("--eval")) return "node -e";
+		return null;
+	}
+	if (executable === "tsc") return typescriptCheckMatch(args);
+	if (executable === "npx") {
+		const inner = npxInvocation(args);
+		return inner === null ? null : npxRunnerMatch(inner.executable, inner.args);
+	}
+	return null;
+}
+
+/** Test runners recognized behind `npx`, where the runner name is the whole claim. */
+const NPX_TEST_RUNNERS: ReadonlySet<string> = new Set(["vitest", "jest", "mocha"]);
+
+function npxRunnerMatch(executable: string, args: ReadonlyArray<string>): string | null {
+	if (NPX_TEST_RUNNERS.has(executable)) return `npx ${executable}`;
+	if (executable === "tsx" && args.includes("--test")) return "npx tsx --test";
+	if (executable === "tsc") return typescriptCheckMatch(args);
+	return null;
+}
+
+/** `tsc --noEmit` is a typecheck; a bare `tsc` is a build that also typechecks. */
+function typescriptCheckMatch(args: ReadonlyArray<string>): string {
+	return args.some((arg) => arg.toLowerCase() === "--noemit") ? "tsc --noEmit" : "tsc";
+}
+
+/**
+ * The command `npx` would run, with npx's own flags consumed. Flags that take a
+ * separate value (`-p react`, `--package=x` is self-contained) must not be
+ * mistaken for the command name.
+ */
+function npxInvocation(args: ReadonlyArray<string>): { executable: string; args: ReadonlyArray<string> } | null {
+	const VALUE_FLAGS = new Set(["-p", "--package", "-c", "--call", "--shell"]);
+	let index = 0;
+	while (index < args.length) {
+		const token = args[index];
+		if (token === undefined) return null;
+		if (VALUE_FLAGS.has(token)) {
+			index += 2;
+			continue;
+		}
+		if (token.startsWith("-")) {
+			index += 1;
+			continue;
+		}
+		return { executable: basenameToken(token), args: args.slice(index + 1) };
+	}
+	return null;
+}
+
+function moduleArg(args: ReadonlyArray<string>): string | null {
+	for (let index = 0; index < args.length - 1; index += 1) {
+		if (args[index] === "-m") return args[index + 1] ?? null;
+	}
+	return null;
+}
+
+function isPythonExecutable(executable: string): boolean {
+	return executable === "python" || executable === "python3" || /^python3\.\d+$/.test(executable);
+}
+
+function pathArgs(segment: ReadonlyArray<string>, commandIndex: number): string[] {
+	const args: string[] = [];
+	let endOfOptions = false;
+	for (let index = commandIndex + 1; index < segment.length; index += 1) {
+		const token = segment[index];
+		if (token === undefined) continue;
+		if (COMMAND_SEPARATORS.has(token)) break;
+		if (!endOfOptions && token === "--") {
+			endOfOptions = true;
+			continue;
+		}
+		if (!endOfOptions && token.startsWith("-")) continue;
+		if (token === ">" || token === ">>" || token === "<" || token === "<<") {
+			index += 1;
+			continue;
+		}
+		args.push(token);
+	}
+	return args;
+}
+
+export function tokenizeShellLike(command: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | null = null;
+
+	const pushCurrent = (): void => {
+		if (current.length === 0) return;
+		tokens.push(current);
+		current = "";
+	};
+
+	for (let index = 0; index < command.length; index += 1) {
+		const char = command[index];
+		if (char === undefined) continue;
+		if (quote !== null) {
+			if (char === quote) {
+				quote = null;
+				continue;
+			}
+			if (quote === '"' && char === "\\" && index + 1 < command.length) {
+				index += 1;
+				current += command[index] ?? "";
+				continue;
+			}
+			current += char;
+			continue;
+		}
+
+		if (char === "'" || char === '"') {
+			quote = char;
+			continue;
+		}
+		if (char === "\\" && index + 1 < command.length) {
+			index += 1;
+			current += command[index] ?? "";
+			continue;
+		}
+		if (/\s/.test(char)) {
+			pushCurrent();
+			if (char === "\n") tokens.push(";");
+			continue;
+		}
+		if (char === ";") {
+			pushCurrent();
+			tokens.push(";");
+			continue;
+		}
+		if (char === "&" && command[index + 1] === "&") {
+			pushCurrent();
+			tokens.push("&&");
+			index += 1;
+			continue;
+		}
+		if (char === "|") {
+			pushCurrent();
+			if (command[index + 1] === "|") {
+				tokens.push("||");
+				index += 1;
+			} else {
+				tokens.push("|");
+			}
+			continue;
+		}
+		if (char === ">") {
+			pushCurrent();
+			if (command[index + 1] === ">") {
+				tokens.push(">>");
+				index += 1;
+			} else {
+				tokens.push(">");
+			}
+			continue;
+		}
+		if (char === "<") {
+			pushCurrent();
+			if (command[index + 1] === "<") {
+				tokens.push("<<");
+				index += 1;
+			} else {
+				tokens.push("<");
+			}
+			continue;
+		}
+		current += char;
+	}
+	pushCurrent();
+	return tokens;
+}
+
+function splitSegments(tokens: ReadonlyArray<string>): string[][] {
+	const segments: string[][] = [];
+	let current: string[] = [];
+	for (const token of tokens) {
+		if (COMMAND_SEPARATORS.has(token)) {
+			if (current.length > 0) segments.push(current);
+			current = [];
+			continue;
+		}
+		current.push(token);
+	}
+	if (current.length > 0) segments.push(current);
+	return segments;
+}
+
+function commandTokenIndex(segment: ReadonlyArray<string>): number | null {
+	let index = 0;
+	while (index < segment.length) {
+		const token = segment[index];
+		if (token === undefined) return null;
+		if (isEnvAssignment(token)) {
+			index += 1;
+			continue;
+		}
+		if (token === "env") {
+			index += 1;
+			while (
+				index < segment.length &&
+				(segment[index]?.startsWith("-") === true || isEnvAssignment(segment[index] ?? ""))
+			) {
+				index += 1;
+			}
+			continue;
+		}
+		if (SHELL_WRAPPERS.has(token)) {
+			index += 1;
+			while (index < segment.length && segment[index]?.startsWith("-") === true) index += 1;
+			continue;
+		}
+		return index;
+	}
+	return null;
+}
+
+function isEnvAssignment(token: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
+}
+
+function basenameToken(token: string | undefined): string {
+	if (token === undefined) return "";
+	const normalized = token.replace(/\\/g, "/");
+	const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+	return basename.toLowerCase();
+}
+
+function artifactMap(artifacts: ReadonlyArray<ProtectedArtifact>): Map<string, ProtectedArtifact> {
+	const out = new Map<string, ProtectedArtifact>();
+	for (const artifact of artifacts) {
+		const key = normalizePathKey(artifact.path);
+		if (key !== null) out.set(key, cloneArtifact(artifact));
+	}
+	return out;
+}
+
+function stateFromMap(artifacts: ReadonlyMap<string, ProtectedArtifact>): ProtectedArtifactState {
+	return {
+		artifacts: Array.from(artifacts.entries())
+			.sort(([left], [right]) => compareStrings(left, right))
+			.map(([, artifact]) => cloneArtifact(artifact)),
+	};
+}
+
+function normalizedArtifacts(artifacts: ReadonlyArray<ProtectedArtifact>): NormalizedArtifact[] {
+	const out = Array.from(artifactMap(artifacts).entries()).map(([key, artifact]) => ({ key, artifact }));
+	out.sort((left, right) => compareStrings(left.key, right.key));
+	return out;
+}
+
+function cloneArtifact(artifact: ProtectedArtifact): ProtectedArtifact {
+	const cloned: ProtectedArtifact = {
+		path: artifact.path,
+		protectedAt: artifact.protectedAt,
+		reason: artifact.reason,
+		source: artifact.source,
+	};
+	if (artifact.validationCommand !== undefined) cloned.validationCommand = artifact.validationCommand;
+	if (artifact.validationExitCode !== undefined) cloned.validationExitCode = artifact.validationExitCode;
+	return cloned;
+}
+
+function normalizePathKey(input: string): string | null {
+	const trimmed = input.trim();
+	if (trimmed.length === 0) return null;
+	if (isWindowsAbsolutePath(trimmed) && path.sep !== "\\") {
+		return toSlashKey(path.win32.normalize(trimmed));
+	}
+	const resolved = path.isAbsolute(trimmed) ? trimmed : path.resolve(trimmed);
+	return toSlashKey(canonicalizeExistingPath(resolved));
+}
+
+function wildcardRootKey(input: string): string | null {
+	const normalizedInput = toSlashKey(input.trim());
+	const firstWildcard = firstWildcardIndex(normalizedInput);
+	if (firstWildcard === null) return null;
+	const prefix = normalizedInput.slice(0, firstWildcard);
+	const slash = prefix.lastIndexOf("/");
+	const root = slash >= 0 ? prefix.slice(0, slash + 1) : ".";
+	return normalizePathKey(root);
+}
+
+function firstWildcardIndex(input: string): number | null {
+	const indexes = ["*", "?", "["].map((char) => input.indexOf(char)).filter((index) => index >= 0);
+	if (indexes.length === 0) return null;
+	return Math.min(...indexes);
+}
+
+function isWindowsAbsolutePath(input: string): boolean {
+	return /^[A-Za-z]:[\\/]/.test(input);
+}
+
+function toSlashKey(input: string): string {
+	return input.replace(/\\/g, "/");
+}
+
+function isSameOrDescendant(candidate: string, parent: string): boolean {
+	if (candidate === parent) return true;
+	const relative = path.posix.relative(parent, candidate);
+	return relative !== "" && !relative.startsWith("..") && !path.posix.isAbsolute(relative);
+}
+
+function compareMatches(left: ProtectedArtifactCommandMatch, right: ProtectedArtifactCommandMatch): number {
+	return (
+		compareStrings(left.artifactPath, right.artifactPath) ||
+		compareStrings(left.commandPath, right.commandPath) ||
+		compareStrings(left.reason, right.reason)
+	);
+}
+
+function compareStrings(left: string, right: string): number {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}