@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10

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/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/revision-store.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { type LockWaitNotice, withRootLock } from "./install-lock.ts";
+import { assertLinkStaysInside, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
 import { EnvironmentError } from "./py-installer.ts";
 
 const POINTER = "active";
@@ -50,7 +51,7 @@ export async function publishNextRevision(
 	signal?: AbortSignal,
 	onLockWait?: (notice: LockWaitNotice) => void,
 ): Promise<{ readonly revision: Revision; readonly previous: Revision | undefined }> {
-	await mkdir(base, { recursive: true });
+	await mkdirPrivate(base);
 	return withRootLock(
 		base,
 		async () => {
@@ -59,8 +60,18 @@ export async function publishNextRevision(
 			const staging = join(base, `.staging-rev-${number}-${process.pid}-${randomUUID()}`);
 			const dir = join(base, `rev-${number}`);
 			try {
-				if (previous === undefined) await mkdir(staging, { recursive: true });
-				else await cp(previous.dir, staging, { recursive: true, verbatimSymlinks: true });
+				if (previous === undefined) await mkdir(staging, { mode: 0o700 });
+				else {
+					await assertNoLinksBelow(base, previous.dir);
+					const sources = await recordedInstallSources(previous.dir);
+					await cp(previous.dir, staging, {
+						recursive: true,
+						verbatimSymlinks: true,
+						filter: async (source) => await assertLinkStaysInside(source, previous.dir, sources),
+					});
+				}
+				// Explicit, not left to the umask: a revision holds the user's installed packages and carried registry config.
+				await chmod(staging, 0o700);
 				await build(staging, previous);
 				signal?.throwIfAborted();
 				await renameRetrying(staging, dir);
@@ -108,3 +119,8 @@ async function highestRevision(base: string): Promise<number> {
 	}
 	return highest;
 }
+
+/** Creates `dir` and any missing parents private to the user (0700; the umask can only narrow it further). */
+export async function mkdirPrivate(dir: string): Promise<void> {
+	await mkdir(dir, { recursive: true, mode: 0o700 });
+}

package/src/extension/runtime-factory.ts

@@ -8,6 +8,7 @@ import {
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import { JsEnvironments } from "../environments/js-environments.ts";
 import { PythonEnvironments } from "../environments/python-environments.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
@@ -49,6 +50,7 @@ export type SessionRuntime = {
 	readonly executeTool: AgentExecuteTool;
 	readonly spawns: boolean;
 	readonly pythonEnvironments?: PythonEnvironments;
+	readonly jsEnvironments: JsEnvironments;
 };
 
 export async function createRuntime(
@@ -98,6 +100,13 @@ export async function createRuntime(
 		artifactsDir: artifacts.dir,
 		executeTool,
 		spawns: activeTools.has(settings.taskTools.task),
+		jsEnvironments: new JsEnvironments({
+			artifactsDir: artifacts.dir,
+			cwd: ctx.cwd,
+			runtime: jsRuntimeInfo().name,
+			env: { ...process.env, ...sessionEnv },
+			settings,
+		}),
 		...(availability.py.detected.ok && enabledLanguages.py
 			? {
 					pythonEnvironments: new PythonEnvironments({

package/src/index.ts

@@ -158,6 +158,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 					settings: runtime.settings,
 					artifactsDir: runtime.artifactsDir,
 					...(runtime.pythonEnvironments === undefined ? {} : { pythonEnvironments: runtime.pythonEnvironments }),
+					jsEnvironments: runtime.jsEnvironments,
 					cellManager,
 					handles,
 					executionTracker: manager,

package/src/kernels/js/cell-dispatch.ts

@@ -0,0 +1,44 @@
+import type { HostToKernelMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
+import { refusedEntry } from "./host-entries.ts";
+import {
+	type JavaScriptKernelOptions,
+	type JavaScriptRunInput,
+	resolveKernelToolNameSource,
+} from "./kernel-contract.ts";
+import type { LocalModuleLoader } from "./local-module-loader.ts";
+
+export type CellDispatch =
+	| { readonly kind: "host"; readonly host: HostCellExecutor }
+	| { readonly kind: "worker"; readonly frames: readonly HostToKernelMessage[] };
+
+/**
+ * Decides at the cell's turn how it runs: as a host entry (an install, or a turn-time refusal such as an unreadable
+ * `%load` file) or in the worker, with the frames the worker needs (the current kernel-tool names, then the cell).
+ */
+export function dispatchCell(
+	queued: JavaScriptRunInput,
+	loader: LocalModuleLoader,
+	options: Pick<JavaScriptKernelOptions, "hostToolNames" | "foreignLanguageNames">,
+): CellDispatch {
+	const input = inputAtStart(queued);
+	if ("refused" in input) return { kind: "host", host: refusedEntry(input.refused) };
+	if (input.host !== undefined) return { kind: "host", host: input.host };
+	return {
+		kind: "worker",
+		frames: [
+			{
+				type: "kernel-tools-names",
+				hostToolNames: resolveKernelToolNameSource(options.hostToolNames),
+				foreignLanguageNames: resolveKernelToolNameSource(options.foreignLanguageNames),
+			},
+			{
+				type: "run",
+				cellId: input.cellId,
+				code: loader.prepareCell(input.code, input.kernelPreludes, input.sourceFile, input.packageRoot?.()),
+				timeoutMs: input.timeoutMs,
+			},
+		],
+	};
+}

package/src/kernels/js/context-manager.ts

@@ -1,17 +1,17 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
-import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
-import { DEFAULT_INTERRUPT_BOUNDS, type WorkerRetirement } from "./interrupt-bounds.ts";
+import { dispatchCell } from "./cell-dispatch.ts";
+import { HostEntries } from "./host-entries.ts";
+import { DEFAULT_INTERRUPT_BOUNDS, JS_INTERRUPT_GRACE_MS, type WorkerRetirement } from "./interrupt-bounds.ts";
 import {
 	assertJavaScriptKernelOpen,
 	type JavaScriptKernelMode,
 	type JavaScriptRunInput,
 	type LifecycleState,
 	type ResultMessage,
-	resolveKernelToolNameSource,
 	type ToolCallMessage,
 } from "./kernel-contract.ts";
 import { type JavaScriptMemoryReading, KernelMemoryBridge } from "./kernel-memory-bridge.ts";
@@ -22,7 +22,7 @@ import type {
 	KernelToolsInvokeRequest,
 } from "./kernel-tools-types.ts";
 import { type JavaScriptKernelOptions, LocalModuleLoader } from "./local-module-loader.ts";
-import { JavaScriptRunQueue } from "./run-queue.ts";
+import { JavaScriptRunQueue, type PendingJavaScriptRun } from "./run-queue.ts";
 import { ToolCallQueue } from "./tool-call-queue.ts";
 import { WorkerChildren } from "./worker-children.ts";
 import { crashedResult } from "./worker-host.ts";
@@ -35,6 +35,15 @@ export type { JavaScriptKernelOptions } from "./local-module-loader.ts";
 export { type JavaScriptWorkerEntryUrlOptions, resolveJsWorkerEntryUrl } from "./worker-startup.ts";
 
 export class JavaScriptKernel {
+	readonly #hostEntries = new HostEntries<PendingJavaScriptRun>({
+		emit: (run, message) => (run.input.onMessage ?? this.#options.onMessage)?.(message),
+		settle: (run, result) => {
+			if (!this.#runs.releaseActive(run)) return;
+			this.#runs.settle(run, result);
+			this.#startNext();
+		},
+		durationMs: (run) => this.#runs.durationMs(run, performance.now()),
+	});
 	readonly #options: JavaScriptKernelOptions;
 	readonly #moduleLoader: LocalModuleLoader;
 	readonly #slot: WorkerSlot;
@@ -129,6 +138,7 @@ export class JavaScriptKernel {
 			const cancelled = this.cancelQueued(cellId, reason);
 			return { stateRetained: Promise.resolve(true), ...(cancelled ? {} : { note: "cell not found" }) };
 		}
+		if (active && this.#hostEntries.abort(active, reason)) return { stateRetained: Promise.resolve(true) };
 		if (!active) {
 			// A worker still stuck in startup is not a healthy idle worker: retiring it is the only recovery.
 			const wedgedInStartup = this.#slot.startingUp;
@@ -163,11 +173,14 @@ export class JavaScriptKernel {
 		if (this.#closePromise) return await this.#closePromise;
 		this.#slot.postMessage({ type: "close" });
 		this.#lifecycle = "closing";
+		const graceMs = this.#options.interruptBounds?.graceMs ?? JS_INTERRUPT_GRACE_MS;
+		const hostEntriesStopped = this.#hostEntries.stopAll("JS kernel closed", graceMs);
 		this.#runs.settleAll("JS kernel closed");
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", "JS kernel closed"));
 		this.#toolCalls.clear();
 		const recovery = this.#recovery.inFlight;
 		const closePromise = (async () => {
+			await hostEntriesStopped;
 			if (recovery) await recovery;
 			await this.#terminate();
 		})().finally(() => {
@@ -196,31 +209,13 @@ export class JavaScriptKernel {
 		if (this.#lifecycle !== "open" || this.#runs.active || !this.#slot.present) return;
 		const next = this.#runs.startNext(performance.now());
 		if (!next) return;
-		const input = inputAtStart(next.input);
-		if ("refused" in input) {
-			this.#runs.releaseActive(next);
-			this.#runs.settle(next, {
-				type: "result",
-				cellId: next.input.cellId,
-				ok: false,
-				error: { message: input.refused },
-				durationMs: 0,
-			});
-			this.#startNext();
+		const dispatch = dispatchCell(next.input, this.#moduleLoader, this.#options);
+		if (dispatch.kind === "host") {
+			this.#hostEntries.start(next, dispatch.host);
 			return;
 		}
 		this.#activeCell.arm(next);
-		this.#slot.postMessage({
-			type: "kernel-tools-names",
-			hostToolNames: resolveKernelToolNameSource(this.#options.hostToolNames),
-			foreignLanguageNames: resolveKernelToolNameSource(this.#options.foreignLanguageNames),
-		});
-		this.#slot.postMessage({
-			type: "run",
-			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(input.code, input.kernelPreludes, input.sourceFile),
-			timeoutMs: next.input.timeoutMs,
-		});
+		for (const frame of dispatch.frames) this.#slot.postMessage(frame);
 	}
 
 	async #restartAfterStop(): Promise<void> {
@@ -261,7 +256,8 @@ export class JavaScriptKernel {
 		this.#activeCell.disarm();
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", error.message));
 		this.#memory.workerLost(error);
-		if (active) {
+		// A crash mid-install stops the install (process group killed, nothing published); it settles itself once stopped.
+		if (active && !this.#hostEntries.abort(active, `JavaScript worker crashed: ${error.message}`)) {
 			this.#runs.releaseActive(active);
 			this.#runs.settle(
 				active,

package/src/kernels/js/host-entries.ts

@@ -0,0 +1,62 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+import { runHostCell } from "../shared/host-cell.ts";
+import type { ResultMessage } from "./kernel-contract.ts";
+
+export interface HostEntryKernel<Run> {
+	emit(run: Run, message: KernelToHostMessage): void;
+	settle(run: Run, result: ResultMessage): void;
+	durationMs(run: Run): number;
+}
+
+/** The host entries (installs) a JavaScript kernel is running: started per queue slot, stopped by interrupt and close. */
+export class HostEntries<Run extends { readonly input: { readonly cellId: string } }> {
+	readonly #aborts = new Map<Run, AbortController>();
+	readonly #done = new Map<Run, Promise<unknown>>();
+	readonly #kernel: HostEntryKernel<Run>;
+
+	constructor(kernel: HostEntryKernel<Run>) {
+		this.#kernel = kernel;
+	}
+
+	/** Runs `host` for `run`'s queue slot; it holds the slot like a cell but never reaches the worker. */
+	start(run: Run, host: HostCellExecutor): void {
+		const entry = runHostCell(run.input.cellId, host, {
+			emit: (message) => this.#kernel.emit(run, message),
+			settle: (result) => {
+				this.#aborts.delete(run);
+				this.#kernel.settle(run, result);
+			},
+			durationMs: () => this.#kernel.durationMs(run),
+			settleAfterAbort: true,
+		});
+		this.#aborts.set(run, entry.abort);
+		this.#done.set(run, entry.done);
+		void entry.done.finally(() => this.#done.delete(run));
+	}
+
+	/** Aborts `run`'s host entry; false when `run` is not one. */
+	abort(run: Run, reason: string): boolean {
+		const abort = this.#aborts.get(run);
+		if (abort === undefined) return false;
+		abort.abort(new Error(reason));
+		return true;
+	}
+
+	/** Aborts every running entry and waits for them to stop, at most `ms`: a closed kernel leaves no install running. */
+	async stopAll(reason: string, ms: number): Promise<void> {
+		const running = [...this.#done.values()];
+		for (const abort of this.#aborts.values()) abort.abort(new Error(reason));
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		await Promise.race([
+			Promise.allSettled(running),
+			new Promise<void>((resolve) => (timer = setTimeout(resolve, ms))),
+		]);
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+/** A turn-time refusal (an unreadable `%load` file, a refused magic) settles in queue order as a failed host entry. */
+export function refusedEntry(message: string): HostCellExecutor {
+	return async () => ({ ok: false, error: { message } });
+}

package/src/kernels/js/local-module-loader.ts

@@ -98,7 +98,13 @@ function loaderPrelude(context: RuntimeModuleContext): string {
 		"    const urlModule = await import('node:url');",
 		"    target = urlModule.pathToFileURL(specifier).href;",
 		"  }",
-		"  return options === undefined ? import(target) : import(target, options);",
+		"  const load = (resolved) => (options === undefined ? import(resolved) : import(resolved, options));",
+		"  const resolvePackage = globalThis[Symbol.for('senpi.kernel.resolvePackage')];",
+		"  if (target === specifier && typeof resolvePackage === 'function') {",
+		"    const resolved = resolvePackage(specifier, [context.cwdUrl, context.packageRootUrl]);",
+		"    if (resolved !== undefined) return await load(resolved);",
+		"  }",
+		"  return await load(target);",
 		"};",
 	].join("\n");
 }
@@ -115,18 +121,23 @@ function contributionPrelude(plan: KernelPreludePlan): string {
 
 export class LocalModuleLoader {
 	readonly #prelude: string;
+	readonly #cwdUrl: string;
 	readonly #contributions = new KernelPreludeTracker();
 
 	constructor(options: LocalModuleLoaderOptions) {
 		this.#prelude = loaderPrelude(runtimeContext(options));
+		this.#cwdUrl = directoryUrl(options.cwd);
 	}
 
-	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = [], sourceFile?: string): string {
+	prepareCell(
+		code: string,
+		contributions: readonly KernelPreludeContribution[] = [],
+		sourceFile?: string,
+		packageRoot?: string,
+	): string {
 		// A %load cell resolves its relative imports from its own file's directory for that cell only.
-		const base =
-			sourceFile === undefined
-				? ""
-				: `\nglobalThis.__senpi_module_context__ = { ...globalThis.__senpi_module_context__, cwdUrl: ${JSON.stringify(directoryUrl(dirname(sourceFile)))} };`;
+		const cwdUrl = sourceFile === undefined ? this.#cwdUrl : directoryUrl(dirname(sourceFile));
+		const base = `\nglobalThis.__senpi_module_context__ = { ...globalThis.__senpi_module_context__, cwdUrl: ${JSON.stringify(cwdUrl)}, packageRootUrl: ${JSON.stringify(packageRoot === undefined ? null : directoryUrl(packageRoot))} };`;
 		const prelude = `${this.#prelude}${base}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
 		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code), ...(sourceFile === undefined ? {} : { sourceFile }) })}`;
 	}

package/src/kernels/js/worker-core.js

@@ -3,6 +3,7 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolPump } from "./kernel-tools-pump.js";
 import { hostDeniedError, hostToolRefusal } from "./kernel-tools-scope.js";
 import { installSessionCwd } from "./worker-cwd.js";
+import { installPackageResolver } from "./worker-package-resolve.js";
 import { createHeapProbe } from "./worker-heap.js";
 import { createWorkerMemory } from "./worker-memory.js";
 import { JsWorkerRuntime } from "./worker-runtime.js";
@@ -129,6 +130,7 @@ export function createWorkerCore(transport, options) {
 			applySessionEnvironment(message.sessionEnv);
 			installSessionCwd(options.cwd);
 			installKernelWebView(requestWebViewPort);
+			installPackageResolver();
 			runtime = new JsWorkerRuntime({
 				cwd: options.cwd,
 				parallelPoolWidth: options.parallelPoolWidth,