@kubb/studio 5.3.16 → 5.3.18

package/dist/index.js

@@ -1,71 +1,27 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { GENERATION_GONE_MESSAGE, generationEventTypes } from "./protocol.js";
+import { AGENT_INSTANCE_HEADER, AgentCloseCode, GENERATION_GONE_MESSAGE, generationEventTypes } from "./protocol.js";
 import { createRequire } from "node:module";
-import process$1 from "node:process";
-import { spawn } from "node:child_process";
+import { createHash, hash, randomBytes, randomUUID } from "node:crypto";
 import { glob, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import path, { isAbsolute, join, relative, resolve, sep } from "node:path";
+import process$1 from "node:process";
+import { spawn } from "node:child_process";
+import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, memoryStorage, resolveCacheDir } from "@kubb/core";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { FetchError, ofetch } from "ofetch";
-import { createHash, hash, randomBytes } from "node:crypto";
 import { promisify, styleText } from "node:util";
 import { createStorage } from "unstorage";
 import fsDriver from "unstorage/drivers/fs";
-import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, memoryStorage } from "@kubb/core";
-import { x } from "tinyexec";
 import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
 import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { mergeDeep } from "remeda";
-import { tmpdir } from "node:os";
 import { gzip } from "node:zlib";
 import { build } from "tsdown";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
 import WebSocket from "ws";
-import { setTimeout as setTimeout$1 } from "node:timers/promises";
-//#region src/constants.ts
-/**
-* Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
-* not whatever default the client would pick on its own.
-*/
-const defaultStudioUrl = "https://kubb.studio";
-/**
-* Defaults the Studio client uses when a host passes nothing.
-* Config path is left out on purpose: each host discovers that itself.
-*/
-const agentDefaults = {
-	studioUrl: defaultStudioUrl,
-	retryIntervalMs: 3e4,
-	heartbeatIntervalMs: 3e4,
-	/**
-	* Slowest heartbeat a host may ask for. Studio drops an agent from the active list once its
-	* stored ping is older than its liveness window, and it stores a ping at most once a minute, so
-	* a slower cadence would make a healthy agent look dead after a single missed ping.
-	*/
-	maxHeartbeatIntervalMs: 6e4,
-	/** How long a heartbeat ping may take before the session is treated as dead. */
-	heartbeatTimeoutMs: 1e4,
-	poolSize: 1,
-	maxGenerations: 8,
-	maxGenerationsMb: 100,
-	maxSnapshotMb: 50
-};
-function positiveNumber(value) {
-	const parsed = Number(value);
-	return value && Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
-}
-/**
-* How many generations an agent keeps and how large they may get, read from
-* `KUBB_AGENT_MAX_GENERATIONS`, `KUBB_AGENT_MAX_GENERATIONS_MB` and `KUBB_AGENT_MAX_SNAPSHOT_MB`.
-* An unset or invalid value keeps the default.
-*/
-function resolveGenerationLimits(env = process.env) {
-	return {
-		maxCount: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS) ?? agentDefaults.maxGenerations)),
-		maxMb: positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS_MB) ?? agentDefaults.maxGenerationsMb,
-		maxSnapshotMb: positiveNumber(env.KUBB_AGENT_MAX_SNAPSHOT_MB) ?? agentDefaults.maxSnapshotMb
-	};
-}
-//#endregion
+import { x } from "tinyexec";
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -388,7 +344,10 @@ function getElapsedMs(hrStart) {
 	return Math.round(ms * 100) / 100;
 }
 //#endregion
-//#region src/machine.ts
+//#region package.json
+var version = "5.3.18";
+//#endregion
+//#region src/operations/machine.ts
 /**
 * Key-value storage the runtime uses for its machine secret and the last Studio config.
 *
@@ -448,7 +407,7 @@ async function getMachineToken() {
 	return machineTokenFrom(await fallbackSecretPromise);
 }
 //#endregion
-//#region src/api.ts
+//#region src/operations/api.ts
 /**
 * Reads a human-readable message from a Studio JSON error body, when it has one. `FetchError`'s own
 * message stops at the status line, so the detail Studio sends with a failure (an agent limit, a
@@ -468,10 +427,6 @@ function responseMessage(data) {
 */
 const REGISTER_RETRIES = 3;
 /**
-* Shared in-flight registration so concurrent pool sessions trigger one purge, not N.
-*/
-let registrationInFlight = null;
-/**
 * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
 * revoked, or the agent it belonged to was deleted in the Studio UI. Hosts catch this to forget
 * the stored credential and pair again.
@@ -483,117 +438,87 @@ var InvalidAgentTokenError = class extends Error {
 	}
 };
 /**
+* Thrown when Studio refuses this agent's protocol version (426). Retrying cannot help until the
+* agent is upgraded, so hosts stop instead of reconnecting.
+*/
+var IncompatibleAgentError = class extends Error {
+	constructor(studioUrl, detail, options) {
+		super(`Kubb Studio at ${studioUrl} requires a newer agent${detail ? `: ${detail}` : ""}. Upgrade @kubb/studio or the Kubb agent image.`, options);
+		this.name = "IncompatibleAgentError";
+	}
+};
+/**
 * Whether a thrown value carries `statusCode`. Not narrowed to `FetchError`: a host wrapper can
 * throw its own error shape with the same field.
-*
-* A 401 means the agent token itself was rejected. A 403 from the session create endpoint means
-* the machine token stored in Studio no longer matches this agent (missing or mismatched).
 */
 function rejectedWith(error, statusCode) {
 	return error?.statusCode === statusCode;
 }
-function sessionError(cause) {
+function registrationError(cause) {
 	const detail = (cause instanceof FetchError ? responseMessage(cause.data) : void 0) ?? getErrorMessage(cause);
-	return new Error(detail ? `Failed to get agent session from Kubb Studio: ${detail}` : "Failed to get agent session from Kubb Studio", { cause });
-}
-/**
-* Performs the raw session create request against Studio.
-*/
-async function requestAgentSession({ token, studioUrl }) {
-	const url = `${studioUrl}/api/agent/sessions`;
-	const data = await ofetch(url, {
-		method: "POST",
-		headers: { Authorization: `Bearer ${token}` },
-		body: { machineToken: await getMachineToken() }
-	});
-	if (!data) throw new Error("No data available for agent session");
-	return data;
-}
-/**
-* Obtain an agent session token from Kubb Studio via HTTP.
-*
-* When Studio rejects the machine token (403), for example after the agent restarted
-* with a new identity while the startup registration call failed, the agent re-registers
-* and retries once, so a single failed registration can't permanently block session creation.
-*/
-async function createAgentSession({ token, studioUrl }) {
-	try {
-		return await requestAgentSession({
-			token,
-			studioUrl
-		});
-	} catch (error) {
-		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		if (!rejectedWith(error, 403) || !await registerAgent({
-			token,
-			studioUrl
-		})) throw sessionError(error);
-		try {
-			return await requestAgentSession({
-				token,
-				studioUrl
-			});
-		} catch (retryError) {
-			if (rejectedWith(retryError, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: retryError });
-			throw sessionError(retryError);
-		}
-	}
+	return new Error(detail ? `Failed to register with Kubb Studio: ${detail}` : "Failed to register with Kubb Studio", { cause });
 }
 /**
-* Register this agent with Kubb Studio by sending the machine ID.
-* Called on agent startup before creating a WebSocket session, and again when
-* Studio rejects the machine token during session creation.
+* Registers this agent process with Kubb Studio (`POST /api/agent/connect`): binds the machine
+* identity to the token, reports what the process can take on, and gets back the URL of the one
+* socket it keeps open.
 *
-* Retries with backoff because a failed registration leaves Studio with a stale
-* machine token that blocks every subsequent session create call. Registration
-* purges all of the agent's sessions on the Studio side, so concurrent callers
-* (multiple pool sessions hitting a 403 at once) share one in-flight run instead
-* of purging each other's fresh sessions.
-*/
-function registerAgent(props) {
-	registrationInFlight ??= runRegistration(props).finally(() => {
-		registrationInFlight = null;
-	});
-	return registrationInFlight;
-}
-async function runRegistration({ token, studioUrl, poolSize }) {
-	const machineToken = await getMachineToken();
+* Retries a transient failure with backoff. A rejected token (401) throws
+* {@link InvalidAgentTokenError} and an unsupported agent version (426) throws
+* {@link IncompatibleAgentError}, since retrying either cannot help.
+*/
+async function registerAgent({ token, studioUrl, instanceId, capacity }) {
+	const body = {
+		machineToken: await getMachineToken(),
+		instanceId,
+		capacity
+	};
 	try {
-		await ofetch(`${studioUrl}/api/agent/connect`, {
+		return await ofetch(`${studioUrl}/api/agent/connect`, {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` },
-			body: {
-				machineToken,
-				poolSize
-			},
+			body,
 			retry: REGISTER_RETRIES,
 			retryDelay: ({ options }) => 2e3 * 2 ** (REGISTER_RETRIES - Number(options.retry))
 		});
-		return true;
 	} catch (error) {
 		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		return false;
+		if (rejectedWith(error, 426)) throw new IncompatibleAgentError(studioUrl, error instanceof FetchError ? responseMessage(error.data) : void 0, { cause: error });
+		throw registrationError(error);
 	}
 }
 /**
-* Notify Kubb Studio that this agent is disconnecting.
-* Called on process termination or server close. Never throws: the local socket is already gone,
-* and failing teardown must not block shutdown or reconnect.
-*
-* @returns `false` when Studio could not be reached or rate limited the call. Any other 4xx
-* counts as notified, since it means Studio already dropped the session.
+* First wait before `createJob` retries a busy or queue-full response, absent a `Retry-After` hint.
 */
-async function disconnect({ sessionId, token, studioUrl }) {
-	try {
-		await ofetch(`${studioUrl}/api/agent/sessions/${sessionId}/disconnect`, {
-			method: "POST",
-			headers: { Authorization: `Bearer ${token}` }
-		});
-		return true;
-	} catch (error) {
-		const statusCode = error?.statusCode;
-		return statusCode !== void 0 && statusCode !== 429 && statusCode >= 400 && statusCode < 500;
-	}
+const CREATE_JOB_INITIAL_DELAY_MS = 1e3;
+/**
+* Slowest `createJob` backs off to between retries.
+*/
+const CREATE_JOB_MAX_INTERVAL_MS = 1e4;
+/**
+* Statuses worth retrying: the agent has no free connection yet (409, a stale conflict a moment
+* later resolves), its queue is momentarily full (429), or it has no live connection at all yet
+* (503, an agent process that is mid-reconnect). Anything else (404 agent not found, 401/403 auth)
+* is thrown straight away, since retrying cannot change the outcome.
+*/
+const CREATE_JOB_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	409,
+	429,
+	503
+]);
+/**
+* Reads Studio's `Retry-After` header (seconds) off a thrown `ofetch` error, when present.
+*/
+function retryAfterMs(error) {
+	const seconds = Number(error.response?.headers.get("retry-after"));
+	return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+}
+/**
+* Adds up to 30% jitter, so every CI run queued behind the same busy agent does not retry in
+* lockstep.
+*/
+function withJitter(ms) {
+	return ms + Math.random() * ms * .3;
 }
 /**
 * Queues a generation or snapshot job on Studio (`POST /api/jobs`).
@@ -601,6 +526,10 @@ async function disconnect({ sessionId, token, studioUrl }) {
 * Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
 * Authenticates with the organization CI API key via `x-api-key`.
 *
+* A busy agent, a full queue, or a momentary lack of a live connection (409, 429, 503) retries with
+* exponential backoff and jitter, honoring Studio's `Retry-After` header when it sends one, up to
+* `timeoutMs`. Every other failure, including a missing agent (404), throws immediately.
+*
 * @example Snapshot job
 * ```ts
 * const job = await createJob({
@@ -614,20 +543,41 @@ async function disconnect({ sessionId, token, studioUrl }) {
 * const finished = await waitForJob({ studioUrl, token, id: job.id })
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, commit, config }) {
-	const { job } = await ofetch(`${studioUrl}/api/jobs`, {
-		method: "POST",
-		headers: { "x-api-key": token },
-		body: {
-			type,
-			agentId,
-			name,
-			version,
-			commit,
-			config
+async function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, instanceId, timeoutMs = 6e4, signal }) {
+	const deadline = Date.now() + timeoutMs;
+	let interval = CREATE_JOB_INITIAL_DELAY_MS;
+	for (;;) {
+		signal?.throwIfAborted();
+		try {
+			const { job } = await ofetch(`${studioUrl}/api/jobs`, {
+				method: "POST",
+				headers: { "x-api-key": token },
+				body: {
+					type,
+					agentId,
+					name,
+					version,
+					commit,
+					baseId,
+					config,
+					instanceId
+				},
+				retry: false,
+				timeout: Math.max(deadline - Date.now(), 1),
+				signal
+			});
+			return job;
+		} catch (error) {
+			signal?.throwIfAborted();
+			const status = error.response?.status;
+			if (!status || !CREATE_JOB_RETRYABLE_STATUSES.has(status) || Date.now() >= deadline) throw error;
+			const wait = Math.min(retryAfterMs(error) ?? withJitter(interval), Math.max(deadline - Date.now(), 0));
+			if (signal) await setTimeout$1(wait, void 0, { signal });
+			else await new Promise((resolve) => setTimeout(resolve, wait));
+			if (Date.now() >= deadline) throw error;
+			interval = Math.min(interval * 2, CREATE_JOB_MAX_INTERVAL_MS);
 		}
-	});
-	return job;
+	}
 }
 /**
 * A job runs a generation and packs a tarball, so it is never done the instant it is queued.
@@ -646,20 +596,26 @@ const MAX_POLL_INTERVAL_MS = 3e4;
 * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
 * deadline passes before Studio finishes.
 */
-async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4 }) {
+async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4, signal }) {
 	const deadline = Date.now() + timeoutMs;
 	let interval = INITIAL_POLL_DELAY_MS;
 	for (;;) {
-		await new Promise((resolve) => setTimeout(resolve, Math.max(Math.min(interval, deadline - Date.now()), 0)));
+		signal?.throwIfAborted();
+		const wait = Math.max(Math.min(interval, deadline - Date.now()), 0);
+		if (signal) await setTimeout$1(wait, void 0, { signal });
+		else await new Promise((resolve) => setTimeout(resolve, wait));
 		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
 		interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
 		try {
 			const { job } = await ofetch(`${studioUrl}/api/jobs/${id}`, {
 				headers: { "x-api-key": token },
-				retry: false
+				retry: false,
+				timeout: Math.max(deadline - Date.now(), 1),
+				signal
 			});
 			if (job.status === "success" || job.status === "failed" || job.status === "canceled") return job;
 		} catch (error) {
+			signal?.throwIfAborted();
 			const response = error.response;
 			if (response?.status !== 429) throw error;
 			const retryAfter = response._data?.data?.tryAgainIn;
@@ -693,90 +649,7 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 	}
 }
 //#endregion
-//#region package.json
-var version = "5.3.16";
-//#endregion
-//#region src/hooks.ts
-/**
-* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
-* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
-* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
-*
-* Returns a remover, so a session that runs one generation after another on the same emitter does
-* not stack a listener per run.
-*/
-function setupHookListener(hooks, root, signal) {
-	return hooks.hook("kubb:hook:start", async (ctx) => {
-		const { id, command, args } = ctx;
-		if (!id) return;
-		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
-		try {
-			const proc = x(command, [...args ?? []], {
-				signal,
-				nodeOptions: {
-					cwd: root,
-					detached: true
-				}
-			});
-			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
-				id,
-				line
-			});
-			const { exitCode } = await proc;
-			if (exitCode !== 0) {
-				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-				await hooks.callHook("kubb:hook:end", {
-					id,
-					command,
-					args,
-					success: false,
-					error
-				});
-				await hooks.callHook("kubb:error", { error });
-				return;
-			}
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: true,
-				error: null
-			});
-		} catch (caughtError) {
-			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-			error.cause = caughtError;
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: false,
-				error
-			});
-			await hooks.callHook("kubb:error", { error });
-		}
-	});
-}
-/**
-* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
-* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
-* that same listener, so a handler added afterward would already have missed it.
-*/
-function waitForHookEnd(hooks, hookId) {
-	return new Promise((resolve, reject) => {
-		const handleHookEnd = (ctx) => {
-			if (ctx.id !== hookId) return;
-			hooks.removeHook("kubb:hook:end", handleHookEnd);
-			if (ctx.success) {
-				resolve();
-				return;
-			}
-			reject(ctx.error);
-		};
-		hooks.hook("kubb:hook:end", handleHookEnd);
-	});
-}
-//#endregion
-//#region src/resolveConfig.ts
+//#region src/operations/resolveConfig.ts
 /**
 * Imports a package, falling back to how the user's project would resolve it.
 *
@@ -934,7 +807,7 @@ async function mergeAdapter(diskAdapter, studioOptions) {
 	return factory(mergeDeep(diskAdapter.options ?? {}, studioOptions));
 }
 //#endregion
-//#region src/configFile.ts
+//#region src/operations/configFile.ts
 /**
 * A valid JavaScript identifier, so an import name can only ever print as `import { name } from`,
 * never as source that breaks out of the import statement.
@@ -1474,6 +1347,11 @@ function applyConfigEdits(source, edits) {
 		changed: current !== source
 	};
 }
+async function writeConfigEdits({ filePath, edits }) {
+	const result = applyConfigEdits(await read(filePath), edits);
+	if (result.changed) await writeFile(filePath, result.source, "utf-8");
+	return result;
+}
 /**
 * The 1-based line where the file's last import declaration ends, or `0` when it has none. Read
 * off the parsed module, so a multi-line `import {\n  x,\n} from '...'` reports its closing line
@@ -1506,145 +1384,60 @@ function withTrailingNewline(code, hadTrailingNewline) {
 	return `${code}\n`;
 }
 //#endregion
-//#region src/generate.ts
-/**
-* `isToolAvailable` spawns a process, and a long-lived connection generates repeatedly, so each
-* executable is probed once per process. The CLI deliberately does not memoize: a `--watch` build
-* should keep noticing a tool installed mid-session.
-*/
-const detectTool = memoize(/* @__PURE__ */ new Map(), detectTool$1);
+//#region src/operations/constants.ts
 /**
-* The two post-build tool steps. Formatting and linting differ only in which tools they look for,
-* so they run through one loop rather than two near-identical blocks.
-*
-* `noun` and `verbing` are spelled out instead of built from `kind`. Concatenating `` `${kind}ter` ``
-* and `` `${kind}ting` `` works for `format`, but doubles the `t` in `lint`, giving "lintter" and
-* "lintting" instead of "linter" and "linting".
+* Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
+* not whatever default the client would pick on its own.
 */
-const TOOL_STEPS = [{
-	kind: "format",
-	noun: "formatter",
-	verbing: "Formatting",
-	tools: formatters,
-	detect: FORMATTER_PREFERENCE
-}, {
-	kind: "lint",
-	noun: "linter",
-	verbing: "Linting",
-	tools: linters,
-	detect: LINTER_PREFERENCE
-}];
+const defaultStudioUrl = "https://kubb.studio";
 /**
-* Absolute path of the directory the formatter and linter are pointed at.
+* Defaults the Studio client uses when a host passes nothing.
+* Config path is left out on purpose: each host discovers that itself.
 */
-function outputPath(config) {
-	return path.isAbsolute(config.output.path) ? config.output.path : path.resolve(process$1.cwd(), config.root, config.output.path);
+const agentDefaults = {
+	studioUrl: defaultStudioUrl,
+	retryIntervalMs: 3e4,
+	heartbeatIntervalMs: 3e4,
+	/**
+	* Slowest heartbeat a host may ask for. Studio drops an agent from the active list once its
+	* stored ping is older than its liveness window, and it stores a ping at most once a minute, so
+	* a slower cadence would make a healthy agent look dead after a single missed ping.
+	*/
+	maxHeartbeatIntervalMs: 6e4,
+	/** How long a heartbeat ping may take before the session is treated as dead. */
+	heartbeatTimeoutMs: 1e4,
+	maxConcurrent: 1,
+	maxGenerations: 8,
+	maxGenerationsMb: 100,
+	maxSnapshotMb: 50
+};
+function positiveNumber(value) {
+	const parsed = Number(value);
+	return value && Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
 }
 /**
-* Emits `kubb:hook:start` and waits for the matching `kubb:hook:end`. The host spawns the process:
-* this only describes what to run and when it finished.
-*
-* @throws whatever the command failed with, so callers can report it their own way.
-*/
-async function runHook({ hooks, id, command, args }) {
-	const hookId = hash("sha256", id);
-	const hookEnd = waitForHookEnd(hooks, hookId);
-	await hooks.callHook("kubb:hook:start", {
-		id: hookId,
-		command,
-		args: [...args]
-	});
-	await hookEnd;
-}
-function isProblemErrorDiagnostic(diagnostic) {
-	return (diagnostic.kind ?? "problem") === "problem" && diagnostic.severity === "error";
-}
-/**
-* Folds error-severity diagnostics into one thrown error so logs name the failing plugin.
+* How many generations an agent keeps and how large they may get, read from
+* `KUBB_AGENT_MAX_GENERATIONS`, `KUBB_AGENT_MAX_GENERATIONS_MB` and `KUBB_AGENT_MAX_SNAPSHOT_MB`.
+* An unset or invalid value keeps the default.
 */
-function formatGenerationFailure(diagnostics) {
-	const reasons = diagnostics.filter(isProblemErrorDiagnostic).map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
-	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
-	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
+function resolveGenerationLimits(env = process.env) {
+	return {
+		maxCount: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS) ?? agentDefaults.maxGenerations)),
+		maxMb: positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS_MB) ?? agentDefaults.maxGenerationsMb,
+		maxSnapshotMb: positiveNumber(env.KUBB_AGENT_MAX_SNAPSHOT_MB) ?? agentDefaults.maxSnapshotMb
+	};
 }
 /**
-* Runs a full Kubb code-generation cycle for the given config.
-*
-* Emits lifecycle events on the provided `hooks` emitter so callers (e.g. the WebSocket stream)
-* can forward progress to connected clients. After a successful build, auto-formatting and
-* linting are applied when configured, followed by any user-defined `hooks.done` commands.
+* An agent's capacity read from `KUBB_AGENT_MAX_CONCURRENT`. An unset or invalid value keeps the
+* default: one job at a time.
 */
-async function generate({ config, hooks, signal }) {
-	signal?.throwIfAborted();
-	const hrStart = process$1.hrtime();
-	await hooks.callHook("kubb:generation:start", { config });
-	await hooks.callHook("kubb:info", { message: config.name ? `Setup generation ${config.name}` : "Setup generation" });
-	const kubb = createKubb(config, {
-		hooks,
-		signal
-	});
-	await kubb.setup();
-	await hooks.callHook("kubb:info", { message: config.name ? `Build generation ${config.name}` : "Build generation" });
-	const { files, diagnostics, storage } = await kubb.safeBuild();
-	signal?.throwIfAborted();
-	await hooks.callHook("kubb:info", { message: "Load summary" });
-	for (const diagnostic of diagnostics.filter(isProblemErrorDiagnostic)) await hooks.callHook("kubb:error", { error: new Error(diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message) });
-	const status = Diagnostics.hasError(diagnostics) ? "failed" : "success";
-	await hooks.callHook("kubb:generation:end", {
-		config,
-		storage: {
-			...storage,
-			readKeys: async () => [...new Set(files.map((file) => file.path))]
-		},
-		diagnostics,
-		status,
-		hrStart,
-		filesCreated: files.length
-	});
-	if (status === "failed") throw formatGenerationFailure(diagnostics);
-	await hooks.callHook("kubb:success", { message: "Generation successfully" });
-	for (const step of TOOL_STEPS) {
-		const setting = config.output[step.kind];
-		if (!setting) continue;
-		await hooks.callHook(`kubb:${step.kind}:start`);
-		const tool = setting === "auto" ? await detectTool(step.detect) : setting;
-		if (!tool) await hooks.callHook("kubb:warn", { message: `No ${step.noun} found (${step.detect.join(", ")}). Skipping ${step.verbing.toLowerCase()}.` });
-		if (tool && setting === "auto") await hooks.callHook("kubb:info", { message: `Auto-detected ${step.noun}: ${styleText("dim", tool)}` });
-		const command = tool ? step.tools[tool] : void 0;
-		if (command) try {
-			await runHook({
-				hooks,
-				id: [config.name, tool].filter(Boolean).join("-"),
-				command: command.command,
-				args: command.args(outputPath(config))
-			});
-			await hooks.callHook("kubb:success", { message: `${step.verbing} with ${tool} successfully` });
-		} catch (caughtError) {
-			await hooks.callHook("kubb:error", { error: new Error(command.errorMessage, { cause: caughtError }) });
-			signal?.throwIfAborted();
-		}
-		await hooks.callHook(`kubb:${step.kind}:end`);
-	}
-	if (config.output.postGenerate?.length) {
-		await hooks.callHook("kubb:hooks:start");
-		for (const entry of config.output.postGenerate) {
-			const line = typeof entry === "string" ? entry : entry.command;
-			const [cmd, ...args] = tokenize(line);
-			if (!cmd) continue;
-			await runHook({
-				hooks,
-				id: line,
-				command: cmd,
-				args
-			});
-			await hooks.callHook("kubb:success", { message: `${line} successfully executed` });
-		}
-		await hooks.callHook("kubb:hooks:end");
-	}
+function resolveAgentCapacity(env = process.env) {
+	return { maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)) };
 }
 //#endregion
-//#region src/snapshotPackage.ts
+//#region src/operations/snapshotPackage.ts
 const gzipAsync = promisify(gzip);
+const UPLOAD_TIMEOUT_MS = 12e4;
 /**
 * Maps a generated file's path to its place inside the tarball, stripping everything before a
 * `src`/`dist` segment and any `..`/empty path segment so a crafted file name cannot escape the
@@ -1782,10 +1575,33 @@ async function createSnapshotPackage(files, packageInfo) {
 		});
 	}
 }
+async function uploadSnapshot({ bytes, uploadPath, studioUrl, token, shutdown }) {
+	const uploadUrl = new URL(uploadPath, studioUrl);
+	if (uploadUrl.origin !== new URL(studioUrl).origin) throw new Error("Snapshot upload path must stay on the Studio origin");
+	const timeout = AbortSignal.timeout(UPLOAD_TIMEOUT_MS);
+	const signal = shutdown ? AbortSignal.any([shutdown, timeout]) : timeout;
+	const redirect = await fetch(uploadUrl, {
+		method: "PUT",
+		headers: { Authorization: `Bearer ${token}` },
+		redirect: "manual",
+		signal
+	});
+	const storageUrl = redirect.headers.get("location");
+	if (redirect.status !== 307 || !storageUrl) throw new Error(`Studio did not provide a storage URL (status ${redirect.status})`);
+	const storage = new URL(storageUrl);
+	if (storage.protocol !== "https:" && storage.hostname !== "localhost" && storage.hostname !== "127.0.0.1") throw new Error(`Refusing snapshot upload to ${storage.origin}`);
+	const response = await fetch(storage, {
+		method: "PUT",
+		body: new Uint8Array(bytes),
+		redirect: "error",
+		signal
+	});
+	if (!response.ok) throw new Error(`Snapshot upload failed with status ${response.status}`);
+}
 //#endregion
-//#region src/generations.ts
+//#region src/operations/generations.ts
 const READ_CONCURRENCY = 50;
-const MB = 1048576;
+const MB$1 = 1048576;
 const INDEX_KEY = "studio/generations.json";
 const hashOf = (content) => createHash("sha1").update(content).digest("hex").slice(0, 16);
 /**
@@ -1812,8 +1628,9 @@ async function listDisk({ root, outputPath, maxFiles }) {
 * tenant never reaches another's output. The oldest go past `maxCount` or `maxMb`, but the newest
 * always stays.
 */
-function createGenerationStore({ storage, maxCount, maxMb }) {
+function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now }) {
 	let index;
+	const isLive = (generation) => ttlMs === void 0 || generation.keptAt === void 0 || now() - generation.keptAt < ttlMs;
 	const dirOf = (jobId) => `studio/generations/${hashOf(jobId)}/`;
 	async function load() {
 		if (index) return index;
@@ -1829,7 +1646,7 @@ function createGenerationStore({ storage, maxCount, maxMb }) {
 	* Copies `files` into the store as one set of `jobId`. Above `maxSetMb` only the hashes are kept.
 	*/
 	async function keep({ jobId, source, files, maxSetMb }) {
-		const maxSetBytes = maxSetMb * MB;
+		const maxSetBytes = maxSetMb * MB$1;
 		const hashes = {};
 		let bytes = 0;
 		await inParallel({
@@ -1864,13 +1681,20 @@ function createGenerationStore({ storage, maxCount, maxMb }) {
 	return {
 		keep,
 		drop,
-		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId),
-		latest: async () => (await load()).at(-1),
+		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId && isLive(generation)),
+		latest: async () => (await load()).filter(isLive).at(-1),
+		/** Total bytes of every set the store holds, expired ones too until the next add drops them. */
+		bytes: async () => (await load()).reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0),
 		async add(generation) {
-			const entries = (await load()).filter((entry) => entry.jobId !== generation.jobId);
-			entries.push(generation);
+			const current = await load();
+			for (const expired of current.filter((entry) => !isLive(entry))) await drop(expired.jobId);
+			const entries = current.filter((entry) => entry.jobId !== generation.jobId && isLive(entry));
+			entries.push({
+				...generation,
+				keptAt: now()
+			});
 			const weight = () => entries.reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0);
-			while (entries.length > 1 && (entries.length > maxCount || weight() > maxMb * MB)) await drop(entries.shift().jobId);
+			while (entries.length > 1 && (entries.length > maxCount || weight() > maxMb * MB$1)) await drop(entries.shift().jobId);
 			index = entries;
 			await storage.writeItem(INDEX_KEY, JSON.stringify(entries));
 		},
@@ -1893,12 +1717,7 @@ function createGenerationStore({ storage, maxCount, maxMb }) {
 	};
 }
 //#endregion
-//#region src/ws.ts
-/**
-* How long the initial handshake may take before the socket is closed and the reconnect loop
-* takes over.
-*/
-const CONNECT_TIMEOUT_MS = 5e3;
+//#region src/operations/generationEvents.ts
 const require = createRequire(import.meta.url);
 function relativeStoragePath(root, filePath) {
 	return (isAbsolute(filePath) ? relative(resolve(root), filePath) : filePath).replaceAll("\\", "/");
@@ -1928,27 +1747,24 @@ async function resolvePeerDependencies(names) {
 		missingDependencies
 	};
 }
-/**
-* Opens a Studio WebSocket connection and closes it when the initial handshake exceeds the configured timeout.
-*/
-function createWebsocket(url, options) {
-	const ws = new WebSocket(url, options);
-	const timer = setTimeout(() => {
-		if (ws.readyState === WebSocket.CONNECTING) ws.close(3008, "Connection timeout");
-	}, CONNECT_TIMEOUT_MS);
-	ws.once("open", () => clearTimeout(timer));
-	ws.once("close", () => clearTimeout(timer));
-	return ws;
-}
+const MAX_QUEUED_EVENTS = 1024;
+const RESERVED_EVENTS = 64;
+const isDiscardable = (event) => event.type === "kubb:files:processing:update" || event.type === "kubb:info" || event.type === "kubb:success";
 /** Forwards selected Kubb lifecycle events to a native Cap'n Web stream. */
 function createGenerationStream(hooks, jobId, options = {}) {
 	const unhooks = [];
 	let root = "";
-	const transform = new TransformStream(void 0, void 0, { highWaterMark: Infinity });
-	const writer = transform.writable.getWriter();
-	let writes = Promise.resolve();
+	let controller;
 	let closed = false;
-	let streamError;
+	const stream = new ReadableStream({
+		start: (value) => {
+			controller = value;
+		},
+		cancel: () => {
+			closed = true;
+			detach();
+		}
+	}, { highWaterMark: MAX_QUEUED_EVENTS });
 	/**
 	* Registers a listener and keeps its remover, so one generation's listeners come off the session
 	* emitter again when that generation ends.
@@ -1957,6 +1773,7 @@ function createGenerationStream(hooks, jobId, options = {}) {
 		unhooks.push(hooks.hook(name, handler));
 	}
 	function emitEvent(type, data) {
+		if (closed) return;
 		const event = {
 			jobId,
 			type,
@@ -1964,9 +1781,12 @@ function createGenerationStream(hooks, jobId, options = {}) {
 			version: 1,
 			timestamp: Date.now()
 		};
-		writes = writes.then(() => writer.write(event)).catch((error) => {
-			streamError = error;
-		});
+		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(event)) return;
+		if (controller.desiredSize <= 0) {
+			fail(/* @__PURE__ */ new Error(`Generation event stream exceeded ${MAX_QUEUED_EVENTS} queued events`));
+			return;
+		}
+		controller.enqueue(event);
 	}
 	on("kubb:plugin:start", (ctx) => {
 		emitEvent("kubb:plugin:start", [{ plugin: { name: ctx.plugin.name } }]);
@@ -2112,25 +1932,38 @@ function createGenerationStream(hooks, jobId, options = {}) {
 		if (closed) return;
 		closed = true;
 		detach();
-		await writes;
-		if (streamError) return;
-		await writer.close().catch(() => void 0);
+		controller.close();
 	}
 	function fail(error) {
 		detach();
 		if (closed) return;
 		closed = true;
-		writer.abort(error).catch(() => void 0);
+		controller.error(error);
 	}
 	return {
-		stream: transform.readable,
+		stream,
 		close,
 		dispose: () => fail(),
 		fail
 	};
 }
 //#endregion
-//#region src/rpc.ts
+//#region src/operations/websocket.ts
+const CONNECT_TIMEOUT_MS = 5e3;
+/**
+* Opens a Studio WebSocket connection and closes it when the initial handshake exceeds the configured timeout.
+*/
+function createWebsocket(url, options) {
+	const ws = new WebSocket(url, options);
+	const timer = setTimeout(() => {
+		if (ws.readyState === WebSocket.CONNECTING) ws.close(3008, "Connection timeout");
+	}, CONNECT_TIMEOUT_MS);
+	ws.once("open", () => clearTimeout(timer));
+	ws.once("close", () => clearTimeout(timer));
+	return ws;
+}
+//#endregion
+//#region src/operations/rpc.ts
 /**
 * The only methods Studio may call on an agent. A `StudioSession` carries far more than
 * {@link AgentApi}, so it is wrapped rather than exposed: what Cap'n Web can reach is exactly what
@@ -2157,6 +1990,9 @@ var AgentRpcTarget = class extends RpcTarget {
 	readFiles(input) {
 		return this.api.readFiles(input);
 	}
+	cancel(jobId) {
+		return this.api.cancel(jobId);
+	}
 };
 /**
 * Opens an authenticated Cap'n Web session to Studio over a WebSocket. Rejects an unencrypted URL
@@ -2168,11 +2004,17 @@ var AgentRpcTarget = class extends RpcTarget {
 * await rpc.studio.ping()
 * ```
 */
-const connectWebSocketRpc = async ({ url, token, local }) => {
+const connectWebSocketRpc = async ({ url, token, instanceId, local }) => {
 	const { protocol, hostname, host } = new URL(url);
 	if (protocol !== "wss:" && !(protocol === "ws:" && (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]"))) throw new Error(`Refusing unencrypted WebSocket to ${host}`);
-	const socket = createWebsocket(url, { headers: { Authorization: `Bearer ${token}` } });
-	const closed = new Promise((resolve) => socket.once("close", resolve));
+	const socket = createWebsocket(url, { headers: {
+		Authorization: `Bearer ${token}`,
+		[AGENT_INSTANCE_HEADER]: instanceId
+	} });
+	const closed = new Promise((resolve) => socket.once("close", (code, reason) => resolve({
+		code,
+		reason: reason.toString()
+	})));
 	const studio = newWebSocketRpcSession(socket, new AgentRpcTarget(local));
 	studio.onRpcBroken(() => socket.close());
 	return {
@@ -2182,11 +2024,274 @@ const connectWebSocketRpc = async ({ url, token, local }) => {
 	};
 };
 //#endregion
-//#region src/StudioSession.ts
+//#region src/operations/hooks.ts
 /**
-* Past this many files in the output directory, no snapshot of it is taken before a run.
+* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
+* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
+* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
+*
+* Returns a remover, so a session that runs one generation after another on the same emitter does
+* not stack a listener per run.
 */
+function setupHookListener(hooks, root, signal) {
+	return hooks.hook("kubb:hook:start", async (ctx) => {
+		const { id, command, args } = ctx;
+		if (!id) return;
+		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
+		try {
+			const proc = x(command, [...args ?? []], {
+				signal,
+				nodeOptions: {
+					cwd: root,
+					detached: true
+				}
+			});
+			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
+				id,
+				line
+			});
+			const { exitCode } = await proc;
+			if (exitCode !== 0) {
+				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+				await hooks.callHook("kubb:hook:end", {
+					id,
+					command,
+					args,
+					success: false,
+					error
+				});
+				await hooks.callHook("kubb:error", { error });
+				return;
+			}
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: true,
+				error: null
+			});
+		} catch (caughtError) {
+			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+			error.cause = caughtError;
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: false,
+				error
+			});
+			await hooks.callHook("kubb:error", { error });
+		}
+	});
+}
+/**
+* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
+* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
+* that same listener, so a handler added afterward would already have missed it.
+*/
+function waitForHookEnd(hooks, hookId) {
+	return new Promise((resolve, reject) => {
+		const handleHookEnd = (ctx) => {
+			if (ctx.id !== hookId) return;
+			hooks.removeHook("kubb:hook:end", handleHookEnd);
+			if (ctx.success) {
+				resolve();
+				return;
+			}
+			reject(ctx.error);
+		};
+		hooks.hook("kubb:hook:end", handleHookEnd);
+	});
+}
+//#endregion
+//#region src/operations/generate.ts
 const DISK_SNAPSHOT_MAX_FILES = 1e4;
+/**
+* `isToolAvailable` spawns a process, and a long-lived connection generates repeatedly, so each
+* executable is probed once per process. The CLI deliberately does not memoize: a `--watch` build
+* should keep noticing a tool installed mid-session.
+*/
+const detectTool = memoize(/* @__PURE__ */ new Map(), detectTool$1);
+/**
+* The two post-build tool steps. Formatting and linting differ only in which tools they look for,
+* so they run through one loop rather than two near-identical blocks.
+*
+* `noun` and `verbing` are spelled out instead of built from `kind`. Concatenating `` `${kind}ter` ``
+* and `` `${kind}ting` `` works for `format`, but doubles the `t` in `lint`, giving "lintter" and
+* "lintting" instead of "linter" and "linting".
+*/
+const TOOL_STEPS = [{
+	kind: "format",
+	noun: "formatter",
+	verbing: "Formatting",
+	tools: formatters,
+	detect: FORMATTER_PREFERENCE
+}, {
+	kind: "lint",
+	noun: "linter",
+	verbing: "Linting",
+	tools: linters,
+	detect: LINTER_PREFERENCE
+}];
+/**
+* Absolute path of the directory the formatter and linter are pointed at.
+*/
+function outputPath(config) {
+	return path.isAbsolute(config.output.path) ? config.output.path : path.resolve(process$1.cwd(), config.root, config.output.path);
+}
+/**
+* Emits `kubb:hook:start` and waits for the matching `kubb:hook:end`. The host spawns the process:
+* this only describes what to run and when it finished.
+*
+* @throws whatever the command failed with, so callers can report it their own way.
+*/
+async function runHook({ hooks, id, command, args }) {
+	const hookId = hash("sha256", id);
+	const hookEnd = waitForHookEnd(hooks, hookId);
+	await hooks.callHook("kubb:hook:start", {
+		id: hookId,
+		command,
+		args: [...args]
+	});
+	await hookEnd;
+}
+function isProblemErrorDiagnostic(diagnostic) {
+	return (diagnostic.kind ?? "problem") === "problem" && diagnostic.severity === "error";
+}
+/**
+* Folds error-severity diagnostics into one thrown error so logs name the failing plugin.
+*/
+function formatGenerationFailure(diagnostics) {
+	const reasons = diagnostics.filter(isProblemErrorDiagnostic).map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
+	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
+	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
+}
+/**
+* Runs a full Kubb code-generation cycle for the given config.
+*
+* Emits lifecycle events on the provided `hooks` emitter so callers (e.g. the WebSocket stream)
+* can forward progress to connected clients. After a successful build, auto-formatting and
+* linting are applied when configured, followed by any user-defined `hooks.done` commands.
+*/
+async function generate({ config, hooks, signal }) {
+	signal?.throwIfAborted();
+	const hrStart = process$1.hrtime();
+	await hooks.callHook("kubb:generation:start", { config });
+	await hooks.callHook("kubb:info", { message: config.name ? `Setup generation ${config.name}` : "Setup generation" });
+	const kubb = createKubb(config, {
+		hooks,
+		signal
+	});
+	await kubb.setup();
+	await hooks.callHook("kubb:info", { message: config.name ? `Build generation ${config.name}` : "Build generation" });
+	const { files, diagnostics, storage } = await kubb.safeBuild();
+	signal?.throwIfAborted();
+	await hooks.callHook("kubb:info", { message: "Load summary" });
+	for (const diagnostic of diagnostics.filter(isProblemErrorDiagnostic)) await hooks.callHook("kubb:error", { error: new Error(diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message) });
+	const status = Diagnostics.hasError(diagnostics) ? "failed" : "success";
+	await hooks.callHook("kubb:generation:end", {
+		config,
+		storage: {
+			...storage,
+			readKeys: async () => [...new Set(files.map((file) => file.path))]
+		},
+		diagnostics,
+		status,
+		hrStart,
+		filesCreated: files.length
+	});
+	if (status === "failed") throw formatGenerationFailure(diagnostics);
+	await hooks.callHook("kubb:success", { message: "Generation successfully" });
+	for (const step of TOOL_STEPS) {
+		const setting = config.output[step.kind];
+		if (!setting) continue;
+		await hooks.callHook(`kubb:${step.kind}:start`);
+		const tool = setting === "auto" ? await detectTool(step.detect) : setting;
+		if (!tool) await hooks.callHook("kubb:warn", { message: `No ${step.noun} found (${step.detect.join(", ")}). Skipping ${step.verbing.toLowerCase()}.` });
+		if (tool && setting === "auto") await hooks.callHook("kubb:info", { message: `Auto-detected ${step.noun}: ${styleText("dim", tool)}` });
+		const command = tool ? step.tools[tool] : void 0;
+		if (command) try {
+			await runHook({
+				hooks,
+				id: [config.name, tool].filter(Boolean).join("-"),
+				command: command.command,
+				args: command.args(outputPath(config))
+			});
+			await hooks.callHook("kubb:success", { message: `${step.verbing} with ${tool} successfully` });
+		} catch (caughtError) {
+			await hooks.callHook("kubb:error", { error: new Error(command.errorMessage, { cause: caughtError }) });
+			signal?.throwIfAborted();
+		}
+		await hooks.callHook(`kubb:${step.kind}:end`);
+	}
+	if (config.output.postGenerate?.length) {
+		await hooks.callHook("kubb:hooks:start");
+		for (const entry of config.output.postGenerate) {
+			const line = typeof entry === "string" ? entry : entry.command;
+			const [cmd, ...args] = tokenize(line);
+			if (!cmd) continue;
+			await runHook({
+				hooks,
+				id: line,
+				command: cmd,
+				args
+			});
+			await hooks.callHook("kubb:success", { message: `${line} successfully executed` });
+		}
+		await hooks.callHook("kubb:hooks:end");
+	}
+}
+async function runGenerationOperation({ config, hooks, signal, jobId, store, snapshotRoot, maxSnapshotMb }) {
+	const diskFiles = snapshotRoot ? await listDisk({
+		root: snapshotRoot,
+		outputPath: config.output.path,
+		maxFiles: DISK_SNAPSHOT_MAX_FILES
+	}) : void 0;
+	const disk = diskFiles ? await store.keep({
+		jobId,
+		source: "disk",
+		files: diskFiles,
+		maxSetMb: maxSnapshotMb
+	}) : void 0;
+	const removeHookListener = setupHookListener(hooks, config.root, signal);
+	try {
+		await generate({
+			config,
+			hooks,
+			signal
+		});
+	} catch (error) {
+		await store.drop(jobId);
+		throw error;
+	} finally {
+		removeHookListener();
+	}
+	return disk;
+}
+//#endregion
+//#region src/runtime/StudioSession.ts
+/** A sandbox shares one in-memory generation store across tenants, so old generations expire. */
+const SANDBOX_GENERATION_TTL_MS = 9e5;
+/**
+* A fresh root for one sandbox job. Kubb keys its output manifest cache by root, so tenants that
+* shared the agent's own root would read each other's manifest.
+*/
+function createJobRoot() {
+	return mkdtemp(path.join(tmpdir(), "kubb-job-"));
+}
+/**
+* Removes a job root and the manifest cache Kubb derived from it. Best effort: a leftover temp
+* directory must not fail a job that already finished.
+*/
+async function removeJobRoot(jobRoot) {
+	await Promise.all([rm(jobRoot, {
+		recursive: true,
+		force: true
+	}), rm(resolveCacheDir(jobRoot), {
+		recursive: true,
+		force: true
+	})]).catch(() => {});
+}
 var GenerationRunTarget = class extends RpcTarget {
 	generationStream;
 	generationResult;
@@ -2233,34 +2338,74 @@ function applyStudioDefaults(options) {
 			...options.permissions
 		},
 		retryInterval: options.retryInterval ?? agentDefaults.retryIntervalMs,
-		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs)
+		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs),
+		capacity: {
+			...resolveAgentCapacity(),
+			...options.capacity
+		},
+		instanceId: options.instanceId ?? randomUUID()
 	};
 }
 /**
-* Schedules another connection attempt.
-*
-* A free function rather than a method: a pending retry timer reaches whatever it closes over, so
-* closing only over `options` (not a `StudioSession`) keeps a queued retry from pinning a closed
-* socket, its hook emitter, or its session id alive for the length of the retry interval.
+* Jobs one agent process can run at once today. Two runs would share this session's hook emitter,
+* and with it each other's events, until each job runs in its own worker (ADR-0003 slice B2).
 */
-function reconnect(options) {
-	const { signal, retryInterval, onTokenRejected } = options;
+const RUNTIME_MAX_CONCURRENT = 1;
+const MB = 1048576;
+function rssMb() {
+	return process$1.memoryUsage().rss / MB;
+}
+function backoffDelayMs(attempt, maxMs) {
+	const cap = Math.min(1e3 * 2 ** (attempt - 1), maxMs);
+	return Math.random() * cap;
+}
+function reconnect(options, delayMs, attempt) {
+	const { signal, onTokenRejected } = options;
 	if (signal?.aborted) return;
 	const cancel = () => clearTimeout(timer);
 	const timer = setTimeout(() => {
 		signal?.removeEventListener("abort", cancel);
 		if (signal?.aborted) return;
-		new StudioSession(options).start().catch((error) => {
+		new StudioSession({
+			...options,
+			reconnectAttempt: attempt
+		}).start().catch((error) => {
 			if (error instanceof InvalidAgentTokenError) {
 				onTokenRejected?.(error);
 				return;
 			}
-			reconnect(options);
+			if (error instanceof IncompatibleAgentError) return;
+			const nextAttempt = attempt + 1;
+			reconnect(options, backoffDelayMs(nextAttempt, options.retryInterval), nextAttempt);
 		});
-	}, retryInterval);
+	}, delayMs);
 	signal?.addEventListener("abort", cancel, { once: true });
 }
 /**
+* Reads what Studio meant by closing the connection. A code Studio did not send on purpose is an
+* ordinary drop, and the agent reconnects as it always has.
+*/
+function planEnd(close) {
+	const code = close?.code;
+	if (code === AgentCloseCode.REAUTHENTICATE) return {
+		reason: "Kubb Studio asked the agent to register again",
+		retry: true
+	};
+	if (code === AgentCloseCode.SUPERSEDED) return {
+		reason: "another instance of this agent took over",
+		retry: false
+	};
+	if (code === AgentCloseCode.INCOMPATIBLE) return {
+		reason: "this agent is too old for Kubb Studio, or was deleted",
+		retry: false,
+		error: /* @__PURE__ */ new Error("Kubb Studio closed the connection: this agent is too old for it, or was deleted. Upgrade the agent, or pair it again.")
+	};
+	return {
+		reason: "connection closed",
+		retry: true
+	};
+}
+/**
 * One agent-to-Studio RPC transport: opening it, keeping it alive, and serving remote methods.
 * `createClient` opens one per pool slot and is the only caller.
 */
@@ -2273,14 +2418,15 @@ var StudioSession = class {
 	*/
 	#unhooks = [];
 	/**
-	* What `createAgentSession` handed back, and the marker for whether a session exists at all.
-	* Before it resolves there is nothing to disconnect and no sandbox flag to read.
+	* What registration handed back, and the marker for whether the agent registered at all.
+	* Before it resolves there is no sandbox flag to read.
 	*/
-	#session;
+	#registration;
 	#rpc;
 	#studioVersion;
 	#disposed = false;
 	#isGenerating = false;
+	#activeJob;
 	#heartbeatTimer;
 	#lastGeneration;
 	#store;
@@ -2290,17 +2436,17 @@ var StudioSession = class {
 	* host does not queue jobs before the agent session is registered.
 	*/
 	#connectAck = Promise.withResolvers();
-	#startupWarning;
-	constructor({ startupWarning, ...options }) {
+	#reconnectAttempt;
+	constructor({ reconnectAttempt, ...options }) {
 		this.#options = applyStudioDefaults(options);
-		this.#startupWarning = startupWarning;
+		this.#reconnectAttempt = reconnectAttempt ?? 0;
 		this.#connectAck.promise.catch(() => {});
 	}
 	/**
 	* A sandbox agent runs on Studio's own infrastructure, so it has no user project to touch.
 	*/
 	get #isSandbox() {
-		return this.#session?.isSandbox === true;
+		return this.#registration?.isSandbox === true;
 	}
 	/**
 	* Kept in the project's cache directory, so it survives a restart, except on a sandbox: its pool
@@ -2310,7 +2456,8 @@ var StudioSession = class {
 		this.#store ??= createGenerationStore({
 			storage: this.#isSandbox ? memoryStorage() : cacheStorage({ root: this.#options.root }),
 			maxCount: this.#limits.maxCount,
-			maxMb: this.#limits.maxMb
+			maxMb: this.#limits.maxMb,
+			ttlMs: this.#isSandbox ? SANDBOX_GENERATION_TTL_MS : void 0
 		});
 		return this.#store;
 	}
@@ -2334,20 +2481,26 @@ var StudioSession = class {
 		return this.#isSandbox || this.#options.permissions.allowRead;
 	}
 	async start() {
-		const { token, studioUrl, signal, heartbeatInterval, installLogger } = this.#options;
+		const { token, studioUrl, signal, heartbeatInterval, installLogger, instanceId, capacity } = this.#options;
 		await installLogger?.(this.#hooks);
-		if (this.#startupWarning) await this.#warn(this.#startupWarning);
 		try {
 			await this.#hooks.callHook("studio:connecting", { url: studioUrl });
-			const session = await createAgentSession({
+			if (this.#reconnectAttempt === 0 && capacity.maxConcurrent > RUNTIME_MAX_CONCURRENT) await this.#warn(`Running ${RUNTIME_MAX_CONCURRENT} job at a time: KUBB_AGENT_MAX_CONCURRENT=${capacity.maxConcurrent} needs per-job workers, which this agent does not have yet`);
+			const registration = await registerAgent({
 				token,
-				studioUrl
+				studioUrl,
+				instanceId,
+				capacity: {
+					...capacity,
+					maxConcurrent: Math.min(capacity.maxConcurrent, RUNTIME_MAX_CONCURRENT)
+				}
 			});
-			this.#session = session;
-			this.#studioVersion = session.version;
+			this.#registration = registration;
+			this.#studioVersion = registration.version;
 			const rpc = await (this.#options.connector ?? connectWebSocketRpc)({
-				url: session.url,
+				url: registration.socketUrl,
 				token,
+				instanceId,
 				local: this
 			});
 			this.#rpc = rpc;
@@ -2362,16 +2515,17 @@ var StudioSession = class {
 					kubb: version,
 					agent: this.#options.version
 				},
-				agentSlug: session.agentSlug,
-				organizationSlug: session.organizationSlug
+				agentSlug: registration.agentSlug,
+				organizationSlug: registration.organizationSlug
 			});
 			await this.#connectAck.promise;
+			this.#reconnectAttempt = 0;
 			await this.#hooks.callHook("studio:ready", {});
 		} catch (error) {
 			this.#disposed = true;
 			this.dispose();
 			await this.#hooks.callHook("studio:error", { error: toError(error) });
-			if (error instanceof InvalidAgentTokenError) throw error;
+			if (error instanceof InvalidAgentTokenError || error instanceof IncompatibleAgentError) throw error;
 			await this.#reconnect();
 		}
 	}
@@ -2381,8 +2535,10 @@ var StudioSession = class {
 	*/
 	async #reconnect() {
 		if (this.#options.signal?.aborted) return;
-		await this.#hooks.callHook("studio:reconnecting", { delayMs: this.#options.retryInterval });
-		reconnect(this.#options);
+		const attempt = this.#reconnectAttempt + 1;
+		const delayMs = backoffDelayMs(attempt, this.#options.retryInterval);
+		await this.#hooks.callHook("studio:reconnecting", { delayMs });
+		reconnect(this.#options, delayMs, attempt);
 	}
 	#warn(message, permission) {
 		return this.#hooks.callHook("studio:warn", {
@@ -2414,10 +2570,23 @@ var StudioSession = class {
 	/**
 	* Races `studio.ping()` against a deadline, so a half-open socket can't hang it forever.
 	* */
-	#ping(rpc) {
+	async #ping(rpc) {
 		const { promise: timedOut, reject: onTimeout } = Promise.withResolvers();
 		const timer = setTimeout(() => onTimeout(/* @__PURE__ */ new Error("Heartbeat ping timed out")), agentDefaults.heartbeatTimeoutMs);
-		return Promise.race([rpc.studio.ping(), timedOut]).finally(() => clearTimeout(timer));
+		try {
+			const load = await Promise.race([this.#load().catch(() => void 0), timedOut]);
+			await Promise.race([rpc.studio.ping(load), timedOut]);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	async #load() {
+		return {
+			running: this.#isGenerating ? 1 : 0,
+			rssMb: Math.round(rssMb()),
+			storeBytes: await this.#generations.bytes(),
+			accepting: true
+		};
 	}
 	/**
 	* Reads `kubb.config.ts` and reports which plugin options Studio may edit.
@@ -2462,8 +2631,11 @@ var StudioSession = class {
 		this.#connectAck.resolve();
 		return payload;
 	}
-	#onAbort = () => void this.#end({ retry: false });
-	#onClose = () => void this.#end({ retry: true });
+	#onAbort = () => void this.#end({
+		reason: "shutdown",
+		retry: false
+	});
+	#onClose = (close) => void this.#end(planEnd(close));
 	/**
 	* Drops the socket and detaches every listener and timer this session added. Idempotent, and
 	* safe before `connect` opened anything.
@@ -2483,17 +2655,12 @@ var StudioSession = class {
 	* Ends the session: tells Studio it is over, drops the socket, and optionally reconnects.
 	* `#disposed` keeps the close event from running this twice, and a shutdown from reconnecting.
 	*/
-	async #end({ retry }) {
-		const { studioUrl, token } = this.#options;
+	async #end({ reason, retry, error }) {
 		if (this.#disposed) return;
 		this.#disposed = true;
 		this.dispose();
-		await this.#hooks.callHook("studio:disconnected", { reason: retry ? "connection closed" : "shutdown" });
-		if (this.#session && !await disconnect({
-			sessionId: this.#session.sessionId,
-			studioUrl,
-			token
-		})) await this.#warn("Could not notify Kubb Studio of the disconnect");
+		await this.#hooks.callHook("studio:disconnected", { reason });
+		if (error) await this.#hooks.callHook("studio:error", { error });
 		if (retry) await this.#reconnect();
 	}
 	startGeneration(data) {
@@ -2501,27 +2668,42 @@ var StudioSession = class {
 			this.#lastGeneration = result;
 		} });
 		const controller = new AbortController();
-		const result = this.#runGeneration(data, controller).then(async (value) => {
+		const cancelRun = async () => {
+			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
+		};
+		const result = this.#runGeneration(data, controller, cancelRun).then(async (value) => {
 			await generationStream.close();
 			return value;
 		}).catch((error) => {
 			generationStream.fail(error);
 			throw error;
+		}).finally(() => {
+			if (this.#activeJob?.cancel === cancelRun) this.#activeJob = void 0;
 		});
 		result.catch(() => {});
-		return new GenerationRunTarget(generationStream.stream, result, async () => {
-			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
-		}, () => {
+		return new GenerationRunTarget(generationStream.stream, result, cancelRun, () => {
 			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
 			generationStream.dispose();
 		});
 	}
-	async #runGeneration(data, controller) {
+	/**
+	* Cancels the currently running job when its id matches `jobId`.
+	*/
+	async cancel(jobId) {
+		if (this.#activeJob?.jobId === jobId) await this.#activeJob.cancel();
+	}
+	async #runGeneration(data, controller, cancelRun) {
 		if (this.#isGenerating) return this.#refuse("Ignored generate: a generation is already in progress", "A generation is already in progress, please wait for it to finish");
 		this.#isGenerating = true;
+		this.#activeJob = {
+			jobId: data.jobId,
+			cancel: cancelRun
+		};
 		const command = "generate";
-		const { root, loadConfig, permissions } = this.#options;
+		const { loadConfig, permissions } = this.#options;
+		let root = this.#options.root;
 		try {
+			if (this.#isSandbox) root = await createJobRoot();
 			await this.#hooks.callHook("studio:command:start", { command });
 			const config = await loadConfig();
 			const patch = data.config;
@@ -2532,43 +2714,28 @@ var StudioSession = class {
 			if (patch?.input && !this.#canUseInput) await this.#warn("Ignored the spec from Studio: generating from a Studio spec was not granted", "allowInput");
 			const resolvedPlugins = plugins ?? config.plugins;
 			this.#lastGeneration = void 0;
-			const diskFiles = this.#hasProjectOnDisk ? await listDisk({
-				root,
-				outputPath: config.output.path,
-				maxFiles: DISK_SNAPSHOT_MAX_FILES
-			}) : void 0;
-			const disk = diskFiles ? await this.#generations.keep({
-				jobId: data.jobId,
-				source: "disk",
-				files: diskFiles,
-				maxSetMb: this.#limits.maxSnapshotMb
-			}) : void 0;
-			const detach = [setupHookListener(this.#hooks, root, controller.signal)];
-			try {
-				await generate({
-					config: {
-						...config,
-						root,
-						input: inputOverride ?? config.input,
-						storage: this.#canWrite ? fsStorage() : memoryStorage(),
-						output: permissions.allowExec ? { ...config.output } : {
-							...config.output,
-							format: false,
-							lint: false,
-							postGenerate: []
-						},
-						plugins: resolvedPlugins,
-						adapter
+			const disk = await runGenerationOperation({
+				config: {
+					...config,
+					root,
+					input: inputOverride ?? config.input,
+					storage: this.#canWrite ? fsStorage() : memoryStorage(),
+					output: permissions.allowExec ? { ...config.output } : {
+						...config.output,
+						format: false,
+						lint: false,
+						postGenerate: []
 					},
-					hooks: this.#hooks,
-					signal: controller.signal
-				});
-			} catch (error) {
-				await this.#generations.drop(data.jobId);
-				throw error;
-			} finally {
-				for (const remove of detach) remove();
-			}
+					plugins: resolvedPlugins,
+					adapter
+				},
+				hooks: this.#hooks,
+				signal: controller.signal,
+				jobId: data.jobId,
+				store: this.#generations,
+				snapshotRoot: this.#hasProjectOnDisk ? root : void 0,
+				maxSnapshotMb: this.#limits.maxSnapshotMb
+			});
 			await this.#hooks.callHook("studio:command:end", {
 				command,
 				info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${this.#canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
@@ -2600,6 +2767,7 @@ var StudioSession = class {
 				disk: disk ? { hashes: disk.hashes } : void 0
 			};
 		} finally {
+			if (root !== this.#options.root) await removeJobRoot(root);
 			this.#isGenerating = false;
 		}
 	}
@@ -2629,8 +2797,10 @@ var StudioSession = class {
 		}
 		if (this.#isGenerating) return refuse("a generation is in progress");
 		try {
-			const { source: patched, outcomes, changed } = applyConfigEdits(await read(configFile), edits);
-			if (changed) await writeFile(configFile, patched, "utf-8");
+			const { source: patched, outcomes, changed } = await writeConfigEdits({
+				filePath: configFile,
+				edits
+			});
 			const applied = outcomes.filter((outcome) => outcome.applied).length;
 			await this.#hooks.callHook("studio:command:end", {
 				command,
@@ -2668,24 +2838,14 @@ var StudioSession = class {
 				version,
 				peerDependencies: generation.peerDependencies
 			});
-			const { token, studioUrl } = this.#options;
-			const uploadUrl = new URL(uploadPath, studioUrl);
-			if (uploadUrl.origin !== new URL(studioUrl).origin) throw new Error("Snapshot upload path must stay on the Studio origin");
-			const redirect = await fetch(uploadUrl, {
-				method: "PUT",
-				headers: { Authorization: `Bearer ${token}` },
-				redirect: "manual"
-			});
-			const storageUrl = redirect.headers.get("location");
-			if (redirect.status !== 307 || !storageUrl) throw new Error(`Studio did not provide a storage URL (status ${redirect.status})`);
-			const storage = new URL(storageUrl);
-			if (storage.protocol !== "https:" && storage.hostname !== "localhost" && storage.hostname !== "127.0.0.1") throw new Error(`Refusing snapshot upload to ${storage.origin}`);
-			const response = await fetch(storage, {
-				method: "PUT",
-				body: new Uint8Array(bytes),
-				redirect: "error"
+			const { token, studioUrl, signal } = this.#options;
+			await uploadSnapshot({
+				bytes,
+				uploadPath,
+				studioUrl,
+				token,
+				shutdown: signal
 			});
-			if (!response.ok) throw new Error(`Snapshot upload failed with status ${response.status}`);
 			await this.#hooks.callHook("studio:command:end", {
 				command,
 				info: `packed ${Object.keys(files).length} file${Object.keys(files).length === 1 ? "" : "s"}`
@@ -2699,10 +2859,7 @@ var StudioSession = class {
 			throw error;
 		}
 	}
-	/**
-	* An agent with a project on disk can show a run against what its output directory held before.
-	* A sandbox agent has no project.
-	*/
+	/** A sandbox has no project directory to snapshot. */
 	get #hasProjectOnDisk() {
 		return !this.#isSandbox && this.#canRead;
 	}
@@ -2731,7 +2888,7 @@ var StudioSession = class {
 	}
 };
 //#endregion
-//#region src/client.ts
+//#region src/runtime/client.ts
 /**
 * Creates the Kubb Studio client: the connection, the command loop, and the generation event
 * stream shared by the `kubb studio` CLI command and the Docker agent.
@@ -2747,7 +2904,7 @@ var StudioSession = class {
 */
 function createClient({ onAuthRequired, ...options }) {
 	const controller = new AbortController();
-	const poolSize = options.poolSize ?? agentDefaults.poolSize;
+	const instanceId = options.instanceId ?? randomUUID();
 	function notifyAuthRequired(error) {
 		if (controller.signal.aborted) return;
 		controller.abort();
@@ -2755,19 +2912,12 @@ function createClient({ onAuthRequired, ...options }) {
 	}
 	return {
 		async connect() {
-			const registered = await registerAgent({
-				token: options.token,
-				studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
-				poolSize
-			});
-			if (controller.signal.aborted) return;
-			const startupWarning = registered ? void 0 : "Could not register with Kubb Studio, continuing";
-			await Promise.all(Array.from({ length: poolSize }, (_, slot) => new StudioSession({
+			await new StudioSession({
 				...options,
+				instanceId,
 				signal: controller.signal,
-				onTokenRejected: notifyAuthRequired,
-				startupWarning: slot === 0 ? startupWarning : void 0
-			}).start()));
+				onTokenRejected: notifyAuthRequired
+			}).start();
 		},
 		disconnect() {
 			controller.abort();
@@ -2775,7 +2925,7 @@ function createClient({ onAuthRequired, ...options }) {
 	};
 }
 //#endregion
-//#region src/runConnection.ts
+//#region src/runtime/runConnection.ts
 /**
 * Waits for whichever comes first: the shutdown signal, or Studio rejecting the token during a
 * background reconnect. Resolves with the rejection, or nothing when the run is being shut down.
@@ -2848,7 +2998,7 @@ async function runConnection({ credentials, clientOptions, onTokenRejected, sign
 	}
 }
 //#endregion
-//#region src/pair.ts
+//#region src/operations/pair.ts
 /** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
 const CLIENT_IDS = {
 	cli: "kubb-cli",
@@ -2971,6 +3121,6 @@ async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
 	}
 }
 //#endregion
-export { InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectWebSocketRpc, createAgent, createClient, createFileStorage, createJob, defaultStudioUrl, generationEventTypes, machineTokenFrom, pairAgent, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
+export { AGENT_INSTANCE_HEADER, AgentCloseCode, IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectWebSocketRpc, createAgent, createClient, createFileStorage, createJob, defaultStudioUrl, generationEventTypes, machineTokenFrom, pairAgent, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
 
 //# sourceMappingURL=index.js.map