@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.10-10

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;
+	}
+}

package/src/environments/js-revision-files.ts

@@ -0,0 +1,91 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+const NPMRC_CARRIED_KEY = /^(?:registry|@[^\s=:/]+:registry|strict-ssl|ca|cafile)$/;
+
+/**
+ * A revision carries forward only the registry settings of its `.npmrc`: `registry`, `@scope:registry`, `strict-ssl`,
+ * `ca` and `cafile`. Every other key, credentials included, is dropped by default, and the file is rewritten as a
+ * regular file: a symlinked `.npmrc` is replaced, never written through, so the file it pointed at stays untouched.
+ */
+export async function carryNpmrcSettings(root: string): Promise<void> {
+	const path = join(root, ".npmrc");
+	let text: string;
+	try {
+		text = await readFile(path, "utf8");
+	} catch {
+		await rm(path, { recursive: true, force: true });
+		return;
+	}
+	const kept = text
+		.split(/\r\n|\r|\n/)
+		.map((line) => line.trim())
+		.filter((line) => {
+			const key = line.split("=", 1)[0]?.trim() ?? "";
+			return line.includes("=") && NPMRC_CARRIED_KEY.test(key);
+		})
+		.flatMap((line) => {
+			const carried = withoutUrlCredentials(line);
+			return carried === undefined ? [] : [carried];
+		});
+	await rm(path, { recursive: true, force: true });
+	if (kept.length > 0) await writeFile(path, `${kept.join("\n")}\n`, { mode: 0o600, flag: "wx" });
+}
+
+/**
+ * The `file:` and absolute path specs a revision's `package.json` already records, as written (npm writes a relative
+ * `file:../..` path) and resolved against the revision: the installer echoes them on every later install.
+ */
+export async function recordedFileSpecs(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;
+		if (typeof dependencies !== "object" || dependencies === null) return [];
+		return Object.values(dependencies).flatMap((spec) => {
+			if (typeof spec !== "string") return [];
+			if (spec.startsWith("file:")) {
+				const path = spec.slice("file:".length);
+				return isAbsolute(path) ? [path] : [path, resolve(root, path)];
+			}
+			return isAbsolute(spec) ? [spec] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * A carried `registry`/`@scope:registry` value keeps only its scheme, host and path: user info, a query and a fragment
+ * can each carry a credential, so they are cleared with the WHATWG URL parser npm itself uses. The path is kept, since
+ * registries are addressed by it, so a registry that embeds a token in its path keeps it in the revision's private
+ * (0600, in a 0700 directory) copy. A value that does not parse is dropped, and so is one that names an environment
+ * variable (`${...}`): npm expands it at install time, and a parsed copy would be a different URL. Other carried keys
+ * pass unchanged.
+ */
+function withoutUrlCredentials(line: string): string | undefined {
+	const separator = line.indexOf("=");
+	const key = line.slice(0, separator).trim();
+	if (!key.endsWith("registry")) return line;
+	const raw = line.slice(separator + 1).trim();
+	if (raw.includes("${")) return undefined;
+	const quote = raw.length >= 2 && (raw[0] === '"' || raw[0] === "'") && raw.endsWith(raw[0]) ? raw[0] : "";
+	let url: URL;
+	try {
+		url = new URL(quote === "" ? raw : raw.slice(1, -1));
+	} catch {
+		return undefined;
+	}
+	url.username = "";
+	url.password = "";
+	url.search = "";
+	url.hash = "";
+	return `${key}=${quote}${url.href}${quote}`;
+}
+
+/** Without its own `package.json`, bun walks up from the revision and installs into the nearest one above it. */
+export async function seedPackageJson(root: string): Promise<void> {
+	await writeFile(join(root, "package.json"), '{"private":true}\n', { flag: "wx" }).catch((error: unknown) => {
+		if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+	});
+}

package/src/environments/no-links.ts

@@ -0,0 +1,132 @@
+import { lstat, readdir, readFile, readlink, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { EnvironmentError } from "./py-installer.ts";
+
+/**
+ * Every managed-root write goes through here: each component of `path` strictly below `root` that exists must be a
+ * real file or directory, never a link, so a write can never land in what a planted link points at. `root` itself
+ * may be a link (a user may relocate their whole artifacts directory); nothing below it may.
+ */
+export async function assertNoLinksBelow(root: string, path: string): Promise<void> {
+	const below = relative(root, path);
+	if (below.startsWith("..") || isAbsolute(below)) {
+		throw new EnvironmentError("environment_install_failed", "refusing to write outside the managed environment");
+	}
+	let current = root;
+	for (const part of below.split(sep).filter((segment) => segment !== "")) {
+		current = join(current, part);
+		const stats = await lstat(current).catch(missing);
+		if (stats === undefined) return;
+		if (stats.isSymbolicLink()) {
+			throw new EnvironmentError(
+				"environment_install_failed",
+				`${relative(root, current)} is a link; refusing to write through it`,
+			);
+		}
+	}
+}
+
+/**
+ * The local directories a revision's `package.json` records as install sources, by package name, as realpaths: npm
+ * writes `file:<path relative to the revision>`, bun the absolute path. Only these may be link targets out of the
+ * revision, because installing from a directory links the package to it.
+ */
+export async function recordedInstallSources(revision: string): Promise<ReadonlyMap<string, string>> {
+	const sources = new Map<string, string>();
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(await readFile(join(revision, "package.json"), "utf8"));
+	} catch {
+		return sources;
+	}
+	if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return sources;
+	const dependencies = manifest.dependencies;
+	if (typeof dependencies !== "object" || dependencies === null) return sources;
+	for (const [name, spec] of Object.entries(dependencies)) {
+		if (typeof spec !== "string") continue;
+		const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+		if (!isAbsolute(path) && !path.startsWith("./") && !path.startsWith("../")) continue;
+		const source = await realpath(resolve(revision, path)).catch(() => undefined);
+		if (source !== undefined && (await stat(source)).isDirectory()) sources.set(name, source);
+	}
+	return sources;
+}
+
+/**
+ * A copy filter. A link inside `tree` may point inside it (relatively: an absolute link would keep pointing at the
+ * previous revision from the copy), or out of it only to exactly the matching file of a recorded install source:
+ * the link at `node_modules/<name>/<rest>` may resolve to `<source of name>/<rest>` and to nothing else. Whether a
+ * target is inside is judged from the link's own text, without following further links.
+ */
+export async function assertLinkStaysInside(
+	path: string,
+	tree: string,
+	sources: ReadonlyMap<string, string>,
+): Promise<boolean> {
+	if (!(await lstat(path)).isSymbolicLink()) return true;
+	const target = await readlink(path);
+	const resolved = resolve(dirname(path), target);
+	const inside = relative(tree, resolved);
+	const where = relative(tree, path);
+	if (inside === "" || (!inside.startsWith("..") && !isAbsolute(inside))) {
+		if (!isAbsolute(target)) return true;
+		throw new EnvironmentError(
+			"environment_install_failed",
+			`${where} is an absolute link into its revision; refusing to build on it`,
+		);
+	}
+	if (await isRecordedSourceLink(where, resolved, sources)) return true;
+	throw new EnvironmentError(
+		"environment_install_failed",
+		`${where} links outside its revision; refusing to build on it`,
+	);
+}
+
+async function isRecordedSourceLink(
+	where: string,
+	resolved: string,
+	sources: ReadonlyMap<string, string>,
+): Promise<boolean> {
+	const parts = where.split(sep);
+	if (parts[0] !== "node_modules" || parts[1] === undefined) return false;
+	const scoped = parts[1].startsWith("@");
+	const name = scoped ? `${parts[1]}/${parts[2] ?? ""}` : parts[1];
+	const source = sources.get(name);
+	if (source === undefined) return false;
+	// `source` is a realpath; the expected target is that path plus the link's own path below the package, taken
+	// literally, so a file of the source that is itself a link out of it does not count as the source.
+	const expected = join(source, ...parts.slice(scoped ? 3 : 2));
+	const actual = await realpath(resolved).catch(() => undefined);
+	return actual !== undefined && actual === expected;
+}
+
+function missing(error: unknown): undefined {
+	if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+	throw error;
+}
+
+/**
+ * Checks every link in a built revision as the next copy will, so an install that leaves a link the next install
+ * would refuse (an installer keeping links into a directory the manifest no longer records) is refused now, while
+ * the previous revision is still active.
+ */
+export async function assertBuiltRevisionLinks(revision: string): Promise<void> {
+	const sources = await recordedInstallSources(revision);
+	const walk = async (dir: string): Promise<void> => {
+		for (const entry of await readdir(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isSymbolicLink()) {
+				await assertLinkStaysInside(path, revision, sources).catch((error: unknown) => {
+					const where = relative(revision, path);
+					throw error instanceof EnvironmentError
+						? new EnvironmentError(
+								"environment_install_failed",
+								`the install left ${where} linked outside the revision, so nothing was published`,
+							)
+						: error;
+				});
+			} else if (entry.isDirectory()) await walk(path);
+		}
+	};
+	await walk(revision);
+}

package/src/environments/packages-install.ts

@@ -0,0 +1,98 @@
+import type { JsEnvironments, JsInstallReceipt } from "./js-environments.ts";
+import type { InstallReceipt } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import type { PythonEnvironments } from "./python-environments.ts";
+
+export interface PackagesInstallEnvironments {
+	readonly python?: PythonEnvironments;
+	readonly js?: JsEnvironments;
+}
+
+export const PACKAGES_INSTALL_DEFAULT_TIMEOUT_SECONDS = 600;
+
+interface PackagesInstallRequest {
+	readonly manager: "pip" | "bun" | "npm";
+	readonly requirements: readonly string[];
+	readonly timeoutSeconds: number;
+}
+
+function invalid(message: string): EnvironmentError {
+	return new EnvironmentError("environment_install_failed", `packages.install(): ${message}`);
+}
+
+function parseRequest(args: unknown): PackagesInstallRequest {
+	if (typeof args !== "object" || args === null) throw invalid("expected (manager, requirements, {timeout?})");
+	const manager = "manager" in args ? args.manager : undefined;
+	if (manager !== "pip" && manager !== "bun" && manager !== "npm") {
+		throw invalid('manager must be "pip" (Python) or "bun" / "npm" (JavaScript)');
+	}
+	const raw = "requirements" in args ? args.requirements : undefined;
+	const list = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : undefined;
+	if (
+		list === undefined ||
+		list.length === 0 ||
+		!list.every((item) => typeof item === "string" && item.trim() !== "")
+	) {
+		throw invalid("requirements must be a non-empty string or a non-empty list of non-empty strings");
+	}
+	const timeout = "timeout" in args ? args.timeout : undefined;
+	if (timeout !== undefined && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) {
+		throw invalid("timeout must be a positive number of seconds");
+	}
+	return {
+		manager,
+		requirements: list.map((item: string) => item.trim()),
+		timeoutSeconds: timeout ?? PACKAGES_INSTALL_DEFAULT_TIMEOUT_SECONDS,
+	};
+}
+
+function jsArguments(requirements: readonly string[]): string {
+	for (const requirement of requirements) {
+		if (/\s/.test(requirement)) throw invalid(`a package spec cannot contain whitespace: ${requirement}`);
+	}
+	return requirements.join(" ");
+}
+
+/**
+ * `packages.install(manager, requirements, {timeout?})`: the in-cell form of `%pip install` / `%bun add` /
+ * `%npm add`. It drives the same session environment the magic cells use and returns its receipt; a stop of the
+ * owning cell cancels it (environment_install_cancelled), and the timeout fails it with environment_install_timeout.
+ * pip receives the requirement list as separate arguments, never re-split. The installer's output is not streamed
+ * into the cell: the receipt is the result, and a failure carries the installer's stderr tail.
+ */
+export async function runPackagesInstall(
+	args: unknown,
+	environments: PackagesInstallEnvironments,
+	signal: AbortSignal | undefined,
+): Promise<InstallReceipt | JsInstallReceipt> {
+	const request = parseRequest(args);
+	const { python, js } = environments;
+	const manager = request.manager;
+	let install: ((signal: AbortSignal) => Promise<InstallReceipt | JsInstallReceipt>) | undefined;
+	if (manager === "pip") {
+		if (python !== undefined) install = (signal) => python.install(request.requirements, signal);
+	} else if (js !== undefined) {
+		install = (signal) => js.install(jsArguments(request.requirements), signal, undefined, manager);
+	}
+	if (install === undefined) {
+		throw new EnvironmentError(
+			"environment_installer_unavailable",
+			manager === "pip"
+				? "pip installs need this session to have a Python interpreter"
+				: "bun/npm installs run only in a JavaScript cell",
+		);
+	}
+	const timeout = AbortSignal.timeout(request.timeoutSeconds * 1_000);
+	const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+	try {
+		return await install(combined);
+	} catch (error) {
+		if (timeout.aborted && !(signal?.aborted ?? false)) {
+			throw new EnvironmentError(
+				"environment_install_timeout",
+				`the install did not finish within ${request.timeoutSeconds}s and was stopped`,
+			);
+		}
+		throw error;
+	}
+}

package/src/environments/project-resolves.ts

@@ -0,0 +1,54 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Whether a bare import of `name` from the session directory resolves in the project before a managed revision: the
+ * host-side twin of the kernel resolver (`kernels/js/worker-package-resolve.js` stays plain JavaScript, and a `.ts`
+ * module may not import it). Like the resolver it stops at the first `node_modules/<name>` directory up the chain,
+ * and that directory wins only when the resolver would take an entry from it.
+ */
+export function projectResolves(cwd: string, name: string): boolean {
+	for (let directory = cwd; ; directory = dirname(directory)) {
+		const packageDir = join(directory, "node_modules", name);
+		if (isDirectory(packageDir)) return hasRootEntry(packageDir);
+		if (dirname(directory) === directory) return false;
+	}
+}
+
+function hasRootEntry(packageDir: string): boolean {
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+	} catch {
+		return legacyFile(join(packageDir, "index.js"));
+	}
+	// The resolver throws on a null manifest and treats any other non-object as one without fields.
+	if (manifest === null) return true;
+	if (typeof manifest !== "object") return legacyFile(join(packageDir, "index.js"));
+	// With `exports` the resolver commits to this package: it imports the "." target or fails, never falling through.
+	if ("exports" in manifest && manifest.exports !== undefined && manifest.exports !== null) return true;
+	const moduleEntry =
+		"Bun" in globalThis && "module" in manifest && typeof manifest.module === "string" ? manifest.module : undefined;
+	const main = "main" in manifest && typeof manifest.main === "string" ? manifest.main : "index.js";
+	return legacyFile(join(packageDir, moduleEntry ?? main));
+}
+
+function legacyFile(path: string): boolean {
+	return [path, `${path}.js`, `${path}.mjs`, `${path}.cjs`, join(path, "index.js")].some(isFile);
+}
+
+function isFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}

package/src/environments/py-environment.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { assertInstalledInRevision, assertNoEditableInstalls } from "./editable-check.ts";
-import { parsePipRequirements, runPipInstall } from "./py-installer.ts";
+import { normalizePipInstall, parsePipRequirements, runPipInstall } from "./py-installer.ts";
 import { publishNextRevision, type Revision } from "./revision-store.ts";
 
 const execFileAsync = promisify(execFile);
@@ -40,12 +40,16 @@ export async function installPythonPackages(input: {
 	readonly base: string;
 	readonly mode: EnvironmentMode;
 	readonly interpreter: string;
-	readonly requirements: string;
+	/** `%pip` argument text, or the requirement list `packages.install()` passes without re-parsing. */
+	readonly requirements: string | readonly string[];
 	readonly cwd: string;
 	readonly signal: AbortSignal;
 	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
 }): Promise<InstallReceipt> {
-	const requested = parsePipRequirements(input.requirements);
+	const requested =
+		typeof input.requirements === "string"
+			? parsePipRequirements(input.requirements)
+			: normalizePipInstall(["install", ...input.requirements]);
 	let stdout = "";
 	const { revision } = await publishNextRevision(
 		input.base,