@workerdeck/server 2.12.0 → 2.14.0

package/build/index.mjs

@@ -1,14 +1,14 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
-import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SessionRunner, attachmentKind, checkClaudeAuth, createEngineSession, getEngineAdapter, installPeerDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines } from "@workerdeck/core";
+import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SHELL_REFUSAL, SessionRunner, attachmentKind, checkClaudeAuth, clampShellTail, createEngineSession, getEngineAdapter, installPeerDirectory, installShellDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines, shellDirectoryHandle, shellSummary, shellTail, ttyText } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_COMMAND_MAX, costOfByModel, imagePartRef, isJobRun, mergeByModel, peerMentionKey, peerMentionSlug, scanPeerMentions, sessionState, setPricingOverrides, subscriptionComparison, supportsPermissionMode } from "@workerdeck/protocol";
-import { createHash, randomUUID } from "node:crypto";
+import { ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_ARTIFACT_MAX_BYTES, SHELL_ARTIFACT_TTL_MS, SHELL_ATTACH_REPLAY_BYTES, SHELL_COLS, SHELL_COMMAND_MAX, SHELL_INPUT_MAX, SHELL_LABEL_MAX, SHELL_LINGER_MS, SHELL_MAX_COLS, SHELL_MAX_ROWS, SHELL_MAX_RUNNING_PER_SESSION, SHELL_MAX_RUNNING_TOTAL, SHELL_MIN_COLS, SHELL_MIN_ROWS, SHELL_ROWS, SHELL_SPILL_BYTES, SHELL_TAIL_FLUSH_MS, SHELL_TAIL_RING_BYTES, costOfByModel, imagePartRef, isJobRun, mergeByModel, peerMentionKey, peerMentionSlug, pickCreateSessionRequest, scanPeerMentions, sessionState, setPricingOverrides, subscriptionComparison, supportsPermissionMode } from "@workerdeck/protocol";
+import { arch, homedir, hostname, platform, tmpdir } from "node:os";
 import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { constants as constants$1, homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { spawn } from "node:child_process";
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
 //#region src/lib/http.ts
 const CONTENT_TYPES = {
 	json: "application/json; charset=utf-8",
@@ -61,6 +61,18 @@ function contentTypeFor(filename) {
 	return CONTENT_TYPES[ext] ?? "text/plain; charset=utf-8";
 }
 //#endregion
+//#region src/lib/machine-id.ts
+let cached;
+function machineId() {
+	cached ??= createHash("sha256").update([
+		hostname(),
+		platform(),
+		arch(),
+		homedir()
+	].join("\0")).digest("hex").slice(0, 32);
+	return cached;
+}
+//#endregion
 //#region src/lib/profile-env.ts
 function isProviderProfile(profile) {
 	return profile.engine === "provider";
@@ -183,6 +195,16 @@ function parseSessionRoute(basePath, url) {
 		produced: true,
 		producedFileId: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2])
 	};
+	if (parts[1] === "shells" && parts.length <= 4) {
+		const action = parts[3];
+		if (action !== void 0 && action !== "output" && action !== "kill") return null;
+		return {
+			id: decodeURIComponent(parts[0]),
+			shells: true,
+			shellId: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2]),
+			shellAction: action
+		};
+	}
 	if (parts.length === 3 && parts[1] === "project" && parts[2] === "icon") return {
 		id: decodeURIComponent(parts[0]),
 		projectIcon: true
@@ -751,34 +773,90 @@ async function handleHostFiles(ctx, req, res, pathname) {
 	}
 	json(res, 404, { error: "not found" });
 }
-//#endregion
-//#region src/routes/create-vet.ts
-function vetCreateRequest(ctx, req, auth) {
+const HOST_ONLY_KEYS = new Set(Object.keys({
+	epoch: true,
+	queryFn: true,
+	env: true,
+	pathToClaudeCodeExecutable: true,
+	extraOptions: true,
+	instructions: true,
+	defaultApprovalTimeoutMs: true,
+	backfillHistory: true,
+	historyFn: true,
+	sessionInfoFn: true,
+	peers: true,
+	shells: true,
+	connectFn: true,
+	codexHome: true,
+	codexPathOverride: true,
+	languageModel: true,
+	tools: true,
+	maxSteps: true,
+	executor: true,
+	executableTools: true,
+	vfs: true,
+	executionLimits: true,
+	executionBackend: true,
+	toolTitles: true,
+	shouldApprove: true,
+	resolveModel: true,
+	reportMcpServers: true,
+	onClose: true,
+	restore: true
+}));
+function vetCreateRequest(ctx, body, auth) {
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return {
+		ok: false,
+		status: 400,
+		error: "request body must be a JSON object"
+	};
+	const hostOnly = Object.keys(body).filter((key) => HOST_ONLY_KEYS.has(key));
+	if (hostOnly.length > 0) return {
+		ok: false,
+		status: 400,
+		error: `host-only runner config is not accepted on a session request: ${hostOnly.join(", ")} (set it from the gateway's buildRunnerConfig hook)`
+	};
+	const req = pickCreateSessionRequest(body);
 	const { availability, factory } = ctx;
 	const refusedScope = factory.applyScope(req, auth);
-	if (refusedScope) return refusedScope;
+	if (refusedScope) return {
+		ok: false,
+		...refusedScope
+	};
 	const refused = factory.applyBypassPolicy(req);
 	if (refused) return {
+		ok: false,
 		status: 403,
 		error: refused
 	};
 	const resolved = factory.resolveProfile(req.profile, auth.allowedProfiles);
 	if (!resolved.ok) return {
+		ok: false,
 		status: resolved.status,
 		error: resolved.error
 	};
 	const unavailable = availability.checkAvailable(resolved.profile);
-	if (unavailable) return unavailable;
+	if (unavailable) return {
+		ok: false,
+		...unavailable
+	};
 	const refusedCwd = factory.checkCwd(req, resolved.profile);
-	if (refusedCwd) return refusedCwd;
+	if (refusedCwd) return {
+		ok: false,
+		...refusedCwd
+	};
 	const badRequest = factory.checkPermissionMode(req.permissionMode, resolved.profile) ?? factory.checkEngineGrants(req, resolved.profile);
 	if (badRequest) return {
+		ok: false,
 		status: 400,
 		error: badRequest
 	};
 	factory.stripInertFields(req, resolved.profile);
 	req.profile = resolved.profile?.name;
-	return null;
+	return {
+		ok: true,
+		request: req
+	};
 }
 //#endregion
 //#region src/routes/jobs.ts
@@ -808,21 +886,28 @@ async function handleJobs(ctx, req, res, pathname, auth) {
 		}
 		if (req.method === "POST") {
 			const body = await readJsonBody(req, ctx.maxBodyBytes);
-			if (!body.session || typeof body.session !== "object") {
+			if (!body?.session || typeof body.session !== "object") {
 				json(res, 400, { error: "session is required" });
 				return;
 			}
-			if (!body.session.prompt || typeof body.session.prompt !== "string") {
+			const prompt = body.session.prompt;
+			if (!prompt || typeof prompt !== "string") {
 				json(res, 400, { error: "session.prompt is required" });
 				return;
 			}
-			const refusal = vetCreateRequest(ctx, body.session, auth);
-			if (refusal) {
-				json(res, refusal.status, { error: refusal.error });
+			const vetted = vetCreateRequest(ctx, body.session, auth);
+			if (!vetted.ok) {
+				json(res, vetted.status, { error: vetted.error });
 				return;
 			}
 			try {
-				json(res, 201, { job: await queue.submit(body) });
+				json(res, 201, { job: await queue.submit({
+					...body,
+					session: {
+						...vetted.request,
+						prompt
+					}
+				}) });
 			} catch (error) {
 				json(res, 400, { error: error instanceof Error ? error.message : "invalid job" });
 			}
@@ -1028,7 +1113,8 @@ const EPHEMERAL_CONFIG_KEYS = [
 	"historyFn",
 	"extraOptions",
 	"env",
-	"peers"
+	"peers",
+	"instructions"
 ];
 function toDurableRecord(record) {
 	const config = { ...record.config };
@@ -1047,7 +1133,7 @@ function createFileSessionStore(options = {}) {
 		try {
 			raw = await readFile(path, "utf8");
 		} catch (error) {
-			if (isMissing(error)) return null;
+			if (isMissing$1(error)) return null;
 			options.onError?.(error, {
 				path,
 				op: "read"
@@ -1102,7 +1188,7 @@ function createFileSessionStore(options = {}) {
 			try {
 				names = await readdir(dir);
 			} catch (error) {
-				if (isMissing(error)) return [];
+				if (isMissing$1(error)) return [];
 				options.onError?.(error, {
 					path: dir,
 					op: "read"
@@ -1126,7 +1212,7 @@ function createFileSessionStore(options = {}) {
 				await rm(path);
 				return true;
 			} catch (error) {
-				if (isMissing(error)) return false;
+				if (isMissing$1(error)) return false;
 				options.onError?.(error, {
 					path,
 					op: "delete"
@@ -1136,7 +1222,7 @@ function createFileSessionStore(options = {}) {
 		}
 	};
 }
-function isMissing(error) {
+function isMissing$1(error) {
 	return error.code === "ENOENT";
 }
 function parseRecord(value) {
@@ -1296,17 +1382,19 @@ const DEFAULT_TTL_MS = 3e4;
 const SWEEP_ABOVE = 256;
 var ProjectInfoService = class {
 	#ttlMs;
+	#decorate;
 	#byCwd = /* @__PURE__ */ new Map();
 	constructor(options = {}) {
 		this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+		this.#decorate = options.decorate ?? ((info) => info);
 	}
 	withProject(info) {
-		if (!info.cwd) return info;
+		if (!info.cwd) return this.#decorate(info);
 		const project = this.#resolve(info.cwd).project;
-		return project ? {
+		return this.#decorate(project ? {
 			...info,
 			project
-		} : info;
+		} : info);
 	}
 	iconFor(cwd) {
 		if (!cwd) return;
@@ -1455,6 +1543,1062 @@ function handleProjectIcon(projects, req, res, cwd) {
 	res.end(read.data);
 }
 //#endregion
+//#region src/services/process-tree.ts
+const PS_ARGS = ["-eo", "pid=,ppid=,pgid="];
+const PS_TIMEOUT_MS = 2e3;
+const PS_MAX_BUFFER = 67108864;
+const MAX_ROUNDS = 5;
+function readProcessTable() {
+	const result = spawnSync("ps", PS_ARGS, {
+		encoding: "utf8",
+		timeout: PS_TIMEOUT_MS,
+		maxBuffer: PS_MAX_BUFFER,
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		]
+	});
+	if (result.error || result.status !== 0 || typeof result.stdout !== "string") return null;
+	return parseProcessTable(result.stdout);
+}
+function parseProcessTable(text) {
+	const rows = [];
+	for (const line of text.split("\n")) {
+		const fields = line.trim().split(/\s+/);
+		if (fields.length !== 3) continue;
+		const [pid, ppid, pgid] = fields.map(Number);
+		if (Number.isInteger(pid) && Number.isInteger(ppid) && Number.isInteger(pgid)) rows.push({
+			pid,
+			ppid,
+			pgid
+		});
+	}
+	return rows;
+}
+function killProcessTrees(roots, deps) {
+	const { self } = deps;
+	const signal = (pid, name) => {
+		try {
+			deps.signal(pid, name);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const owned = (pid) => Number.isInteger(pid) && pid > 1 && pid !== self;
+	const live = new Set(roots.filter(owned));
+	const closure = /* @__PURE__ */ new Map();
+	const rootRows = /* @__PURE__ */ new Map();
+	const foreign = [];
+	let scanned = false;
+	let selfPgid;
+	for (let round = 0; round < MAX_ROUNDS; round++) {
+		const table = readTable(deps.table);
+		if (table === null) break;
+		const byPid = /* @__PURE__ */ new Map();
+		const byParent = /* @__PURE__ */ new Map();
+		for (const row of table) {
+			byPid.set(row.pid, row);
+			const siblings = byParent.get(row.ppid);
+			if (siblings) siblings.push(row);
+			else byParent.set(row.ppid, [row]);
+		}
+		let grew = false;
+		if (!scanned) {
+			scanned = true;
+			selfPgid = byPid.get(self)?.pgid;
+			for (const root of live) {
+				const row = byPid.get(root);
+				if (row === void 0) continue;
+				if (row.ppid !== self) {
+					foreign.push(root);
+					live.delete(root);
+					continue;
+				}
+				rootRows.set(root, row);
+				signal(-root, "SIGSTOP");
+				grew = true;
+			}
+		}
+		for (const root of rootRows.keys()) {
+			const queue = [root];
+			const seen = /* @__PURE__ */ new Set([root]);
+			while (queue.length > 0) {
+				const parent = queue.shift();
+				for (const child of byParent.get(parent) ?? []) {
+					if (!owned(child.pid) || seen.has(child.pid)) continue;
+					seen.add(child.pid);
+					queue.push(child.pid);
+					if (!closure.has(child.pid)) {
+						closure.set(child.pid, child);
+						signal(child.pid, "SIGSTOP");
+						grew = true;
+					}
+				}
+			}
+		}
+		if (!grew) break;
+	}
+	const unreached = [];
+	const groups = /* @__PURE__ */ new Set();
+	for (const root of live) {
+		groups.add(root);
+		if (!signal(-root, "SIGKILL")) unreached.push(root);
+	}
+	for (const pid of closure.keys()) signal(pid, "SIGKILL");
+	if (selfPgid !== void 0) for (const row of [...rootRows.values(), ...closure.values()]) {
+		const group = row.pgid;
+		if (group <= 1 || group === self || group === selfPgid || groups.has(group)) continue;
+		groups.add(group);
+		signal(-group, "SIGKILL");
+	}
+	return {
+		scanned,
+		descendants: closure.size,
+		foreign,
+		unreached
+	};
+}
+function readTable(table) {
+	try {
+		return table();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/services/shells.ts
+const NOTIFY_MS = 250;
+const SWEEP_INTERVAL_MS = 36e5;
+const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+const ID_CHARS = 12;
+const TERM = "xterm-256color";
+const INDEX_SUFFIX = ".json";
+const INDEX_VERSION = 1;
+const CTTY_WRAPPER = "true <>/dev/tty 2>/dev/null; exec \"$0\" -c \"$1\"";
+let ptyModule;
+async function loadPty() {
+	if (ptyModule !== void 0) return ptyModule;
+	try {
+		ptyModule = await import("@lydell/node-pty");
+	} catch {
+		ptyModule = null;
+	}
+	return ptyModule;
+}
+function createShellDirectory(registry) {
+	return {
+		list: async (from) => registry.list(from).map(shellSummary),
+		read: async (from, shellId, options) => {
+			const info = registry.get(from, shellId);
+			if (!info) return;
+			const text = await registry.output(from, shellId, { view: "text" });
+			if (text === void 0) return;
+			return {
+				shell: shellSummary(info),
+				...shellTail(text, clampShellTail(options?.tail))
+			};
+		}
+	};
+}
+function shellPermitted(shells, runner, operator) {
+	if (shells === null || !operator) return false;
+	const info = runner.info();
+	return (info.capabilities ?? (info.engine ? ENGINE_CAPABILITIES[info.engine] : void 0))?.hostCwd === true;
+}
+function shellChildEnv(base) {
+	const env = {};
+	for (const [key, value] of Object.entries(base)) if (value !== void 0) env[key] = value;
+	return env;
+}
+function clampSize(size) {
+	return {
+		cols: clamp(size.cols, SHELL_MIN_COLS, SHELL_MAX_COLS),
+		rows: clamp(size.rows, SHELL_MIN_ROWS, SHELL_MAX_ROWS)
+	};
+}
+function loginShell(env) {
+	const shell = env.SHELL;
+	return shell && shell.startsWith("/") ? shell : "/bin/sh";
+}
+function createShellRegistry(options) {
+	const { generation } = options;
+	const dir = options.artifactDir;
+	const base = dir ?? join(tmpdir(), `workerdeck-shells-${process.pid}`);
+	const limits = {
+		spill: options.spillBytes ?? SHELL_SPILL_BYTES,
+		cap: options.artifactMaxBytes ?? SHELL_ARTIFACT_MAX_BYTES,
+		ring: options.tailRingBytes ?? SHELL_TAIL_RING_BYTES
+	};
+	const tailFlushMs = options.tailFlushMs ?? SHELL_TAIL_FLUSH_MS;
+	const ttlMs = options.artifactTtlMs ?? SHELL_ARTIFACT_TTL_MS;
+	const perSession = options.maxRunningPerSession ?? SHELL_MAX_RUNNING_PER_SESSION;
+	const total = options.maxRunningTotal ?? SHELL_MAX_RUNNING_TOTAL;
+	const sweepIntervalMs = options.sweepIntervalMs ?? SWEEP_INTERVAL_MS;
+	const sessions = /* @__PURE__ */ new Map();
+	const loading = /* @__PURE__ */ new Map();
+	let sweeper;
+	let stopped = false;
+	const report = (error, context) => options.onError?.(error, context);
+	const indexPath = (sessionId) => join(base, `${encodeURIComponent(sessionId)}${INDEX_SUFFIX}`);
+	const pathsFor = (sessionId, shellId) => {
+		const encoded = encodeURIComponent(sessionId);
+		const sessionDir = join(base, encoded);
+		return {
+			dir: sessionDir,
+			raw: join(sessionDir, `${shellId}.raw`),
+			tail: join(sessionDir, `${shellId}.tail.raw`),
+			rel: `${encoded}/${shellId}.raw`
+		};
+	};
+	const find = (sessionId, id) => sessions.get(sessionId)?.entries.get(id);
+	const runningAll = () => [...sessions.values()].flatMap(runningIn);
+	const persist = (state) => {
+		if (!dir || state.pending) return;
+		state.pending = true;
+		state.chain = state.chain.then(async () => {
+			state.pending = false;
+			const payload = JSON.stringify(serialize(state));
+			await mkdir(dir, {
+				recursive: true,
+				mode: 448
+			});
+			const path = indexPath(state.sessionId);
+			const temp = `${path}.${process.pid}.tmp`;
+			await writeFile(temp, payload, { mode: 384 });
+			await rename(temp, path);
+		}).catch((error) => report(error, {
+			op: "index",
+			sessionId: state.sessionId
+		}));
+	};
+	const readIndex = async (sessionId) => {
+		const state = freshSession(sessionId);
+		if (!dir) return state;
+		let raw;
+		try {
+			raw = await readFile(indexPath(sessionId), "utf8");
+		} catch (error) {
+			if (!isMissing(error)) report(error, {
+				op: "index",
+				sessionId
+			});
+			return state;
+		}
+		let index;
+		try {
+			index = parseIndex(JSON.parse(raw));
+		} catch (error) {
+			report(error, {
+				op: "index",
+				sessionId
+			});
+			return state;
+		}
+		state.nextOrdinal = index.nextOrdinal;
+		const now = Date.now();
+		let dirty = false;
+		for (const record of index.shells) {
+			const { generation: recordGeneration, output, artifact, ...info } = record;
+			if (info.status === "running" && recordGeneration !== generation) {
+				info.status = "exited";
+				info.endReason = "server_restarted";
+				info.endedAt = now;
+				delete info.exitCode;
+				delete info.signal;
+				dirty = true;
+			}
+			state.entries.set(info.id, {
+				info,
+				generation: recordGeneration,
+				artifact: new StoredArtifact(pathsFor(sessionId, info.id), info, {
+					output,
+					artifact
+				}),
+				sinks: /* @__PURE__ */ new Set(),
+				listeners: /* @__PURE__ */ new Set()
+			});
+		}
+		if (dirty) persist(state);
+		return state;
+	};
+	const load = (sessionId) => {
+		const held = sessions.get(sessionId);
+		if (held) return Promise.resolve(held);
+		let inflight = loading.get(sessionId);
+		if (!inflight) {
+			inflight = readIndex(sessionId).then((state) => {
+				sessions.set(sessionId, state);
+				loading.delete(sessionId);
+				return state;
+			});
+			loading.set(sessionId, inflight);
+		}
+		return inflight;
+	};
+	const fire = (entry) => {
+		for (const listener of entry.listeners) try {
+			listener();
+		} catch (error) {
+			report(error, {
+				op: "listener",
+				sessionId: entry.info.sessionId,
+				shellId: entry.info.id
+			});
+		}
+	};
+	const scheduleNotify = (entry) => {
+		if (entry.notify) return;
+		entry.notify = setTimeout(() => {
+			entry.notify = void 0;
+			if (entry.info.status === "running") fire(entry);
+		}, NOTIFY_MS);
+		entry.notify.unref();
+	};
+	const settle = (state, entry, reason) => {
+		if (entry.info.status !== "running") return;
+		entry.info.status = "exited";
+		entry.info.endedAt = Date.now();
+		entry.info.endReason = reason;
+		clearTimeout(entry.clock);
+		clearTimeout(entry.notify);
+		clearInterval(entry.tailTimer);
+		entry.clock = entry.notify = entry.tailTimer = void 0;
+		entry.child = void 0;
+		entry.pid = void 0;
+		if (entry.artifact instanceof LiveArtifact) entry.artifact.close();
+		for (const sink of entry.sinks) try {
+			sink.end(reason);
+		} catch {}
+		entry.sinks.clear();
+		persist(state);
+		fire(entry);
+	};
+	const treeDeps = {
+		table: options.processTable ?? readProcessTable,
+		signal: (pid, name) => void process.kill(pid, name),
+		self: process.pid
+	};
+	const killTrees = (entries) => {
+		const live = entries.flatMap((entry) => entry.pid === void 0 ? [] : [{
+			entry,
+			pid: entry.pid
+		}]);
+		if (live.length === 0) return;
+		const result = killProcessTrees(live.map(({ pid }) => pid), treeDeps);
+		for (const { entry, pid } of live) {
+			if (result.unreached.includes(pid)) try {
+				entry.child?.kill("SIGKILL");
+			} catch {}
+			const context = {
+				op: "kill",
+				sessionId: entry.info.sessionId,
+				shellId: entry.info.id
+			};
+			if (!result.scanned) report(/* @__PURE__ */ new Error("no process table (ps), only the process group was signalled"), context);
+			else if (result.foreign.includes(pid)) report(/* @__PURE__ */ new Error(`pid ${pid} is no longer this shell's child and was left alone`), context);
+		}
+	};
+	const killEntries = (targets, reason) => {
+		const running = targets.filter(({ entry }) => entry.info.status === "running");
+		killTrees(running.map(({ entry }) => entry));
+		for (const { state, entry } of running) settle(state, entry, reason);
+		return running.length;
+	};
+	const kill = (state, entry, reason) => {
+		killEntries([{
+			state,
+			entry
+		}], reason);
+	};
+	const killSession = (sessionId, reason) => {
+		const state = sessions.get(sessionId);
+		if (!state) return;
+		killEntries(runningIn(state).map((entry) => ({
+			state,
+			entry
+		})), reason);
+	};
+	const spawn = async ({ runner, command, owner }) => {
+		if (stopped) throw new Error("the gateway is shutting down");
+		const sessionId = runner.id;
+		const state = await load(sessionId);
+		const pty = await loadPty();
+		if (!pty) throw new Error(SHELL_REFUSAL);
+		const cwd = runner.info().cwd;
+		if (!(await stat(cwd).catch(() => void 0))?.isDirectory()) throw new Error(`the session's cwd is not a directory: ${cwd}`);
+		const inSession = runningIn(state).length;
+		if (inSession >= perSession) throw new Error(`this session already has ${inSession} shells running (the limit is ${perSession})`);
+		const overall = runningAll().length;
+		if (overall >= total) throw new Error(`the gateway already has ${overall} shells running (the limit is ${total})`);
+		const id = mintShellId();
+		const info = {
+			id,
+			sessionId,
+			ordinal: state.nextOrdinal++,
+			command,
+			label: shellLabel(command),
+			cwd,
+			owner,
+			status: "running",
+			startedAt: Date.now(),
+			bytes: 0,
+			cols: SHELL_COLS,
+			rows: SHELL_ROWS
+		};
+		const artifact = new LiveArtifact(pathsFor(sessionId, id), limits, (error) => report(error, {
+			op: "artifact",
+			sessionId,
+			shellId: id
+		}));
+		const entry = {
+			info,
+			generation,
+			artifact,
+			sinks: /* @__PURE__ */ new Set(),
+			listeners: /* @__PURE__ */ new Set()
+		};
+		state.entries.set(id, entry);
+		const env = shellChildEnv(process.env);
+		env.TERM = TERM;
+		env.COLORTERM = "truecolor";
+		env.PWD = cwd;
+		let child;
+		try {
+			child = pty.spawn("/bin/sh", [
+				"-c",
+				CTTY_WRAPPER,
+				loginShell(process.env),
+				command
+			], {
+				name: TERM,
+				cols: SHELL_COLS,
+				rows: SHELL_ROWS,
+				cwd,
+				env
+			});
+		} catch (error) {
+			settle(state, entry, "spawn_failed");
+			throw error instanceof Error ? error : /* @__PURE__ */ new Error("failed to start the shell");
+		}
+		entry.child = child;
+		entry.pid = child.pid;
+		child.onData((data) => {
+			if (entry.info.status !== "running") return;
+			const changed = artifact.append(data);
+			entry.info.bytes = artifact.bytes;
+			if (changed) {
+				if (artifact.capped && !entry.info.capped) {
+					entry.info.capped = true;
+					entry.tailTimer = setInterval(() => artifact.writeTail(), tailFlushMs);
+					entry.tailTimer.unref();
+				}
+				persist(state);
+			}
+			for (const sink of entry.sinks) try {
+				sink.write(data);
+			} catch {
+				entry.sinks.delete(sink);
+			}
+			scheduleNotify(entry);
+		});
+		child.onExit(({ exitCode, signal }) => {
+			if (entry.info.status !== "running") return;
+			if (signal) entry.info.signal = signal;
+			else entry.info.exitCode = exitCode;
+			settle(state, entry, "exit");
+		});
+		if (options.timeoutMs !== void 0 && options.timeoutMs > 0) {
+			entry.clock = setTimeout(() => kill(state, entry, "timeout"), options.timeoutMs);
+			entry.clock.unref();
+		}
+		persist(state);
+		return {
+			shell: { ...info },
+			source: sourceFor(entry, artifact)
+		};
+	};
+	const sweep = async () => {
+		const now = Date.now();
+		for (const state of sessions.values()) {
+			let dirty = false;
+			for (const entry of state.entries.values()) {
+				const { status, endedAt } = entry.info;
+				if (status !== "exited" || endedAt === void 0 || now - endedAt < ttlMs) continue;
+				state.entries.delete(entry.info.id);
+				dirty = true;
+				try {
+					await entry.artifact.remove();
+				} catch (error) {
+					report(error, {
+						op: "sweep",
+						sessionId: state.sessionId,
+						shellId: entry.info.id
+					});
+				}
+			}
+			if (dirty) persist(state);
+		}
+	};
+	return {
+		spawn,
+		get: (sessionId, shellId) => {
+			const entry = find(sessionId, shellId);
+			return entry ? { ...entry.info } : void 0;
+		},
+		list: (sessionId) => {
+			const state = sessions.get(sessionId);
+			if (!state) return [];
+			return [...state.entries.values()].map((entry) => ({ ...entry.info })).sort((a, b) => b.ordinal - a.ordinal);
+		},
+		running: () => runningAll().map((entry) => ({ ...entry.info })),
+		kill: (sessionId, shellId, reason = "killed") => {
+			const state = sessions.get(sessionId);
+			const entry = state?.entries.get(shellId);
+			if (!state || !entry) return;
+			kill(state, entry, reason);
+			return { ...entry.info };
+		},
+		killAll: (reason) => {
+			stopped = true;
+			if (sweeper) {
+				clearInterval(sweeper);
+				sweeper = void 0;
+			}
+			return killEntries([...sessions.values()].flatMap((state) => runningIn(state).map((entry) => ({
+				state,
+				entry
+			}))), reason);
+		},
+		killAllSync: () => {
+			killTrees(runningAll());
+		},
+		attach: async (sessionId, shellId, sink) => {
+			const entry = find(sessionId, shellId);
+			if (!entry) throw new Error("unknown shell");
+			const pending = [];
+			let live = false;
+			let ended;
+			const proxy = {
+				write: (data) => {
+					if (live) sink.write(data);
+					else pending.push(data);
+				},
+				end: (reason) => {
+					if (live) sink.end(reason);
+					else ended = reason;
+				}
+			};
+			if (entry.info.status === "running") entry.sinks.add(proxy);
+			let replay;
+			try {
+				replay = await entry.artifact.replay(SHELL_ATTACH_REPLAY_BYTES);
+			} catch (error) {
+				entry.sinks.delete(proxy);
+				throw error;
+			}
+			live = true;
+			if (ended !== void 0) {
+				const reason = ended;
+				queueMicrotask(() => sink.end(reason));
+			}
+			return {
+				shell: { ...entry.info },
+				scrollback: replay.toString("utf8") + pending.join(""),
+				detach: () => {
+					entry.sinks.delete(proxy);
+				}
+			};
+		},
+		write: (sessionId, shellId, data) => {
+			const entry = find(sessionId, shellId);
+			if (!entry) throw new Error("unknown shell");
+			if (typeof data !== "string" || data.length > SHELL_INPUT_MAX) throw new Error(`shell input must be a string of at most ${SHELL_INPUT_MAX} characters`);
+			if (!entry.child) throw new Error("the shell has exited");
+			entry.child.write(data);
+		},
+		resize: (sessionId, shellId, size) => {
+			const entry = find(sessionId, shellId);
+			if (!entry) throw new Error("unknown shell");
+			const next = clampSize(size);
+			if (entry.child) {
+				try {
+					entry.child.resize(next.cols, next.rows);
+				} catch {}
+				entry.info.cols = next.cols;
+				entry.info.rows = next.rows;
+			}
+			return next;
+		},
+		output: async (sessionId, shellId, query) => {
+			const entry = find(sessionId, shellId);
+			if (!entry) return;
+			if (query.tail === void 0 && query.view === "text") return entry.artifact.textView();
+			const text = (await entry.artifact.read(query.tail)).toString("utf8");
+			return query.view === "raw" ? text : ttyText(text);
+		},
+		hydrate: async () => {
+			if (dir) {
+				let names = [];
+				try {
+					names = await readdir(dir);
+				} catch (error) {
+					if (!isMissing(error)) report(error, { op: "index" });
+				}
+				for (const name of names) {
+					if (!name.endsWith(INDEX_SUFFIX)) continue;
+					let sessionId;
+					try {
+						sessionId = decodeURIComponent(name.slice(0, -5));
+					} catch {
+						continue;
+					}
+					await load(sessionId);
+				}
+			}
+			await sweep();
+			if (!sweeper && !stopped) {
+				sweeper = setInterval(() => void sweep(), sweepIntervalMs);
+				sweeper.unref();
+			}
+		},
+		sweep,
+		flush: async () => {
+			const states = [...sessions.values()];
+			await Promise.all(states.flatMap((state) => [...state.entries.values()].map((entry) => entry.artifact.idle())));
+			await Promise.all(states.map((state) => state.chain));
+			if (!dir && stopped) await rm(base, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		},
+		decorate: (info) => {
+			const state = sessions.get(info.id);
+			if (!state) return info;
+			const now = Date.now();
+			const shells = [...state.entries.values()].filter((entry) => {
+				const { status, exitCode, endedAt } = entry.info;
+				return status === "running" || typeof exitCode === "number" && exitCode !== 0 && endedAt !== void 0 && now - endedAt < SHELL_LINGER_MS;
+			}).map((entry) => ({ ...entry.info }));
+			return shells.length > 0 ? {
+				...info,
+				shells
+			} : info;
+		},
+		watch: (runner) => runner.subscribe((event) => {
+			if (event.type === "session_closed" || event.type === "status_changed" && event.status === "parked") killSession(runner.id, "killed");
+		}, runner.info().lastSeq)
+	};
+}
+var LiveArtifact = class {
+	#paths;
+	#limits;
+	#onError;
+	#ring;
+	#ringAt = 0;
+	#ringLen = 0;
+	#chunks = [];
+	#chunkBytes = 0;
+	#bytes = 0;
+	#spilled = false;
+	#capped = false;
+	#closed = false;
+	#broken = false;
+	#io = Promise.resolve();
+	#handle;
+	#done = "";
+	#pending = "";
+	#textCache;
+	constructor(paths, limits, onError) {
+		this.#paths = paths;
+		this.#limits = limits;
+		this.#onError = onError;
+		this.#ring = Buffer.alloc(Math.max(0, limits.ring));
+	}
+	get bytes() {
+		return this.#bytes;
+	}
+	get capped() {
+		return this.#capped;
+	}
+	append(data) {
+		const chunk = Buffer.from(data, "utf8");
+		const before = this.#bytes;
+		this.#bytes += chunk.length;
+		this.#ringPush(chunk);
+		this.#textCache = void 0;
+		if (this.#capped) return false;
+		const room = Math.max(0, this.#limits.cap - before);
+		const kept = chunk.length <= room ? chunk : chunk.subarray(0, room);
+		this.#textAppend(kept === chunk ? data : kept.toString("utf8"));
+		let changed = false;
+		if (this.#spilled) this.#write(kept);
+		else {
+			this.#chunks.push(kept);
+			this.#chunkBytes += kept.length;
+			if (this.#chunkBytes > this.#limits.spill) {
+				this.#spill();
+				changed = true;
+			}
+		}
+		if (this.#bytes > this.#limits.cap) {
+			this.#capped = true;
+			changed = true;
+		}
+		return changed;
+	}
+	text() {
+		if (this.#textCache === void 0) {
+			let text = this.#done + ttyText(this.#pending);
+			if (this.#capped) {
+				const after = this.#bytes - this.#limits.cap;
+				const kept = Math.min(after, this.#ringLen);
+				if (kept > 0) text += (after > kept ? "\n" : "") + ttyText(this.tail(kept).toString("utf8"));
+			}
+			this.#textCache = text;
+		}
+		return this.#textCache;
+	}
+	textView() {
+		return Promise.resolve(this.text());
+	}
+	tail(n = this.#ringLen) {
+		const size = this.#ring.length;
+		const take = Math.max(0, Math.min(n, this.#ringLen));
+		const out = Buffer.allocUnsafe(take);
+		if (take === 0) return out;
+		const start = (this.#ringAt - take + size) % size;
+		const first = Math.min(take, size - start);
+		this.#ring.copy(out, 0, start, start + first);
+		if (first < take) this.#ring.copy(out, first, 0, take - first);
+		return out;
+	}
+	replay(max) {
+		const want = Math.max(0, Math.floor(max));
+		if (!this.#spilled) {
+			const all = Buffer.concat(this.#chunks, this.#chunkBytes);
+			return Promise.resolve(all.subarray(Math.max(0, all.length - want)));
+		}
+		if (this.#capped || want <= this.#ringLen) return Promise.resolve(this.tail(want));
+		const end = this.#bytes;
+		return this.#io.then(() => readRange(this.#paths.raw, Math.max(0, end - want), end));
+	}
+	async read(tail) {
+		if (tail !== void 0) return this.replay(tail);
+		if (!this.#spilled) return Buffer.concat(this.#chunks, this.#chunkBytes);
+		await this.#io;
+		return readWhole(this.#paths.raw);
+	}
+	stored() {
+		return this.#spilled ? { artifact: this.#paths.rel } : { output: Buffer.concat(this.#chunks, this.#chunkBytes).toString("utf8") };
+	}
+	writeTail() {
+		const tail = this.tail();
+		this.#queue(async () => {
+			await mkdir(this.#paths.dir, {
+				recursive: true,
+				mode: 448
+			});
+			const temp = `${this.#paths.tail}.${process.pid}.tmp`;
+			await writeFile(temp, tail, { mode: 384 });
+			await rename(temp, this.#paths.tail);
+		});
+	}
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		if (this.#capped) this.writeTail();
+		this.#io = this.#io.then(async () => {
+			const handle = this.#handle;
+			this.#handle = void 0;
+			await handle?.close().catch(() => {});
+		});
+	}
+	idle() {
+		return this.#io;
+	}
+	async remove() {
+		this.close();
+		await this.#io;
+		await rm(this.#paths.raw, { force: true });
+		await rm(this.#paths.tail, { force: true });
+	}
+	#textAppend(data) {
+		const newline = data.lastIndexOf("\n");
+		if (newline === -1) {
+			this.#pending += data;
+			return;
+		}
+		this.#done += ttyText(this.#pending + data.slice(0, newline + 1));
+		this.#pending = data.slice(newline + 1);
+	}
+	#ringPush(chunk) {
+		const size = this.#ring.length;
+		if (size === 0 || chunk.length === 0) return;
+		if (chunk.length >= size) {
+			chunk.copy(this.#ring, 0, chunk.length - size);
+			this.#ringAt = 0;
+			this.#ringLen = size;
+			return;
+		}
+		const first = Math.min(chunk.length, size - this.#ringAt);
+		chunk.copy(this.#ring, this.#ringAt, 0, first);
+		if (first < chunk.length) chunk.copy(this.#ring, 0, first);
+		this.#ringAt = (this.#ringAt + chunk.length) % size;
+		this.#ringLen = Math.min(size, this.#ringLen + chunk.length);
+	}
+	#spill() {
+		this.#spilled = true;
+		const buffered = Buffer.concat(this.#chunks, this.#chunkBytes);
+		this.#chunks = [];
+		this.#chunkBytes = 0;
+		this.#queue(async () => {
+			await mkdir(this.#paths.dir, {
+				recursive: true,
+				mode: 448
+			});
+			this.#handle = await open(this.#paths.raw, "w", 384);
+			await this.#handle.write(buffered);
+		});
+	}
+	#write(chunk) {
+		if (chunk.length === 0) return;
+		this.#queue(async () => {
+			await this.#handle?.write(chunk);
+		});
+	}
+	#queue(task) {
+		this.#io = this.#io.then(async () => {
+			if (this.#broken) return;
+			try {
+				await task();
+			} catch (error) {
+				this.#broken = true;
+				this.#onError(error);
+			}
+		});
+	}
+};
+var StoredArtifact = class {
+	#paths;
+	#bytes;
+	#capped;
+	#stored;
+	constructor(paths, info, stored) {
+		this.#paths = paths;
+		this.#bytes = info.bytes;
+		this.#capped = info.capped === true;
+		this.#stored = stored.artifact !== void 0 ? { artifact: stored.artifact } : { output: stored.output ?? "" };
+	}
+	async read(tail) {
+		if (tail !== void 0) return this.replay(tail);
+		return this.#head();
+	}
+	async replay(max) {
+		const want = Math.max(0, Math.floor(max));
+		if (this.#capped) {
+			const ring = await readWhole(this.#paths.tail);
+			return ring.subarray(Math.max(0, ring.length - want));
+		}
+		if (this.#stored.output !== void 0) {
+			const all = Buffer.from(this.#stored.output, "utf8");
+			return all.subarray(Math.max(0, all.length - want));
+		}
+		const size = await stat(this.#paths.raw).then((s) => s.size, () => 0);
+		return readRange(this.#paths.raw, Math.max(0, size - want), size);
+	}
+	async textView() {
+		const head = await this.#head();
+		let text = ttyText(head.toString("utf8"));
+		if (this.#capped) {
+			const ring = await readWhole(this.#paths.tail);
+			const after = this.#bytes - head.length;
+			const kept = Math.min(after, ring.length);
+			if (kept > 0) text += (after > kept ? "\n" : "") + ttyText(ring.subarray(ring.length - kept).toString("utf8"));
+		}
+		return text;
+	}
+	stored() {
+		return this.#stored;
+	}
+	idle() {
+		return Promise.resolve();
+	}
+	async remove() {
+		await rm(this.#paths.raw, { force: true });
+		await rm(this.#paths.tail, { force: true });
+	}
+	#head() {
+		return this.#stored.output !== void 0 ? Promise.resolve(Buffer.from(this.#stored.output, "utf8")) : readWhole(this.#paths.raw);
+	}
+};
+function serialize(state) {
+	return {
+		version: INDEX_VERSION,
+		sessionId: state.sessionId,
+		nextOrdinal: state.nextOrdinal,
+		shells: [...state.entries.values()].map((entry) => ({
+			...entry.info,
+			generation: entry.generation,
+			...entry.artifact.stored()
+		}))
+	};
+}
+function parseIndex(value) {
+	const index = value;
+	if (!index || index.version !== INDEX_VERSION || typeof index.sessionId !== "string" || !Array.isArray(index.shells)) throw new Error("unrecognised shell index");
+	const shells = index.shells.filter((record) => typeof record === "object" && record !== null && typeof record.id === "string");
+	const nextOrdinal = typeof index.nextOrdinal === "number" && index.nextOrdinal > 0 ? index.nextOrdinal : 1;
+	return {
+		version: INDEX_VERSION,
+		sessionId: index.sessionId,
+		nextOrdinal,
+		shells
+	};
+}
+function freshSession(sessionId) {
+	return {
+		sessionId,
+		nextOrdinal: 1,
+		entries: /* @__PURE__ */ new Map(),
+		chain: Promise.resolve(),
+		pending: false
+	};
+}
+function runningIn(state) {
+	return [...state.entries.values()].filter((entry) => entry.info.status === "running");
+}
+function sourceFor(entry, artifact) {
+	return {
+		info: () => entry.info,
+		text: () => artifact.text(),
+		subscribe: (listener) => {
+			entry.listeners.add(listener);
+			return () => {
+				entry.listeners.delete(listener);
+			};
+		}
+	};
+}
+function mintShellId() {
+	const bytes = randomBytes(ID_CHARS);
+	let id = "sh_";
+	for (let i = 0; i < ID_CHARS; i++) id += ID_ALPHABET[bytes[i] & 31];
+	return id;
+}
+function shellLabel(command) {
+	return (command.split("\n")[0] ?? "").trim().slice(0, SHELL_LABEL_MAX);
+}
+function clamp(value, min, max) {
+	return Number.isFinite(value) ? Math.min(max, Math.max(min, Math.trunc(value))) : min;
+}
+function isMissing(error) {
+	return error?.code === "ENOENT";
+}
+async function readWhole(path) {
+	try {
+		return await readFile(path);
+	} catch (error) {
+		if (isMissing(error)) return Buffer.alloc(0);
+		throw error;
+	}
+}
+async function readRange(path, start, end) {
+	const length = Math.max(0, end - start);
+	if (length === 0) return Buffer.alloc(0);
+	let handle;
+	try {
+		handle = await open(path, "r");
+	} catch (error) {
+		if (isMissing(error)) return Buffer.alloc(0);
+		throw error;
+	}
+	try {
+		const out = Buffer.allocUnsafe(length);
+		let got = 0;
+		while (got < length) {
+			const { bytesRead } = await handle.read(out, got, length - got, start + got);
+			if (bytesRead === 0) break;
+			got += bytesRead;
+		}
+		return got === length ? out : out.subarray(0, got);
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+//#region src/routes/shells.ts
+async function handleShells(ctx, req, res, route, runner, operator) {
+	const { shells } = ctx;
+	const sessionId = route.id;
+	if (!shells) {
+		json(res, 404, { error: SHELL_REFUSAL });
+		return;
+	}
+	if (!operator) {
+		json(res, 403, { error: SHELL_REFUSAL });
+		return;
+	}
+	if (route.shellId === void 0) {
+		if (req.method !== "GET") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		json(res, 200, { shells: shells.list(sessionId) });
+		return;
+	}
+	if (route.shellAction === "kill") {
+		if (req.method !== "POST") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		if (!runner || !shellPermitted(shells, runner, operator)) {
+			json(res, 403, { error: SHELL_REFUSAL });
+			return;
+		}
+		const shell = shells.kill(sessionId, route.shellId);
+		if (!shell) {
+			json(res, 404, { error: "shell not found" });
+			return;
+		}
+		json(res, 200, { shell });
+		return;
+	}
+	if (req.method !== "GET") {
+		json(res, 405, { error: "method not allowed" });
+		return;
+	}
+	if (route.shellAction === "output") {
+		const url = new URL(req.url ?? "/", "http://internal");
+		const view = url.searchParams.get("view") === "raw" ? "raw" : "text";
+		const tailParam = url.searchParams.get("tail");
+		const tail = tailParam === null ? void 0 : Number(tailParam);
+		if (tail !== void 0 && (!Number.isInteger(tail) || tail <= 0)) {
+			json(res, 400, { error: "tail must be a positive integer" });
+			return;
+		}
+		const output = await shells.output(sessionId, route.shellId, {
+			view,
+			tail
+		});
+		if (output === void 0) {
+			json(res, 404, { error: "shell not found" });
+			return;
+		}
+		const body = Buffer.from(output, "utf8");
+		res.writeHead(200, untrustedDownloadHeaders(`${route.shellId}.txt`, "text/plain; charset=utf-8", body.length));
+		res.end(body);
+		return;
+	}
+	const shell = shells.get(sessionId, route.shellId);
+	if (!shell) {
+		json(res, 404, { error: "shell not found" });
+		return;
+	}
+	json(res, 200, { shell });
+}
+//#endregion
 //#region src/routes/tool-results.ts
 function handleToolResult(req, res, lookup, seq) {
 	if (req.method !== "GET") {
@@ -1517,13 +2661,12 @@ async function handleSessions(ctx, req, res, route, auth) {
 			return;
 		}
 		if (req.method === "POST") {
-			const body = await readJsonBody(req, ctx.maxBodyBytes);
-			const refusal = vetCreateRequest(ctx, body, auth);
-			if (refusal) {
-				json(res, refusal.status, { error: refusal.error });
+			const vetted = vetCreateRequest(ctx, await readJsonBody(req, ctx.maxBodyBytes), auth);
+			if (!vetted.ok) {
+				json(res, vetted.status, { error: vetted.error });
 				return;
 			}
-			const runner = await factory.createRunner(factory.buildRunnerConfig(body));
+			const runner = await factory.createRunner(factory.buildRunnerConfig(vetted.request));
 			factory.watchAuthSource(runner);
 			json(res, 201, { session: projects.withProject(runner.info()) });
 			return;
@@ -1588,6 +2731,10 @@ async function handleSessions(ctx, req, res, route, auth) {
 		await handleProducedFiles(ctx, req, res, route.id, route.producedFileId);
 		return;
 	}
+	if (route.shells) {
+		await handleShells(ctx, req, res, route, runner ?? null, authSvc.isOperator(auth));
+		return;
+	}
 	if (route.projectIcon) {
 		handleProjectIcon(projects, req, res, (runner?.info() ?? parked.info).cwd);
 		return;
@@ -1611,7 +2758,15 @@ async function handleSessions(ctx, req, res, route, auth) {
 			json(res, 409, { error: "session is parked (it has no pending permission requests)" });
 			return;
 		}
-		if (!runner.resolvePermission(route.permissionId, body)) {
+		const decision = body.behavior === "allow" ? {
+			behavior: "allow",
+			updatedInput: body.updatedInput
+		} : {
+			behavior: "deny",
+			message: body.message,
+			interrupt: body.interrupt
+		};
+		if (!runner.resolvePermission(route.permissionId, decision)) {
 			json(res, 404, { error: "permission request not found (already resolved or expired)" });
 			return;
 		}
@@ -1654,151 +2809,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 	}
 	json(res, 405, { error: "method not allowed" });
 }
-const TIMEOUT_EXIT_CODE = 124;
-const SPAWN_FAILURE_EXIT_CODE = 127;
-const KILLED_EXIT_CODE = 128 + constants$1.signals.SIGKILL;
-function shellPermitted(shell, runner, operator) {
-	if (shell === null || !operator) return false;
-	const info = runner.info();
-	return (info.capabilities ?? (info.engine ? ENGINE_CAPABILITIES[info.engine] : void 0))?.hostCwd === true;
-}
-function shellChildEnv(base) {
-	const env = {};
-	for (const [key, value] of Object.entries(base)) if (value !== void 0) env[key] = value;
-	return env;
-}
-function createShellService(options = {}) {
-	const timeoutMs = options.timeoutMs ?? 12e4;
-	const maxOutputBytes = options.maxOutputBytes ?? 32768;
-	const active = /* @__PURE__ */ new Map();
-	const run = async (sessionId, cwd, command) => {
-		if (active.has(sessionId)) throw new Error("a shell command is still running on this session");
-		const child = spawnShell({
-			command,
-			cwd,
-			env: shellChildEnv(process.env),
-			timeoutMs,
-			maxOutputBytes
-		});
-		active.set(sessionId, child);
-		try {
-			return await child.result;
-		} finally {
-			if (active.get(sessionId) === child) active.delete(sessionId);
-		}
-	};
-	const kill = (sessionId, reason = "session closed") => {
-		active.get(sessionId)?.kill(reason);
-	};
-	const watch = (runner) => runner.subscribe((event) => {
-		if (event.type === "session_closed") kill(runner.id, "session closed");
-		else if (event.type === "status_changed" && event.status === "parked") kill(runner.id, "session parked");
-	}, runner.info().lastSeq);
-	const killAll = () => {
-		for (const sessionId of active.keys()) kill(sessionId, "server shutting down");
-	};
-	const running = (sessionId) => active.has(sessionId);
-	return {
-		run,
-		kill,
-		watch,
-		killAll,
-		running,
-		timeoutMs,
-		maxOutputBytes
-	};
-}
-var BoundedOutput = class {
-	#chunks = [];
-	#kept = 0;
-	#dropped = 0;
-	#budget;
-	constructor(budget) {
-		this.#budget = budget;
-	}
-	push(chunk) {
-		const take = Math.min(chunk.length, this.#budget.remaining);
-		if (take > 0) {
-			this.#chunks.push(take === chunk.length ? chunk : chunk.subarray(0, take));
-			this.#kept += take;
-			this.#budget.remaining -= take;
-		}
-		this.#dropped += chunk.length - take;
-	}
-	text() {
-		const head = Buffer.concat(this.#chunks, this.#kept).toString("utf8");
-		return this.#dropped > 0 ? `${head}\n[output truncated: ${this.#dropped} more bytes dropped]` : head;
-	}
-};
-function spawnShell(input) {
-	const startedAt = Date.now();
-	const budget = { remaining: input.maxOutputBytes };
-	const stdout = new BoundedOutput(budget);
-	const stderr = new BoundedOutput(budget);
-	let settle;
-	const result = new Promise((resolve) => {
-		settle = resolve;
-	});
-	let done = false;
-	const finish = (exitCode, note) => {
-		if (done) return;
-		done = true;
-		clearTimeout(timer);
-		const captured = stderr.text();
-		const stderrText = note ? captured ? `${captured}\n[${note}]` : `[${note}]` : captured;
-		settle?.({
-			command: input.command,
-			stdout: stdout.text(),
-			stderr: stderrText,
-			exitCode,
-			durationMs: Date.now() - startedAt
-		});
-	};
-	const child = spawn("/bin/sh", ["-c", input.command], {
-		cwd: input.cwd,
-		env: {
-			...input.env,
-			PWD: input.cwd
-		},
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		],
-		detached: true
-	});
-	child.stdout.on("data", (chunk) => stdout.push(chunk));
-	child.stderr.on("data", (chunk) => stderr.push(chunk));
-	const killGroup = () => {
-		if (child.pid === void 0) return;
-		try {
-			process.kill(-child.pid, "SIGKILL");
-		} catch {
-			try {
-				child.kill("SIGKILL");
-			} catch {}
-		}
-		child.stdout.destroy();
-		child.stderr.destroy();
-	};
-	const kill = (reason, exitCode = KILLED_EXIT_CODE) => {
-		if (done) return;
-		killGroup();
-		finish(exitCode, `killed: ${reason}`);
-	};
-	const timer = setTimeout(() => kill(`timed out after ${Math.round(input.timeoutMs / 1e3)}s`, TIMEOUT_EXIT_CODE), input.timeoutMs);
-	child.on("error", (error) => finish(SPAWN_FAILURE_EXIT_CODE, error.message));
-	child.on("close", (code, signal) => {
-		const signalCode = signal ? constants$1.signals[signal] ?? 0 : 0;
-		finish(code ?? (signalCode ? 128 + signalCode : 1), signal ? `killed by ${signal}` : void 0);
-	});
-	return {
-		result,
-		kill: (reason) => kill(reason)
-	};
-}
-//#endregion
-//#region src/routes/ws.ts
+const SHELL_DETACHED_BACKPRESSURE = "backpressure";
 function attachClient(ctx, ws, runner, req, access) {
 	const { bridge, parking } = ctx;
 	const url = new URL(req.url ?? "/", "http://internal");
@@ -1808,12 +2819,18 @@ function attachClient(ctx, ws, runner, req, access) {
 	const send = (frame) => {
 		if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(frame));
 	};
+	const client = {
+		send,
+		open: () => ws.readyState === ws.OPEN,
+		buffered: () => ws.bufferedAmount,
+		shells: /* @__PURE__ */ new Map()
+	};
 	send({
 		type: "attached",
 		protocolVersion: PROTOCOL_VERSION,
 		session: ctx.projects.withProject(runner.info()),
 		replayingFrom: afterSeq,
-		...shellPermitted(ctx.shell, runner, access.operator) ? { shell: true } : {},
+		...shellPermitted(ctx.shells, runner, access.operator) ? { shell: true } : {},
 		...ctx.pricingOverrides ? { pricingOverrides: ctx.pricingOverrides } : {}
 	});
 	const unsubscribe = runner.subscribe((event) => send({
@@ -1837,7 +2854,7 @@ function attachClient(ctx, ws, runner, req, access) {
 			});
 			return;
 		}
-		handleCommand(ctx, frame, runner, access).catch((error) => {
+		handleCommand(ctx, frame, runner, access, client).catch((error) => {
 			send({
 				type: "protocol_error",
 				message: error instanceof Error ? error.message : "command failed"
@@ -1845,12 +2862,13 @@ function attachClient(ctx, ws, runner, req, access) {
 		});
 	});
 	ws.on("close", () => {
+		detachShells(client);
 		unsubscribe();
 		detachBridge();
 		parking.onDetach(runner.id);
 	});
 }
-async function handleCommand(ctx, frame, runner, access) {
+async function handleCommand(ctx, frame, runner, access, client) {
 	const { attachmentStore, bridge } = ctx;
 	switch (frame.type) {
 		case "user_message": {
@@ -1904,21 +2922,107 @@ async function handleCommand(ctx, frame, runner, access) {
 			});
 			return;
 		case "shell_command": {
-			if (!shellPermitted(ctx.shell, runner, access.operator) || ctx.shell === null) throw new Error("shell commands are not available on this session");
+			const shells = permittedShells(ctx, runner, access);
 			if (typeof frame.command !== "string" || frame.command.includes("\0")) throw new Error("shell command must be a string");
 			if (frame.command.length > SHELL_COMMAND_MAX) throw new Error(`shell command exceeds ${SHELL_COMMAND_MAX} characters`);
 			if (frame.command.trim() === "") throw new Error("shell command is empty");
 			if (!runner.queueLocalCommand) throw new Error(`the ${runner.info().engine ?? "claude"} engine cannot take shell output`);
-			const result = await ctx.shell.run(runner.id, runner.info().cwd, frame.command);
-			runner.queueLocalCommand(result);
+			const { shell, source } = await shells.spawn({
+				runner,
+				command: frame.command,
+				owner: "user"
+			});
+			try {
+				runner.queueLocalCommand(source);
+			} catch (error) {
+				shells.kill(runner.id, shell.id);
+				throw error;
+			}
 			return;
 		}
+		case "shell_attach":
+			await attachShell(permittedShells(ctx, runner, access), client, runner.id, frame.shellId, {
+				cols: frame.cols,
+				rows: frame.rows
+			});
+			return;
+		case "shell_input":
+			permittedShells(ctx, runner, access).write(runner.id, frame.shellId, frame.data);
+			return;
+		case "shell_resize":
+			permittedShells(ctx, runner, access).resize(runner.id, frame.shellId, {
+				cols: frame.cols,
+				rows: frame.rows
+			});
+			return;
+		case "shell_detach":
+			detachShell(client, frame.shellId);
+			return;
 		case "close":
 			runner.close("client");
 			return;
 		default: throw new Error(`unknown command: ${frame.type}`);
 	}
 }
+function permittedShells(ctx, runner, access) {
+	if (ctx.shells === null || !shellPermitted(ctx.shells, runner, access.operator)) throw new Error(SHELL_REFUSAL);
+	return ctx.shells;
+}
+async function attachShell(shells, client, sessionId, shellId, size) {
+	shells.resize(sessionId, shellId, size);
+	let detach;
+	const drop = (reason) => {
+		if (detach === void 0 || client.shells.get(shellId) !== detach) return;
+		client.shells.delete(shellId);
+		detach();
+		client.send({
+			type: "shell_detached",
+			shellId,
+			reason
+		});
+	};
+	const sink = {
+		write: (data) => {
+			if (client.buffered() > 4194304) {
+				drop(SHELL_DETACHED_BACKPRESSURE);
+				return;
+			}
+			client.send({
+				type: "shell_output",
+				shellId,
+				data
+			});
+		},
+		end: drop
+	};
+	const attached = await shells.attach(sessionId, shellId, sink);
+	if (!client.open()) {
+		attached.detach();
+		return;
+	}
+	detachShell(client, shellId);
+	if (attached.shell.status === "running") {
+		detach = attached.detach;
+		client.shells.set(shellId, detach);
+	}
+	const { shell, scrollback } = attached;
+	client.send({
+		type: "shell_attached",
+		shellId,
+		shell,
+		cols: shell.cols,
+		rows: shell.rows,
+		scrollback
+	});
+}
+function detachShell(client, shellId) {
+	client.shells.get(shellId)?.();
+	client.shells.delete(shellId);
+}
+function detachShells(client) {
+	for (const detach of client.shells.values()) detach();
+	client.shells.clear();
+}
 //#endregion
 //#region src/services/attachments.ts
 const DEFAULT_MAX_FILE_BYTES = 10485760;
@@ -2742,7 +3846,6 @@ var ProfileService = class {
 			if (!hasEngineRunnerFactory) return `profile '${p.name}' uses engine 'provider' but no \`createEngineRunner\` was provided to build one`;
 		} else if (p.engine === "codex") {
 			if (p.codexHome && !existsSync(p.codexHome)) return `profile '${p.name}' codexHome does not exist: ${p.codexHome}`;
-			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver - put instructions in the target repo’s AGENTS.md instead`;
 		} else if (!p.configDir || !existsSync(p.configDir)) return `profile '${p.name}' configDir does not exist: ${p.configDir}`;
 		if (disableBypassPermissions && p.defaults?.permissionMode === "bypassPermissions") return `profile '${p.name}' defaults to bypassPermissions but disableBypassPermissions is set`;
 		const fallbackMode = p.defaults?.permissionMode;
@@ -3396,13 +4499,16 @@ function createSessionFactory(deps) {
 		}
 	};
 	const buildRunner = async (built, restore, id) => {
-		const config = deps.peers ? {
-			...built,
-			peers: deps.peers
-		} : built;
-		const name = config.profile;
+		const name = built.profile;
 		const profile = name !== void 0 ? profiles.get(name) : void 0;
 		if (name !== void 0 && !profile) throw new Error(`unknown profile: ${name}`);
+		const capabilities = profile?.capabilities ?? adapterFor(profile?.engine).capabilities;
+		const config = {
+			...built,
+			...deps.peers ? { peers: deps.peers } : {},
+			...deps.shells && capabilities.hostCwd === true ? { shells: deps.shells } : {}
+		};
+		if (config.instructions !== void 0 && capabilities.systemInstructions === false) throw new Error(`the ${engineOf(profile)} engine cannot deliver system instructions`);
 		const runner = profile && isProviderProfile(profile) ? await deps.createEngineRunner({
 			config,
 			profile,
@@ -3496,7 +4602,7 @@ function createSessionFactory(deps) {
 const SOCKET_CLOSE_GRACE_MS = 250;
 const CLOSE_DEADLINE_MS = 1e3;
 const USAGE_STALE_MS = 3e5;
-function surveyDrain(registry) {
+function surveyDrain(registry, shells) {
 	const working = [];
 	const awaitingHuman = [];
 	for (const info of registry.list()) {
@@ -3507,7 +4613,12 @@ function surveyDrain(registry) {
 	return {
 		working,
 		awaitingHuman,
-		timedOut: false
+		timedOut: false,
+		shells: (shells?.running() ?? []).map(({ sessionId, id, label }) => ({
+			sessionId,
+			id,
+			label
+		}))
 	};
 }
 function sameDrain(a, b) {
@@ -3567,13 +4678,24 @@ function createWorkerServer(options = {}) {
 		if (invalid) throw new Error(`createWorkerServer: ${invalid}`);
 	}
 	const refs = {};
-	const projects = new ProjectInfoService();
+	const generation = randomUUID();
+	const shells = options.shell?.enabled === true ? createShellRegistry({
+		generation,
+		artifactDir: options.shell.artifactDir ?? null,
+		timeoutMs: options.shell.timeoutMs,
+		artifactMaxBytes: options.shell.artifactMaxBytes,
+		artifactTtlMs: options.shell.artifactTtlMs,
+		maxRunningPerSession: options.shell.maxRunningPerSession,
+		onError: (error, context) => console.warn(`[workerdeck] shell ${context.op} error (${context.shellId ?? context.sessionId ?? "-"}): ${String(error)}`)
+	}) : null;
+	const projects = new ProjectInfoService({ decorate: (info) => shells ? shells.decorate(info) : info });
 	const peers = options.peers?.enabled === false ? void 0 : createPeerService({
 		refs,
 		projects,
 		options: options.peers
 	});
 	if (peers) installPeerDirectory(peers);
+	installShellDirectory(shells ? createShellDirectory(shells) : void 0);
 	const factory = createSessionFactory({
 		adapterFor,
 		profiles,
@@ -3584,6 +4706,7 @@ function createWorkerServer(options = {}) {
 		approvalTimeoutMs: options.approvalTimeoutMs,
 		requireApiKey: options.requireApiKey,
 		peers: peers ? peerDirectoryHandle() : void 0,
+		shells: shells ? shellDirectoryHandle() : void 0,
 		refs
 	});
 	const availability = new AvailabilityTracker({
@@ -3597,14 +4720,13 @@ function createWorkerServer(options = {}) {
 		decorateInfo: (info) => projects.withProject(info)
 	});
 	const producedFiles = new ProducedFileStore();
-	const shell = options.shell?.enabled === true ? createShellService(options.shell) : null;
 	const registry = new SessionRegistry({ onRegister: (runner) => {
 		const detachers = [
 			notifier.watch(runner),
 			producedFiles.watch(runner),
 			profileUsage.watch(runner),
 			spendLedger.watch(runner),
-			shell?.watch(runner),
+			shells?.watch(runner),
 			peers?.watch(runner)
 		];
 		const profile = runner.info().profile;
@@ -3715,7 +4837,8 @@ function createWorkerServer(options = {}) {
 		hostFilesWritable: options.hostFiles?.write === true,
 		maxHostFileBytes: options.hostFiles?.maxFileBytes ?? 1048576,
 		maxHostDirEntries: options.hostFiles?.maxEntries ?? 5e3,
-		shell,
+		shells,
+		generation,
 		pricingOverrides: Object.keys(pricing.overrides).length > 0 ? pricing.overrides : void 0
 	};
 	const handleRequest = async (req, res) => {
@@ -3784,6 +4907,18 @@ function createWorkerServer(options = {}) {
 			await handleSdkSessions(ctx, req, res, authCtx);
 			return;
 		}
+		if (pathname === basePath + "/meta") {
+			const authCtx = await auth.authenticate(req);
+			if (!authCtx.ok) {
+				json(res, 401, { error: "unauthorized" });
+				return;
+			}
+			json(res, 200, {
+				protocolVersion: PROTOCOL_VERSION,
+				...auth.isOperator(authCtx) ? { machineId: machineId() } : {}
+			});
+			return;
+		}
 		if (pathname.startsWith(basePath + "/fs/")) {
 			const authCtx = await auth.authenticate(req);
 			if (!authCtx.ok) {
@@ -3884,10 +5019,12 @@ function createWorkerServer(options = {}) {
 		queue,
 		bridge,
 		parking,
+		shells,
 		listen: async (port, host) => {
 			await profiles.refreshStored();
 			await profiles.seedStore();
 			await parking.hydrate();
+			await shells?.hydrate();
 			return new Promise((resolve, reject) => {
 				server.once("error", reject);
 				server.listen(port, host, () => {
@@ -3919,16 +5056,16 @@ function createWorkerServer(options = {}) {
 			const { timeoutMs = 3e4, pollMs = 250, onProgress } = drainOptions;
 			draining = true;
 			const deadline = Date.now() + timeoutMs;
-			let report = surveyDrain(registry);
+			let report = surveyDrain(registry, shells);
 			onProgress?.(report);
 			while (report.working.length > 0 && Date.now() < deadline) {
 				await new Promise((resolve) => setTimeout(resolve, pollMs));
-				const next = surveyDrain(registry);
+				const next = surveyDrain(registry, shells);
 				if (!sameDrain(next, report)) onProgress?.(next);
 				report = next;
 			}
 			report = {
-				...surveyDrain(registry),
+				...surveyDrain(registry, shells),
 				timedOut: false
 			};
 			report.timedOut = report.working.length > 0;
@@ -3938,23 +5075,25 @@ function createWorkerServer(options = {}) {
 		close: () => {
 			closing ??= new Promise((resolve) => {
 				queue?.close();
+				shells?.killAll("server_stopped");
+				const flushed = shells?.flush().catch(() => {}) ?? Promise.resolve();
 				parking.close();
 				registry.closeAll();
-				shell?.killAll();
 				for (const ws of wss.clients) ws.close(1001, "server shutting down");
 				queueSockets.clear();
 				const force = setTimeout(() => {
 					for (const ws of wss.clients) ws.terminate();
 				}, SOCKET_CLOSE_GRACE_MS);
 				force.unref();
-				const deadline = setTimeout(() => resolve(), CLOSE_DEADLINE_MS);
+				const finish = () => void flushed.then(() => resolve());
+				const deadline = setTimeout(finish, CLOSE_DEADLINE_MS);
 				deadline.unref();
 				const drained = Promise.all([new Promise((done) => wss.close(() => done())), new Promise((done) => server.close(() => done()))]);
 				server.closeAllConnections();
 				drained.then(() => {
 					clearTimeout(force);
 					clearTimeout(deadline);
-					resolve();
+					finish();
 				});
 			});
 			return closing;
@@ -4052,6 +5191,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, toDurableRecord };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SHELL_REFUSAL, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellRegistry, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map