@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10

package/CHANGELOG.md

@@ -12,6 +12,28 @@
 
 ### Removed
 
+## [2026.10.10] - 2026-10-05
+
+### Breaking Changes
+
+### Added
+
+- Isolated eval cells: with `sandbox.enabled`, `isolate: true` runs a JavaScript cell in a fresh QuickJS VM with no persistence and no ambient host (only `tools.*`, `print`, `display`), streaming output under a credit window. Off by default; the eval schema is unchanged until the setting is on.
+- A JavaScript cell that is only `%bun add <package ...>` or `%npm add <package ...>` installs packages into a per-session managed environment without restarting the kernel; the next cell imports them by bare name, the project's `package.json` and `node_modules` are untouched, lifecycle scripts never run, and a failed or cancelled install leaves the previous packages active ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- An isolated (`isolate: true`) cell whose QuickJS runtime is missing now fails with `eval_isolate_unavailable` before any of its code runs, instead of a module-resolution error that named a host path ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- `%bun add` over a package first installed from a local directory now works when the new archive's top directory is not `package/` (a GitHub-style `<repo>-<sha>.tgz`, or a plain `.tar`): its name is read from the archive's own top-level directory, so the old directory's links are removed before bun installs ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- A nested tool call that is denied inside an `eval` cell (a permission denial or another hook's block) now reaches the cell as the plain denial, without the `Expected parameters:` schema hint that made it read like an argument error; argument failures still get the hint ([#2700](https://github.com/code-yeongyu/senpi/issues/2700)). Thanks to @MoerAI ([#2755](https://github.com/code-yeongyu/senpi/pull/2755)).
+- An `eval` run with an invalid `language` value (for example `"python"`, `""` or `null`) now gets its own error listing the enabled languages, instead of the "run requires language" message meant for an omitted one; `peek` and `stop` still need no language ([#1395](https://github.com/code-yeongyu/senpi/issues/1395)). Thanks to @MoerAI.
+
+### Removed
+
 ## [2026.10.9] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -67,6 +67,12 @@ Windows fresh-cache bootstrap p99 (30 samples). A stalled or failed start names
 the last stage and retains the interpreter's diagnostic error. The low-level
 `PythonKernel.start({ startupTimeoutMs })` override applies per stage.
 
+Every `eval` run must explicitly select an enabled `language` (`js`, `py`, `rb`,
+or `jl`); there is no default kernel, even when only one language is enabled.
+Omitting `action` means `run`, so it also requires `language`. Control requests
+with `action: "peek"` or `action: "stop"` use `cell_id` and do not require a
+language.
+
 ### Session environment
 
 Every kernel starts with the active session's `PI_*` environment — `PI_SESSION_ID`,
@@ -117,6 +123,35 @@ cannot be read fails the cell with a message naming the path as written
 (`file not found: <path>`, `permission denied: <path>`); files over 8 MiB, and
 anything that is not a regular file, are refused.
 
+### JavaScript packages
+
+A JavaScript cell whose only line is `%bun add <package ...>` or `%npm add <package ...>`
+installs packages without restarting the kernel; the next cell imports them by bare name.
+`%bun add` uses bun and `%npm add` uses npm; `environments.js.installer` (`bun`, `npm` or
+`auto`: bun when it is on `PATH`, else npm) applies only where the magic names none, and the
+kernel's own runtime never changes to get one.
+
+In the default managed mode packages go into an environment revision under the session's
+artifacts directory, never into the project's `package.json` or `node_modules`. With
+`environments.managedRoot` set, every session using that root shares one revision chain: their
+installs are serialized and each revision carries the packages installed before it.
+A bare import resolves from the session directory's `node_modules` first and then from the
+active revision, using each package's `exports` for `import` (ESM-only packages load), so the
+project's own packages still win, and both win over Senpi's own dependencies (a package neither has may still load from Senpi's install). When a
+newly added package is also in the project's `node_modules`, the result says
+`environment_resolution_conflict` because the project copy resolves first.
+
+Each install builds a new revision that carries the previous one forward (its `package.json`,
+lockfile, and from `.npmrc` only `registry`, `@scope:registry`, `strict-ssl`, `ca` and `cafile`, rewritten as a regular file; credentials and every other key are dropped, and `bunfig.toml` is not carried)
+and is published only when the installer succeeds; a failed or cancelled install, or one still
+running when the session closes, leaves the previous revision active. Lifecycle scripts never run
+(`--ignore-scripts`), installer flags are refused because the host picks the destination, and a
+path-like package (`./pkg`, `file:../pkg`) is a path from the session directory. Package names
+are split on whitespace; quoting is not supported. Error and installer text names the session directory as
+`<cwd>`, the revision as `<root>`, the temp directory as `<tmp>`, the home directory as `~`, and an
+absolute package path by its file name only. `%environment project` installs
+into the session directory itself instead.
+
 ### Python packages
 
 A Python cell whose only line is `%pip install <requirements>` installs packages
@@ -145,6 +180,19 @@ that project, with concurrent installs serialised by a lock. Setting
 of `environment_install_failed`, `environment_install_cancelled`,
 `environment_installer_unavailable` or `environment_resolution_conflict`.
 
+### Isolated cells
+
+With `sandbox.enabled: true`, a JavaScript call may pass `isolate: true`. The cell then runs in a fresh QuickJS VM (the vendored pi codemode runtime) instead of the persistent kernel:
+
+- Nothing persists: globals from the kernel are not visible, and a global set in one isolated cell is gone in the next. `store()` throws `eval_isolate_no_state` and `load()` returns `undefined`.
+- No ambient host: there is no `process`, `require`, file system, network, child processes or timers. The cell's only reach is `tools.<name>` (also `tool.<name>`; every active tool except `eval`, run through the same permission hooks as a direct call) plus `print`, `display`, `text` and `image`.
+- `isolate: true` isolates the JavaScript, not the tools it calls: a tool keeps its normal reach. `tools.bash`, for example, runs a shell with the session's environment and files, under the same permission hooks as any other call.
+- Output streams from the VM in frames under a 256 KiB credit window, so the VM never holds a large item; the host joins an item's frames before adding it to the result, and memory stays bounded by `sandbox.memoryMb`.
+- It is a host entry in the JavaScript queue: it waits for earlier cells, Stop and the run budget end it, and the persistent kernel is never restarted for it.
+- Limits: `sandbox.memoryMb` (default 64) and `sandbox.timeoutSeconds` (default 300). Failures are named: `eval_isolate_memory_limit`, `eval_isolate_timeout`, `eval_isolate_unresolved_promise` (a top-level promise that can never settle) and `eval_isolate_unavailable` (the runtime could not start).
+
+While `sandbox.enabled` is `false` (the default) the `isolate` field is absent from the eval schema, and passing it is refused with `eval_isolate_invalid`, as are `isolate` with another language and `isolate` with `reset`.
+
 ## Settings
 
 Configuration is loaded in this order:
@@ -218,7 +266,7 @@ Configuration is loaded in this order:
 | `prompt.advertiseHelpers` | `false` | When `true`, one pointer line to `tool_schema('eval:helpers')` is appended to the eval description. |
 | `kernelTools.enabled` | `true` | Allows cells to define kernel tools (`tool(fn)`, `@tool`). `false` makes them refuse with `tools_unavailable`. |
 
-The `languages.pyInterpreter`, `environments.*`, `isolation.*`, `sandbox.*`, `prompt.*` and `kernelTools.*` keys are accepted and validated now, with the defaults shown, which match today's behaviour. The effect each of those rows describes takes effect when its feature ships; until then, setting a key changes nothing.
+The `languages.pyInterpreter`, `environments.*`, `isolation.*`, `prompt.*` and `kernelTools.*` keys are accepted and validated now, with the defaults shown, which match today's behaviour. The effect each of those rows describes takes effect when its feature ships; until then, setting a key changes nothing.
 
 `SENPI_CODEMODE_PY`, `SENPI_CODEMODE_JS`, `SENPI_CODEMODE_RB`, and
 `SENPI_CODEMODE_JL` override the corresponding file setting. `1` or `true`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.9",
+	"version": "2026.10.10",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -32,15 +32,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.9",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.9"
+		"@code-yeongyu/senpi": "2026.10.10"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.9"
+		"@code-yeongyu/senpi": "2026.10.10"
 	},
 	"keywords": [
 		"senpi",

package/src/environments/js-environments.ts

@@ -0,0 +1,208 @@
+import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import { withRootLock } from "./install-lock.ts";
+import {
+	absoluteSpec,
+	type JsInstallerChoice,
+	parseJsPackages,
+	requestedPackageName,
+	resolveJsInstaller,
+	runJsInstall,
+	withoutHostPaths,
+} from "./js-installer.ts";
+import { carryNpmrcSettings, recordedFileSpecs, seedPackageJson } from "./js-revision-files.ts";
+import { assertBuiltRevisionLinks, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
+import { projectResolves } from "./project-resolves.ts";
+import type { EnvironmentMode } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import { mkdirPrivate, publishNextRevision, readActiveRevision } from "./revision-store.ts";
+
+/** The paths in a revision that the installer writes. */
+const INSTALLER_WRITES = [
+	"package.json",
+	"package-lock.json",
+	"bun.lock",
+	"bun.lockb",
+	"node_modules",
+	".npmrc",
+	"bunfig.toml",
+];
+
+export interface JsInstallReceipt {
+	readonly installer: "bun" | "npm";
+	readonly mode: EnvironmentMode;
+	readonly revision: number | undefined;
+	readonly added: readonly string[];
+	readonly shadowed: readonly string[];
+}
+
+export interface JsEnvironmentsOptions {
+	readonly artifactsDir: string;
+	readonly cwd: string;
+	readonly runtime: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly settings: Pick<ResolvedCodemodeSettings, "environments">;
+}
+
+export class JsEnvironments {
+	readonly #options: JsEnvironmentsOptions;
+	#mode: EnvironmentMode = "managed";
+	#packageRoot: string | undefined;
+
+	constructor(options: JsEnvironmentsOptions) {
+		this.#options = options;
+	}
+
+	get mode(): EnvironmentMode {
+		return this.#mode;
+	}
+
+	get packageRoot(): string | undefined {
+		return this.#mode === "managed" ? this.#packageRoot : undefined;
+	}
+
+	async setMode(mode: EnvironmentMode): Promise<string> {
+		this.#mode = mode;
+		if (mode === "project") return this.#options.cwd;
+		this.#packageRoot = (await readActiveRevision(this.#managedBase()))?.dir;
+		return this.#managedBase();
+	}
+
+	async install(
+		requested: string,
+		signal: AbortSignal,
+		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
+		requestedInstaller?: "bun" | "npm",
+	): Promise<JsInstallReceipt> {
+		const environments = this.#options.settings.environments;
+		if (environments?.autoProvision === false) {
+			throw new EnvironmentError(
+				"environment_installer_unavailable",
+				"installs are turned off for this project (environments.autoProvision is false)",
+			);
+		}
+		const packages = parseJsPackages(requested).map((spec) => absoluteSpec(spec, this.#options.cwd));
+		// `%bun add` and `%npm add` name their installer; the setting applies only where the magic does not.
+		const choice: JsInstallerChoice = requestedInstaller ?? environments?.js?.installer ?? "auto";
+		const { installer, command } = resolveJsInstaller(choice, this.#options.env);
+		let recordedSpecs: readonly string[] = [];
+		const run = (root: string, remove?: string) =>
+			runJsInstall({
+				installer,
+				command,
+				root,
+				packages,
+				...(remove === undefined ? {} : { remove }),
+				recordedSpecs,
+				cwd: this.#options.cwd,
+				env: this.#options.env,
+				signal,
+				...(onOutput === undefined ? {} : { onOutput }),
+			});
+		// The lock and the revision store fail with raw file system errors; they reach the cell redacted.
+		const redacted =
+			(...roots: string[]) =>
+			(error: unknown) => {
+				const raw =
+					error instanceof EnvironmentError
+						? error.message.slice(error.code.length + 2)
+						: String(error instanceof Error ? error.message : error);
+				const text = roots.reduce(
+					(message, root) => withoutHostPaths(message, { root, cwd: this.#options.cwd, packages, recordedSpecs }),
+					raw,
+				);
+				if (error instanceof EnvironmentError) throw new EnvironmentError(error.code, text);
+				// An abort while waiting for the lock or before the publish is a cancel, not a failure.
+				if (signal.aborted)
+					throw new EnvironmentError("environment_install_cancelled", `the install was cancelled: ${text}`);
+				throw new EnvironmentError("environment_install_failed", text);
+			};
+		if (this.#mode === "project") {
+			const before = await dependencyNames(this.#options.cwd);
+			const lockRoot = join(this.#options.cwd, ".senpi", "js-packages");
+			await mkdir(lockRoot, { recursive: true });
+			await withRootLock(lockRoot, async () => await run(this.#options.cwd), signal).catch(redacted(lockRoot));
+			const added = (await dependencyNames(this.#options.cwd)).filter((name) => !before.includes(name));
+			return { installer, mode: "project", revision: undefined, added, shadowed: [] };
+		}
+		let added: string[] = [];
+		const requestedBase = this.#managedBase();
+		const base = await canonicalBase(this.#managedRoot(), requestedBase).catch(redacted(requestedBase));
+		const { revision } = await publishNextRevision(
+			base,
+			async (staging) => {
+				await carryNpmrcSettings(staging);
+				await rm(join(staging, "bunfig.toml"), { recursive: true, force: true });
+				await seedPackageJson(staging);
+				// Every path the installer writes must be the revision's own, never a link out of it.
+				for (const entry of INSTALLER_WRITES) await assertNoLinksBelow(base, join(staging, entry));
+				const before = await dependencyNames(staging);
+				recordedSpecs = await recordedFileSpecs(staging);
+				// A package whose source changes kind (a directory to a tarball or registry version, or back) is removed
+				// first: bun keeps its per-file links into the old directory otherwise (#2758).
+				for (const name of await sourceKindChanges(staging, packages)) await run(staging, name);
+				await run(staging);
+				await assertBuiltRevisionLinks(staging);
+				added = (await dependencyNames(staging)).filter((name) => !before.includes(name));
+			},
+			signal,
+		).catch(redacted(base, requestedBase));
+		this.#packageRoot = revision.dir;
+		const shadowed = added.filter((name) => projectResolves(this.#options.cwd, name));
+		return { installer, mode: "managed", revision: revision.number, added, shadowed };
+	}
+
+	#managedRoot(): string {
+		return this.#options.settings.environments?.managedRoot ?? this.#options.artifactsDir;
+	}
+
+	#managedBase(): string {
+		return join(this.#managedRoot(), "environments", "js", this.#options.runtime);
+	}
+}
+
+async function dependencyNames(root: string): Promise<string[]> {
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return [];
+		const dependencies = manifest.dependencies;
+		return typeof dependencies === "object" && dependencies !== null ? Object.keys(dependencies) : [];
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/**
+ * Creates the managed base, checks that nothing below the managed root is a link, and returns its realpath: npm keys
+ * a linked package in its lockfile by a path relative to the prefix, and a prefix under a linked directory (macOS
+ * `/var` is a link to `/private/var`) gives keys that stop resolving once the staged revision is renamed.
+ */
+async function canonicalBase(managedRoot: string, base: string): Promise<string> {
+	await assertNoLinksBelow(managedRoot, base);
+	await mkdirPrivate(base);
+	await assertNoLinksBelow(managedRoot, base);
+	return await realpath(base);
+}
+
+/** Names among `packages` whose recorded source is a directory and is not the same directory now, or the reverse. */
+export async function sourceKindChanges(revision: string, packages: readonly string[]): Promise<string[]> {
+	const installed = new Set(await dependencyNames(revision));
+	const sources = await recordedInstallSources(revision);
+	const changed: string[] = [];
+	for (const spec of packages) {
+		const name = await requestedPackageName(spec);
+		if (name === undefined || !installed.has(name)) continue;
+		const directory = await localDirectory(spec);
+		if (directory !== sources.get(name)) changed.push(name);
+	}
+	return changed;
+}
+
+async function localDirectory(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (!isAbsolute(path)) return undefined;
+	const resolved = await realpath(path).catch(() => undefined);
+	return resolved !== undefined && (await stat(resolved)).isDirectory() ? resolved : undefined;
+}

package/src/environments/js-installer.ts

@@ -0,0 +1,268 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, delimiter, isAbsolute, join, resolve, sep } from "node:path";
+import { EnvironmentError } from "./py-installer.ts";
+
+export type JsInstallerChoice = "auto" | "bun" | "npm";
+export type JsInstaller = "bun" | "npm";
+
+const STDERR_TAIL_BYTES = 4_096;
+
+function onPath(command: string, env: NodeJS.ProcessEnv): string | undefined {
+	const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+	const extensions = process.platform === "win32" ? [".exe", ".cmd", ""] : [""];
+	for (const directory of (env[pathKey] ?? "").split(delimiter)) {
+		if (directory === "") continue;
+		for (const extension of extensions) {
+			const candidate = join(directory, `${command}${extension}`);
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+export function resolveJsInstaller(
+	choice: JsInstallerChoice,
+	env: NodeJS.ProcessEnv,
+): { readonly installer: JsInstaller; readonly command: string } {
+	const order: readonly JsInstaller[] = choice === "auto" ? ["bun", "npm"] : [choice];
+	for (const installer of order) {
+		const command = onPath(installer, env);
+		if (command !== undefined) return { installer, command };
+	}
+	throw new EnvironmentError(
+		"environment_installer_unavailable",
+		choice === "auto" ? "neither bun nor npm is on PATH" : `${choice} is not on PATH`,
+	);
+}
+
+export function parseJsPackages(text: string): string[] {
+	if (/[\u0000-\u0008\u000e-\u001f\u007f]/.test(text)) {
+		throw new EnvironmentError("environment_install_failed", "package names cannot contain control characters");
+	}
+	const packages = text.split(/\s+/).filter((token) => token !== "");
+	const flag = packages.find((token) => token.startsWith("-"));
+	if (flag !== undefined) {
+		throw new EnvironmentError(
+			"environment_install_failed",
+			`installer flags are chosen by the host; name packages only (got ${flag})`,
+		);
+	}
+	if (packages.length === 0)
+		throw new EnvironmentError("environment_install_failed", "name at least one package to add");
+	return packages;
+}
+
+/**
+ * A path-like spec (`./pkg`, `../x.tgz`, `file:./pkg`) means a path from the session directory; both installers get it
+ * absolute, because bun resolves a relative spec from the revision it builds and npm from its own cwd.
+ */
+export function absoluteSpec(spec: string, cwd: string): string {
+	const file = spec.startsWith("file:") ? spec.slice("file:".length) : undefined;
+	const path = file ?? spec;
+	const pathLike = path.startsWith("./") || path.startsWith("../") || path === "." || path === "..";
+	if (!pathLike) return spec;
+	const absolute = resolve(cwd, path);
+	return file === undefined ? absolute : `file:${absolute}`;
+}
+
+export function jsInstallArgv(installer: JsInstaller, root: string, packages: readonly string[]): string[] {
+	return installer === "bun"
+		? ["add", "--ignore-scripts", "--cwd", root, ...packages]
+		: ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--prefix", root, ...packages];
+}
+
+export function jsRemoveArgv(installer: JsInstaller, root: string, name: string): string[] {
+	return installer === "bun"
+		? ["remove", "--ignore-scripts", "--cwd", root, name]
+		: ["uninstall", "--ignore-scripts", "--no-audit", "--no-fund", "--prefix", root, name];
+}
+
+const REGISTRY_NAME = /^((?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*)(?:@[^/]*)?$/i;
+
+/**
+ * The package name a spec installs, when it can be known before the install: a local directory's or tarball's own
+ * `package.json` name, or the name of a registry spec (`name`, `name@range`, `@scope/name@range`). Undefined for URL
+ * and git specs.
+ */
+export async function requestedPackageName(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (isAbsolute(path)) {
+		try {
+			const manifest: unknown = JSON.parse(
+				(await stat(path)).isDirectory()
+					? await readFile(join(path, "package.json"), "utf8")
+					: await tarballManifest(path),
+			);
+			return typeof manifest === "object" &&
+				manifest !== null &&
+				"name" in manifest &&
+				typeof manifest.name === "string"
+				? manifest.name
+				: undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	return REGISTRY_NAME.exec(spec)?.[1];
+}
+
+/**
+ * An archive's own `package.json`, read from its single top-level directory as both installers unpack it: npm's
+ * `package/`, or a GitHub-style `<repo>-<sha>/`. tar detects the compression itself, so a plain `.tar` works too.
+ */
+async function tarballManifest(path: string): Promise<string> {
+	const entries = (await tarOutput(["-tf", path])).split("\n").filter((entry) => entry !== "");
+	const normalized = (entry: string) => entry.replace(/^(\.\/)+/, "");
+	const tops = new Set(entries.map((entry) => normalized(entry).split("/")[0] ?? "").filter((top) => top !== ""));
+	// An archive whose entries do not all sit under one directory has no single package to name: judging it by
+	// whichever entry comes first could name the wrong one.
+	const [top, ...others] = [...tops];
+	if (top === undefined || others.length > 0 || top === "." || top === "..") {
+		throw new Error("the archive does not hold one top-level directory");
+	}
+	// Extract by the member's own name: GNU tar matches it exactly, so a leading "./" must be kept.
+	const manifest = entries.find((entry) => normalized(entry) === `${top}/package.json`);
+	if (manifest === undefined) throw new Error("the archive holds no package.json in its top-level directory");
+	return await tarOutput(["-xOf", path, manifest]);
+}
+
+function tarOutput(args: readonly string[]): Promise<string> {
+	return new Promise((resolveText, reject) => {
+		execFile("tar", [...args], { maxBuffer: 64 << 20 }, (error, stdout) =>
+			error === null ? resolveText(stdout) : reject(error),
+		);
+	});
+}
+
+export function runJsInstall(input: {
+	readonly installer: JsInstaller;
+	readonly command: string;
+	readonly root: string;
+	readonly packages: readonly string[];
+	/** Remove this package instead of adding `packages`. */
+	readonly remove?: string;
+	/** Absolute specs already recorded in the revision; the installer echoes them, so they are redacted too. */
+	readonly recordedSpecs?: readonly string[];
+	readonly cwd: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly signal: AbortSignal;
+	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+}): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (input.signal.aborted) {
+			reject(new EnvironmentError("environment_install_cancelled", "the install was cancelled before it started"));
+			return;
+		}
+		const argv =
+			input.remove === undefined
+				? jsInstallArgv(input.installer, input.root, input.packages)
+				: jsRemoveArgv(input.installer, input.root, input.remove);
+		const child = spawn(input.command, argv, {
+			cwd: input.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			// npm reads `global`/`location` from any .npmrc and the env; a global install would land where the import never looks.
+			env: {
+				...input.env,
+				npm_config_ignore_scripts: "true",
+				npm_config_global: "false",
+				npm_config_location: "project",
+			},
+			detached: process.platform !== "win32",
+		});
+		let output = "";
+		const record = (stream: "stdout" | "stderr") => (data: string) => {
+			output = (output + data).slice(-STDERR_TAIL_BYTES);
+			input.onOutput?.(stream, withoutHostPaths(data, input));
+		};
+		child.stdout.setEncoding("utf8").on("data", record("stdout"));
+		child.stderr.setEncoding("utf8").on("data", record("stderr"));
+		const onAbort = () => {
+			if (child.pid !== undefined && process.platform !== "win32") {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+					return;
+				} catch {
+					// ESRCH (the group is gone) or EPERM (macOS refuses a group whose leader already exited): stop the
+					// installer itself. An abort listener must never throw: nothing above it can catch the error.
+				}
+			}
+			child.kill("SIGKILL");
+		};
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		child.once("error", (error) => {
+			input.signal.removeEventListener("abort", onAbort);
+			reject(
+				new EnvironmentError(
+					"environment_installer_unavailable",
+					`${input.installer}: ${withoutHostPaths(error.message, input)}`,
+				),
+			);
+		});
+		child.once("close", (code, signal) => {
+			input.signal.removeEventListener("abort", onAbort);
+			if (input.signal.aborted) {
+				reject(
+					new EnvironmentError(
+						"environment_install_cancelled",
+						`the install was cancelled${cancelReason(input.signal, input)}; ${input.installer} was stopped`,
+					),
+				);
+			} else if (code === 0) resolve();
+			else {
+				reject(
+					new EnvironmentError(
+						"environment_install_failed",
+						withoutHostPaths(output.trim(), input) || `${input.installer} exited with ${code ?? signal}`,
+					),
+				);
+			}
+		});
+	});
+}
+
+function cancelReason(signal: AbortSignal, input: Parameters<typeof withoutHostPaths>[1]): string {
+	const reason: unknown = signal.reason;
+	return reason instanceof Error && reason.name !== "AbortError" ? `: ${withoutHostPaths(reason.message, input)}` : "";
+}
+
+/** Installer output names the session's own roots; error text says `<root>`/`<cwd>`/`~` instead of absolute paths. */
+export function withoutHostPaths(
+	text: string,
+	input: {
+		readonly root: string;
+		readonly cwd: string;
+		readonly packages: readonly string[];
+		readonly recordedSpecs?: readonly string[];
+	},
+): string {
+	const home = homedir();
+	// A spec that is an absolute file path names the user's file system; it is shown by its file name only.
+	// This install's absolute specs, and every path an earlier install recorded (npm records a relative `file:` path).
+	const requested = input.packages
+		.map((spec) => (spec.startsWith("file:") ? spec.slice("file:".length) : spec))
+		.filter((path) => isAbsolute(path));
+	const specPaths = [...requested, ...(input.recordedSpecs ?? [])]
+		.sort((a, b) => b.length - a.length)
+		.map((path) => [path, `<path>/${basename(path)}`] as const);
+	return [
+		...specPaths,
+		[input.root, "<root>"],
+		[input.cwd, "<cwd>"],
+		[realpathOrSelf(tmpdir()), "<tmp>"],
+		[tmpdir(), "<tmp>"],
+		[home, "~"],
+	]
+		.filter(([path]) => path !== "" && path !== sep)
+		.reduce((current, [path, label]) => current.replaceAll(path, label), text);
+}
+
+function realpathOrSelf(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}