@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.10

package/CHANGELOG.md

@@ -12,6 +12,48 @@
 
 ### 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
+
+### Added
+
+- Python `agent(prompt, tools=[...])` grants the child the cell's `@tool` functions by name, like JavaScript's `agent(prompt, { tools })`; anything other than a list of names is refused with `invalid_tools` ([#2731](https://github.com/code-yeongyu/senpi/issues/2731)).
+- `workpool(agent, name, {mode, tools})` forwards `tools`, a list of kernel-tool names the cell defined, to the host workpool unchanged in all four languages, so pool workers can call them; anything other than a list of names is refused with `invalid_tools` before reaching the host. Which kernels' tools a host accepts is the host's call: JavaScript `tool(fn)` tools work on omo today, while Python `@tool` tools need omo#9529 ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A Python or JavaScript cell that is only `%load <path>` runs that local file as the cell: its definitions persist, Python tracebacks name the file and its sibling modules import, and JavaScript resolves the file's relative imports from its directory; remote URLs are refused ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A Python cell that is only `%pip install <requirements>` installs packages without restarting the kernel; the next cell imports them. Packages go into the session's own environment (or `<cwd>/.senpi/python-packages` after `%environment project`), never the interpreter's site-packages or the user site, and a failed or cancelled install leaves the previous packages active ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- A Python cell can now grant its `@tool` functions to a child ([#2731](https://github.com/code-yeongyu/senpi/issues/2731)). Host calls from Python cells (`tool.task(..., tools=[...])`, `agent(..., tools=[...])`, `workpool(..., tools=[...])`) reached the host with no kernel-tools capability, so every such grant was refused as unavailable. Each call now carries its cell, and the host gives it that cell's capability while the cell runs; a call from another, unknown or finished cell gets none.
+- `%pip` parsing follow-ups ([#2689](https://github.com/code-yeongyu/senpi/pull/2689)): a `%pip` or `%environment` line after code now says to put it on its own cell instead of "Unsupported line magic"; a comment line ending in a backslash no longer swallows the `%pip` line after it; inside double quotes a backslash is kept unless it escapes a quote, backslash, `$` or a backtick, as a POSIX shell does.
+
+### Removed
+
 ## [2026.10.8] - 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`,
@@ -100,6 +106,93 @@ getter and may name a file that does not exist yet. It honors session-directory
 and in-memory sessions; it cannot be derived reliably from `PI_SESSION_FILE`. If the host
 omits the getter, the variable is unset rather than inherited from the launching process.
 
+### Loading a file
+
+A Python or JavaScript cell whose only line is `%load <path>` reads that file and
+runs it as the cell, so its definitions persist like any cell. The path is relative
+to the session directory, or a `local://` or `file://` URL; other URL schemes are
+refused and nothing is fetched. The cell runs as its file: Python compiles it under
+the file's name, so tracebacks name the file and line, and sets `__file__` and puts
+the file's directory first on the import path, so `from sibling import g` resolves
+next to it. JavaScript evaluates it under the file's name and resolves its relative
+imports from the file's directory. The file is read when the cell's turn comes in
+the kernel's queue, so a `%load` queued behind the cell that writes the file runs
+what that cell wrote. When the cell ends, Python takes the file's directory back off
+the import path and restores `__file__`, so later cells import as before. A file that
+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
+without restarting the kernel: variables, the process and its working directory
+stay as they were. The cell runs in the kernel's queue like any other cell (it waits
+for the cell ahead of it, can be cancelled while queued, and detaches past the
+foreground window), but the install runs on the host, so its time does not count
+against the run budget. The next cell imports the new packages; modules a cell
+already imported stay cached until `reset`.
+
+Packages go into the session's own environment, never into the interpreter's
+site-packages or the user site: pip always runs as
+`<kernel interpreter> -m pip install --target <environment>`, and flags that pick
+another destination (`--target`, `--user`, `--prefix`, `--root`, `--home`,
+`-e`) are refused. Each install builds a new revision of the environment and
+publishes it only when pip succeeds, so a failed or cancelled install leaves the
+previous packages active and importable. A cell that mixes `%pip` with code is
+refused; put `%pip` on its own cell.
+
+`%environment managed` (the default) keeps the environment under the session's
+artifacts directory, or `environments.managedRoot` when set; `%environment project`
+installs into `<cwd>/.senpi/python-packages` instead, shared by every session in
+that project, with concurrent installs serialised by a lock. Setting
+`environments.autoProvision` to `false` turns installs off
+(`environment_installer_unavailable`). Failures carry pip's error output and one
+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:
@@ -173,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`
@@ -207,7 +300,7 @@ options object and asynchronous helpers are `await`-able.
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
 | `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
 | `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
-| `workpool(agent, name, mode?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. |
+| `workpool(agent, name, mode?, tools?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. `tools` is a list of kernel-tool names this cell defined; the pool's workers may call exactly those, the host refuses any name the caller doesn't hold, and a value that isn't a list of names raises `invalid_tools`. Ruby and Julia define no kernel tools, so they have nothing to grant. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |
 | `pipeline(items, ...stages)` | Applies stages left to right with a barrier between stages. |
@@ -256,8 +349,11 @@ Any isolation metadata supplied by the host on a handle is preserved as
 `{subagent_type, prompt, model?}` as its plain-data agent spec. Mode is `fresh`
 or `keep_alive`: pass `{mode: "fresh"}` in JS, `mode="fresh"` in Python/Julia,
 or `mode: "fresh"` in Ruby. Omission is forwarded unchanged to the engine;
-hosts without an approved default still require an explicit mode. Custom tool
-names are not enabled by this adapter.
+hosts without an approved default still require an explicit mode. `tools`
+(kernel-tool names, for example from Python `@tool` or JavaScript `tool(fn)`) is
+forwarded unchanged to the host's `create`, which validates it: `{tools: ["add"]}`
+in JS, `tools=["add"]` in Python/Julia, `tools: ["add"]` in Ruby. There is no
+`pool.wait()`; the host delivers the aggregate.
 
 `push` forwards `[{key, input}]` and returns the host receipt without waiting
 for admission. Operations return the same `{text, details, images?, hasError?}`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.8",
+	"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.8",
+		"@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.8"
+		"@code-yeongyu/senpi": "2026.10.10"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.8"
+		"@code-yeongyu/senpi": "2026.10.10"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/http-server.ts

@@ -8,6 +8,8 @@ const LOOPBACK_HOST = "127.0.0.1";
 
 export interface BridgeHttpCallRequest {
 	callId: string;
+	/** The calling run's secret; the host resolves that run's kernel-tools capability from it. */
+	cellToken?: string;
 	toolName: string;
 	args: unknown;
 	signal: AbortSignal;
@@ -132,7 +134,13 @@ async function dispatchCall(body: unknown, options: BridgeServerOptions, signal:
 	try {
 		return {
 			ok: true,
-			value: await options.onCall({ callId: body.callId, toolName: body.toolName, args: body.args, signal }),
+			value: await options.onCall({
+				callId: body.callId,
+				...(typeof body.cellToken === "string" ? { cellToken: body.cellToken } : {}),
+				toolName: body.toolName,
+				args: body.args,
+				signal,
+			}),
 		};
 	} catch (error) {
 		return { ok: false, error: bridgeError(error) };

package/src/bridge/protocol.ts

@@ -44,6 +44,10 @@ const hostToKernelMessageSchema = Type.Union([
 		cellId: Type.String({ minLength: 1 }),
 		code: Type.String(),
 		timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+		/** Python only: the published environment revision to import from, applied before the cell runs; empty removes the previous one. */
+		envRoot: Type.Optional(Type.String()),
+		/** The file a `%load` cell runs; the runner compiles under its name and imports beside it. */
+		sourceFile: Type.Optional(Type.String({ minLength: 1 })),
 		/** Python only: active tool globals to install before the cell and deactivated ones to remove. */
 		preludes: Type.Optional(
 			Type.Object({

package/src/bridges/eval-virtual-schemas.ts

@@ -52,6 +52,7 @@ const helpersEntry: EvalSchemaResult = {
 		"control.status() goes through the host subscription; control.send/cancel/output are fenced by owner, id and run_epoch inside the task owner (stale -> eval_handle_stale, foreign -> eval_handle_forbidden); control.output() returns only that epoch's transcript. The plain output() helper and task tools are unchanged.",
 		"The legacy agent(..., {handle: true}) record is unchanged: .output stays a string and no enumerable key is added. A saved {kind, id, run_epoch} (or the record itself) can be rebound with handle(ref) in a later cell or after a kernel reset while the owner and run epoch are valid.",
 		"completion(prompt, {handle: true}) (py: handle=True) returns a control handle after preflight validation; provider failures surface in its outcome; its deadline derives from the creating cell's hard deadline. Completion handles are codemode-owned and need no host capability; once the session generation is dropped they fail with eval_handle_stale.",
+		"workpool(agent, name, {mode?, tools?}) (py/jl: mode=, tools=; rb: mode:, tools:) forwards tools (kernel-tool names, e.g. from @tool or tool(fn)) unchanged to the host workpool tool's create; the host checks them. There is no pool.wait(): the host delivers the aggregate and the kernel stays free to serve kernel tools.",
 		"See tool_schema('eval:wait') for the barrier semantics.",
 	].join("\n"),
 	parameters: {

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