@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.9

package/CHANGELOG.md

@@ -12,6 +12,44 @@
 
 ### 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
+
+### Added
+
+- Internal groundwork for installing Python packages from a cell: per-session environment revisions that are published only after a successful install (a failed or interrupted install leaves the previous revision active), a per-root install lock, and a pip installer that always targets the session's own directory. Not exposed to cells yet ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Python kernel tools: `@tool` registers a function that in-process children can call, with its schema inferred from type hints; callbacks are served while the kernel is idle or its cell waits on a host call, never during a running computation, and a reset or redefinition makes old descriptors stale. `tool.defined()` / `tool.undefine()` in Python, and `tool_schema("eval:kernel-tools")` ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Internal groundwork for isolated sandbox cells: a vendored copy of the pi codemode runtime (QuickJS in a worker) with two opt-in host options, output streaming bounded by a credit window and a store policy that keeps no state. Nothing uses it yet ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- A cold Python kernel start on a busy machine no longer fails as a hang: startup keeps waiting while the interpreter is still using CPU or writing output, and fails only when it has gone completely still (naming the stage), or after 120 s without becoming ready ([#2718](https://github.com/code-yeongyu/senpi/issues/2718)).
+
+### Removed
+
 ## [2026.10.7] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -100,6 +100,51 @@ 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.
+
+### 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`.
+
 ## Settings
 
 Configuration is loaded in this order:
@@ -202,11 +247,12 @@ options object and asynchronous helpers are `await`-able.
 | `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. |
 | `tool(fn, metadata?)` (js) | Registers a named function as a kernel tool for in-process children. `metadata.name` registers it under that name instead of the function's; arguments are still passed in the function's parameter order. |
 | `tool.defined()` / `tool.undefine(name)` (js) | List the kernel tools this kernel defines (sorted), and remove one (`true` if it existed). A descriptor taken before `undefine` can no longer be invoked. Both names are reserved: a kernel tool can't be registered as `defined` or `undefine` (`reserved_tool_name`), and a host tool with either name is shadowed in the `tool` namespace, so it can't be called from a JavaScript cell. |
+| `@tool` / `@tool(name=, description=, schema=)` (py) | Registers a Python function as a kernel tool for in-process children; the schema is inferred from its type hints (`tool_schema("eval:kernel-tools")` lists the rules). Callbacks run while the kernel is idle or its cell is parked in a host call, never in the middle of a running computation. `tool.defined()` and `tool.undefine(name)` work as in JavaScript. Ruby and Julia kernels answer `tools_unavailable`. |
 | `completion(prompt, model?, system?, schema?)` | Requests a one-shot host completion; `schema` asks the host to parse structured output. |
 | `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. |
@@ -255,8 +301,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?}`
@@ -461,8 +510,21 @@ Homebrew (put `/opt/homebrew/opt/ruby/bin` first on `PATH`; macOS's system Ruby
 before `--write-baseline`.
 
 The report is gitignored `gate-report.json` by default (`--report <path>` overrides it).
-`test/gate/allowlist.json` contains reviewed additive changes keyed by plan node;
-it cannot authorize removal or modification of a legacy entry. The test-only
+`test/gate/allowlist.json` contains reviewed additive changes keyed by plan node.
+A pull request that changes the committed `baseline.json` itself (an intended
+schema or prompt change, a renamed contract, a deleted module) must list every
+cell it edits or removes under that node's `changes`, each as
+`{ "key": "<section>/<cell>", "reason": "..." }`. In a pull request the gate reads
+the baseline at the merge base and fails any baseline edit or removal that is
+not listed, any edited or added cell that differs from what the head measures,
+and any listed removal the head still measures. A cell written into the baseline that
+was absent at the merge base must be listed under some node's `additions` (an entry an earlier
+pull request added counts, so a re-record can write in cells approved before); only `changes`
+entries must be new in this pull request. Reviewers read each `changes`
+entry: it is the only record of why a protected surface moved. If the merge
+base cannot be resolved in a pull request, the gate fails closed; the gate job
+checks out full history for this. A local run outside a pull request reviews
+baseline changes only with `--base-ref <ref>`. The test-only
 `SENPI_CODEMODE_GATE_MUTATE=drop-phase` report mutation proves that helper removal
 is rejected. `SENPI_CODEMODE_GATE_MUTATE=leak-kernel` leaves the real kernel
 alive at the teardown witness, then closes it in `finally`; nonzero process,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.7",
+	"version": "2026.10.9",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -32,14 +32,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.7",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.9",
+		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.7"
+		"@code-yeongyu/senpi": "2026.10.9"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.7"
+		"@code-yeongyu/senpi": "2026.10.9"
 	},
 	"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/kernel-tools-protocol.ts

@@ -92,12 +92,20 @@ export const kernelToolKernelToHostSchemas = [
 		requestId: Type.String({ minLength: 1 }),
 		ok: Type.Literal(true),
 		value: Type.Unknown(),
+		/** Python: text the tool printed during this call (never the parent cell's output). */
+		output: Type.Optional(Type.String()),
 	}),
 	Type.Object({
 		type: Type.Literal("kernel-tool-invoke-reply"),
 		requestId: Type.String({ minLength: 1 }),
 		ok: Type.Literal(false),
 		error: kernelToolErrorSchema,
+		output: Type.Optional(Type.String()),
+	}),
+	/** Python: the kernel's tool names after a define or undefine, for cross-language collision checks. */
+	Type.Object({
+		type: Type.Literal("kernel-tools-defined"),
+		names: Type.Array(Type.String({ minLength: 1 })),
 	}),
 ] as const;
 

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: {
@@ -69,9 +70,30 @@ const helpersEntry: EvalSchemaResult = {
 	},
 };
 
+const kernelToolsEntry: EvalSchemaResult = {
+	name: "eval:kernel-tools",
+	description: [
+		"Kernel tools: functions a cell defines that in-process children can call (js and py; rb/jl answer tools_unavailable).",
+		"js: tool(fn, {name?, description?, schema?}) registers a named function; arguments are passed in its parameter order; without schema only the parameter names are inferred and every one is required.",
+		'py: @tool or @tool(name=..., description=..., schema=...) registers the function and returns it unchanged. The schema is inferred from type hints (str, int, float, bool, None, list[T], dict[str, T], Literal, unions and Optional as nullable, Annotated[T, "description"], keyword-only parameters); a JSON default makes a parameter optional; string annotations (from __future__ import annotations) resolve through the function\'s globals. Positional-only, *args, **kwargs and unresolvable or unsupported annotations are refused with invalid_tool_definition unless schema= is given. The function is never called to infer anything.',
+		"tool.defined() lists this kernel's kernel tools (sorted); tool.undefine(name) removes one (true if it existed). The names defined and undefine are reserved.",
+		"Grants: a child is given descriptors (name, kernel_generation, definition_revision) before it starts. A reset, restart or redefinition makes an old descriptor fail with kernel_tool_stale; the new definition never satisfies it. A name defined in both js and py fails describe with tool_name_collision.",
+		"py callbacks run while the kernel is idle or its cell is parked in a host call (a tool call, wait(), an install); a cell busy in pure computation is never interrupted, the callback waits. A callback's printed text goes to its own reply, never the parent cell's output. Cancelling a call ends it at its next host call (kernel_tool_cancelled); a computation already running finishes and its result is dropped. An awaited object from the parent cell's event loop fails with kernel_tool_loop_mismatch.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			tool: { description: "js: tool(fn, metadata?); py: @tool / @tool(name=, description=, schema=)" },
+			"tool.defined": { description: "() -> names[]" },
+			"tool.undefine": { description: "(name) -> boolean" },
+		},
+	},
+};
+
 const VIRTUAL_ENTRIES: ReadonlyMap<string, EvalSchemaResult> = new Map([
 	[waitEntry.name, waitEntry],
 	[helpersEntry.name, helpersEntry],
+	[kernelToolsEntry.name, kernelToolsEntry],
 ]);
 
 export function virtualEvalSchema(name: string): EvalSchemaResult | undefined {

package/src/environments/editable-check.ts

@@ -0,0 +1,116 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { EnvironmentError } from "./py-installer.ts";
+
+/**
+ * Refuses a staged revision that links to code outside itself: a PEP 660 editable install
+ * (`direct_url.json` with `dir_info.editable`), a legacy `setup.py develop` (`.egg-link`), a `.pth` path
+ * line that resolves outside the revision, or a symlink anywhere in it that does. `.pth` lines starting
+ * with `import` are code that runs at startup, like any installed package's code, and are not inspected.
+ * A refused revision is never published.
+ */
+export async function assertNoEditableInstalls(staging: string): Promise<void> {
+	const root = await realpath(staging).catch(() => resolve(staging));
+	let entries: string[];
+	try {
+		entries = await readdir(staging);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const path = join(staging, entry);
+		if (entry.endsWith(".egg-link"))
+			refuse(entry.replace(/\.egg-link$/u, ""), "a legacy editable install (.egg-link)");
+		if (
+			entry.endsWith(".dist-info") &&
+			isEditable(await readFile(join(path, "direct_url.json"), "utf8").catch(() => ""))
+		) {
+			refuse(entry.replace(/\.dist-info$/u, ""), "an editable install");
+		}
+		if (entry.endsWith(".pth")) {
+			for (const line of (await readFile(path, "utf8").catch(() => "")).split(/\r?\n/u)) {
+				const text = line.trim();
+				if (text === "" || text.startsWith("#") || text.startsWith("import ")) continue;
+				if (!(await inside(root, resolve(staging, text))))
+					refuse(entry, `a path outside the environment (${text})`);
+			}
+		}
+	}
+	await refuseOutsideLinks(root, staging);
+}
+
+/** Every symlink in the revision, at any depth, must resolve inside it; links are checked, not followed. */
+async function refuseOutsideLinks(root: string, dir: string): Promise<void> {
+	for (const entry of await readdir(dir)) {
+		const path = join(dir, entry);
+		const info = await lstat(path);
+		if (info.isSymbolicLink()) {
+			if (!(await inside(root, path))) refuse(relative(root, path), "a link that points outside the environment");
+		} else if (info.isDirectory()) {
+			await refuseOutsideLinks(root, path);
+		}
+	}
+}
+
+/**
+ * pip reports what it installed; each of those distributions must be in the revision. A configuration
+ * that redirects pip elsewhere (a target, root or prefix from any config file or variable, on any pip
+ * version) leaves them missing here, so the install fails instead of publishing an empty revision.
+ */
+export async function assertInstalledInRevision(stdout: string, staging: string): Promise<void> {
+	const line = stdout.split("\n").find((entry) => entry.startsWith("Successfully installed "));
+	if (line === undefined) return;
+	const present = new Set((await readdir(staging).catch(() => [] as string[])).flatMap(installedName));
+	for (const token of line.slice("Successfully installed ".length).trim().split(/\s+/u)) {
+		const name = token.slice(0, token.lastIndexOf("-"));
+		if (!present.has(canonicalName(name))) {
+			throw new EnvironmentError(
+				"environment_install_failed",
+				`${name} was installed outside the session's environment (pip's configuration redirected it); nothing was published`,
+			);
+		}
+	}
+}
+
+/**
+ * The project a metadata entry records: `name-version.dist-info` (wheels), or `name-version[-pyX.Y].egg-info`
+ * (a setup.py project pip <= 23.0 installs without the wheel package). Both escape `-` in the name to `_`.
+ */
+function installedName(entry: string): string[] {
+	if (entry.endsWith(".dist-info")) {
+		const stem = entry.slice(0, -".dist-info".length);
+		return [canonicalName(stem.slice(0, stem.lastIndexOf("-")))];
+	}
+	if (entry.endsWith(".egg-info")) return [canonicalName(entry.split("-")[0] ?? "")];
+	return [];
+}
+
+function canonicalName(name: string): string {
+	return name.toLowerCase().replace(/[-_.]+/gu, "_");
+}
+
+async function inside(root: string, path: string): Promise<boolean> {
+	const real = await realpath(path).catch(() => resolve(path));
+	const rel = relative(root, real);
+	return (
+		rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith(sep) && !/^[A-Za-z]:/u.test(rel))
+	);
+}
+
+function refuse(name: string, what: string): never {
+	throw new EnvironmentError(
+		"environment_install_failed",
+		`${name} was installed as ${what}; packages must live in the session's environment root, so editable and linked installs are not allowed`,
+	);
+}
+
+function isEditable(text: string): boolean {
+	try {
+		const value: unknown = JSON.parse(text);
+		if (typeof value !== "object" || value === null || !("dir_info" in value)) return false;
+		const dirInfo = value.dir_info;
+		return typeof dirInfo === "object" && dirInfo !== null && "editable" in dirInfo && dirInfo.editable === true;
+	} catch {
+		return false;
+	}
+}

package/src/environments/install-lock.ts

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { link, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+const LOCK_FILE = ".install.lock";
+const REAP_PREFIX = ".install.lock.reap.";
+const RECHECK_MS = 500;
+// An unparseable lock can only come from a crash in an older version's create-then-write; it is stale once old.
+const UNREADABLE_STALE_MS = 5_000;
+const WAIT_NOTICE_MS = 30_000;
+
+type Holder = { readonly pid: number; readonly host: string; readonly nonce: string };
+
+export type LockWaitNotice = {
+	readonly holder: { readonly pid: number; readonly host: string } | undefined;
+	readonly waitedMs: number;
+};
+
+/**
+ * Serialises installs into one environment root across sessions and processes.
+ *
+ * The lock file is published complete (written to a unique temp file, then `link`ed into place, which fails
+ * if a lock exists), so it is never seen empty. A lock whose holder is a dead process on this host, or
+ * that is unreadable and old, is stale. Each lock incarnation has its own key (its holder's nonce), and
+ * only the waiter that exclusively creates the reap claim for that key may remove it, after re-reading the
+ * lock under the claim and finding the same incarnation. A stale incarnation's holder is dead and nobody
+ * else may remove it, so it can't change between that re-read and the removal: a live lock is never
+ * deleted. A claimer that dies passes the claim on to the next claim in the chain.
+ */
+export async function withRootLock<T>(
+	base: string,
+	fn: () => Promise<T>,
+	signal?: AbortSignal,
+	onWait?: (notice: LockWaitNotice) => void,
+): Promise<T> {
+	const path = join(base, LOCK_FILE);
+	const mine: Holder = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+	const started = Date.now();
+	let noticed = false;
+	for (;;) {
+		signal?.throwIfAborted();
+		if (await tryCreate(base, path, mine)) break;
+		if (await takeOverIfStale(base, path)) continue;
+		if (!noticed && Date.now() - started >= WAIT_NOTICE_MS) {
+			noticed = true;
+			const holder = await readHolder(path);
+			onWait?.({ holder: holder && { pid: holder.pid, host: holder.host }, waitedMs: Date.now() - started });
+		}
+		await waitForRelease(base, path, signal);
+	}
+	try {
+		return await fn();
+	} finally {
+		const holder = await readHolder(path);
+		if (holder?.nonce === mine.nonce) await rm(path, { force: true });
+	}
+}
+
+async function tryCreate(base: string, path: string, holder: Holder): Promise<boolean> {
+	const temp = join(base, `.install.lock.${holder.nonce}`);
+	await writeFile(temp, JSON.stringify(holder), { mode: 0o600 });
+	try {
+		await link(temp, path);
+		return true;
+	} catch (error) {
+		if (errorCode(error) === "EEXIST") return false;
+		throw error;
+	} finally {
+		await rm(temp, { force: true });
+	}
+}
+
+async function takeOverIfStale(base: string, path: string): Promise<boolean> {
+	const key = await staleKey(path);
+	if (key === undefined) return false;
+	const claim = await claimReap(base, key);
+	if (claim === undefined) return false;
+	try {
+		// Under the claim nobody else may remove this incarnation, and its holder is dead, so it is still the
+		// lock judged stale exactly when it still has the same key.
+		if ((await staleKey(path)) !== key) return false;
+		await rm(path, { force: true });
+		await removeDeadClaims(base, key);
+		return true;
+	} finally {
+		await rm(claim, { force: true });
+	}
+}
+
+/** Once the incarnation is gone, its claims only matter to waiters that will find a different lock. */
+async function removeDeadClaims(base: string, key: string): Promise<void> {
+	const prefix = `${REAP_PREFIX}${key}.`;
+	for (const name of (await readdir(base)).filter((entry) => entry.startsWith(prefix))) {
+		const holder = await readHolder(join(base, name));
+		if (holder !== undefined && holder.host === hostname() && !isAlive(holder.pid))
+			await rm(join(base, name), { force: true });
+	}
+}
+
+/**
+ * Creates the next free reap claim for one lock incarnation: `<key>.0`, or the claim after the last one
+ * whose holder died. Returns undefined when a live waiter already holds it.
+ */
+async function claimReap(base: string, key: string): Promise<string | undefined> {
+	for (let depth = 0; ; depth++) {
+		const claim = join(base, `${REAP_PREFIX}${key}.${depth}`);
+		if (await tryCreate(base, claim, { pid: process.pid, host: hostname(), nonce: randomUUID() })) return claim;
+		const holder = await readHolder(claim);
+		// Gone again (its holder finished): the caller re-reads the lock and retries.
+		if (holder === undefined) return undefined;
+		if (holder.host !== hostname() || isAlive(holder.pid)) return undefined;
+	}
+}
+
+async function reapInProgress(base: string, key: string): Promise<boolean> {
+	const prefix = `${REAP_PREFIX}${key}.`;
+	let names: string[];
+	try {
+		names = (await readdir(base)).filter((name) => name.startsWith(prefix));
+	} catch {
+		return false;
+	}
+	for (const name of names) {
+		const holder = await readHolder(join(base, name));
+		if (holder !== undefined && holder.host === hostname() && isAlive(holder.pid)) return true;
+	}
+	return false;
+}
+
+/** The incarnation key of a stale lock (its holder's nonce, or its inode when unreadable), else undefined. */
+async function staleKey(path: string): Promise<string | undefined> {
+	let content: string;
+	try {
+		content = await readFile(path, "utf8");
+	} catch {
+		return undefined;
+	}
+	const holder = parseHolder(content);
+	if (holder !== undefined && (holder.host !== hostname() || isAlive(holder.pid))) return undefined;
+	if (holder !== undefined && /^[\w-]+$/u.test(holder.nonce)) return holder.nonce;
+	try {
+		const info = await stat(path);
+		// A dead holder's lock without a usable nonce, or an unreadable old one, is keyed by its inode.
+		return holder !== undefined || Date.now() - info.mtimeMs > UNREADABLE_STALE_MS ? `ino${info.ino}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function readHolder(path: string): Promise<Holder | undefined> {
+	try {
+		return parseHolder(await readFile(path, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+function parseHolder(content: string): Holder | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(content);
+	} catch {
+		return undefined;
+	}
+	if (typeof value !== "object" || value === null) return undefined;
+	const pid = "pid" in value ? value.pid : undefined;
+	const host = "host" in value ? value.host : undefined;
+	const nonce = "nonce" in value ? value.nonce : undefined;
+	return typeof pid === "number" && typeof host === "string"
+		? { pid, host, nonce: typeof nonce === "string" ? nonce : "" }
+		: undefined;
+}
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return errorCode(error) !== "ESRCH";
+	}
+}
+
+function errorCode(error: unknown): string | undefined {
+	return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+
+/** Wakes when the lock file goes away; the periodic recheck covers dropped file-watch events and staleness. */
+function waitForRelease(base: string, path: string, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const watcher = watch(base, () => check());
+		const timer = setInterval(() => check(), RECHECK_MS);
+		const onAbort = () => done(() => reject(signal?.reason));
+		signal?.addEventListener("abort", onAbort, { once: true });
+		let settled = false;
+		function done(settle: () => void): void {
+			if (settled) return;
+			settled = true;
+			watcher.close();
+			clearInterval(timer);
+			signal?.removeEventListener("abort", onAbort);
+			settle();
+		}
+		function check(): void {
+			void stat(path).then(
+				// A stale lock is worth retrying only when no live waiter is already reaping it; otherwise wait.
+				() =>
+					staleKey(path).then(
+						async (key) => key !== undefined && !(await reapInProgress(base, key)) && done(resolve),
+					),
+				() => done(resolve),
+			);
+		}
+		// An abort during the claim inspection that led here fired before this listener existed.
+		if (signal?.aborted) {
+			onAbort();
+			return;
+		}
+		// The holder may have released between the failed create and the watcher starting; no event would follow.
+		check();
+	});
+}