@stim-cli/server 1.21.0 → 1.22.0

package/dist/{stim-server-BQKNg9Jp.mjs → stim-server-BKcEacbU.mjs}

@@ -1,4 +1,4 @@
-import { n as protocol_exports } from "./protocol-D21Ab4EI.mjs";
+import { n as protocol_exports } from "./protocol-ZY9j2h32.mjs";
 import { createRequire } from "node:module";
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { appendFileSync, chmodSync, closeSync, constants, copyFileSync, cpSync, createReadStream, existsSync, futimesSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, statfsSync, watch, writeFileSync, writeSync } from "node:fs";
@@ -6,15 +6,15 @@ import { basename, delimiter, dirname, isAbsolute, join, posix, relative, resolv
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { DEVICE_HOST_LIMITS, HOSTED_APP_CHUNK_BYTES, HOSTED_MACOS_APP_SLOTS, HOSTED_PARKED_CANDIDATES, KeyedEntities, RECORDING_CAP_BYTES, RECORDING_FOOTAGE_MS, RECORDING_PLATFORMS, SETTING_SCOPES, archiveDir, archivedUsage, assertHostedDeviceLedger, buildWorkerRoot, capDrops, clientIdentity, closedSegmentName, compileGrep, createDebugLog, deviceHostArea, deviceHostRoot, deviceViewersDir, footageDrops, getConcurrencyLimits, getParkedMax, hostedAndroidPlacements, hostedAppArea, hostedAppAttempt, hostedAppBlobs, hostedDeviceId, hostedIosPlacements, hostedMacosBundleId, hostedMacosLogsDir, hostedNativeLogsDir, hostedWorkerSettleMs, isJournalExpired, isJsonObject, isSetupJournalPrunable, listRecordedDevices, listSegments, loadConfig, machineCapacity, machineEndpoint, macosAppState, openSegmentName, parseHostedAppOffer, parseHostedLocalDeviceCount, parseHostedLogsCursor, parseHostedNativeOffer, parseHostedOfferRequest, parseHostedPlatformDevice, parseHostedRequest, queryJsonLogs, readArchive, readArchiveState, readBuildHistory, readBuildMachines, readDeviceHostMachines, readHostedApp, readHostedAppMetadata, readHostedDevice, readHostedDeviceLedger, readHostedMacosApp, readHostedNativeLogsCheckpoint, readHostedSessions, readJsonObject, readLogTimeline, readLogsSince, readMacosRecord, readSetupJournal, readWorkspaceState, recordingDeviceName, rememberHostedAppBlobRename, saturation, serverLocalSocket, serverSetupDir, settingDefinition, settingValueError, setupJournalFile, sortByTs, statusViews, stimBuildDigest, tryAcquireBuildSlotClaim, validHostedAppBlob, validRunId, windowsShortDir, windowsShortDirKey, workspaceRecordingsDir } from "@stim-cli/core/state";
 import { availableParallelism, cpus, freemem, homedir, hostname, loadavg, tmpdir, totalmem, userInfo } from "node:os";
-import { parseArgs } from "node:util";
+import { isDeepStrictEqual, parseArgs } from "node:util";
 import { discoverToolchain } from "@stim-cli/core/toolchain";
 import { copyFile, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { compiledHelper, configDir, createMetroBridge, quoteUnitWord, unitLines, unitWords, validMacosResourceDestination, withDirLock, workspaceStateDir } from "@stim-cli/core";
+import { compiledHelper, configDir, createMetroBridge, quoteUnitWord, reactNativeArtifactIdentity, reactNativeArtifactQuery, reusableDependencies, swiftpmArtifactQuery, unitLines, unitWords, validMacosResourceDestination, withDirLock, workspaceStateDir } from "@stim-cli/core";
 import { CLOSE_REFUSED, HandshakeRefusal, MAX_CLIENT_MESSAGE_BYTES, MAX_FIRST_MESSAGE_BYTES, MAX_SERVER_MESSAGE_BYTES, MODE_FIRST_CONTACT, TRANSPORT_OVERHEAD_BYTES, acceptNoise, decodeSecret, initiateNoise, keyFingerprint, newSecret, readOrCreateKeyFile, secretValues } from "@stim-cli/core/noise-session";
 import { DEFAULT_STUCK_MINUTES, OVERSIGHT_CATEGORIES, inQuietHours, oversee, oversightTitle } from "@stim-cli/core/oversight";
 import { connect, createServer, isIP } from "node:net";
-import { ClaimRefusedError, claimRemoveCommand, clearClaimChild, clearFreeClaimSet, exclusiveClaimDir, markClaimChildPending, processGroupAlive, releaseClaim, setClaimChild, sharedClaimDir, tryAcquireClaim } from "@stim-cli/core/ownership-claim";
+import { ClaimRefusedError, claimRemoveCommand, clearClaimChild, clearFreeClaimSet, exclusiveClaimDir, markClaimChildPending, processGroupAlive, readClaimSet, releaseClaim, setClaimChild, sharedClaimDir, tryAcquireClaim } from "@stim-cli/core/ownership-claim";
 import { findTailscale, isTailscaleTransport, planServe, readRawTailscaleStatus, readTailscaleStatus, serveCommand, serveRoute, tailnetEndpoint, tailscaleInstall, tailscaleTransport } from "@stim-cli/transport-tailscale";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
@@ -127,6 +127,54 @@ function devicesFile() {
 function clientsFile(capability) {
 	return join(serverDir(), `${capability}-clients.json`);
 }
+/** Registry events are hints; callers must reread grants and retain missed-event repair. */
+function watchClientRegistries(changed) {
+	const files = [clientsFile("build"), clientsFile("device-host")];
+	const names = new Set(files.map((file) => basename(file)));
+	const watchers = /* @__PURE__ */ new Map();
+	let stopped = false;
+	const clearFiles = () => {
+		const previous = [...watchers.values()];
+		watchers.clear();
+		for (const observer of previous) observer.close();
+	};
+	const refresh = () => {
+		clearFiles();
+		for (const file of files) try {
+			const observer = watch(file, { persistent: false }, (event) => {
+				if (stopped || watchers.get(file) !== observer) return;
+				if (event === "rename") refresh();
+				changed();
+			});
+			watchers.set(file, observer);
+			observer.once("error", () => {
+				if (watchers.get(file) !== observer) return;
+				watchers.delete(file);
+				observer.close();
+				changed();
+			});
+		} catch {}
+	};
+	refresh();
+	let directory;
+	try {
+		directory = watch(serverDir(), { persistent: false }, (_event, filename) => {
+			if (stopped || filename !== null && !names.has(filename.toString())) return;
+			refresh();
+			changed();
+		});
+		directory.once("error", () => {
+			directory?.close();
+			directory = void 0;
+			if (!stopped) changed();
+		});
+	} catch {}
+	return () => {
+		stopped = true;
+		directory?.close();
+		clearFiles();
+	};
+}
 function secretsFile() {
 	return join(serverDir(), "secrets.json");
 }
@@ -1602,15 +1650,48 @@ const taskScheduler = {
 		]);
 		if (!started.ok) return started;
 		const deadline = Date.now() + SUPERVISOR_WAIT_MS;
-		while (!await runningSupervisor(label)) {
-			if (Date.now() >= deadline) return {
-				ok: false,
-				stdout: "",
-				stderr: `${taskName(label)} did not start its supervisor within ${SUPERVISOR_WAIT_MS / 1e3} s; see ${join(taskScheduler.root(label), "supervisor.log")} and \`schtasks /Query /TN ${taskName(label)} /V /FO LIST\`.`
-			};
-			await new Promise((resolve) => setTimeout(resolve, 250));
+		let observer;
+		let changed = false;
+		let timer;
+		let wake;
+		const notify = () => {
+			changed = true;
+			wake?.();
+		};
+		try {
+			try {
+				observer = watch(taskScheduler.root(label), { persistent: false }, (_event, filename) => {
+					if (filename === null || filename.toString() === "supervisor.json") notify();
+				});
+				observer.once("error", () => {
+					observer?.close();
+					observer = void 0;
+					notify();
+				});
+			} catch {}
+			for (;;) {
+				changed = false;
+				if (await runningSupervisor(label)) return started;
+				const remaining = deadline - Date.now();
+				if (remaining <= 0) return {
+					ok: false,
+					stdout: "",
+					stderr: `${taskName(label)} did not start its supervisor within ${SUPERVISOR_WAIT_MS / 1e3} s; see ${join(taskScheduler.root(label), "supervisor.log")} and \`schtasks /Query /TN ${taskName(label)} /V /FO LIST\`.`
+				};
+				if (changed) continue;
+				await new Promise((resolve) => {
+					wake = () => {
+						clearTimeout(timer);
+						wake = void 0;
+						resolve();
+					};
+					timer = setTimeout(wake, Math.min(remaining, observer ? 1e3 : 250));
+				});
+			}
+		} finally {
+			clearTimeout(timer);
+			observer?.close();
 		}
-		return started;
 	},
 	async stop(label) {
 		const state = await runningSupervisor(label);
@@ -2466,16 +2547,17 @@ function withUpdateClaim(label, work) {
 /**
 * Installs `source` beside the server the job runs, waits for offloaded builds and hosted sessions to finish,
 * switches the job to it and restarts it, and switches back when it does not answer as the installed build. Never
-* touches pairings, approvals, the host app, `$STIM_HOME` or the serve route.
+* touches pairings, approvals, the host app, `$STIM_HOME` or the serve route. With `waitForWork` false,
+* restart interrupts active work instead of waiting for idle; shutdown and health checks still apply.
 */
-async function updateService(label, source, log) {
+async function updateService(label, source, log, waitForWork = true) {
 	if (!existsSync(plistPath(label))) throw new ServiceError(`${label} is not installed.`);
-	return withUpdateClaim(label, (installed) => updateInstalledService(label, installed, source, log));
+	return withUpdateClaim(label, (installed) => updateInstalledService(label, installed, source, log, waitForWork));
 }
-async function updateInstalledService(label, installed, source, log) {
+async function updateInstalledService(label, installed, source, log, waitForWork = true) {
 	const at = (/* @__PURE__ */ new Date()).toISOString();
 	try {
-		const notes = await switchToSource(label, installed, source, log);
+		const notes = await switchToSource(label, installed, source, log, waitForWork);
 		recordOutcome(label, {
 			at,
 			target: describeSource(source),
@@ -2493,11 +2575,12 @@ async function updateInstalledService(label, installed, source, log) {
 		throw error;
 	}
 }
-async function switchToSource(label, installed, source, log) {
+async function switchToSource(label, installed, source, log, waitForWork) {
 	const versions = join(serviceRoot(label), "versions");
 	const target = await installServer(versions, source, installed.node, log);
 	if (sameFile(installed.script, target.script)) return [`${label} already runs ${describeBuild(target.build)}.`];
-	await waitForIdle(installed.port, log);
+	if (waitForWork) await waitForIdle(installed.port, log);
+	else log("Restarting without waiting for active builds or hosted sessions; they will be interrupted.");
 	log(`Switching ${label} to ${describeBuild(target.build)}.`);
 	const script = realpathSync(target.script);
 	await switchTo(installed, script, target.build);
@@ -2769,6 +2852,25 @@ function listCommandLines() {
 }
 //#endregion
 //#region src/build-artifact-cache.ts
+const androidPackage = (value) => typeof value === "string" && /^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+$/.test(value);
+function gradleQueryKey(query) {
+	const { android, inputs } = query;
+	return createHash("sha256").update(JSON.stringify([
+		query.project,
+		query.sourceDigest,
+		inputs.ignored,
+		inputs.outputs,
+		android.variant,
+		android.abi === "all" ? null : android.abi,
+		android.compilerCache,
+		android.gradleBuildCache,
+		android.pch,
+		android.gradleRoot ?? null,
+		android.module ?? null
+	])).digest("hex");
+}
+const completedKind = (query) => "build" in query ? "swiftpm" : "sourceDigest" in query ? "gradle" : "react-native";
+const completedKey = (query) => "sourceDigest" in query && !("build" in query) ? gradleQueryKey(query) : createHash("sha256").update(JSON.stringify(query)).digest("hex");
 function validArtifactIdentity(value) {
 	return isJsonObject(value) && typeof value.fingerprint === "string" && value.fingerprint.length > 0 && value.fingerprint.length <= 256 && typeof value.cacheKey === "string" && value.cacheKey.length > 0 && value.cacheKey.length <= 1024;
 }
@@ -2800,7 +2902,7 @@ var BuildArtifactCache = class {
 				encoding: "utf8",
 				signal
 			}));
-			if (!isJsonObject(record) || record.fingerprint !== identity.fingerprint || record.cacheKey !== identity.cacheKey || typeof record.name !== "string" || basename(record.name) !== record.name || !record.name.endsWith(".app") || typeof record.size !== "number" || !Number.isSafeInteger(record.size) || record.size <= 0 || typeof record.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.sha256)) return null;
+			if (!isJsonObject(record) || record.fingerprint !== identity.fingerprint || record.cacheKey !== identity.cacheKey || typeof record.name !== "string" || basename(record.name) !== record.name || !(record.name.endsWith(".app") || record.name.endsWith(".apk") && androidPackage(record.androidPackage)) || typeof record.size !== "number" || !Number.isSafeInteger(record.size) || record.size <= 0 || typeof record.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.sha256)) return null;
 			if ((await this.files.stat({
 				key: record.sha256,
 				signal
@@ -2809,7 +2911,8 @@ var BuildArtifactCache = class {
 				...identity,
 				name: record.name,
 				size: record.size,
-				sha256: record.sha256
+				sha256: record.sha256,
+				...record.name.endsWith(".apk") && androidPackage(record.androidPackage) ? { androidPackage: record.androidPackage } : {}
 			};
 		} catch {
 			signal.throwIfAborted();
@@ -2817,7 +2920,7 @@ var BuildArtifactCache = class {
 		}
 	}
 	async store(identity, parameters, archive, artifact, signal) {
-		if (!validArtifactIdentity(identity) || !await verified(archive, artifact, signal)) return;
+		if (!validArtifactIdentity(identity) || !await verified(archive, artifact, signal)) return false;
 		await this.files.store({
 			key: artifact.sha256,
 			sourcePath: archive,
@@ -2840,10 +2943,57 @@ var BuildArtifactCache = class {
 			});
 			signal.throwIfAborted();
 			await rename(temporary, this.record(identity));
+			return true;
+		} finally {
+			await rm(temporary, { force: true });
+		}
+	}
+	async storeCompleted(query, identity, receipt, archive, artifact, signal) {
+		if (!("build" in query) && ("sourceDigest" in query || query.platform === "android")) {
+			if (!artifact.name.endsWith(".apk") || !androidPackage(artifact.androidPackage)) return;
+		} else if (!artifact.name.endsWith(".app")) return;
+		if (!await this.store(identity, { ...query }, archive, artifact, signal)) return;
+		const key = completedKey(query);
+		const temporary = join(this.directory, `${randomUUID()}.partial`);
+		try {
+			await writeFile(temporary, JSON.stringify({
+				query: key,
+				receipt
+			}), {
+				mode: 384,
+				signal
+			});
+			signal.throwIfAborted();
+			await rename(temporary, join(this.directory, `${key}.${completedKind(query)}.json`));
 		} finally {
 			await rm(temporary, { force: true });
 		}
 	}
+	async completedRecord(query, signal) {
+		signal.throwIfAborted();
+		try {
+			const key = completedKey(query);
+			const record = JSON.parse(await readFile(join(this.directory, `${key}.${completedKind(query)}.json`), {
+				encoding: "utf8",
+				signal
+			}));
+			return isJsonObject(record) && record.query === key && isJsonObject(record.receipt) ? record : null;
+		} catch {
+			signal.throwIfAborted();
+			return null;
+		}
+	}
+	async receipt(query, signal) {
+		return (await this.completedRecord(query, signal))?.receipt ?? null;
+	}
+	async lookupReactNative(query, signal) {
+		const record = await this.completedRecord(query, signal);
+		if (!record || !isJsonObject(record.receipt) || !isJsonObject(record.receipt.toolchain) || !isDeepStrictEqual(record.receipt.query, query)) return null;
+		return this.lookup(reactNativeArtifactIdentity({
+			query,
+			toolchain: record.receipt.toolchain
+		}), signal);
+	}
 	async fetch(identity, destinationDir, signal) {
 		const artifact = await this.lookup(identity, signal);
 		if (!artifact) return null;
@@ -2866,6 +3016,175 @@ var BuildArtifactCache = class {
 	}
 };
 //#endregion
+//#region src/artifact-query.ts
+/** Revalidates only a completed build's private inputs, holding its area until the owned query has stopped. */
+function runArtifactQuery({ worker, area, env, query, receipt, signal, timeoutMs = 1e4, killGraceMs = 1e3 }) {
+	signal.throwIfAborted();
+	const attempt = tryAcquireClaim({
+		root: `${area}.claims`,
+		mode: "shared",
+		label: "Completed artifact query"
+	});
+	if (!attempt.acquired) {
+		if (attempt.pending) releaseClaim(attempt.pending);
+		return {
+			done: Promise.resolve({
+				identity: null,
+				settled: true
+			}),
+			cancel: () => {}
+		};
+	}
+	const claim = attempt.acquired;
+	markClaimChildPending(claim);
+	let child;
+	try {
+		child = spawn(process.execPath, [worker, "build" in query ? "swiftpm-artifact" : "native-gradle-artifact"], {
+			cwd: area,
+			env,
+			detached: true,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+	} catch (error) {
+		clearClaimChild(claim);
+		releaseClaim(claim);
+		throw error;
+	}
+	let identity = null;
+	let closed = false;
+	let ended = false;
+	let stopped = false;
+	let output = "";
+	let treeStopped = null;
+	let killTimer;
+	let settleTimer;
+	let groupTimer;
+	let finish;
+	const done = new Promise((resolve) => {
+		finish = resolve;
+	});
+	const end = (settled) => {
+		if (ended) return;
+		ended = true;
+		clearTimeout(deadline);
+		clearTimeout(killTimer);
+		clearTimeout(settleTimer);
+		clearTimeout(groupTimer);
+		signal.removeEventListener("abort", cancel);
+		let result = null;
+		if (settled) {
+			try {
+				clearClaimChild(claim);
+				releaseClaim(claim);
+			} catch (error) {
+				settled = false;
+				console.error(`stim-server: Completed artifact query could not release ${claim.path}: ${String(error)}`);
+			}
+			if (settled && !stopped) try {
+				const value = JSON.parse(output);
+				if (isJsonObject(value) && isJsonObject(value.identity) && typeof value.identity.hash === "string" && /^[a-f0-9]{64}$/.test(value.identity.hash) && typeof value.identity.key === "string" && value.identity.key.length > 0 && value.identity.key.length <= 1024) result = {
+					fingerprint: value.identity.hash,
+					cacheKey: value.identity.key
+				};
+			} catch {}
+		}
+		if (!settled) {
+			child.stdin?.destroy();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			child.unref();
+			console.error(`stim-server: Completed artifact query cleanup is unresolved at ${claim.path}; inspect before ${claimRemoveCommand(claim.root)}`);
+		}
+		finish({
+			identity: result,
+			settled
+		});
+	};
+	const signalGroup = (name) => {
+		if (!identity || !child.pid) return;
+		const status = inspectProcessIdentity(identity);
+		if (status !== "same" && status !== "gone") return;
+		if (process.platform === "win32") treeStopped ??= new Promise((resolve) => {
+			execFile(join(process.env.SystemRoot || "C:\\Windows", "System32", "taskkill.exe"), [
+				"/PID",
+				String(child.pid),
+				"/T",
+				"/F"
+			], { timeout: 4e3 }, (error) => resolve(!error));
+		});
+		else try {
+			process.kill(-child.pid, name);
+		} catch {}
+	};
+	const cancel = () => {
+		if (ended || stopped) return;
+		stopped = true;
+		signalGroup("SIGTERM");
+		killTimer = setTimeout(() => signalGroup("SIGKILL"), killGraceMs);
+		settleTimer = setTimeout(() => end(false), killGraceMs + 5e3);
+	};
+	const drained = async () => {
+		if (ended || !closed) return;
+		if (treeStopped && !await treeStopped) return end(false);
+		if (!child.pid || !processGroupAlive(child.pid)) return end(true);
+		cancel();
+		groupTimer = setTimeout(() => void drained(), 25);
+	};
+	const deadline = setTimeout(cancel, timeoutMs);
+	child.stdout?.setEncoding("utf8");
+	child.stdout?.on("data", (chunk) => {
+		if (Buffer.byteLength(output) + Buffer.byteLength(chunk) > 16384) cancel();
+		else output += chunk;
+	});
+	child.stderr?.resume();
+	child.stdin?.on("error", cancel);
+	child.once("error", () => {
+		cancel();
+		closed = true;
+		drained();
+	});
+	child.once("close", (code) => {
+		if (code !== 0) cancel();
+		closed = true;
+		drained();
+	});
+	signal.addEventListener("abort", cancel, { once: true });
+	const captured = child.pid === void 0 ? null : captureProcessIdentity(child.pid);
+	if (!captured?.ok || child.pid === void 0) {
+		child.kill("SIGKILL");
+		cancel();
+	} else {
+		identity = {
+			pid: child.pid,
+			processToken: captured.token
+		};
+		try {
+			setClaimChild(claim, identity);
+			if (signal.aborted) cancel();
+			else child.stdin?.end(JSON.stringify({
+				root: join(area, "src", query.project),
+				receipt,
+				..."build" in query ? { query } : {
+					sourceDigest: query.sourceDigest,
+					inputs: query.inputs,
+					android: query.android
+				}
+			}));
+		} catch (error) {
+			console.error(`stim-server: Completed artifact query could not record its child: ${String(error)}`);
+			cancel();
+		}
+	}
+	return {
+		done,
+		cancel
+	};
+}
+//#endregion
 //#region src/build.ts
 const DEFAULT_BUILD_LIMITS = {
 	maxJobs: 1,
@@ -2931,6 +3250,61 @@ function androidOptions(value) {
 		module
 	};
 }
+function macosBuildOptions(params) {
+	const options = params.macos;
+	if (!isJsonObject(options) || typeof options.product !== "string" || !/^[A-Za-z0-9_.-]{1,100}$/.test(options.product) || !validBuildPath(options.infoPlist) || typeof options.bundleId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,199}$/.test(options.bundleId)) return refusal("bad-request", "A macos build needs a valid product, relative infoPlist path and bundleId in params.macos.");
+	if (options.resources !== void 0 && (!isJsonObject(options.resources) || Object.keys(options.resources).length > 256 || Object.entries(options.resources).some(([destination, source]) => !validMacosResourceDestination(destination) || !validBuildPath(source))) || options.assetCatalog !== void 0 && options.assetCatalog !== null && !validBuildPath(options.assetCatalog)) return refusal("bad-request", "params.macos needs contained resource destinations and repository-relative sources.");
+	const artifactQuery = options.artifactInputs === void 0 ? null : swiftpmArtifactQuery({
+		project: params.project,
+		sourceDigest: params.fingerprint,
+		stimBuild: params.stimBuild,
+		inputs: options.artifactInputs,
+		build: {
+			product: options.product,
+			infoPlist: options.infoPlist,
+			resources: options.resources ?? {},
+			assetCatalog: options.assetCatalog ?? null
+		}
+	});
+	if (options.artifactInputs !== void 0 && !artifactQuery) return refusal("bad-request", "SwiftPM artifact retention needs a complete repeatable input declaration.");
+	return { options: {
+		product: options.product,
+		infoPlist: options.infoPlist,
+		bundleId: options.bundleId,
+		...artifactQuery ? { artifactInputs: artifactQuery.inputs } : {},
+		...options.resources !== void 0 ? { resources: options.resources } : {},
+		...options.assetCatalog !== void 0 ? { assetCatalog: options.assetCatalog } : {}
+	} };
+}
+function gradleArtifactQuery(value) {
+	if (!isJsonObject(value) || Object.keys(value).some((key) => ![
+		"project",
+		"sourceDigest",
+		"inputs",
+		"android"
+	].includes(key))) return null;
+	const { project, sourceDigest, inputs } = value;
+	const path = (candidate) => validBuildPath(candidate) && !/[\\:]/.test(candidate);
+	if (typeof project !== "string" || project !== "" && !path(project) || typeof sourceDigest !== "string" || !/^[a-f0-9]{64}$/.test(sourceDigest) || !isJsonObject(inputs) || inputs.complete !== true || Object.keys(inputs).some((key) => ![
+		"complete",
+		"ignored",
+		"outputs"
+	].includes(key)) || !Array.isArray(inputs.ignored) || !inputs.ignored.every(path) || !Array.isArray(inputs.outputs) || !inputs.outputs.every(path)) return null;
+	const android = androidOptions(value.android);
+	return android && android.variant !== null ? {
+		project,
+		sourceDigest,
+		inputs: {
+			complete: true,
+			ignored: inputs.ignored,
+			outputs: inputs.outputs
+		},
+		android: {
+			...android,
+			variant: android.variant
+		}
+	} : null;
+}
 function freeBytes(path) {
 	try {
 		const stats = statfsSync(path);
@@ -2944,13 +3318,6 @@ function workerFreeBytes(root) {
 	const free = [root, ...process.platform === "win32" ? [dirname(dirname(windowsShortDir(root)))] : []].map(freeBytes).filter((bytes) => bytes !== null);
 	return free.length ? Math.min(...free) : null;
 }
-function nonEmptyDir(path) {
-	try {
-		return readdirSync(path).length > 0;
-	} catch {
-		return false;
-	}
-}
 function gradleDaemonIdleMs() {
 	const definition = settingDefinition("server.gradleDaemonIdleMinutes");
 	const value = loadConfig()?.server?.gradleDaemonIdleMinutes;
@@ -3007,6 +3374,8 @@ var BuildHost = class {
 	owned = /* @__PURE__ */ new Map();
 	sessions = /* @__PURE__ */ new Map();
 	served = /* @__PURE__ */ new Set();
+	removals = /* @__PURE__ */ new Map();
+	queries = /* @__PURE__ */ new Set();
 	retained = /* @__PURE__ */ new Map();
 	closed = false;
 	draining = null;
@@ -3108,13 +3477,30 @@ var BuildHost = class {
 		});
 		return value;
 	}
-	async offer(client, params) {
+	async offer(client, params, signal = new AbortController().signal) {
 		if (!isJsonObject(params) || !validRepo(params.repo)) return refusal("bad-request", "build.offer needs params.repo.");
+		let dependencies;
+		if (params.dependencies !== void 0) {
+			const value = params.dependencies;
+			if (!isJsonObject(value) || typeof value.project !== "string" || value.project !== "" && (!validBuildPath(value.project) || /[\\:]/.test(value.project)) || value.packageName !== null && typeof value.packageName !== "string") return refusal("bad-request", "Dependency warmth needs a repository project and package name or null.");
+			dependencies = {
+				project: value.project,
+				packageName: value.packageName
+			};
+		}
 		if (params.rubyVersion !== void 0 && (typeof params.rubyVersion !== "string" || !new RegExp(protocol_exports.BUILD_RUBY_VERSION_PATTERN).test(params.rubyVersion))) return refusal("bad-request", "build.offer needs a Ruby installation name without path separators.");
 		if (params.native !== void 0 && params.native !== "xcode" && params.native !== "gradle") return refusal("bad-request", "build.offer supports native Xcode or Gradle toolchains.");
 		if (params.artifact !== void 0 && (params.native !== "xcode" || !validArtifactIdentity(params.artifact))) return refusal("bad-request", "An artifact lookup needs a complete native Xcode identity.");
-		const artifact = params.artifact === void 0 ? void 0 : await this.cache(client, params.repo).lookup(params.artifact, new AbortController().signal);
+		const query = params.gradleArtifact === void 0 ? void 0 : gradleArtifactQuery(params.gradleArtifact);
+		if (query === null || query !== void 0 && (params.native !== "gradle" || params.artifact !== void 0)) return refusal("bad-request", "A native Gradle artifact lookup needs its completed source and build choices.");
+		const reactNative = params.reactNativeArtifact === void 0 ? void 0 : reactNativeArtifactQuery(params.reactNativeArtifact);
+		if (reactNative === null || reactNative !== void 0 && (params.native !== void 0 || params.artifact !== void 0 || query !== void 0)) return refusal("bad-request", "A React Native artifact lookup needs its development fingerprint and build choices.");
+		const swiftpm = params.swiftpmArtifact === void 0 ? void 0 : swiftpmArtifactQuery(params.swiftpmArtifact);
+		if (swiftpm === null || swiftpm !== void 0 && (params.native !== void 0 || params.artifact !== void 0 || query !== void 0 || reactNative !== void 0)) return refusal("bad-request", "A SwiftPM artifact lookup needs its completed source and declared build choices.");
+		const artifact = swiftpm !== void 0 ? await this.privateArtifact(client, params.repo, swiftpm, signal) : reactNative !== void 0 ? await this.cache(client, params.repo).lookupReactNative(reactNative, signal) : query !== void 0 ? await this.privateArtifact(client, params.repo, query, signal) : params.artifact === void 0 ? void 0 : await this.cache(client, params.repo).lookup(params.artifact, signal);
+		if (this.closed || this.removals.has(client) || signal.aborted || !(this.options.allowed?.(client) ?? true)) return refusal("build-refused", "This build connection closed or lost access during the offer.");
 		const toolchain = await this.toolchain(params.rubyVersion ?? null, params.native);
+		if (this.closed || this.removals.has(client) || signal.aborted || !(this.options.allowed?.(client) ?? true)) return refusal("build-refused", "This build connection closed or lost access during the offer.");
 		if (!toolchain) return refusal("build-refused", "This machine could not read its build toolchain.");
 		const root = this.root();
 		mkdirSync(root, {
@@ -3122,10 +3508,6 @@ var BuildHost = class {
 			mode: 448
 		});
 		const area = join(this.clientDir(client), "repos", params.repo);
-		let lockfile = null;
-		try {
-			lockfile = readFileSync(join(area, "lockfile"), "utf8");
-		} catch {}
 		const available = await readAvailableMemory();
 		const total = totalmem();
 		const memory = available === null ? {} : {
@@ -3140,8 +3522,8 @@ var BuildHost = class {
 			},
 			warm: {
 				checkout: existsSync(join(area, "src")),
-				dependencies: typeof params.lockfile === "string" && lockfile === params.lockfile,
-				build: nonEmptyDir(join(area, "home", "workspaces")) || nonEmptyDir(join(area, "macos"))
+				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, dependencies.packageName, params.lockfile),
+				build: false
 			},
 			...artifact !== void 0 ? { artifact } : {}
 		} };
@@ -3149,6 +3531,101 @@ var BuildHost = class {
 	cache(client, repo) {
 		return new BuildArtifactCache(join(this.clientDir(client), "repos", repo, "artifact-cache"));
 	}
+	workerEnvironment(clientDir, area) {
+		return {
+			...this.options.env,
+			STIM_HOME: join(area, "home"),
+			CP_HOME_DIR: join(clientDir, "cache", "cocoapods-home"),
+			CP_CACHE_DIR: join(clientDir, "cache", "cocoapods"),
+			npm_config_store_dir: join(clientDir, "cache", "pnpm-store"),
+			GRADLE_USER_HOME: gradleUserHome(clientDir)
+		};
+	}
+	async privateArtifact(client, repo, query, signal) {
+		try {
+			if (this.closed || this.removals.has(client) || !(this.options.allowed?.(client) ?? true) || this.queries.size >= 4) return null;
+			const cache = this.cache(client, repo);
+			const receipt = await cache.receipt(query, signal);
+			if (!receipt || this.closed || this.removals.has(client) || signal.aborted || !(this.options.allowed?.(client) ?? true) || this.queries.size >= 4) return null;
+			const clientDir = this.clientDir(client), area = join(clientDir, "repos", repo);
+			const run = runArtifactQuery({
+				worker: this.options.worker,
+				area,
+				env: this.workerEnvironment(clientDir, area),
+				query,
+				receipt,
+				signal,
+				killGraceMs: this.limits.killGraceMs
+			});
+			const entry = {
+				client,
+				run,
+				settled: false
+			};
+			this.queries.add(entry);
+			this.served.add(client);
+			try {
+				const result = await run.done;
+				entry.settled = result.settled;
+				if (!result.settled) throw new Error("Native artifact lookup cleanup is unresolved; inspect this machine's stim-server logs before retrying.");
+				if (!result.identity || signal.aborted || this.closed || !(this.options.allowed?.(client) ?? true)) return null;
+				const artifact = await cache.lookup(result.identity, signal);
+				return "build" in query ? artifact?.name.endsWith(".app") ? artifact : null : artifact?.androidPackage ? artifact : null;
+			} finally {
+				if (entry.settled) this.queries.delete(entry);
+			}
+		} catch (error) {
+			console.error(`stim-server: Completed artifact lookup failed for ${client}/${repo}: ${String(error)}`);
+			throw new Error("This machine could not verify the completed artifact inputs or their cleanup; inspect its stim-server logs before retrying.", { cause: error });
+		}
+	}
+	async stopQueries(client) {
+		const entries = [...this.queries].filter((entry) => client === void 0 || entry.client === client);
+		for (const entry of entries) entry.run.cancel();
+		return (await Promise.all(entries.map((entry) => entry.run.done))).every((result) => result.settled);
+	}
+	async storeCompletedGradle(client, repo, job, entry, signal) {
+		const outcome = entry.outcome, metadata = entry.cacheArtifact, native = job.native;
+		if (!outcome?.ok || !isJsonObject(native) || native.provider !== "gradle" || !isJsonObject(native.cache) || native.cache.write !== true || native.cache.remote !== true || outcome.fingerprint !== null || outcome.sourceDigest !== native.sourceDigest || typeof outcome.androidPackage !== "string" || !metadata || !isJsonObject(metadata.identity) || !isJsonObject(metadata.receipt)) return;
+		const identity = {
+			fingerprint: metadata.identity.hash,
+			cacheKey: metadata.identity.key
+		};
+		const query = gradleArtifactQuery({
+			project: job.project,
+			sourceDigest: native.sourceDigest,
+			inputs: native.inputs,
+			android: job.android
+		});
+		if (!query || !validArtifactIdentity(identity)) return;
+		await this.cache(client, repo).storeCompleted(query, identity, metadata.receipt, entry.archive, {
+			...outcome.artifact,
+			androidPackage: outcome.androidPackage
+		}, signal);
+	}
+	async storeCompletedSwiftpm(client, repo, job, entry, signal) {
+		const metadata = entry.swiftpmArtifact;
+		if (!entry.outcome?.ok || job.platform !== "macos" || job.cacheArtifact !== true || !isJsonObject(job.macos) || !metadata || !isJsonObject(metadata.identity) || !isJsonObject(metadata.receipt)) return;
+		const options = job.macos;
+		const query = swiftpmArtifactQuery({
+			project: job.project,
+			sourceDigest: job.expectedFingerprint,
+			stimBuild: job.stimBuild,
+			inputs: options.artifactInputs,
+			build: {
+				product: options.product,
+				infoPlist: options.infoPlist,
+				resources: options.resources ?? {},
+				assetCatalog: options.assetCatalog ?? null
+			}
+		});
+		const identity = {
+			fingerprint: metadata.identity.hash,
+			cacheKey: metadata.identity.key
+		};
+		if (!query || !validArtifactIdentity(identity) || identity.cacheKey !== `swiftpm-peer-${identity.fingerprint}` || entry.outcome.fingerprint !== query.sourceDigest || !isDeepStrictEqual(query, metadata.receipt.query) || !isDeepStrictEqual(metadata.identity, metadata.receipt.identity)) return;
+		await this.cache(client, repo).storeCompleted(query, identity, metadata.receipt, entry.archive, entry.outcome.artifact, signal);
+	}
 	running() {
 		return this.jobs.size;
 	}
@@ -3219,12 +3696,45 @@ var BuildHost = class {
 		} catch {}
 	}
 	/** Cancels the builds of `client`, a client that lost `build`, and deletes its area once they end. */
-	async remove(client) {
-		if (!client || client === "." || client === ".." || basename(client) !== client) return;
+	remove(client) {
+		if (!client || client === "." || client === ".." || basename(client) !== client) return Promise.resolve();
+		const pending = this.removals.get(client);
+		if (pending) return pending;
+		const removal = this.removeClient(client).finally(() => this.removals.delete(client));
+		this.removals.set(client, removal);
+		return removal;
+	}
+	async removeClient(client) {
 		for (const [token, entry] of this.retained) if (entry.client === client) this.drop(token);
 		const jobs = [...this.jobs].filter((job) => job.client === client);
 		for (const job of jobs) job.cancel();
+		const queriesSettled = await this.stopQueries(client);
 		await Promise.all(jobs.map((job) => job.done));
+		if (!queriesSettled) {
+			console.error(`stim-server: retaining the build area of ${client} because artifact query cleanup is unresolved.`);
+			return;
+		}
+		let areas;
+		try {
+			areas = await readdir(join(this.clientDir(client), "repos"));
+		} catch (error) {
+			if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+				console.error(`stim-server: retaining unreadable build areas of ${client}: ${String(error)}`);
+				return;
+			}
+			areas = [];
+		}
+		for (const area of areas.filter((name) => name.endsWith(".claims"))) {
+			const root = join(this.clientDir(client), "repos", area);
+			const clearance = clearFreeClaimSet({
+				root,
+				label: "build worker"
+			});
+			if (clearance.status !== "cleared") {
+				console.error(`stim-server: retaining the build area of ${client}; ownership at ${root} is ${clearance.status}.`);
+				return;
+			}
+		}
 		if (process.platform === "win32") await this.sweepDaemons(client);
 		const removeDir = async (dir) => {
 			try {
@@ -3263,7 +3773,7 @@ var BuildHost = class {
 	}
 	/** Starts the build of one synced manifest; the job belongs to the caller's connection. */
 	launch({ client, repo, job, session, send }) {
-		if (this.closed) return refusal("build-refused", "This machine is shutting down stim-server.");
+		if (this.closed || this.removals.has(client)) return refusal("build-refused", "This machine is shutting down or removing this build client.");
 		const { declined } = this.capacity();
 		if (declined) return refusal("build-busy", `This machine declines the build: ${declined}.`);
 		const clientDir = this.clientDir(client);
@@ -3335,14 +3845,7 @@ var BuildHost = class {
 					"pipe",
 					"ignore"
 				],
-				env: {
-					...this.options.env,
-					STIM_HOME: join(area, "home"),
-					CP_HOME_DIR: join(clientDir, "cache", "cocoapods-home"),
-					CP_CACHE_DIR: join(clientDir, "cache", "cocoapods"),
-					npm_config_store_dir: join(clientDir, "cache", "pnpm-store"),
-					GRADLE_USER_HOME: gradleUserHome(clientDir)
-				}
+				env: this.workerEnvironment(clientDir, area)
 			});
 		} catch (error) {
 			releaseClaims();
@@ -3432,7 +3935,12 @@ var BuildHost = class {
 				job: id,
 				record: value.record
 			});
-			else if (value.type === "result") entry.outcome = workerOutcome(value, isJsonObject(job.native) && job.native.provider === "gradle" ? "gradle" : void 0);
+			else if (value.type === "result") {
+				if (isJsonObject(value.cacheArtifact)) entry.cacheArtifact = value.cacheArtifact;
+				if (isJsonObject(value.reactNativeArtifact)) entry.reactNativeArtifact = value.reactNativeArtifact;
+				if (isJsonObject(value.swiftpmArtifact)) entry.swiftpmArtifact = value.swiftpmArtifact;
+				entry.outcome = workerOutcome(value, isJsonObject(job.native) && job.native.provider === "gradle" ? "gradle" : void 0);
+			}
 		});
 		this.jobs.add(entry);
 		this.owned.set(id, entry);
@@ -3477,6 +3985,24 @@ var BuildHost = class {
 							}
 						});
 					}
+					try {
+						await this.storeCompletedGradle(client, repo, job, entry, caching.signal);
+						await this.storeCompletedSwiftpm(client, repo, job, entry, caching.signal);
+						const metadata = entry.reactNativeArtifact;
+						const query = metadata && isJsonObject(metadata.receipt) ? reactNativeArtifactQuery(metadata.receipt.query) : null;
+						if (entry.outcome?.ok && job.cacheArtifact === true && !job.native && query && metadata && isJsonObject(metadata.identity) && query.fingerprint === job.expectedFingerprint && entry.outcome.fingerprint === job.expectedFingerprint && query.project === job.project && query.platform === job.platform) {
+							const identity = {
+								fingerprint: metadata.identity.hash,
+								cacheKey: metadata.identity.key
+							};
+							if (validArtifactIdentity(identity)) await this.cache(client, repo).storeCompleted(query, identity, metadata.receipt, entry.archive, {
+								...entry.outcome.artifact,
+								...entry.outcome.androidPackage ? { androidPackage: entry.outcome.androidPackage } : {}
+							}, caching.signal);
+						}
+					} catch (error) {
+						console.error(`stim-server: could not retain the completed artifact for ${client}/${repo}: ${String(error)}`);
+					}
 					entry.settled = true;
 					this.jobs.delete(entry);
 					if (cancelled) this.sweepDaemons(client);
@@ -3600,6 +4126,7 @@ var BuildHost = class {
 	*/
 	abandonDetached(allowed, deleteAreas = false) {
 		for (const job of this.owned.values()) if (!job.session && !allowed(job.client)) this.abandon(job);
+		for (const entry of this.queries) if (!allowed(entry.client)) entry.run.cancel();
 		for (const [token, entry] of this.retained) if (!allowed(entry.client)) this.drop(token);
 		for (const client of this.served) {
 			if (!deleteAreas || allowed(client)) continue;
@@ -3612,15 +4139,17 @@ var BuildHost = class {
 		clearInterval(this.sweeper);
 		for (const job of this.owned.values()) this.abandon(job);
 		for (const token of this.retained.keys()) this.drop(token);
+		await this.stopQueries();
 		await Promise.all([...this.jobs].map((job) => job.done));
 		await this.sweeping;
 	}
 };
 function workerOutcome(value, native) {
 	const timings = isJsonObject(value.timings) ? value.timings : {};
+	const androidPackage = typeof value.androidPackage === "string" && /^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+$/.test(value.androidPackage) ? value.androidPackage : void 0;
 	if (value.ok === true && isJsonObject(value.artifact)) {
 		const { name, size, sha256 } = value.artifact;
-		if (typeof name === "string" && typeof size === "number" && typeof sha256 === "string" && (native !== "gradle" || value.fingerprint === null && typeof value.androidPackage === "string" && /^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+$/.test(value.androidPackage))) return {
+		if (typeof name === "string" && typeof size === "number" && typeof sha256 === "string" && (native !== "gradle" || value.fingerprint === null && androidPackage !== void 0)) return {
 			ok: true,
 			artifact: {
 				name,
@@ -3628,7 +4157,7 @@ function workerOutcome(value, native) {
 				sha256
 			},
 			fingerprint: native === "gradle" ? null : String(value.fingerprint),
-			...native === "gradle" ? { androidPackage: value.androidPackage } : {},
+			...androidPackage ? { androidPackage } : {},
 			...typeof value.sourceDigest === "string" ? { sourceDigest: value.sourceDigest } : {},
 			compilationCache: isJsonObject(value.compilationCache) ? value.compilationCache : {},
 			timings
@@ -3655,6 +4184,7 @@ var BuildSession = class {
 	jobs = /* @__PURE__ */ new Map();
 	closed = false;
 	transfers = new AbortController();
+	signal = this.transfers.signal;
 	host;
 	client;
 	socket;
@@ -3753,6 +4283,12 @@ var BuildSession = class {
 			if (!isJsonObject(input) || typeof input.sourceDigest !== "string" || !/^[0-9a-f]{64}$/.test(input.sourceDigest)) return refusal("bad-request", "A native build needs its source transfer digest.");
 			if (input.provider === "gradle") {
 				const inputs = input.inputs;
+				const cache = input.cache;
+				if (cache !== void 0 && (!isJsonObject(cache) || [
+					"read",
+					"write",
+					"remote"
+				].some((key) => typeof cache[key] !== "boolean"))) return refusal("bad-request", "A native Gradle artifact cache policy needs boolean read, write and remote values.");
 				if (platform !== "android" || params.fingerprint !== null || !isJsonObject(inputs) || inputs.complete !== true || Object.keys(inputs).some((key) => ![
 					"complete",
 					"ignored",
@@ -3774,16 +4310,9 @@ var BuildSession = class {
 		if (platform === "android" && !android) return refusal("bad-request", "An android build needs params.android: variant and abi (string or null), gradleBuildCache, pch and compilerCache.");
 		let macos = null;
 		if (platform === "macos") {
-			const options = params.macos;
-			if (!isJsonObject(options) || typeof options.product !== "string" || !/^[A-Za-z0-9_.-]{1,100}$/.test(options.product) || !validBuildPath(options.infoPlist) || typeof options.bundleId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,199}$/.test(options.bundleId)) return refusal("bad-request", "A macos build needs a valid product, relative infoPlist path and bundleId in params.macos.");
-			if (options.resources !== void 0 && (!isJsonObject(options.resources) || Object.keys(options.resources).length > 256 || Object.entries(options.resources).some(([destination, source]) => !validMacosResourceDestination(destination) || !validBuildPath(source))) || options.assetCatalog !== void 0 && options.assetCatalog !== null && !validBuildPath(options.assetCatalog)) return refusal("bad-request", "params.macos needs contained resource destinations and repository-relative sources.");
-			macos = {
-				product: options.product,
-				infoPlist: options.infoPlist,
-				bundleId: options.bundleId,
-				...options.resources !== void 0 ? { resources: options.resources } : {},
-				...options.assetCatalog !== void 0 ? { assetCatalog: options.assetCatalog } : {}
-			};
+			const parsed = macosBuildOptions(params);
+			if ("error" in parsed) return parsed;
+			macos = parsed.options;
 		}
 		if (params.project !== "" && !validBuildPath(params.project)) return refusal("bad-request", "params.project must be a relative path inside the repository.");
 		if (!this.done || this.repo !== params.repo) return refusal("bad-request", "Send the whole manifest of this repo with build.sync first.");
@@ -3806,6 +4335,8 @@ var BuildSession = class {
 				project: params.project,
 				packageName: optional(params.packageName),
 				isExpo: params.isExpo === true,
+				cacheArtifact: params.cacheArtifact === true,
+				stimBuild: params.stimBuild,
 				configuration: optional(params.configuration),
 				scheme: optional(params.scheme),
 				iosProjectPath: optional(params.iosProjectPath),
@@ -3862,6 +4393,17 @@ var BuildSession = class {
 	async cachedArtifact(params) {
 		if (!isJsonObject(params) || !validRepo(params.repo) || !validArtifactIdentity(params.artifact)) return refusal("bad-request", "A cached artifact needs its repository and complete identity.");
 		if (this.closed) return refusal("build-refused", "The connection closed.");
+		if (params.gradleArtifact !== void 0 || params.reactNativeArtifact !== void 0 || params.swiftpmArtifact !== void 0) {
+			if ([
+				params.gradleArtifact,
+				params.reactNativeArtifact,
+				params.swiftpmArtifact
+			].filter((value) => value !== void 0).length > 1) return refusal("bad-request", "Choose one completed artifact query.");
+			const query = params.gradleArtifact !== void 0 ? gradleArtifactQuery(params.gradleArtifact) : params.swiftpmArtifact !== void 0 ? swiftpmArtifactQuery(params.swiftpmArtifact) : reactNativeArtifactQuery(params.reactNativeArtifact);
+			if (!query) return refusal("bad-request", "Choose the completed source and build options.");
+			const current = "sourceDigest" in query ? await this.host.privateArtifact(this.client, params.repo, query, this.transfers.signal) : await this.host.cache(this.client, params.repo).lookupReactNative(query, this.transfers.signal);
+			if (!current || current.fingerprint !== params.artifact.fingerprint || current.cacheKey !== params.artifact.cacheKey) return { result: null };
+		} else if (params.artifact.cacheKey.startsWith("react-native-") || params.artifact.cacheKey.startsWith("swiftpm-peer-") || (await this.host.cache(this.client, params.repo).lookup(params.artifact, this.transfers.signal))?.androidPackage) return refusal("bad-request", "This cached artifact needs a current build query.");
 		const area = join(this.host.clientDir(this.client), "repos", params.repo);
 		mkdirSync(area, {
 			recursive: true,
@@ -4079,7 +4621,8 @@ function parseSetupArgs(args, now, ticket) {
 			},
 			yes: { type: "boolean" },
 			json: { type: "boolean" },
-			verbose: { type: "boolean" }
+			verbose: { type: "boolean" },
+			"no-wait": { type: "boolean" }
 		}
 	});
 	if (values.ticket !== void 0) throw new SetupRefusal("setup no longer takes --ticket, because other users on this machine can read command-line arguments. Set STIM_SETUP_TICKET=<ticket> before stim-server setup, or copy a new command from Stim Desktop.");
@@ -4111,7 +4654,8 @@ function parseSetupArgs(args, now, ticket) {
 		pathPrepend,
 		yes: values.yes === true,
 		json: values.json === true,
-		verbose: values.verbose === true
+		verbose: values.verbose === true,
+		noWait: values["no-wait"] === true
 	};
 }
 /** The record a client made for each capability by spending this run's ticket. */
@@ -4160,7 +4704,16 @@ function setupClaim() {
 		releaseClaim(attempt.acquired);
 	};
 }
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const sleep = (ms, signal) => new Promise((resolve) => {
+	const finish = () => {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", finish);
+		resolve();
+	};
+	const timer = setTimeout(finish, ms);
+	signal?.addEventListener("abort", finish, { once: true });
+	if (signal?.aborted) finish();
+});
 const binary = () => findTailscale(process.env);
 async function interruptible(work, signal) {
 	if (!signal) return work;
@@ -4276,6 +4829,7 @@ function defaultSetupDeps() {
 			if (!result.ok) throw new ServiceError(result.stderr.trim());
 		},
 		records: () => [...readBuildClients(), ...readDeviceHostClients()],
+		watchRecords: watchClientRegistries,
 		storeSecret: storeSetupSecret,
 		dropSecret: dropSetupSecret,
 		panes: hostPermissionPanes,
@@ -4580,7 +5134,7 @@ async function runSetup(args, version, deps) {
 				protocol: health?.protocol,
 				running: health !== null
 			}, version, !desktop);
-			const fix = desktop ? `If Stim Desktop runs this server, update Stim Desktop with Check for Updates in its app menu. Otherwise run npm install --global @stim-cli/server@${version} and restart the server.` : `stim-server service update --label ${opts.label} --release ${version}`;
+			const fix = desktop ? `If Stim Desktop runs this server, update Stim Desktop with Check for Updates in its app menu. Otherwise run npm install --global @stim-cli/server@${version} and restart the server.` : `stim-server service update --label ${opts.label} --release ${version}${opts.noWait ? " --no-wait" : ""}`;
 			if (decision === "too-old") throw new SetupRefusal(`This server predates setup support (${current?.version} speaks protocol ${health?.protocol ?? 1}; setup needs protocol ${SETUP_PROTOCOL}). ${desktop ? "Update and restart the app's server, then rerun setup." : "Update the service, then rerun setup."}`, false, fix);
 			if (decision === "update") {
 				if (!installed?.script || !installed.node || installed.port === null) throw new SetupRefusal("The managed service has no usable server invocation.");
@@ -4589,7 +5143,7 @@ async function runSetup(args, version, deps) {
 					script: installed.script,
 					node: installed.node,
 					port: installed.port
-				}, { release: version }, chatter))) chatter(note);
+				}, { release: version }, chatter, !opts.noWait))) chatter(note);
 				installed = await wait(deps.installed(opts.label));
 				const updated = await wait(deps.health(opts.port));
 				if (!updated) throw new SetupRefusal("The updated server is not answering.");
@@ -4712,12 +5266,28 @@ async function runSetup(args, version, deps) {
 			approved.push(capability);
 		}
 		if (approved.length && deps.now() < Date.parse(opts.expiresAt)) {
-			deps.storeSecret(opts.ticket, approved, opts.expiresAt, deps.now());
-			secretStored = true;
-			while (deps.now() < Date.parse(opts.expiresAt)) {
-				for (const grant of recorded(approved)) note(grant, false);
-				if (approved.every((c) => journal.granted.some((g) => g.capability === c))) break;
-				await wait(deps.sleep(Math.min(1e3, Math.max(0, Date.parse(opts.expiresAt) - deps.now()))));
+			let changed = false;
+			let sleeping;
+			const stopWatching = deps.watchRecords(() => {
+				changed = true;
+				sleeping?.abort();
+			});
+			try {
+				deps.storeSecret(opts.ticket, approved, opts.expiresAt, deps.now());
+				secretStored = true;
+				if (deps.fromDoctor) printer.line("Waiting for the requesting machine to reconnect. Run `stim doctor` on that machine to finish.");
+				while (deps.now() < Date.parse(opts.expiresAt)) {
+					changed = false;
+					for (const grant of recorded(approved)) note(grant, false);
+					if (approved.every((c) => journal.granted.some((g) => g.capability === c))) break;
+					if (changed) continue;
+					sleeping = new AbortController();
+					await wait(deps.sleep(Math.min(1e3, Math.max(0, Date.parse(opts.expiresAt) - deps.now())), sleeping.signal));
+					sleeping = void 0;
+				}
+			} finally {
+				sleeping?.abort();
+				stopWatching();
 			}
 		}
 		step("approve", journal.granted.length === opts.capabilities.length ? "ok" : "pending", "Access approval", journal.granted.length === opts.capabilities.length ? "Chosen capabilities approved." : "Missing approval: builds or hosted simulators will not work. Generate a new command after expiry.", void 0, approvalView(journal.granted.length === opts.capabilities.length));
@@ -4798,7 +5368,7 @@ const ERROR_REPEAT_MS = 6e4;
 const MAX_REMEMBERED = 256;
 /** One token of a service-log line: no whitespace or control characters, so a client cannot forge another field or line. */
 const printable = (value) => String(value).replace(/[^\x21-\x7e]+/g, "_").slice(0, 80);
-const text = (fields) => Object.entries(fields).filter(([, value]) => value !== void 0 && value !== null).map(([key, value]) => `${key}=${printable(value)}`).join(" ");
+const text$1 = (fields) => Object.entries(fields).filter(([, value]) => value !== void 0 && value !== null).map(([key, value]) => `${key}=${printable(value)}`).join(" ");
 /**
 * Request timing for stim-server. An error reply always goes to the service log (stderr), once a minute per
 * client, method and code. With debug logging on, every request goes to the service log and to
@@ -4859,21 +5429,165 @@ function createRequestLog({ service = (line) => console.error(line), debug = cre
 						error: code
 					};
 					if (debug.enabled()) {
-						service(`stim-server: debug request ${text(fields)}`);
+						service(`stim-server: debug request ${text$1(fields)}`);
 						const { run, ...rest } = fields;
 						debug.log("request", {
 							...rest,
 							runId: run
 						});
-					} else if (code !== void 0 && errorDue(`${client.id}|${method}|${code}`)) service(`stim-server: request failed ${text(fields)}`);
+					} else if (code !== void 0 && errorDue(`${client.id}|${method}|${code}`)) service(`stim-server: request failed ${text$1(fields)}`);
 				}
 			};
 		},
 		host(event, fields, failed = false) {
 			if (debug.enabled()) {
-				service(`stim-server: debug ${event} ${text(fields)}`);
+				service(`stim-server: debug ${event} ${text$1(fields)}`);
 				debug.log(event, fields);
-			} else if (failed && errorDue(`host|${event}|${String(fields.host)}`)) service(`stim-server: ${event} ${text(fields)}`);
+			} else if (failed && errorDue(`host|${event}|${String(fields.host)}`)) service(`stim-server: ${event} ${text$1(fields)}`);
+		}
+	};
+}
+//#endregion
+//#region src/platform-run.ts
+const nativeText = [
+	"slot",
+	"remoteBuild",
+	"remote",
+	"easProfile"
+];
+const nativeBoolean = ["metroCheck", "buildCache"];
+const iosText = [
+	"configuration",
+	"scheme",
+	"deviceType",
+	"runtime",
+	"simulatorApp"
+];
+const androidText = [
+	"variant",
+	"systemImage",
+	"deviceProfile"
+];
+function text(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= 1024 && !value.includes("\0");
+}
+function optionalText(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function optionalBoolean(value) {
+	return typeof value === "boolean" ? value : void 0;
+}
+function selector(value) {
+	return typeof value === "string" || typeof value === "boolean" ? value : void 0;
+}
+function parsePlatformRun(params) {
+	if (!isJsonObject(params) || Object.keys(params).some((key) => key !== "cwd" && key !== "options") || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || !isJsonObject(params.options)) return null;
+	const { cwd, options } = params;
+	const { platform } = options;
+	if (platform !== "ios" && platform !== "android" && platform !== "macos" && platform !== "web") return null;
+	const texts = platform === "ios" ? [...nativeText, ...iosText] : platform === "android" ? [...nativeText, ...androidText] : platform === "macos" ? ["remote", "remoteBuild"] : [];
+	const booleans = platform === "ios" || platform === "android" ? nativeBoolean : platform === "web" ? ["headed"] : [];
+	for (const [key, value] of Object.entries(options)) {
+		if (key === "platform") continue;
+		if (texts.includes(key) ? !text(value) : booleans.includes(key) ? typeof value !== "boolean" : (platform === "ios" || platform === "android") && (key === "device" || key === "wait") ? typeof value !== "boolean" && !text(value) : true) return null;
+	}
+	if (platform === "web") return {
+		cwd,
+		options: {
+			platform,
+			headed: optionalBoolean(options.headed)
+		}
+	};
+	if (platform === "macos") return {
+		cwd,
+		options: {
+			platform,
+			remote: optionalText(options.remote),
+			remoteBuild: optionalText(options.remoteBuild)
+		}
+	};
+	const native = {
+		slot: optionalText(options.slot),
+		metroCheck: optionalBoolean(options.metroCheck),
+		buildCache: optionalBoolean(options.buildCache),
+		remoteBuild: optionalText(options.remoteBuild),
+		remote: optionalText(options.remote),
+		easProfile: optionalText(options.easProfile),
+		device: selector(options.device),
+		wait: selector(options.wait)
+	};
+	return platform === "ios" ? {
+		cwd,
+		options: {
+			...native,
+			platform,
+			configuration: optionalText(options.configuration),
+			scheme: optionalText(options.scheme),
+			deviceType: optionalText(options.deviceType),
+			runtime: optionalText(options.runtime),
+			simulatorApp: optionalText(options.simulatorApp)
+		}
+	} : {
+		cwd,
+		options: {
+			...native,
+			platform,
+			variant: optionalText(options.variant),
+			systemImage: optionalText(options.systemImage),
+			deviceProfile: optionalText(options.deviceProfile)
+		}
+	};
+}
+//#endregion
+//#region src/platform-build.ts
+function parsePlatformBuild(params) {
+	if (!isJsonObject(params) || Object.keys(params).some((key) => key !== "cwd" && key !== "options") || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || !isJsonObject(params.options)) return null;
+	const { cwd, options } = params;
+	const { platform } = options;
+	if (platform !== "ios" && platform !== "android" && platform !== "macos") return null;
+	const texts = platform === "ios" ? [
+		"configuration",
+		"scheme",
+		"remoteBuild"
+	] : platform === "android" ? ["variant", "remoteBuild"] : ["remoteBuild"];
+	for (const [key, value] of Object.entries(options)) {
+		if (key === "platform" || platform === "ios" && key === "arch" || platform === "android" && key === "abi") continue;
+		if (texts.includes(key) ? typeof value !== "string" || value.length === 0 || value.length > 1024 || value.includes("\0") : platform !== "macos" && key === "buildCache" ? typeof value !== "boolean" : true) return null;
+	}
+	const remoteBuild = typeof options.remoteBuild === "string" ? options.remoteBuild : void 0;
+	if (platform === "macos") return {
+		cwd,
+		options: {
+			platform,
+			remoteBuild
+		}
+	};
+	const buildCache = typeof options.buildCache === "boolean" ? options.buildCache : void 0;
+	if (platform === "ios") {
+		const { arch } = options;
+		if (arch !== void 0 && arch !== "arm64" && arch !== "x86_64" && arch !== "all") return null;
+		return {
+			cwd,
+			options: {
+				platform,
+				remoteBuild,
+				buildCache,
+				arch,
+				configuration: typeof options.configuration === "string" ? options.configuration : void 0,
+				scheme: typeof options.scheme === "string" ? options.scheme : void 0
+			}
+		};
+	}
+	const { abi } = options;
+	if (abi !== void 0 && abi !== "arm64-v8a" && abi !== "armeabi-v7a" && abi !== "x86" && abi !== "x86_64" && abi !== "all") return null;
+	return {
+		cwd,
+		options: {
+			platform,
+			remoteBuild,
+			buildCache,
+			abi,
+			variant: typeof options.variant === "string" ? options.variant : void 0
 		}
 	};
 }
@@ -13037,7 +13751,7 @@ function readFailure(cause) {
 	return `${cause.code}: ${cause.message}${cause.remedy ? ` ${cause.remedy}` : ""}`;
 }
 function stopAction(cwd, env, limits, options = {}) {
-	const root = realpathSync(cwd);
+	let root = realpathSync(cwd);
 	if (!lstatSync(root).isDirectory()) throw new Error("The workspace is not a directory.");
 	let stderr = "";
 	const client = createStim({
@@ -13064,7 +13778,11 @@ function stopAction(cwd, env, limits, options = {}) {
 	});
 	const drained = Promise.resolve().then(() => client.stop({
 		slot: options.slot,
-		signal: abort.signal
+		signal: abort.signal,
+		beforeStop: (workspace) => {
+			options.beforeStop?.(workspace);
+			root = workspace;
+		}
 	})).then((result) => {
 		const stdout = JSON.stringify({
 			root,
@@ -13086,7 +13804,8 @@ function stopAction(cwd, env, limits, options = {}) {
 		};
 	}, (cause) => ({
 		ok: false,
-		message: readFailure(cause)
+		message: readFailure(cause),
+		...cause instanceof StimError ? { code: cause.code } : {}
 	})).finally(() => clearTimeout(timer));
 	return {
 		outcome: Promise.race([drained, deadline]),
@@ -13160,34 +13879,199 @@ function reloadAction(cwd, env, limits, options = {}) {
 		}
 	};
 }
-function isLoopback(address) {
-	return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
-}
-/**
-* The tailnet address of the peer. `tailscale serve` proxies from loopback and names the peer in
-* X-Forwarded-For; a loopback connection without that header comes from this machine.
-*/
-function peerAddress(request) {
-	const remote = request.socket.remoteAddress;
-	if (!isLoopback(remote)) return remote ?? null;
-	const forwarded = request.headers["x-forwarded-for"];
-	return (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(",")[0]?.trim() || null;
-}
-function peerLabel(identity) {
-	return identity ? `${identity.name || identity.id}${identity.user ? ` (${identity.user})` : ""}` : null;
-}
-const NO_TAILSCALE = {
-	state: "unavailable",
-	reason: "the tailscale command was not found"
-};
-function serverTransports(options) {
-	const tailscale = options.transports?.find(isTailscaleTransport) ?? tailscaleTransport({
-		env: options.env,
-		snapshot: {
-			binary: options.tailscale ?? null,
-			state: options.tailscaleState ?? NO_TAILSCALE
-		},
-		monitor: options.tailscaleMonitor ?? null
+function lifecycleAction(cwd, env, limits, label, timeoutCode, execute, onProgress) {
+	const abort = new AbortController();
+	let bytes = 0;
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		abort.abort();
+	}, limits.timeoutMs);
+	const drained = Promise.resolve().then(() => execute(createStim({
+		projectRoot: cwd,
+		env,
+		onProgress: (progress) => {
+			bytes += Buffer.byteLength(progress.message);
+			if (bytes > limits.maxOutputBytes) throw new StimError({
+				code: "STIM_OUTPUT_LIMIT",
+				message: `${label} printed more than ${limits.maxOutputBytes} bytes.`
+			});
+			onProgress?.(progress);
+		}
+	}), abort.signal)).then((result) => result, (cause) => {
+		const details = cause instanceof StimError && isJsonObject(cause.details) ? cause.details.cause : void 0;
+		return {
+			ok: false,
+			message: readFailure(cause),
+			...cause instanceof StimError ? {
+				code: cause.code,
+				stdout: JSON.stringify({
+					code: cause.code,
+					message: cause.message,
+					remedy: cause.remedy
+				}),
+				unresolved: cause.code === "STIM_CLAIM_UNAVAILABLE",
+				...isJsonObject(details) && Array.isArray(details.retainedClaimRoots) && details.retainedClaimRoots.every((root) => typeof root === "string" && isAbsolute(root)) ? { retainedClaimRoots: details.retainedClaimRoots } : {}
+			} : {}
+		};
+	}).then((outcome) => !outcome.unresolved && bytes + Buffer.byteLength(outcome.stdout ?? "") > limits.maxOutputBytes ? {
+		ok: false,
+		code: "STIM_OUTPUT_LIMIT",
+		unresolved: outcome.unresolved,
+		retainedClaimRoots: outcome.retainedClaimRoots,
+		message: `${label} printed more than ${limits.maxOutputBytes} bytes.`
+	} : outcome).then((outcome) => timedOut && !outcome.unresolved ? {
+		ok: false,
+		code: timeoutCode,
+		message: `${label} did not finish within ${limits.timeoutMs / 1e3} s.`
+	} : outcome).finally(() => clearTimeout(timer));
+	return {
+		outcome: drained,
+		drained,
+		cancel: async () => {
+			abort.abort();
+			return await drained;
+		}
+	};
+}
+function startAction(cwd, env, limits, options = {}) {
+	return lifecycleAction(cwd, env, limits, "stim start", "STIM_METRO_TIMEOUT", async (client, signal) => {
+		const result = await client.start({
+			remote: options.remote,
+			resetCache: options.resetCache,
+			waitSeconds: options.waitSeconds,
+			beforeStart: options.beforeStart,
+			signal
+		});
+		return {
+			ok: true,
+			stdout: JSON.stringify(result),
+			summary: `Dev server ${result.alreadyRunning ? "already running" : "ready"} on port ${result.port}.`
+		};
+	}, options.onProgress);
+}
+function platformRunAction(cwd, env, limits, options, onProgress) {
+	return lifecycleAction(cwd, env, limits, `stim ${options.platform}`, "STIM_RUN_FAILED", async (client, signal) => {
+		const result = await client.run({
+			...options,
+			signal
+		});
+		const summary = result.platform === "web" ? `${result.facts.url} ${result.facts.launched === true ? "loaded" : result.facts.launched}. ${result.facts.running ? "Logs: stim logs --errors." : "The owned Chrome is no longer running. Run stim logs --errors, then stim web again."}` : `${options.platform} run completed.`;
+		return {
+			ok: true,
+			stdout: JSON.stringify(result),
+			summary
+		};
+	}, onProgress);
+}
+function platformBuildAction(cwd, env, limits, options, onProgress) {
+	return lifecycleAction(cwd, env, limits, `${options.platform} build`, "STIM_BUILD_FAILED", async (client, signal) => {
+		const result = await client.build({
+			...options,
+			signal
+		});
+		return {
+			ok: true,
+			stdout: JSON.stringify(result),
+			summary: `${options.platform} build completed.`
+		};
+	}, onProgress);
+}
+function gcAction(cwd, env, limits, options, onProgress) {
+	return lifecycleAction(cwd, env, limits, "stim gc", "STIM_GC_TIMEOUT", async (client, signal) => {
+		const { report, exitCode } = await client.collectGarbage({
+			...options,
+			signal
+		});
+		const stdout = JSON.stringify(report);
+		return exitCode === 0 ? {
+			ok: true,
+			stdout,
+			summary: "Garbage collection completed."
+		} : {
+			ok: false,
+			stdout,
+			code: "STIM_GC_FAILED",
+			message: "Garbage collection reported failures."
+		};
+	}, onProgress);
+}
+function machineAccessAction(cwd, env, limits, ticket, onProgress) {
+	return lifecycleAction(cwd, env, limits, "Machine access request", "STIM_REPORT_TIMEOUT", async (client, signal) => ({
+		ok: true,
+		stdout: JSON.stringify(await client.requestMachineAccess({
+			ticket,
+			signal
+		})),
+		summary: "Machine access report completed."
+	}), onProgress);
+}
+function worktreeWarmAction(cwd, env, limits, options, onProgress) {
+	return lifecycleAction(cwd, env, limits, "stim worktree warm", "STIM_WORKTREE_WARM_TIMEOUT", async (client, signal) => {
+		const result = await client.warmWorktree({
+			...options,
+			signal
+		});
+		const stdout = JSON.stringify(result);
+		return result.exitCode === 0 ? {
+			ok: true,
+			stdout,
+			summary: "Worktree warming completed."
+		} : {
+			ok: false,
+			stdout,
+			code: "STIM_WORKTREE_WARM_FAILED",
+			message: "Worktree warming reported failures."
+		};
+	}, onProgress);
+}
+function worktreeRemoveAction(cwd, env, limits, options, onProgress) {
+	return lifecycleAction(cwd, env, limits, "stim worktree remove", "STIM_WORKTREE_REMOVE_TIMEOUT", async (client, signal) => {
+		const result = await client.removeWorktree({
+			...options,
+			signal
+		});
+		const stdout = JSON.stringify(result);
+		return result.exitCode === 0 ? {
+			ok: true,
+			stdout,
+			summary: "Worktree cleanup completed."
+		} : {
+			ok: false,
+			stdout,
+			code: "STIM_WORKTREE_REMOVE_FAILED",
+			message: "Worktree cleanup reported failures."
+		};
+	}, onProgress);
+}
+function isLoopback(address) {
+	return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}
+/**
+* The tailnet address of the peer. `tailscale serve` proxies from loopback and names the peer in
+* X-Forwarded-For; a loopback connection without that header comes from this machine.
+*/
+function peerAddress(request) {
+	const remote = request.socket.remoteAddress;
+	if (!isLoopback(remote)) return remote ?? null;
+	const forwarded = request.headers["x-forwarded-for"];
+	return (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(",")[0]?.trim() || null;
+}
+function peerLabel(identity) {
+	return identity ? `${identity.name || identity.id}${identity.user ? ` (${identity.user})` : ""}` : null;
+}
+const NO_TAILSCALE = {
+	state: "unavailable",
+	reason: "the tailscale command was not found"
+};
+function serverTransports(options) {
+	const tailscale = options.transports?.find(isTailscaleTransport) ?? tailscaleTransport({
+		env: options.env,
+		snapshot: {
+			binary: options.tailscale ?? null,
+			state: options.tailscaleState ?? NO_TAILSCALE
+		},
+		monitor: options.tailscaleMonitor ?? null
 	});
 	return {
 		transports: options.transports ?? [tailscale],
@@ -13263,6 +14147,9 @@ function buildAllowed(session) {
 function requestId(value) {
 	return typeof value === "number" || typeof value === "string" ? value : null;
 }
+function validPlanRequest(value) {
+	return typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
 function registeredWorkspace(workspace) {
 	if (typeof workspace !== "string") return {
 		code: "bad-request",
@@ -13481,6 +14368,7 @@ async function startServer(options) {
 		...options.actionLimits
 	};
 	const busyWorkspaces = /* @__PURE__ */ new Set();
+	const retainedLifecycles = /* @__PURE__ */ new Set();
 	const planQueues = /* @__PURE__ */ new Map();
 	const readDetailsReport = (method, cwd = homedir(), platform) => {
 		const abort = new AbortController();
@@ -13791,6 +14679,7 @@ async function startServer(options) {
 		const replays = /* @__PURE__ */ new Map();
 		let keyframeReads = 0;
 		const commands = /* @__PURE__ */ new Set();
+		const planRequests = /* @__PURE__ */ new Map();
 		const persistentActions = /* @__PURE__ */ new Set();
 		let nextSubscription = 1;
 		let device = null;
@@ -13874,7 +14763,19 @@ async function startServer(options) {
 					},
 					...options.host ? { host } : {},
 					capabilities: device.capabilities,
-					features: protocol_exports.FEATURES.filter((feature) => (!["desktop-settings-write", "desktop-reload"].includes(feature) || options.desktopBootstrap !== void 0) && (local || ![
+					features: protocol_exports.FEATURES.filter((feature) => (![
+						"desktop-settings-write",
+						"desktop-reload",
+						"desktop-start",
+						"desktop-run",
+						"desktop-build",
+						"desktop-gc",
+						"desktop-worktree-remove",
+						"desktop-worktree-warm",
+						"desktop-machine-access",
+						"desktop-plan"
+					].includes(feature) || options.desktopBootstrap !== void 0) && (local || ![
+						"desktop-plan",
 						"desktop-reports",
 						"desktop-report-platform",
 						"desktop-settings",
@@ -13882,7 +14783,14 @@ async function startServer(options) {
 						"desktop-full-logs",
 						"desktop-doctor-run",
 						"desktop-stop",
-						"desktop-reload"
+						"desktop-reload",
+						"desktop-start",
+						"desktop-run",
+						"desktop-build",
+						"desktop-gc",
+						"desktop-worktree-remove",
+						"desktop-worktree-warm",
+						"desktop-machine-access"
 					].includes(feature))),
 					actions: device.capabilities.includes("control") ? [...protocol_exports.ACTIONS] : [],
 					device: {
@@ -14561,54 +15469,6 @@ async function startServer(options) {
 			});
 			subscriptions.set(subscription, cleanup);
 		}
-		function command(id, args, cwd, result, limits = commandLimits, turn = null) {
-			if (commands.size >= MAX_COMMANDS) {
-				error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
-				return null;
-			}
-			let run = null;
-			let dropped = false;
-			let release;
-			const released = new Promise((resolve) => {
-				release = resolve;
-			});
-			const cancel = async () => {
-				dropped = true;
-				if (!run) return void (turn ?? Promise.resolve()).then(release);
-				await run.cancel();
-				release();
-			};
-			const start = async () => {
-				if (dropped) return;
-				run = runStim(options.stimCli, options.env, args, cwd, limits);
-				const outcome = await run.outcome;
-				commands.delete(cancel);
-				running.delete(cancel);
-				try {
-					if (!outcome.ok) {
-						const printed = actionOutcome(outcome);
-						return error(id, "stim-failed", printed.ok ? outcome.message : printed.error.message);
-					}
-					let value;
-					try {
-						value = result(outcome.stdout);
-					} catch {
-						return error(id, "stim-failed", `stim ${args[0]} printed output that is not JSON.`);
-					}
-					send(socket, {
-						id,
-						result: value
-					});
-				} finally {
-					release();
-				}
-			};
-			commands.add(cancel);
-			running.add(cancel);
-			if (turn) turn.then(start);
-			else start();
-			return released;
-		}
 		function archiveRead(id, read) {
 			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
 			let dropped = false;
@@ -14674,15 +15534,22 @@ async function startServer(options) {
 				running.delete(cancel);
 			});
 		}
-		function inProcessRead(id, label, read, timeoutMs = commandLimits.timeoutMs) {
-			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+		function inProcessRead(id, label, read, timeoutMs = commandLimits.timeoutMs, turn = null) {
+			if (commands.size >= MAX_COMMANDS) {
+				error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+				return null;
+			}
 			const abort = new AbortController();
-			const deadline = setTimeout(() => {
-				if (abort.signal.aborted) return;
-				abort.abort();
-				error(id, "stim-failed", `${label} did not finish within ${timeoutMs / 1e3} s.`);
-			}, timeoutMs);
-			const task = Promise.resolve(abort.signal).then(read).then((result) => {
+			let deadline;
+			const task = Promise.resolve(turn).then(() => {
+				abort.signal.throwIfAborted();
+				deadline = setTimeout(() => {
+					if (abort.signal.aborted) return;
+					abort.abort();
+					error(id, "stim-failed", `${label} did not finish within ${timeoutMs / 1e3} s.`);
+				}, timeoutMs);
+				return read(abort.signal);
+			}).then((result) => {
 				if (abort.signal.aborted) return void 0;
 				if (Buffer.byteLength(JSON.stringify(result)) > commandLimits.maxOutputBytes) error(id, "stim-failed", `${label} printed more than ${commandLimits.maxOutputBytes} bytes.`);
 				else send(socket, {
@@ -14702,16 +15569,23 @@ async function startServer(options) {
 			};
 			commands.add(cancel);
 			running.add(cancel);
+			return {
+				done: task,
+				cancel
+			};
 		}
 		function workspaceCommand(id, method, params) {
 			if (params !== void 0 && !isJsonObject(params)) return error(id, "bad-request", "params must be an object.");
 			const cwd = workspaceDir(id, params?.workspace, false);
 			if (!cwd) return;
-			if (method === "settings.get") return inProcessRead(id, "stim settings", (signal) => createStim({
-				projectRoot: cwd,
-				env: options.env
-			}).settings({ signal }));
-			return inProcessRead(id, "stim stats", (signal) => createStim({
+			if (method === "settings.get") {
+				inProcessRead(id, "stim settings", (signal) => createStim({
+					projectRoot: cwd,
+					env: options.env
+				}).settings({ signal }));
+				return;
+			}
+			inProcessRead(id, "stim stats", (signal) => createStim({
 				projectRoot: cwd,
 				env: options.env
 			}).stats({ signal }));
@@ -14767,7 +15641,16 @@ async function startServer(options) {
 			let admittedCwd = resolved.dir;
 			let run;
 			try {
-				run = action.action === "stop" ? stopAction(resolved.dir, options.env, actionLimits) : reloadAction(resolved.dir, options.env, actionLimits, {
+				run = action.action === "stop" ? stopAction(resolved.dir, options.env, actionLimits, { beforeStop: (workspace) => {
+					if (workspace === resolved.dir) return;
+					if (busyWorkspaces.has(workspace)) throw new StimError({
+						code: "STIM_ACTION_BUSY",
+						message: `An action is already running in ${workspace}.`
+					});
+					busyWorkspaces.add(workspace);
+					admittedCwd = workspace;
+					record.workspace = clip(workspace);
+				} }) : reloadAction(resolved.dir, options.env, actionLimits, {
 					platform: action.platform,
 					beforeReload: (workspace) => {
 						if (workspace === resolved.dir) return;
@@ -14854,6 +15737,7 @@ async function startServer(options) {
 			const subscription = openSubscription(id);
 			if (!subscription) return;
 			const startedAt = Date.now();
+			let admittedCwd = cwd;
 			const slot = typeof params.slot === "string" ? params.slot : void 0;
 			let observing = true;
 			let terminal;
@@ -14875,6 +15759,15 @@ async function startServer(options) {
 			try {
 				run = stopAction(cwd, options.env, actionLimits, {
 					slot,
+					beforeStop: (workspace) => {
+						if (workspace === cwd) return;
+						if (busyWorkspaces.has(workspace)) throw new StimError({
+							code: "STIM_ACTION_BUSY",
+							message: `An action is already running in ${workspace}.`
+						});
+						busyWorkspaces.add(workspace);
+						admittedCwd = workspace;
+					},
 					onProgress: (progress) => {
 						if (!observing) return;
 						outputBytes += Buffer.byteLength(progress.message);
@@ -14911,6 +15804,7 @@ async function startServer(options) {
 			run.drained.then((outcome) => {
 				running.delete(cancel);
 				busyWorkspaces.delete(cwd);
+				busyWorkspaces.delete(admittedCwd);
 				const recorded = terminal ?? outcome;
 				auditSafely({
 					at: new Date(startedAt).toISOString(),
@@ -14919,7 +15813,7 @@ async function startServer(options) {
 						name: owner.name
 					},
 					action: "stop",
-					workspace: cwd,
+					workspace: admittedCwd,
 					...slot === void 0 ? {} : { slot },
 					ok: recorded.ok,
 					durationMs: Date.now() - startedAt,
@@ -15016,6 +15910,193 @@ async function startServer(options) {
 				});
 			});
 		}
+		function subscribeStart(id, params, owner) {
+			if (!isJsonObject(params) || Object.keys(params).some((key) => ![
+				"cwd",
+				"remote",
+				"resetCache",
+				"waitSeconds"
+			].includes(key)) || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || params.remote !== void 0 && typeof params.remote !== "boolean" || params.resetCache !== void 0 && typeof params.resetCache !== "boolean" || params.waitSeconds !== void 0 && (typeof params.waitSeconds !== "number" || !Number.isSafeInteger(params.waitSeconds) || params.waitSeconds <= 0)) return error(id, "bad-request", "Start requires an absolute cwd, optional remote/resetCache booleans, and a positive whole waitSeconds.");
+			const remote = typeof params.remote === "boolean" ? params.remote : void 0;
+			const resetCache = typeof params.resetCache === "boolean" ? params.resetCache : void 0;
+			const waitSeconds = typeof params.waitSeconds === "number" ? params.waitSeconds : void 0;
+			subscribeLifecycle(id, params.cwd, owner, "start", (cwd, beforeStart, onProgress) => startAction(cwd, options.env, actionLimits, {
+				remote,
+				resetCache,
+				waitSeconds,
+				beforeStart,
+				onProgress
+			}));
+		}
+		function subscribeRun(id, params, owner) {
+			const parsed = parsePlatformRun(params);
+			if (!parsed) return error(id, "bad-request", "Run requires an absolute cwd and valid platform options.");
+			const limits = {
+				...actionLimits,
+				timeoutMs: options.actionLimits?.timeoutMs ?? 36e5
+			};
+			subscribeLifecycle(id, parsed.cwd, owner, "run", (cwd, _beforeRun, onProgress) => platformRunAction(cwd, options.env, limits, parsed.options, onProgress), parsed.options.platform);
+		}
+		function subscribeBuild(id, params, owner) {
+			const parsed = parsePlatformBuild(params);
+			if (!parsed) return error(id, "bad-request", "Build requires an absolute cwd and valid artifact-only options.");
+			const limits = {
+				...actionLimits,
+				timeoutMs: options.actionLimits?.timeoutMs ?? 36e5
+			};
+			subscribeLifecycle(id, parsed.cwd, owner, "build", (cwd, _beforeBuild, onProgress) => platformBuildAction(cwd, options.env, limits, parsed.options, onProgress), parsed.options.platform);
+		}
+		function subscribeGc(id, params, owner) {
+			if (!desktopSessions.has(socket)) return error(id, "forbidden", "Garbage collection requires the connection of the Stim Desktop that started this server.");
+			if (!isJsonObject(params) || Object.keys(params).some((key) => ![
+				"cwd",
+				"cache",
+				"olderThan",
+				"worktrees",
+				"delete",
+				"idleMs"
+			].includes(key)) || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || params.cache !== void 0 && (typeof params.cache !== "string" || !params.cache.trim() || params.cache.length > 1024) || params.olderThan !== void 0 && (typeof params.olderThan !== "number" || !Number.isSafeInteger(params.olderThan)) || params.worktrees !== void 0 && typeof params.worktrees !== "boolean" || params.delete !== void 0 && typeof params.delete !== "boolean" || params.idleMs !== void 0 && (typeof params.idleMs !== "number" || !Number.isSafeInteger(params.idleMs) || params.idleMs <= 0)) return error(id, "bad-request", "GC requires an absolute cwd and valid cache, age, worktree, delete and idle selectors.");
+			const request = {
+				cache: typeof params.cache === "string" ? params.cache : void 0,
+				olderThan: typeof params.olderThan === "number" ? params.olderThan : void 0,
+				worktrees: typeof params.worktrees === "boolean" ? params.worktrees : void 0,
+				delete: typeof params.delete === "boolean" ? params.delete : void 0,
+				idleMs: typeof params.idleMs === "number" ? params.idleMs : void 0
+			};
+			subscribeLifecycle(id, params.cwd, owner, "gc", (cwd, _admit, onProgress) => gcAction(cwd, options.env, actionLimits, request, onProgress));
+		}
+		function subscribeMachineAccess(id, params, owner) {
+			if (!desktopSessions.has(socket)) return error(id, "forbidden", "Requesting machine access requires the connection of the Stim Desktop that started this server.");
+			if (!isJsonObject(params) || Object.keys(params).some((key) => key !== "cwd" && key !== "ticket") || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || params.ticket !== void 0 && (typeof params.ticket !== "string" || !decodeSecret(params.ticket))) return error(id, "bad-request", "Machine access requires an absolute cwd and an optional valid setup ticket.");
+			const ticket = typeof params.ticket === "string" ? params.ticket : void 0;
+			subscribeLifecycle(id, params.cwd, owner, "machine-access", (cwd, _admit, onProgress) => machineAccessAction(cwd, options.env, actionLimits, ticket, onProgress));
+		}
+		function subscribeWorktreeWarm(id, params, owner) {
+			if (!desktopSessions.has(socket)) return error(id, "forbidden", "Warming worktrees requires the connection of the Stim Desktop that started this server.");
+			if (!isJsonObject(params) || Object.keys(params).some((key) => key !== "cwd") || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd)) return error(id, "bad-request", "Worktree warming requires only an absolute cwd.");
+			const limits = {
+				...actionLimits,
+				timeoutMs: options.actionLimits?.timeoutMs ?? 54e5
+			};
+			subscribeLifecycle(id, params.cwd, owner, "worktree-warm", (cwd, beforeWarm, onProgress) => worktreeWarmAction(cwd, options.env, limits, { beforeWarm }, onProgress));
+		}
+		function subscribeWorktreeRemove(id, params, owner) {
+			if (!desktopSessions.has(socket)) return error(id, "forbidden", "Removing worktrees requires the connection of the Stim Desktop that started this server.");
+			if (!isJsonObject(params) || Object.keys(params).some((key) => ![
+				"cwd",
+				"target",
+				"force"
+			].includes(key)) || typeof params.cwd !== "string" || params.cwd.length > 4096 || params.cwd.includes("\0") || !isAbsolute(params.cwd) || params.target !== void 0 && (typeof params.target !== "string" || params.target.length > 4096 || params.target.includes("\0") || !isAbsolute(params.target)) || params.force !== void 0 && typeof params.force !== "boolean") return error(id, "bad-request", "Worktree removal requires an absolute cwd, optional absolute target and boolean force.");
+			const request = {
+				target: typeof params.target === "string" ? params.target : void 0,
+				force: typeof params.force === "boolean" ? params.force : void 0
+			};
+			subscribeLifecycle(id, params.cwd, owner, "worktree-remove", (cwd, beforeRemove, onProgress) => worktreeRemoveAction(cwd, options.env, actionLimits, {
+				...request,
+				beforeRemove
+			}, onProgress));
+		}
+		function subscribeLifecycle(id, requestedCwd, owner, kind, begin, platform) {
+			let cwd;
+			try {
+				cwd = realpathSync(requestedCwd);
+				if (!lstatSync(cwd).isDirectory()) throw new Error("The workspace is not a directory.");
+			} catch (cause) {
+				return error(id, "bad-request", `Cannot ${kind} this workspace: ${readFailure(cause)}`);
+			}
+			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (busyWorkspaces.has(cwd)) return error(id, "action-busy", `An action is already running in ${cwd}.`);
+			const subscription = openSubscription(id);
+			if (!subscription) return;
+			const startedAt = Date.now();
+			let admittedCwd = cwd;
+			const admittedWorkspaces = /* @__PURE__ */ new Set();
+			let observing = true;
+			let terminal;
+			const finish = (outcome) => {
+				terminal ??= outcome;
+				if (!observing) return;
+				observing = false;
+				subscriptions.delete(subscription);
+				send(socket, {
+					event: `desktop-${kind}-ended`,
+					subscription,
+					exitCode: outcome.ok ? 0 : 1,
+					stdout: outcome.stdout ?? "",
+					message: outcome.ok ? outcome.summary : outcome.message
+				});
+			};
+			const run = begin(cwd, (workspace) => {
+				if (admittedWorkspaces.has(workspace)) return;
+				if (workspace !== cwd && busyWorkspaces.has(workspace)) throw new StimError({
+					code: "STIM_ACTION_BUSY",
+					message: `An action is already running in ${workspace}.`
+				});
+				if (admittedWorkspaces.size === 0) admittedCwd = workspace;
+				admittedWorkspaces.add(workspace);
+				busyWorkspaces.add(workspace);
+			}, (progress) => {
+				if (observing) send(socket, {
+					event: `desktop-${kind}-progress`,
+					subscription,
+					...progress
+				});
+			});
+			const cancel = async () => {
+				await run.cancel();
+			};
+			commands.add(cancel);
+			running.add(cancel);
+			busyWorkspaces.add(cwd);
+			subscriptions.set(subscription, async () => {
+				observing = false;
+				const outcome = await run.cancel();
+				if (!outcome.ok && outcome.unresolved) return {
+					code: "action-failed",
+					message: outcome.message
+				};
+			});
+			run.outcome.then(finish);
+			run.drained.then((outcome) => {
+				if (kind === "gc" || kind === "worktree-remove" || kind === "worktree-warm" || kind === "machine-access") desktopReports.invalidate();
+				const release = () => {
+					commands.delete(cancel);
+					running.delete(cancel);
+					busyWorkspaces.delete(cwd);
+					for (const workspace of admittedWorkspaces) busyWorkspaces.delete(workspace);
+				};
+				const roots = outcome.retainedClaimRoots;
+				if (outcome.unresolved) {
+					const reconcile = () => {
+						if (!roots?.length) return;
+						if (roots.some((root) => {
+							const claims = readClaimSet(root);
+							return claims.live.length > 0 || claims.unresolved.length > 0;
+						})) return;
+						release();
+						retainedLifecycles.delete(reconcile);
+					};
+					retainedLifecycles.add(reconcile);
+				} else release();
+				const recorded = terminal ?? outcome;
+				auditSafely({
+					at: new Date(startedAt).toISOString(),
+					device: {
+						id: owner.id,
+						name: owner.name
+					},
+					action: kind,
+					workspace: admittedCwd,
+					...platform ? { platform } : {},
+					ok: recorded.ok,
+					durationMs: Date.now() - startedAt,
+					...recorded.ok ? {} : { error: {
+						code: "action-failed",
+						message: outcome.unresolved ? "STIM_CLAIM_UNAVAILABLE" : recorded.code || (kind === "start" ? "STIM_METRO_START_FAILED" : kind === "gc" ? "STIM_GC_FAILED" : kind === "build" ? "STIM_BUILD_FAILED" : "STIM_RUN_FAILED")
+					} }
+				});
+			});
+		}
 		function writeDesktopSetting(id, params, owner) {
 			if (!isJsonObject(params) || typeof params.cwd !== "string" || !isAbsolute(params.cwd) || params.cwd.length > 4096 || params.cwd.includes("\0") || typeof params.key !== "string" || params.key.length === 0 || params.key.length > 256 || params.action !== "set" && params.action !== "unset" || (params.action === "set" ? typeof params.value !== "string" : "value" in params) || Object.keys(params).some((key) => ![
 				"cwd",
@@ -15396,23 +16477,46 @@ async function startServer(options) {
 			if (slot !== void 0 && (typeof slot !== "string" || !SLOT_NAME.test(slot))) return error(id, "bad-request", "params.slot must be 1-64 letters, digits, underscores or hyphens.");
 			const cwd = workspaceDir(id, params.workspace, true);
 			if (!cwd) return;
-			const finished = command(id, [
+			queuePlan(id, cwd, {
 				platform,
-				"--plan",
-				"--json",
-				...slot === void 0 ? [] : [`--slot=${slot}`]
-			], cwd, (stdout) => {
-				const value = JSON.parse(stdout);
-				if (!isJsonObject(value) || value.platform !== platform) throw new Error("not a plan");
-				return value;
-			}, {
-				...commandLimits,
-				timeoutMs: options.commandLimits?.timeoutMs ?? PLAN_TIMEOUT_MS
-			}, planQueues.get(cwd) ?? null);
+				...slot === void 0 ? {} : { slot }
+			}, "build.plan");
+		}
+		function queuePlan(id, cwd, plan, method, request) {
+			if (request !== void 0 && planRequests.size >= MAX_COMMANDS) {
+				error(id, "limit-exceeded", "Acknowledge retained plan refusals before requesting more previews.");
+				return;
+			}
+			let unresolved;
+			const finished = inProcessRead(id, `stim ${plan.platform}`, async (signal) => {
+				try {
+					return await createStim({
+						projectRoot: cwd,
+						env: options.env
+					}).plan({
+						...plan,
+						signal
+					});
+				} catch (cause) {
+					if (method !== "desktop.plan.get" || !(cause instanceof StimError)) throw cause;
+					const refusal = {
+						code: cause.code,
+						message: cause.message,
+						remedy: cause.remedy
+					};
+					if (cause.code === "STIM_CLAIM_UNAVAILABLE") unresolved = refusal;
+					return refusal;
+				}
+			}, options.commandLimits?.timeoutMs ?? PLAN_TIMEOUT_MS, planQueues.get(cwd) ?? null);
 			if (!finished) return;
-			planQueues.set(cwd, finished);
-			finished.finally(() => {
-				if (planQueues.get(cwd) === finished) planQueues.delete(cwd);
+			planQueues.set(cwd, finished.done);
+			if (request !== void 0) planRequests.set(request, {
+				cancel: finished.cancel,
+				refusal: () => unresolved
+			});
+			finished.done.finally(() => {
+				if (planQueues.get(cwd) === finished.done) planQueues.delete(cwd);
+				if (request !== void 0 && planRequests.get(request)?.cancel === finished.cancel && !unresolved) planRequests.delete(request);
 			});
 		}
 		function registerPush(id, params, session) {
@@ -15441,7 +16545,7 @@ async function startServer(options) {
 		async function buildMethod(id, method, params, session) {
 			if (!buildAllowed(session)) return error(id, "forbidden", `${method} needs build access, which this machine has not granted this device.`);
 			buildSession ??= builds.session(session.id, socket, (event) => send(socket, event));
-			const answer = method === "build.offer" ? await builds.offer(session.id, params) : method === "build.sync" ? buildSession.sync(params) : method === "build.start" ? await buildSession.start(params) : method === "build.cancel" ? buildSession.cancel(params) : method === "build.attach" ? buildSession.attach(params) : method === "build.cached-artifact" ? await buildSession.cachedArtifact(params) : await buildSession.artifact(params);
+			const answer = method === "build.offer" ? await builds.offer(session.id, params, buildSession.signal) : method === "build.sync" ? buildSession.sync(params) : method === "build.start" ? await buildSession.start(params) : method === "build.cancel" ? buildSession.cancel(params) : method === "build.attach" ? buildSession.attach(params) : method === "build.cached-artifact" ? await buildSession.cachedArtifact(params) : await buildSession.artifact(params);
 			send(socket, "error" in answer ? {
 				id,
 				error: answer.error
@@ -15464,10 +16568,19 @@ async function startServer(options) {
 				"desktop.settings.write",
 				"desktop.logs.subscribe",
 				"desktop.doctor.run",
+				"desktop.machine-access.subscribe",
 				"desktop.stop.subscribe",
-				"desktop.reload.subscribe"
+				"desktop.reload.subscribe",
+				"desktop.start.subscribe",
+				"desktop.run.subscribe",
+				"desktop.build.subscribe",
+				"desktop.gc.subscribe",
+				"desktop.worktree.remove.subscribe",
+				"desktop.worktree.warm.subscribe",
+				"desktop.plan.get",
+				"desktop.plan.cancel"
 			].includes(method)) return null;
-			if (!local || options.desktopBootstrap !== void 0 && !desktopSessions.has(socket)) return Promise.resolve(error(id, "forbidden", method === "route.setup" ? "Phone connection setup requires the connection of the Stim Desktop that started this server." : method === "desktop.doctor.run" ? "Running project doctor requires the connection of the Stim Desktop that started this server." : method === "desktop.settings.write" ? "Changing settings requires the connection of the Stim Desktop that started this server." : method === "desktop.reload.subscribe" ? "Reloading apps requires the connection of the Stim Desktop that started this server." : method === "desktop.stop.subscribe" ? "Stopping workspaces requires the connection of the Stim Desktop that started this server." : method.startsWith("desktop.") ? "Desktop reads require the connection of the Stim Desktop that started this server." : method.startsWith("device-host.sessions") ? "Listing or stopping hosted sessions requires the connection of the Stim Desktop that started this server." : "Updating another machine requires the connection of the Stim Desktop that started this server."));
+			if (!local || options.desktopBootstrap !== void 0 && !desktopSessions.has(socket)) return Promise.resolve(error(id, "forbidden", method === "route.setup" ? "Phone connection setup requires the connection of the Stim Desktop that started this server." : method === "desktop.doctor.run" ? "Running project doctor requires the connection of the Stim Desktop that started this server." : method === "desktop.settings.write" ? "Changing settings requires the connection of the Stim Desktop that started this server." : method === "desktop.reload.subscribe" ? "Reloading apps requires the connection of the Stim Desktop that started this server." : method === "desktop.build.subscribe" ? "Building artifacts requires the connection of the Stim Desktop that started this server." : method === "desktop.run.subscribe" ? "Running apps requires the connection of the Stim Desktop that started this server." : method === "desktop.start.subscribe" ? "Starting dev servers requires the connection of the Stim Desktop that started this server." : method === "desktop.stop.subscribe" ? "Stopping workspaces requires the connection of the Stim Desktop that started this server." : method.startsWith("desktop.") ? "Desktop operations require the connection of the Stim Desktop that started this server." : method.startsWith("device-host.sessions") ? "Listing or stopping hosted sessions requires the connection of the Stim Desktop that started this server." : "Updating another machine requires the connection of the Stim Desktop that started this server."));
 			if (method === "desktop.settings.write") {
 				if (!desktopSessions.has(socket)) {
 					error(id, "forbidden", "Changing settings requires the connection of the Stim Desktop that started this server.");
@@ -15484,6 +16597,93 @@ async function startServer(options) {
 				subscribeReload(id, params, owner);
 				return Promise.resolve();
 			}
+			if (method === "desktop.plan.cancel") {
+				if (!desktopSessions.has(socket)) {
+					error(id, "forbidden", "Cancelling a plan requires the connection of the Stim Desktop that started this server.");
+					return Promise.resolve();
+				}
+				if (!isJsonObject(params) || Object.keys(params).length !== 1 || !validPlanRequest(params.request)) {
+					error(id, "bad-request", "Choose the request of this connection to cancel.");
+					return Promise.resolve();
+				}
+				const request = params.request;
+				const pending = planRequests.get(request);
+				(async () => {
+					await pending?.cancel();
+					const refusal = pending?.refusal();
+					if (planRequests.get(request) === pending) planRequests.delete(request);
+					send(socket, {
+						id,
+						result: {
+							cancelled: pending !== void 0,
+							...refusal ? { refusal } : {}
+						}
+					});
+				})();
+				return Promise.resolve();
+			}
+			if (method === "desktop.plan.get") {
+				if (!desktopSessions.has(socket)) {
+					error(id, "forbidden", "Planning builds requires the connection of the Stim Desktop that started this server.");
+					return Promise.resolve();
+				}
+				if (!isJsonObject(params) || Object.keys(params).some((key) => key !== "cwd" && key !== "platform" && key !== "slot" && key !== "request") || typeof params.cwd !== "string" || params.cwd.length > 4096 || !isAbsolute(params.cwd) || params.request !== void 0 && !validPlanRequest(params.request) || params.platform !== "ios" && params.platform !== "android" && params.platform !== "macos" || params.slot !== void 0 && (params.platform === "macos" || typeof params.slot !== "string" || !SLOT_NAME.test(params.slot))) {
+					error(id, "bad-request", "Choose an absolute cwd and ios/android/macos platform; slot applies only to ios/android.");
+					return Promise.resolve();
+				}
+				if (typeof params.request === "string" && planRequests.has(params.request)) {
+					error(id, "bad-request", "This connection already has a plan with that request.");
+					return Promise.resolve();
+				}
+				let cwd;
+				try {
+					cwd = realpathSync(params.cwd);
+					if (!lstatSync(cwd).isDirectory()) throw new Error("not a directory");
+				} catch {
+					error(id, "bad-request", "Choose an existing project directory.");
+					return Promise.resolve();
+				}
+				const plan = params.platform === "macos" ? { platform: "macos" } : {
+					platform: params.platform,
+					...params.slot === void 0 ? {} : { slot: params.slot }
+				};
+				queuePlan(id, cwd, plan, "desktop.plan.get", typeof params.request === "string" ? params.request : void 0);
+				return Promise.resolve();
+			}
+			const subscribeCleanup = {
+				"desktop.machine-access.subscribe": subscribeMachineAccess,
+				"desktop.gc.subscribe": subscribeGc,
+				"desktop.worktree.remove.subscribe": subscribeWorktreeRemove,
+				"desktop.worktree.warm.subscribe": subscribeWorktreeWarm
+			}[method];
+			if (subscribeCleanup) {
+				subscribeCleanup(id, params, owner);
+				return Promise.resolve();
+			}
+			if (method === "desktop.build.subscribe") {
+				if (!desktopSessions.has(socket)) {
+					error(id, "forbidden", "Building artifacts requires the connection of the Stim Desktop that started this server.");
+					return Promise.resolve();
+				}
+				subscribeBuild(id, params, owner);
+				return Promise.resolve();
+			}
+			if (method === "desktop.run.subscribe") {
+				if (!desktopSessions.has(socket)) {
+					error(id, "forbidden", "Running apps requires the connection of the Stim Desktop that started this server.");
+					return Promise.resolve();
+				}
+				subscribeRun(id, params, owner);
+				return Promise.resolve();
+			}
+			if (method === "desktop.start.subscribe") {
+				if (!desktopSessions.has(socket)) {
+					error(id, "forbidden", "Starting dev servers requires the connection of the Stim Desktop that started this server.");
+					return Promise.resolve();
+				}
+				subscribeStart(id, params, owner);
+				return Promise.resolve();
+			}
 			if (method === "desktop.stop.subscribe") {
 				subscribeStop(id, params, owner);
 				return Promise.resolve();
@@ -15552,11 +16752,14 @@ async function startServer(options) {
 				cwd: resolve(String(params.cwd)),
 				...params.platform === "ios" || params.platform === "android" ? { platform: params.platform } : {}
 			};
-			if (method === "desktop.reports.get") return inProcessRead(id, `stim ${target.report}`, async (signal) => {
-				const snapshot = await desktopReports.get(target, signal);
-				if (snapshot.error) throw new Error(snapshot.error);
-				return snapshot;
-			}, options.commandLimits?.timeoutMs ?? DETAILS_TIMEOUT_MS);
+			if (method === "desktop.reports.get") {
+				inProcessRead(id, `stim ${target.report}`, async (signal) => {
+					const snapshot = await desktopReports.get(target, signal);
+					if (snapshot.error) throw new Error(snapshot.error);
+					return snapshot;
+				}, options.commandLimits?.timeoutMs ?? DETAILS_TIMEOUT_MS);
+				return;
+			}
 			const subscription = openSubscription(id);
 			if (!subscription) return;
 			subscriptions.set(subscription, desktopReports.subscribe(target, (snapshot) => send(socket, {
@@ -15687,17 +16890,7 @@ async function startServer(options) {
 					result: {}
 				});
 			}
-			if (method === "device-host.unsubscribe") {
-				const name = params.subscription;
-				const unsubscribe = typeof name === "string" ? subscriptions.get(name) : void 0;
-				if (!unsubscribe) return error(id, "unknown-subscription", `No subscription ${String(name)}.`);
-				unsubscribe();
-				subscriptions.delete(name);
-				return send(socket, {
-					id,
-					result: {}
-				});
-			}
+			if (method === "device-host.unsubscribe") return unsubscribeRequest(id, params.subscription);
 			if (method === "device-host.control.end") {
 				const name = params.session;
 				if (typeof name !== "string" || !control.endById(controller(session), name)) return error(id, "unknown-session", `No control session ${String(name)} on this connection.`);
@@ -15730,6 +16923,20 @@ async function startServer(options) {
 				result: { authorized: true }
 			});
 		}
+		async function unsubscribeRequest(id, name) {
+			if (typeof name !== "string") return error(id, "unknown-subscription", `No subscription ${String(name)}.`);
+			const unsubscribe = subscriptions.get(name);
+			if (!unsubscribe) return error(id, "unknown-subscription", `No subscription ${name}.`);
+			subscriptions.delete(name);
+			const failure = await unsubscribe();
+			send(socket, failure ? {
+				id,
+				error: failure
+			} : {
+				id,
+				result: {}
+			});
+		}
 		async function handle(raw) {
 			if (socket.readyState !== socket.OPEN) return;
 			let message;
@@ -15753,6 +16960,7 @@ async function startServer(options) {
 			if (message.method === "hello") return hello(id, message.params);
 			if (!device) return refuse(id, "unauthorized", "Send hello first.", CLOSE_REFUSED);
 			if (message.method === "desktop.authenticate") return authenticateDesktop(id, message.params);
+			for (const reconcile of retainedLifecycles) reconcile();
 			if (protocol_exports.DEVICE_HOST_METHODS.includes(message.method)) {
 				if (!device.capabilities.includes("device-host")) return error(id, "forbidden", "Explicit device-host approval is required.");
 				return hostedMethod(id, message.method, message.params, device);
@@ -15889,23 +17097,7 @@ async function startServer(options) {
 					result: {}
 				});
 			}
-			if (message.method === "unsubscribe") {
-				const name = isJsonObject(message.params) ? message.params.subscription : void 0;
-				const unsubscribe = typeof name === "string" ? subscriptions.get(name) : void 0;
-				if (!unsubscribe) return send(socket, {
-					id,
-					error: {
-						code: "unknown-subscription",
-						message: `No subscription ${String(name)}.`
-					}
-				});
-				subscriptions.delete(name);
-				unsubscribe();
-				return send(socket, {
-					id,
-					result: {}
-				});
-			}
+			if (message.method === "unsubscribe") return unsubscribeRequest(id, isJsonObject(message.params) ? message.params.subscription : void 0);
 			send(socket, {
 				id,
 				error: {
@@ -16448,7 +17640,7 @@ const USAGE = `Usage:
                                     --env and --path-prepend apply after the login shell's environment
   STIM_SETUP_TICKET=<t> stim-server setup --expires <iso>
                     [--build] [--device-host] [--port <n>] [--label <name>]
-                    [--env KEY=VALUE]... [--path-prepend <dir>]... [--yes] [--json] [--verbose]
+                    [--env KEY=VALUE]... [--path-prepend <dir>]... [--yes] [--json] [--verbose] [--no-wait]
                                     worker-side approval of the machine holding this ticket, until expiry
   stim-server service install [--port <n>] [--label <name>] [--serve]
                               [--env KEY=VALUE]... [--path-prepend <dir>]...
@@ -16456,10 +17648,11 @@ const USAGE = `Usage:
                                     a Linux systemd user service, or a Windows scheduled task;
                                     --serve adds a tailnet-only \`tailscale serve\` route
   stim-server service status [--label <name>] [--json]
-  stim-server service update [--label <name>] --release <version>|--from <dir>
+  stim-server service update [--label <name>] [--no-wait] --release <version>|--from <dir>
                                     install that stim-server release from npm, or the .tgz
                                     packages in <dir>, beside the current one, switch the
                                     service to it, and switch back if it does not answer
+                                    --no-wait interrupts active builds and hosted sessions at restart
   stim-server service rollback [--label <name>]
                                     switch the service back to the server it ran before
   stim-server service uninstall [--label <name>]
@@ -16643,6 +17836,7 @@ async function runService(sub, extra, values, env, pathPrepend) {
 		"uninstall"
 	].includes(sub ?? "")) fail(`unknown command.\n${USAGE}`);
 	if (sub !== "update" && (values.release !== void 0 || values.from !== void 0)) fail(`--release and --from apply only to \`service update\`.\n${USAGE}`);
+	if (sub !== "update" && values["no-wait"]) fail(`--no-wait applies only to \`service update\`.\n${USAGE}`);
 	if (sub !== "install" && (values.serve || values.port !== void 0 || values.env || values["path-prepend"])) fail(`--port, --serve, --env and --path-prepend apply only to \`service install\`.\n${USAGE}`);
 	if (sub !== "status" && values.json) fail(`--json applies only to \`service status\`.\n${USAGE}`);
 	try {
@@ -16670,7 +17864,7 @@ async function runService(sub, extra, values, env, pathPrepend) {
 			const from = values.from === void 0 ? null : resolve(values.from);
 			if (from !== null && !statSync(from, { throwIfNoEntry: false })?.isDirectory()) fail(`--from takes a directory of .tgz packages, got ${values.from}.`);
 			const source = from === null ? { release: values.release } : { from };
-			for (const line of await updateService(label, source, (progress) => console.log(progress))) console.log(line);
+			for (const line of await updateService(label, source, (progress) => console.log(progress), !values["no-wait"])) console.log(line);
 		} else if (sub === "rollback") for (const line of await rollbackService(label, (progress) => console.log(progress))) console.log(line);
 		else for (const line of await uninstallService(label)) console.log(line);
 	} catch (error) {
@@ -16685,11 +17879,14 @@ async function setup() {
 	process.on("SIGINT", interrupt);
 	process.on("SIGTERM", interrupt);
 	const ticket = process.env.STIM_SETUP_TICKET;
+	const fromDoctor = process.env.STIM_SETUP_ORIGIN === "doctor";
 	delete process.env.STIM_SETUP_TICKET;
+	delete process.env.STIM_SETUP_ORIGIN;
 	try {
 		process.exitCode = await runSetup(process.argv.slice(3), pkg.version, {
 			...defaultSetupDeps(),
 			ticket,
+			fromDoctor,
 			signal: controller.signal
 		});
 	} finally {
@@ -16722,6 +17919,7 @@ async function main() {
 			},
 			release: { type: "string" },
 			from: { type: "string" },
+			"no-wait": { type: "boolean" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -16747,6 +17945,7 @@ async function main() {
 	}
 	if ((values.label !== void 0 || values.serve) && !service) fail(`--label and --serve apply only to \`service\`.\n${USAGE}`);
 	if ((values.release !== void 0 || values.from !== void 0) && !service) fail(`--release and --from apply only to \`service update\`.\n${USAGE}`);
+	if (values["no-wait"] && !service) fail(`--no-wait applies only to \`service update\` or \`setup\`.\n${USAGE}`);
 	if (values["loopback-only"] && command !== void 0) fail(`--loopback-only applies only to serving.\n${USAGE}`);
 	if (command === void 0) return serve(port, extraEnv, pathPrepend, values["loopback-only"] === true);
 	const grant = command === "devices" && sub === "grant";