@stim-cli/server 1.25.0 → 1.26.0

package/README.md

@@ -93,7 +93,7 @@ it appends the default Node of nvm, fnm, Volta, mise or asdf, Homebrew,
 `JAVA_HOME` to a Homebrew `openjdk` (17, then 21, then the newest), else Android
 Studio's bundled runtime, when no JDK is installed under
 `/Library/Java/JavaVirtualMachines`. It never replaces a variable it was given,
-and its own Node's directory is always the last `PATH` entry. CocoaPods uses the
+and its own Node's directory is always the last `PATH` entry. The build host repeats this discovery for each build offer, toolchain read and build start, so a tool installed after the server started, such as Homebrew's directory, a JDK or the Android SDK, is found without a restart, within the minute the toolchain report is cached. A `PATH` line added to a shell profile is never read. CocoaPods uses the
 project's `.ruby-version` Ruby, else rvm's or rbenv's default Ruby, and reads the
 login shell only when neither exists. Anything else a shell profile sets, such as
 `STIM_*` variables, reaches the server only through its environment or `--env`.
@@ -275,7 +275,9 @@ reports without starting a CLI process. `desktop.reports.get` takes
 Doctor accepts a selected folder before it is registered with Stim. The result is
 `{ "pending": false, "value": { ... }, "measuredAt": "..." }`; a failed read
 returns `stim-failed`. Doctor never repairs the project or records a CLI run, and
-GC never deletes anything.
+GC never deletes anything. The GC report, here and in `machine.details`, takes
+worktree build-state sizes only from the disk-usage cache and runs no `du` for
+them; a stale size is `null`.
 
 The local-only `desktop-report-platform` feature adds an optional `"platform": "ios"`
 or `"platform": "android"` to doctor targets. Omitting it checks all selected platforms.
@@ -291,12 +293,17 @@ Active subscriptions refresh after 60 seconds; no refresh timer runs without
 subscribers. `unsubscribe` and disconnect remove the subscription. Cancelling a
 get request does not cancel another reader's shared work.
 
-After changing settings, running an action, or explicitly refreshing a view,
-Desktop calls `desktop.reports.invalidate` without parameters. This invalidates
-all report targets and refreshes active subscriptions. Results started before
-invalidation cannot replace a newer result or satisfy a waiting get. The existing
-request and subscription caps, report byte quota, API execution and cleanup
-budgets, and 150-second server limit apply. At most four shared report probes run
+`desktop.reports.invalidate` without parameters invalidates all report targets
+and refreshes active subscriptions. With the local-only
+`desktop-report-invalidate-target` feature it also takes a report target, as
+`desktop.reports.get` does, and invalidates only that target, so a fresh read
+of one report does not restart the others. Results started before
+invalidation cannot replace a newer result or satisfy a waiting get; invalidation
+aborts such a probe, so a waiting get waits only for the fresh one. A waiting get
+does not use one of the connection's request slots: a connection can wait for 16
+reports at a time, and more fail with `limit-exceeded`. The subscription cap,
+report byte quota, API execution and cleanup budgets, and 150-second server limit
+apply. At most four shared report probes run
 at once across connections and targets. A new target above that limit returns a
 busy error without starting or queuing work; invalidate and retry after a probe
 finishes. Unsubscribing does not release a probe's slot before it drains.
@@ -359,7 +366,10 @@ person approves does setup store the ticket's derived PSK and lookup in
 gets `unknown-secret`, and its `stim doctor` reports the machine as pending and
 tries again on every run. The requester's next first-contact handshake with the
 ticket records its public key once per approved capability, which spends the
-ticket. From then on the ticket admits only that key, until it expires, so a
+ticket. While it waits, setup says so ("Waiting for the requesting machine to
+connect. Stim Desktop sends this automatically.", or the `stim doctor`
+instruction for a Doctor-made command) and confirms each approval when it
+arrives. From then on the ticket admits only that key, until it expires, so a
 requester that lost the reply can retry; setup deletes an unspent secret when it
 ends. Build and
 device-host approvals are separate records. A build grant carries no `read` or
@@ -1360,7 +1370,10 @@ event loop. Until that read returns, `/health` answers HTTP 503 with
 requests get 503, and no status follower, native helper, file watcher or
 recorder starts. A read that does not return within 10 seconds, plus up to one
 second to stop the child, leaves the server listening with
-`startup: { "state": "degraded", "reason": "..." }` and HTTP 503 on `/health`,
+`startup: { "state": "degraded", "reason": "...", "cause": "home-unreadable" }`
+(`start-failed` when starting failed after the read returned) and HTTP 503 on
+`/health` (a tailnet peer sees only `{ "version", "startup": { "state",
+"cause" } }`, because the reason names the Stim home path),
 logs the reason once, and reads again every 30 seconds. When a read returns,
 the server starts its watchers and recorder, `/health` answers 200 with
 `startup: { "state": "ready" }`, and no restart is needed. `service status`
@@ -1621,9 +1634,14 @@ connected since stim-server started keeps its directory when revoked.
   `arch`; `xcode`; `simulatorSdk`; `macosSdk` (from
   `xcrun --sdk macosx --show-sdk-version`); `cocoapods`; `runtimes`, the simulator
   runtimes with an iPhone simulator to build for; `jdk`, the major version of
-  the JDK in `JAVA_HOME` or the macOS default; and `androidSdk`, the `ndk`,
+  the JDK in `JAVA_HOME` or the macOS default; `jdks`, the majors of every JDK it finds
+  (`JAVA_HOME`, the system JVM directories, Homebrew, Android Studio's JBR, SDKMAN), the default included; `developerDir` (what `xcode-select -p` prints) and `xcodeApps` (the Xcode apps in
+  `/Applications` with `version`, `build` and, while `xcode` is null, the `license` and `firstLaunch` checks of each), on a Mac; and `androidSdk`, the `ndk`,
   `buildTools` and `platforms` directories of the SDK in `ANDROID_HOME`, else `~/Library/Android/sdk` on macOS or
-  `~/Android/Sdk` on Linux, null without one), `capacity` and `warm`
+  `~/Android/Sdk` on Linux, null without one), `androidHome` (that directory) and
+  `androidLicenses` (whether `licenses/android-sdk-license` in it has content, so
+  Gradle can download a missing package; both absent from a server older than
+  them, and from a worker without an SDK), `capacity` and `warm`
   (`checkout`, `dependencies`, and the legacy `build` field, now always false)
   for that repository. For React Native and Expo builds, clients supporting `build-dependency-cache` can send
   `dependencies: { project, packageName }` alongside `lockfile`; the dependency
@@ -1715,7 +1733,9 @@ connected since stim-server started keeps its directory when revoked.
   simulator runtime identifier, required for `ios`, null for `android`),
   `fingerprint`, `packageName`, `isExpo`, `optimizations`, `android` (for
   `android`: `variant`, `abi`, `gradleBuildCache`, `pch` and `compilerCache`,
-  `ccache` or `none`), `stimBuild` and, from a caller that saw `build-compat`, `compat`, after the whole manifest of `repo` was
+  `ccache` or `none`), `stimBuild` and, from a caller that saw `build-compat`, `compat`, and, for Android from a caller
+  that saw `build-jdk`, `jdk` (the JDK major its Gradle runs on; the build runs with `JAVA_HOME` at an installed JDK of
+  that major, and fails if there is none), after the whole manifest of `repo` was
   synced on this connection. A peer-cache-capable React Native caller can set
   `cacheArtifact: true` to retain a completed development archive when its cache
   write and remote policies allow it. With the `fingerprint-sources` feature, a
@@ -1945,7 +1965,7 @@ Events are `{ "event", "subscription", ... }`.
   retained logs and agent-device session actions locally through core, with the same JSON filters, ordering,
   markers and error context. Archive reads are synchronous and queued per
   connection, yielding to the event loop between requests. Pending archive
-  reads share the four-request limit with commands. Archived session actions
+  reads share the connection's request limit with commands. Archived session actions
   retain available platform and device attribution; device ids and Stim slot
   assignments absent from retained files are unavailable after removal. They never follow files or use a hosted relay.
   An archive subscription sends its records in the same batches and limits,
@@ -2355,9 +2375,10 @@ Events are `{ "event", "subscription", ... }`.
 
 `workspace` is an environment `path` from a status payload. Any other path is
 refused with `unknown-workspace` and runs nothing. A connection holds at most
-32 subscriptions and runs at most 4 `logs.query`, `stats.get`,
+32 subscriptions and runs at most 32 `logs.query`, `stats.get`,
 `settings.get`, `build.plan`, `workspace.files` and `workspace.diff` requests at
-a time. `logs.query`, `stats.get` and `settings.get` fail after 60 seconds,
+a time, actions included. A tailnet device runs at most 16 across all its
+connections; more fail with `limit-exceeded`. `logs.query`, `stats.get` and `settings.get` fail after 60 seconds,
 `build.plan` after 150; these four fail at 32 MiB of output. Closing the
 connection stops running requests. When the command refuses with Stim's error
 contract on stdout, the `stim-failed` message is its code, message and remedy;

package/dist/{protocol-VEZO2CyR.mjs → protocol-nY-u8rtw.mjs}

@@ -2427,10 +2427,10 @@ function protocolJsonSchema() {
 				}),
 				request("desktop.reports.get", { $ref: "#/$defs/DesktopReportTarget" }),
 				request("desktop.reports.subscribe", { $ref: "#/$defs/DesktopReportTarget" }),
-				optionalParams("desktop.reports.invalidate", {
+				optionalParams("desktop.reports.invalidate", { oneOf: [{
 					type: "object",
 					maxProperties: 0
-				}),
+				}, { $ref: "#/$defs/DesktopReportTarget" }] }),
 				optionalParams("desktop.settings.schema", {
 					type: "object",
 					maxProperties: 0
@@ -3316,6 +3316,11 @@ function protocolJsonSchema() {
 						compat: {
 							...buildCompat,
 							description: "Compared instead of stimBuild by a machine whose build.offer toolchain reports compat."
+						},
+						jdk: {
+							type: "string",
+							pattern: "^[0-9]{1,3}$",
+							description: "The JDK major an Android build runs on, sent to a stim-server with the build-jdk feature."
 						}
 					}
 				}),

package/dist/protocol.mjs

@@ -1,3 +1,3 @@
-import { t as protocolJsonSchema } from "./protocol-VEZO2CyR.mjs";
+import { t as protocolJsonSchema } from "./protocol-nY-u8rtw.mjs";
 export * from "@stim-cli/core/protocol";
 export { protocolJsonSchema };

package/dist/protocol.schema.json

@@ -1281,9 +1281,11 @@
               "hosted-metro-ports",
               "server-update",
               "build-compat",
+              "build-jdk",
               "status-views",
               "desktop-reports",
               "desktop-report-platform",
+              "desktop-report-invalidate-target",
               "desktop-settings",
               "desktop-settings-schema",
               "desktop-settings-write",
@@ -4030,8 +4032,15 @@
               "const": "desktop.reports.invalidate"
             },
             "params": {
-              "type": "object",
-              "maxProperties": 0
+              "oneOf": [
+                {
+                  "type": "object",
+                  "maxProperties": 0
+                },
+                {
+                  "$ref": "#/$defs/DesktopReportTarget"
+                }
+              ]
             }
           }
         },
@@ -7688,6 +7697,11 @@
                   "type": "integer",
                   "minimum": 1,
                   "description": "Compared instead of stimBuild by a machine whose build.offer toolchain reports compat."
+                },
+                "jdk": {
+                  "type": "string",
+                  "pattern": "^[0-9]{1,3}$",
+                  "description": "The JDK major an Android build runs on, sent to a stim-server with the build-jdk feature."
                 }
               }
             }

package/dist/{stim-server-DowAx-6v.mjs → stim-server-DU1htjam.mjs}

@@ -1,4 +1,4 @@
-import { n as protocol_exports } from "./protocol-VEZO2CyR.mjs";
+import { n as protocol_exports } from "./protocol-nY-u8rtw.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";
@@ -661,16 +661,16 @@ function validateServeEnvironment(env, pathPrepend, serving = false) {
 * environment launchd gave the process; one that `source` lacks is skipped with a line on stderr. `STIM_HOME` and
 * `SHELL` entries are skipped the same way: the job takes them from the installing process.
 */
-function applyServeEnvironment(base, env, pathPrepend, source = process.env) {
+function applyServeEnvironment(base, env, pathPrepend, source = process.env, warn = console.error) {
 	const result = { ...base };
 	for (const entry of env) {
 		const parsed = parseEnvAssignment(entry);
 		const name = typeof parsed === "string" ? entry : parsed.key;
-		if (JOB_KEYS.includes(name)) console.error(`stim-server: ignoring --env ${name}; the service takes it from the process that installed it.`);
+		if (JOB_KEYS.includes(name)) warn(`stim-server: ignoring --env ${name}; the service takes it from the process that installed it.`);
 		else if (typeof parsed !== "string") result[name] = parsed.value;
 		else if (ENV_KEY_PATTERN.test(entry)) {
 			const value = source[entry];
-			if (value === void 0) console.error(`stim-server: --env ${entry} has no value in the service environment; skipping it.`);
+			if (value === void 0) warn(`stim-server: --env ${entry} has no value in the service environment; skipping it.`);
 			else result[entry] = value;
 		}
 	}
@@ -3457,6 +3457,9 @@ var BuildHost = class {
 			} catch {}
 		}
 	}
+	environment() {
+		return this.options.currentEnv?.() ?? this.options.env;
+	}
 	root() {
 		return buildWorkerRoot();
 	}
@@ -3472,7 +3475,7 @@ var BuildHost = class {
 		const value = new Promise((resolve) => {
 			const args = native ? [`offer-native-${native}`] : ["offer", ...rubyVersion ? [rubyVersion] : []];
 			const child = spawn(process.execPath, [this.options.worker, ...args], {
-				env: this.options.env,
+				env: this.environment(),
 				stdio: [
 					"ignore",
 					"pipe",
@@ -3548,7 +3551,7 @@ var BuildHost = class {
 			},
 			warm: {
 				checkout: existsSync(join(area, "src")),
-				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, params.lockfile, this.options.env),
+				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, params.lockfile, this.environment()),
 				build: false
 			},
 			...artifact !== void 0 ? { artifact } : {}
@@ -3559,7 +3562,7 @@ var BuildHost = class {
 	}
 	workerEnvironment(clientDir, area) {
 		return {
-			...this.options.env,
+			...this.environment(),
 			STIM_HOME: join(area, "home"),
 			CP_HOME_DIR: join(clientDir, "cache", "cocoapods-home"),
 			CP_CACHE_DIR: join(clientDir, "cache", "cocoapods"),
@@ -4373,6 +4376,7 @@ var BuildSession = class {
 				cacheArtifact: params.cacheArtifact === true,
 				stimBuild: params.stimBuild,
 				...compat !== void 0 && toolchain.compat !== void 0 ? { compat } : {},
+				...typeof params.jdk === "string" ? { jdk: params.jdk } : {},
 				configuration: optional(params.configuration),
 				scheme: optional(params.scheme),
 				iosProjectPath: optional(params.iosProjectPath),
@@ -4972,7 +4976,7 @@ function toolChecks(tools, stimBuild, platform) {
 		],
 		[
 			"Android SDK",
-			!!tools.androidSdk?.platforms.length && !!tools.androidSdk.buildTools.length && !!tools.androidSdk.ndk.length,
+			!!tools.androidSdk,
 			tools.androidSdk ? JSON.stringify(tools.androidSdk) : "Missing Android SDK",
 			platform === "linux" ? "Install the Android SDK in ~/Android/Sdk, or rerun setup with --env ANDROID_HOME=<sdk>" : platform === "win32" ? "Install the Android SDK in %LOCALAPPDATA%\\Android\\Sdk, or rerun setup with --env ANDROID_HOME=<sdk>" : "Install Android Studio or set ANDROID_HOME"
 		],
@@ -5314,7 +5318,8 @@ async function runSetup(args, version, deps) {
 			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.");
+				const waiting = deps.fromDoctor ? "Waiting for the requesting machine to reconnect. Run `stim doctor` on that machine to finish." : "Waiting for the requesting machine to connect. Stim Desktop sends this automatically.";
+				step("approve", "running", "Access approval", waiting, void 0, { running: waiting });
 				while (deps.now() < Date.parse(opts.expiresAt)) {
 					changed = false;
 					for (const grant of recorded(approved)) note(grant, false);
@@ -12136,6 +12141,7 @@ var UsageRecorder = class {
 //#endregion
 //#region src/desktop-reports.ts
 const MAX_REPORT_READS = 4;
+const reportKey = (target) => target.report === "gc" ? "gc" : `doctor:${target.platform ?? "all"}:${target.cwd}`;
 var DesktopReports = class {
 	entries = /* @__PURE__ */ new Map();
 	closed = false;
@@ -12206,9 +12212,13 @@ var DesktopReports = class {
 			}
 		};
 	}
-	invalidate() {
-		for (const entry of this.entries.values()) {
+	/** Invalidates `target`, or every target without one. */
+	invalidate(target) {
+		const only = target && this.entries.get(reportKey(target));
+		if (target && !only) return;
+		for (const entry of only ? [only] : this.entries.values()) {
 			entry.generation++;
+			entry.pending?.abort.abort();
 			clearTimeout(entry.timer);
 			entry.timer = void 0;
 			if (entry.listeners.size && !entry.pending) this.start(entry);
@@ -12224,7 +12234,7 @@ var DesktopReports = class {
 	}
 	entry(target) {
 		for (const [key, entry] of this.entries) if (!entry.readers && !entry.listeners.size && !entry.pending && (!entry.settled || this.now() - entry.settled.at >= this.ttlMs)) this.entries.delete(key);
-		const key = target.report === "gc" ? "gc" : `doctor:${target.platform ?? "all"}:${target.cwd}`;
+		const key = reportKey(target);
 		let entry = this.entries.get(key);
 		if (!entry) {
 			entry = {
@@ -12247,6 +12257,7 @@ var DesktopReports = class {
 		const admitted = this.activeLoads < MAX_REPORT_READS;
 		if (admitted) this.activeLoads++;
 		const generation = entry.generation;
+		const abort = new AbortController();
 		const pending = {
 			promise: Promise.resolve().then(() => {
 				if (this.closed) return {
@@ -12257,7 +12268,7 @@ var DesktopReports = class {
 					ok: false,
 					message: `The server is already running ${MAX_REPORT_READS} shared reports. Try again after a report finishes.`
 				};
-				return this.load(entry.target);
+				return this.load(entry.target, abort.signal);
 			}).catch((cause) => ({
 				ok: false,
 				message: cause instanceof Error ? cause.message : String(cause)
@@ -12278,7 +12289,8 @@ var DesktopReports = class {
 				this.publish(entry);
 				this.schedule(entry);
 			}),
-			generation
+			generation,
+			abort
 		};
 		entry.pending = pending;
 		this.publish(entry);
@@ -13787,7 +13799,12 @@ function lastCursor(page) {
 	return last ? archiveCursor(last) : null;
 }
 const STATUS_READ_WAIT_MS = 3e4;
-const MAX_COMMANDS = 4;
+const REQUEST_LIMITS = {
+	connection: 32,
+	device: 16
+};
+const MAX_REPORT_WAITS = 16;
+const MAX_RETAINED_PLANS = 4;
 function isWorkspaceChangeMethod(method) {
 	return method === "workspace.files" || method === "workspace.diff";
 }
@@ -14438,6 +14455,11 @@ async function startServer(options) {
 		return foldBuild;
 	};
 	const running = /* @__PURE__ */ new Set();
+	const peerCommands = /* @__PURE__ */ new Map();
+	const requestLimits = {
+		...REQUEST_LIMITS,
+		...options.requestLimits
+	};
 	const cancelling = new Pending();
 	const logLimits = {
 		...LOG_LIMITS,
@@ -14454,8 +14476,10 @@ async function startServer(options) {
 	const busyWorkspaces = /* @__PURE__ */ new Set();
 	const retainedLifecycles = /* @__PURE__ */ new Set();
 	const planQueues = /* @__PURE__ */ new Map();
-	const readDetailsReport = (method, cwd = homedir(), platform) => {
+	const readDetailsReport = (method, cwd = homedir(), platform, signal) => {
 		const abort = new AbortController();
+		if (signal?.aborted) abort.abort();
+		else signal?.addEventListener("abort", () => abort.abort(), { once: true });
 		const timeoutMs = options.commandLimits?.timeoutMs ?? DETAILS_TIMEOUT_MS;
 		let task;
 		const cancel = async () => {
@@ -14468,10 +14492,14 @@ async function startServer(options) {
 				projectRoot: cwd,
 				env: options.env
 			});
-			return method === "doctor" ? await stim.doctor({
+			if (method === "doctor") return await stim.doctor({
 				signal: abort.signal,
 				platform
-			}) : await stim[method]({ signal: abort.signal });
+			});
+			return method === "gc" ? await stim.gc({
+				signal: abort.signal,
+				measureBuildState: false
+			}) : await stim.stats({ signal: abort.signal });
 		}).then((report) => {
 			if (method !== "stats" && Buffer.byteLength(JSON.stringify(report)) > commandLimits.maxOutputBytes) return {
 				ok: false,
@@ -14491,7 +14519,7 @@ async function startServer(options) {
 		running.add(cancel);
 		return task;
 	};
-	const desktopReports = new DesktopReports((target) => readDetailsReport(target.report, target.report === "doctor" ? target.cwd : void 0, target.report === "doctor" ? target.platform : void 0));
+	const desktopReports = new DesktopReports((target, signal) => readDetailsReport(target.report, target.report === "doctor" ? target.cwd : void 0, target.report === "doctor" ? target.platform : void 0, signal));
 	const machineDetails = new MachineDetailsCache(() => loadMachineDetails(() => readDetailsReport("gc"), loadAudit, () => readDetailsReport("stats")));
 	const buildMachines = new BuildMachinesCache();
 	let recordingTurn = Promise.resolve();
@@ -14583,6 +14611,7 @@ async function startServer(options) {
 	const builds = new BuildHost({
 		worker: join(dirname(options.stimCli), "offload-worker.mjs"),
 		env: options.env,
+		currentEnv: options.currentEnv,
 		limits: options.buildLimits,
 		ready: () => startup.state === "ready",
 		finished: ({ client, repo, ok, error, durationMs }) => auditSafely({
@@ -14763,6 +14792,19 @@ async function startServer(options) {
 		const replays = /* @__PURE__ */ new Map();
 		let keyframeReads = 0;
 		const commands = /* @__PURE__ */ new Set();
+		const reportWaits = /* @__PURE__ */ new Set();
+		const holdSlot = (cancel) => {
+			commands.add(cancel);
+			if (peer !== null) peerCommands.set(peer, (peerCommands.get(peer) ?? 0) + 1);
+		};
+		const releaseSlot = (cancel) => {
+			if (!commands.delete(cancel) || peer === null) return;
+			const left = (peerCommands.get(peer) ?? 1) - 1;
+			if (left > 0) peerCommands.set(peer, left);
+			else peerCommands.delete(peer);
+		};
+		const slotsFull = (needed = 1) => commands.size + needed > requestLimits.connection || peer !== null && (peerCommands.get(peer) ?? 0) + needed > requestLimits.device;
+		const slotsMessage = (needed = 1) => peer !== null && commands.size + needed <= requestLimits.connection ? `A remote device can run ${requestLimits.device} requests at a time.` : `A connection can run ${requestLimits.connection} requests at a time.`;
 		const planRequests = /* @__PURE__ */ new Map();
 		const persistentActions = /* @__PURE__ */ new Set();
 		let nextSubscription = 1;
@@ -14862,6 +14904,7 @@ async function startServer(options) {
 						"desktop-plan",
 						"desktop-reports",
 						"desktop-report-platform",
+						"desktop-report-invalidate-target",
 						"desktop-settings",
 						"desktop-settings-schema",
 						"desktop-settings-write",
@@ -15555,18 +15598,18 @@ async function startServer(options) {
 			subscriptions.set(subscription, cleanup);
 		}
 		function archiveRead(id, read) {
-			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (slotsFull()) return error(id, "limit-exceeded", slotsMessage());
 			let dropped = false;
 			const cancel = async () => {
 				dropped = true;
 				await task;
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			const task = archiveReads.then(() => new Promise((resolve) => setImmediate(resolve))).then(() => {
 				if (!dropped && socket.readyState === socket.OPEN) return read();
 			}).finally(() => {
-				commands.delete(cancel);
+				releaseSlot(cancel);
 				running.delete(cancel);
 			});
 			archiveReads = task.catch(() => socket.close(1011, "internal error"));
@@ -15598,14 +15641,14 @@ async function startServer(options) {
 			if (!isJsonObject(params) || typeof params.workspace !== "string" || !params.workspace.length || params.workspace.length > 4096 || params.workspace.includes("\0") || !needsPath && params.group !== "changed" && params.group !== "untracked" || needsPath && (typeof params.path !== "string" || !params.path.length || params.path.length > 4096 || params.path.includes("\0")) || Object.keys(params).some((key) => key !== "workspace" && !(needsPath ? key === "path" : key === "group"))) return error(id, "bad-request", "Workspace diff requires workspace and, for a patch, a file path.");
 			const cwd = workspaceDir(id, params.workspace, true);
 			if (!cwd) return;
-			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (slotsFull()) return error(id, "limit-exceeded", slotsMessage());
 			const abort = new AbortController();
 			let task;
 			const cancel = async () => {
 				abort.abort();
 				await task;
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			task = readWorkspaceDiff(cwd, needsPath ? params.path : void 0, options.env, abort.signal, !needsPath ? params.group : void 0).then((result) => {
 				if (!abort.signal.aborted) send(socket, {
@@ -15615,13 +15658,13 @@ async function startServer(options) {
 			}, (cause) => {
 				if (!abort.signal.aborted) error(id, "stim-failed", cause.message);
 			}).finally(() => {
-				commands.delete(cancel);
+				releaseSlot(cancel);
 				running.delete(cancel);
 			});
 		}
-		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.`);
+		function inProcessRead(id, label, read, timeoutMs = commandLimits.timeoutMs, turn = null, report = false) {
+			if (report ? reportWaits.size >= MAX_REPORT_WAITS : slotsFull()) {
+				error(id, "limit-exceeded", report ? `A connection can wait for ${MAX_REPORT_WAITS} reports at a time.` : slotsMessage());
 				return null;
 			}
 			const abort = new AbortController();
@@ -15645,14 +15688,16 @@ async function startServer(options) {
 				if (!abort.signal.aborted) error(id, "stim-failed", readFailure(cause));
 			}).finally(() => {
 				clearTimeout(deadline);
-				commands.delete(cancel);
+				releaseSlot(cancel);
+				reportWaits.delete(cancel);
 				running.delete(cancel);
 			});
 			const cancel = async () => {
 				abort.abort();
 				await task;
 			};
-			commands.add(cancel);
+			if (report) reportWaits.add(cancel);
+			else holdSlot(cancel);
 			running.add(cancel);
 			return {
 				done: task,
@@ -15721,7 +15766,7 @@ async function startServer(options) {
 			const { action } = parsed;
 			const resolved = registeredWorkspace(action.workspace);
 			if ("code" in resolved) return refuseAction(resolved.code, resolved.message);
-			if (commands.size >= MAX_COMMANDS) return refuseAction("limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (slotsFull()) return refuseAction("limit-exceeded", slotsMessage());
 			if (busyWorkspaces.has(resolved.dir)) return refuseAction("action-busy", `An action is already running in ${resolved.dir}. Try again when it finishes.`);
 			let admittedCwd = resolved.dir;
 			let run;
@@ -15755,7 +15800,7 @@ async function startServer(options) {
 			let finished = false;
 			const release = (outcome) => {
 				if (outcome.unresolved) return;
-				commands.delete(cancel);
+				releaseSlot(cancel);
 				persistentActions.delete(cancel);
 				running.delete(cancel);
 				busyWorkspaces.delete(resolved.dir);
@@ -15793,7 +15838,7 @@ async function startServer(options) {
 				await run.cancel();
 				release(await run.drained);
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			persistentActions.add(cancel);
 			running.add(cancel);
 			run.outcome.then((outcome) => finish(!outcome.ok && "code" in outcome && outcome.code === "STIM_ACTION_BUSY" ? {
@@ -15920,7 +15965,7 @@ async function startServer(options) {
 			} catch (cause) {
 				return error(id, "bad-request", `Cannot reload 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 (slotsFull()) return error(id, "limit-exceeded", slotsMessage());
 			if (busyWorkspaces.has(cwd)) return error(id, "action-busy", `An action is already running in ${cwd}.`);
 			const subscription = openSubscription(id);
 			if (!subscription) return;
@@ -15961,7 +16006,7 @@ async function startServer(options) {
 				}
 			});
 			const cancel = () => run.cancel();
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			busyWorkspaces.add(cwd);
 			subscriptions.set(subscription, () => {
@@ -15971,7 +16016,7 @@ async function startServer(options) {
 			run.outcome.then(finish);
 			run.drained.then((outcome) => {
 				if (!outcome.unresolved) {
-					commands.delete(cancel);
+					releaseSlot(cancel);
 					running.delete(cancel);
 					busyWorkspaces.delete(cwd);
 					busyWorkspaces.delete(admittedCwd);
@@ -16089,7 +16134,7 @@ async function startServer(options) {
 			} 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 (slotsFull()) return error(id, "limit-exceeded", slotsMessage());
 			if (busyWorkspaces.has(cwd)) return error(id, "action-busy", `An action is already running in ${cwd}.`);
 			const subscription = openSubscription(id);
 			if (!subscription) return;
@@ -16130,7 +16175,7 @@ async function startServer(options) {
 			const cancel = async () => {
 				await run.cancel();
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			busyWorkspaces.add(cwd);
 			subscriptions.set(subscription, async () => {
@@ -16145,7 +16190,7 @@ async function startServer(options) {
 			run.drained.then((outcome) => {
 				if (kind === "gc" || kind === "worktree-remove" || kind === "worktree-warm" || kind === "machine-access") desktopReports.invalidate();
 				const release = () => {
-					commands.delete(cancel);
+					releaseSlot(cancel);
 					running.delete(cancel);
 					busyWorkspaces.delete(cwd);
 					for (const workspace of admittedWorkspaces) busyWorkspaces.delete(workspace);
@@ -16199,7 +16244,7 @@ async function startServer(options) {
 			} catch (cause) {
 				return error(id, "bad-request", `Cannot change settings here: ${readFailure(cause)}`);
 			}
-			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (slotsFull()) return error(id, "limit-exceeded", slotsMessage());
 			if (busyWorkspaces.has(cwd)) return error(id, "action-busy", `An action is already running in ${cwd}.`);
 			const { key, action } = params;
 			const value = typeof params.value === "string" ? params.value : void 0;
@@ -16287,7 +16332,7 @@ async function startServer(options) {
 				} });
 			}).finally(() => {
 				clearTimeout(deadline);
-				commands.delete(cancel);
+				releaseSlot(cancel);
 				running.delete(cancel);
 				busyWorkspaces.delete(cwd);
 				busyWorkspaces.delete(admittedCwd);
@@ -16313,7 +16358,7 @@ async function startServer(options) {
 				abort.abort();
 				await task;
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			busyWorkspaces.add(cwd);
 		}
@@ -16325,7 +16370,7 @@ async function startServer(options) {
 				abort.abort();
 				await task;
 			};
-			commands.add(cancel);
+			holdSlot(cancel);
 			running.add(cancel);
 			task = Promise.resolve().then(() => createStim({
 				projectRoot: cwd,
@@ -16335,7 +16380,7 @@ async function startServer(options) {
 				signal: abort.signal
 			})).then((records) => Buffer.byteLength(records.map((record) => JSON.stringify(record)).join("\n")) > commandLimits.maxOutputBytes ? `stim logs printed more than ${commandLimits.maxOutputBytes} bytes.` : records, (cause) => readFailure(cause)).finally(() => {
 				clearTimeout(deadline);
-				commands.delete(cancel);
+				releaseSlot(cancel);
 				running.delete(cancel);
 			});
 			return task;
@@ -16377,7 +16422,7 @@ async function startServer(options) {
 				archive
 			});
 			if (!cwd) return;
-			if (archive === void 0 && commands.size + 2 > MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			if (archive === void 0 && slotsFull(2)) return error(id, "limit-exceeded", slotsMessage(2));
 			const slotName = slot ?? "default";
 			const spans = recordedSpans(listSegments(recordingDir(workspace, platform, slotName, archive), archive !== void 0));
 			const replayTarget = {
@@ -16568,7 +16613,7 @@ async function startServer(options) {
 			}, "build.plan");
 		}
 		function queuePlan(id, cwd, plan, method, request) {
-			if (request !== void 0 && planRequests.size >= MAX_COMMANDS) {
+			if (request !== void 0 && planRequests.size >= MAX_RETAINED_PLANS) {
 				error(id, "limit-exceeded", "Acknowledge retained plan refusals before requesting more previews.");
 				return;
 			}
@@ -16831,8 +16876,7 @@ async function startServer(options) {
 			}).settings({ signal }));
 		}
 		function desktopReport(id, method, params) {
-			if (method === "desktop.reports.invalidate") {
-				if (params !== void 0 && (!isJsonObject(params) || Object.keys(params).length)) return error(id, "bad-request", "desktop.reports.invalidate takes no parameters.");
+			if (method === "desktop.reports.invalidate" && (params === void 0 || isJsonObject(params) && !Object.keys(params).length)) {
 				desktopReports.invalidate();
 				return send(socket, {
 					id,
@@ -16845,12 +16889,19 @@ async function startServer(options) {
 				cwd: resolve(String(params.cwd)),
 				...params.platform === "ios" || params.platform === "android" ? { platform: params.platform } : {}
 			};
+			if (method === "desktop.reports.invalidate") {
+				desktopReports.invalidate(target);
+				return send(socket, {
+					id,
+					result: {}
+				});
+			}
 			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);
+				}, options.commandLimits?.timeoutMs ?? DETAILS_TIMEOUT_MS, null, true);
 				return;
 			}
 			const subscription = openSubscription(id);
@@ -17222,12 +17273,14 @@ async function startServer(options) {
 			controllers.delete(socket);
 			for (const unsubscribe of subscriptions.values()) unsubscribe();
 			subscriptions.clear();
-			for (const cancel of commands) {
-				if (persistentActions.has(cancel)) continue;
+			for (const cancel of [...commands, ...reportWaits]) {
+				if (persistentActions.has(cancel)) {
+					releaseSlot(cancel);
+					continue;
+				}
 				running.delete(cancel);
 				cancelling.track(cancel());
 			}
-			commands.clear();
 		});
 	}
 	function upgrade(request, socket, head) {
@@ -17415,7 +17468,13 @@ async function startServer(options) {
 				return;
 			}
 			if (request.method === "GET" && request.url === "/health" && peerAddress(request) !== null && request.headers.origin === void 0 && request.headers["sec-fetch-site"] === void 0) {
-				const peerHealth = { version: health.version };
+				const peerHealth = {
+					version: health.version,
+					...startup.state === "ready" ? {} : { startup: startup.state === "degraded" ? {
+						state: "degraded",
+						cause: startup.cause
+					} : { state: "pending" } }
+				};
 				response.writeHead(startup.state === "ready" ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify(peerHealth));
 				return;
 			}
@@ -17600,6 +17659,7 @@ async function startServer(options) {
 		}
 		startupProbe = probeDirectories(directories, options.env, options.startupProbeMs ?? 1e4, configDir());
 		let reason = await startupProbe.result;
+		let cause = "home-unreadable";
 		startupProbe = null;
 		if (closing) return settle(startup);
 		if (reason === null) try {
@@ -17611,6 +17671,7 @@ async function startServer(options) {
 			becomeReady();
 		} catch (error) {
 			reason = error.message;
+			cause = "start-failed";
 		}
 		if (reason === null) {
 			if (startup.state === "degraded") console.error("stim-server: the Stim home answers again; serving clients.");
@@ -17635,7 +17696,8 @@ async function startServer(options) {
 		if (startup.state !== "degraded" || startup.reason !== reason) console.error(`stim-server: listening, but not serving clients until the Stim home answers. ${reason}`);
 		startup = {
 			state: "degraded",
-			reason
+			reason,
+			cause
 		};
 		settle(startup);
 		startupRetry = setTimeout(() => void checkHome(), options.startupRetryMs ?? 3e4);
@@ -17786,12 +17848,21 @@ async function serve(port, extraEnv, pathPrepend, loopbackOnly) {
 	const desktopInput = bootstrapFd === "0" ? await readDesktopBootstrap(process.stdin).catch(() => fail("Desktop bootstrap input is invalid or unavailable.")) : void 0;
 	delete process.env.NODE_COMPILE_CACHE;
 	const captureHost = hostFromExecutable(process.env.STIM_HOST_EXECUTABLE);
-	const env = applyServeEnvironment(discoverToolchain(process.env).env, extraEnv, pathPrepend);
-	delete env.CLAUDE_CODE_SESSION_ID;
-	delete env.CODEX_THREAD_ID;
+	const inherited = { ...process.env };
+	const serveEnvironment = (warn) => {
+		const found = applyServeEnvironment(discoverToolchain(inherited).env, extraEnv, pathPrepend, process.env, warn);
+		delete found.CLAUDE_CODE_SESSION_ID;
+		delete found.CODEX_THREAD_ID;
+		return found;
+	};
+	const env = serveEnvironment();
 	if (!process.env.STIM_HOME && env.STIM_HOME) process.env.STIM_HOME = env.STIM_HOME;
 	if (process.env.STIM_HOME) env.STIM_HOME = process.env.STIM_HOME;
 	Object.assign(process.env, env);
+	const currentEnv = () => ({
+		...serveEnvironment(() => {}),
+		...env.STIM_HOME ? { STIM_HOME: env.STIM_HOME } : {}
+	});
 	const loaded = await loadTransport({
 		reference: "@stim-cli/transport-tailscale",
 		load: () => import("@stim-cli/transport-tailscale"),
@@ -17818,6 +17889,7 @@ async function serve(port, extraEnv, pathPrepend, loopbackOnly) {
 			stimVersion: stim.version,
 			serverVersion: pkg.version,
 			env,
+			currentEnv,
 			transports: [transport],
 			service: {
 				label: serviceManagerOrNull()?.runningLabel(process.env) ?? null,

package/dist/stim-server.mjs

@@ -4,6 +4,6 @@ const encode = (version) => version.split(".", 3).reduce((sum, part) => sum * 1e
 if (encode(process.versions.node) < encode("22.12.0")) {
 	process.stderr.write(`STIM_NODE_UNSUPPORTED: stim-server needs Node 22.12.0 or later; this is Node ${process.versions.node} at ${process.execPath}. To run stim-server where a project pins an older Node, see https://stim.appandflow.com/docs/requirements#older-node-pins\n`);
 	process.exitCode = 1;
-} else import("./stim-server-DowAx-6v.mjs");
+} else import("./stim-server-DU1htjam.mjs");
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Serves Stim status to paired clients over Tailscale, and runs reload and stop for clients granted control.",
   "license": "MIT",
   "repository": {
@@ -28,13 +28,13 @@
     "./protocol.schema.json": "./dist/protocol.schema.json"
   },
   "dependencies": {
-    "@stim-cli/agent-driver": "1.25.0",
-    "@stim-cli/agent-driver-agent-device": "1.25.0",
-    "@stim-cli/cache": "1.25.0",
-    "@stim-cli/core": "1.25.0",
-    "@stim-cli/transport": "1.25.0",
-    "@stim-cli/transport-tailscale": "1.25.0",
-    "stim": "1.25.0",
+    "@stim-cli/agent-driver": "1.26.0",
+    "@stim-cli/agent-driver-agent-device": "1.26.0",
+    "@stim-cli/cache": "1.26.0",
+    "@stim-cli/core": "1.26.0",
+    "@stim-cli/transport": "1.26.0",
+    "@stim-cli/transport-tailscale": "1.26.0",
+    "stim": "1.26.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {