@code-yeongyu/senpi-codemode 2026.10.27-2 → 2026.10.30-2

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

@@ -0,0 +1,388 @@
+import { MessageChannel, type MessagePort, type Transferable, Worker, type WorkerOptions } from "node:worker_threads";
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import {
+	invocationSession,
+	type InvocationSession,
+	registerInvocationSession,
+} from "../shared/invocation-authority.ts";
+import type { WorkerRetirement } from "./interrupt-bounds.ts";
+import type { CellAuthorityToken, JavaScriptKernelOptions } from "./kernel-contract.ts";
+import type { KernelToolsInvokeOptions, KernelToolsInvokeRequest } from "./kernel-tools-types.ts";
+import { type PermissionSession, registerPermissionKernel, unregisterPermissionKernel } from "./permission-sessions.ts";
+import { forwardWorkerMessage, workerErrorFrame } from "./permission-worker-frames.ts";
+import {
+	createPermissionSlots,
+	interruptPermissionSlots,
+	type PermissionRequest,
+	servePermissionSlot,
+} from "./permission-slots.mjs";
+
+export { revokeSessionKernels } from "./permission-sessions.ts";
+
+type WorkerCommand =
+	| { type: "check"; slot: number; generation: number }
+	| { type: "retire" }
+	| {
+			type: "spawn";
+			script: string;
+			token?: string;
+			port: MessagePort;
+			options: WorkerOptions & { preload?: string | string[] };
+	  };
+
+export class KernelPermissionHost {
+	readonly kernelId = crypto.randomUUID();
+	readonly #options: JavaScriptKernelOptions;
+	readonly #session: PermissionSession;
+	readonly #retire: () => Promise<WorkerRetirement>;
+	readonly #tokens = new Map<string, CellAuthorityToken>();
+	readonly #runs = new Map<string, CellAuthorityToken>();
+	readonly #invocations = new Map<string, CellAuthorityToken>();
+	readonly #invokerBindings = new Map<string, number>();
+	readonly #retained = new Map<string, Set<CellAuthorityToken>>();
+	readonly #pools = new Set<SharedArrayBuffer>();
+	readonly #ports = new Set<MessagePort>();
+	readonly #children = new Map<Worker, Promise<void>>();
+	readonly #releaseSession: () => void;
+	#kernel: CellAuthorityToken;
+	#revoked = false;
+	#retiring?: Promise<void>;
+
+	constructor(options: JavaScriptKernelOptions, retire: () => Promise<WorkerRetirement>) {
+		this.#options = options;
+		this.#retire = retire;
+		this.#kernel = this.#mint();
+		this.#session = registerPermissionKernel(options.sessionId, this);
+		this.#releaseSession = registerInvocationSession(options.sessionId, () => this.#snapshot());
+	}
+
+	get blocked(): boolean {
+		return this.#revoked || this.#session.dead || this.#session.pending !== undefined || this.#retiring !== undefined;
+	}
+
+	async admit(): Promise<void> {
+		await this.#session.pending;
+		await this.#retiring;
+		this.assertSessionLive();
+	}
+
+	assertSessionLive(): void {
+		if (this.#session.dead) throw new Error("Permission authority unavailable; restart the session");
+	}
+
+	#snapshot(): InvocationSession {
+		return {
+			cwd: this.#options.cwd,
+			state: this.#options.permissions?.state() ?? { epoch: 0, active: false, rules: [] },
+		};
+	}
+
+	#mint(
+		signal?: AbortSignal,
+		session = { sessionId: this.#options.sessionId, ...this.#snapshot() },
+	): CellAuthorityToken {
+		const { state } = session;
+		if (!Number.isInteger(state.epoch) || state.epoch < 0 || state.epoch >= 2 ** 29)
+			throw new Error("Invalid permission epoch");
+		const authority = new SharedArrayBuffer(4);
+		Atomics.store(new Int32Array(authority), 0, (state.epoch << 2) | 2 | Number(state.active));
+		return {
+			id: crypto.randomUUID(),
+			sessionId: session.sessionId,
+			cwd: session.cwd,
+			authority,
+			rules: state.rules,
+			signal,
+		};
+	}
+
+	/** Resolve host-only caller identity before admitting any invocation frame to the worker. */
+	resolveInvocationToken(
+		_request: KernelToolsInvokeRequest,
+		options?: AbortSignal | KernelToolsInvokeOptions,
+	): CellAuthorityToken {
+		const signal = options && ("aborted" in options ? options : options.signal);
+		const session = invocationSession(
+			this.#options.sessionId,
+			this.#snapshot(),
+			options,
+			this.#options.permissions?.resolveSession,
+		);
+		const token = this.#mint(signal, session);
+		if (session.sessionId !== this.#options.sessionId) {
+			const binding = registerPermissionKernel(session.sessionId, this);
+			if (binding.dead || binding.pending) {
+				if (!this.#invokerBindings.has(session.sessionId)) unregisterPermissionKernel(session.sessionId, this);
+				throw new Error("Permission authority unavailable");
+			}
+			this.#invokerBindings.set(session.sessionId, (this.#invokerBindings.get(session.sessionId) ?? 0) + 1);
+		}
+		this.#tokens.set(token.id, token);
+		return token;
+	}
+
+	invocation(request: KernelToolsInvokeRequest, options?: AbortSignal | KernelToolsInvokeOptions): () => void {
+		const token = this.resolveInvocationToken(request, options);
+		this.#invocations.set(request.call_id, token);
+		const cancel = () => this.#kill(token);
+		token.signal?.addEventListener("abort", cancel, { once: true });
+		if (token.signal?.aborted) cancel();
+		return () => {
+			token.signal?.removeEventListener("abort", cancel);
+			this.#invocations.delete(request.call_id);
+			this.#release(token);
+		};
+	}
+
+	frame(
+		message: HostToKernelMessage,
+	): HostToKernelMessage & { authority?: ReturnType<KernelPermissionHost["wireToken"]> } {
+		let token: CellAuthorityToken | undefined;
+		if (message.type === "run") {
+			token = this.#mint();
+			this.#tokens.set(token.id, token);
+			this.#runs.set(message.cellId, token);
+		} else if (message.type === "kernel-tool-invoke") {
+			token = this.#invocations.get(message.call_id);
+		} else if (message.type === "interrupt" || message.type === "close") {
+			// An interrupt (including a timeout) ends work like settlement: inactive continuations survive.
+			for (const token of this.#tokens.values()) {
+				if (message.type === "interrupt") this.#release(token);
+				else this.#kill(token);
+			}
+			if (message.type === "close") this.#endRetained();
+			for (const pool of this.#pools) interruptPermissionSlots(pool);
+		}
+		return token ? { ...message, authority: this.wireToken(token) } : message;
+	}
+
+	settle(message: KernelToHostMessage): void {
+		if (message.type !== "result") return;
+		const token = this.#runs.get(message.cellId);
+		this.#runs.delete(message.cellId);
+		if (token) this.#release(token);
+	}
+
+	#release(token: CellAuthorityToken): void {
+		if (!this.#tokens.delete(token.id)) return;
+		// Settled no-deny work keeps its async resources; the kernel word still revokes them. A live
+		// inactive token is retained rather than forgotten, and keeps its invoker binding for as long as it
+		// is alive, so that session's revocation still reaches the continuation it left behind. Nothing
+		// reports when that continuation actually finishes, so the binding ends with the token, which is
+		// what closing the kernel does; it does not end earlier.
+		const word = Atomics.load(new Int32Array(token.authority), 0);
+		if (word & 2 && !(word & 1)) {
+			if (this.#invokerBindings.has(token.sessionId)) {
+				const held = this.#retained.get(token.sessionId) ?? new Set<CellAuthorityToken>();
+				held.add(token);
+				this.#retained.set(token.sessionId, held);
+			}
+			this.#sweepRetained(token.sessionId);
+			return;
+		}
+		this.#kill(token);
+		this.#unbind(token.sessionId);
+	}
+
+	/** A retained token holds its own binding and gives it back once that token is dead, not before. */
+	#sweepRetained(sessionId: string): void {
+		const held = this.#retained.get(sessionId);
+		if (!held) return;
+		for (const token of held) {
+			if (Atomics.load(new Int32Array(token.authority), 0) & 2) continue;
+			held.delete(token);
+			this.#unbind(sessionId);
+		}
+		if (held.size === 0) this.#retained.delete(sessionId);
+	}
+
+	/** Closing the kernel ends every continuation it was still holding open for an invoker. */
+	#endRetained(): void {
+		for (const [sessionId, held] of this.#retained) {
+			for (const token of held) this.#kill(token);
+			this.#sweepRetained(sessionId);
+		}
+	}
+
+	#unbind(sessionId: string): void {
+		const count = this.#invokerBindings.get(sessionId);
+		if (count === undefined) return;
+		if (count > 1) this.#invokerBindings.set(sessionId, count - 1);
+		else {
+			this.#invokerBindings.delete(sessionId);
+			unregisterPermissionKernel(sessionId, this);
+		}
+	}
+
+	/** Worker retirement ends every continuation, so no invoker revocation needs to reach this kernel. */
+	#unbindInvokers(): void {
+		for (const sessionId of this.#invokerBindings.keys()) unregisterPermissionKernel(sessionId, this);
+		this.#invokerBindings.clear();
+		this.#retained.clear();
+	}
+
+	#kill(token: CellAuthorityToken): void {
+		Atomics.and(new Int32Array(token.authority), 0, ~2);
+	}
+
+	wireToken(token: CellAuthorityToken) {
+		return { id: token.id, authority: token.authority, rules: token.rules };
+	}
+
+	bootstrap() {
+		if (this.#revoked) {
+			this.#kernel = this.#mint();
+			this.#revoked = false;
+		}
+		return this.#channel();
+	}
+
+	#channel(token?: CellAuthorityToken) {
+		const slots = createPermissionSlots();
+		const { port1, port2 } = new MessageChannel();
+		this.#pools.add(slots);
+		this.#ports.add(port1);
+		port1.on("message", (message: WorkerCommand) => {
+			if (message.type === "check") {
+				void servePermissionSlot(slots, message.slot, message.generation, (request) => this.#decide(request));
+			} else if (message.type === "retire") {
+				this.revoke();
+				void this.retire();
+			} else if (message.type === "spawn") {
+				this.#spawnChild(message);
+			}
+		});
+		port1.on("close", () => {
+			this.#pools.delete(slots);
+			this.#ports.delete(port1);
+		});
+		return {
+			port: port2,
+			slots,
+			kernel: this.wireToken(this.#kernel),
+			deadlineMs: this.#options.permissions?.checkDeadlineMs,
+			token: token && this.wireToken(token),
+			cwd: this.#options.cwd,
+		};
+	}
+
+	async #decide(request: PermissionRequest) {
+		const token = this.#tokens.get(request.token);
+		if (!token || this.#revoked || this.#session.dead || !(Atomics.load(new Int32Array(token.authority), 0) & 2)) {
+			throw new Error("Permission authority unavailable");
+		}
+		const decide = this.#options.permissions?.decide;
+		if (!decide) throw new Error("Cell decider unavailable");
+		const answer = await decide(token, request.call);
+		if (!(Atomics.load(new Int32Array(token.authority), 0) & 2)) throw new Error("Permission authority revoked");
+		return answer;
+	}
+
+	#spawnChild(message: Extract<WorkerCommand, { type: "spawn" }>): void {
+		const token = message.token ? this.#tokens.get(message.token) : undefined;
+		if (this.blocked || (message.token && !token)) {
+			message.port.close();
+			return;
+		}
+		const permission = this.#channel(token);
+		const messageKey = crypto.randomUUID();
+		const { preload, ...workerOptions } = message.options;
+		let worker: Worker;
+		try {
+			worker = new Worker(new URL("./permission-worker-entry.js", import.meta.url), {
+				...workerOptions,
+				workerData: {
+					permission: { ...permission, messageKey },
+					enforced: token !== undefined,
+					script: message.script,
+					preload,
+					userWorkerData: workerOptions.workerData,
+				},
+				transferList: [permission.port],
+			});
+		} catch (error) {
+			permission.port.close();
+			message.port.postMessage(workerErrorFrame(error));
+			message.port.postMessage({ type: "exit" });
+			message.port.close();
+			return;
+		}
+		const exited = new Promise<void>((resolve) =>
+			worker.once("exit", () => {
+				message.port.postMessage({ type: "exit" });
+				message.port.close();
+				this.#children.delete(worker);
+				resolve();
+			}),
+		);
+		this.#children.set(worker, exited);
+		worker.on("error", (error: Error) => message.port.postMessage(workerErrorFrame(error)));
+		worker.on("online", () => message.port.postMessage({ type: "open" }));
+		worker.on("message", (frame: unknown) => {
+			if (
+				frame !== null &&
+				typeof frame === "object" &&
+				"key" in frame &&
+				frame.key === messageKey &&
+				"value" in frame &&
+				"transfer" in frame &&
+				Array.isArray(frame.transfer)
+			) {
+				forwardWorkerMessage(message.port, frame.value, frame.transfer);
+			} else forwardWorkerMessage(message.port, frame, []);
+		});
+		message.port.on("message", (frame: { type: string; value?: unknown; transfer?: Transferable[] }) => {
+			if (frame.type === "terminate") void worker.terminate();
+			else if (frame.type === "message") worker.postMessage(frame.value, frame.transfer);
+		});
+	}
+
+	revoke(): void {
+		this.#revoked = true;
+		this.#kill(this.#kernel);
+		for (const token of this.#tokens.values()) this.#kill(token);
+		for (const pool of this.#pools) interruptPermissionSlots(pool);
+	}
+
+	retire(): Promise<void> {
+		if (this.#retiring) return this.#retiring;
+		const retirement = (async () => {
+			let outcome: WorkerRetirement;
+			try {
+				outcome = await this.#retire();
+			} catch {
+				outcome = "abandoned";
+			}
+			if (outcome === "abandoned") this.#failed();
+		})();
+		this.#retiring = retirement;
+		void retirement
+			.finally(() => {
+				if (this.#retiring === retirement) this.#retiring = undefined;
+			})
+			.catch(() => {});
+		return retirement;
+	}
+
+	#failed(): void {
+		this.#session.dead = true;
+		this.#options.onRevocationFailed?.({ sessionId: this.#options.sessionId, kernelId: this.kernelId });
+	}
+
+	async terminateChildren(): Promise<void> {
+		const children = [...this.#children];
+		for (const [worker] of children) void worker.terminate();
+		await Promise.all(children.map(([, exited]) => exited));
+		for (const port of this.#ports) port.close();
+		for (const token of this.#tokens.values()) this.#release(token);
+		this.#unbindInvokers();
+		this.#runs.clear();
+	}
+
+	dispose(): void {
+		this.revoke();
+		this.#releaseSession();
+		this.#unbindInvokers();
+		unregisterPermissionKernel(this.#options.sessionId, this);
+	}
+}

package/src/kernels/js/permission-runtime.js

@@ -0,0 +1,205 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { pathToFileURL } from "node:url";
+import { MessageChannel, parentPort } from "node:worker_threads";
+import { authorityDecision } from "./permission-authority.mjs";
+import { createPermissionRequester } from "./permission-slots.mjs";
+import { createCodePermissionGuard } from "./interpose-code.js";
+
+let initialized = false;
+
+export async function initializePermissionRuntime(install, workerData, engine) {
+	if (initialized) throw new Error("Permission runtime already initialized");
+	initialized = true;
+	const context = new AsyncLocalStorage();
+	const bound = new Map();
+	const data = workerData.permission;
+	// The bootstrap transport is host authority, not user-visible worker data.
+	delete workerData.permission;
+	const inactiveWord = new SharedArrayBuffer(4);
+	Atomics.store(new Int32Array(inactiveWord), 0, 2);
+	const kernel = data?.kernel ?? { id: "", authority: inactiveWord, rules: [] };
+	const requester = data && createPermissionRequester(data.slots, {
+		wake: (slot, generation) => data.port.postMessage({ type: "check", slot, generation }),
+		retire: () => data.port.postMessage({ type: "retire" }),
+		deadlineMs: data.deadlineMs,
+	});
+	const refusal = (reason, rule) => {
+		const error = new Error(`${reason}${rule ? ` (${rule.permission}: ${rule.pattern}, ${rule.layer})` : ""}`);
+		error.name = "CellPermissionDeniedError";
+		error.code = "cell_permission_denied";
+		error.rule = rule;
+		return error;
+	};
+	// Resolution hooks and module top-level bodies run outside the importing cell's async context. A
+	// token that is importing opens a LOADING WINDOW; an out-of-context operation is attributed to that
+	// token only while it is the sole loader, bound, active and alive, and no other bound token is active
+	// (design 6.4 / N4). Any other shape keeps today's refusal: never a pass that was a refusal before.
+	const loading = new Map();
+	const activeBit = (entry) => Atomics.load(new Int32Array(entry.authority), 0) & 1;
+	const aliveBit = (entry) => Atomics.load(new Int32Array(entry.authority), 0) & 2;
+	const load = async (thunk) => {
+		const token = context.getStore();
+		if (!token) return thunk();
+		const entry = loading.get(token.id);
+		if (entry) entry.depth += 1;
+		else loading.set(token.id, { token, depth: 1 });
+		try {
+			return await thunk();
+		} finally {
+			const current = loading.get(token.id);
+			if (current && (current.depth -= 1) === 0) loading.delete(token.id);
+		}
+	};
+	Object.defineProperty(load, "pending", { value: () => loading.size });
+	Object.defineProperty(globalThis, Symbol.for("senpi.kernel.permissionLoad"), { value: load });
+	const soleLoader = () => {
+		if (loading.size !== 1) return undefined;
+		const [{ token }] = loading.values();
+		if (!bound.has(token.id) || !activeBit(token) || !aliveBit(token)) return undefined;
+		for (const other of bound.values()) if (other.id !== token.id && activeBit(other)) return undefined;
+		return token;
+	};
+	const authorize = (operation) => {
+		const token = context.getStore() ?? soleLoader();
+		const disposition = authorityDecision(token, token ? [] : [...bound.values()], kernel);
+		if (disposition === "pass") return;
+		const rule = token?.rules[0] ?? [...bound.values()].find((entry) => entry.rules.length)?.rules[0] ?? kernel.rules[0];
+		if (disposition === "refuse" || !requester || !token) throw refusal("Permission authority unavailable", rule);
+		try {
+			const { call, unsupported, granted } = operation();
+			if (unsupported) throw refusal("Operation cannot be checked", rule);
+			if (granted) return;
+			const result = requester.check({ token: token.id, call });
+			// Revocation may have raced an already-published answer.
+			if (!(Atomics.load(new Int32Array(token.authority), 0) & 2)) throw new Error("Permission authority revoked");
+			if (result.action === "deny") throw refusal("Operation denied", result.rule);
+		} catch (error) {
+			if (error?.code === "cell_permission_denied") throw error;
+			throw refusal(error instanceof Error ? error.message : "Permission check failed", rule);
+		}
+	};
+	install(authorize);
+	const codeGuard = createCodePermissionGuard(authorize);
+	const runAuthority = async (token, run, source) => {
+		if (!token && authorityDecision(undefined, [...bound.values()], kernel) !== "pass") {
+			throw refusal("Permission authority unavailable", kernel.rules[0]);
+		}
+		if (token) bound.set(token.id, token);
+		try { return await context.run(token, () => { codeGuard.scan(source); return run(); }); }
+		finally { if (token) bound.delete(token.id); }
+	};
+
+	// Only a configured kernel replaces the constructor; the entry already put a forwarder on the module
+	// before its ESM namespace existed, and this class is what it constructs.
+	if (data && globalThis.Worker) {
+		engine.installGuardedWorker(class Worker extends EventTarget {
+			#port;
+			onmessage = null;
+			onerror = null;
+			onopen = null;
+			onclose = null;
+			onmessageerror = null;
+			constructor(script, options = {}) {
+				super();
+				const token = context.getStore();
+				if (authorityDecision(token, [...bound.values()], kernel) === "refuse") throw refusal("Permission authority unavailable", token?.rules[0] ?? kernel.rules[0]);
+				const { port1, port2 } = new MessageChannel();
+				this.#port = port1;
+				port1.on("message", (frame) => {
+					if (frame.type === "message") {
+						const event = new MessageEvent("message", { data: frame.value });
+						if (frame.value === undefined) Object.defineProperty(event, "data", { value: undefined });
+						this.onmessage?.(event);
+						this.dispatchEvent(event);
+					} else if (frame.type === "error") {
+						const event = new ErrorEvent("error", {
+							message: frame.message, error: frame.error,
+							filename: frame.filename, lineno: frame.lineno, colno: frame.colno,
+						});
+						this.onerror?.(event);
+						this.dispatchEvent(event);
+					} else if (frame.type === "messageerror") {
+						const event = new MessageEvent("messageerror", { data: frame.error });
+						this.onmessageerror?.(event);
+						this.dispatchEvent(event);
+					} else if (frame.type === "open") {
+						const event = new Event("open");
+						this.onopen?.(event);
+						this.dispatchEvent(event);
+					} else if (frame.type === "exit") {
+						port1.close();
+						const event = new Event("close");
+						this.onclose?.(event);
+						this.dispatchEvent(event);
+					}
+				});
+				port1.on("messageerror", (error) => {
+					const event = new MessageEvent("messageerror", { data: error });
+					this.onmessageerror?.(event);
+					this.dispatchEvent(event);
+				});
+				const href = new URL(String(script), pathToFileURL(`${process.cwd()}/`)).href;
+				// Inactive resources belong to the kernel lifetime, not the completed run's registry entry.
+				const activeToken = token && (Atomics.load(new Int32Array(token.authority), 0) & 1) ? token.id : undefined;
+				data.port.postMessage({ type: "spawn", script: href, token: activeToken, port: port2, options }, [port2]);
+			}
+			postMessage(value, options = []) {
+				const transfer = Array.isArray(options) ? options : options.transfer ?? [];
+				this.#port.postMessage({ type: "message", value, transfer }, transfer);
+			}
+			terminate() { this.#port.postMessage({ type: "terminate" }); }
+			ref() { this.#port.ref(); return this; }
+			unref() { this.#port.unref(); return this; }
+		});
+	}
+
+	if (workerData.script) {
+		const { installSessionCwd } = await import("./worker-cwd.js");
+		installSessionCwd(data.cwd, { permissionInterposed: true });
+		globalThis.postMessage = (value, options = []) => {
+			const transfer = Array.isArray(options) ? options : options.transfer ?? [];
+			parentPort.postMessage({ key: data.messageKey, value, transfer }, transfer);
+		};
+		globalThis.close = () => parentPort.close();
+		const events = new EventTarget();
+		globalThis.addEventListener = events.addEventListener.bind(events);
+		globalThis.removeEventListener = events.removeEventListener.bind(events);
+		parentPort.on("message", (value) => context.run(data.token, () => {
+			const event = new MessageEvent("message", { data: value });
+			if (value === undefined) Object.defineProperty(event, "data", { value: undefined });
+			globalThis.onmessage?.(event);
+			events.dispatchEvent(event);
+		}));
+		engine.activate();
+		await runAuthority(data.token, async () => {
+			// User preloads still precede the script, but never precede interposition.
+			const preloads = typeof workerData.preload === "string" ? [workerData.preload] : workerData.preload ?? [];
+			const require = process.getBuiltinModule("node:module").createRequire(pathToFileURL(`${data.cwd}/__preload__.js`));
+			const { isAbsolute } = process.getBuiltinModule("node:path");
+			for (const preload of preloads) {
+				const resolved = /^[a-z][a-z\d+.-]*:/iu.test(preload) && !isAbsolute(preload) ? preload : require.resolve(preload);
+				await load(() => import(isAbsolute(resolved) ? pathToFileURL(resolved).href : resolved));
+			}
+			await load(() => import(workerData.script));
+		});
+		return;
+	}
+	const { createWorkerCore } = await import("./worker-core.js");
+	const { initializeResolverIO } = await import("./worker-package-resolve.js");
+	initializeResolverIO(engine.resolverIO);
+	const { initializeProcessCleanup } = await import("./process-tree.js");
+	const { initializeWindowsCleanup } = await import("./windows-tree-kill.js");
+	initializeProcessCleanup(engine.cleanupExecFile);
+	initializeWindowsCleanup(engine.cleanupExecFile);
+	createWorkerCore({
+		send: (message) => parentPort.postMessage(message),
+		onMessage(handler) { parentPort.on("message", handler); return () => parentPort.off("message", handler); },
+		close() { parentPort.close(); setTimeout(() => process.exit(0), 0); },
+	}, {
+		cwd: workerData.cwd,
+		parallelPoolWidth: workerData.parallelPoolWidth,
+		cwdInstallOptions: { permissionInterposed: true },
+		runAuthority,
+		permissionIO: engine.permissionIO,
+	});
+}

package/src/kernels/js/permission-sessions.ts

@@ -0,0 +1,46 @@
+interface SessionKernel {
+	revoke(): void;
+	retire(): Promise<void>;
+}
+
+export interface PermissionSession {
+	dead: boolean;
+	pending?: Promise<void>;
+	readonly kernels: Set<SessionKernel>;
+}
+
+const sessions = new Map<string, PermissionSession>();
+
+export function registerPermissionKernel(sessionId: string, kernel: SessionKernel): PermissionSession {
+	let session = sessions.get(sessionId);
+	if (!session) {
+		session = { dead: false, kernels: new Set() };
+		sessions.set(sessionId, session);
+	}
+	session.kernels.add(kernel);
+	return session;
+}
+
+export function unregisterPermissionKernel(sessionId: string, kernel: SessionKernel): void {
+	const session = sessions.get(sessionId);
+	if (!session) return;
+	session.kernels.delete(kernel);
+	if (!session.dead && !session.pending && session.kernels.size === 0) sessions.delete(sessionId);
+}
+
+/** All words go DEAD synchronously, before retirement or another admission can run. */
+export function revokeSessionKernels(sessionId: string): Promise<void> {
+	const session = sessions.get(sessionId);
+	if (!session) return Promise.resolve();
+	if (session.pending) return session.pending;
+	const kernels = [...session.kernels];
+	for (const kernel of kernels) kernel.revoke();
+	const pending = Promise.all(kernels.map((kernel) => kernel.retire())).then(() => {});
+	session.pending = pending;
+	void pending
+		.finally(() => {
+			if (session.pending === pending) session.pending = undefined;
+		})
+		.catch(() => {});
+	return pending;
+}

package/src/kernels/js/permission-slots.d.mts

@@ -0,0 +1,51 @@
+export interface CellRule {
+	readonly permission: string;
+	readonly pattern: string;
+	readonly layer: string;
+}
+export interface CellCanonicalPath {
+	/** PATH_IDENTITY_VERSION of the kernel that computed it; the host ignores any other version. */
+	readonly v: number;
+	readonly path: string;
+	readonly foldCase: boolean;
+}
+export type CellOperation = {
+	readonly tool: "bash" | "read" | "write" | "ls";
+	readonly input: {
+		readonly command?: string;
+		/** The path as written by the cell, byte-for-byte. */
+		readonly path?: string;
+		/** The absolute string the operation hands to the runtime. */
+		readonly executedPath?: string;
+		readonly canonical?: CellCanonicalPath;
+		/** Error code when the kernel could not canonicalize the executed path. */
+		readonly unresolvable?: string;
+	};
+	readonly cwd?: string;
+};
+export type CellDecision = { readonly action: "pass" } | { readonly action: "deny"; readonly rule: CellRule };
+export interface PermissionRequest {
+	readonly token: string;
+	readonly call: CellOperation;
+}
+export function createPermissionSlots(): SharedArrayBuffer;
+export function permissionControl(buffer: SharedArrayBuffer, index: number): number;
+export function interruptPermissionSlot(buffer: SharedArrayBuffer, index: number, observed: number): boolean;
+export function interruptPermissionSlots(buffer: SharedArrayBuffer): void;
+export function createPermissionRequester(
+	buffer: SharedArrayBuffer,
+	hooks: {
+		wake(index: number, generation: number): void;
+		wait?: typeof Atomics.wait;
+		generationLimit?: number;
+		deadlineMs?: number;
+		retire?(): void;
+	},
+): { check(request: PermissionRequest): CellDecision };
+export function servePermissionSlot(
+	buffer: SharedArrayBuffer,
+	index: number,
+	generation: number,
+	decide: (request: PermissionRequest) => CellDecision | Promise<CellDecision>,
+	hooks?: { claimed?(): void | Promise<void> },
+): Promise<void>;