@code-yeongyu/senpi-codemode 2026.10.27-2 → 2026.10.30-2

package/src/kernels/js/inline-worker-entry.js

@@ -1,23 +1 @@
-import { parentPort, workerData } from "node:worker_threads";
-import { createWorkerCore } from "./worker-core.js";
-
-if (!parentPort) throw new Error("JS kernel inline fallback worker missing parentPort");
-
-const transport = {
-	send(message) {
-		parentPort.postMessage(message);
-	},
-	onMessage(handler) {
-		parentPort.on("message", handler);
-		return () => parentPort.off("message", handler);
-	},
-	close() {
-		parentPort.close();
-		setTimeout(() => process.exit(0), 0);
-	},
-};
-
-createWorkerCore(transport, {
-	cwd: workerData.cwd,
-	parallelPoolWidth: workerData.parallelPoolWidth,
-});
+import "./interpose.js";

package/src/kernels/js/inline-worker.ts

@@ -4,6 +4,7 @@ import type { MessagePort } from "node:worker_threads";
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import type { JavaScriptKernelMode } from "./kernel-contract.ts";
+import type { KernelPermissionHost } from "./permission-host.ts";
 import { spawnNodeWorker } from "./worker-host.ts";
 
 export interface JavaScriptInlineWorkerEntryUrlOptions extends CodemodeRuntimeAssetEnvironment {
@@ -27,6 +28,10 @@ export interface WorkerLike {
 	terminate(): Promise<void>;
 }
 
-export function createInlineWorker(cwd: string, parallelPoolWidth: number): WorkerLike {
-	return spawnNodeWorker(resolveInlineWorkerEntryUrl(), cwd, parallelPoolWidth, "inline");
+export function createInlineWorker(
+	cwd: string,
+	parallelPoolWidth: number,
+	permissions?: KernelPermissionHost,
+): WorkerLike {
+	return spawnNodeWorker(resolveInlineWorkerEntryUrl(), cwd, parallelPoolWidth, "inline", permissions);
 }

package/src/kernels/js/interpose-bun.js

@@ -0,0 +1,220 @@
+import { checkPath, executionPath, replaceMethod } from "./interpose-paths.js";
+
+const READERS = ["text", "json", "bytes", "arrayBuffer", "stream", "formData", "image"];
+const ignore = () => {};
+const WRITERS = ["write", "delete", "unlink"];
+
+export function installBunPermissions(check, resources) {
+	const bun = globalThis.Bun;
+	const stand = new WeakMap();
+	const unwrap = (value) => stand.get(value) ?? value;
+	const files = { source: () => {}, destination: () => {}, handle: () => false };
+	if (typeof bun?.file === "function") {
+		const originalFile = bun.file;
+		const proto = Object.getPrototypeOf(originalFile(new URL(import.meta.url)));
+		// Captured before any cell runs, so a per-instance "name" cannot redirect a decision away
+		// from the path the runtime will actually open.
+		const nativePath = Object.getOwnPropertyDescriptor(proto, "name").get;
+		const nativeStat = proto.stat;
+		// A memory Blob carries no file and answers nothing; anything the native stat does answer for is
+		// backed by a file this decision cannot name, which is what makes it undecidable rather than safe.
+		const fileBacked = (value) => {
+			let pending;
+			try {
+				pending = nativeStat.call(value);
+			} catch {
+				return true;
+			}
+			if (pending === undefined) return false;
+			if (typeof pending?.then === "function") pending.then(ignore, ignore);
+			return true;
+		};
+		const pathOf = (value) => {
+			try {
+				return nativePath.call(unwrap(value));
+			} catch {
+				return undefined;
+			}
+		};
+		const granted = (value, mode) => {
+			const grant = resources.path(value);
+			if (grant === undefined) return false;
+			resources.use(typeof grant === "number" ? grant : value, mode);
+			return true;
+		};
+		const handle = (value, mode) => {
+			if (typeof value === "number") return granted(value, mode);
+			if (value === null || typeof value !== "object") return false;
+			const path = pathOf(value);
+			if (typeof path === "string") {
+				checkPath(check, mode, path);
+				return true;
+			}
+			if (granted(unwrap(value), mode)) return true;
+			if (!(unwrap(value) instanceof Blob)) return false;
+			// A file-backed handle whose path cannot be read cannot be decided, so it never receives bytes
+			// and never hands any out either.
+			if (mode === "write") check(() => ({ unsupported: true }));
+			if (mode === "read") check(() => (fileBacked(unwrap(value)) ? { unsupported: true } : { granted: true })); // sink:undecidable-read
+			return true;
+		};
+		const source = (value) => {
+			for (const part of Array.isArray(value) ? value : [value]) handle(part, "read");
+		};
+		const destination = (value) => {
+			if (typeof value === "number") resources.use(value, "write");
+			else if (!handle(value, "write")) checkPath(check, "write", value);
+		};
+		const native = (value) => (Array.isArray(value) ? value.map(unwrap) : unwrap(value));
+		Object.assign(files, { source, destination, handle });
+		const standIn = (file) => {
+			// Metadata answers for the same file the content was refused for, so it is decided the same way.
+			const metadata = () => checkPath(check, "read", nativePath.call(file));
+			const surface = {
+				exists: (...args) => {
+					metadata(); // sink:standin-metadata
+					return proto.exists.apply(file, args);
+				},
+				stat: (...args) => {
+					metadata(); // sink:standin-metadata
+					return nativeStat.apply(file, args);
+				},
+				slice: (...args) => standIn(proto.slice.apply(file, args)),
+			};
+			// The native accessors live on the prototype, so these stay off the own enumerable surface too:
+			// a structured-clone walk still fails on the missing internal slots rather than on a check.
+			Object.defineProperties(surface, {
+				name: { get: () => nativePath.call(file), configurable: true },
+				type: { get: () => file.type, configurable: true },
+				size: {
+					get: () => {
+						metadata(); // sink:standin-metadata
+						return file.size;
+					},
+					configurable: true,
+				},
+				lastModified: {
+					get: () => {
+						metadata(); // sink:standin-metadata
+						return file.lastModified;
+					},
+					configurable: true,
+				},
+			});
+			for (const name of [...READERS, ...WRITERS, "writer"]) {
+				surface[name] = (...args) => proto[name].apply(file, args);
+			}
+			stand.set(surface, file);
+			return surface;
+		};
+		for (const name of READERS) {
+			replaceMethod(proto, name, (original) => function (...args) {
+				source(this); // sink:bunfile-read
+				return original.apply(unwrap(this), args);
+			});
+		}
+		for (const name of WRITERS) {
+			replaceMethod(proto, name, (original) => function (...args) {
+				destination(this); // sink:bunfile-write
+				if (name === "write") source(args[0]); // sink:bunfile-write-parts
+				return original.apply(unwrap(this), name === "write" ? [native(args[0]), ...args.slice(1)] : args);
+			});
+		}
+		replaceMethod(proto, "writer", (original) => function (...args) {
+			destination(this); // sink:bunfile-writer
+			const writer = original.apply(unwrap(this), args);
+			resources.record(writer, pathOf(this), ["write"]);
+			for (const name of ["write", "flush", "end"]) {
+				replaceMethod(writer, name, (fn) => function (...parameters) {
+					resources.use(this, "write");
+					return fn.apply(this, parameters);
+				});
+			}
+			return writer;
+		});
+		bun.file = function (path, ...args) {
+			const file = originalFile.call(this, executionPath(path), ...args);
+			if (typeof path === "number") return resources.record(file, path, ["read", "write"]);
+			try {
+				checkPath(check, "read", path); // sink:bun-file-mint
+			} catch (error) {
+				if (error?.code !== "cell_permission_denied") throw error;
+				// A denied path yields a stand-in with no internal slots, so every native consumer
+				// of a file handle refuses it instead of reading the file behind our back.
+				return standIn(file);
+			}
+			return file;
+		};
+		replaceMethod(bun, "write", (original) => function (target, data, ...args) {
+			destination(target); // sink:bun-write-destination
+			source(data); // sink:bun-write-parts
+			return original.call(this, executionPath(unwrap(target)), native(data), ...args);
+		});
+		// A route value may be a per-method map ({'/f':{GET: handle}}), which Bun reads the handle out of
+		// exactly like the flat form, so every nested value is decided too.
+		const nestedRoutes = (value, depth, seen) => {
+			if (value === null || typeof value !== "object" || depth === 0 || seen.has(value)) return;
+			if (unwrap(value) instanceof Blob) return;
+			seen.add(value);
+			for (const inner of Object.values(value)) {
+				source(inner);
+				nestedRoutes(inner, depth - 1, seen);
+			}
+		};
+		replaceMethod(bun, "serve", (original) => function (options, ...args) {
+			for (const map of [options?.routes, options?.static]) {
+				for (const value of map === null || typeof map !== "object" ? [] : Object.values(map)) {
+					source(value); // sink:bun-serve
+					nestedRoutes(value, 3, new Set()); // sink:bun-serve-nested
+				}
+			}
+			return original.call(this, options, ...args);
+		});
+		const buffer = process.getBuiltinModule("node:buffer");
+		for (const name of ["Blob", "File", "Response", "Request"]) {
+			const original = globalThis[name];
+			const guarded = new Proxy(original, {
+				construct(target, args, newTarget) {
+					if (name === "Blob" || name === "File") source(args[0]);
+					else source(name === "Response" ? args[0] : args[1]?.body);
+					return Reflect.construct(target, args, newTarget);
+				},
+			});
+			globalThis[name] = guarded;
+			if (buffer[name] === original) buffer[name] = guarded;
+			if (original.prototype.constructor === original) {
+				Object.defineProperty(original.prototype, "constructor", { value: guarded });
+			}
+		}
+		for (const name of ["append", "set"]) {
+			replaceMethod(FormData.prototype, name, (original) => function (key, value, ...args) {
+				source(value);
+				return original.call(this, key, value, ...args);
+			});
+		}
+	}
+	if (bun?.Glob) {
+		for (const name of ["scan", "scanSync"]) {
+			replaceMethod(bun.Glob.prototype, name, (original) => function (options) {
+				const cwd = typeof options === "string" ? options : (options?.cwd ?? process.cwd());
+				checkPath(check, "ls", cwd);
+				return original.call(
+					this,
+					typeof options === "string" ? executionPath(cwd) : { ...options, cwd: executionPath(cwd) },
+				);
+			});
+		}
+	}
+	replaceMethod(bun, "mmap", (original) => function (path, options) {
+		check(() => ({ granted: true, unsupported: options?.shared !== false }));
+		checkPath(check, "read", path);
+		return original.call(this, executionPath(path), options);
+	});
+	replaceMethod(globalThis, "fetch", (original) => function (input, ...args) {
+		const href = input instanceof Request ? input.url : String(input);
+		if (href.startsWith("file:")) checkPath(check, "read", new URL(href));
+		files.source(args[0]?.body);
+		return original.call(this, input, ...args);
+	});
+	return files;
+}

package/src/kernels/js/interpose-capabilities.js

@@ -0,0 +1,29 @@
+import { replaceMethod } from "./interpose-paths.js";
+
+export function installCapabilityPermissions(check) {
+	const refuse = () => check(() => ({ unsupported: true }));
+	for (const name of ["binding", "_linkedBinding", "dlopen"]) {
+		replaceMethod(process, name, (original) => function (...args) {
+			refuse();
+			return original.apply(this, args);
+		});
+	}
+	if (globalThis.Bun) {
+		const original = globalThis.Bun.plugin;
+		Object.defineProperty(globalThis, Symbol.for("senpi.kernel.permissionBunPlugin"), { value: function (...args) {
+			refuse();
+			return original(...args);
+		} });
+	}
+	const module = process.getBuiltinModule("node:module");
+	replaceMethod(module, "register", (original) => function (...args) {
+		refuse();
+		return original.apply(this, args);
+	});
+	let load = module._load;
+	Object.defineProperty(module, "_load", {
+		configurable: true, enumerable: true,
+		get: () => load,
+		set(value) { refuse(); load = value; },
+	});
+}

package/src/kernels/js/interpose-code.js

@@ -0,0 +1,8 @@
+export function createCodePermissionGuard(check) {
+	const scan = (source) => check(() => {
+		const prepared = source?.startsWith("/*senpi:prepared-cell*/")
+			? JSON.parse(source.slice("/*senpi:prepared-cell*/".length)) : undefined;
+		return { granted: true, unsupported: prepared?.dynamicCodeCapability === true };
+	});
+	return { scan };
+}

package/src/kernels/js/interpose-fs.js

@@ -0,0 +1,124 @@
+import { checkPath, executionPath, replaceMethod } from "./interpose-paths.js";
+import { createResourceTable } from "./interpose-resources.js";
+
+export const FS_PERMISSION_PATHS = new Set([
+	"writeFile", "appendFile", "truncate", "mkdir", "mkdtemp", "rm", "rmdir", "unlink",
+	"symlink", "chmod", "chown", "lchmod", "lchown", "utimes", "lutimes", "rename", "link", "copyFile", "cp",
+	"readFile", "readlink", "realpath", "readdir", "opendir", "open", "openAsBlob",
+	"createReadStream", "createWriteStream",
+]);
+
+export function installFilesystemPermissions(check) {
+	const fs = process.getBuiltinModule("node:fs");
+	const resources = createResourceTable(check);
+	const promises = [...new Set([fs.promises, process.getBuiltinModule("node:fs/promises")])];
+	const decisions = {
+		writeFile: [[0, "write"]], appendFile: [[0, "write"]], truncate: [[0, "write"]],
+		mkdir: [[0, "write"]], mkdtemp: [[0, "write"]], rm: [[0, "write"]], rmdir: [[0, "write"]],
+		unlink: [[0, "write"]], symlink: [[1, "write"]], chmod: [[0, "write"]], chown: [[0, "write"]],
+		lchmod: [[0, "write"]], lchown: [[0, "write"]],
+		utimes: [[0, "write"]], lutimes: [[0, "write"]], rename: [[0, "write"], [1, "write"]],
+		link: [[0, "write"], [1, "write"]], copyFile: [[0, "read"], [1, "write"]], cp: [[0, "read"], [1, "write"]],
+		readFile: [[0, "read"]], readlink: [[0, "read"]], realpath: [[0, "read"]],
+		readdir: [[0, "ls"]], opendir: [[0, "ls"]], openAsBlob: [[0, "read"]],
+	};
+	const guard = (original, entries) => function (...args) {
+		const actual = [...args];
+		for (const [index, tool] of entries) {
+			const value = args[index];
+			if (typeof value === "number" || (value !== null && typeof value === "object" && typeof value.fd === "number")) {
+				resources.use(value, tool === "write" ? "write" : "read");
+			} else {
+				checkPath(check, tool, value);
+				actual[index] = executionPath(value);
+			}
+		}
+		return original.apply(this, actual);
+	};
+	for (const [name, entries] of Object.entries(decisions)) {
+		replaceMethod(fs, name, (original) => guard(original, entries));
+		replaceMethod(fs, `${name}Sync`, (original) => guard(original, entries));
+		for (const owner of promises) replaceMethod(owner, name, (original) => guard(original, entries));
+	}
+	replaceMethod(fs.realpath, "native", (original) => guard(original, [[0, "read"]]));
+	replaceMethod(fs.realpathSync, "native", (original) => guard(original, [[0, "read"]]));
+	for (const owner of [fs, ...promises]) {
+		for (const name of ["glob", "globSync"]) replaceMethod(owner, name, (original) => function (pattern, ...args) {
+			const options = args[0];
+			const cwd = options && typeof options === "object" ? options.cwd ?? process.cwd() : process.cwd();
+			checkPath(check, "ls", cwd);
+			const effective = options && typeof options === "object" ? { ...options, cwd: executionPath(cwd) } : { cwd: process.cwd() };
+			return typeof options === "function"
+				? original.call(this, pattern, effective, ...args)
+				: original.call(this, pattern, effective, ...args.slice(1));
+		});
+	}
+	replaceMethod(fs, "openSync", (original) => function (file, flags, ...args) {
+		const modes = resources.open(file, flags);
+		return resources.record(original.call(this, executionPath(file), flags, ...args), file, modes);
+	});
+	replaceMethod(fs, "open", (original) => function (file, flags, ...args) {
+		if (typeof flags === "function") { args = [flags]; flags = undefined; }
+		const modes = resources.open(file, flags);
+		const callback = args.at(-1);
+		if (typeof callback !== "function") return original.call(this, executionPath(file), flags, ...args);
+		return original.call(this, executionPath(file), flags, ...args.slice(0, -1), (error, fd) => {
+			if (!error) resources.record(fd, file, modes);
+			callback(error, fd);
+		});
+	});
+	for (const owner of promises) replaceMethod(owner, "open", (original) => function (file, flags, ...args) {
+		const modes = resources.open(file, flags);
+		return original.call(this, executionPath(file), flags, ...args).then((handle) => resources.handle(handle, file, modes));
+	});
+	for (const [mode, names] of [
+		["read", ["read", "readv"]],
+		["write", ["write", "writev", "ftruncate", "fchmod", "fchown", "futimes", "fsync", "fdatasync"]],
+	]) {
+		for (const name of names) {
+			for (const key of [name, `${name}Sync`]) replaceMethod(fs, key, (original) => function (fd, ...args) {
+				resources.use(fd, mode);
+				return original.call(this, fd, ...args);
+			});
+		}
+	}
+	replaceMethod(fs, "closeSync", (original) => function (fd, ...args) {
+		resources.use(fd);
+		const result = original.call(this, fd, ...args);
+		resources.forget(fd);
+		return result;
+	});
+	replaceMethod(fs, "close", (original) => function (fd, callback) {
+		resources.use(fd);
+		return original.call(this, fd, (error) => { if (!error) resources.forget(fd); callback(error); });
+	});
+	for (const [name, mode] of [["createReadStream", "read"], ["createWriteStream", "write"]]) {
+		replaceMethod(fs, name, (original) => function (file, options) {
+			const fd = options?.fd;
+			if (fd != null) resources.use(fd, mode);
+			else checkPath(check, mode, file);
+			const stream = original.call(this, executionPath(file), options);
+			resources.record(stream, file, [mode]);
+			stream.once("open", (descriptor) => resources.record(descriptor, file, [mode]));
+			const methods = mode === "write" ? ["write", "end"] : ["read"];
+			for (const method of methods) replaceMethod(stream, method, (fn) => function (...args) {
+				resources.use(stream, mode);
+				return fn.apply(this, args);
+			});
+			return stream;
+		});
+	}
+	const protectBlob = (blob, file) => {
+		resources.record(blob, file, ["read"]);
+		for (const name of ["text", "bytes", "arrayBuffer", "stream", "slice"]) replaceMethod(blob, name, (fn) => function (...params) {
+			resources.use(this, "read");
+			const value = fn.apply(this, params);
+			return name === "slice" ? protectBlob(value, file) : value;
+		});
+		return blob;
+	};
+	replaceMethod(fs, "openAsBlob", (original) => function (file, ...args) {
+		return original.call(this, file, ...args).then((blob) => protectBlob(blob, file));
+	});
+	return resources;
+}

package/src/kernels/js/interpose-modules.js

@@ -0,0 +1,107 @@
+import { checkPath, requestedPath } from "./interpose-paths.js";
+
+const { dirname, isAbsolute, resolve } = process.getBuiltinModule("node:path");
+const { fileURLToPath } = process.getBuiltinModule("node:url");
+
+export function installModulePermissions(check, userWorker = false) {
+	const module = process.getBuiltinModule("node:module");
+	const nativeRequire = module.createRequire(import.meta.url);
+	const resolveSync = globalThis.Bun?.resolveSync;
+	let sealed = false;
+	// Resolving a specifier re-enters this hook, because the engine resolver is itself observed. That
+	// re-entry is one import still being decided, not another import, so it must not ask again.
+	let resolving = false;
+	// A user worker's own script reaches its own workerData and parentPort through this module, which
+	// #4387 keeps transparent, so only the cell context treats the module itself as a capability.
+	const forbidden = userWorker
+		? /^(?:bun:ffi|(?:node:)?vm)$/u
+		: /^(?:bun:ffi|(?:node:)?(?:vm|worker_threads))$/u;
+	const workerThreads = /^(?:node:)?worker_threads$/u;
+	// A cell already owns these as globals, so handing them back over require grants nothing, while
+	// Worker, parentPort and workerData stay out of reach: the raw Worker would spawn an uninterposed
+	// one. Only require can substitute a namespace, so import and getBuiltinModule stay refused.
+	const portPrimitives = () =>
+		Object.freeze(
+			Object.fromEntries(
+				["MessageChannel", "MessagePort", "BroadcastChannel"]
+					.filter((name) => name in globalThis)
+					.map((name) => [name, globalThis[name]]),
+			),
+		);
+	const pathLike = (name) => name.startsWith(".") || isAbsolute(name) || name.startsWith("file:");
+	const guard = (source, importer) => {
+		const specifier = String(source);
+		if (!sealed || resolving) return;
+		if (forbidden.test(specifier) || specifier.endsWith(".node")) check(() => ({ unsupported: true }));
+		if (!pathLike(specifier)) return;
+		const parent = importer?.startsWith("file:") ? fileURLToPath(importer) : importer;
+		const base = parent ? dirname(parent) : process.cwd();
+		const candidate = specifier.startsWith("file:") ? fileURLToPath(specifier) : specifier;
+		let target;
+		resolving = true;
+		try {
+			target = resolveSync ? resolveSync(candidate, base) : nativeRequire.resolve(resolve(base, candidate));
+		} catch {
+			target = isAbsolute(candidate) ? candidate : resolve(base, candidate);
+		} finally {
+			resolving = false;
+		}
+		checkPath(check, "read", target);
+	};
+	// Only resolution is observed: Bun owns every loader and import attribute.
+	if (globalThis.Bun?.plugin) {
+		Bun.plugin({
+			name: "senpi-cell-permissions",
+			setup(build) {
+				build.onResolve({ filter: /.*/u }, (args) => { guard(args.path, args.importer); });
+			},
+		});
+	}
+	// The decision comes first. A cell nothing is enforced against sees the engine's own module, so
+	// no-rules behaviour is unchanged and matches what import() returns; only a refusal is answered
+	// with the port primitives the cell already owns as globals.
+	const requireGuard = (specifier, importer) => {
+		if (!sealed || !workerThreads.test(String(specifier))) {
+			guard(specifier, importer);
+			return undefined;
+		}
+		try {
+			guard(specifier, importer);
+		} catch (error) {
+			if (error?.code !== "cell_permission_denied") throw error;
+			return portPrimitives();
+		}
+		return undefined;
+	};
+	const originalRequire = module.prototype.require;
+	module.prototype.require = function (specifier) {
+		const substitute = requireGuard(specifier, this.filename);
+		if (substitute) return substitute;
+		if (specifier === "bun" && globalThis.Bun) return globalThis[Symbol.for("senpi.kernel.bun")] ?? globalThis.Bun;
+		return originalRequire.call(this, specifier);
+	};
+	const originalCreateRequire = module.createRequire;
+	module.createRequire = function (...args) {
+		const require = originalCreateRequire.apply(this, args);
+		const guarded = function (specifier) {
+			const substitute = requireGuard(specifier, requestedPath(args[0]) ?? String(args[0]));
+			if (substitute) return substitute;
+			if (specifier === "bun" && globalThis.Bun) return globalThis[Symbol.for("senpi.kernel.bun")] ?? globalThis.Bun;
+			return require(specifier);
+		};
+		Object.assign(guarded, require);
+		guarded.cache = new Proxy(require.cache, {
+			set(target, name, value) { check(() => ({ unsupported: true })); return Reflect.set(target, name, value); },
+			deleteProperty(target, name) { check(() => ({ unsupported: true })); return Reflect.deleteProperty(target, name); },
+			defineProperty(target, name, descriptor) { check(() => ({ unsupported: true })); return Reflect.defineProperty(target, name, descriptor); },
+		});
+		return guarded;
+	};
+	const getBuiltin = process.getBuiltinModule;
+	process.getBuiltinModule = function (name) {
+		if (sealed && forbidden.test(name)) check(() => ({ unsupported: true }));
+		return getBuiltin.call(this, name);
+	};
+	Object.defineProperty(globalThis, Symbol.for("senpi.kernel.permissionImport"), { value: guard });
+	return () => { sealed = true; };
+}

package/src/kernels/js/interpose-paths.js

@@ -0,0 +1,80 @@
+import { createPathIdentity, PATH_IDENTITY_VERSION } from "../shared/path-identity.mjs";
+
+const path = process.getBuiltinModule("node:path");
+const fs = process.getBuiltinModule("node:fs");
+const { fileURLToPath } = process.getBuiltinModule("node:url");
+
+// Captured at module evaluation, before any interposition or cwd patch replaces them: the identity
+// must resolve with the engine's own native realpath and must never reach the live `path.resolve`
+// that worker-cwd.js rebinds to the session root (design N11).
+const identity = createPathIdentity({
+	realpathNative: fs.realpathSync.native,
+	lstat: fs.lstatSync,
+	readlink: fs.readlinkSync,
+	pathApi: {
+		join: path.join,
+		dirname: path.dirname,
+		basename: path.basename,
+		isAbsolute: path.isAbsolute,
+		sep: path.sep,
+		win32Resolve: path.win32.resolve,
+	},
+	platform: process.platform,
+});
+
+export function requestedPath(value) {
+	if (value instanceof URL) return fileURLToPath(value);
+	if (value instanceof Uint8Array) {
+		const text = Buffer.from(value).toString();
+		return Buffer.from(text).equals(value) ? text : undefined;
+	}
+	return typeof value === "string" ? value : undefined;
+}
+
+export function executionPath(value) {
+	if (typeof value === "string") return path.resolve(process.cwd(), value);
+	if (value instanceof Uint8Array && !path.isAbsolute(Buffer.from(value).toString("latin1"))) {
+		return Buffer.concat([Buffer.from(process.cwd() + path.sep), value]);
+	}
+	return value;
+}
+
+/** The written spelling, the executed spelling, and the kernel-computed canonical form (or why there is none). */
+function pathIdentityInput(value, executed = requestedPath(executionPath(value))) {
+	const requested = requestedPath(value);
+	if (requested === undefined || executed === undefined) return { input: { path: requested }, unsupported: true };
+	const input = { path: requested, executedPath: executed };
+	try {
+		const { path: canonical, foldCase } = identity.canonical(executed);
+		input.canonical = { v: PATH_IDENTITY_VERSION, path: canonical, foldCase };
+	} catch (error) {
+		input.unresolvable = typeof error?.code === "string" ? error.code : "EUNKNOWN";
+	}
+	return { input, unsupported: false };
+}
+
+export function checkPath(check, tool, value, options = {}) {
+	try {
+		check(() => {
+			const { input, unsupported } = pathIdentityInput(value, options.executed);
+			return { call: { tool, input, cwd: options.cwd ?? process.cwd() }, unsupported };
+		});
+	} catch (error) {
+		if (error?.code === "cell_permission_denied" && typeof value === "string") error.message += `: ${value}`;
+		throw error;
+	}
+}
+
+export function replaceMethod(owner, name, wrap) {
+	const original = owner?.[name];
+	if (typeof original !== "function") return;
+	const wrapped = wrap(original);
+	for (const key of Reflect.ownKeys(original)) {
+		if (key === "length" || key === "name" || key === "prototype" || Object.hasOwn(wrapped, key)) continue;
+		Object.defineProperty(wrapped, key, Object.getOwnPropertyDescriptor(original, key));
+	}
+	Object.defineProperty(owner, name, {
+		...(Object.getOwnPropertyDescriptor(owner, name) ?? { configurable: true, writable: true, enumerable: false }),
+		value: wrapped,
+	});
+}