@stim-cli/server 1.17.2 → 1.19.0

package/README.md

@@ -112,8 +112,9 @@ GUI login session.
 
 Running setup on the worker is the worker-side approval. It pre-approves at
 most one request per chosen capability, from this node, carrying this ticket,
-until this expiry. A terminal asks y/N for each grant (default No); use `--yes`
-to approve without those questions, including without a terminal. Without
+until this expiry. A terminal asks Y/n for each grant (default Yes: Enter, `y` and `yes` approve;
+`n`, `no` and any other answer decline); use `--yes` to approve without those
+questions, including without a terminal. Without
 a terminal or `--yes`, setup refuses before installing anything unless every
 chosen capability already has a matching approval. A person on
 the worker still approves; an SSH-driven run is not offered. Build and
@@ -155,7 +156,7 @@ nothing. Android and CocoaPods checks are not needed for hosting alone.
 In a terminal, setup prints a banner, then one line per step with a green check,
 a yellow arrow while a step runs, or a red cross; `NO_COLOR`, `TERM=dumb` and a
 non-terminal give plain `[ok]`, `[failed]` and `[pending]` marks, no colors and no
-in-place line. The y/N questions stay, one line each. The run ends with a
+in-place line. The Y/n questions stay, one line each. The run ends with a
 headline such as "janics-mac-mini is ready to build for Janic's MacBook Pro", one
 line per approved capability, a `Fix` line for each skipped permission or missing
 tool, and one `To undo` line. `--verbose` prints every step with its detail, the
@@ -1162,7 +1163,11 @@ The server re-reads the build clients on every call, and revoking a client
 closes its connections and cancels its builds.
 
 - `build.offer` takes `repo` (the client's name for its repository: letters,
-  digits, `.`, `_` and `-`, at most 80) and an optional `lockfile` sha256. It
+  digits, `.`, `_` and `-`, at most 80), an optional `lockfile` sha256, and an
+  optional `rubyVersion` (the project's normalized `.ruby-version`, a nonempty
+  installation name without path separators, NUL or line breaks). The CocoaPods probe uses the
+  same Ruby selection and UTF-8 locale defaults as `pod install`; omitting
+  `rubyVersion` uses the worker's default Ruby. It
   returns `toolchain` (`stimBuild`, a digest of the bundled Stim's built code;
   `arch`; `xcode`; `simulatorSdk`; `macosSdk` (from
   `xcrun --sdk macosx --show-sdk-version`); `cocoapods`; `runtimes`, the simulator
@@ -1178,11 +1183,12 @@ closes its connections and cancels its builds.
   average per CPU), `builds` (this Mac's own Stim runs in prebuild, pods or
   compile that it did not offload, plus the offloaded builds it runs), `maxBuilds` (its
   `concurrency.maxBuilds`, 0 when unlimited), `maxLoadPerCore` (its
-  `server.maxLoadPerCore`, default 2), and `declined`: why it would refuse a
+  `server.maxLoadPerCore`, default 2), `memoryUsedBytes` (Activity Monitor's
+  Memory Used) and `memoryTotalBytes`, and `declined`: why it would refuse a
   build now, or null. It declines while it runs its limit of offloaded builds,
   while the worker root's volume has less than 10 GiB free, while `builds`
   reaches a non-zero `maxBuilds`, or while `loadPerCore` is at or above
-  `maxLoadPerCore`. The toolchain is read at most once a minute; capacity on
+  `maxLoadPerCore`. The toolchain is read at most once a minute per Ruby context; capacity on
   every offer.
 - `build.sync` takes `repo`, `files` and `done`. `files` is one page of the
   manifest, each `{ "path", "kind": "file"|"exec"|"link", "size", "sha256" }`,
@@ -1890,8 +1896,10 @@ after. With a `stim` whose status has no `activity.recent`, every app log
 record counts as activity, so an app that keeps logging never looks stuck or
 finished.
 
-Each workspace notifies once per episode: a stuck agent notifies again only
-after new activity and a new quiet stretch, a loop only after a success or a
+Each workspace notifies once per episode: an agent stop pushes `finished` once
+per run, which ends when the workspace goes idle, and a workspace pushes
+`attention` once per run, which starts over when the workspace stops being idle
+or has no item left; a stuck agent notifies again only after new activity and a new quiet stretch, a loop only after a success or a
 different failure. A push carries a collapse id for its workspace and
 category, so a later one replaces the earlier notification on the phone
 instead of stacking. What is already true when the server starts or a device

package/dist/{protocol-Btu-PwQS.mjs → protocol-qo5TTavl.mjs}

@@ -1,5 +1,5 @@
 import "node:module";
-import { ACTIONS, BUILD_REPO_PATTERN, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FEATURES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, INPUT_KEYS, KEY_MODIFIERS, LEGACY_PUSH_EVENTS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, NOTIFICATION_LEVELS, NOTIFICATION_SUPPRESSIONS, PLATFORMS, PROTOCOL_VERSION, PUSH_EVENTS, PUSH_TOKEN_PATTERN, RELOAD_PLATFORMS, REPLAY_MARKER_KINDS, REPLAY_RATES, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS } from "@stim-cli/core/protocol";
+import { ACTIONS, BUILD_REPO_PATTERN, BUILD_RUBY_VERSION_PATTERN, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FEATURES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, INPUT_KEYS, KEY_MODIFIERS, LEGACY_PUSH_EVENTS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, NOTIFICATION_LEVELS, NOTIFICATION_SUPPRESSIONS, PLATFORMS, PROTOCOL_VERSION, PUSH_EVENTS, PUSH_TOKEN_PATTERN, RELOAD_PLATFORMS, REPLAY_MARKER_KINDS, REPLAY_RATES, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS } from "@stim-cli/core/protocol";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -785,7 +785,11 @@ function protocolJsonSchema() {
 						required: ["name", "version"],
 						properties: {
 							name: { type: "string" },
-							version: { type: "string" }
+							version: { type: "string" },
+							runId: {
+								type: "string",
+								pattern: "^[A-Za-z0-9._-]{1,64}$"
+							}
 						}
 					},
 					auth: { oneOf: [
@@ -2209,7 +2213,11 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: {
 						repo: buildRepo,
-						lockfile: sha256
+						lockfile: sha256,
+						rubyVersion: {
+							type: "string",
+							pattern: BUILD_RUBY_VERSION_PATTERN
+						}
 					}
 				}),
 				request("build.sync", {

package/dist/protocol.mjs

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

package/dist/protocol.schema.json

@@ -1145,6 +1145,10 @@
             },
             "version": {
               "type": "string"
+            },
+            "runId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9._-]{1,64}$"
             }
           }
         },
@@ -1420,7 +1424,8 @@
               "device",
               "build",
               "agent",
-              "maintenance"
+              "maintenance",
+              "placement"
             ]
           }
         },
@@ -5215,6 +5220,10 @@
                 "lockfile": {
                   "type": "string",
                   "pattern": "^[0-9a-f]{64}$"
+                },
+                "rubyVersion": {
+                  "type": "string",
+                  "pattern": "^(?!\\.{1,2}$)[^/\\\\\\u0000\\r\\n]+$"
                 }
               }
             }

package/dist/stim-frames/SimulatorDisplay.swift

@@ -66,7 +66,10 @@ public enum CoreSimulator {
   }
 
   static func simulatorKitPath(_ developerDir: String) -> String {
-    "\(developerDir)/../SharedFrameworks/SimulatorKit.framework/SimulatorKit"
+    let shared = "\(developerDir)/../SharedFrameworks/SimulatorKit.framework/SimulatorKit"
+    let legacy = "\(developerDir)/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit"
+    return FileManager.default.fileExists(atPath: shared) || !FileManager.default.fileExists(atPath: legacy)
+      ? shared : legacy
   }
 
   static let deviceSet: NSObject? = {

package/dist/{stim-server-CJIlV28Y.mjs → stim-server-DThEHaj6.mjs}

@@ -1,8 +1,8 @@
-import { n as protocol_exports } from "./protocol-Btu-PwQS.mjs";
+import { n as protocol_exports } from "./protocol-qo5TTavl.mjs";
 import { createRequire } from "node:module";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { HOSTED_APP_CHUNK_BYTES, HOSTED_MACOS_APP_SLOTS, RECORDING_CAP_BYTES, RECORDING_FOOTAGE_MS, RECORDING_PLATFORMS, archiveDir, assertHostedDeviceLedger, buildWorkerRoot, capDrops, closedSegmentName, compileGrep, createAgentActionReader, deviceHostArea, deviceHostRoot, deviceViewersDir, footageDrops, getConcurrencyLimits, getParkedMax, hostedAndroidPlacements, hostedAppArea, hostedAppAttempt, hostedAppBlobs, hostedDeviceId, hostedIosPlacements, hostedMacosBundleId, hostedMacosLogsDir, hostedNativeLogsDir, isJournalExpired, isJsonObject, isSetupJournalPrunable, listRecordedDevices, listSegments, loadConfig, machineCapacity, macosAppState, openSegmentName, parseHostedAppOffer, parseHostedLocalDeviceCount, parseHostedLogsCursor, parseHostedNativeOffer, parseHostedOfferRequest, parseHostedPlatformDevice, parseHostedRequest, parseNdjsonLine, pinnedEndpoint, queryJsonLogs, readArchive, readArchiveState, readBuildHistory, readBuildMachines, readDeviceHostMachines, readHostedApp, readHostedAppMetadata, readHostedDevice, readHostedDeviceLedger, readHostedMacosApp, readHostedNativeLogsCheckpoint, readHostedSessions, readJsonObject, readLogTimeline, readLogsSince, readMacosRecord, readSetupJournal, readWorkspaceState, recordingDeviceName, rememberHostedAppBlobRename, saturation, serverSetupDir, settingDefinition, settingValueError, setupJournalFile, sortByTs, stimBuildDigest, tryAcquireBuildSlotClaim, validHostedAppBlob, workspaceRecordingsDir } from "@stim-cli/core/state";
+import { HOSTED_APP_CHUNK_BYTES, HOSTED_MACOS_APP_SLOTS, RECORDING_CAP_BYTES, RECORDING_FOOTAGE_MS, RECORDING_PLATFORMS, archiveDir, assertHostedDeviceLedger, buildWorkerRoot, capDrops, closedSegmentName, compileGrep, createAgentActionReader, createDebugLog, deviceHostArea, deviceHostRoot, deviceViewersDir, footageDrops, getConcurrencyLimits, getParkedMax, hostedAndroidPlacements, hostedAppArea, hostedAppAttempt, hostedAppBlobs, hostedDeviceId, hostedIosPlacements, hostedMacosBundleId, hostedMacosLogsDir, hostedNativeLogsDir, isJournalExpired, isJsonObject, isSetupJournalPrunable, listRecordedDevices, listSegments, loadConfig, machineCapacity, macosAppState, openSegmentName, parseHostedAppOffer, parseHostedLocalDeviceCount, parseHostedLogsCursor, parseHostedNativeOffer, parseHostedOfferRequest, parseHostedPlatformDevice, parseHostedRequest, parseNdjsonLine, pinnedEndpoint, queryJsonLogs, readArchive, readArchiveState, readBuildHistory, readBuildMachines, readDeviceHostMachines, readHostedApp, readHostedAppMetadata, readHostedDevice, readHostedDeviceLedger, readHostedMacosApp, readHostedNativeLogsCheckpoint, readHostedSessions, readJsonObject, readLogTimeline, readLogsSince, readMacosRecord, readSetupJournal, readWorkspaceState, recordingDeviceName, rememberHostedAppBlobRename, saturation, serverSetupDir, settingDefinition, settingValueError, setupJournalFile, sortByTs, stimBuildDigest, tryAcquireBuildSlotClaim, validHostedAppBlob, validRunId, workspaceRecordingsDir } from "@stim-cli/core/state";
 import { accessSync, 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";
 import { availableParallelism, cpus, freemem, homedir, hostname, loadavg, tmpdir, totalmem } from "node:os";
 import { parseArgs } from "node:util";
@@ -1186,30 +1186,6 @@ function readTailscaleStatus(binary, env, timeoutMs = TIMEOUT_MS$1) {
 		});
 	});
 }
-function tailscaleStatus(binary, env) {
-	if (!binary) return {
-		state: "unavailable",
-		reason: "the tailscale command was not found"
-	};
-	try {
-		const output = execFileSync(binary, ["status", "--json"], {
-			env,
-			timeout: TIMEOUT_MS$1,
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		});
-		return parseTailscaleStatus(JSON.parse(output));
-	} catch (error) {
-		return {
-			state: "unavailable",
-			reason: `\`tailscale status --json\` failed: ${error.message}`
-		};
-	}
-}
 function reaches(address, target, hosts) {
 	if (typeof address !== "string") return null;
 	let url;
@@ -1556,7 +1532,7 @@ async function waitForHealth(port, label) {
 }
 async function prepareRoute(port, previous) {
 	const binary = findTailscale(process.env);
-	const status = tailscaleStatus(binary, process.env);
+	const status = await readTailscaleStatus(binary, process.env);
 	if (!binary || status.state !== "running") throw new ServiceError("--serve needs Tailscale running on this Mac, and the tailscale command on PATH.");
 	const plan = planServe(await serveRoute(binary, process.env, port, status.ips), port, previous?.serve ?? null);
 	if ("refusal" in plan) throw new ServiceError(plan.refusal);
@@ -1834,7 +1810,7 @@ async function uninstallJob(label) {
 	let routeOff = null;
 	const tailscale = findTailscale(process.env);
 	if (installed.serve?.created && installed.port !== null) {
-		const status = tailscaleStatus(tailscale, process.env);
+		const status = await readTailscaleStatus(tailscale, process.env);
 		if (!tailscale || status.state !== "running") throw new ServiceError(`${label} created the tailscale serve route on https port ${installed.serve.port}, and Tailscale is not answering, so uninstall cannot check it. Start Tailscale and run this again.`);
 		const route = await serveRoute(tailscale, process.env, installed.port, status.ips);
 		if (route.state === "routed" && route.port === installed.serve.port) routeOff = installed.serve.port;
@@ -2619,8 +2595,7 @@ var BuildHost = class {
 	retained = /* @__PURE__ */ new Map();
 	closed = false;
 	draining = null;
-	toolchainAt = 0;
-	toolchainValue = null;
+	toolchains = /* @__PURE__ */ new Map();
 	options;
 	sweeping = Promise.resolve();
 	queued = null;
@@ -2674,11 +2649,17 @@ var BuildHost = class {
 	clientDir(client) {
 		return join(this.root(), client);
 	}
-	toolchain() {
-		if (this.toolchainValue && Date.now() - this.toolchainAt < this.limits.toolchainTtlMs) return this.toolchainValue;
-		this.toolchainAt = Date.now();
-		this.toolchainValue = new Promise((resolve) => {
-			const child = spawn(process.execPath, [this.options.worker, "offer"], {
+	toolchain(rubyVersion = null) {
+		const now = Date.now();
+		for (const [context, entry] of this.toolchains) if (now - entry.at >= this.limits.toolchainTtlMs) this.toolchains.delete(context);
+		const cached = this.toolchains.get(rubyVersion);
+		if (cached) return cached.value;
+		const value = new Promise((resolve) => {
+			const child = spawn(process.execPath, [
+				this.options.worker,
+				"offer",
+				...rubyVersion ? [rubyVersion] : []
+			], {
 				env: this.options.env,
 				stdio: [
 					"ignore",
@@ -2694,21 +2675,26 @@ var BuildHost = class {
 			child.on("close", () => {
 				clearTimeout(timer);
 				try {
-					const value = JSON.parse(out);
-					resolve(isJsonObject(value) ? value : null);
+					const report = JSON.parse(out);
+					resolve(isJsonObject(report) ? report : null);
 				} catch {
 					resolve(null);
 				}
 			});
 		});
-		this.toolchainValue.then((value) => {
-			if (!value) this.toolchainValue = null;
+		this.toolchains.set(rubyVersion, {
+			at: now,
+			value
 		});
-		return this.toolchainValue;
+		value.then((result) => {
+			if (!result && this.toolchains.get(rubyVersion)?.value === value) this.toolchains.delete(rubyVersion);
+		});
+		return value;
 	}
 	async offer(client, params) {
 		if (!isJsonObject(params) || !validRepo(params.repo)) return refusal("bad-request", "build.offer needs params.repo.");
-		const toolchain = await this.toolchain();
+		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.");
+		const toolchain = await this.toolchain(params.rubyVersion ?? null);
 		if (!toolchain) return refusal("build-refused", "This Mac could not read its build toolchain.");
 		const root = this.root();
 		mkdirSync(root, {
@@ -2720,9 +2706,18 @@ var BuildHost = class {
 		try {
 			lockfile = readFileSync(join(area, "lockfile"), "utf8");
 		} catch {}
+		const available = await readAvailableMemory();
+		const total = totalmem();
+		const memory = available === null ? {} : {
+			memoryTotalBytes: total,
+			memoryUsedBytes: total - available
+		};
 		return { result: {
 			toolchain,
-			capacity: this.capacity(),
+			capacity: {
+				...this.capacity(),
+				...memory
+			},
 			warm: {
 				checkout: existsSync(join(area, "src")),
 				dependencies: typeof params.lockfile === "string" && lockfile === params.lockfile,
@@ -3599,7 +3594,7 @@ async function confirmSetup(input, question, timeoutMs) {
 	input.on("SIGINT", interrupt);
 	input.on("close", interrupt);
 	try {
-		return /^(y|yes)$/i.test((await input.question(question, { signal: controller.signal })).trim());
+		return /^(|y|yes)$/i.test((await input.question(question, { signal: controller.signal })).trim());
 	} catch (error) {
 		if (controller.signal.reason instanceof SetupRefusal) throw controller.signal.reason;
 		if (error.name === "AbortError") return false;
@@ -3611,6 +3606,15 @@ async function confirmSetup(input, question, timeoutMs) {
 		input.close();
 	}
 }
+const discardInput = () => void 0;
+async function discardTypedAhead(stream) {
+	if (!stream.isTTY) return;
+	stream.on("data", discardInput);
+	stream.resume();
+	await sleep(300);
+	stream.off("data", discardInput);
+	stream.pause();
+}
 function defaultSetupDeps() {
 	return {
 		now: Date.now,
@@ -3619,10 +3623,13 @@ function defaultSetupDeps() {
 		display: setupDisplayFor(process.stdout.isTTY === true, process.env, (text) => void process.stdout.write(text)),
 		stdout: (line) => console.log(line),
 		stderr: (line) => console.error(line),
-		confirm: (question, timeoutMs) => confirmSetup(createInterface({
-			input: process.stdin,
-			output: process.stderr
-		}), question, timeoutMs),
+		confirm: async (question, timeoutMs) => {
+			await discardTypedAhead(process.stdin);
+			return confirmSetup(createInterface({
+				input: process.stdin,
+				output: process.stderr
+			}), question, timeoutMs);
+		},
 		permissionWait(ms) {
 			if (!process.stdin.isTTY) return sleep(ms).then(() => false);
 			return new Promise((resolve, reject) => {
@@ -3798,9 +3805,9 @@ const capabilityNoun = (capability) => capability === "build" ? "builds" : "host
 function approvalQuestion(concise, name, capability, nodeId) {
 	if (!concise) {
 		const verb = capability === "build" ? "build on this Mac" : "host simulators on this Mac";
-		return `${name} (node ${nodeId.slice(0, 4)}...) asks to ${verb}. Approve? [y/N] `;
+		return `${name} (node ${nodeId.slice(0, 4)}...) asks to ${verb}. Approve? [Y/n] `;
 	}
-	return `Approve ${name} to ${capability === "build" ? "build here (runs its project code" : "host simulators here (runs its app code"} on this Mac)? [y/N] `;
+	return `Approve ${name} to ${capability === "build" ? "build here (runs its project code" : "host simulators here (runs its app code"} on this Mac)? [Y/n] `;
 }
 function serverText(desktop, decision, version) {
 	if (desktop) return `using the app's stim-server ${version}`;
@@ -4180,6 +4187,93 @@ async function runSetup(args, version, deps) {
 	return journal.exit;
 }
 //#endregion
+//#region src/request-log.ts
+const SLOW_MS = 1e3;
+const METHOD = /^[a-z][a-z0-9.-]{0,47}$/;
+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(" ");
+/**
+* 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
+* `logs/debug/server.ndjson` with its duration and the slow steps. Lines carry the method, the client's device id,
+* the CLI run id, durations and the error code: never params, messages, tokens or tickets.
+*/
+function createRequestLog({ service = (line) => console.error(line), debug = createDebugLog("server"), now = Date.now } = {}) {
+	const lastError = /* @__PURE__ */ new Map();
+	const errorDue = (key) => {
+		const at = now();
+		const last = lastError.get(key);
+		if (last !== void 0 && at - last < ERROR_REPEAT_MS) return false;
+		lastError.delete(key);
+		lastError.set(key, at);
+		if (lastError.size > MAX_REMEMBERED) lastError.delete(lastError.keys().next().value);
+		return true;
+	};
+	return {
+		track() {
+			let client = {
+				id: null,
+				runId: null
+			};
+			const inflight = /* @__PURE__ */ new Map();
+			return {
+				identify(next) {
+					client = next;
+				},
+				begin(id, method) {
+					if (id === null) return;
+					if (inflight.size >= MAX_REMEMBERED) inflight.delete(inflight.keys().next().value);
+					inflight.set(id, {
+						method: METHOD.test(method) ? method : "unknown",
+						start: now(),
+						steps: {}
+					});
+				},
+				step(id, name, ms) {
+					const entry = inflight.get(id);
+					if (entry) entry.steps[name] = Math.round(ms);
+				},
+				reply(message) {
+					if (!message || typeof message !== "object" || !("id" in message)) return;
+					const { id, error } = message;
+					const entry = inflight.get(id);
+					if (entry) inflight.delete(id);
+					if (!entry && !error) return;
+					const code = error ? String(error.code ?? "error").slice(0, 64) : void 0;
+					const method = entry?.method ?? "unknown";
+					const ms = entry ? now() - entry.start : void 0;
+					const fields = {
+						method,
+						client: client.id ?? void 0,
+						run: client.runId ?? void 0,
+						ms,
+						...ms !== void 0 && ms >= SLOW_MS ? { slow: true } : {},
+						...entry?.steps,
+						error: code
+					};
+					if (debug.enabled()) {
+						service(`stim-server: debug request ${text(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)}`);
+				}
+			};
+		},
+		host(event, fields, failed = false) {
+			if (debug.enabled()) {
+				service(`stim-server: debug ${event} ${text(fields)}`);
+				debug.log(event, fields);
+			} else if (failed && errorDue(`host|${event}|${String(fields.host)}`)) service(`stim-server: ${event} ${text(fields)}`);
+		}
+	};
+}
+//#endregion
 //#region src/agent-driver.ts
 /** The driver cannot run or cannot scope an app; the message is safe to show a client. */
 var AgentDriverUnavailable = class extends Error {};
@@ -6441,9 +6535,11 @@ var DeviceHost = class {
 	reconciling;
 	draining = null;
 	limits;
+	debug;
 	options;
 	constructor(options) {
 		this.options = options;
+		this.debug = createDebugLog("server", { env: options.env });
 		this.limits = {
 			prepareMs: 3e5,
 			offerMs: 3e4,
@@ -7593,6 +7689,15 @@ var DeviceHost = class {
 			if (options.claim) clearClaimChild(options.claim);
 			throw error;
 		}
+		const started = performance.now();
+		const mode = "mode" in options.input && typeof options.input.mode === "string" ? options.input.mode : void 0;
+		const diagnostic = (event, fields = {}) => this.debug.log(`device-host.worker.${event}`, {
+			mode,
+			workerPid: child.pid,
+			ms: Math.round(performance.now() - started),
+			...fields
+		});
+		diagnostic("start", { timeoutMs: options.timeoutMs });
 		let identity = null;
 		const output = [];
 		let outputBytes = 0;
@@ -7615,7 +7720,14 @@ var DeviceHost = class {
 			clearTimeout(killTimer);
 			clearTimeout(finishTimer);
 			clearTimeout(groupTimer);
-			const settled = closed && (!child.pid || !processGroupAlive(child.pid));
+			const groupAlive = closed && child.pid ? processGroupAlive(child.pid) : null;
+			const settled = closed && groupAlive !== true;
+			diagnostic("settled", {
+				closed,
+				groupAlive,
+				settled,
+				cancelling
+			});
 			if (settled && options.claim) clearClaimChild(options.claim);
 			let value = null;
 			try {
@@ -7643,9 +7755,10 @@ var DeviceHost = class {
 				process.kill(-child.pid, name);
 			} catch {}
 		};
-		const cancel = () => {
+		const cancel = (reason = "requested") => {
 			if (finished || cancelling) return;
 			cancelling = true;
+			diagnostic("cancel", { reason });
 			notice ??= "Hosted worker was cancelled or exceeded its deadline.";
 			signal("SIGTERM");
 			killTimer = setTimeout(() => signal("SIGKILL"), this.limits.killGraceMs);
@@ -7655,15 +7768,15 @@ var DeviceHost = class {
 			if (finished) return;
 			if (!child.pid || !processGroupAlive(child.pid)) finish();
 			else {
-				cancel();
+				cancel("group-after-close");
 				groupTimer = setTimeout(finishGroup, 25);
 			}
 		};
-		const timer = setTimeout(cancel, options.timeoutMs);
+		const timer = setTimeout(() => cancel("deadline"), options.timeoutMs);
 		child.stdout?.on("data", (chunk) => {
 			if (outputBytes + chunk.length > options.maxOutputBytes) {
 				notice = "Hosted worker output exceeded its bound.";
-				cancel();
+				cancel("output-bound");
 			} else {
 				output.push(chunk);
 				outputBytes += chunk.length;
@@ -7672,13 +7785,18 @@ var DeviceHost = class {
 		child.stderr?.on("data", (chunk) => {
 			stderr = (stderr + chunk.toString()).slice(-8192);
 		});
-		child.stdin?.on("error", () => cancel());
+		child.stdin?.on("error", () => cancel("stdin-error"));
 		child.once("error", (error) => {
+			diagnostic("error", { code: error.code });
 			notice = error.message;
 			closed = true;
 			finishGroup();
 		});
-		child.once("close", (code) => {
+		child.once("close", (code, closeSignal) => {
+			diagnostic("close", {
+				code,
+				signal: closeSignal
+			});
 			if (code !== 0) notice ??= stderr.trim() || `Hosted worker exited ${code}.`;
 			closed = true;
 			finishGroup();
@@ -7687,7 +7805,7 @@ var DeviceHost = class {
 		if (!captured?.ok || child.pid === void 0) {
 			notice = "The worker process identity could not be captured; no native request was sent.";
 			child.kill("SIGKILL");
-			cancel();
+			cancel("identity-unavailable");
 		} else {
 			identity = {
 				pid: child.pid,
@@ -7698,7 +7816,7 @@ var DeviceHost = class {
 				child.stdin?.end(JSON.stringify(options.input));
 			} catch (error) {
 				notice = error.message;
-				cancel();
+				cancel("request-write");
 			}
 		}
 		return {
@@ -8835,6 +8953,7 @@ var LatestFrames = class {
 //#endregion
 //#region src/hosted-relay.ts
 const TIMEOUT_MS = 1e4;
+const REQUEST_TIMEOUT_MS = 2e4;
 const KEYFRAME_RETRY_MS = 1e3;
 const CONGESTION_NOTICE_MS = 250;
 function routeOf(message) {
@@ -8857,6 +8976,8 @@ var Upstream = class {
 	users = 0;
 	features = [];
 	onClose = null;
+	connectMs = 0;
+	helloMs = 0;
 	token;
 	constructor(endpoint, token) {
 		this.token = token;
@@ -8923,6 +9044,7 @@ var Upstream = class {
 	}
 	/** Connects and says hello with the token; the host must grant `capability` to this Mac. */
 	async open(version, capability = "device-host") {
+		const started = Date.now();
 		await new Promise((resolve, reject) => {
 			const done = (error) => {
 				clearTimeout(timer);
@@ -8943,6 +9065,7 @@ var Upstream = class {
 			this.socket.once("close", closed);
 			this.socket.once("error", failed);
 		});
+		this.connectMs = Date.now() - started;
 		const reply = await this.request("hello", {
 			protocol: 1,
 			client: {
@@ -8951,6 +9074,7 @@ var Upstream = class {
 			},
 			auth: { deviceToken: this.token }
 		});
+		this.helloMs = Date.now() - started - this.connectMs;
 		if ("error" in reply) throw new Error(reply.error.message);
 		if (!isJsonObject(reply.result) || !Array.isArray(reply.result.capabilities) || !reply.result.capabilities.includes(capability)) throw new Error(`the host did not grant ${capability} access`);
 		if (Array.isArray(reply.result.features)) this.features = reply.result.features.filter((feature) => typeof feature === "string");
@@ -8959,7 +9083,7 @@ var Upstream = class {
 		if (this.ended) return Promise.reject(this.ended);
 		return new Promise((resolve, reject) => {
 			const id = this.nextId++;
-			const timer = setTimeout(() => this.fail(`the host did not answer ${method} in time`), TIMEOUT_MS);
+			const timer = setTimeout(() => this.fail(`the host was busy or slow: it did not answer ${method} within ${REQUEST_TIMEOUT_MS / 1e3} seconds`), REQUEST_TIMEOUT_MS);
 			this.pending.set(id, {
 				resolve: (reply) => {
 					clearTimeout(timer);
@@ -9032,6 +9156,7 @@ var HostConnections = class {
 	/** Checks the credential and pinned node on every call, then joins or opens the connection to that endpoint. */
 	async acquire(host) {
 		let token = "";
+		const started = Date.now();
 		try {
 			const credential = readDeviceHostMachines().find((entry) => entry.machine === host.machine);
 			if (!credential || credential.state !== "approved") throw new Error("no approved device-host credential");
@@ -9047,6 +9172,7 @@ var HostConnections = class {
 				endpoint.host
 			]);
 			let entry = this.open.get(key);
+			const created = !entry;
 			if (!entry) {
 				const connection = new Upstream(endpoint, token);
 				const opened = {
@@ -9067,10 +9193,24 @@ var HostConnections = class {
 				lease.release();
 				throw cause;
 			}
+			this.options.log?.("host_connect", {
+				host: host.machine,
+				ms: Date.now() - started,
+				...created ? {
+					connectMs: entry.connection.connectMs,
+					helloMs: entry.connection.helloMs
+				} : { reused: true }
+			});
 			return lease;
 		} catch (cause) {
 			const reason = cause.message;
-			throw new Error(token ? reason.replaceAll(token, "[redacted]") : reason, { cause });
+			const safe = token ? reason.replaceAll(token, "[redacted]") : reason;
+			this.options.log?.("host_connect", {
+				host: host.machine,
+				ms: Date.now() - started,
+				error: safe.slice(0, 200)
+			}, true);
+			throw new Error(safe, { cause });
 		}
 	}
 	close() {
@@ -13064,7 +13204,9 @@ function take(bucket, cost, perSecond, capacity) {
 	bucket.tokens -= cost;
 	return true;
 }
+const trackers = /* @__PURE__ */ new WeakMap();
 function send(socket, message) {
+	if (typeof message !== "string") trackers.get(socket)?.reply(message);
 	if (socket.readyState === socket.OPEN) socket.send(typeof message === "string" ? message : JSON.stringify(message));
 }
 function buildAllowed(session) {
@@ -13166,6 +13308,7 @@ async function startServer(options) {
 		}
 		return hostProbe;
 	};
+	const requestLog = options.requestLog ?? createRequestLog();
 	const limiter = new FailureLimiter(options.maxAuthFailures ?? 5, options.failureWindowMs ?? 6e4);
 	const authTimeoutMs = options.authTimeoutMs ?? 5e3;
 	const feeds = new FeedPool(options.stimCli, options.env);
@@ -13480,7 +13623,10 @@ async function startServer(options) {
 		limits: options.pushLimits
 	});
 	const relays = /* @__PURE__ */ new Map();
-	const hostConnections = new HostConnections(options.hostedRelay ?? { status: () => readRawTailscaleStatus(tailscaleNow().binary, options.env) }, options.serverVersion);
+	const hostConnections = new HostConnections({
+		...options.hostedRelay ?? { status: () => readRawTailscaleStatus(tailscaleNow().binary, options.env) },
+		log: requestLog.host
+	}, options.serverVersion);
 	let revocationCheck = null;
 	let checkedRegistry = null;
 	const checkRevocations = () => {
@@ -13544,6 +13690,9 @@ async function startServer(options) {
 		const commands = /* @__PURE__ */ new Set();
 		let nextSubscription = 1;
 		let device = null;
+		const tracker = requestLog.track();
+		trackers.set(socket, tracker);
+		let runId = null;
 		let buildSession = null;
 		let queue = Promise.resolve();
 		let archiveReads = Promise.resolve();
@@ -13584,7 +13733,15 @@ async function startServer(options) {
 			if (!isJsonObject(params) || !auth || !isJsonObject(params.client)) return refuse(id, "bad-request", "hello needs params.client and params.auth.", CLOSE_BAD_REQUEST);
 			if (params.protocol !== protocol_exports.PROTOCOL_VERSION) return refuse(id, "protocol-unsupported", `This server speaks protocol ${protocol_exports.PROTOCOL_VERSION}.`, CLOSE_BAD_REQUEST);
 			clearTimeout(timer);
+			runId = validRunId(params.client.runId);
+			tracker.identify({
+				id: null,
+				runId
+			});
+			const probing = hostHealth();
+			const whoisStarted = Date.now();
 			const identity = await identify();
+			tracker.step(id, "whois", Date.now() - whoisStarted);
 			if (socket.readyState !== socket.OPEN) return;
 			if (!identity) return refuse(id, "identity-unavailable", `tailscale whois did not identify ${peer}.`, CLOSE_UNAUTHORIZED);
 			let outcome;
@@ -13638,8 +13795,15 @@ async function startServer(options) {
 				return;
 			}
 			device = outcome.device;
+			tracker.identify({
+				id: device.id,
+				runId
+			});
 			sessions.set(socket, device);
 			sampler.start();
+			const probeWaited = Date.now();
+			const host = options.host ? await probing : void 0;
+			if (options.host) tracker.step(id, "probe", Date.now() - probeWaited);
 			send(socket, {
 				id,
 				result: {
@@ -13650,7 +13814,7 @@ async function startServer(options) {
 						stim: options.stimVersion,
 						home: homedir()
 					},
-					...options.host ? { host: await hostHealth() } : {},
+					...options.host ? { host } : {},
 					capabilities: device.capabilities,
 					features: [...protocol_exports.FEATURES],
 					actions: device.capabilities.includes("control") ? [...protocol_exports.ACTIONS] : [],
@@ -14798,6 +14962,7 @@ async function startServer(options) {
 				});
 				return refuse(id, "bad-request", "Expected {id, method, params}.", CLOSE_BAD_REQUEST);
 			}
+			tracker.begin(id, message.method);
 			if (message.method === "hello") return hello(id, message.params);
 			if (!device) return refuse(id, "unauthorized", "Send hello first.", CLOSE_UNAUTHORIZED);
 			if (protocol_exports.DEVICE_HOST_METHODS.includes(message.method)) {
@@ -15374,7 +15539,7 @@ async function serve(port, extraEnv, pathPrepend, loopbackOnly) {
 	if (process.env.STIM_HOME) env.STIM_HOME = process.env.STIM_HOME;
 	const launchdLabel = process.env.XPC_SERVICE_NAME;
 	const tailscaleBinary = findTailscale(env);
-	const tailscale = tailscaleStatus(tailscaleBinary, env);
+	const tailscale = await readTailscaleStatus(tailscaleBinary, env);
 	const stim = bundledStim();
 	const monitor = watchTailscale({
 		env,
@@ -15450,7 +15615,7 @@ const SCOPE_TEXT = {
 };
 async function pair(port, json, control) {
 	const binary = findTailscale(process.env);
-	const tailscale = tailscaleStatus(binary, process.env);
+	const tailscale = await readTailscaleStatus(binary, process.env);
 	let endpoint = `ws://127.0.0.1:${port}`;
 	let note = tailscaleNote(tailscale);
 	if (note) note = `${note} The endpoint above only works on this Mac.`;

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-CJIlV28Y.mjs");
+} else import("./stim-server-DThEHaj6.mjs");
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.17.2",
+  "version": "1.19.0",
   "description": "Serves Stim status to paired clients over Tailscale, and runs reload and stop for clients granted control.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
     "./protocol.schema.json": "./dist/protocol.schema.json"
   },
   "dependencies": {
-    "@stim-cli/core": "^1.17.2",
-    "stim": "1.17.2",
+    "@stim-cli/core": "^1.19.0",
+    "stim": "1.19.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {