@workerdeck/server 0.13.0 → 0.15.0

package/build/index.mjs

@@ -4,7 +4,7 @@ import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { WebSocketServer } from "ws";
-import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
+import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, createEngineSession, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
 import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, supportsPermissionMode } from "@workerdeck/protocol";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -803,11 +803,213 @@ var BridgeHub = class {
 	}
 };
 //#endregion
+//#region src/session-store.ts
+const isDormant = (record) => record.kind === "dormant";
+/** Single-process, no persistence: parks survive a client disconnect, not a restart. */
+var MemorySessionStore = class {
+	#records = /* @__PURE__ */ new Map();
+	save(record) {
+		this.#records.set(record.id, record);
+		return Promise.resolve();
+	}
+	get(id) {
+		return Promise.resolve(this.#records.get(id) ?? null);
+	}
+	list() {
+		return Promise.resolve([...this.#records.values()]);
+	}
+	delete(id) {
+		return Promise.resolve(this.#records.delete(id));
+	}
+};
+/**
+* Config fields that must not be written to durable storage: two are functions
+* (JSON drops them silently), `extraOptions` is SDK `Options` and may hold hooks
+* and callbacks, and `env` is a credential-bearing map — the same rule
+* `profile-store.ts` follows, for the same reason.
+*
+* Dropping them costs a rehydrated session nothing, but the reason differs by
+* record kind and both halves matter. A provider session's credentials are
+* resolved by `createEngineRunner` from the operator's environment on every
+* build, wake included — so a parked record never needed them. A **dormant**
+* record is a claude or codex session, which does consume `env` (the profile's
+* `CLAUDE_CONFIG_DIR` pin lives there), and that is precisely why waking one
+* feeds its config back through the server's `buildRunnerConfig` instead of
+* handing it to the engine as-is: the pin and the host hook's injections are
+* re-derived from the profile, never read back off disk. Persisting them would
+* be a credential map in a file *and* a stale one.
+*/
+const EPHEMERAL_CONFIG_KEYS = [
+	"queryFn",
+	"historyFn",
+	"extraOptions",
+	"env"
+];
+/** The record as it may be persisted: same session, config narrowed to what is
+* safe and meaningful to keep (see {@link EPHEMERAL_CONFIG_KEYS}). */
+function toDurableRecord(record) {
+	const config = { ...record.config };
+	for (const key of EPHEMERAL_CONFIG_KEYS) delete config[key];
+	return {
+		...record,
+		config
+	};
+}
+/** Bump when the on-disk shape changes incompatibly; records written by another
+* version are ignored rather than half-read into a broken session. */
+const FORMAT_VERSION = 1;
+/**
+* Durable single-host store: one JSON file per parked session under `dir`, written
+* through a temp file and a rename so a crash mid-write cannot truncate a session.
+* `hydrate()` at `listen()` picks them up, re-indexes their executions, and re-arms
+* the watchdogs, so a restart no longer loses parked work.
+*
+* Know what is on that disk: **the record holds the session's entire transcript** —
+* prompts, model output, and tool I/O — in plaintext. Put it somewhere with the same
+* protection as the SDK's own transcripts (`~/.claude/projects`), not in a directory
+* that gets served, synced, or backed up somewhere looser.
+*
+* Single-process by design, exactly like the bundled queue adapter and profile
+* store: two servers sharing one directory would both hydrate the same records and
+* race to rebuild them. That is what the seam is for.
+*
+* Nothing here reaps: a record leaves only when its session wakes or is deleted.
+* An execution dispatched without a deadline (a `DeferredExecutor` with no
+* `timeoutMs`) has no watchdog to end the wait, so its record — and its transcript
+* — stays until `DELETE /sessions/:id`. Give deferred calls a deadline, or sweep.
+*/
+function createFileSessionStore(options = {}) {
+	const dir = options.dir ?? join(process.cwd(), ".workerdeck", "parked");
+	const fileFor = (id) => join(dir, `${encodeURIComponent(id)}.json`);
+	const read = async (path) => {
+		let raw;
+		try {
+			raw = await readFile(path, "utf8");
+		} catch (error) {
+			if (isMissing(error)) return null;
+			options.onError?.(error, {
+				path,
+				op: "read"
+			});
+			return null;
+		}
+		try {
+			return parseRecord(JSON.parse(raw));
+		} catch (error) {
+			options.onError?.(error, {
+				path,
+				op: "read"
+			});
+			return null;
+		}
+	};
+	return {
+		save: async (record) => {
+			const path = fileFor(record.id);
+			let payload;
+			try {
+				payload = JSON.stringify({
+					version: FORMAT_VERSION,
+					record: toDurableRecord(record)
+				});
+			} catch (error) {
+				options.onError?.(error, {
+					path,
+					op: "save"
+				});
+				throw new Error(`parked session '${record.id}' is not JSON-serializable — a host-injected value reached its config or snapshot: ${String(error)}`);
+			}
+			try {
+				await mkdir(dir, {
+					recursive: true,
+					mode: 448
+				});
+				const temp = `${path}.${process.pid}.tmp`;
+				await writeFile(temp, payload, { mode: 384 });
+				await rename(temp, path);
+			} catch (error) {
+				options.onError?.(error, {
+					path,
+					op: "save"
+				});
+				throw error;
+			}
+		},
+		get: (id) => read(fileFor(id)),
+		list: async () => {
+			let names;
+			try {
+				names = await readdir(dir);
+			} catch (error) {
+				if (isMissing(error)) return [];
+				options.onError?.(error, {
+					path: dir,
+					op: "read"
+				});
+				throw error;
+			}
+			return (await Promise.all(names.filter((name) => name.endsWith(".json")).map(async (name) => {
+				const record = await read(join(dir, name));
+				if (!record) return null;
+				if (`${encodeURIComponent(record.id)}.json` === name) return record;
+				options.onError?.(/* @__PURE__ */ new Error(`parked record '${record.id}' is stored as '${name}' and cannot be read back by id`), {
+					path: join(dir, name),
+					op: "read"
+				});
+				return null;
+			}))).filter((record) => record !== null);
+		},
+		delete: async (id) => {
+			const path = fileFor(id);
+			try {
+				await rm(path);
+				return true;
+			} catch (error) {
+				if (isMissing(error)) return false;
+				options.onError?.(error, {
+					path,
+					op: "delete"
+				});
+				return false;
+			}
+		}
+	};
+}
+const isMissing = (error) => error.code === "ENOENT";
+/** Shape-check a parsed file. A record missing any of these could not be rebuilt,
+* and half-restoring one is worse than skipping it. */
+function parseRecord(value) {
+	if (!value || typeof value !== "object") return null;
+	const envelope = value;
+	if (envelope.version !== FORMAT_VERSION) return null;
+	const record = envelope.record;
+	if (!record || typeof record !== "object") return null;
+	if (typeof record.id !== "string") return null;
+	if (!record.info || !record.config) return null;
+	if (record.kind === "dormant") {
+		const dormant = record;
+		if (typeof dormant.sdkSessionId !== "string" || typeof dormant.savedAt !== "number") return null;
+		return dormant;
+	}
+	const parked = record;
+	if (typeof parked.parkedAt !== "number" || !parked.snapshot) return null;
+	if (!Array.isArray(parked.executions)) return null;
+	return parked;
+}
+//#endregion
 //#region src/parking.ts
 /**
-* Deferred execution's other half: parking a session that is waiting on work no
+* Two ways a session outlives its runner, behind one door.
+*
+* **Parking** is deferred execution's other half: a session waiting on work no
 * process in this server is doing.
 *
+* **Dormancy** is the restart story for the engines that cannot park. Every live
+* claude or codex session leaves a small record naming its engine session id, so
+* a gateway that comes back up lists them and resumes one the first time someone
+* attaches. Both kinds live in the same store and come back through the same
+* `ensureLive`, which is why there is one class here and not two.
+*
 * The runner announces the moment with `status_changed: 'parked'` — emitted only
 * once every dispatch of the batch has been handed over, so the snapshot can never
 * miss a call that was still being dispatched. From there this class snapshots,
@@ -855,12 +1057,21 @@ var SessionParkManager = class {
 	remember(sessionId, config) {
 		this.#configs.set(sessionId, config);
 	}
-	/** Adopt the store's contents (a durable store after a restart): re-index the
+	/**
+	* Adopt the store's contents (a durable store after a restart): re-index the
 	* executions and re-arm their watchdogs, no deadline sooner than the grace
-	* window — nothing could have been delivered while the process was down. */
+	* window — nothing could have been delivered while the process was down.
+	*
+	* Dormant records need nothing here, which is the point of them. They list
+	* from the store (`listInfo`) and come back on first attach (`ensureLive`), so
+	* a boot with fifty remembered sessions spawns nothing at all.
+	*/
 	async hydrate() {
 		const floor = Date.now() + (this.#options.expiredGraceMs ?? 6e4);
-		for (const record of await this.#options.store.list()) for (const execution of record.executions) this.#track(record.id, execution, floor);
+		for (const record of await this.#options.store.list()) {
+			if (isDormant(record)) continue;
+			for (const execution of record.executions) this.#track(record.id, execution, floor);
+		}
 	}
 	/**
 	* Follow a session's lifecycle: index its deferred executions, park it when the
@@ -886,8 +1097,13 @@ var SessionParkManager = class {
 					return;
 				case "status_changed":
 					if (event.status === "parked") this.#park(runner);
+					else this.#rememberDormant(runner);
+					return;
+				case "system_init":
+					this.#rememberDormant(runner);
 					return;
 				case "session_closed":
+					if (this.#closed) return;
 					this.discard(runner.id);
 					return;
 				default: return;
@@ -911,14 +1127,14 @@ var SessionParkManager = class {
 	sessionFor(executionId) {
 		return this.#owners.get(executionId) ?? this.#settled.get(executionId);
 	}
-	/** The parked session's record, for the read paths (GET, list, attach). */
+	/** The stored session's record, for the read paths (GET, list, attach). */
 	get(id) {
 		return this.#queue(id, () => this.#options.store.get(id));
 	}
-	/** Every parked session's info, to merge into `GET {basePath}/sessions`. */
+	/** Every stored session's info, to merge into `GET {basePath}/sessions`. */
 	async listInfo() {
 		await Promise.all(this.#storeOps.values());
-		return (await this.#options.store.list()).map((record) => record.info);
+		return (await this.#options.store.list()).filter((record) => this.#options.registry.get(record.id) === void 0).map((record) => record.info);
 	}
 	/** The live runner for a session, rehydrating a parked one on demand. Undefined
 	* when the session is neither live nor parked. */
@@ -973,6 +1189,51 @@ var SessionParkManager = class {
 		this.#timers.clear();
 		this.#detachTimers.clear();
 	}
+	/**
+	* Write (or refresh) the dormant record that lets this session survive a
+	* restart. Cheap and repeated on purpose — driven off `system_init` and every
+	* non-park status change — because the alternative is a shutdown hook, and a
+	* shutdown hook is exactly what a `kill -9`, an OOM or a pulled power cable
+	* do not run.
+	*
+	* Four gates, each of which would otherwise produce a record that is worse
+	* than none: the engine must be able to resume at all (a provider session
+	* would come back with an empty transcript — it has `park()` instead), it must
+	* have named its session, the host must remember the config to rebuild from,
+	* and the runner must still be the registry's. That last one is what keeps a
+	* park from being overwritten: `#park` evicts before it saves, so a late event
+	* from an evicted runner finds itself a stranger here and writes nothing.
+	*/
+	async #rememberDormant(runner) {
+		if (this.#closed) return;
+		const info = runner.info();
+		const sdkSessionId = info.sdkSessionId;
+		if (sdkSessionId === void 0) return;
+		if (!(info.capabilities ?? ENGINE_CAPABILITIES[info.engine ?? "claude"]).resume) return;
+		const config = this.#configs.get(runner.id);
+		if (!config) return;
+		if (this.#options.registry.get(runner.id) !== runner) return;
+		const record = {
+			kind: "dormant",
+			id: runner.id,
+			info: {
+				...info,
+				status: "idle"
+			},
+			profile: info.profile,
+			config,
+			sdkSessionId,
+			savedAt: Date.now()
+		};
+		try {
+			await this.#queue(runner.id, () => this.#options.store.save(record));
+		} catch (error) {
+			this.#options.onError?.(error, {
+				sessionId: runner.id,
+				phase: "remember"
+			});
+		}
+	}
 	async #park(runner) {
 		if (this.#closed || !runner.park) return;
 		const id = runner.id;
@@ -992,6 +1253,7 @@ var SessionParkManager = class {
 		};
 		this.#options.registry.evict(id);
 		const record = {
+			kind: "parked",
 			id,
 			info,
 			profile: info.profile,
@@ -1036,7 +1298,7 @@ var SessionParkManager = class {
 		}
 		if (runner.id !== id) {
 			runner.close("error");
-			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' — the engine factory must forward EngineRunnerContext.restore to the runner config`);
+			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' — the engine factory must forward EngineRunnerContext.restore (or, without a snapshot, the session id) to the runner config`);
 			this.#options.onError?.(error, {
 				sessionId: id,
 				phase: "resume"
@@ -1045,9 +1307,9 @@ var SessionParkManager = class {
 		}
 		this.#options.registry.register(runner);
 		this.remember(id, record.config);
-		this.watch(runner, record.snapshot.seq);
+		this.watch(runner, isDormant(record) ? 0 : record.snapshot.seq);
 		this.#options.onResumed?.(id, runner);
-		await this.#queue(id, () => this.#options.store.delete(id));
+		if (!isDormant(record)) await this.#queue(id, () => this.#options.store.delete(id));
 		runner.start();
 		return runner;
 	}
@@ -1097,187 +1359,6 @@ var SessionParkManager = class {
 	}
 };
 //#endregion
-//#region src/session-store.ts
-/** Single-process, no persistence: parks survive a client disconnect, not a restart. */
-var MemorySessionStore = class {
-	#records = /* @__PURE__ */ new Map();
-	save(record) {
-		this.#records.set(record.id, record);
-		return Promise.resolve();
-	}
-	get(id) {
-		return Promise.resolve(this.#records.get(id) ?? null);
-	}
-	list() {
-		return Promise.resolve([...this.#records.values()]);
-	}
-	delete(id) {
-		return Promise.resolve(this.#records.delete(id));
-	}
-};
-/**
-* Config fields that must not be written to durable storage: two are functions
-* (JSON drops them silently), `extraOptions` is SDK `Options` and may hold hooks
-* and callbacks, and `env` is a credential-bearing map — the same rule
-* `profile-store.ts` follows, for the same reason.
-*
-* Dropping them costs a rehydrated session nothing: all four are consumed by the
-* Claude engine alone, and the Claude engine cannot park (the CLI owns its process
-* state — `buildRunner` refuses a `restore` for it). A provider session's
-* credentials are resolved by `createEngineRunner` from the operator's environment
-* on every build, wake included.
-*/
-const EPHEMERAL_CONFIG_KEYS = [
-	"queryFn",
-	"historyFn",
-	"extraOptions",
-	"env"
-];
-/** The record as it may be persisted: same session, config narrowed to what is
-* safe and meaningful to keep (see {@link EPHEMERAL_CONFIG_KEYS}). */
-function toDurableRecord(record) {
-	const config = { ...record.config };
-	for (const key of EPHEMERAL_CONFIG_KEYS) delete config[key];
-	return {
-		...record,
-		config
-	};
-}
-/** Bump when the on-disk shape changes incompatibly; records written by another
-* version are ignored rather than half-read into a broken session. */
-const FORMAT_VERSION = 1;
-/**
-* Durable single-host store: one JSON file per parked session under `dir`, written
-* through a temp file and a rename so a crash mid-write cannot truncate a session.
-* `hydrate()` at `listen()` picks them up, re-indexes their executions, and re-arms
-* the watchdogs, so a restart no longer loses parked work.
-*
-* Know what is on that disk: **the record holds the session's entire transcript** —
-* prompts, model output, and tool I/O — in plaintext. Put it somewhere with the same
-* protection as the SDK's own transcripts (`~/.claude/projects`), not in a directory
-* that gets served, synced, or backed up somewhere looser.
-*
-* Single-process by design, exactly like the bundled queue adapter and profile
-* store: two servers sharing one directory would both hydrate the same records and
-* race to rebuild them. That is what the seam is for.
-*
-* Nothing here reaps: a record leaves only when its session wakes or is deleted.
-* An execution dispatched without a deadline (a `DeferredExecutor` with no
-* `timeoutMs`) has no watchdog to end the wait, so its record — and its transcript
-* — stays until `DELETE /sessions/:id`. Give deferred calls a deadline, or sweep.
-*/
-function createFileSessionStore(options = {}) {
-	const dir = options.dir ?? join(process.cwd(), ".workerdeck", "parked");
-	const fileFor = (id) => join(dir, `${encodeURIComponent(id)}.json`);
-	const read = async (path) => {
-		let raw;
-		try {
-			raw = await readFile(path, "utf8");
-		} catch (error) {
-			if (isMissing(error)) return null;
-			options.onError?.(error, {
-				path,
-				op: "read"
-			});
-			return null;
-		}
-		try {
-			return parseRecord(JSON.parse(raw));
-		} catch (error) {
-			options.onError?.(error, {
-				path,
-				op: "read"
-			});
-			return null;
-		}
-	};
-	return {
-		save: async (record) => {
-			const path = fileFor(record.id);
-			let payload;
-			try {
-				payload = JSON.stringify({
-					version: FORMAT_VERSION,
-					record: toDurableRecord(record)
-				});
-			} catch (error) {
-				options.onError?.(error, {
-					path,
-					op: "save"
-				});
-				throw new Error(`parked session '${record.id}' is not JSON-serializable — a host-injected value reached its config or snapshot: ${String(error)}`);
-			}
-			try {
-				await mkdir(dir, {
-					recursive: true,
-					mode: 448
-				});
-				const temp = `${path}.${process.pid}.tmp`;
-				await writeFile(temp, payload, { mode: 384 });
-				await rename(temp, path);
-			} catch (error) {
-				options.onError?.(error, {
-					path,
-					op: "save"
-				});
-				throw error;
-			}
-		},
-		get: (id) => read(fileFor(id)),
-		list: async () => {
-			let names;
-			try {
-				names = await readdir(dir);
-			} catch (error) {
-				if (isMissing(error)) return [];
-				options.onError?.(error, {
-					path: dir,
-					op: "read"
-				});
-				throw error;
-			}
-			return (await Promise.all(names.filter((name) => name.endsWith(".json")).map(async (name) => {
-				const record = await read(join(dir, name));
-				if (!record) return null;
-				if (`${encodeURIComponent(record.id)}.json` === name) return record;
-				options.onError?.(/* @__PURE__ */ new Error(`parked record '${record.id}' is stored as '${name}' and cannot be read back by id`), {
-					path: join(dir, name),
-					op: "read"
-				});
-				return null;
-			}))).filter((record) => record !== null);
-		},
-		delete: async (id) => {
-			const path = fileFor(id);
-			try {
-				await rm(path);
-				return true;
-			} catch (error) {
-				if (isMissing(error)) return false;
-				options.onError?.(error, {
-					path,
-					op: "delete"
-				});
-				return false;
-			}
-		}
-	};
-}
-const isMissing = (error) => error.code === "ENOENT";
-/** Shape-check a parsed file. A record missing any of these could not be rebuilt,
-* and half-restoring one is worse than skipping it. */
-function parseRecord(value) {
-	if (!value || typeof value !== "object") return null;
-	const envelope = value;
-	if (envelope.version !== FORMAT_VERSION) return null;
-	const record = envelope.record;
-	if (!record || typeof record !== "object") return null;
-	if (typeof record.id !== "string" || typeof record.parkedAt !== "number") return null;
-	if (!record.info || !record.config || !record.snapshot) return null;
-	if (!Array.isArray(record.executions)) return null;
-	return record;
-}
-//#endregion
 //#region src/server.ts
 function json(res, status, body) {
 	const payload = JSON.stringify(body);
@@ -1450,6 +1531,54 @@ function cwdAllowed(cwd, roots) {
 		return resolved === r || resolved.startsWith(r + sep);
 	});
 }
+/** Most tags one session (or one principal) may carry, and the longest a key or
+* value may be. Not a security property — a bound so an opaque map cannot become
+* an unbounded store that every list response then carries. */
+const MAX_SCOPE_KEYS = 16;
+const MAX_SCOPE_LEN = 200;
+/** A `Record<string, string>` or nothing. Duck-typed the same way
+* `allowedProfiles` is: a malformed value is ignored, never half-applied. */
+function readScope(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const entries = Object.entries(value);
+	if (entries.some(([, v]) => typeof v !== "string")) return void 0;
+	return Object.fromEntries(entries);
+}
+/** Validate a caller-supplied scope. Returns an error string, or null when it is
+* well-formed (including when it is absent). */
+function checkScope(value) {
+	if (value === void 0) return null;
+	const scope = readScope(value);
+	if (!scope) return "scope must be an object of string values";
+	const entries = Object.entries(scope);
+	if (entries.length > MAX_SCOPE_KEYS) return `scope may carry at most ${MAX_SCOPE_KEYS} keys`;
+	for (const [key, val] of entries) {
+		if (key.length === 0) return "scope keys must not be empty";
+		if (key.length > MAX_SCOPE_LEN || val.length > MAX_SCOPE_LEN) return `scope keys and values must be at most ${MAX_SCOPE_LEN} characters`;
+	}
+	return null;
+}
+/** Key-order-independent equality — a host runner that rebuilt the record
+* rather than echoing the reference must still pass the build-time check. */
+function sameScope(a, b) {
+	const left = Object.entries(a ?? {}).sort(([x], [y]) => x < y ? -1 : 1);
+	const right = Object.entries(b ?? {}).sort(([x], [y]) => x < y ? -1 : 1);
+	return left.length === right.length && left.every(([key, value], i) => right[i][0] === key && right[i][1] === value);
+}
+/**
+* The default visibility rule, used whenever the host supplies no
+* `authorizeSession`: every key the principal pins must match the session's, and
+* an unset principal scope sees everything.
+*
+* The asymmetry is intended — a session may carry tags the principal says
+* nothing about (an app that tags `{space, user, conversation}` while the
+* principal only pins `{space, user}` still works), but a session missing a key
+* the principal pins is not this caller's.
+*/
+function scopeMatches(principal, session) {
+	if (!principal) return true;
+	return Object.entries(principal).every(([key, value]) => session?.[key] === value);
+}
 function createWorkerServer(options = {}) {
 	if (!options.authenticate && !options.allowUnauthenticated) throw new Error("createWorkerServer: provide `authenticate` or explicitly set `allowUnauthenticated: true`");
 	const basePath = options.basePath ?? "/v1";
@@ -1635,18 +1764,88 @@ function createWorkerServer(options = {}) {
 	const stripInertFields = (req, profile) => {
 		if (!adapterFor(profile?.engine).capabilities.interactiveApprovals) delete req.questionBehavior;
 	};
+	/**
+	* Validate the request's scope and merge the principal's into it.
+	*
+	* A scoped principal's keys are *filled in* when the request omits them and
+	* *refused* when the request disagrees: a caller inside a scope may narrow
+	* itself with extra tags, never claim to be somewhere else. That makes an
+	* embedder's stamping proxy defense in depth rather than the only line — a
+	* request that slipped past it still cannot create a session in another
+	* scope. An unscoped principal (the operator) may write any tags.
+	*/
+	const applyScope = (req, auth) => {
+		const invalid = checkScope(req.scope);
+		if (invalid) return {
+			status: 400,
+			error: invalid
+		};
+		if (!auth.scope) return null;
+		const merged = { ...req.scope };
+		for (const [key, value] of Object.entries(auth.scope)) {
+			const claimed = merged[key];
+			if (claimed !== void 0 && claimed !== value) return {
+				status: 403,
+				error: `scope '${key}' does not match the caller's`
+			};
+			merged[key] = value;
+		}
+		const tooBig = checkScope(merged);
+		if (tooBig) return {
+			status: 400,
+			error: tooBig
+		};
+		req.scope = merged;
+		return null;
+	};
+	/**
+	* `cwd`, required or not depending on the engine's capability record — the
+	* record rather than the engine name, so a host engine that has no host
+	* filesystem gets the same treatment without this file learning its name.
+	*
+	* When one *is* supplied it is validated even for an engine that will not read
+	* it: a path the caller went out of their way to name should not be quietly
+	* exempt from the operator's roots. And note what this check is not — for a
+	* filesystem-less engine `allowedCwdRoots` guards nothing at all. The
+	* boundary there is the capability wiring, not a path prefix.
+	*/
+	const checkCwd = (req, profile) => {
+		if (req.cwd !== void 0 && typeof req.cwd !== "string") return {
+			status: 400,
+			error: "cwd must be a string"
+		};
+		if (!req.cwd) return adapterFor(profile?.engine).capabilities.hostCwd === false ? null : {
+			status: 400,
+			error: "cwd is required"
+		};
+		return cwdAllowed(req.cwd, options.allowedCwdRoots) ? null : {
+			status: 403,
+			error: "cwd is outside the allowed roots"
+		};
+	};
+	/**
+	* Re-stamp the request's scope onto whatever the host's `buildRunnerConfig`
+	* returned. The hook is host code and may rewrite the config wholesale; a
+	* hook that dropped `scope` would silently *widen* a session's visibility,
+	* which is the one direction a bug here must not go. Same posture as the
+	* profile's env pin winning over the hook.
+	*/
+	const withScope = (config, scope) => scope === void 0 ? config : {
+		...config,
+		scope
+	};
 	/** Profile-aware config hook: fill the profile's defaults into unset request fields,
 	* run the host hook, then pin CLAUDE_CONFIG_DIR — the profile wins even when the
 	* host hook set its own env (see `claudeSessionEnv` for the one case the pin is
 	* skipped, and why). Handed to the queue too, so jobs inherit profiles. */
 	const buildRunnerConfig = (req) => {
 		const profile = req.profile !== void 0 ? profileFor(req.profile) : void 0;
-		if (!profile) return hostBuildRunnerConfig(req);
-		const config = hostBuildRunnerConfig({
+		if (!profile) return withScope(hostBuildRunnerConfig(req), req.scope);
+		const config = withScope(hostBuildRunnerConfig({
 			...req,
 			model: req.model ?? profile.defaults?.model ?? profile.provider?.model,
 			permissionMode: req.permissionMode ?? profile.defaults?.permissionMode
-		});
+		}), req.scope);
 		if (engineOf(profile) !== "claude") return config;
 		const base = config.env ?? process.env;
 		const env = claudeSessionEnv(profile, base);
@@ -1661,21 +1860,25 @@ function createWorkerServer(options = {}) {
 	*
 	* `restore` rebuilds a parked session rather than creating a new one — same id,
 	* same log, mid-task. */
-	const buildRunner = async (config, restore) => {
+	const buildRunner = async (config, restore, id) => {
 		const name = config.profile;
 		const profile = name !== void 0 ? profileFor(name) : void 0;
 		if (name !== void 0 && !profile) throw new Error(`unknown profile: ${name}`);
-		if (profile && isProviderProfile(profile)) return options.createEngineRunner({
+		const runner = profile && isProviderProfile(profile) ? await options.createEngineRunner({
 			config,
 			profile,
 			bridge,
-			restore
-		});
-		return adapterFor(profile?.engine).createRunner({
+			restore,
+			id
+		}) : await adapterFor(profile?.engine).createRunner({
 			config,
 			profile,
-			restore
+			restore,
+			id
 		});
+		const reported = runner.info().scope;
+		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} — echo config.scope from info()`);
+		return runner;
 	};
 	const createRunner = async (config) => {
 		const runner = registry.register(await buildRunner(config));
@@ -1755,7 +1958,10 @@ function createWorkerServer(options = {}) {
 		parkDelayMs: options.parking?.parkDelayMs,
 		expiredGraceMs: options.parking?.expiredGraceMs,
 		onError: options.parking?.onError,
-		rebuild: (record) => buildRunner(record.config, record.snapshot),
+		rebuild: (record) => isDormant(record) ? buildRunner(buildRunnerConfig({
+			...record.config,
+			resume: record.sdkSessionId
+		}), void 0, record.id) : buildRunner(record.config, record.snapshot),
 		attachedCount: (sessionId) => bridge.attachedCount(sessionId),
 		onParking: (sessionId, executionId) => queue?.onSessionParking(sessionId, executionId) ?? true,
 		onResumed: (sessionId, runner) => queue?.onSessionResumed(sessionId, runner)
@@ -1865,6 +2071,20 @@ function createWorkerServer(options = {}) {
 			if (verdict.available === true) availabilityWarned.delete(profile.name);
 		}).catch(() => {});
 	};
+	/**
+	* The create-time half of `requireAvailableProfile`. Only a definite `false`
+	* refuses: an unprobed profile ('unknown', or probes turned off entirely) is
+	* not evidence of anything and must not become a closed door.
+	*/
+	const checkAvailable = (profile) => {
+		if (!options.requireAvailableProfile || !profile) return null;
+		const verdict = availability.get(profile.name)?.verdict;
+		if (!verdict || verdict.available !== false) return null;
+		return {
+			status: 503,
+			error: `profile '${profile.name}' is unavailable: ${verdict.reason ?? "no usable credentials"}`
+		};
+	};
 	/** Launch-time sweep, concurrent and fire-and-forget. */
 	const preflightCredentials = () => {
 		for (const profile of allProfiles()) probeProfile(profile);
@@ -1885,12 +2105,79 @@ function createWorkerServer(options = {}) {
 		const principal = await options.authenticate(req);
 		if (principal === null || principal === void 0 || principal === false) return { ok: false };
 		const allowed = principal.allowedProfiles;
+		const scope = readScope(principal.scope);
 		return {
 			ok: true,
+			principal,
+			scope: scope && Object.keys(scope).length > 0 ? scope : void 0,
+			operator: typeof principal.operator === "boolean" ? principal.operator : void 0,
 			allowedProfiles: Array.isArray(allowed) && allowed.every((p) => typeof p === "string") ? allowed : void 0,
 			canManageProfiles: principal.canManageProfiles === true
 		};
 	};
+	/**
+	* May this caller see — and therefore drive — this session? The one rule
+	* behind the list filter, every `/sessions/:id/*` route, the WS attach, the
+	* execution-result door and the job routes: three callers, one predicate, so
+	* they cannot drift into three subtly different answers.
+	*/
+	const canSee = (auth, session) => {
+		if (!options.authorizeSession) return scopeMatches(auth.scope, session.scope);
+		try {
+			return options.authorizeSession(auth.principal, session) === true;
+		} catch {
+			return false;
+		}
+	};
+	/**
+	* The job flavour of {@link canSee}. Once the run has started, the live
+	* session's info is the real subject and the host's rule decides on it. Before
+	* that (queued) and after (finished, session gone) there is no session to
+	* hand over, so the predicate gets a **stub** built from what the job records:
+	* its scope, its profile, its cwd.
+	*
+	* A stub rather than a fallback to the default rule, which is what this did
+	* first and was wrong: a host policy *narrower* than plain tag-match (tags
+	* plus a role, say) would have had queued jobs admitted — and cancelable — by
+	* a peer it rejects. The predicate must be the only rule wherever it exists.
+	* A host reading fields a queued job cannot have (model, status detail) gets
+	* `undefined` and should treat the id and the scope as the load-bearing ones.
+	*/
+	const canSeeJob = (auth, job) => {
+		const live = job.sessionId ? registry.get(job.sessionId)?.info() : void 0;
+		if (live) return canSee(auth, live);
+		if (!options.authorizeSession) return scopeMatches(auth.scope, job.scope);
+		return canSee(auth, {
+			id: job.sessionId ?? job.id,
+			status: job.status === "running" ? "running" : job.status === "parked" ? "parked" : job.status === "queued" ? "starting" : "closed",
+			cwd: job.cwd,
+			profile: job.profile,
+			createdAt: job.createdAt,
+			lastSeq: 0,
+			pendingPermissionCount: 0,
+			scope: job.scope
+		});
+	};
+	/**
+	* Is this caller the operator, rather than someone embedded inside a scope?
+	*
+	* It decides the surfaces that answer about the **gateway** instead of about
+	* one session — the host filesystem, the engine's own on-disk session store,
+	* the queue and its firehose. There is nothing to filter on those and no
+	* honest way to narrow them, so a non-operator is refused outright (404, like
+	* every other miss).
+	*
+	* Two ways to be one, and the second exists because the first is not enough.
+	* A principal carrying `scope` is an end user; a principal carrying neither
+	* `scope` nor a policy is the operator — that is the unscoped default every
+	* existing deployment relies on. But a host may write `authorizeSession` over
+	* its *own* principal shape and never set `scope` at all, and reading that as
+	* "everyone is the operator" is how a locked-down gateway ends up serving its
+	* filesystem to end users. So **declaring a policy withdraws the default**,
+	* and such a host marks its operator principals explicitly with
+	* `operator: true` (`operator: false` forces the other way, at any time).
+	*/
+	const isOperator = (auth) => auth.operator ?? (auth.scope === void 0 && !options.authorizeSession);
 	const parseRoute = (url) => {
 		const pathname = new URL(url, "http://internal").pathname;
 		if (!pathname.startsWith(basePath + "/sessions")) return null;
@@ -2408,13 +2695,17 @@ function createWorkerServer(options = {}) {
 				json(res, 405, { error: "method not allowed" });
 				return;
 			}
+			if (!isOperator(auth)) {
+				json(res, 404, { error: "not found" });
+				return;
+			}
 			json(res, 200, { stats: await queue.stats() });
 			return;
 		}
 		const rest = pathname.slice((basePath + "/jobs").length).replace(/^\//, "");
 		if (rest === "") {
 			if (req.method === "GET") {
-				json(res, 200, { jobs: await queue.list() });
+				json(res, 200, { jobs: (await queue.list()).filter((job) => canSeeJob(auth, job)) });
 				return;
 			}
 			if (req.method === "POST") {
@@ -2423,16 +2714,13 @@ function createWorkerServer(options = {}) {
 					json(res, 400, { error: "session is required" });
 					return;
 				}
-				if (!body.session.cwd || typeof body.session.cwd !== "string") {
-					json(res, 400, { error: "session.cwd is required" });
-					return;
-				}
 				if (!body.session.prompt || typeof body.session.prompt !== "string") {
 					json(res, 400, { error: "session.prompt is required" });
 					return;
 				}
-				if (!cwdAllowed(body.session.cwd, options.allowedCwdRoots)) {
-					json(res, 403, { error: "cwd is outside the allowed roots" });
+				const refusedScope = applyScope(body.session, auth);
+				if (refusedScope) {
+					json(res, refusedScope.status, { error: refusedScope.error });
 					return;
 				}
 				const refused = applyBypassPolicy(body.session);
@@ -2445,6 +2733,16 @@ function createWorkerServer(options = {}) {
 					json(res, resolved.status, { error: resolved.error });
 					return;
 				}
+				const unavailable = checkAvailable(resolved.profile);
+				if (unavailable) {
+					json(res, unavailable.status, { error: unavailable.error });
+					return;
+				}
+				const refusedCwd = checkCwd(body.session, resolved.profile);
+				if (refusedCwd) {
+					json(res, refusedCwd.status, { error: refusedCwd.error });
+					return;
+				}
 				const badRequest = checkPermissionMode(body.session.permissionMode, resolved.profile) ?? checkEngineGrants(body.session, resolved.profile);
 				if (badRequest) {
 					json(res, 400, { error: badRequest });
@@ -2469,11 +2767,16 @@ function createWorkerServer(options = {}) {
 		}
 		if (req.method === "GET") {
 			const job = await queue.get(id);
-			if (job) json(res, 200, { job });
+			if (job && canSeeJob(auth, job)) json(res, 200, { job });
 			else json(res, 404, { error: "job not found" });
 			return;
 		}
 		if (req.method === "DELETE") {
+			const existing = await queue.get(id);
+			if (!existing || !canSeeJob(auth, existing)) {
+				json(res, 404, { error: "job not found" });
+				return;
+			}
 			const job = await queue.cancel(id);
 			if (job) json(res, 200, { job });
 			else json(res, 404, { error: "job not found" });
@@ -2529,10 +2832,11 @@ function createWorkerServer(options = {}) {
 			json(res, 400, { error: "status must be 'ok' or 'failed'" });
 			return;
 		}
-		if (auth.allowedProfiles) {
+		if (auth.allowedProfiles || auth.scope || options.authorizeSession) {
 			const owner = parking.sessionFor(executionId);
-			const profile = owner === void 0 ? void 0 : registry.get(owner)?.info().profile ?? (await parking.get(owner))?.profile;
-			if (owner === void 0 || profile !== void 0 && !auth.allowedProfiles.includes(profile)) {
+			const info = owner === void 0 ? void 0 : registry.get(owner)?.info() ?? (await parking.get(owner))?.info;
+			const profile = info?.profile;
+			if (owner === void 0 || auth.allowedProfiles !== void 0 && profile !== void 0 && !auth.allowedProfiles.includes(profile) || info !== void 0 && !canSee(auth, info)) {
 				json(res, 404, { error: "execution not found" });
 				return;
 			}
@@ -2630,7 +2934,7 @@ function createWorkerServer(options = {}) {
 			if (req.method === "GET") {
 				json(res, 200, {
 					profile: withManagedFlag(profile),
-					config: readProfileConfig(profile)
+					config: isOperator(auth) ? readProfileConfig(profile) : void 0
 				});
 				return;
 			}
@@ -2672,14 +2976,23 @@ function createWorkerServer(options = {}) {
 				json(res, 401, { error: "unauthorized" });
 				return;
 			}
+			if (!isOperator(auth)) {
+				json(res, 404, { error: "not found" });
+				return;
+			}
 			await handleSdkSessions(req, res, auth);
 			return;
 		}
 		if (pathname.startsWith(basePath + "/fs/")) {
-			if (!(await authenticate(req)).ok) {
+			const auth = await authenticate(req);
+			if (!auth.ok) {
 				json(res, 401, { error: "unauthorized" });
 				return;
 			}
+			if (!isOperator(auth)) {
+				json(res, 404, { error: "not found" });
+				return;
+			}
 			await handleHostFiles(req, res, pathname);
 			return;
 		}
@@ -2695,17 +3008,14 @@ function createWorkerServer(options = {}) {
 		}
 		if (!route.id) {
 			if (req.method === "GET") {
-				json(res, 200, { sessions: [...registry.list(), ...await parking.listInfo()] });
+				json(res, 200, { sessions: [...registry.list(), ...await parking.listInfo()].filter((session) => canSee(auth, session)) });
 				return;
 			}
 			if (req.method === "POST") {
 				const body = await readJsonBody(req, maxBodyBytes);
-				if (!body.cwd || typeof body.cwd !== "string") {
-					json(res, 400, { error: "cwd is required" });
-					return;
-				}
-				if (!cwdAllowed(body.cwd, options.allowedCwdRoots)) {
-					json(res, 403, { error: "cwd is outside the allowed roots" });
+				const refusedScope = applyScope(body, auth);
+				if (refusedScope) {
+					json(res, refusedScope.status, { error: refusedScope.error });
 					return;
 				}
 				const refused = applyBypassPolicy(body);
@@ -2718,6 +3028,16 @@ function createWorkerServer(options = {}) {
 					json(res, resolved.status, { error: resolved.error });
 					return;
 				}
+				const unavailable = checkAvailable(resolved.profile);
+				if (unavailable) {
+					json(res, unavailable.status, { error: unavailable.error });
+					return;
+				}
+				const refusedCwd = checkCwd(body, resolved.profile);
+				if (refusedCwd) {
+					json(res, refusedCwd.status, { error: refusedCwd.error });
+					return;
+				}
 				const badRequest = checkPermissionMode(body.permissionMode, resolved.profile) ?? checkEngineGrants(body, resolved.profile);
 				if (badRequest) {
 					json(res, 400, { error: badRequest });
@@ -2739,6 +3059,10 @@ function createWorkerServer(options = {}) {
 			json(res, 404, { error: "session not found" });
 			return;
 		}
+		if (!canSee(auth, runner?.info() ?? parked.info)) {
+			json(res, 404, { error: "session not found" });
+			return;
+		}
 		if (route.attachments) {
 			await handleAttachments(req, res, route.id, runner?.info() ?? parked.info, route.attachmentId);
 			return;
@@ -2756,7 +3080,7 @@ function createWorkerServer(options = {}) {
 				json(res, 405, { error: "method not allowed" });
 				return;
 			}
-			const snapshotFiles = parked?.snapshot.vfs;
+			const snapshotFiles = parked && !isDormant(parked) ? parked.snapshot.vfs : void 0;
 			const vfs = runner?.vfs ?? (snapshotFiles && {
 				list: () => Object.keys(snapshotFiles).sort(),
 				read: (path) => snapshotFiles[path]
@@ -2862,11 +3186,17 @@ function createWorkerServer(options = {}) {
 					socket.destroy();
 					return;
 				}
-				if (!(await authenticate(req)).ok) {
+				const queueAuth = await authenticate(req);
+				if (!queueAuth.ok) {
 					socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
 					socket.destroy();
 					return;
 				}
+				if (!isOperator(queueAuth)) {
+					socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+					socket.destroy();
+					return;
+				}
 				wss.handleUpgrade(req, socket, head, (ws) => {
 					queueSockets.add(ws);
 					ws.on("close", () => queueSockets.delete(ws));
@@ -2883,13 +3213,20 @@ function createWorkerServer(options = {}) {
 				socket.destroy();
 				return;
 			}
-			if (!(await authenticate(req)).ok) {
+			const auth = await authenticate(req);
+			if (!auth.ok) {
 				socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
 				socket.destroy();
 				return;
 			}
+			const known = registry.get(route.id)?.info() ?? (await parking.get(route.id))?.info;
+			if (known && !canSee(auth, known)) {
+				socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+				socket.destroy();
+				return;
+			}
 			const runner = await parking.ensureLive(route.id).catch(() => void 0);
-			if (!runner) {
+			if (!runner || !canSee(auth, runner.info())) {
 				socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
 				socket.destroy();
 				return;
@@ -3023,6 +3360,106 @@ function createWorkerServer(options = {}) {
 	};
 }
 //#endregion
+//#region src/sandboxed-profile.ts
+/**
+* A `provider` profile that grants a session nothing but the sandbox: the
+* QuickJS guest, the in-memory VFS, and the model.
+*
+* This adds no mechanism. `capabilities: []` and `mcpServers: []` already mean
+* what they mean, and `createToolContext` already withholds a tool whose backend
+* the host did not inject. What the helper buys is that the locked-down profile
+* is one call rather than three fields an operator has to get right together —
+* the failure mode being a profile that *looks* sandboxed and still grants
+* `deliver_file` because nobody wrote the empty array.
+*
+* What a session under it can do:
+* - run untrusted JavaScript in the WASM guest, under the interpreter's own
+*   timeout and memory limits (`eval_script`),
+* - read and write the session's in-memory VFS, which is a map and not a
+*   filesystem — no host path is reachable from it.
+*
+* What it cannot do: read or write a host path, spawn a process, reach the
+* network (`web_fetch`/`download`/`web_search` are capabilities, and none is
+* granted), deliver a file, or use an MCP server.
+*
+* Two things this helper does **not** do, because they are not a profile's to
+* decide. It does not authorize anyone — visibility is
+* `CreateSessionRequest.scope` plus the gateway's `authorizeSession`. And it
+* does not make the model's *input* trustworthy: content the loop reads is
+* attacker-influenced by default, and a sandbox bounds what a tool can reach,
+* not what a prompt can talk the model into asking for.
+*
+* @param name Profile name clients name in `CreateSessionRequest.profile`.
+* @param provider Which model to run (credentials stay in the operator's
+*   environment and are resolved by the host's `createEngineRunner` — never
+*   here, and never on the wire).
+*/
+function sandboxedProviderProfile(name, provider, options = {}) {
+	return {
+		name,
+		engine: "provider",
+		provider,
+		description: options.description ?? "Sandboxed: no host filesystem, no shell, no egress",
+		defaults: options.defaults,
+		session: {
+			capabilities: options.capabilities ?? [],
+			mcpServers: options.mcpServers ?? [],
+			instructions: options.instructions
+		}
+	};
+}
+//#endregion
+//#region src/provider-runner.ts
+/**
+* Build a provider-engine runner from the server's `createEngineRunner` context.
+*
+* `createEngineRunner` is a blank sheet: it hands you a context and wants a
+* `Runner`, and four of the five things a correct one must do are invisible in
+* the types — forward `restore`, adopt `id`, seed the VFS only when *not*
+* restoring, and dispose per-session resources. Each is a runtime-only failure
+* (a woken session that starts empty, a refused rebuild, an overwritten
+* filesystem, a connection leaked per session), and each is handled here.
+*
+* ```ts
+* createEngineRunner: (ctx) =>
+*   createProviderRunner(ctx, {
+*     model: (id) => openai(id ?? 'gpt-5.6-luna'),
+*     executor: quickjs,
+*     capabilities: { webFetch: {} },
+*     mcp,
+*     onClose: () => mcp.close(),
+*   }),
+* ```
+*
+* The hook itself stays open for anything this does not cover — this is the
+* 80% case, not a replacement for it.
+*/
+async function createProviderRunner(ctx, options) {
+	const { config, profile, bridge, restore, id } = ctx;
+	const resolveModel = (modelId) => typeof options.model === "function" ? options.model(modelId) : options.model;
+	const executor = options.executor === "browser" ? { dispatch: (call) => bridge.executorFor(call.sessionId).dispatch(call) } : options.executor;
+	return createEngineSession({
+		config: {
+			...config,
+			languageModel: resolveModel(config.model),
+			restore,
+			onClose: options.onClose
+		},
+		id,
+		profile,
+		resolveModel: (_profile, c) => resolveModel(c.model),
+		selectExecutor: () => executor,
+		backend: options.executor === "browser" ? "browser" : "server",
+		capabilities: options.capabilities,
+		tools: options.tools,
+		mcp: options.mcp,
+		mcpTools: options.mcpTools,
+		instructions: options.instructions,
+		executionLimits: options.executionLimits,
+		seedVfs: options.seedVfs
+	});
+}
+//#endregion
 //#region src/profile-store.ts
 /** Non-durable store for tests and ephemeral deployments. */
 function createMemoryProfileStore(seed = []) {
@@ -3071,6 +3508,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, sandboxedProviderProfile, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map