@workerdeck/server 0.23.0 → 1.0.0

package/build/index.mjs

@@ -2,13 +2,29 @@ import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, createEngineSession, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, imagePartRef, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, imagePartRef, sessionState, supportsPermissionMode } from "@workerdeck/protocol";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { 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";
 //#region src/lib/http.ts
+const CONTENT_TYPES = {
+	json: "application/json; charset=utf-8",
+	md: "text/markdown; charset=utf-8",
+	html: "text/html; charset=utf-8",
+	csv: "text/csv; charset=utf-8",
+	xml: "application/xml; charset=utf-8",
+	svg: "image/svg+xml; charset=utf-8"
+};
+function untrustedDownloadHeaders(filename, contentType, byteLength) {
+	return {
+		"content-type": contentType,
+		"content-length": byteLength,
+		"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
+		"x-content-type-options": "nosniff"
+	};
+}
 function json(res, status, body) {
 	const payload = JSON.stringify(body);
 	res.writeHead(status, {
@@ -18,18 +34,10 @@ function json(res, status, body) {
 	res.end(payload);
 }
 async function readJsonBody(req, maxBytes) {
-	const chunks = [];
-	let size = 0;
-	for await (const chunk of req) {
-		size += chunk.length;
-		if (size > maxBytes) throw new Error("request body too large");
-		chunks.push(chunk);
-	}
-	if (size === 0) return {};
-	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	const body = await readRawBody(req, maxBytes);
+	if (body.length === 0) return {};
+	return JSON.parse(body.toString("utf8"));
 }
-/** Body as bytes, refusing anything over `maxBytes`. Attachments are the one
-* thing this server takes that isn't JSON. */
 async function readRawBody(req, maxBytes) {
 	const chunks = [];
 	let size = 0;
@@ -40,27 +48,9 @@ async function readRawBody(req, maxBytes) {
 	}
 	return Buffer.concat(chunks);
 }
-/** Conservative content types for VFS downloads: text formats the agent actually
-* produces; anything unrecognized ships as plain text (the VFS is string-backed). */
-const CONTENT_TYPES = {
-	json: "application/json; charset=utf-8",
-	md: "text/markdown; charset=utf-8",
-	html: "text/html; charset=utf-8",
-	csv: "text/csv; charset=utf-8",
-	xml: "application/xml; charset=utf-8",
-	svg: "image/svg+xml; charset=utf-8"
-};
-/** sha256 hex — the currency of the conditional-write protocol on `/fs/write`. */
 function hashBytes(bytes) {
 	return createHash("sha256").update(bytes).digest("hex");
 }
-/**
-* The file's text, or null if it isn't text. Decoding never fails in Node — invalid
-* bytes become U+FFFD — so the only honest test is a round trip: if re-encoding the
-* decoded string reproduces the original bytes, nothing was lost and the client can
-* safely edit and send it back. Anything else ships base64, which an editor can
-* refuse to open rather than silently corrupt on save.
-*/
 function asUtf8(bytes) {
 	const text = bytes.toString("utf8");
 	return Buffer.from(text, "utf8").equals(bytes) ? text : null;
@@ -70,26 +60,15 @@ function contentTypeFor(filename) {
 }
 //#endregion
 //#region src/lib/profile-env.ts
-/**
-* Pure profile/environment/path rules: which engine a profile runs, where the
-* CLI's config resolution lands, the CLAUDE_CONFIG_DIR pin, and the cwd-roots
-* policy. No state, no I/O beyond reads of the filesystem the rules are about.
-*/
-/** A profile runs the model-agnostic engine rather than Claude Code. `engine` is
-* optional so profiles written before provider support keep meaning 'claude'. */
 function isProviderProfile(profile) {
 	return profile.engine === "provider";
 }
-/** The engine a profile runs, absent meaning 'claude' (pre-provider profiles). */
 function engineOf(profile) {
 	return profile?.engine ?? "claude";
 }
-/** Where the CLI's own resolution lands for a given environment: an explicit
-* CLAUDE_CONFIG_DIR, else ~/.claude. */
 function cliConfigDir(env) {
 	return env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
 }
-/** Auto-created profile when none are declared: the operator's own config dir. */
 function detectDefaultProfiles() {
 	const dir = cliConfigDir(process.env);
 	return existsSync(dir) ? [{
@@ -97,9 +76,6 @@ function detectDefaultProfiles() {
 		configDir: dir
 	}] : [];
 }
-/** Compare config dirs by what they name on disk: declared paths arrive with
-* trailing slashes or symlinked prefixes (`/var` vs `/private/var` on macOS); a
-* path that doesn't exist falls back to plain normalization. */
 function canonicalDir(path) {
 	try {
 		return realpathSync(path);
@@ -107,18 +83,6 @@ function canonicalDir(path) {
 		return resolve(path);
 	}
 }
-/**
-* The env a Claude session under `profile` is spawned with, starting from
-* `base` (the host hook's env, else the server's own). The pin is skipped when
-* `base` would already land the CLI in the profile's dir, and that skip is
-* load-bearing, not an optimisation: CLAUDE_CONFIG_DIR *set at all* switches
-* the CLI's credential source to `<dir>/.credentials.json` — on macOS a
-* claude.ai login lives in the login Keychain, consulted only while the
-* variable is UNSET, so pinning even the CLI's own default `~/.claude` turns a
-* working login into "Not logged in". When `base` names a *different* dir than
-* the profile, the pin stands: the profile must win over hook- or operator-set
-* env, or sessions under two profiles quietly collapse into one identity.
-*/
 function claudeSessionEnv(profile, base) {
 	return canonicalDir(profile.configDir) === canonicalDir(cliConfigDir(base)) ? base : {
 		...base,
@@ -133,14 +97,6 @@ function cwdAllowed(cwd, roots) {
 		return resolved === r || resolved.startsWith(r + sep);
 	});
 }
-/**
-* Curated, view-only snapshot of a profile's config dir for GET /profiles/:name.
-* Best-effort: a missing or unparseable settings.json just omits the settings block.
-* Env var VALUES are never read into the response — names only.
-*
-* Provider profiles have no config dir, so the snapshot is empty for them: their
-* configuration is the `provider` block already on ProfileInfo.
-*/
 function readProfileConfig(profile) {
 	const dir = profile.configDir;
 	if (!dir) return {
@@ -286,7 +242,7 @@ async function handleExecutionResult(ctx, req, res, pathname, auth) {
 		const owner = parking.sessionFor(executionId);
 		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 && !authSvc.canSee(auth, info)) {
+		if (owner === void 0 || info === void 0 || auth.allowedProfiles !== void 0 && profile !== void 0 && !auth.allowedProfiles.includes(profile) || !authSvc.canSee(auth, info)) {
 			json(res, 404, { error: "execution not found" });
 			return;
 		}
@@ -300,15 +256,8 @@ async function handleExecutionResult(ctx, req, res, pathname, auth) {
 }
 //#endregion
 //#region src/services/host-files.ts
-/**
-* Built once at startup from operator config. Roots are canonicalized here
-* because resolution produces realpath'd targets: a root that is itself a
-* symlink (`/tmp` -> `/private/tmp` on macOS) would otherwise contain nothing.
-* A misdeclared root throws rather than silently guarding the wrong tree —
-* same stance as profile config dirs in server.ts. An empty list is legal and
-* refuses everything; "no roots means allow all" is `cwdAllowed`'s contract,
-* never this module's.
-*/
+const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = constants.O_NONBLOCK ?? 0;
 function createHostFileRoots(roots) {
 	return { roots: roots.map((configured) => {
 		if (invalidRequest(configured)) throw new Error(`createHostFileRoots: root must be an absolute path: ${JSON.stringify(configured)}`);
@@ -332,24 +281,12 @@ function refuse(status, error) {
 		error
 	};
 }
-/** The uniform filesystem refusal — see the disclosure policy in the header.
-* The string is deliberately constant: a distinct message is as much an oracle
-* as a distinct status. */
 function notFound() {
 	return refuse(404, "not found");
 }
-/** NUL is rejected before any fs call — Node throws a TypeError on NUL paths,
-* and that must surface as a refusal, not a 500. Relative paths are refused
-* outright rather than resolved against a cwd this API never promised. */
 function invalidRequest(requested) {
 	return requested.length === 0 || requested.includes("\0") || !isAbsolute(requested);
 }
-/** Both sides are realpath output, so this is a pure lexical question — but a
-* bare prefix check gets the boundary wrong (`/x/app` would swallow
-* `/x/application`). `relative` answers it exactly: inside iff the walk from
-* root to candidate is empty or never has to leave through `..`. Exported for
-* the project-icon resolver (`project-info.ts`), which makes the same claim
-* against a project root; both callers must hand it realpath output only. */
 function contained(rootCanonical, candidate) {
 	const rel = relative(rootCanonical, candidate);
 	return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
@@ -357,14 +294,6 @@ function contained(rootCanonical, candidate) {
 function rootContaining(roots, canonical) {
 	return roots.roots.find((root) => contained(root.canonical, canonical));
 }
-/**
-* For read/list: the target must exist. realpath is handed the request whole —
-* no lexical `..` collapsing first, because `root/link/..` is lexically `root`
-* but physically the link target's parent, and only the physical answer is the
-* true one. Symlinks that canonicalize *inside* a root are followed and served:
-* containment is a property of the canonical target, not of the route to it —
-* the operator granted the whole subtree, so nothing new becomes reachable.
-*/
 function resolveExisting(roots, requested) {
 	if (invalidRequest(requested)) return refuse(403, "invalid path");
 	let canonical;
@@ -395,19 +324,6 @@ function resolveExisting(roots, requested) {
 	};
 	return refuse(403, "not a regular file or directory");
 }
-/**
-* For write: the target may not exist, so realpath cannot be asked directly.
-* An existing target reuses read semantics — writing *through* a symlink that
-* canonicalizes inside a root is allowed (`root/link -> root/real.txt` edits
-* real.txt), same reasoning as {@link resolveExisting}. A missing target
-* canonicalizes its immediate parent and re-checks: only the final component
-* may be new, and anything already sitting there — in practice a dangling
-* symlink — is refused, because open(2) with O_CREAT follows it and would
-* create the file wherever it points. That refusal is `not found`, not 403: a
-* link to an existing outside file already answers 404 via the exists branch,
-* so a distinct status for the dangling case would hand back exactly the
-* existence bit the uniform 404 exists to withhold.
-*/
 function resolveForWrite(roots, requested) {
 	if (invalidRequest(requested)) return refuse(403, "invalid path");
 	try {
@@ -454,28 +370,12 @@ function resolveForWrite(roots, requested) {
 	}
 	return notFound();
 }
-/** lstat semantics on purpose: a listing shows a symlink AS a symlink — the
-* server never follows one while rendering a directory. Following happens only
-* when the entry is itself requested, through {@link resolveExisting}, which
-* refuses it if it escapes. `readdir(withFileTypes)` already answers without
-* following, so this is classification, not I/O. */
 function entryKind(entry) {
 	if (entry.isSymbolicLink()) return "symlink";
 	if (entry.isFile()) return "file";
 	if (entry.isDirectory()) return "dir";
 	return "other";
 }
-const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
-const O_NONBLOCK = constants.O_NONBLOCK ?? 0;
-/**
-* The open half of the resolve→open discipline; pass `ResolveOutcome.path`,
-* never the requested string. O_NOFOLLOW turns a final component swapped for a
-* symlink inside the race window into ELOOP instead of a follow; O_NONBLOCK
-* makes a swapped-in fifo open instantly instead of parking the request until a
-* writer appears (it is inert for regular files); the fstat gate refuses
-* anything that is not a plain file before a byte is read — `/dev/zero` would
-* otherwise be an unbounded read.
-*/
 function readContained(path) {
 	let fd;
 	try {
@@ -495,13 +395,6 @@ function readContained(path) {
 		closeSync(fd);
 	}
 }
-/**
-* O_CREAT|O_NOFOLLOW refuses (ELOOP) a symlink planted at the final component
-* after resolve — the exact swap that would land the write at the link's
-* target. Truncation happens via ftruncate only AFTER the fd is proven to be a
-* regular file, so a swapped-in device or fifo is never truncated or written;
-* O_NONBLOCK turns the reader-less-fifo open from a hang into ENXIO.
-*/
 function writeContained(path, data) {
 	let fd;
 	try {
@@ -522,23 +415,6 @@ function writeContained(path, data) {
 }
 //#endregion
 //#region src/services/host-file-search.ts
-/**
-* The recursive half of the host-file routes: what `@file` autocomplete needs and
-* `/fs/list` deliberately isn't. Listing answers "what is in this directory"; this
-* answers "which file in this tree did you mean", which is a different query and a
-* different cost model.
-*
-* Kept out of `host-files.ts` on purpose. That module is the audited containment
-* core; this one walks *inside* an already-resolved, already-contained directory
-* and never resolves a path of its own. Its one security-relevant rule is that it
-* does not follow symlinks — see the walk below.
-*/
-/**
-* Directories a source tree keeps that nobody types `@` looking for, and that are
-* usually most of the entries on disk. Skipping them is what makes the walk cheap
-* enough to run per keystroke; the operator can replace the list via
-* `hostFiles.ignore`.
-*/
 const DEFAULT_IGNORED_DIRS = [
 	".git",
 	".hg",
@@ -562,18 +438,6 @@ const DEFAULT_IGNORED_DIRS = [
 	"DerivedData",
 	".build"
 ];
-/**
-* Breadth-first so shallow files rank first before scoring even runs — for a bare
-* `@` that ordering *is* the ranking, and for a query it breaks ties the way a
-* person expects (`src/index.ts` over `src/a/b/c/index.ts`).
-*
-* Symlinks are skipped outright, as files and as directories. As directories it is
-* the difference between a bounded walk and an unbounded one (a cycle, or a link
-* to `/`); as files it keeps this function's output within the tree it was handed,
-* so nothing it offers can be a path that `resolveExisting` would later refuse.
-* A tree that genuinely lives behind symlinks is not autocompletable — an accepted
-* cost for not having to re-derive containment here.
-*/
 function searchFiles(base, options = {}) {
 	const limit = options.limit ?? 50;
 	const maxScanned = options.maxScanned ?? 2e4;
@@ -628,14 +492,6 @@ function searchFiles(base, options = {}) {
 		truncated: !exhausted || found.length > limit
 	};
 }
-/**
-* Subsequence matching, like every `@`-picker worth using: `seslist` finds
-* `SessionListView.swift`. Returns null for no match.
-*
-* Scored so the two things people actually mean win — a hit in the filename beats
-* one buried in the directory path, and characters typed consecutively beat the
-* same characters scattered — rather than trying to be a ranking engine.
-*/
 function scoreMatch(relativePath, name, needle) {
 	if (needle === "") return 0;
 	const inName = subsequenceScore(name.toLowerCase(), needle);
@@ -658,15 +514,9 @@ function subsequenceScore(haystack, needle) {
 }
 //#endregion
 //#region src/routes/host-files.ts
-/**
-* `{basePath}/fs/*` — the operator's real tree. Authorized by the auth key alone
-* and deliberately outside the agent permission flow: the caller is the operator.
-*
-* Every path in here goes through `services/host-files.ts` first, which
-* canonicalizes and *then* re-checks containment. The naive prefix compare
-* `cwdAllowed` does would be wrong at this door — the agent writes into these
-* trees, and a symlink it created is a path the operator never typed.
-*/
+function kindRank(type) {
+	return type === "dir" ? 0 : 1;
+}
 async function handleHostFiles(ctx, req, res, pathname) {
 	const { basePath, hostFiles, hostFilesWritable, maxHostFileBytes, maxHostDirEntries } = ctx;
 	if (!hostFiles) {
@@ -766,10 +616,7 @@ async function handleHostFiles(ctx, req, res, pathname) {
 					modifiedAt
 				};
 			});
-			entries.sort((a, b) => {
-				const rank = (t) => t === "dir" ? 0 : 1;
-				return rank(a.type) - rank(b.type) || a.name.localeCompare(b.name);
-			});
+			entries.sort((a, b) => kindRank(a.type) - kindRank(b.type) || a.name.localeCompare(b.name));
 			json(res, 200, {
 				path: resolved.path,
 				entries,
@@ -883,9 +730,44 @@ async function handleHostFiles(ctx, req, res, pathname) {
 	json(res, 404, { error: "not found" });
 }
 //#endregion
+//#region src/routes/create-vet.ts
+/**
+* The one create-validation ladder, run by both create doors — `POST /sessions` and the
+* `session` block of `POST /jobs`. The scope design claims the two are indistinguishable, so
+* the order and the refusals have to come from a single place rather than two copies that can
+* drift. Mutates `req`: strips inert fields and pins the resolved profile name.
+*/
+function vetCreateRequest(ctx, req, auth) {
+	const { availability, factory } = ctx;
+	const refusedScope = factory.applyScope(req, auth);
+	if (refusedScope) return refusedScope;
+	const refused = factory.applyBypassPolicy(req);
+	if (refused) return {
+		status: 403,
+		error: refused
+	};
+	const resolved = factory.resolveProfile(req.profile, auth.allowedProfiles);
+	if (!resolved.ok) return {
+		status: resolved.status,
+		error: resolved.error
+	};
+	const unavailable = availability.checkAvailable(resolved.profile);
+	if (unavailable) return unavailable;
+	const refusedCwd = factory.checkCwd(req, resolved.profile);
+	if (refusedCwd) return refusedCwd;
+	const badRequest = factory.checkPermissionMode(req.permissionMode, resolved.profile) ?? factory.checkEngineGrants(req, resolved.profile);
+	if (badRequest) return {
+		status: 400,
+		error: badRequest
+	};
+	factory.stripInertFields(req, resolved.profile);
+	req.profile = resolved.profile?.name;
+	return null;
+}
+//#endregion
 //#region src/routes/jobs.ts
 async function handleJobs(ctx, req, res, pathname, auth) {
-	const { auth: authSvc, availability, basePath, factory, queue } = ctx;
+	const { auth: authSvc, basePath, queue } = ctx;
 	if (!queue) {
 		json(res, 404, { error: "job queue not configured" });
 		return;
@@ -918,38 +800,11 @@ async function handleJobs(ctx, req, res, pathname, auth) {
 				json(res, 400, { error: "session.prompt is required" });
 				return;
 			}
-			const refusedScope = factory.applyScope(body.session, auth);
-			if (refusedScope) {
-				json(res, refusedScope.status, { error: refusedScope.error });
-				return;
-			}
-			const refused = factory.applyBypassPolicy(body.session);
-			if (refused) {
-				json(res, 403, { error: refused });
-				return;
-			}
-			const resolved = factory.resolveProfile(body.session.profile, auth.allowedProfiles);
-			if (!resolved.ok) {
-				json(res, resolved.status, { error: resolved.error });
-				return;
-			}
-			const unavailable = availability.checkAvailable(resolved.profile);
-			if (unavailable) {
-				json(res, unavailable.status, { error: unavailable.error });
+			const refusal = vetCreateRequest(ctx, body.session, auth);
+			if (refusal) {
+				json(res, refusal.status, { error: refusal.error });
 				return;
 			}
-			const refusedCwd = factory.checkCwd(body.session, resolved.profile);
-			if (refusedCwd) {
-				json(res, refusedCwd.status, { error: refusedCwd.error });
-				return;
-			}
-			const badRequest = factory.checkPermissionMode(body.session.permissionMode, resolved.profile) ?? factory.checkEngineGrants(body.session, resolved.profile);
-			if (badRequest) {
-				json(res, 400, { error: badRequest });
-				return;
-			}
-			factory.stripInertFields(body.session, resolved.profile);
-			body.session.profile = resolved.profile?.name;
 			try {
 				json(res, 201, { job: await queue.submit(body) });
 			} catch (error) {
@@ -1066,6 +921,10 @@ async function handleProfiles(ctx, req, res, pathname, auth) {
 }
 //#endregion
 //#region src/routes/sdk-sessions.ts
+function withinRoots(sessions, roots, limit, offset = 0) {
+	const allowed = sessions.filter((s) => s.cwd !== void 0 && cwdAllowed(s.cwd, roots)).sort((a, b) => b.lastModified - a.lastModified);
+	return limit === void 0 ? allowed.slice(offset) : allowed.slice(offset, offset + limit);
+}
 async function handleSdkSessions(ctx, req, res, auth) {
 	const { adapterFor, factory, profiles } = ctx;
 	if (req.method !== "GET") {
@@ -1122,18 +981,14 @@ async function handleSdkSessions(ctx, req, res, auth) {
 		json(res, 500, { error: error instanceof Error ? error.message : "failed to list sessions" });
 	}
 }
-/** The sessions whose `cwd` is inside the roots, newest first, then paged. A
-* summary with no `cwd` cannot be shown to be inside them, so it is dropped. */
-function withinRoots(sessions, roots, limit, offset = 0) {
-	const allowed = sessions.filter((s) => s.cwd !== void 0 && cwdAllowed(s.cwd, roots)).sort((a, b) => b.lastModified - a.lastModified);
-	return limit === void 0 ? allowed.slice(offset) : allowed.slice(offset, offset + limit);
-}
 //#endregion
 //#region src/services/session-store.ts
-/** A live record is refreshed in place on wake; a park is consumed by it. */
-const isLiveRecord = (record) => record.kind === "live";
-const isDormant = (record) => record.kind === "dormant";
-/** Single-process, no persistence: parks survive a client disconnect, not a restart. */
+function isLiveRecord(record) {
+	return record.kind === "live";
+}
+function isDormant(record) {
+	return record.kind === "dormant";
+}
 var MemorySessionStore = class {
 	#records = /* @__PURE__ */ new Map();
 	save(record) {
@@ -1150,31 +1005,12 @@ var MemorySessionStore = class {
 		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];
@@ -1183,29 +1019,7 @@ function toDurableRecord(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`);
@@ -1245,7 +1059,7 @@ function createFileSessionStore(options = {}) {
 					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)}`);
+				throw new Error(`parked session '${record.id}' is not JSON-serializable — a host-injected value reached its config or snapshot: ${String(error)}`, { cause: error });
 			}
 			try {
 				await mkdir(dir, {
@@ -1303,9 +1117,9 @@ function createFileSessionStore(options = {}) {
 		}
 	};
 }
-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 isMissing(error) {
+	return error.code === "ENOENT";
+}
 function parseRecord(value) {
 	if (!value || typeof value !== "object") return null;
 	const envelope = value;
@@ -1363,12 +1177,7 @@ async function handleAttachments(ctx, req, res, sessionId, session, attachmentId
 			return;
 		}
 		const bytes = Buffer.from(found.data, "base64");
-		res.writeHead(200, {
-			"content-type": found.mediaType,
-			"content-length": bytes.length,
-			"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(found.name)}`,
-			"x-content-type-options": "nosniff"
-		});
+		res.writeHead(200, untrustedDownloadHeaders(found.name, found.mediaType, bytes.length));
 		res.end(bytes);
 		return;
 	}
@@ -1414,21 +1223,6 @@ async function handleMcp(ctx, req, res, runner, serverName) {
 }
 //#endregion
 //#region src/routes/produced-files.ts
-/**
-* `{basePath}/sessions/:id/produced[/:fileId]` — files this session's ENGINE
-* wrote on the host (codex's generated images), listed and served.
-*
-* The one route here with no root allowlist and no byte cap, and the comment
-* on `ProducedFileStore` is the argument for why that is right rather
-* than lax: the allowlist is the exact set of paths this session's own runner
-* announced producing. It is emphatically NOT a hole in `/fs/*` — a path the
-* *agent* named is not a produced file and never enters this store.
-*
-* Everything else matches the attachment download: `nosniff` and an attachment
-* disposition, because these bytes are model-authored and must not render as a
-* document on the gateway's origin. (`<img src>` is unaffected — disposition
-* does not apply to subresources, which is the whole point.)
-*/
 async function handleProducedFiles(ctx, req, res, sessionId, fileId) {
 	const { producedFiles } = ctx;
 	if (req.method !== "GET") {
@@ -1461,12 +1255,7 @@ async function handleProducedFiles(ctx, req, res, sessionId, fileId) {
 		return;
 	}
 	const filename = basename(found.path) || "file";
-	res.writeHead(200, {
-		"content-type": found.mediaType ?? contentTypeFor(filename),
-		"content-length": stat.size,
-		"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
-		"x-content-type-options": "nosniff"
-	});
+	res.writeHead(200, untrustedDownloadHeaders(filename, found.mediaType ?? contentTypeFor(filename), stat.size));
 	await new Promise((done) => {
 		const stream = createReadStream(found.path);
 		stream.on("error", () => {
@@ -1479,59 +1268,11 @@ async function handleProducedFiles(ctx, req, res, sessionId, fileId) {
 }
 //#endregion
 //#region src/services/project-info.ts
-/**
-* Project identity discovery: the `.workerdeck.json` ancestor walk behind
-* `SessionInfo.project`, and the read side of `GET /sessions/:id/project/icon`.
-*
-* The gateway resolves this — not each client — because the file lives on the
-* gateway's filesystem, which a phone or a remote browser cannot see. It is
-* stamped onto `SessionInfo` at **serve time** (`withProject`), never persisted:
-* a copy captured into a parking record would replay a stale name forever,
-* where a serve-time read picks up an edited file on every session at once
-* within the TTL. That is the profile tracker's 0%-after-reset placement
-* argument, applied to a filesystem fact instead of a clock.
-*
-* Every failure degrades to "no project" and never to an error: a session must
-* not fail, or even warn, because of a display declaration. A malformed,
-* oversized, or symlinked `.workerdeck.json` is *skipped and the walk
-* continues* — a broken file in `packages/ui` must not shadow the repo root's
-* valid one — and inside a valid file each field degrades on its own (junk
-* name → the root's basename, junk icon → no icon).
-*
-* The icon is the security surface, because its path comes out of a config
-* file the *agent* can write (the session cwd is the agent's working tree).
-* The rules are `host-files.ts`'s, not `cwdAllowed`'s (docs/GOTCHAS.md §Host
-* filesystem): the declared path is resolved against the project root and then
-* realpath'd **whole**, containment is decided on the canonical result only
-* (so `"icon": "../../../../etc/key.png"` and a planted `icon.png → ~/.ssh/…`
-* symlink both fail the same check), the open goes through `readContained`
-* (O_NOFOLLOW, fstat-before-io), and the media type comes from the *declared*
-* extension — png and svg only, by decision. A refused icon is
-* indistinguishable on the wire and on the route from a never-declared one:
-* `icon` absent, the route 404s. The one disclosure this feature accepts is
-* inherent to it: the walk reads ancestors of a vetted cwd, so a project file
-* an operator placed *above* their roots (`~/.workerdeck.json`) applies to
-* everything under it — nearest-wins from the cwd, exactly git's own
-* discovery, and the file is a display declaration by definition.
-*
-* Cache: per exact cwd string, TTL'd, with negative results cached at the same
-* price — `GET /sessions` polls at 1.2s while anything is working and the hit
-* path must be a Map lookup, never a walk. Keyed by cwd rather than by root
-* because the root is not known until the walk has run. Bounded by sweeping
-* expired entries once the map outgrows any plausible live session count.
-*/
 const PROJECT_FILE = ".workerdeck.json";
-/** A config file, not a document — anything bigger is skipped as malformed. */
 const MAX_PROJECT_FILE_BYTES = 64 * 1024;
-/** Display name clip — a list row's width, not a document's. */
 const MAX_NAME_CHARS = 80;
-/** lucide's naming: lowercase kebab-case. Shape-only — the gateway has no icon
-* catalog and must not grow one; an unknown-but-well-formed name ships and the
-* client falls back (a stale row, never withheld state). */
 const GLYPH_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const DEFAULT_TTL_MS = 3e4;
-/** Sweep threshold: above this many cached cwds, expired entries are evicted
-* on the next resolve so dead sessions' keys do not accumulate forever. */
 const SWEEP_ABOVE = 256;
 var ProjectInfoService = class {
 	#ttlMs;
@@ -1539,11 +1280,6 @@ var ProjectInfoService = class {
 	constructor(options = {}) {
 		this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
 	}
-	/**
-	* The serve-time decoration: `info` with `project` stamped on, or the same
-	* object untouched when there is nothing to add — the common case on a list
-	* poll, so no allocation for it (replaySlice's same-object rule).
-	*/
 	withProject(info) {
 		if (!info.cwd) return info;
 		const project = this.#resolve(info.cwd).project;
@@ -1552,11 +1288,8 @@ var ProjectInfoService = class {
 			project
 		} : info;
 	}
-	/** The icon route's read side: the canonical, contained icon file for this
-	* session's cwd — resolved from the gateway's own cache, never from anything
-	* the client named. Undefined = no project, no icon, or an icon refused. */
 	iconFor(cwd) {
-		if (!cwd) return void 0;
+		if (!cwd) return;
 		return this.#resolve(cwd).icon;
 	}
 	#resolve(cwd) {
@@ -1574,10 +1307,6 @@ var ProjectInfoService = class {
 		return fresh;
 	}
 };
-/** The ancestor walk: realpath the cwd (a lexical walk over `/tmp/x` would
-* miss the file at `/private/tmp/x`, and canonicalizing here is what makes
-* `root` — the grouping key — spell identically for every cwd inside one
-* project), then nearest `.workerdeck.json` wins, to the filesystem root. */
 function discover(cwd) {
 	if (!isAbsolute(cwd) || cwd.includes("\0")) return {};
 	let dir;
@@ -1594,8 +1323,6 @@ function discover(cwd) {
 		dir = parent;
 	}
 }
-/** One directory's verdict: a project record, or undefined to keep walking —
-* which is the same answer for "absent" and for every malformed shape. */
 function tryLoad(file, root) {
 	let stat;
 	try {
@@ -1603,16 +1330,16 @@ function tryLoad(file, root) {
 	} catch {
 		return;
 	}
-	if (!stat.isFile() || stat.size > MAX_PROJECT_FILE_BYTES) return void 0;
+	if (!stat.isFile() || stat.size > MAX_PROJECT_FILE_BYTES) return;
 	const read = readContained(file);
-	if (!read.ok) return void 0;
+	if (!read.ok) return;
 	let parsed;
 	try {
 		parsed = JSON.parse(read.data.toString("utf8"));
 	} catch {
 		return;
 	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return;
 	const raw = parsed;
 	const name = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim().slice(0, MAX_NAME_CHARS) : basename(root);
 	const icon = classifyIcon(raw.icon, root);
@@ -1625,41 +1352,36 @@ function tryLoad(file, root) {
 		...icon?.resolved ? { icon: icon.resolved } : {}
 	};
 }
-/**
-* The one-string icon rule (documented on protocol's `ProjectInfo`): ends in
-* `.png`/`.svg` → repo-relative image path, else lucide-shaped glyph name,
-* else ignored. Total and collision-free — a glyph name contains no dot.
-*/
 function classifyIcon(value, root) {
-	if (typeof value !== "string") return void 0;
+	if (typeof value !== "string") return;
 	const declared = value.trim();
-	if (!declared || declared.includes("\0") || declared.length > 512) return void 0;
+	if (!declared || declared.includes("\0") || declared.length > 512) return;
 	const lower = declared.toLowerCase();
 	const mediaType = lower.endsWith(".png") ? "image/png" : lower.endsWith(".svg") ? "image/svg+xml" : void 0;
 	if (!mediaType) {
-		if (!GLYPH_RE.test(declared) || declared.length > 64) return void 0;
+		if (!GLYPH_RE.test(declared) || declared.length > 64) return;
 		return { wire: {
 			type: "glyph",
 			name: declared
 		} };
 	}
-	if (isAbsolute(declared) || declared.includes("\\")) return void 0;
+	if (isAbsolute(declared) || declared.includes("\\")) return;
 	let canonical;
 	try {
 		canonical = realpathSync(resolve(root, declared));
 	} catch {
 		return;
 	}
-	if (!contained(root, canonical)) return void 0;
+	if (!contained(root, canonical)) return;
 	let stat;
 	try {
 		stat = lstatSync(canonical);
 	} catch {
 		return;
 	}
-	if (!stat.isFile() || stat.size === 0 || stat.size > 524288) return void 0;
+	if (!stat.isFile() || stat.size === 0 || stat.size > 524288) return;
 	const read = readContained(canonical);
-	if (!read.ok || read.data.length > 524288) return void 0;
+	if (!read.ok || read.data.length > 524288) return;
 	const hash = createHash("sha256").update(read.data).digest("hex");
 	return {
 		wire: {
@@ -1763,7 +1485,7 @@ function handleToolResult(req, res, lookup, seq) {
 //#endregion
 //#region src/routes/sessions.ts
 async function handleSessions(ctx, req, res, route, auth) {
-	const { attachmentStore, auth: authSvc, availability, bridge, factory, parking, producedFiles, projects, registry } = ctx;
+	const { attachmentStore, auth: authSvc, bridge, factory, parking, producedFiles, projects, registry } = ctx;
 	if (!route.id) {
 		if (req.method === "GET") {
 			json(res, 200, { sessions: [...registry.list(), ...await parking.listInfo()].filter((session) => authSvc.canSee(auth, session)).map((session) => projects.withProject(session)) });
@@ -1771,38 +1493,11 @@ async function handleSessions(ctx, req, res, route, auth) {
 		}
 		if (req.method === "POST") {
 			const body = await readJsonBody(req, ctx.maxBodyBytes);
-			const refusedScope = factory.applyScope(body, auth);
-			if (refusedScope) {
-				json(res, refusedScope.status, { error: refusedScope.error });
-				return;
-			}
-			const refused = factory.applyBypassPolicy(body);
-			if (refused) {
-				json(res, 403, { error: refused });
-				return;
-			}
-			const resolved = factory.resolveProfile(body.profile, auth.allowedProfiles);
-			if (!resolved.ok) {
-				json(res, resolved.status, { error: resolved.error });
-				return;
-			}
-			const unavailable = availability.checkAvailable(resolved.profile);
-			if (unavailable) {
-				json(res, unavailable.status, { error: unavailable.error });
+			const refusal = vetCreateRequest(ctx, body, auth);
+			if (refusal) {
+				json(res, refusal.status, { error: refusal.error });
 				return;
 			}
-			const refusedCwd = factory.checkCwd(body, resolved.profile);
-			if (refusedCwd) {
-				json(res, refusedCwd.status, { error: refusedCwd.error });
-				return;
-			}
-			const badRequest = factory.checkPermissionMode(body.permissionMode, resolved.profile) ?? factory.checkEngineGrants(body, resolved.profile);
-			if (badRequest) {
-				json(res, 400, { error: badRequest });
-				return;
-			}
-			factory.stripInertFields(body, resolved.profile);
-			body.profile = resolved.profile?.name;
 			const runner = await factory.createRunner(factory.buildRunnerConfig(body));
 			factory.watchAuthSource(runner);
 			json(res, 201, { session: projects.withProject(runner.info()) });
@@ -1860,12 +1555,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 			return;
 		}
 		const filename = route.filePath.split("/").pop() || "file";
-		res.writeHead(200, {
-			"content-type": contentTypeFor(filename),
-			"content-length": Buffer.byteLength(content),
-			"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
-			"x-content-type-options": "nosniff"
-		});
+		res.writeHead(200, untrustedDownloadHeaders(filename, contentTypeFor(filename), Buffer.byteLength(content)));
 		res.end(content);
 		return;
 	}
@@ -2050,20 +1740,6 @@ async function handleCommand(ctx, frame, runner) {
 //#region src/services/attachments.ts
 const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
 const DEFAULT_MAX_SESSION_BYTES = 64 * 1024 * 1024;
-/**
-* Per-session hold for files the user attached to a message.
-*
-* In memory, and deliberately so. An attachment is only *needed* for the instant
-* between the upload and the message that names it; everything after that is
-* convenience (a client re-rendering a thumbnail after a reattach). That is the
-* same bargain `GET /sessions/:id/files` makes — the session's lifetime, no
-* durability tier — and it keeps the gateway from accumulating a photo library
-* on disk that nobody asked it to look after.
-*
-* Both caps are enforced here rather than at the route, so a host embedding the
-* server cannot forget one: a single file that is too big is a 413, and so is a
-* session whose total would go over.
-*/
 var AttachmentStore = class {
 	#bySession = /* @__PURE__ */ new Map();
 	#maxFileBytes;
@@ -2121,18 +1797,9 @@ var AttachmentStore = class {
 			attachment: ref(attachment)
 		};
 	}
-	/** The stored record, bytes included — for the download route and for the send
-	* path that turns ids into content blocks. */
 	get(sessionId, id) {
 		return this.#bySession.get(sessionId)?.get(id);
 	}
-	/**
-	* Resolve the ids a `user_message` named, in the order given.
-	*
-	* Missing ids are reported rather than skipped: a message that quietly lost its
-	* picture reads as the model ignoring it, which is a far worse failure than a
-	* command that errors.
-	*/
 	resolve(sessionId, ids) {
 		const held = this.#bySession.get(sessionId);
 		const attachments = [];
@@ -2162,11 +1829,6 @@ function ref(attachment) {
 		bytes: attachment.bytes
 	};
 }
-/**
-* A display name, not a path. The name is echoed back to clients and put in front
-* of the model in the text-attachment envelope, so directory separators, control
-* characters and unbounded length all come off here.
-*/
 function safeName(name) {
 	const cleaned = (name.split(/[/\\]/).pop() ?? "").replace(/[\u0000-\u001f\u007f"<>]/g, "").trim();
 	if (cleaned === "" || cleaned === "." || cleaned === "..") return "attachment";
@@ -2174,26 +1836,14 @@ function safeName(name) {
 }
 //#endregion
 //#region src/lib/scope.ts
-/**
-* The scope rules — opaque tags assigned at create, immutable after, and the
-* only intra-deployment scoping primitive there is. WorkerDeck stores and
-* enforces the tags; the embedder's `authorizeSession` decides what they mean.
-*/
-/** 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;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return;
 	const entries = Object.entries(value);
-	if (entries.some(([, v]) => typeof v !== "string")) return void 0;
+	if (entries.some(([, v]) => typeof v !== "string")) return;
 	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);
@@ -2206,23 +1856,11 @@ function checkScope(value) {
 	}
 	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);
@@ -2246,7 +1884,6 @@ function createAuthService(deps) {
 			canManageProfiles: principal.canManageProfiles === true
 		};
 	};
-	/** May this caller see — and therefore drive — this session? */
 	const canSee = (auth, session) => {
 		if (!options.authorizeSession) return scopeMatches(auth.scope, session.scope);
 		try {
@@ -2255,20 +1892,6 @@ function createAuthService(deps) {
 			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 ? refs.registry.get(job.sessionId)?.info() : void 0;
 		if (live) return canSee(auth, live);
@@ -2284,25 +1907,6 @@ function createAuthService(deps) {
 			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);
 	return {
 		authenticate,
@@ -2313,32 +1917,14 @@ function createAuthService(deps) {
 }
 //#endregion
 //#region src/services/availability.ts
-/**
-* Availability, per profile: the adapter's probe run over the env the real
-* assembly path produces (so anything the host hook injects — a
-* CLAUDE_CODE_OAUTH_TOKEN, say — counts as logged in). Cached, and served on
-* `GET /profiles` as `available`/`unavailableReason`.
-*
-* Gated on `checkCredentials` like the old claude-only preflight (this is a
-* library; `pnpm test` must spawn nothing unless a test injects fake
-* adapters or probes). 'unknown' stays out of the cache's answers: a probe
-* that couldn't run is not evidence of a missing login. **Display-only**
-* downstream — session create against an unavailable profile still proceeds
-* and fails with the engine's own error, because the probe can be stale in
-* both directions and refusing on it would turn a probe bug into an outage.
-* (`requireAvailableProfile` is the one deliberate exception, and only on a
-* definite `false`.)
-*/
 const AVAILABILITY_TTL_MS = 6e4;
 var AvailabilityTracker = class {
 	#verdicts = /* @__PURE__ */ new Map();
-	/** Profiles already warned about on the console, so re-probes don't spam. */
 	#warned = /* @__PURE__ */ new Set();
 	#opts;
 	constructor(opts) {
 		this.#opts = opts;
 	}
-	/** The cached verdict, if any probe has answered. */
 	get(name) {
 		return this.#verdicts.get(name)?.verdict;
 	}
@@ -2367,11 +1953,6 @@ var AvailabilityTracker = class {
 			if (verdict.available === true) this.#warned.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.
-	*/
 	checkAvailable(profile) {
 		if (!this.#opts.requireAvailableProfile || !profile) return null;
 		const verdict = this.get(profile.name);
@@ -2381,13 +1962,9 @@ var AvailabilityTracker = class {
 			error: `profile '${profile.name}' is unavailable: ${verdict.reason ?? "no usable credentials"}`
 		};
 	}
-	/** Launch-time sweep, concurrent and fire-and-forget. */
 	preflight(profiles) {
 		for (const profile of profiles) this.probe(profile);
 	}
-	/** Lazy re-probe on reads, so an operator who just ran `codex login` (or
-	* exported a key) sees the profile go green without a restart. Serves the
-	* cached verdict now; the refreshed one lands on the next request. */
 	refresh(profiles) {
 		if (!this.#opts.checkCredentials) return;
 		const now = Date.now();
@@ -2399,32 +1976,18 @@ var AvailabilityTracker = class {
 };
 //#endregion
 //#region src/services/bridge.ts
-/**
-* Routes tool executions between a session and the browser tabs attached to it.
-*
-* A session may have several clients attached (dashboard plus embedded panel);
-* the bridge asks the **first attached** one, which is the closest thing to "the
-* client driving this session". If none is attached, dispatch fails fast rather
-* than hanging — an autonomous job simply never bridges, it uses the server
-* executor instead.
-*/
 var BridgeHub = class {
 	#sessions = /* @__PURE__ */ new Map();
 	#options;
 	constructor(options = {}) {
 		this.#options = options;
 	}
-	/** The executor to hand a runner for this session. Created on first use and
-	* reused, so results routed back always reach the same pending table. */
 	executorFor(sessionId) {
 		return this.#bridge(sessionId).executor;
 	}
-	/** How many clients are watching this session. Parking consults it: a session
-	* someone is watching stays live. */
 	attachedCount(sessionId) {
 		return this.#sessions.get(sessionId)?.sockets.length ?? 0;
 	}
-	/** Register an attached client. Returns a detach function. */
 	attach(sessionId, send) {
 		const bridge = this.#bridge(sessionId);
 		bridge.sockets.push(send);
@@ -2433,14 +1996,9 @@ var BridgeHub = class {
 			if (index >= 0) bridge.sockets.splice(index, 1);
 		};
 	}
-	/**
-	* Deliver a client's answer to a bridged call. Returns false when the id is
-	* unknown or already settled — late and duplicate answers are ignored.
-	*/
 	resolve(sessionId, executionId, answer) {
 		return this.#sessions.get(sessionId)?.executor.resolve(executionId, answer) ?? false;
 	}
-	/** Drop a session's bridge, failing anything still in flight. */
 	remove(sessionId) {
 		const bridge = this.#sessions.get(sessionId);
 		if (!bridge) return;
@@ -2478,38 +2036,15 @@ var BridgeHub = class {
 };
 //#endregion
 //#region src/services/notifications.ts
-/**
-* Turns session events into the handful of notifications a human away from the
-* screen cares about, and delivers them to a webhook and/or a local observer.
-*
-* This is the *primitive*, deliberately transport-agnostic: the server stays
-* credential-free and knows nothing about APNs, Slack or email. Turning a
-* notification into a push is a forwarder's job (the turnkey CLI's), and one that
-* needs credentials, so it does not live here.
-*
-* Delivery is best-effort and ordered per session, mirroring the job queue's
-* webhook behaviour — a consumer that missed one can always attach to the session
-* WS with `afterSeq` and see the truth.
-*/
 var SessionNotifier = class {
 	#options;
-	/** Per-session delivery chain, so a session's notifications arrive in order. */
 	#chains = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.#options = options;
 	}
-	/** True when nothing is listening — lets the caller skip subscribing at all. */
 	get idle() {
 		return !this.#options.webhook && !this.#options.onNotification;
 	}
-	/**
-	* Subscribe to a runner for its lifetime.
-	*
-	* `afterSeq` defaults to whatever the runner has already emitted, which is what
-	* makes this safe on a *rehydrated* session: `subscribe` replays the log from
-	* `afterSeq`, so subscribing at 0 to a session rebuilt from a park would
-	* re-announce every permission request it ever made.
-	*/
 	watch(runner, afterSeq = runner.info().lastSeq) {
 		if (this.idle) return;
 		runner.subscribe((event) => {
@@ -2573,12 +2108,6 @@ var SessionNotifier = class {
 			if (this.#chains.get(runner.id) === next) this.#chains.delete(runner.id);
 		});
 	}
-	/**
-	* Best-effort POST with exponential backoff. Deliberately a near-copy of the
-	* queue's job-webhook delivery rather than a shared helper: the two channels
-	* have different payloads and different consumers, and coupling them would mean
-	* a change to job deliveries silently changing session deliveries.
-	*/
 	async #deliver(webhook, notification) {
 		const attempts = this.#options.attempts ?? 3;
 		const baseDelay = this.#options.retryDelayMs ?? 500;
@@ -2599,100 +2128,27 @@ var SessionNotifier = class {
 };
 //#endregion
 //#region src/services/parking.ts
-/**
-* 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,
-* evicts, and persists; delivering a result rebuilds the runner under the same id
-* and hands the result to it. The session's identity, event log, and seq numbering
-* survive intact, so a client reattaching with `afterSeq` sees one unbroken stream.
-*/
 var SessionParkManager = class {
 	#options;
-	/** executionId → sessionId, for routing a result to its session. Kept in memory
-	* across the park; rebuilt from the store by {@link hydrate}. */
 	#owners = /* @__PURE__ */ new Map();
-	/** Executions already settled, kept until their session ends so a late or
-	* duplicate delivery answers "already settled" instead of "never heard of it". */
 	#settled = /* @__PURE__ */ new Map();
 	#timers = /* @__PURE__ */ new Map();
-	/** One resume per session, ever: two results arriving together must not build
-	* two runners under the same id (the second would orphan the first, leaking the
-	* MCP connection the park existed to release). */
 	#resuming = /* @__PURE__ */ new Map();
 	#detachTimers = /* @__PURE__ */ new Map();
-	/** The config each live session was built from — what a rebuild needs, and the
-	* one thing a runner doesn't carry on its public surface. */
 	#configs = /* @__PURE__ */ new Map();
-	/**
-	* Sessions this process has written a dormant record for. Its only job is to
-	* tell "the engine has not named its session *yet*" apart from "the engine
-	* had named it and no longer has one" (a `conversation_reset` on an engine
-	* whose fresh id is not known until its next turn) — the first is the normal
-	* startup window and must cost no store write, the second must delete a
-	* record that has gone stale. It is accurate for exactly the sessions that
-	* matter: a woken session's runner is rebuilt with `resume` set, so it names
-	* its engine session immediately and re-enters the set on its first save.
-	*/
 	#remembered = /* @__PURE__ */ new Set();
-	/**
-	* In-flight store work per session, so operations on one record run in order.
-	*
-	* Load-bearing with any store whose writes are real I/O. `#park` must evict the
-	* runner *before* the save completes (an attach between `park()` and `evict()`
-	* would bind a client to an inert runner), which leaves a window where the
-	* session is in neither the registry nor the store. A delivery arriving inside it
-	* would read past the write: `store.get` misses, the result is answered 404, the
-	* execution is filed as settled with its watchdog cleared — and then the record
-	* lands on disk with nothing left alive that could ever wake it. A `discard`
-	* inside the same window would delete nothing and leave the save to resurrect a
-	* session the caller was told was closed.
-	*/
 	#storeOps = /* @__PURE__ */ new Map();
 	#closed = false;
 	constructor(options) {
 		this.#options = options;
 	}
-	/** Record the config a session was created with. Only sessions the host
-	* remembers can be parked — there is no way to rebuild the others. */
 	remember(sessionId, config) {
 		this.#configs.set(sessionId, config);
 	}
-	/**
-	* Re-save a live session's dormant record because something outside the event
-	* stream changed it.
-	*
-	* `#rememberDormant` is otherwise driven by `status_changed` and `system_init`
-	* alone, and a rename (`PATCH /sessions/:id`) fires neither — so without this
-	* a renamed session that is never touched again keeps its old title on disk
-	* and comes back under it. Safe to call for anything: every gate in
-	* `#rememberDormant` still applies, so a session that cannot be resumed, has
-	* no engine session yet, or is no longer the registry's writes nothing.
-	*/
 	touch(runner) {
 		this.#rememberDormant(runner);
 		this.#persistLive(runner);
 	}
-	/**
-	* 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.
-	*
-	* 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()) {
@@ -2700,12 +2156,6 @@ var SessionParkManager = class {
 			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
-	* engine says the turn has come to rest on them, and clean up when it ends.
-	* `afterSeq` skips a rehydrated runner's replayed history (re-arming a watchdog
-	* from an event whose deadline already passed would fail the execution instantly).
-	*/
 	watch(runner, afterSeq = 0) {
 		return runner.subscribe((event) => {
 			switch (event.type) {
@@ -2748,7 +2198,6 @@ var SessionParkManager = class {
 			}
 		}, afterSeq);
 	}
-	/** A client detached: park the session if that was the last one watching. */
 	onDetach(sessionId) {
 		if (this.#closed) return;
 		const runner = this.#options.registry.get(sessionId);
@@ -2761,34 +2210,21 @@ var SessionParkManager = class {
 		timer.unref?.();
 		this.#detachTimers.set(sessionId, timer);
 	}
-	/** Which session this execution belongs to — still waiting, or already settled. */
 	sessionFor(executionId) {
 		return this.#owners.get(executionId) ?? this.#settled.get(executionId);
 	}
-	/** The stored session's record, for the read paths (GET, list, attach). */
 	get(id) {
 		return this.#queue(id, () => this.#options.store.get(id));
 	}
-	/** 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()).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. */
 	async ensureLive(id) {
 		const live = this.#options.registry.get(id);
 		if (live) return live;
 		return this.#resume(id);
 	}
-	/**
-	* Deliver a deferred execution's result. Rehydrates the session if needed and
-	* folds the result into its agent loop.
-	*
-	* Undefined = no session is waiting on that id. `applied: false` = it was already
-	* settled: a duplicate delivery, or one racing the watchdog. Both are expected,
-	* neither is an error.
-	*/
 	async submitResult(executionId, result) {
 		const sessionId = this.#owners.get(executionId);
 		if (sessionId === void 0) {
@@ -2811,7 +2247,6 @@ var SessionParkManager = class {
 			sessionId
 		};
 	}
-	/** Drop a parked session for good: the run is over (closed, canceled, killed). */
 	async discard(sessionId) {
 		clearTimeout(this.#detachTimers.get(sessionId));
 		this.#detachTimers.delete(sessionId);
@@ -2828,21 +2263,6 @@ 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();
@@ -2880,17 +2300,6 @@ var SessionParkManager = class {
 			});
 		}
 	}
-	/**
-	* Drop a dormant record that has stopped being true, leaving the live session
-	* alone — the narrow counterpart to {@link ParkingService.discard}, which also
-	* forgets the config and the session's executions and would therefore make a
-	* clear cost the session its ability to go dormant ever again.
-	*
-	* Only ever called behind {@link ParkingService.#rememberDormant}'s guards,
-	* which is what keeps it off a parked record: a park evicts the runner from
-	* the registry before it saves, and the ownership guard turns a late event
-	* from an evicted runner into a no-op.
-	*/
 	async #forgetDormant(sessionId) {
 		this.#remembered.delete(sessionId);
 		try {
@@ -2902,26 +2311,6 @@ var SessionParkManager = class {
 			});
 		}
 	}
-	/**
-	* Write a live session's snapshot through to the store, so a restart can
-	* rebuild it. The counterpart to {@link #rememberDormant} for the engine that
-	* has no engine-side session to resume from — same discipline, different
-	* mechanism: that one remembers *where the transcript is*, this one carries it.
-	*
-	* The gates are the same four, plus the option and the engine's ability. The
-	* `registry.get(runner.id) !== runner` check is doing the same work it does
-	* there: a runner that has been evicted (parked, or replaced by a rebuild)
-	* finds itself a stranger here and writes nothing, so a late event cannot
-	* overwrite a park with a stale live record.
-	*
-	* **This must not run synchronously inside the event listener**, and that is
-	* easy to lose. `turn_result` is emitted from inside the turn, *before* the
-	* `finally` that clears the runner's abort controller — so a `snapshot()`
-	* called straight from the listener would see a turn in flight and refuse,
-	* every single time, silently. `#queue`'s microtask hop is what puts the call
-	* after it. A refactor that "simplifies" this into a direct call produces a
-	* write-through that never writes and nothing that says so.
-	*/
 	async #persistLive(runner) {
 		if (this.#closed || !this.#options.persistLive || !runner.snapshot) return;
 		const config = this.#configs.get(runner.id);
@@ -3009,7 +2398,7 @@ var SessionParkManager = class {
 	}
 	async #rebuild(id) {
 		const record = await this.#queue(id, () => this.#options.store.get(id));
-		if (!record) return void 0;
+		if (!record) return;
 		let runner;
 		try {
 			runner = await this.#options.rebuild(record);
@@ -3037,9 +2426,6 @@ var SessionParkManager = class {
 		runner.start();
 		return runner;
 	}
-	/** Run a store operation after whatever is already in flight for this session.
-	* The chain is per session and drops itself once idle; a failed operation never
-	* poisons the ones behind it (each caller handles its own). */
 	#queue(sessionId, op) {
 		const result = (this.#storeOps.get(sessionId) ?? Promise.resolve()).then(op);
 		const settled = result.then(() => {}, () => {});
@@ -3084,40 +2470,8 @@ var SessionParkManager = class {
 };
 //#endregion
 //#region src/services/produced-files.ts
-/**
-* The paths this gateway will serve from `GET /sessions/:id/produced/:fileId`.
-*
-* **This is the whole access-control model, so it is worth being precise about
-* what it is.** The store is an allowlist built from one source and one only:
-* `file_produced` events, which a runner emits about a file its own engine just
-* wrote. It is not a directory grant. Nothing else can add to it — not a
-* request, not a config, and in particular not the agent, whose own path claims
-* go through `/fs/*` and that route's root allowlist.
-*
-* That is why the route needs neither `hostFiles.roots` nor `maxFileBytes`:
-* "somewhere under a root the operator declared" is a guess about which paths
-* are safe, while "the exact path this session's runner reported producing" is
-* a fact about one file. A 2 MB generated PNG is the common case, and making
-* the operator raise a byte cap to see their own picture was the bug this
-* replaces.
-*
-* Lifetime is the session's, like `AttachmentStore`'s: in memory, dropped when
-* the session is removed. The bytes are never held here — only the path, so a
-* gateway serving a long session accumulates a few hundred bytes per picture
-* rather than the pictures.
-*/
 var ProducedFileStore = class {
 	#bySession = /* @__PURE__ */ new Map();
-	/**
-	* Register a runner's produced files for its lifetime.
-	*
-	* Subscribes from seq 0, which is the opposite of what `SessionNotifier` wants
-	* and correct for the same reason: registration is idempotent (a `fileId` is
-	* derived from its path, so re-registering overwrites with itself), and a
-	* session rebuilt from a park must re-learn every file it produced before the
-	* park — otherwise a client's transcript keeps rendering image cards whose
-	* bytes have quietly become unreachable.
-	*/
 	watch(runner) {
 		runner.subscribe((event) => {
 			if (event.type !== "file_produced") return;
@@ -3135,7 +2489,6 @@ var ProducedFileStore = class {
 	get(sessionId, fileId) {
 		return this.#bySession.get(sessionId)?.get(fileId);
 	}
-	/** Everything one session has produced, newest registration last. */
 	list(sessionId) {
 		return [...this.#bySession.get(sessionId)?.values() ?? []];
 	}
@@ -3145,19 +2498,9 @@ var ProducedFileStore = class {
 };
 //#endregion
 //#region src/services/profiles.ts
-/**
-* The profile directory: startup-declared profiles unioned with store-managed
-* ones, validation shared by startup (throws) and the management routes (400s),
-* and the response decoration (`forResponse`) every profile answer goes through.
-*
-* Declared profiles are code — never persisted, never editable over HTTP. The
-* store-managed set is mirrored in memory so every lookup on the request path
-* stays synchronous; `refreshStored()` reloads it after each mutation.
-*/
 var ProfileService = class {
 	#declared;
 	#declaredByName;
-	/** Store-managed profiles, mirrored in memory — see the module doc. */
 	#stored = /* @__PURE__ */ new Map();
 	#opts;
 	constructor(opts) {
@@ -3166,11 +2509,6 @@ var ProfileService = class {
 		this.#declaredByName = new Map(opts.declared.map((p) => [p.name, p]));
 		if (this.#declaredByName.size !== opts.declared.length) throw new Error("createWorkerServer: duplicate profile names in `profiles`");
 	}
-	/**
-	* Everything wrong with a profile that the server can tell without running it.
-	* Shared by startup (where it throws) and the management routes (where it 400s),
-	* so a profile created over HTTP can never be one startup would have refused.
-	*/
 	validate(p) {
 		const { adapterFor, disableBypassPermissions, hasEngineRunnerFactory } = this.#opts;
 		if (isProviderProfile(p)) {
@@ -3185,31 +2523,17 @@ var ProfileService = class {
 		if (fallbackMode && !supportsPermissionMode(p.engine, fallbackMode)) return `profile '${p.name}' defaults to permission mode '${fallbackMode}', which engine '${engineOf(p)}' does not support (supported: ${adapterFor(engineOf(p)).capabilities.permissionModes.join(", ")})`;
 		return null;
 	}
-	/** Reload the in-memory mirror of the store — once at `listen()`, and after
-	* each management-route mutation. Single-process, like the bundled queue. */
 	async refreshStored() {
 		if (!this.#opts.store) return;
 		this.#stored.clear();
 		for (const p of await this.#opts.store.list()) this.#stored.set(p.name, p);
 	}
-	/** Response-only marker so a UI knows which rows it may edit. Declared profiles
-	* are code; only store-backed ones can be changed over the API. */
 	withManagedFlag(p) {
 		return this.#declaredByName.has(p.name) ? p : {
 			...p,
 			managed: true
 		};
 	}
-	/**
-	* Response shape for a profile: the managed marker, the engine's capability
-	* record, its static model catalog (correct from the first request — no
-	* warm-up session, no process spawned), the availability verdict when one
-	* has been probed, the learned default model (the one thing a static
-	* catalog cannot know: a claude profile's default is the operator's CLI
-	* config, so it stays absent until a session on the profile reports it),
-	* and the plan usage learned from the profile's sessions' rate_limit events.
-	* Read-only decoration — never persisted.
-	*/
 	forResponse(p) {
 		const { adapterFor, decorate } = this.#opts;
 		const adapter = adapterFor(p.engine);
@@ -3229,16 +2553,12 @@ var ProfileService = class {
 		if (usage) base.usage = usage;
 		return base;
 	}
-	/** Declared profiles first: a name collision means the code wins, and the stored
-	* one is unreachable rather than silently overriding server options. */
 	all() {
 		return [...this.#declared, ...[...this.#stored.values()].filter((p) => !this.#declaredByName.has(p.name))];
 	}
 	get(name) {
 		return this.#declaredByName.get(name) ?? this.#stored.get(name);
 	}
-	/** Profile management is doubly opt-in: the operator wires a store, and the host
-	* marks the principal. Neither on its own is enough. */
 	manageGuard(auth) {
 		if (!this.#opts.store) return {
 			status: 404,
@@ -3250,19 +2570,12 @@ var ProfileService = class {
 		};
 		return null;
 	}
-	/** Startup-declared profiles are code. Editing one over HTTP would make the
-	* server options lie about what is actually running. */
 	declaredGuard(profile) {
 		return this.#declaredByName.has(profile.name) ? {
 			status: 403,
 			error: `profile '${profile.name}' is declared in server options and cannot be changed over the API — edit the \`profiles\` option instead`
 		} : null;
 	}
-	/**
-	* A managed Claude profile names a config directory, and that directory is a
-	* credential store. Bound it to operator-declared roots; unset roots means the
-	* management routes create provider profiles only.
-	*/
 	configDirGuard(profile) {
 		if (isProviderProfile(profile)) return null;
 		const roots = this.#opts.allowedConfigDirRoots;
@@ -3275,9 +2588,6 @@ var ProfileService = class {
 			error: "configDir is outside the allowed roots"
 		};
 	}
-	/** Validate and persist a managed profile. Shared by create and update so a
-	* PATCH can never leave behind a profile a POST would have refused. Returns
-	* the saved profile (managed-flagged) or a refusal. */
 	async saveManaged(incoming) {
 		const { managed: _clientClaim, ...profile } = incoming;
 		const refused = this.configDirGuard(profile);
@@ -3301,35 +2611,8 @@ var ProfileService = class {
 };
 //#endregion
 //#region src/services/profile-usage.ts
-/**
-* The gateway's single plan-usage state per profile, fed from every session's
-* `rate_limit` events and served on `GET /profiles` (`ProfileInfo.usage`).
-*
-* Why this exists at all: usage had only ever lived in session transcripts, so
-* a client attaching to a session that idled since yesterday replayed
-* yesterday's reading as if current — and a session opened today knew nothing
-* of what a sibling session on the same account spent an hour ago. The profile
-* is the account boundary (one config dir / codex home / provider key = one
-* plan), so the newest reading across all of a profile's sessions is the one
-* usage state that is ever worth showing. No history: last-write-wins per
-* window, exactly the reducer's rule on the client side.
-*
-* Last-write-wins goes by the **event's own clock**, not arrival order:
-* `watch()` subscribes from seq 0 (a replayed log is how a rebuilt session's
-* readings arrive at all), and a replayed yesterday-reading must not clobber
-* the fresher one another session on the same profile reported live. All
-* events are stamped by this gateway's clock at emit time, so the comparison
-* is sound across sessions.
-*
-* In-memory on purpose, like the learned default models and the availability
-* cache: display-only state may start empty after a restart (absent = unknown,
-* never 0%), and the first session to report refills it.
-*/
 var ProfileUsageTracker = class {
-	/** profile name → rateLimitType → newest reading. */
 	#profiles = /* @__PURE__ */ new Map();
-	/** Follow a runner's `rate_limit` events for its lifetime. Sessions without a
-	* profile have no account to attribute usage to and are skipped. */
 	watch(runner) {
 		const profile = runner.info().profile;
 		if (!profile) return;
@@ -3347,31 +2630,14 @@ var ProfileUsageTracker = class {
 			});
 		});
 	}
-	/**
-	* The profile's windows as they should be served *now*. Undefined until any
-	* session on the profile has reported (unknown, never 0%).
-	*
-	* The 0%-after-reset inference lives here — at serve time — and nowhere
-	* else, because it is a function of the wall clock: a window whose own
-	* `resetsAt` has passed with no newer reading has provably rolled, so the
-	* pre-reset utilization is no longer merely stale but *wrong*. It cannot be
-	* a producer's job (the producers only relay what the engine said, and the
-	* whole problem is the engine's silence; a fabricated 0% event would be
-	* replayed from transcripts forever as if reported) and must not be every
-	* renderer's (N clients would each reimplement the clock math). The held
-	* reading stays untouched, so a late fresh report still lands by ts, and the
-	* served zero is labeled `inferredReset` — it is a floor, not a report: the
-	* account may have been used outside this gateway since the reset.
-	*/
 	usage(profile, now = Date.now()) {
 		const windows = this.#profiles.get(profile);
-		if (!windows || windows.size === 0) return void 0;
+		if (!windows || windows.size === 0) return;
 		const out = {};
 		for (const [type, held] of windows) out[type] = serveWindow(held, now);
 		return out;
 	}
 };
-/** `resetsAt` is epoch **seconds** (protocol contract); `now` is epoch ms. */
 function serveWindow(held, now) {
 	const resetsAt = held.info.resetsAt;
 	if (resetsAt !== void 0 && resetsAt * 1e3 <= now) return {
@@ -3390,7 +2656,6 @@ function serveWindow(held, now) {
 }
 //#endregion
 //#region src/services/registry.ts
-/** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
 var SessionRegistry = class {
 	#sessions = /* @__PURE__ */ new Map();
 	#options;
@@ -3400,19 +2665,14 @@ var SessionRegistry = class {
 	create(config) {
 		return this.adopt(new SessionRunner(config));
 	}
-	/** Build and list a Claude-engine runner without starting it, so watchers can
-	* subscribe first. Call `start()` once they have. */
 	prepare(config) {
 		return this.register(new SessionRunner(config));
 	}
-	/** Register an already-built runner (a non-Claude engine) and start it. */
 	adopt(runner) {
 		this.register(runner);
 		runner.start();
 		return runner;
 	}
-	/** List a runner without starting it — for a rehydrated session, whose watchers
-	* must be subscribed before it comes back up. */
 	register(runner) {
 		const existing = this.#sessions.get(runner.id);
 		this.#sessions.set(runner.id, runner);
@@ -3431,8 +2691,6 @@ var SessionRegistry = class {
 		runner.close("server");
 		return this.#sessions.delete(id);
 	}
-	/** Drop a runner WITHOUT closing it: the session isn't ending, it parked and
-	* lives on in its snapshot. Closing here would tell every client it was over. */
 	evict(id) {
 		return this.#sessions.delete(id);
 	}
@@ -3442,50 +2700,19 @@ var SessionRegistry = class {
 };
 //#endregion
 //#region src/services/session-factory.ts
-/**
-* The create pipeline: everything between a `CreateSessionRequest` arriving and
-* a `Runner` running — policy checks (bypass, permission mode, engine grants,
-* scope, cwd), profile resolution, config assembly (`buildRunnerConfig`), and
-* the one chokepoint that builds runners for create, dormant rebuild and parked
-* rebuild alike (`buildRunner`).
-*
-* Registry/parking/bridge are handed in as late-bound refs because construction
-* is mutually recursive with them (parking's rebuild callback calls
-* `buildRunner`; `createRunner` registers and watches). The refs are filled
-* during assembly, before the server accepts a request.
-*/
 function createSessionFactory(deps) {
 	const { adapterFor, profiles, refs } = deps;
-	/** Profiles (by name; '' = none) whose oauth notice has been logged. */
 	const subscriptionNoticeShown = /* @__PURE__ */ new Set();
-	/** Enforce the server's bypass policy on a create request. Returns a 403 message
-	* for an explicit bypass-mode request; strips the pre-authorization capability
-	* silently (see the option's doc for why). */
 	const applyBypassPolicy = (req) => {
 		if (!deps.disableBypassPermissions) return null;
 		if (req.permissionMode === "bypassPermissions") return "bypassPermissions is disabled on this server (disableBypassPermissions)";
 		delete req.allowDangerouslySkipPermissions;
 		return null;
 	};
-	/** Reject a permission mode the resolved profile's engine has no meaning for.
-	* The create form already filters what it offers, but the API is the boundary:
-	* a provider session asked for 'plan' should be told so, not silently coerced
-	* into 'default' by whatever assembles its runner. Returns an error message. */
 	const checkPermissionMode = (mode, profile) => {
 		if (mode === void 0 || supportsPermissionMode(profile?.engine, mode)) return null;
 		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') — supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
 	};
-	/**
-	* Refuse the request fields the resolved profile's engine cannot honor —
-	* read off its capability record, so the create form's filtering and the
-	* API boundary can never disagree. Refusing beats coercing: a caller who
-	* asked for something the engine has no meaning for should be told, not
-	* left wondering where the option went. Also enforces the provider grant
-	* rules (capabilities narrow, never widen; MCP servers are the profile's to
-	* declare — MCP tools are authoritative, server-side, with server
-	* credentials, so honoring a client-supplied server would let a caller
-	* point an authoritative tool anywhere it liked).
-	*/
 	const checkEngineGrants = (req, profile) => {
 		const engine = engineOf(profile);
 		const caps = adapterFor(profile?.engine).capabilities;
@@ -3503,22 +2730,9 @@ function createSessionFactory(deps) {
 		if (ungranted.length === 0) return null;
 		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) — a request may narrow capabilities, not widen them`;
 	};
-	/** Drop request fields that are meaningless (not wrong) for the engine —
-	* today just `questionBehavior` where no approval channel exists, so job
-	* webhooks never grow phantom permission_requested expectations. */
 	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 {
@@ -3543,17 +2757,6 @@ function createSessionFactory(deps) {
 		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,
@@ -3568,21 +2771,10 @@ function createSessionFactory(deps) {
 			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 ? profiles.get(req.profile) : void 0;
 		if (!profile) return withScope(deps.hostBuildRunnerConfig(req), req.scope);
@@ -3599,7 +2791,6 @@ function createSessionFactory(deps) {
 			env
 		};
 	};
-	/** The env a probe should test: exactly what the real assembly path produces. */
 	const sessionEnvFor = (profile) => {
 		try {
 			return buildRunnerConfig({
@@ -3610,12 +2801,6 @@ function createSessionFactory(deps) {
 			return engineOf(profile) === "claude" ? claudeSessionEnv(profile, process.env) : process.env;
 		}
 	};
-	/** Build a runner for a session, choosing the engine from its profile. Async
-	* because the engine factory may be: a provider session can need an awaited
-	* assembly step (per-session MCP connect) before it has a runner at all.
-	*
-	* `restore` rebuilds a parked session rather than creating a new one — same id,
-	* same log, mid-task. */
 	const buildRunner = async (config, restore, id) => {
 		const name = config.profile;
 		const profile = name !== void 0 ? profiles.get(name) : void 0;
@@ -3643,9 +2828,6 @@ function createSessionFactory(deps) {
 		runner.start();
 		return runner;
 	};
-	/** Resolve a request's profile: required when several are declared, implicit with
-	* exactly one, scoped by the principal's allowedProfiles. Returns the resolved
-	* profile (undefined when the server declares none) or a response-ready error. */
 	const resolveProfile = (name, allowedProfiles) => {
 		if (name !== void 0 && typeof name !== "string") return {
 			ok: false,
@@ -3713,30 +2895,40 @@ function createSessionFactory(deps) {
 }
 //#endregion
 //#region src/server.ts
+/** How long a client gets to acknowledge the shutdown close frame before its socket is torn down. */
+const SOCKET_CLOSE_GRACE_MS = 250;
 /**
-* `createWorkerServer` — the assembly. Option types live in `options.ts`, the
-* shared-state record routes take in `context.ts`, per-route behaviour in
-* `routes/`, the stateful pieces in `services/`, and the pure rules in `lib/`.
-* This file only wires them together and dispatches requests.
+* Split live sessions into "will finish by itself" and "needs a person".
+*
+* `sessionState` is the vocabulary the dashboard, the session list and `workerdeck guard` already sort by, and it
+* draws exactly the line a drain needs: `working` covers starting/running and running subagents, while `attention`
+* covers a pending approval. Re-spelling that set here is how the two definitions would drift apart.
 */
+function surveyDrain(registry) {
+	const working = [];
+	const awaitingHuman = [];
+	for (const info of registry.list()) {
+		const state = sessionState(info);
+		if (state === "working") working.push(info.id);
+		else if (state === "attention") awaitingHuman.push(info.id);
+	}
+	return {
+		working,
+		awaitingHuman,
+		timedOut: false
+	};
+}
+function sameDrain(a, b) {
+	return a.working.join() === b.working.join() && a.awaitingHuman.join() === b.awaitingHuman.join();
+}
 function createWorkerServer(options = {}) {
 	if (!options.authenticate && !options.allowUnauthenticated) throw new Error("createWorkerServer: provide `authenticate` or explicitly set `allowUnauthenticated: true`");
 	const basePath = options.basePath ?? "/v1";
 	const fallback = options.fallback;
 	const corsOrigins = options.cors?.origins.length ? new Set(options.cors.origins) : void 0;
 	const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
-	/** The engine's adapter, honoring the test-only `engines` override. */
 	const adapterFor = (engine) => options.engines?.[engine ?? "claude"] ?? getEngineAdapter(engine);
-	/**
-	* What each claude profile's *default* model resolves to, learned from the
-	* `capabilities` events of sessions that ran on it. The model *list* is the
-	* adapter's static catalog now; the default is the one thing a catalog
-	* cannot know (it is the operator's CLI config), so it alone is still
-	* learned — and still absent on a cold server, the accepted regression.
-	*/
 	const profileDefaultModels = /* @__PURE__ */ new Map();
-	/** The single plan-usage state per profile, fed from every session's
-	* `rate_limit` events and served by `forResponse` (see ProfileUsageTracker). */
 	const profileUsage = new ProfileUsageTracker();
 	const profiles = new ProfileService({
 		declared: options.profiles ?? detectDefaultProfiles(),
@@ -3825,6 +3017,8 @@ function createWorkerServer(options = {}) {
 		refs
 	});
 	const wss = new WebSocketServer({ noServer: true });
+	let closing;
+	let draining = false;
 	const queueSockets = /* @__PURE__ */ new Set();
 	const sendQueueFrame = (ws, frame) => {
 		if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(frame));
@@ -3967,6 +3161,10 @@ function createWorkerServer(options = {}) {
 			json(res, 404, { error: "not found" });
 			return;
 		}
+		if (draining && req.method === "POST" && route.id === void 0) {
+			json(res, 503, { error: "server is shutting down" });
+			return;
+		}
 		const authCtx = await auth.authenticate(req);
 		if (!authCtx.ok) {
 			json(res, 401, { error: "unauthorized" });
@@ -4057,53 +3255,50 @@ function createWorkerServer(options = {}) {
 				});
 			});
 		},
-		close: () => new Promise((resolve) => {
-			queue?.close();
-			parking.close();
-			registry.closeAll();
-			for (const ws of queueSockets) ws.close();
-			queueSockets.clear();
-			wss.close();
-			server.close(() => resolve());
-			server.closeAllConnections();
-		})
+		drain: async (drainOptions = {}) => {
+			const { timeoutMs = 3e4, pollMs = 250, onProgress } = drainOptions;
+			draining = true;
+			const deadline = Date.now() + timeoutMs;
+			let report = surveyDrain(registry);
+			onProgress?.(report);
+			while (report.working.length > 0 && Date.now() < deadline) {
+				await new Promise((resolve) => setTimeout(resolve, pollMs));
+				const next = surveyDrain(registry);
+				if (!sameDrain(next, report)) onProgress?.(next);
+				report = next;
+			}
+			report = {
+				...surveyDrain(registry),
+				timedOut: false
+			};
+			report.timedOut = report.working.length > 0;
+			onProgress?.(report);
+			return report;
+		},
+		close: () => {
+			closing ??= new Promise((resolve) => {
+				queue?.close();
+				parking.close();
+				registry.closeAll();
+				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();
+				wss.close();
+				server.close(() => {
+					clearTimeout(force);
+					resolve();
+				});
+				server.closeAllConnections();
+			});
+			return closing;
+		}
 	};
 }
 //#endregion
 //#region src/lib/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,
@@ -4120,30 +3315,6 @@ function sandboxedProviderProfile(name, provider, options = {}) {
 }
 //#endregion
 //#region src/lib/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;
@@ -4179,7 +3350,6 @@ async function createProviderRunner(ctx, options) {
 }
 //#endregion
 //#region src/services/profile-store.ts
-/** Non-durable store for tests and ephemeral deployments. */
 function createMemoryProfileStore(seed = []) {
 	const profiles = new Map(seed.map((p) => [p.name, p]));
 	return {
@@ -4188,14 +3358,6 @@ function createMemoryProfileStore(seed = []) {
 		delete: (name) => void profiles.delete(name)
 	};
 }
-/**
-* JSON-file store: one array of profiles at `path` (default
-* `<cwd>/.workerdeck/profiles.json`). Writes go through a temp file and a
-* rename so a crash mid-write cannot truncate the operator's profile list.
-*
-* Single-process by design, exactly like the bundled queue adapter — two servers
-* sharing one file would race. That is what the seam is for.
-*/
 function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profiles.json")) {
 	const read = () => {
 		try {